增加91卡券订单示例

前后端现状分析.md

@@ -2,25 +2,30 @@
 
 ## 当前结论
 
-整体架构方向没有跑偏，后端主干仍然是 `routes -> services -> repositories`，前端也已经逐步从“巨石页面”往“薄页面 + composable + 子组件”推进。
+整体架构方向没有跑偏。
 
-现在最需要继续优化的，不是全项目平均整理，而是两类高风险区域：
+- 后端主干仍然是 `routes -> services -> repositories`
+- 前端后台管理也已经从“单页巨石”逐步转成“薄页面 + composable + 子组件 + 分领域 service”
 
-1. 已经明显长成巨石、后续改动容易连锁的后端运行时模块
-2. 已经完成第一轮拆分、但还需要收口和补测试的前端后台配置模块
+和最初相比，当前最重要的变化有两点：
+
+1. 平台配置这条前后端竖线，第一阶段拆分已经基本完成
+2. 真正还需要优先处理的，已经转向后端运行时巨石模块
+
+所以现在不适合再把精力平均分散到全项目，而应该把已经拆开的区域收口，把还没拆开的大文件优先解决。
 
 ## 已完成
 
-### 平台配置页前端拆分
+### 1. 平台配置页前端拆分
 
 这部分已经不再是最初判断里的“一个页面承载四套完整平台流”。
 
 - `8e1a4be` 拆分前端后台管理 API 客户端
   - `apps/frontend/src/services/admin.ts` 已改成聚合入口
-  - 后台 API 已按领域拆到 `services/admin/` 目录
+  - 后台 API 已按领域拆到 `apps/frontend/src/services/admin/`
 
 - `dff7da7` 拆分平台配置页脚本逻辑
-  - `AdminPlatformShopsView.vue` 的平台状态和行为已经拆到多个 composable
+  - `apps/frontend/src/views/admin/AdminPlatformShopsView.vue` 的平台状态和行为已经拆到 composable
   - 已有：
     - `useAdminAgisoPlatform.ts`
     - `useAdminKhhaoPlatform.ts`
@@ -30,9 +35,7 @@
 - `4650c3e` 抽离平台配置页共享样式
   - 共享样式已统一收口到 `apps/frontend/src/styles/admin-platform-shops.css`
 
-- `60c2d91` 拆分平台配置页 Agiso 与 khhao 区块
-- `254a031` 拆分平台配置页快手核销区块
-- `8f6a72f` 拆分平台配置页履约调试区块
+- `60c2d91`、`254a031`、`8f6a72f` 完成平台区块拆分
   - 四个平台区块已经分别下沉为独立组件：
     - `AdminPlatformAgisoSection.vue`
     - `AdminPlatformKhhaoSection.vue`
@@ -43,134 +46,120 @@
   - 新增 `AdminResultCard.vue`
   - `khhao` / `快手核销` / `cloudtentacles` 的重复结果卡片已统一
 
-### 现阶段对平台配置页的重新判断
+### 2. `session-proof.js` 已完成第一轮拆分
 
-`apps/frontend/src/views/admin/AdminPlatformShopsView.vue` 仍然不算小，但问题性质已经变了：
+这条线已经不是“下一步待开始”，而是已经落地完成。
 
-- 现在主要问题不再是“大模板混杂”
-- 现在的主要问题是：
-  - 父页面 `script setup` 仍然偏胖
-  - 几个子组件之间还有少量可复用片段
-  - 前端缺少测试防线
+当前 `apps/backend/src/services/session/` 下已经拆出：
 
-也就是说，这条线的第一阶段“拆分大页面”已经基本完成，后面不应该继续无限抽象，而应该适时收口。
+- `session-proof-mode.js`
+- `session-proof-paths.js`
+- `session-proof-result-writer.js`
+- `session-proof-beijing-time.js`
+- `session-proof-renderer.js`
+- `session-proof-html.js`
+- `session-proof-constants.js`
+
+`apps/backend/src/services/session/session-proof.js` 现在已经收敛成门面层，文件体量约 `145` 行，风险比之前明显下降。
+
+### 3. 后台平台配置服务已完成按平台拆分
+
+这条线也已经不是最初的 `admin-platform-config-service.js` 巨石形态了。
+
+最近这波提交已经完成：
+
+- `d629bc9` 整理后台平台配置服务目录结构
+- `d11879f` 下沉后台履约规则校验编排逻辑
+- `8c9d487` 下沉后台云触手会话结果组装逻辑
+- `dad646b` 抽离后台平台配置写入归一化逻辑
+- `60b84b2` 下沉后台 khhao 平台辅助组装逻辑
+- `3a7c311` 按平台拆分后台平台配置服务
+
+当前 `apps/backend/src/services/admin/platform-config/` 已形成按职责拆分的目录：
+
+- `service.js`
+  - 只保留统一导出入口
+- `agiso-service.js`
+- `khhao-service.js`
+- `kuaishou-eticket-service.js`
+- `cloudtentacles-service.js`
+- `fulfillment-bindings-service.js`
+- `kuaishou-cloud-fulfillment-service.js`
+- 配套 helper / mapper / validation / test 文件
+
+其中 `service.js` 已经从原来的 600+ 行缩到 53 行，平台配置后端竖线的第一阶段拆分已经完成。
 
 ## 已过时的判断
 
