1078 lines
25 KiB
Markdown
1078 lines
25 KiB
Markdown
# 方案 A：订单编排与自动兑换设计
|
||
|
||
## 1. 目标
|
||
|
||
基于现有两个项目：
|
||
|
||
- 后端 [order-site-backend](/Users/yml/codes/order-site-backend)
|
||
- 前端 [order-site-rewrite](/Users/yml/codes/order-site-rewrite)
|
||
|
||
增加一条面向真实订单的自动化交付链路：
|
||
|
||
1. 第三方平台通过订单创建成功或支付成功通知，将订单数据推送到我方后端。
|
||
2. 后端根据订单和商品信息匹配需要发放的 CDK，并创建交付任务。
|
||
3. 后端生成一个面向用户的领取链接，并通过可用渠道发送给用户。
|
||
4. 用户打开链接后，通过 QQ 或 WX 完成角色绑定。
|
||
5. 后端复用现有 Playwright 自动化能力，自动提交 CDK、执行绑定、生成截图。
|
||
6. 前端实时展示绑定状态、兑换状态和最终截图。
|
||
|
||
该方案采用“订单编排层 + 浏览器自动化执行层”两层结构，不直接把现有浏览器会话工具当作订单系统使用。
|
||
|
||
## 2. 当前系统现状
|
||
|
||
### 2.1 后端现状
|
||
|
||
当前后端主线是浏览器会话兑换工具，而不是订单系统。
|
||
|
||
- Express 入口在 [src/index.js](/Users/yml/codes/order-site-backend/src/index.js:1)
|
||
- 现有路由只覆盖腾讯浏览器会话接口，在 [src/routes/tencent.js](/Users/yml/codes/order-site-backend/src/routes/tencent.js:1)
|
||
- 浏览器会话创建、刷新、关闭、兑换都集中在 [src/services/session.js](/Users/yml/codes/order-site-backend/src/services/session.js:80)
|
||
- 验证码识别与兑换提交流程在 [src/services/session-redeem.js](/Users/yml/codes/order-site-backend/src/services/session-redeem.js:3)
|
||
- 截图、结果 JSON、证明产物生成在 [src/services/session-proof.js](/Users/yml/codes/order-site-backend/src/services/session-proof.js:16)
|
||
- OCR 子服务使用 `uv` 启动，在 [src/services/ocr.js](/Users/yml/codes/order-site-backend/src/services/ocr.js:83)
|
||
|
||
当前系统没有以下关键能力：
|
||
|
||
- 没有订单表
|
||
- 没有 CDK 库存表
|
||
- 没有 webhook 接收和签名校验
|
||
- 没有任务状态机
|
||
- 没有用户领取链接管理
|
||
- 没有消息投递模块
|
||
- 没有浏览器会话与订单任务的绑定关系
|
||
|
||
### 2.2 前端现状
|
||
|
||
当前前端是一个单页腾讯兑换工具。
|
||
|
||
- 路由只包含 `/tx/browser`，在 [src/router/index.ts](/Users/yml/codes/order-site-rewrite/src/router/index.ts:1)
|
||
- 主页面在 [src/views/tx/TencentBrowserView.vue](/Users/yml/codes/order-site-rewrite/src/views/tx/TencentBrowserView.vue:1)
|
||
- 页面编排在 [src/composables/useTencentBrowserSessionPage.ts](/Users/yml/codes/order-site-rewrite/src/composables/useTencentBrowserSessionPage.ts:1)
|
||
- 状态轮询在 [src/composables/tencent/useTencentBrowserSessionPolling.ts](/Users/yml/codes/order-site-rewrite/src/composables/tencent/useTencentBrowserSessionPolling.ts:1)
|
||
- 兑换前角色确认、兑换按钮、结果展示已经具备基础 UI，可复用
|
||
|
||
当前前端没有以下能力：
|
||
|
||
- 没有订单领取页
|
||
- 没有 token 校验页
|
||
- 没有订单详情页
|
||
- 没有任务状态驱动的前端展示
|
||
- 没有“订单上下文中的浏览器会话”概念
|
||
|
||
## 3. 总体架构
|
||
|
||
### 3.1 分层设计
|
||
|
||
建议分成 4 层：
|
||
|
||
1. 平台接入层
|
||
负责接收订单创建成功、支付成功、售后等通知，完成签名校验和原始数据落库。
|
||
2. 订单编排层
|
||
负责订单幂等、商品解析、CDK 预占、任务创建、链接生成、状态流转。
|
||
3. 浏览器自动化执行层
|
||
复用现有腾讯浏览器会话、角色识别、验证码识别、兑换提交、截图生成能力。
|
||
4. 用户交互层
|
||
用户通过领取链接进入前端页面，完成 QQ/WX 登录、角色确认、查看结果。
|
||
|
||
### 3.2 核心原则
|
||
|
||
- 订单与浏览器会话解耦
|
||
- CDK 先预占、后核销
|
||
- 所有平台通知必须幂等
|
||
- 用户访问链接使用 token，不直接使用订单号鉴权
|
||
- 浏览器自动化失败必须可重试、可人工接管
|
||
- 所有关键节点都要保留审计数据
|
||
|
||
## 4. 业务流程
|
||
|
||
### 4.1 主流程
|
||
|
||
1. 平台发送订单通知到后端 webhook。
|
||
2. 后端校验签名，按平台订单号幂等写入 `orders`。
|
||
3. 根据订单商品、规格、渠道信息生成一个或多个 `delivery_tasks`。
|
||
4. 系统从 `cdk_inventory` 中为任务预占可用 CDK。
|
||
5. 系统生成 `claim_token`，构造领取链接。
|
||
6. 系统通过站内消息、短信、客服人工转发或支付成功页展示，把链接给用户。
|
||
7. 用户打开链接，前端调用后端校验 token 和任务状态。
|
||
8. 用户选择 QQ 或 WX 登录，后端创建浏览器 session，并绑定到 `delivery_task`。
|
||
9. 用户扫码后，后端识别角色、大区、昵称等信息。
|
||
10. 前端展示识别结果，用户确认角色无误。
|
||
11. 后端自动执行 CDK 提交、验证码识别、截图生成。
|
||
12. 成功后任务进入 `redeemed`，CDK 进入 `delivered`。
|
||
13. 前端展示截图、结果消息、订单号、角色信息。
|
||
|
||
### 4.2 异常流程
|
||
|
||
- webhook 重复推送：只更新状态，不重复创建任务
|
||
- 商品无法匹配 CDK：任务进入 `manual_review`
|
||
- CDK 库存不足：任务进入 `waiting_inventory`
|
||
- token 过期：提示用户重新获取领取链接
|
||
- 浏览器自动化失败：任务进入 `retry_pending` 或 `manual_review`
|
||
- 用户长时间未领取：任务进入 `expired`，释放预占 CDK
|
||
|
||
## 5. 数据模型设计
|
||
|
||
建议先上 SQLite，跑通后如有并发压力再切 PostgreSQL。当前项目还没有数据库依赖，先用 SQLite 可以把复杂度压低。
|
||
|
||
### 5.1 `orders`
|
||
|
||
订单主表。
|
||
|
||
字段建议：
|
||
|
||
- `id`
|
||
- `platform`
|
||
- `platform_order_id`
|
||
- `order_status`
|
||
- `pay_status`
|
||
- `buyer_id`
|
||
- `buyer_name`
|
||
- `raw_payload_json`
|
||
- `created_at`
|
||
- `updated_at`
|
||
- `paid_at`
|
||
|
||
约束建议：
|
||
|
||
- `platform + platform_order_id` 唯一
|
||
|
||
### 5.2 `order_items`
|
||
|
||
订单子项表，用于一单多商品。
|
||
|
||
字段建议：
|
||
|
||
- `id`
|
||
- `order_id`
|
||
- `sku_code`
|
||
- `sku_name`
|
||
- `quantity`
|
||
- `spec_json`
|
||
- `delivery_mode`
|
||
- `created_at`
|
||
- `updated_at`
|
||
|
||
### 5.3 `cdk_inventory`
|
||
|
||
CDK 库存表。
|
||
|
||
字段建议：
|
||
|
||
- `id`
|
||
- `batch_no`
|
||
- `sku_code`
|
||
- `cdk_code`
|
||
- `status`
|
||
- `reserved_by_task_id`
|
||
- `delivered_at`
|
||
- `invalid_reason`
|
||
- `created_at`
|
||
- `updated_at`
|
||
|
||
状态建议：
|
||
|
||
- `available`
|
||
- `reserved`
|
||
- `delivered`
|
||
- `invalid`
|
||
|
||
### 5.4 `delivery_tasks`
|
||
|
||
交付任务表，是整个方案的核心。
|
||
|
||
字段建议：
|
||
|
||
- `id`
|
||
- `order_id`
|
||
- `order_item_id`
|
||
- `platform_order_id`
|
||
- `task_no`
|
||
- `task_status`
|
||
- `login_type`
|
||
- `claim_token_id`
|
||
- `reserved_cdk_id`
|
||
- `browser_session_id`
|
||
- `role_id`
|
||
- `role_name`
|
||
- `area`
|
||
- `partition`
|
||
- `nickname`
|
||
- `result_code`
|
||
- `result_message`
|
||
- `screenshot_path`
|
||
- `artifacts_json`
|
||
- `last_error`
|
||
- `retry_count`
|
||
- `expires_at`
|
||
- `claimed_at`
|
||
- `redeemed_at`
|
||
- `created_at`
|
||
- `updated_at`
|
||
|
||
状态建议：
|
||
|
||
- `pending_payment`
|
||
- `paid`
|
||
- `waiting_inventory`
|
||
- `cdk_reserved`
|
||
- `link_generated`
|
||
- `claimed`
|
||
- `role_confirmed`
|
||
- `redeeming`
|
||
- `redeemed`
|
||
- `retry_pending`
|
||
- `manual_review`
|
||
- `expired`
|
||
- `closed`
|
||
|
||
### 5.5 `claim_tokens`
|
||
|
||
领取链接表。
|
||
|
||
字段建议：
|
||
|
||
- `id`
|
||
- `task_id`
|
||
- `token`
|
||
- `status`
|
||
- `expired_at`
|
||
- `used_at`
|
||
- `max_use_count`
|
||
- `used_count`
|
||
- `created_at`
|
||
- `updated_at`
|
||
|
||
状态建议：
|
||
|
||
- `active`
|
||
- `used`
|
||
- `expired`
|
||
- `revoked`
|
||
|
||
### 5.6 `webhook_events`
|
||
|
||
保留原始通知，便于审计和重放。
|
||
|
||
字段建议：
|
||
|
||
- `id`
|
||
- `platform`
|
||
- `event_type`
|
||
- `event_key`
|
||
- `signature_valid`
|
||
- `headers_json`
|
||
- `query_json`
|
||
- `body_json`
|
||
- `processed`
|
||
- `process_error`
|
||
- `created_at`
|
||
|
||
## 6. 后端模块拆分
|
||
|
||
建议在现有后端上新增以下模块。
|
||
|
||
### 6.1 路由层
|
||
|
||
新增路由目录建议：
|
||
|
||
- `src/routes/webhooks.js`
|
||
- `src/routes/orders.js`
|
||
- `src/routes/claims.js`
|
||
- `src/routes/admin.js`
|
||
|
||
说明：
|
||
|
||
- `webhooks.js` 接平台推送
|
||
- `orders.js` 给内部系统或管理端查订单和任务
|
||
- `claims.js` 给用户领取页调用
|
||
- `admin.js` 做手工补单、重试、失效处理
|
||
|
||
### 6.2 服务层
|
||
|
||
新增服务建议：
|
||
|
||
- `src/services/order-service.js`
|
||
- `src/services/order-item-service.js`
|
||
- `src/services/delivery-task-service.js`
|
||
- `src/services/cdk-service.js`
|
||
- `src/services/claim-service.js`
|
||
- `src/services/webhook-service.js`
|
||
- `src/services/message-service.js`
|
||
- `src/services/redeem-executor-service.js`
|
||
|
||
职责划分建议：
|
||
|
||
- `webhook-service`
|
||
负责签名校验、原始通知记录、事件分发
|
||
- `order-service`
|
||
负责订单幂等写入和状态更新
|
||
- `delivery-task-service`
|
||
负责任务状态机
|
||
- `cdk-service`
|
||
负责 CDK 分配、预占、释放、核销
|
||
- `claim-service`
|
||
负责 token 生成、校验、过期
|
||
- `message-service`
|
||
负责发链接
|
||
- `redeem-executor-service`
|
||
负责把任务桥接到现有腾讯浏览器会话执行器
|
||
|
||
### 6.3 持久化层
|
||
|
||
建议新增：
|
||
|
||
- `src/db/`
|
||
- `src/repositories/`
|
||
|
||
推荐目录：
|
||
|
||
- `src/db/client.js`
|
||
- `src/repositories/order-repo.js`
|
||
- `src/repositories/task-repo.js`
|
||
- `src/repositories/cdk-repo.js`
|
||
- `src/repositories/claim-repo.js`
|
||
- `src/repositories/webhook-repo.js`
|
||
|
||
## 7. 对现有浏览器自动化能力的复用方式
|
||
|
||
现有后端能力不废弃，而是作为执行器继续使用。
|
||
|
||
### 7.1 可直接复用的能力
|
||
|
||
- 创建浏览器会话：`createTencentBrowserSession`
|
||
- 轮询会话状态：`getTencentBrowserSession`、`getTencentBrowserSessionSummary`
|
||
- 扫码登录后识别角色信息：`session.js` 内已有活动页信息抽取逻辑
|
||
- 执行兑换：`redeemTencentBrowserSession`
|
||
- 生成截图和结果 JSON：`saveRedeemArtifacts`
|
||
- OCR worker：继续使用当前 `uv run ocr-worker worker`
|
||
|
||
### 7.2 需要补的一层包装
|
||
|
||
不要让订单系统直接操作裸 `sessionId`，应通过 `redeem-executor-service` 管理：
|
||
|
||
1. 根据 `taskId` 创建浏览器 session
|
||
2. 把 `taskId <-> sessionId` 关系落库
|
||
3. 用户扫码完成后，把识别到的角色信息同步回任务
|
||
4. 用户确认角色后，再触发兑换
|
||
5. 兑换完成后，把截图路径和最终结果回写到任务
|
||
|
||
## 8. API 设计
|
||
|
||
### 8.1 平台 webhook
|
||
|
||
`POST /api/v1/webhooks/agiso/trade`
|
||
|
||
职责：
|
||
|
||
- 接收订单创建成功通知
|
||
- 接收支付成功通知
|
||
- 验签
|
||
- 幂等入库
|
||
- 推进任务状态
|
||
|
||
### 8.2 用户领取页相关
|
||
|
||
`GET /api/v1/claim/:token`
|
||
|
||
返回：
|
||
|
||
- token 是否有效
|
||
- 订单号
|
||
- 商品摘要
|
||
- 当前任务状态
|
||
- 是否已绑定角色
|
||
- 是否已有截图
|
||
|
||
`POST /api/v1/claim/:token/session`
|
||
|
||
入参：
|
||
|
||
- `loginType: qq | wx`
|
||
|
||
职责：
|
||
|
||
- 校验 token
|
||
- 创建腾讯浏览器 session
|
||
- 将 session 绑定到任务
|
||
- 返回二维码和 session 摘要
|
||
|
||
`GET /api/v1/claim/:token/session/summary`
|
||
|
||
职责：
|
||
|
||
- 轮询当前领取任务下的 session 状态
|
||
- 返回角色信息、二维码状态、截图状态
|
||
|
||
`POST /api/v1/claim/:token/confirm-role`
|
||
|
||
职责：
|
||
|
||
- 用户确认当前角色无误
|
||
- 把任务推进到 `role_confirmed`
|
||
|
||
`POST /api/v1/claim/:token/redeem`
|
||
|
||
职责：
|
||
|
||
- 后端读取预占 CDK
|
||
- 调用执行器自动提交
|
||
- 回写结果
|
||
|
||
`GET /api/v1/claim/:token/screenshot`
|
||
|
||
职责：
|
||
|
||
- 返回最终截图
|
||
|
||
### 8.3 管理后台或内部接口
|
||
|
||
`POST /api/v1/admin/tasks/:taskId/retry`
|
||
|
||
`POST /api/v1/admin/tasks/:taskId/release-cdk`
|
||
|
||
`POST /api/v1/admin/tasks/:taskId/close`
|
||
|
||
`GET /api/v1/admin/orders/:orderId`
|
||
|
||
`GET /api/v1/admin/tasks/:taskId`
|
||
|
||
## 9. 运营后台设计
|
||
|
||
### 9.1 是否需要后台
|
||
|
||
需要，而且应作为正式模块纳入方案。
|
||
|
||
原因：
|
||
|
||
- 订单通知会重复、失败或延迟，必须能人工排查
|
||
- CDK 库存需要日常导入、校验、释放、核销
|
||
- 自动化链路不是 100% 成功，必须有失败任务处理入口
|
||
- 用户咨询时，需要快速看到订单、任务、角色、截图和错误原因
|
||
- 后续一定会出现补发、重试、关闭任务、重新生成链接等运营动作
|
||
|
||
如果没有后台，系统上线后所有异常都会退化成查数据库、查日志、手改数据，维护成本会快速失控。
|
||
|
||
### 9.2 更稳的做法
|
||
|
||
更稳的做法不是把管理页面直接混进用户领取页，而是拆成两套入口：
|
||
|
||
1. 用户前台
|
||
继续服务用户领取、扫码登录、角色确认、结果查看。
|
||
2. 运营后台
|
||
专门服务订单排查、CDK 管理、任务重试、异常处理。
|
||
|
||
建议形式：
|
||
|
||
- 用户前台继续使用 [order-site-rewrite](/Users/yml/codes/order-site-rewrite)
|
||
- 运营后台先作为同仓库下独立路由模块实现，例如 `/admin`
|
||
- 后端单独提供 `/api/v1/admin/*` 接口
|
||
|
||
这样做的好处：
|
||
|
||
- 用户链路和运营链路隔离
|
||
- 权限边界更清楚
|
||
- 页面状态不会互相污染
|
||
- 以后即使单独拆管理后台，也不会影响用户前台
|
||
|
||
### 9.3 后台第一版目标
|
||
|
||
第一版后台不追求复杂权限系统和漂亮界面，目标只有一个：
|
||
|
||
让你能稳定运营这条自动交付链路。
|
||
|
||
第一版最少应覆盖：
|
||
|
||
1. 查订单
|
||
2. 查交付任务
|
||
3. 导入和维护 CDK
|
||
4. 查看 webhook 日志
|
||
5. 重试失败任务
|
||
6. 释放预占 CDK
|
||
7. 重新生成领取链接
|
||
|
||
### 9.4 后台页面模块建议
|
||
|
||
#### 1. 概览页
|
||
|
||
展示核心数字：
|
||
|
||
- 今日订单数
|
||
- 已支付待领取数
|
||
- 领取中任务数
|
||
- 兑换成功数
|
||
- 异常任务数
|
||
- 库存不足的 SKU 数
|
||
|
||
这页主要用来让你快速判断系统是否在健康运行。
|
||
|
||
#### 2. 订单列表页
|
||
|
||
展示字段建议：
|
||
|
||
- 订单号
|
||
- 平台
|
||
- 商品摘要
|
||
- 支付状态
|
||
- 订单状态
|
||
- 创建时间
|
||
- 更新时间
|
||
- 对应任务数
|
||
|
||
支持筛选：
|
||
|
||
- 平台订单号
|
||
- 支付状态
|
||
- 时间范围
|
||
- 商品 SKU
|
||
|
||
进入详情后可查看：
|
||
|
||
- 原始订单通知
|
||
- 子项列表
|
||
- 对应交付任务
|
||
|
||
#### 3. 交付任务列表页
|
||
|
||
这是后台最核心的页面。
|
||
|
||
展示字段建议：
|
||
|
||
- `task_no`
|
||
- 平台订单号
|
||
- 商品 SKU
|
||
- 当前任务状态
|
||
- 预占 CDK
|
||
- 登录方式
|
||
- 角色名
|
||
- 角色 ID
|
||
- 浏览器 sessionId
|
||
- 重试次数
|
||
- 最后错误
|
||
- 创建时间
|
||
- 更新时间
|
||
|
||
支持操作：
|
||
|
||
- 查看详情
|
||
- 重新生成链接
|
||
- 重试任务
|
||
- 释放 CDK
|
||
- 关闭任务
|
||
- 标记人工处理
|
||
|
||
#### 4. CDK 管理页
|
||
|
||
这是第二核心页面。
|
||
|
||
应支持：
|
||
|
||
- 单条新增
|
||
- 批量导入
|
||
- 按 SKU 查看库存
|
||
- 查看状态分布
|
||
- 查看预占任务
|
||
- 手动失效
|
||
- 手动释放
|
||
|
||
展示字段建议：
|
||
|
||
- `sku_code`
|
||
- `batch_no`
|
||
- `cdk_code`
|
||
- `status`
|
||
- `reserved_by_task_id`
|
||
- `created_at`
|
||
- `updated_at`
|
||
|
||
导入方式建议至少支持：
|
||
|
||
- 文本框多行粘贴导入
|
||
- CSV 文件导入
|
||
|
||
导入校验建议：
|
||
|
||
- 去重
|
||
- 空值校验
|
||
- SKU 必填
|
||
- 批次号可选但建议保留
|
||
|
||
#### 5. webhook 日志页
|
||
|
||
展示：
|
||
|
||
- 平台
|
||
- 事件类型
|
||
- 平台订单号
|
||
- 验签是否通过
|
||
- 是否处理成功
|
||
- 错误信息
|
||
- 到达时间
|
||
|
||
支持查看：
|
||
|
||
- headers
|
||
- query
|
||
- body
|
||
- 对应生成的订单和任务
|
||
|
||
可选操作：
|
||
|
||
- 手动重放处理
|
||
|
||
#### 6. 任务详情页
|
||
|
||
任务详情页建议整合以下信息：
|
||
|
||
- 订单信息
|
||
- 商品和 SKU
|
||
- claim token 状态
|
||
- 浏览器 session 状态
|
||
- 角色识别结果
|
||
- 兑换结果
|
||
- 截图预览
|
||
- 原始错误日志
|
||
- 操作按钮
|
||
|
||
这个页面会成为你处理异常单的主工作台。
|
||
|
||
### 9.5 后台最小接口集
|
||
|
||
建议新增后台接口：
|
||
|
||
#### 订单
|
||
|
||
- `GET /api/v1/admin/orders`
|
||
- `GET /api/v1/admin/orders/:orderId`
|
||
|
||
#### 任务
|
||
|
||
- `GET /api/v1/admin/tasks`
|
||
- `GET /api/v1/admin/tasks/:taskId`
|
||
- `POST /api/v1/admin/tasks/:taskId/retry`
|
||
- `POST /api/v1/admin/tasks/:taskId/close`
|
||
- `POST /api/v1/admin/tasks/:taskId/release-cdk`
|
||
- `POST /api/v1/admin/tasks/:taskId/regenerate-claim-link`
|
||
- `POST /api/v1/admin/tasks/:taskId/mark-manual-review`
|
||
|
||
#### CDK
|
||
|
||
- `GET /api/v1/admin/cdks`
|
||
- `POST /api/v1/admin/cdks`
|
||
- `POST /api/v1/admin/cdks/import`
|
||
- `POST /api/v1/admin/cdks/:cdkId/invalidate`
|
||
- `POST /api/v1/admin/cdks/:cdkId/release`
|
||
|
||
#### webhook
|
||
|
||
- `GET /api/v1/admin/webhook-events`
|
||
- `GET /api/v1/admin/webhook-events/:eventId`
|
||
- `POST /api/v1/admin/webhook-events/:eventId/replay`
|
||
|
||
#### 概览
|
||
|
||
- `GET /api/v1/admin/dashboard/summary`
|
||
|
||
### 9.6 后台权限建议
|
||
|
||
第一版建议至少分两层：
|
||
|
||
1. `admin`
|
||
可导入 CDK、改任务状态、重试任务、关闭任务、重放 webhook。
|
||
2. `operator`
|
||
可查订单、查任务、看截图、看日志，但不能做高风险修改。
|
||
|
||
如果第一版先不做完整账号体系，也至少要做一个最简单的后台鉴权，例如：
|
||
|
||
- 独立后台口令
|
||
- 基础登录态
|
||
- 后端校验管理接口访问权限
|
||
|
||
不要把后台接口直接裸露给公网无鉴权访问。
|
||
|
||
### 9.7 后台与前台的边界
|
||
|
||
建议明确边界：
|
||
|
||
- 前台只处理用户领取和结果查看
|
||
- 后台只处理运营和异常处置
|
||
|
||
前台不要出现：
|
||
|
||
- 手动改任务状态
|
||
- 手动改 CDK
|
||
- 看其他订单
|
||
|
||
后台不要承担：
|
||
|
||
- 用户扫码登录入口
|
||
- 用户领取页展示逻辑
|
||
|
||
这样职责清晰，后续维护成本最低。
|
||
|
||
### 9.8 后台的落地顺序
|
||
|
||
建议放在整体计划的阶段 4 中作为正式内容，但有两个能力应提前做：
|
||
|
||
1. CDK 导入
|
||
2. 任务列表与详情查看
|
||
|
||
原因：
|
||
|
||
- 没有 CDK 导入能力，阶段 1 根本跑不顺
|
||
- 没有任务查看能力，阶段 2 和阶段 3 出问题时无法排查
|
||
|
||
因此更合适的执行顺序是：
|
||
|
||
- 阶段 1 完成订单骨架后，先补一个极简后台
|
||
- 阶段 2 和 3 继续完善业务闭环
|
||
- 阶段 4 再补全 webhook 重放、统计面板、权限细化
|
||
|
||
### 9.9 后台最小可行版本
|
||
|
||
后台 MVP 建议包含：
|
||
|
||
1. 登录页
|
||
2. 概览页
|
||
3. 订单列表页
|
||
4. 任务列表页
|
||
5. 任务详情页
|
||
6. CDK 导入页
|
||
7. webhook 日志页
|
||
|
||
这已经足够支撑第一版系统上线和日常运营。
|
||
|
||
### 9.10 结论
|
||
|
||
后端侧需要一个管理界面，而且应当作为正式模块设计，不建议临时拼接。
|
||
|
||
更稳的做法是：
|
||
|
||
- 用户前台与运营后台分离
|
||
- 后台先做最小可行版本
|
||
- 优先覆盖查单、查任务、导入 CDK、重试异常
|
||
- 后台接口独立鉴权
|
||
|
||
## 10. 前端设计
|
||
|
||
### 9.1 路由设计
|
||
|
||
现有前端只有 `/tx/browser`，建议新增：
|
||
|
||
- `/claim/:token`
|
||
|
||
这个页面才是正式业务入口。
|
||
|
||
`/tx/browser` 保留为内部调试工具页，不作为正式交付页面。
|
||
|
||
### 9.2 页面结构
|
||
|
||
建议页面拆成 4 个区域：
|
||
|
||
1. 订单摘要区
|
||
展示订单号、商品名、状态说明
|
||
2. 登录绑定区
|
||
复用现有二维码卡片能力
|
||
3. 角色确认区
|
||
复用现有角色展示和确认能力
|
||
4. 结果展示区
|
||
复用现有截图和结果卡片能力
|
||
|
||
### 9.3 可复用的前端模块
|
||
|
||
可以复用：
|
||
|
||
- [TencentAuthCard.vue](/Users/yml/codes/order-site-rewrite/src/components/tencent/TencentAuthCard.vue:1)
|
||
- [TencentRedeemPanel.vue](/Users/yml/codes/order-site-rewrite/src/components/tencent/TencentRedeemPanel.vue:1)
|
||
- [TencentResultPanel.vue](/Users/yml/codes/order-site-rewrite/src/components/tencent/TencentResultPanel.vue:1)
|
||
- [useTencentBrowserSessionPolling.ts](/Users/yml/codes/order-site-rewrite/src/composables/tencent/useTencentBrowserSessionPolling.ts:1)
|
||
- [useTencentBrowserSessionPresentation.ts](/Users/yml/codes/order-site-rewrite/src/composables/tencent/useTencentBrowserSessionPresentation.ts:1)
|
||
|
||
但需要改造：
|
||
|
||
- 不再让前端自己输入兑换码
|
||
- 不再让前端自己决定是否创建裸 session
|
||
- 页面所有操作都基于 `claim token`
|
||
|
||
### 9.4 前端状态设计
|
||
|
||
建议页面状态围绕任务状态展开，而不是围绕裸 session：
|
||
|
||
- `tokenValid`
|
||
- `taskStatus`
|
||
- `orderSummary`
|
||
- `session`
|
||
- `activityInfo`
|
||
- `roleConfirmed`
|
||
- `redeemResult`
|
||
- `screenshotUrl`
|
||
|
||
## 11. 状态机设计
|
||
|
||
### 10.1 任务状态流转
|
||
|
||
主状态机建议如下：
|
||
|
||
1. `pending_payment`
|
||
2. `paid`
|
||
3. `waiting_inventory`
|
||
4. `cdk_reserved`
|
||
5. `link_generated`
|
||
6. `claimed`
|
||
7. `role_confirmed`
|
||
8. `redeeming`
|
||
9. `redeemed`
|
||
|
||
异常分支：
|
||
|
||
- `retry_pending`
|
||
- `manual_review`
|
||
- `expired`
|
||
- `closed`
|
||
|
||
### 10.2 CDK 状态流转
|
||
|
||
1. `available`
|
||
2. `reserved`
|
||
3. `delivered`
|
||
|
||
异常分支：
|
||
|
||
- `invalid`
|
||
|
||
### 10.3 token 状态流转
|
||
|
||
1. `active`
|
||
2. `used`
|
||
|
||
异常分支：
|
||
|
||
- `expired`
|
||
- `revoked`
|
||
|
||
## 12. 安全与风控
|
||
|
||
### 11.1 token 安全
|
||
|
||
- token 必须使用高熵随机串
|
||
- 不要把订单号作为唯一访问凭证
|
||
- token 要支持过期
|
||
- token 要支持撤销
|
||
- token 校验失败不要泄露订单是否存在
|
||
|
||
### 11.2 webhook 安全
|
||
|
||
- 验签必须在业务处理前完成
|
||
- 保存原始 query、body、headers
|
||
- 根据平台订单号和事件类型做幂等
|
||
- 对重复通知返回成功，避免平台无限重试
|
||
|
||
### 11.3 自动化风险
|
||
|
||
- 登录状态和验证码都可能失败
|
||
- 活动页 DOM 变更会导致自动化失效
|
||
- 平台风控弹窗可能导致流程卡死
|
||
- 必须保留重试和人工兜底入口
|
||
|
||
## 13. 失败补偿机制
|
||
|
||
### 12.1 自动重试
|
||
|
||
可自动重试的场景：
|
||
|
||
- OCR 识别失败
|
||
- 页面刷新失败
|
||
- 临时网络超时
|
||
- 可恢复的验证码错误
|
||
|
||
不建议自动无限重试，应限制次数并回写错误。
|
||
|
||
### 12.2 人工接管
|
||
|
||
以下场景建议直接转人工：
|
||
|
||
- 角色识别异常
|
||
- 商品和 CDK 映射无法确认
|
||
- 自动化连续失败
|
||
- CDK 已疑似提交但返回结果不明确
|
||
|
||
### 12.3 过期处理
|
||
|
||
- 领取链接超时未使用，任务转 `expired`
|
||
- 任务过期后释放 `reserved` 状态的 CDK
|
||
- 如已创建浏览器 session，应主动清理
|
||
|
||
## 14. 技术选型建议
|
||
|
||
### 13.1 后端
|
||
|
||
当前后端是 Node.js + Express + Playwright，建议保持不变。
|
||
|
||
新增建议：
|
||
|
||
- 数据库先用 SQLite
|
||
- 数据访问先用简单 repository 封装
|
||
- 后续需要时再引入 ORM
|
||
|
||
原因：
|
||
|
||
- 先把主流程跑通
|
||
- 当前系统规模小，没必要过早引入太重的基础设施
|
||
- 浏览器自动化已经在 Node 侧，订单编排继续留在同一进程更简单
|
||
|
||
### 13.2 前端
|
||
|
||
当前前端是 Vue 3 + Element Plus，建议保持不变。
|
||
|
||
只需要增加：
|
||
|
||
- claim 页面
|
||
- claim 相关 API service
|
||
- task 视图模型
|
||
|
||
### 13.3 Python 相关
|
||
|
||
当前 Python 仅用于 OCR worker，继续使用 `uv` 管理即可。
|
||
|
||
如果后续需要：
|
||
|
||
- 图像增强
|
||
- 模板匹配
|
||
- 截图后处理
|
||
|
||
仍然应放在独立 Python 子服务里，并统一通过 `uv` 维护依赖。
|
||
|
||
## 15. 推荐执行顺序
|
||
|
||
建议分 4 个阶段实施。
|
||
|
||
### 阶段 1：后端订单骨架
|
||
|
||
目标：
|
||
|
||
- 接 webhook
|
||
- 落订单
|
||
- 建任务
|
||
- 预占 CDK
|
||
- 生成领取链接
|
||
|
||
要做的事：
|
||
|
||
1. 增加数据库和表结构
|
||
2. 实现 webhook 验签和幂等
|
||
3. 实现订单、任务、CDK、token 的 repository 和 service
|
||
4. 实现任务状态机基础逻辑
|
||
5. 实现领取链接生成
|
||
|
||
阶段产出：
|
||
|
||
- 支付成功后，系统能自动生成领取任务和领取链接
|
||
|
||
### 阶段 2：极简后台 + 前端领取页
|
||
|
||
目标：
|
||
|
||
- 有基本运营能力
|
||
- 用户通过 token 打开页面
|
||
- 看见订单信息
|
||
- 创建登录 session
|
||
- 扫码并确认角色
|
||
|
||
要做的事：
|
||
|
||
1. 新增 `/admin` 路由和极简后台骨架
|
||
2. 实现订单列表、任务列表、任务详情、CDK 导入
|
||
3. 新增 `/claim/:token` 路由
|
||
4. 新增 claim 页面和 API service
|
||
5. 复用当前二维码、轮询、角色确认组件
|
||
6. 页面状态从 `session 驱动` 改成 `task + session 双驱动`
|
||
|
||
阶段产出：
|
||
|
||
- 运营能查任务和导入 CDK，用户能进入正式领取页面并完成角色绑定
|
||
|
||
### 阶段 3：自动兑换闭环
|
||
|
||
目标：
|
||
|
||
- 用户确认角色后自动提交 CDK
|
||
- 生成截图并前端展示
|
||
|
||
要做的事：
|
||
|
||
1. 封装 `redeem-executor-service`
|
||
2. 将任务与 session 建立绑定关系
|
||
3. 后端从预占 CDK 读取兑换码，不再由前端输入
|
||
4. 回写截图路径、业务返回码、错误信息
|
||
|
||
阶段产出：
|
||
|
||
- 从订单通知到最终截图形成完整闭环
|
||
|
||
### 阶段 4：补偿和完整运营能力
|
||
|
||
目标：
|
||
|
||
- 可重试
|
||
- 可过期释放
|
||
- 可人工处理
|
||
- 有更完整的后台能力
|
||
|
||
要做的事：
|
||
|
||
1. 增加任务重试接口
|
||
2. 增加过期清理任务
|
||
3. 增加 webhook 重放
|
||
4. 增加概览统计和异常筛选
|
||
5. 增加后台权限细化
|
||
6. 增加关键日志和审计落库
|
||
|
||
阶段产出：
|
||
|
||
- 系统具备基本上线可运维性
|
||
|
||
## 16. 最小可行版本定义
|
||
|
||
第一版上线目标不建议追求“完全无人值守”，建议定义为：
|
||
|
||
- 平台支付成功后自动创建领取任务
|
||
- 自动预占 CDK
|
||
- 自动生成领取链接
|
||
- 用户进入页面后自行扫码登录
|
||
- 用户确认角色后系统自动提交 CDK
|
||
- 成功后展示截图
|
||
- 运营可在后台查看订单、任务、库存和 webhook 日志
|
||
- 失败后进入重试或人工处理
|
||
|
||
这是当前代码基础上最稳、最容易落地、售后风险最低的版本。
|
||
|
||
## 17. 关键决策结论
|
||
|
||
- 采用方案 A 是合理的
|
||
- 不建议直接用订单号做访问凭证
|
||
- 不建议前端继续保留“手输 CDK”的正式业务模式
|
||
- 不建议一开始就做全自动零确认绑定
|
||
- 建议先做订单编排层，再复用现有浏览器自动化执行层
|
||
- 建议优先做 SQLite 版本跑通链路
|
||
- 建议把 `/tx/browser` 保留为内部调试页，把 `/claim/:token` 做成正式业务入口
|
||
- 建议把运营后台作为正式模块纳入，而不是后补工具页
|
||
|
||
## 18. 下一步落地建议
|
||
|
||
下一步建议直接进入“阶段 1 实施设计”，输出更细的开发清单：
|
||
|
||
1. 数据库表结构 SQL
|
||
2. 后端目录和文件改造清单
|
||
3. API 请求和响应示例
|
||
4. 前台 `/claim/:token` 页面状态图
|
||
5. 后台 `/admin` 页面结构与接口契约
|
||
6. 任务状态机枚举定义
|
||
|
||
如果继续推进，我建议下一步先把：
|
||
|
||
- 表结构
|
||
- 后端 API 草案
|
||
- 前端 `/claim/:token` 页面接口契约
|
||
- 后台 `/admin` 核心接口契约
|
||
|
||
这三部分先定死，然后再开始编码。
|