order_site/docs/backend-refactor-status.md

# Backend Refactor Status

最后更新：2026-04-09（已切换到“测试数据可丢弃，不做历史迁移兼容”前提）

## 当前结论

后端正在从“单一腾讯领取兑换工具”迁移到“通用订单履约系统”。

当前代码已经完成了下面两件大事：

1. 数据层已经切到 PostgreSQL，并引入了新的通用履约模型。
2. 仓库结构已经分出 `db / repositories / services / routes / frontend / deploy` 等清晰边界。

当前仍处于新旧架构并存阶段，但已经明确采用下面的推进原则：

- 现有数据库数据视为测试数据，可直接清空
- 不再为了旧测试数据保留历史迁移修复逻辑
- 新配置只认当前履约模型，不再从旧映射自动推导

当前主要表现为：

- 新 schema 已经使用 `fulfillment_* / inventory_items / task_inventory_bindings`
- 核心 service 主链路已经开始直接使用“主 token / 主库存绑定”语义
- admin/public 资源名已经切到 `inventory`
- 剩余工作主要集中在“多库存绑定能力上浮”和“测试/种子数据体系化”

## 当前真实架构

从工程实现视角，当前后端可以按 5 层理解：

1. 接口层
   - `src/routes/`
   - 负责接 HTTP 请求、鉴权、组装响应
2. 应用编排层
   - `src/services/order/`
   - `src/services/claim/`
   - `src/services/admin/`
   - 负责订单、任务、库存、领取、后台操作编排
3. 执行能力层
   - `src/services/session/`
   - `src/services/platforms/`
   - 负责浏览器自动化、平台消息发送、OCR 调用
4. 持久化层
   - `src/repositories/`
   - 负责 orders、tasks、inventory、claim_tokens、webhook_events 的读写
5. 基础设施层
   - `src/db/`
   - `src/config/`
   - 负责数据库连接、迁移、运行时配置、bootstrap

## 已完成部分

### 1. 通用履约模型已经落库

当前迁移文件已经不再围绕旧式单库存码模型设计，而是引入了：

- `fulfillment_profiles`
- `fulfillment_profile_requirements`
- `sku_fulfillment_bindings`
- `inventory_items`
- `fulfillment_tasks`
- `task_inventory_bindings`
- `tencent_browser_contexts`
- `message_deliveries`

这说明系统底层已经支持：

- 同一个 SKU 绑定不同履约方式
- 不同 provider / platform / shop 的差异化履约策略
- 一个任务绑定多个库存项
- 不同 `credential_type` 的库存凭据
- 手动发货与腾讯领取兑换并存

### 2. 履约目录 bootstrap 已经具备基础抽象

当前 bootstrap 中已经定义了两个核心 profile：

- `manual_review`
- `tencent_claim_redeem`

说明“手动发货”和“腾讯领取兑换”已经从业务概念上进入统一履约目录，而不是散落在业务代码里。

### 3. Admin 路由已经完成按领域拆分

后台路由不再全部堆在一个文件里，而是按：

- auth
- dashboard
- users
- orders
- tasks
- inventory
- webhook-events
- platform-config

拆成独立模块，便于继续演进。

### 4. 核心任务读写已经开始切回新 schema 语义

当前仓库层已经明确暴露：

- `primary_claim_token_*`
- `primary_inventory_item_*`

应用层也开始改为基于这些字段处理“主领取 token / 主库存绑定”，而不是继续把它们伪装成旧 `claim_token_id / reserved_cdk_id`。

另外，`claimed_at / role_confirmed_at / redeemed_at` 这些任务时间字段现在也已真正通过 repository 落库，不再只是 service 层表面传值。

### 5. 本地 Docker 开发栈已经重新打通

当前开发 Compose 已改为：

- `postgres` 提供开发数据库
- backend 通过 `DATABASE_URL` 连接 PostgreSQL
- 启动时自动执行 migration 与 bootstrap

这轮还顺手修掉了一个启动顺序问题：

- 之前 backend 启动时没有等待 migration 完成，就先执行 fulfillment catalog bootstrap
- 现已改为先 `await runDatabaseMigrations()`，再继续后续初始化

本地验证结果：

- `docker compose -f docker-compose.dev.yml` 可拉起 `postgres / backend / frontend / web`
- `/health` 可正常返回
- admin 登录可用
- `GET /api/v1/admin/tasks` 已能正常鉴权并返回结果

### 6. `manual_dispatch` 已具备完整人工履约闭环

当前 `manual_dispatch` 不再只是把任务停在 `manual_review`，而是已经补齐成新的正式履约路径：

- paid 后的人工履约任务会进入 `manual_review`
- admin 新增 `POST /api/v1/admin/tasks/:taskId/complete-manual-dispatch`
- 支持把人工履约结果明确回写为 `delivered` 或 `failed`
- 结果会写入 `task_status / delivery_status / result_code / result_message / context_json`
- 如果任务绑定了库存凭据，人工完成时也会同步把库存置为 consumed
- `task_events` 已开始记录人工履约完成事件

同时，人工履约任务已经不再允许误走旧自动链路：

- 不再允许对 `manual_dispatch` 执行自动重试
- 不再允许为 `manual_dispatch` 重新生成领取链接
- admin 详情页已补上人工履约回写表单与结果展示

