order_site

订单自动兑换与履约管理系统。

项目采用前后端分离架构，主要用于接收订单、匹配履约规则、生成领取链接、管理库存、执行自动/半自动兑换，并提供后台页面处理人工复核、平台配置和任务追踪。

技术栈

• 前端：Vue 3、Vite、Element Plus、TypeScript
• 后端：Node.js、Express、PostgreSQL、Playwright
• OCR：外部镜像服务，后端通过 OCR_BASE_URL 调用
• 网关：Caddy
• 本地与生产运行：Docker Compose

目录结构

apps/
  backend/                  后端 API、任务编排、平台对接、数据库迁移
    src/
    data/                   本地开发运行数据和平台配置
  frontend/                 前端后台、领取页和配置页面
deploy/
  caddy/                    Caddy 反向代理配置
  docker/                   前后端镜像 Dockerfile
docs/                       平台接口、迁移设计和部署资料
docker-compose.dev.yml      本地 Docker 开发环境
docker-compose.yml          生产/服务器 Compose

本地开发

推荐直接使用 Docker，本地不需要额外维护 Node、PostgreSQL、Playwright 浏览器和 OCR 运行环境。

cp .env.mac-docker.example .env
docker compose -f docker-compose.dev.yml up -d --build

如果只运行快手 Cloud / 91 卡券 / 快手小店核销链路，可以使用轻量 Compose。这个模式不会启动 OCR，也不会安装或预热 Playwright 浏览器：

docker compose -f docker-compose.kuaishou.dev.yml up -d --build

启动后常用入口：

• 前端、后台、领取页：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

快手轻量开发模式没有 noVNC 入口，前端首页默认进入后台。

查看容器状态：

docker compose -f docker-compose.dev.yml ps

查看日志：

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

停止环境：

docker compose -f docker-compose.dev.yml down

开发验证

本项目以容器内验证为准。

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 backend npm run build
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

前端生产构建：

docker compose -f docker-compose.dev.yml exec -T frontend npm run build

后端数据库迁移通常会在启动时自动执行；需要手动执行时：

docker compose -f docker-compose.dev.yml exec -T backend npm run db:migrate

热更新

开发版 Compose 会把源码挂载进容器：

• 修改 apps/backend/src：后端容器内 tsx watch 自动重启
• 修改 apps/frontend/src：Vite 自动 HMR
• 修改数据库 migration：重启后端会自动执行迁移

如果只改业务代码，一般不需要重新 --build。改 Dockerfile、系统依赖或基础镜像时再重新构建。

环境变量

本地开发从根目录 .env 读取，模板为：

cp .env.mac-docker.example .env

生产部署从 .env.server.example 复制：

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_IMAGE：OCR 外部服务镜像，默认 order_site-ocr-worker:latest
• OCR_BASE_URL：后端访问 OCR 的 HTTP 地址，Docker 内默认 http://ocr-worker:8100

运行数据

本地开发数据：

• 后端配置与运行产物：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 后启动：

cp .env.server.example .env
mkdir -p deploy/data/backend
docker compose up -d --build

只部署快手轻量服务时使用：

mkdir -p deploy/data/backend-kuaishou
docker compose -f docker-compose.kuaishou.yml up -d --build

生产入口：

• 前端与领取页：https://你的域名/
• 后端健康检查：https://你的域名/health
• 后端 API：https://你的域名/api/v1/...

生产 Compose 会自动：

• 启动 PostgreSQL
• 启动 OCR worker
• 启动后端并执行 migration
• 初始化默认后台管理员
• 同步履约目录
• 通过 Caddy 暴露前端和 API

查看生产日志：

docker compose logs -f backend
docker compose logs -f web

开发数据脚本

后端提供开发数据脚本：

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

脚本默认有预览/确认语义，执行前注意终端输出说明。

主要业务模块

• 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：用户领取页

排障

如果页面打不开：

docker compose -f docker-compose.dev.yml ps
docker compose -f docker-compose.dev.yml logs -f web

如果后端未 ready：

docker compose -f docker-compose.dev.yml logs -f backend
curl http://localhost/health/ready

如果浏览器兑换或扫码异常：

docker compose -f docker-compose.dev.yml logs -f backend
open http://127.0.0.1:6080/vnc.html

如果前端类型或 lint 失败：

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

如果后端单测失败：

docker compose -f docker-compose.dev.yml exec -T backend npm test

提交前检查清单

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 或相关日志