彻底重构-4

docs/backend-refactor-status.md

@@ -21,7 +21,8 @@
 
 - 新 schema 已经使用 `fulfillment_* / inventory_items / task_inventory_bindings`
 - 核心 service 主链路已经开始直接使用“主 token / 主库存绑定”语义
-- 边角脚本、前端命名和少量后台返回结构仍处于过渡期
+- admin/public 资源名已经切到 `inventory`
+- 剩余工作主要集中在“多库存绑定能力上浮”和“测试/种子数据体系化”
 
 ## 当前真实架构
 
@@ -51,7 +52,7 @@
 
 ### 1. 通用履约模型已经落库
 
-当前迁移文件已经不再围绕旧式单 CDK 模型设计，而是引入了：
+当前迁移文件已经不再围绕旧式单库存码模型设计，而是引入了：
 
 - `fulfillment_profiles`
 - `fulfillment_profile_requirements`
@@ -88,7 +89,7 @@
 - users
 - orders
 - tasks
-- cdks
+- inventory
 - webhook-events
 - platform-config
 
@@ -105,44 +106,144 @@
 
 另外，`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. 新 schema 和部分 service 仍然错位
-
-当前最主要的问题不是“没功能”，而是“新数据模型已经落地，但应用层还没有完全跟上”。
-
-典型现象：
-
-- 前后端接口命名还留着一部分旧 CDK 心智
-- 局部 service 仍需要继续统一 async/await 与新仓库接口写法
-
-### 2. 多凭据任务能力还没有完全上浮到应用层
+### 1. 多凭据任务能力还没有完全上浮到应用层
 
 底层已经支持一个任务绑定多个库存项，但上层展示和操作仍偏向：
 
-- 一个任务只看一个预占 CDK
+- 虽然 admin 任务详情已经开始返回并展示 `inventoryBindings`
+- 任务列表和订单详情已经开始展示绑定摘要计数
+- 但列表操作入口和大部分应用编排仍主要围绕一个主库存项
 - 一个任务只暴露一个领取 token
-- 后台仍以单库存项视角管理任务
+- 后台操作还没有按“绑定集合”粒度设计
 
-### 3. 手动发货 profile 还没有形成完整闭环
+### 2. 测试数据初始化还不够体系化
 
-当前模型和 bootstrap 已有 `manual_dispatch` 方向，但完整的手动履约执行链路还没有完全落到 service、admin 操作和结果回写上。
+虽然已经明确“测试数据可丢弃”，也已经有 PostgreSQL 清库脚本和基础 seed 脚本，但当前场景库仍然偏薄。
 
-### 4. repository 与 admin API 之间仍有一层过渡期命名
+还缺：
 
-虽然内部主链路已经开始使用 `primary_*` 字段，但部分 admin 返回 payload 仍保留 `reservedCdkId / claimTokenId` 这样的旧命名，以避免前端同时大面积改动。
+- `redeeming / redeemed with screenshot / claim token revoked` 等更靠近真实自动化结果的场景
+- 更接近真实订单组合的多任务、多数量、多库存绑定样本
+
+### 3. 任务状态与库存绑定状态仍可进一步解耦
+
+当前虽然已经有 `task_status / delivery_status / inventory_status / task_inventory_bindings` 四套状态，但 admin 视角仍以“任务主状态”为中心：
+
+- 详情页已经开始展示库存绑定集合
+- 任务列表和订单详情已经开始展示绑定摘要
+- 但订单列表、任务操作入口还没有把多库存绑定事件完整展开
+- `manual_dispatch` 与自动领取任务共用的列表状态摘要还比较粗
+- 订单编排层还没有把“多库存、多步骤”履约任务展开成更清晰的应用层对象
 
 ## 现在最该继续做的事
 
-1. 让 admin 层完全对齐新的 `fulfillment_tasks / inventory_items` 语义
-2. 把“单个 reserved CDK”心智继续升级为“任务库存绑定”
-3. 把 `manual_review / manual_dispatch` 从 profile 扩展成完整可执行链路
-4. 补一套基于 PostgreSQL 和新 schema 的清库/种子数据脚本
+1. 把“单个主库存项”心智继续升级为“任务库存绑定集合”
+2. 让 admin 层逐步暴露多库存绑定、多履约步骤的真实状态
+3. 在现有 seed 基础上继续扩充更多任务状态和编排场景
+4. 继续把订单列表和任务操作入口也切到绑定集合视角
 
-当前这件事已经完成一半：
+当前这件事已经继续往前走了一步：
 
 - 旧 SQLite 思路的 `scripts/cleanup-dev-data.js` 已经替换为基于 PostgreSQL 新 schema 的清库脚本
-- 但种子数据脚本还没补，bootstrap 目前主要负责 profile/catalog，不负责完整测试数据生成
+- admin 任务详情已开始暴露并展示 `task_inventory_bindings` 集合
+- admin 任务列表和订单详情已开始消费绑定摘要计数
+- `scripts/seed-dev-data.js` 已扩展到 claim 主流程多状态样本，bootstrap 仍然只负责 profile/catalog，不负责完整业务测试数据生成
 
 ## 文档说明