-下面这些结论需要更新，不再按最初版本理解：
+下面这些判断不应该再按旧版本理解。
 
-### `AdminPlatformShopsView.vue` 是前端第一优先级
+### 1. `AdminPlatformShopsView.vue` 是前端第一优先级
 
-这个判断已经部分过时。
+这个判断已经过时。
 
 原因：
 
-- 该页面的四套平台模板已经完成拆分
-- 平台行为已经移动到 composable
-- 剩余问题主要是“收口”和“测试”，不是继续大拆
+- 四个平台模板已经拆开
+- 主要行为已经下沉到 composable
+- 剩余问题更多是收口、少量复用和测试，而不是继续大拆页面
 
 新判断：
 
 - 这条线仍可继续小步优化
-- 但优先级已经低于后端的 `session.js`、`session-proof.js`、`admin-platform-config-service.js`
+- 但优先级已经明显低于后端 `session.js`、`claim-session-service.js`、`admin-write-service.js`
 
-### 继续深挖前端平台配置页
+### 2. `admin-platform-config-service.js` 是后端当前主战场
 
-这个方向不应该再作为主战场。
+这个判断也已经过时。
 
-剩余可做项有，但应该控制强度：
+原因：
 
-- 可以继续抽 `section-title-row` 或 `meta-card` 这一层公共片段
-- 但不能为了统一而统一
-- 再往下更应该转向后端高风险链路
+- 这条线已经迁到 `apps/backend/src/services/admin/platform-config/`
+- 统一入口 `service.js` 已经很薄
+- 大部分公共逻辑也已经拆到 `context.js`、`writes.js`、`validation.js`、`mappers.js`、`fulfillment.js` 等模块
+
+新判断：
+
+- 平台配置后端已经从“继续大拆”阶段，进入“适度收口 + 补测试 + 控制 cloudtentacles 继续膨胀”阶段
+
+### 3. 下一刀应该从 `session-proof.js` 开始
+
+这个判断也已过时。
+
+原因：
+
+- `session-proof.js` 第一轮拆分已经完成
+- 现在更该处理的是仍然明显偏大的运行时主线文件
 
 ## 仍然优先拆分 / 优先优化
 
-### 1. `apps/backend/src/services/session/session.js`
+### 1. `apps/backend/src/services/admin/admin-write-service.js`
 
-后端第一优先级，判断不变。
+这是现在最胖、最值得优先处理的大文件之一，当前约 `1710` 行。
 
-它同时承担：
+它更像“后台万能动作总线”，跨域过多：
 
-- Playwright 浏览器生命周期
-- 会话内存状态
-- 二维码抓取
-- 登录态判断
-- 角色信息同步
-- 兑换执行
-- 截图产物
-- 自动关闭
+- 库存
+- claim
+- webhook
+- cloudtentacles
+- 快手核销
+- 腾讯 session
+- task 手工动作
 
-而且仍然是 `@ts-nocheck`。这类文件每继续增长一次，后面改动成本都会上升。
+建议方向：
 
-建议目标：
+- `admin-inventory-write`
+- `admin-task-actions`
+- `admin-claim-actions`
+- `admin-webhook-actions`
+- `admin-manual-redeem-actions`
 
-- `browser-runtime`
-- `session-store`
-- `session-presentation`
-- `session-redeem-orchestrator`
-- `session-persistence`
+如果继续放大，这类文件会成为后续所有后台动作改动的冲突中心。
 
-### 2. `apps/backend/src/services/session/session-proof.js`
+### 2. `apps/backend/src/services/claim/claim-session-service.js`
 