### 7. admin 任务接口开始去除旧 `CDK` 过渡命名

这一轮继续把任务侧接口往新模型对齐：

- 任务释放入口已改为 `release-inventory`
- 任务 action payload 不再返回 `reservedCdkId`
- 主领取 token 字段统一为 `primaryClaimTokenId`
- 前端任务详情/列表不再依赖 `reservedCdkCodeMasked` 和 `cdk` 兼容对象

当前任务管理界面已经优先使用：

- `inventoryItemId`
- `inventory.displayValue`
- `inventory.credentialType`
- `primaryClaimTokenId`

### 8. admin 库存管理域已经切到 `inventory` 资源名

这一轮把库存管理域的外层入口也继续切到新模型：

- 后端 admin API 已从 `/api/v1/admin/cdks` 切到 `/api/v1/admin/inventory`
- 前端后台路由已从 `/admin/cdks` 切到 `/admin/inventory`
- 库存管理页面、导航、审计 action、targetType 已统一改为库存项语义
- 库存列表返回结构已改为 `inventoryItemId / displayValue / credentialType`

现在从 URL、页面和 admin payload 角度，库存域已经不再把资源本身暴露成旧 `cdk` 名称。

### 9. 后端内部 `cdk` 命名主链路已经收口到 `inventory`

这轮已经把后端主链路里的历史命名继续清理掉：

- `repositories/cdk-repo.js` 已收口为 `repositories/inventory-repo.js`
- `services/order/cdk-service.js` 已收口为 `services/order/inventory-service.js`
- admin / claim / delivery 主链路已改用 `getInventoryItemById / reserveInventoryForTask / releaseReservedInventoryItem` 等命名
- 任务错误文案已统一改成“库存项 / 库存凭据”语义

现在 `apps/backend/src` 主干里已经不再保留旧 `cdk-*` 仓储与服务文件名。

### 10. 开发种子数据入口已经补上

这轮已经补上新的开发数据入口，不再只能靠手工 webhook 或临时 SQL 验证：

- 新增 `apps/backend/scripts/seed-dev-data.js`
- 新增 `npm run seed:dev-data`
- 支持 `--apply --reset` 先清库再重建固定场景
- 当前已覆盖：
  - `manual_pending`
  - `manual_completed`
  - `claim_ready`
  - `claim_claimed`
  - `claim_role_confirmed`
  - `claim_retry_pending`
  - `claim_expired`
  - `claim_waiting_inventory`

这意味着后续继续改任务列表、订单详情、履约编排时，已经有一套可重复验证的最小场景。

## 当前未完成部分

### 1. 多凭据任务能力还没有完全上浮到应用层

底层已经支持一个任务绑定多个库存项，但上层展示和操作仍偏向：

- 虽然 admin 任务详情已经开始返回并展示 `inventoryBindings`
- 任务列表和订单详情已经开始展示绑定摘要计数
- 但列表操作入口和大部分应用编排仍主要围绕一个主库存项
- 一个任务只暴露一个领取 token
- 后台操作还没有按“绑定集合”粒度设计

### 2. 测试数据初始化还不够体系化

虽然已经明确“测试数据可丢弃”，也已经有 PostgreSQL 清库脚本和基础 seed 脚本，但当前场景库仍然偏薄。

还缺：

- `redeeming / redeemed with screenshot / claim token revoked` 等更靠近真实自动化结果的场景
- 更接近真实订单组合的多任务、多数量、多库存绑定样本

### 3. 任务状态与库存绑定状态仍可进一步解耦

当前虽然已经有 `task_status / delivery_status / inventory_status / task_inventory_bindings` 四套状态，但 admin 视角仍以“任务主状态”为中心：

- 详情页已经开始展示库存绑定集合
- 任务列表和订单详情已经开始展示绑定摘要
- 但订单列表、任务操作入口还没有把多库存绑定事件完整展开
- `manual_dispatch` 与自动领取任务共用的列表状态摘要还比较粗
- 订单编排层还没有把“多库存、多步骤”履约任务展开成更清晰的应用层对象

## 现在最该继续做的事

1. 把“单个主库存项”心智继续升级为“任务库存绑定集合”
2. 让 admin 层逐步暴露多库存绑定、多履约步骤的真实状态
3. 在现有 seed 基础上继续扩充更多任务状态和编排场景
4. 继续把订单列表和任务操作入口也切到绑定集合视角

当前这件事已经继续往前走了一步：

- 旧 SQLite 思路的 `scripts/cleanup-dev-data.js` 已经替换为基于 PostgreSQL 新 schema 的清库脚本
- admin 任务详情已开始暴露并展示 `task_inventory_bindings` 集合
- admin 任务列表和订单详情已开始消费绑定摘要计数
- `scripts/seed-dev-data.js` 已扩展到 claim 主流程多状态样本，bootstrap 仍然只负责 profile/catalog，不负责完整业务测试数据生成

## 文档说明

以下旧文档已删除，不再作为事实来源：

- `apps/backend/方案A-订单编排与自动兑换设计.md`
- `apps/backend/阶段1-4实施规格说明.md`

后续请以代码、迁移文件和本状态文档为准。