彻底重构-3
This commit is contained in:
yml
@@ -0,0 +1,154 @@
|
||||
# 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`
|
||||
|
||||
后续请以代码、迁移文件和本状态文档为准。
|
||||
Reference in New Issue
Block a user