order_site/apps/backend/README.md

order-site-backend

腾讯活动浏览器会话后端。

当前主线只有一条：

• 后端托管 Playwright 浏览器
• 前端展示二维码并轮询会话状态
• 登录完成后，后端直接在活动页填写 CDK、识别验证码、执行兑换
• 兑换完成后返回状态，并按配置决定是否生成截图/证明产物

快速启动

先安装 Node 依赖：

npm install

首次使用前同步 OCR 子服务依赖：

cd /Users/yml/codes/order-site-backend/subservices/ocr-worker
uv sync

回到项目根目录启动：

cd /Users/yml/codes/order-site-backend
npm run dev

Linux 部署：

npm install
npm run browser:install:linux
npm run start

配置文件

现在推荐直接改配置文件，不需要每次在终端里手动拼环境变量。

• 默认配置：config/default.cjs
• 本地覆盖：config/local.cjs
• 参考模板：config/local.example.cjs

推荐做法：

1. 通用默认值放在 config/default.cjs
2. 你自己机器上的配置放在 config/local.cjs
3. 只有 CI、部署脚本、临时排查时再用环境变量覆盖

当前最常改的配置有：

• 服务端口
• 浏览器是否无头、是否预热、是否常驻、slowMo
• OCR 子服务目录
• 会话调试开关
• 兑换证明模式 full | basic | off

接口

• POST /api/v1/tencent/browser/session 创建浏览器会话，返回 sessionId、二维码和初始状态
• GET /api/v1/tencent/browser/session/:sessionId 返回完整会话状态
• GET /api/v1/tencent/browser/session/:sessionId/summary 轮询用轻量摘要接口，默认不返回二维码 base64
• POST /api/v1/tencent/browser/session/:sessionId/refresh 强制刷新后端活动页
• POST /api/v1/tencent/browser/session/:sessionId/redeem 执行兑换
• GET /api/v1/tencent/browser/session/:sessionId/screenshot 读取最近一次兑换截图
• DELETE /api/v1/tencent/browser/session/:sessionId 关闭浏览器会话

目录

• src/index.js Express 入口
• src/routes/tencent.js 接口路由
• src/services/session.js 会话编排与浏览器生命周期
• src/services/session-*.js 登录、兑换、OCR、凭证产物等模块
• subservices/ocr-worker 内嵌 OCR 子服务

产物

浏览器会话产物默认保存在：

• data/browser-sessions/<sessionId>/qq-qr.png
• data/browser-sessions/<sessionId>/session.json
• data/browser-sessions/<sessionId>/captcha-attempt-*.png
• data/browser-sessions/<sessionId>/redeem-result.png
• data/browser-sessions/<sessionId>/page.html
• data/browser-sessions/<sessionId>/result.json

这些都是运行时产物，默认不提交 Git。

TENCENT_REDEEM_PROOF_MODE 对应的配置文件项会影响生成强度：

• full：完整证明
• basic：只保留最终截图和结果 JSON
• off：不生成证明文件