yml/order_site
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
4c395103a98c86c0939c6f860008db788e4b8fae
order_site/docs/backend-refactor-status.md
T
yml 4c395103a9 彻底重构-4
2026-04-09 15:51:24 +08:00

9.7 KiB
Raw Blame History

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

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

Reference in New Issue View Git Blame Copy Permalink