-这是下一步最合适的切入点。
-
-当前职责混在一起：
-
-- 证明模式判定
-- 产物路径拼接
-- 结果页 DOM 注入
-- 北京时间来源抓取
-- 截图拼接
-- 结果 JSON 落盘
-
-这类文件比 `session.js` 更小，适合作为后端拆分的第一刀，风险更低，能先把拆分节奏跑顺。
-
-建议拆分方向：
-
-- `proof-mode`
-  - 处理 `resolveRedeemProofMode`
-  - 处理 `shouldCaptureBeijingTimeProof`
-
-- `proof-paths`
-  - 处理 `buildArtifactPaths`
-
-- `proof-result-writer`
-  - 处理 `writeRedeemResultFile`
-
-- `proof-beijing-time`
-  - 处理北京时间页面抓取与截图
-
-- `proof-renderer`
-  - 处理结果弹层、合成图、截图表现逻辑
-
-先保留 `session-proof.js` 作为门面导出层，第一阶段不要改公开接口。
-
-### 3. `apps/backend/src/services/admin/admin-platform-config-service.js`
-
-这条线依然偏胖，而且和前端平台配置页是一整条竖线。
-
-虽然前端页面已经拆开，但后端这条 service 仍然同时承载：
-
-- 平台配置读写
-- 登录测试
-- 订单查询
-- SKU 调试
-- 虚拟号调试
-- 履约绑定
-
-建议后续按平台拆为：
-
-- `agiso-admin-service`
-- `khhao-admin-service`
-- `kuaishou-eticket-admin-service`
-- `cloudtentacles-admin-service`
-
-同时把“配置读写”和“调试接口”分层处理。
-
-### 4. `apps/backend/src/services/claim/claim-session-service.js`
-
-仍然是后续重点。
+当前约 `1255` 行，仍然是后端运行时第二优先级。
 
 问题主要在：
 
@@ -184,29 +173,50 @@
 - `claim-task-sync`
 - `claim-fulfillment-finalizer`
 
-### 5. `apps/backend/src/services/admin/admin-write-service.js`
+这条线和下单、兑换、任务状态强相关，越晚拆越难动。
 
-依然偏胖，但优先级略低于上面三项。
+### 3. `apps/backend/src/services/session/session.js`
 
-它更像“后台万能动作总线”，跨域过多：
+当前约 `566` 行，虽然比前两项小，但仍然是高风险运行时核心。
 
-- 库存
-- claim
-- webhook
-- cloudtentacles
-- 快手核销
-- 腾讯 session
+它同时承担：
 
-建议后续至少拆成：
+- Playwright 浏览器生命周期
+- 会话内存状态
+- 二维码抓取
+- 登录态判断
+- 角色信息同步
+- 兑换执行
+- 自动关闭
 
-- `admin-inventory-write`
-- `admin-task-actions`
-- `admin-webhook-actions`
-- `admin-manual-redeem-actions`
+好消息是：`session-proof.js`、`session-qq.js`、`session-wx.js`、`session-redeem.js`、`session-page.js`、`session-state.js` 等子模块已经存在，说明这条线并不是没拆过。
 
-### 6. `apps/backend/src/services/webhook/webhook-service.js`
+当前更合适的目标不是“从零拆分”，而是继续把 `session.js` 剩余的编排职责下沉，最终把它收敛成真正的 orchestrator。
 
-仍然适合改成流水线。
+### 4. 平台配置竖线的收口项
+
+虽然平台配置的大拆分已经完成，但这条线还有一些第二优先级问题：
+
+- `apps/backend/src/services/admin/platform-config/cloudtentacles-service.js`
+  - 当前约 `250` 行
+  - 已经比原来小很多，但仍同时承载登录、会话校验、商品目录、虚拟号调试、完整 flow 调试
+  - 如果后面 cloudtentacles 功能继续增加，可以进一步拆成：
+    - `cloudtentacles-auth-service`
+    - `cloudtentacles-catalog-service`
+    - `cloudtentacles-virtual-number-service`
+
+- `apps/frontend/src/views/admin/AdminPlatformShopsView.vue`
+  - 当前约 `402` 行
+  - 已经不是巨石模板问题，剩下主要是 overview 卡片和页面级加载编排还在父层
+
+- `apps/frontend/src/services/admin/platform-config.ts`
+  - 当前约 `373` 行
+  - 还可以进一步按平台拆成更细的 `services/admin/platform-config/` 子文件
+  - 但这属于可做项，不是最高优先级
+
+### 5. `apps/backend/src/services/webhook/webhook-service.js`
+
+这条线仍然适合改成流水线。
 
 建议拆成：
 
@@ -217,7 +227,9 @@
 - `webhook-process`
 - `webhook-replay`
 
-### 7. `apps/backend/src/config/runtime.js`
+它不是眼下最大的文件，但属于典型“流程很多、分支很多、回归成本高”的区域。
+
+### 6. `apps/backend/src/config/runtime.js`
 
 仍需要“配置声明化”优化。
 
@@ -235,25 +247,26 @@
 
 ## 质量防线现状
 
-这个判断仍然成立，而且重要性上升了。
+这个判断仍然成立，而且现在重要性更高。
 
 当前风险：
 
 - 后端高风险模块仍然存在 `@ts-nocheck`
