129 lines
7.1 KiB
Markdown
129 lines
7.1 KiB
Markdown
---
|
||
name: 前后端业务逻辑一致性检查报告
|
||
overview: 全量比对后端 Go 服务（zt-closet-backend）与微信小程序前端（zt-closet-wxmini-frontend）的业务逻辑，逐模块核对接口路径、请求/响应字段、枚举值、状态机、错误码的一致性，最终产出一份差异清单报告（不改任何代码）。
|
||
todos:
|
||
- id: explore-backend
|
||
content: 用 [subagent:code-explorer] 探索后端 dto/service/errcode/constants，提取权威契约清单
|
||
status: completed
|
||
- id: explore-frontend
|
||
content: 用 [subagent:code-explorer] 探索前端 pages/utils/types，提取实际调用契约清单
|
||
status: completed
|
||
- id: compare-core
|
||
content: 对比用户/额度/运势/衣物模块，记录差异与严重程度
|
||
status: completed
|
||
dependencies:
|
||
- explore-backend
|
||
- explore-frontend
|
||
- id: compare-social
|
||
content: 对比穿搭/AI推荐/衣柜分享/收藏点赞/通知模块，记录差异与严重程度
|
||
status: completed
|
||
dependencies:
|
||
- explore-backend
|
||
- explore-frontend
|
||
- id: compare-trade
|
||
content: 对比商品/订单/虚拟支付模块，并全表核对错误码与枚举
|
||
status: completed
|
||
dependencies:
|
||
- explore-backend
|
||
- explore-frontend
|
||
- id: gen-report
|
||
content: 汇总生成《前后端业务逻辑一致性检查报告》
|
||
status: completed
|
||
dependencies:
|
||
- compare-core
|
||
- compare-social
|
||
- compare-trade
|
||
---
|
||
|
||
## 用户需求
|
||
|
||
检查后端业务服务全量代码（`~/zt-closet-backend`），确保前端微信小程序与后端业务逻辑一致。
|
||
|
||
## 已确认的处理方式
|
||
|
||
1. **仅输出不一致报告**：以差异清单形式呈现（接口路径、字段、枚举值、状态机、错误码等），**不修改任何前后端代码**。
|
||
2. **不核对后端《接口文档.md》**：本次只关注「前端代码」与「后端源码」的一致性，以 `/root/zt-closet-backend` 的 Go 源码为权威基准。
|
||
|
||
## 核心产出
|
||
|
||
产出一份《前后端业务逻辑一致性检查报告》，按业务模块（用户 / 额度 / 运势 / 衣物 / 穿搭 / AI 推荐 / 衣柜分享 / 收藏点赞 / 通知 / 商品 / 订单支付）分类，逐项列出：
|
||
|
||
- 不一致位置（前端文件:行 + 后端文件:行）
|
||
- 差异描述
|
||
- 严重程度（阻断 / 高风险 / 低风险 / 建议）
|
||
- 建议修复方向
|
||
|
||
## 技术栈
|
||
|
||
- 后端（权威基准，只读分析）：Go + Gin，位于 `/root/zt-closet-backend`
|
||
- 前端（被检查方，只读分析）：微信小程序原生 + TypeScript，位于 `/root/zt-closet-wxmini-frontend/miniprogram`
|
||
- 比对方法：静态源码契约提取 + 逐模块交叉比对，不涉及运行时
|
||
|
||
## 实现方案
|
||
|
||
### 核心策略
|
||
|
||
采用「契约提取—交叉比对」方法：
|
||
|
||
1. **提取后端权威契约**：以 `internal/routers/router.go` 注册的 42 个接口为主线，通读 `internal/routers/api/v1/`、`internal/dto/`、`internal/service/`、`pkg/errcode/`，提取每个接口的路径、HTTP 方法、请求字段（名称/必填/类型/枚举）、响应字段（名称/类型/单位）、枚举值、状态机规则、错误码。
|
||
2. **提取前端实际契约**：通读 17 个页面 `.ts` 与 `utils/request.ts`、`utils/config.ts`、`utils/auth.ts`、`types/models.ts`、`typings/index.d.ts`，提取实际调用的接口路径、请求体字段名、响应字段名、枚举常量定义、错误码映射表、关键业务规则处理（轮询/幂等/额度回退/惰性过期等）。
|
||
3. **逐模块交叉比对**：后端契约 vs 前端契约，识别字段名不一致、枚举值缺失/错位、错误码遗漏、单位换算缺失、状态机处理缺失等问题。
|
||
|
||
### 比对维度（关键决策）
|
||
|
||
- 接口路径与 HTTP 方法是否一致
|
||
- 请求字段名 / 必填性 / 类型 / 枚举取值是否一致
|
||
- 响应字段名 / 类型 / 单位（金额分、时间秒）是否一致
|
||
- 枚举常量值与状态机定义是否一致
|
||
- 错误码映射表是否完整且值正确
|
||
- 关键业务规则前端是否实现（上传轮询、支付后轮询订单、点赞乐观更新、分享惰性过期、AI 推荐额度不退还提示等）
|
||
|
||
### 严重程度分级
|
||
|
||
- **阻断**：导致功能不可用或数据错误（如字段名错误、请求路径错误、枚举值错位）
|
||
- **高风险**：特定场景下功能出错或体验严重受损（如单位未换算、错误码遗漏导致误提示）
|
||
- **低风险**：边缘场景或文案差异
|
||
- **建议**：非功能性优化建议
|
||
|
||
## 实现要点
|
||
|
||
- **不修改任何代码**，唯一新增物为报告文件 `/root/zt-closet-wxmini-frontend/前后端业务逻辑一致性检查报告.md`。
|
||
- 以后端源码为唯一权威，前端为被检查对象。
|
||
- 重点核对项：
|
||
- 虚拟支付链路：`/order/virtual` + `wx.requestVirtualPayment`，字段 `sign_data`/`pay_sig`/`signature`、`platform` 枚举 `android|ios|harmony|windows`、`mode` 取值，对照后端 `dto/order.go`、`service/virtualpay.go`。
|
||
- 易错字段：主颜色请求字段 `color` vs 响应 `color_main`；通知 `is_read` 1=未读/2=已读；`/like/:targetUUID` 路径参数驼峰；AI 推荐响应字段 `outfit_item`（单数）。
|
||
- 额度与状态机：上传/删除回退规则、公开扣额度、AI 生成失败回退、衣柜分享惰性过期。
|
||
- 错误码全表：前端 `ERROR_MESSAGES` 与后端 `pkg/errcode` 逐项核对，确认缺失与值错误。
|
||
- 疑似缺口：前端未调用 `/ad-reward/grant`（广告激励额度发放）入口，需确认是否属功能缺失。
|
||
|
||
## 目录结构
|
||
|
||
本次任务不修改现有代码，仅新增一份报告文件；以下为报告产出位置与需要通读的源码范围。
|
||
|
||
```
|
||
/root/zt-closet-wxmini-frontend/
|
||
└── 前后端业务逻辑一致性检查报告.md # [NEW] 唯一产出物，按业务模块分类记录差异清单
|
||
|
||
只读分析范围（后端）：
|
||
/root/zt-closet-backend/
|
||
├── internal/routers/router.go # 42 个接口注册主线
|
||
├── internal/routers/api/v1/ # 13 个 handler
|
||
├── internal/dto/ # 14 个请求/响应 DTO
|
||
├── internal/service/ # 18 个业务逻辑（含 virtualpay/constants）
|
||
└── pkg/errcode/ # 10 个错误码文件
|
||
|
||
只读分析范围（前端）：
|
||
/root/zt-closet-wxmini-frontend/miniprogram/
|
||
├── pages/ # 17 个页面 .ts
|
||
├── utils/request.ts / config.ts / auth.ts # 请求封装 / 枚举与错误码 / Token
|
||
├── types/models.ts # 前端实体类型
|
||
└── typings/index.d.ts # 全局类型声明
|
||
```
|
||
|
||
## 推荐使用的 Agent 扩展
|
||
|
||
### SubAgent
|
||
|
||
- **code-explorer**
|
||
- 用途：后端（dto/service/errcode/constants 等 60+ 文件）与前端（17 页面 + utils + types）体量较大，使用该子代理跨目录、多文件并行探索，高效提取接口契约与调用点，避免主上下文被大量源码淹没。
|
||
- 预期结果：产出后端权威契约清单（接口字段/枚举/错误码/状态机）与前端实际调用契约清单（路径/字段/枚举/错误码映射/业务规则处理），作为逐模块比对的输入。 |