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 / 主库存绑定”语义
• 边角脚本、前端命名和少量后台返回结构仍处于过渡期

当前真实架构

从工程实现视角，当前后端可以按 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. 通用履约模型已经落库

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

• 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
• cdks
• 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 层表面传值。

当前未完成部分

1. 新 schema 和部分 service 仍然错位

当前最主要的问题不是“没功能”，而是“新数据模型已经落地，但应用层还没有完全跟上”。

典型现象：

• 前后端接口命名还留着一部分旧 CDK 心智
• 局部 service 仍需要继续统一 async/await 与新仓库接口写法

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

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

• 一个任务只看一个预占 CDK
• 一个任务只暴露一个领取 token
• 后台仍以单库存项视角管理任务

3. 手动发货 profile 还没有形成完整闭环

当前模型和 bootstrap 已有 manual_dispatch 方向，但完整的手动履约执行链路还没有完全落到 service、admin 操作和结果回写上。

4. repository 与 admin API 之间仍有一层过渡期命名

虽然内部主链路已经开始使用 primary_* 字段，但部分 admin 返回 payload 仍保留 reservedCdkId / claimTokenId 这样的旧命名，以避免前端同时大面积改动。

现在最该继续做的事

1. 让 admin 层完全对齐新的 fulfillment_tasks / inventory_items 语义
2. 把“单个 reserved CDK”心智继续升级为“任务库存绑定”
3. 把 manual_review / manual_dispatch 从 profile 扩展成完整可执行链路
4. 补一套基于 PostgreSQL 和新 schema 的清库/种子数据脚本

当前这件事已经完成一半：

• 旧 SQLite 思路的 scripts/cleanup-dev-data.js 已经替换为基于 PostgreSQL 新 schema 的清库脚本
• 但种子数据脚本还没补，bootstrap 目前主要负责 profile/catalog，不负责完整测试数据生成

文档说明

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

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

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