-- 前端后台配置页最近已经连续多次重构
-- 目前主要依靠 `typecheck + build` 防回归
+- 平台配置页和后台平台配置服务最近连续经历了多轮重构
+- 当前主要还是依赖 `typecheck + test + build` 防回归
 
 这能挡住：
 
 - 类型问题
-- 组件引用问题
-- 构建问题
+- 引用错误
+- 明显的构建错误
+- 一部分纯函数退化
 
-但挡不住：
+但仍挡不住：
 
-- 交互退化
-- 条件渲染错误
-- 任务状态流转异常
+- 页面条件渲染退化
+- 管理台复杂交互异常
+- 任务状态流转串线
 - 外部平台调试链路断裂
 
 建议至少补两层最小防线：
@@ -263,8 +276,8 @@
    - 关键按钮存在性 / 条件渲染测试
 
 2. 后端
-   - `session-proof.js` 纯函数单测
-   - 快手 cloud / claim / task 状态流转的集成 smoke 测试
+   - `claim-session-service.js` 关键状态流转测试
+   - `admin-write-service.js` 高风险动作 smoke 测试
 
 ## 暂时不用急着拆
 
@@ -272,9 +285,9 @@
 
 - `TencentBrowserView.vue`
 - `session-qq.js`
-- 对应 `wx` 变体
+- `session-wx.js`
 
-这些区域当前模式反而比较健康，后续可以作为其它模块拆分时的参照。
+这些区域当前模式相对健康，仍然可以作为其它模块拆分时的参考。
 
 ## 下一步计划
 
@@ -285,55 +298,58 @@
 3. 抽离平台配置页共享样式
 4. 拆分 Agiso / khhao / 快手核销 / cloudtentacles 四个平台区块
 5. 抽离结果信息卡片
+6. 拆分 `session-proof.js`
+7. 重构后台 `platform-config` 目录并完成按平台拆分
 
-### 下一阶段
+### 下一阶段建议
 
-#### Phase 1：从 `session-proof.js` 开始
+#### Phase 1：先处理 `admin-write-service.js`
 
 目标：
 
-- 先拆一个比 `session.js` 更小、更收敛的后端高风险文件
-- 建立后端拆分模板
-- 不改公开接口，不改产物格式，不改调用方
+- 优先拆掉当前最大的后台动作总线
+- 先按职责切片，不改路由公开接口
+- 把高频变更区域从一个文件拆成多个动作模块
 
 建议步骤：
 
-1. 抽纯函数
-   - proof mode
-   - proof path
-   - result writer
+1. 先按动作域分段
+   - inventory
+   - task
+   - claim
+   - webhook
+   - redeem
 
-2. 抽副作用模块
-   - 北京时间截图采集
-   - 证明图合成
+2. 把纯组装和副作用编排分开
 
-3. 保留门面文件
-   - `session-proof.js` 暂时继续导出原接口
+3. 保留 `admin-write-service.js` 作为门面导出层
 
-4. 每个小阶段都跑校验并单独提交
-
-#### Phase 2：再处理 `session.js`
+#### Phase 2：再处理 `claim-session-service.js`
 
 前提：
 
-- `session-proof.js` 拆分完成
-- 对这条运行时链路已经熟悉
+- `admin-write-service.js` 的动作边界更清楚
+- claim / task / inventory 之间的依赖关系已经更容易梳理
 
-#### Phase 3：回到平台配置后端竖线
+#### Phase 3：继续收口 `session.js`
 
-重点转向：
+重点：
 
-- `admin-platform-config-service.js`
-- 相关 route
-- 相关调试接口
+- 不是重写
+- 而是继续把剩余运行时编排下沉到已有 session 子模块
+
+#### Phase 4：补平台配置页与后台动作的最小 smoke 测试
+
+这一步不一定最先做，但应该尽早插入，避免后续继续重构时缺乏防线。
 
 ## 当前建议
 
-前端平台配置页这条线可以暂时收口，不建议再继续大规模抽模板。
+平台配置这条前后端竖线现在可以先收口，不建议继续把它当主战场。
 
-下一步最合适的是：
+更合适的下一步是：
 
-1. 开始拆 `apps/backend/src/services/session/session-proof.js`
-2. 同时补一层最小测试防线
+1. 开始拆 `apps/backend/src/services/admin/admin-write-service.js`
+2. 同步梳理 `claim-session-service.js` 的职责边界
+3. 尽快补一层最小 smoke 测试
 
-如果继续执行，下一刀就从 `session-proof.js` 开始。
+如果继续执行，下一刀最值得从 `admin-write-service.js` 开始。