# 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`

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