order_site/前后端现状分析.md

# 前后端现状分析

## 当前结论

整体架构方向没有跑偏。

- 后端主干仍然是 `routes -> services -> repositories`
- 前端后台管理也已经从“单页巨石”逐步转成“薄页面 + composable + 子组件 + 分领域 service”

和最初相比，当前最重要的变化有两点：

1. 平台配置这条前后端竖线，第一阶段拆分已经基本完成
2. 真正还需要优先处理的，已经转向后端运行时巨石模块

所以现在不适合再把精力平均分散到全项目，而应该把已经拆开的区域收口，把还没拆开的大文件优先解决。

## 已完成

### 1. 平台配置页前端拆分

这部分已经不再是最初判断里的“一个页面承载四套完整平台流”。

- `8e1a4be` 拆分前端后台管理 API 客户端
  - `apps/frontend/src/services/admin.ts` 已改成聚合入口
  - 后台 API 已按领域拆到 `apps/frontend/src/services/admin/`

- `dff7da7` 拆分平台配置页脚本逻辑
  - `apps/frontend/src/views/admin/AdminPlatformShopsView.vue` 的平台状态和行为已经拆到 composable
  - 已有：
    - `useAdminAgisoPlatform.ts`
    - `useAdminNinetyonePlatform.ts`
    - `useAdminKuaishouEticketPlatform.ts`
    - `useAdminCloudtentaclesPlatform.ts`

- `4650c3e` 抽离平台配置页共享样式
  - 共享样式已统一收口到 `apps/frontend/src/styles/admin-platform-shops.css`

- `60c2d91`、`254a031`、`8f6a72f` 完成平台区块拆分
  - 四个平台区块已经分别下沉为独立组件：
    - `AdminPlatformAgisoSection.vue`
    - `AdminPlatformNinetyoneSection.vue`
    - `AdminPlatformKuaishouEticketSection.vue`
    - `AdminPlatformCloudtentaclesSection.vue`

- `58f25fa` 抽离平台配置结果信息卡片
  - 新增 `AdminResultCard.vue`
  - `快手核销` / `cloudtentacles` 的重复结果卡片已统一

### 2. `session-proof.js` 已完成第一轮拆分

这条线已经不是“下一步待开始”，而是已经落地完成。

当前 `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` 抽离后台平台配置写入归一化逻辑
- `3a7c311` 按平台拆分后台平台配置服务

当前 `apps/backend/src/services/admin/platform-config/` 已形成按职责拆分的目录：

- `service.js`
  - 只保留统一导出入口
