修复一些的过时测试 优化readme
This commit is contained in:
yml
@@ -1,156 +1,252 @@
|
||||
# order-site-workspace
|
||||
# order_site
|
||||
|
||||
统一工作区版本的订单自动兑换系统。
|
||||
订单自动兑换与履约管理系统。
|
||||
|
||||
项目采用前后端分离架构，主要用于接收订单、匹配履约规则、生成领取链接、管理库存、执行自动/半自动兑换，并提供后台页面处理人工复核、平台配置和任务追踪。
|
||||
|
||||
## 技术栈
|
||||
|
||||
- 前端：Vue 3、Vite、Element Plus、TypeScript
|
||||
- 后端：Node.js、Express、PostgreSQL、Playwright
|
||||
- OCR：独立 Python worker
|
||||
- 网关：Caddy
|
||||
- 本地与生产运行：Docker Compose
|
||||
|
||||
## 目录结构
|
||||
|
||||
```text
|
||||
apps/
|
||||
backend/ Node + Express + Playwright + OCR worker
|
||||
frontend/ Vue 3 + Vite + Element Plus
|
||||
backend/ 后端 API、任务编排、平台对接、数据库迁移
|
||||
src/
|
||||
data/ 本地开发运行数据和平台配置
|
||||
subservices/ocr-worker/ OCR 子服务源码
|
||||
frontend/ 前端后台、领取页和配置页面
|
||||
deploy/
|
||||
caddy/ Caddy 配置
|
||||
docker/ Dockerfile
|
||||
docs/ 迁移与部署文档
|
||||
docker-compose.yml
|
||||
caddy/ Caddy 反向代理配置
|
||||
docker/ 前后端与 OCR 镜像 Dockerfile
|
||||
docs/ 平台接口、迁移设计和部署资料
|
||||
docker-compose.dev.yml 本地 Docker 开发环境
|
||||
docker-compose.yml 生产/服务器 Compose
|
||||
```
|
||||
|
||||
## 本地开发
|
||||
|
||||
前端：
|
||||
|
||||
```bash
|
||||
cd apps/frontend
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
后端：
|
||||
|
||||
```bash
|
||||
cp .env.mac-docker.example .env
|
||||
cd apps/backend/subservices/ocr-worker
|
||||
uv sync
|
||||
cd apps/backend
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
## Docker 部署
|
||||
|
||||
```bash
|
||||
cp .env.server.example .env
|
||||
mkdir -p deploy/data/backend
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
生产版 Compose 现在会把后端运行数据直接挂载到宿主机目录：
|
||||
|
||||
- `deploy/data/backend`
|
||||
|
||||
这样服务器上可以直接查看和备份：
|
||||
|
||||
- `logs/`
|
||||
- `browser-sessions/`
|
||||
- `redeem-screenshots/`
|
||||
- `agiso-shops.json`
|
||||
- `order-fulfillment-bindings.json`
|
||||
|
||||
如果你本地已经配好了店铺和履约绑定，首次上线前可以把这两份文件先放进去：
|
||||
|
||||
- `deploy/data/backend/agiso-shops.json`
|
||||
- `deploy/data/backend/order-fulfillment-bindings.json`
|
||||
|
||||
后端启动时会自动执行数据库 migration、初始化默认管理员、同步履约目录；但 `/app/data` 下的业务配置文件仍以宿主机目录内容为准。
|
||||
|
||||
## Docker 本地开发
|
||||
推荐直接使用 Docker，本地不需要额外维护 Node、PostgreSQL、Playwright 浏览器和 OCR 运行环境。
|
||||
|
||||
```bash
|
||||
cp .env.mac-docker.example .env
|
||||
docker compose -f docker-compose.dev.yml up -d --build
|
||||
```
|
||||
|
||||
开发环境现在不再把 Caddy 绑定到固定域名。
|
||||
这意味着：
|
||||
启动后常用入口：
|
||||
|
||||
- 本地直接访问 `http://localhost` 可用
|
||||
- 用 ngrok / cloudflared 转发到 `http://localhost:80` 时，不需要因为随机子域名变化而改 Caddy 配置
|
||||
- 如果要生成发给用户的公网领取链接，只需要更新 `.env` 里的 `APP_BASE_URL`
|
||||
- 前端、后台、领取页：`http://localhost`
|
||||
- 后端健康检查：`http://localhost/health`
|
||||
- 后端 API 前缀：`http://localhost/api/v1/...`
|
||||
- OCR worker：`http://127.0.0.1:8100/health`
|
||||
- noVNC 浏览器画面：`http://127.0.0.1:6080/vnc.html`
|
||||
|
||||
开发版 Compose 现在是热更新模式：
|
||||
|
||||
- `postgres` 容器提供 PostgreSQL
|
||||
- 后端源码挂载到容器里，运行 `npm run dev`
|
||||
- 前端源码挂载到容器里，运行 `vite`
|
||||
- Caddy 只负责把 `80/443` 反代到前后端容器
|
||||
|
||||
通常只有首次启动、改 Dockerfile、改系统依赖时才需要 `--build`。
|
||||
|
||||
开发版 Compose 会把后端运行产物目录直接挂载到：
|
||||
|
||||
- [apps/backend/data](/Users/yml/codes/order-site-workspace/apps/backend/data)
|
||||
|
||||
这样本地可以直接看到：
|
||||
|
||||
- `data/logs/*.log`
|
||||
- 浏览器会话产物
|
||||
- 截图和证明文件
|
||||
|
||||
当 `TENCENT_BROWSER_HEADLESS=false` 时，开发版后端容器会自动启动 `Xvfb + x11vnc + noVNC`。
|
||||
默认可直接在本机访问：
|
||||
|
||||
- `http://127.0.0.1:6080/vnc.html`
|
||||
|
||||
这样即使整个项目都跑在 Docker 里，也可以直接查看后端 Playwright 浏览器画面。
|
||||
|
||||
PostgreSQL 数据则保存在 Docker volume 里：
|
||||
|
||||
- `postgres_dev_data`
|
||||
|
||||
当前 Dockerfile 已默认针对国内服务器优化以下下载源：
|
||||
|
||||
- Debian `apt` 使用腾讯云镜像
|
||||
- `npm` 使用 `npmmirror`
|
||||
- Python `pip` 使用腾讯云 PyPI 镜像
|
||||
- 后端 Playwright 固定为 `1.42.1`，浏览器下载使用 `npmmirror`
|
||||
|
||||
如果你的服务器网络环境不同，也可以在构建时覆盖：
|
||||
查看容器状态：
|
||||
|
||||
```bash
|
||||
docker compose build \
|
||||
--build-arg DEBIAN_MIRROR=mirrors.tuna.tsinghua.edu.cn \
|
||||
--build-arg NPM_REGISTRY=https://registry.npmjs.org \
|
||||
--build-arg UV_INDEX_URL=https://pypi.org/simple
|
||||
docker compose -f docker-compose.dev.yml ps
|
||||
```
|
||||
|
||||
默认入口：
|
||||
查看日志：
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.dev.yml logs -f backend
|
||||
docker compose -f docker-compose.dev.yml logs -f frontend
|
||||
docker compose -f docker-compose.dev.yml logs -f ocr-worker
|
||||
```
|
||||
|
||||
停止环境：
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.dev.yml down
|
||||
```
|
||||
|
||||
## 开发验证
|
||||
|
||||
本项目以容器内验证为准。
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.dev.yml exec -T backend npm test
|
||||
docker compose -f docker-compose.dev.yml exec -T backend npm run typecheck
|
||||
docker compose -f docker-compose.dev.yml exec -T frontend npm run typecheck
|
||||
docker compose -f docker-compose.dev.yml exec -T frontend npm run lint
|
||||
```
|
||||
|
||||
前端生产构建：
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.dev.yml exec -T frontend npm run build
|
||||
```
|
||||
|
||||
后端数据库迁移通常会在启动时自动执行；需要手动执行时：
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.dev.yml exec -T backend npm run db:migrate
|
||||
```
|
||||
|
||||
## 热更新
|
||||
|
||||
开发版 Compose 会把源码挂载进容器：
|
||||
|
||||
- 修改 `apps/backend/src`：后端容器内 `node --watch` 自动重启
|
||||
- 修改 `apps/frontend/src`：Vite 自动 HMR
|
||||
- 修改 `apps/backend/subservices/ocr-worker`：下次 OCR 调用会使用挂载后的代码
|
||||
- 修改数据库 migration：重启后端会自动执行迁移
|
||||
|
||||
如果只改业务代码，一般不需要重新 `--build`。改 Dockerfile、系统依赖或基础镜像时再重新构建。
|
||||
|
||||
## 环境变量
|
||||
|
||||
本地开发从根目录 `.env` 读取，模板为：
|
||||
|
||||
```bash
|
||||
cp .env.mac-docker.example .env
|
||||
```
|
||||
|
||||
生产部署从 `.env.server.example` 复制：
|
||||
|
||||
```bash
|
||||
cp .env.server.example .env
|
||||
```
|
||||
|
||||
常用变量：
|
||||
|
||||
- `APP_BASE_URL`：应用公网地址，用于推导领取链接
|
||||
- `CLAIM_BASE_URL`：领取页地址，优先级高于 `APP_BASE_URL`
|
||||
- `ADMIN_SESSION_SECRET`：后台登录态签名密钥
|
||||
- `ADMIN_DEFAULT_USERS_JSON`：默认后台用户
|
||||
- `DATABASE_URL`：PostgreSQL 连接串
|
||||
- `TENCENT_BROWSER_HEADLESS`：Playwright 是否无头运行
|
||||
- `TENCENT_BROWSER_PREWARM`：启动时是否预热浏览器
|
||||
- `OCR_BASE_URL`：OCR worker 地址
|
||||
|
||||
## 运行数据
|
||||
|
||||
本地开发数据：
|
||||
|
||||
- 后端配置与运行产物：`apps/backend/data`
|
||||
- PostgreSQL 数据：Docker volume `postgres_dev_data`
|
||||
- 后端日志：`apps/backend/data/logs`
|
||||
- 浏览器会话：`apps/backend/data/browser-sessions`
|
||||
- 兑换截图：`apps/backend/data/redeem-screenshots`
|
||||
|
||||
生产部署数据：
|
||||
|
||||
- 后端数据挂载到 `deploy/data/backend`
|
||||
- PostgreSQL 数据保存在 Docker volume `postgres_data`
|
||||
- Caddy 数据保存在 Docker volume `caddy_data`
|
||||
|
||||
注意：`apps/backend/data/*.json` 中可能包含账号、Cookie、token、平台配置等敏感信息。提交代码前请确认没有把真实生产凭据提交到仓库。
|
||||
|
||||
## 生产部署
|
||||
|
||||
在服务器上准备 `.env` 后启动：
|
||||
|
||||
```bash
|
||||
cp .env.server.example .env
|
||||
mkdir -p deploy/data/backend
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
生产入口：
|
||||
|
||||
- 前端与领取页：`https://你的域名/`
|
||||
- 后端健康检查：`https://你的域名/health`
|
||||
- 后端接口前缀：`https://你的域名/api/v1/...`
|
||||
- 后端 API：`https://你的域名/api/v1/...`
|
||||
|
||||
开发环境下的链接生成规则：
|
||||
生产 Compose 会自动：
|
||||
|
||||
- 优先使用 `CLAIM_BASE_URL`
|
||||
- 如果未设置 `CLAIM_BASE_URL`，后端会自动根据 `APP_BASE_URL` 推导为 `APP_BASE_URL/#/claim`
|
||||
- 启动 PostgreSQL
|
||||
- 启动 OCR worker
|
||||
- 启动后端并执行 migration
|
||||
- 初始化默认后台管理员
|
||||
- 同步履约目录
|
||||
- 通过 Caddy 暴露前端和 API
|
||||
|
||||
开发时如果只改业务代码，直接保留 `docker compose -f docker-compose.dev.yml up -d` 即可：
|
||||
查看生产日志：
|
||||
|
||||
- 改后端 `src/`：容器内自动热重启
|
||||
- 改前端 `src/`：Vite 自动热更新
|
||||
- 改 OCR Python：后端下次调用时直接走挂载后的最新源码
|
||||
- 改数据库 schema：后端启动时会自动执行 migration
|
||||
```bash
|
||||
docker compose logs -f backend
|
||||
docker compose logs -f web
|
||||
```
|
||||
|
||||
详细文档：
|
||||
## 开发数据脚本
|
||||
|
||||
- [服务器部署教程](/Users/yml/codes/order-site-workspace/docs/%E6%9C%8D%E5%8A%A1%E5%99%A8%E9%83%A8%E7%BD%B2%E6%95%99%E7%A8%8B.md)
|
||||
- [首次上线检查清单](/Users/yml/codes/order-site-workspace/docs/%E9%A6%96%E6%AC%A1%E4%B8%8A%E7%BA%BF%E6%A3%80%E6%9F%A5%E6%B8%85%E5%8D%95.md)
|
||||
- [mac 本地 Docker 调试模板](/Users/yml/codes/order-site-workspace/.env.mac-docker.example)
|
||||
- [服务器部署模板](/Users/yml/codes/order-site-workspace/.env.server.example)
|
||||
后端提供开发数据脚本：
|
||||
|
||||
## 迁移原则
|
||||
```bash
|
||||
docker compose -f docker-compose.dev.yml exec -T backend npm run seed:dev-data
|
||||
docker compose -f docker-compose.dev.yml exec -T backend npm run cleanup:dev-data
|
||||
```
|
||||
|
||||
- 不重写现有业务代码
|
||||
- 先统一目录、部署和配置
|
||||
- 生产环境优先使用 `.env` 和宿主机数据目录挂载
|
||||
- 本机 Docker 调试优先使用 [docker-compose.dev.yml](/Users/yml/codes/order-site-workspace/docker-compose.dev.yml)
|
||||
脚本默认有预览/确认语义，执行前注意终端输出说明。
|
||||
|
||||
## 主要业务模块
|
||||
|
||||
- `apps/backend/src/routes`：API 路由
|
||||
- `apps/backend/src/services/order`：订单、webhook、库存和履约匹配
|
||||
- `apps/backend/src/services/fulfillment`：快手 Cloud 等履约编排
|
||||
- `apps/backend/src/services/session`：腾讯登录、二维码、兑换和截图
|
||||
- `apps/backend/src/services/admin`：后台读写、权限、配置管理
|
||||
- `apps/backend/src/services/platforms`：外部平台 API 封装
|
||||
- `apps/backend/src/repositories`：数据库访问
|
||||
- `apps/frontend/src/views/admin`：后台页面
|
||||
- `apps/frontend/src/views/claim`：用户领取页
|
||||
|
||||
## 排障
|
||||
|
||||
如果页面打不开：
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.dev.yml ps
|
||||
docker compose -f docker-compose.dev.yml logs -f web
|
||||
```
|
||||
|
||||
如果后端未 ready：
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.dev.yml logs -f backend
|
||||
curl http://localhost/health/ready
|
||||
```
|
||||
|
||||
如果浏览器兑换或扫码异常：
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.dev.yml logs -f backend
|
||||
open http://127.0.0.1:6080/vnc.html
|
||||
```
|
||||
|
||||
如果前端类型或 lint 失败：
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.dev.yml exec -T frontend npm run typecheck
|
||||
docker compose -f docker-compose.dev.yml exec -T frontend npm run lint
|
||||
```
|
||||
|
||||
如果后端单测失败：
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.dev.yml exec -T backend npm test
|
||||
```
|
||||
|
||||
## 提交前检查清单
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.dev.yml exec -T backend npm test
|
||||
docker compose -f docker-compose.dev.yml exec -T backend npm run typecheck
|
||||
docker compose -f docker-compose.dev.yml exec -T frontend npm run typecheck
|
||||
docker compose -f docker-compose.dev.yml exec -T frontend npm run lint
|
||||
```
|
||||
|
||||
确认项：
|
||||
|
||||
- 没有提交真实账号、Cookie、token、手机号或生产配置
|
||||
- `.env` 未被提交
|
||||
- 数据库 migration 与代码一起提交
|
||||
- 领取链接相关改动已在 Docker 环境验证
|
||||
- 涉及 Playwright/OCR 的改动已看过 noVNC 或相关日志
|
||||
|
||||
Reference in New Issue
Block a user