- `agiso-service.js`
- `ninetyone-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 行，平台配置后端竖线的第一阶段拆分已经完成。

## 已过时的判断

下面这些判断不应该再按旧版本理解。

### 1. `AdminPlatformShopsView.vue` 是前端第一优先级

这个判断已经过时。

原因：

- 四个平台模板已经拆开
- 主要行为已经下沉到 composable
- 剩余问题更多是收口、少量复用和测试，而不是继续大拆页面

新判断：

- 这条线仍可继续小步优化
- 但优先级已经明显低于后端 `session.js`、`claim-session-service.js`、`admin-write-service.js`

### 2. `admin-platform-config-service.js` 是后端当前主战场

这个判断也已经过时。

原因：

- 这条线已经迁到 `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/admin/admin-write-service.js`

这是现在最胖、最值得优先处理的大文件之一，当前约 `1710` 行。

它更像“后台万能动作总线”，跨域过多：

- 库存
- claim
- webhook
- cloudtentacles
- 快手核销
- 腾讯 session
- task 手工动作

建议方向：

- `admin-inventory-write`
- `admin-task-actions`
- `admin-claim-actions`
- `admin-webhook-actions`
- `admin-manual-redeem-actions`

如果继续放大，这类文件会成为后续所有后台动作改动的冲突中心。

### 2. `apps/backend/src/services/claim/claim-session-service.js`

当前约 `1255` 行，仍然是后端运行时第二优先级。

问题主要在：

- 管理态 / 用户态创建逻辑平行复制
- claim token、浏览器会话、任务同步、库存释放、自动发货收尾混在一起

建议方向：

- `claim-context`
- `claim-session-lifecycle`
- `claim-task-sync`
- `claim-fulfillment-finalizer`

这条线和下单、兑换、任务状态强相关，越晚拆越难动。

### 3. `apps/backend/src/services/session/session.js`

当前约 `566` 行，虽然比前两项小，但仍然是高风险运行时核心。

它同时承担：

- Playwright 浏览器生命周期
- 会话内存状态
- 二维码抓取
- 登录态判断
- 角色信息同步
- 兑换执行
- 自动关闭

好消息是：`session-proof.js`、`session-qq.js`、`session-wx.js`、`session-redeem.js`、`session-page.js`、`session-state.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`

这条线仍然适合改成流水线。

建议拆成：

- `webhook-parse`
- `webhook-verify`
- `webhook-ignore-policy`
- `webhook-enrich`
- `webhook-process`
- `webhook-replay`

它不是眼下最大的文件，但属于典型“流程很多、分支很多、回归成本高”的区域。

### 6. `apps/backend/src/config/runtime.js`

仍需要“配置声明化”优化。

目前问题不是功能错，而是长期可维护性差：

- env override 越堆越长
- 新平台配置接入成本越来越高
- 难测、难查、难对照

建议后期改成：

- 配置 schema
- env 映射表
- 默认值与来源声明

## 质量防线现状

这个判断仍然成立，而且现在重要性更高。

当前风险：

- 后端高风险模块仍然存在 `@ts-nocheck`
- 平台配置页和后台平台配置服务最近连续经历了多轮重构
- 当前主要还是依赖 `typecheck + test + build` 防回归

这能挡住：

- 类型问题
- 引用错误
- 明显的构建错误
- 一部分纯函数退化

但仍挡不住：

- 页面条件渲染退化
- 管理台复杂交互异常
- 任务状态流转串线
- 外部平台调试链路断裂

建议至少补两层最小防线：

1. 前端
   - 平台配置页基础渲染 smoke 测试
   - 关键按钮存在性 / 条件渲染测试

2. 后端
   - `claim-session-service.js` 关键状态流转测试
   - `admin-write-service.js` 高风险动作 smoke 测试

## 暂时不用急着拆

### 腾讯浏览器前端链路

- `TencentBrowserView.vue`
- `session-qq.js`
- `session-wx.js`

这些区域当前模式相对健康，仍然可以作为其它模块拆分时的参考。

## 下一步计划

### 已完成阶段

1. 拆分前端后台管理 API 客户端
2. 拆分平台配置页脚本逻辑
3. 抽离平台配置页共享样式
4. 拆分 Agiso / 91卡券 / 快手核销 / cloudtentacles 四个平台区块
5. 抽离结果信息卡片
6. 拆分 `session-proof.js`
7. 重构后台 `platform-config` 目录并完成按平台拆分

### 下一阶段建议

#### Phase 1：先处理 `admin-write-service.js`

目标：

- 优先拆掉当前最大的后台动作总线
- 先按职责切片，不改路由公开接口
- 把高频变更区域从一个文件拆成多个动作模块

建议步骤：

1. 先按动作域分段
   - inventory
   - task
   - claim
   - webhook
   - redeem

2. 把纯组装和副作用编排分开

3. 保留 `admin-write-service.js` 作为门面导出层

#### Phase 2：再处理 `claim-session-service.js`

前提：

- `admin-write-service.js` 的动作边界更清楚
- claim / task / inventory 之间的依赖关系已经更容易梳理

#### Phase 3：继续收口 `session.js`

重点：

- 不是重写
- 而是继续把剩余运行时编排下沉到已有 session 子模块

#### Phase 4：补平台配置页与后台动作的最小 smoke 测试

这一步不一定最先做，但应该尽早插入，避免后续继续重构时缺乏防线。

## 当前建议

平台配置这条前后端竖线现在可以先收口，不建议继续把它当主战场。

更合适的下一步是：

1. 开始拆 `apps/backend/src/services/admin/admin-write-service.js`
2. 同步梳理 `claim-session-service.js` 的职责边界
3. 尽快补一层最小 smoke 测试

如果继续执行，下一刀最值得从 `admin-write-service.js` 开始。