# API 对比与修复方案

## 概览统计
- v1 控制器: adminapi 81、api 24、core 4、boot 4、ai 2、src 1、apps 1（合计 113）
- v1 接口: adminapi 552、api 108、core 9、boot 8、ai 8、src 4、apps 3（合计 692）
- Java 控制器: adminapi 122、api 45（合计 167）
- Java 接口: adminapi 850、api 200（合计 1050）
- 分布一致性：两侧以 `/adminapi` 为主、`/api` 次之；方法分布均以 `GET` 为主，`POST/PUT` 次之，`DELETE` 较少，无 `PATCH`

## 模块覆盖明细（v1 vs Java）
- sys（api）
  - v1: `sys-config.controller.ts` 5、`sys-verify.controller.ts` 6、`upload.controller.ts` 4、`captcha.controller.ts` 1
  - Java: `SysConfigController.java` 7、`SysVerifyController.java` 6、`UploadController.java` 4、`CaptchaController.java` 1
- wechat（api）
  - v1: `wechat.controller.ts` 9
  - Java: `WechatController.java` 9
- weapp（api）
  - v1: `weapp.controller.ts` 6
  - Java: `WeappController.java` 7
- pay（api）
  - v1: `pay.controller.ts` 4
  - Java: `PayController.java` 4
- member（api）
  - v1: `member.controller.ts` 9、`member-cash-out.controller.ts` 13、`member-account.controller.ts` 8、`member-address.controller.ts` 5、`member-sign.controller.ts` 6
  - Java: `MemberController.java` 9、`MemberCashOutController.java` 13、`MemberAccountController.java` 8、`MemberAddressController.java` 5、`MemberSignController.java` 6
- login（api）
  - v1: `login.controller.ts` 7、`register.controller.ts` 3
  - Java: `LoginController.java` 7、`RegisterController.java` 2
- diy（api）
  - v1: `diy-form.controller.ts` 6、`diy.controller.ts` 4
  - Java: `DiyFormController.java` 6、`DiyController.java` 4
- channel（api）
  - v1: `channel/app.controller.ts` 2
  - Java: `channel/AppController.java` 2
- agreement（api）
  - v1: `agreement.controller.ts` 1
  - Java: `AgreementController.java` 1
- addon（api）
  - v1: `addon.controller.ts` 1
  - Java: `AddonController.java` 1
- adminapi（样本）
  - v1: `sys-*` 合计 19（如 `sys-config.controller.ts:19`）、`member-*` 合计 19、`site-*` 合计 18、`notice-*` 合计 27、`diy-*` 合计 24、`niucloud-*` 合计 13、`pay-*` 合计 8、`login-*` 合计 4
  - Java: 对应 `sys/*` 19、`member/*` 19、`site/*` 18、`notice/*` 27、`diy/*` 24、`niucloud/*` 13、`pay/*` 8、`login/*` 2

## 模块差异与证据（按域）
- sys（api）
  - 证据（v1）：
    - `wwjcloud/libs/wwjcloud-core/src/controllers/api/sys/sys-config.controller.ts:50,60,70,80,90` — 五个 GET 路由已对齐 Java
    - `wwjcloud/libs/wwjcloud-core/src/controllers/api/sys/sys-verify.controller.ts:35,45,55,69,77,85` — 六个路由已对齐（含 POST `verify/{code}`）
    - `wwjcloud/libs/wwjcloud-core/src/controllers/api/sys/upload.controller.ts:47,61,75,86` — 四个 POST 路由已对齐
    - `wwjcloud/libs/wwjcloud-core/src/controllers/api/sys/captcha.controller.ts:35` — `GET /api/captcha` 对齐
  - 证据（Java）：
    - `niucloud-java/niucloud-core/src/main/java/com/niu/core/controller/api/sys/SysConfigController.java:64,75,86,96,107,140` — 六个 GET；v1 缺 `member_mobile_exist`
    - `niucloud-java/niucloud-core/src/main/java/com/niu/core/controller/api/sys/SysVerifyController.java:25,36,48,59,72,85` — 六个路由对齐
    - `niucloud-java/niucloud-core/src/main/java/com/niu/core/controller/api/sys/UploadController.java:24,31,38,47` — 四个 POST 对齐
    - `niucloud-java/niucloud-core/src/main/java/com/niu/core/controller/api/sys/CaptchaController.java:13-15` — `GET /api/captcha` 对齐
  - 差异：缺失 `GET /api/member_mobile_exist`；`verify_detail` 参数名 `{code}` vs `:id`

- wechat（api）
  - 证据（v1）：`wwjcloud/libs/wwjcloud-core/src/controllers/api/wechat/wechat.controller.ts:30,41,49,59,67,75,83,91,99`
  - 证据（Java）：`niucloud-java/niucloud-core/src/main/java/com/niu/core/controller/api/wechat/WechatController.java:38,48,60,69,78,87,98,107,116`
  - 差异：`GET /api/wechat/user` 返回结构需按 Java 包装为 `{ data: '<json-string>' }`

- weapp（api）
  - 证据（v1）：`wwjcloud/libs/wwjcloud-core/src/controllers/api/weapp/weapp.controller.ts:38,50,62,74,86,98`
  - 证据（Java）：`niucloud-java/niucloud-core/src/main/java/com/niu/core/controller/api/weapp/WeappController.java:28,37,46,56,65,75`
  - 差异：`getMsgJumpPath` 的查询参数名 `out_trade_no`（Java） vs `outTradeNo`（v1）

- pay（api）
  - 证据（v1）：`wwjcloud/libs/wwjcloud-core/src/controllers/api/pay/pay.controller.ts:25,34-55,56-68,70-84`
  - 证据（Java）：`niucloud-java/niucloud-core/src/main/java/com/niu/core/controller/api/pay/PayController.java:31-34,47-57,64-67,69-72`
  - 差异：无（路径与方法一致）

- member（api）
  - 证据（v1）：`member-cash-out.controller.ts:44,62,73,83,93,102,112,125,140,153,165,174,188`（示例）
  - 证据（Java）：`MemberCashOutController.java:33-36,43-48,55-59,66-70,77-80,87-93,101-105,112-115,122-127,134-137,144-147,155-159,166-172`
  - 差异：无显著差异（路径与方法一致，返回结构键名部分需逐项核验）

- login（api）
  - 证据（v1）：`login.controller.ts:44,62,86,106,119,146,159`
  - 证据（Java）：`LoginController.java:53-57,65-70,78-83,90-93,100-105,112-116,119-131`
  - 差异：`register.controller.ts` 方法数 v1 为 3，Java 为 2；需核验新增方法来源与必要性

- adminapi/login
  - 证据（v1）：`adminapi/login/login.controller.ts:40,60,73-107,114-122`
  - 证据（Java）：`adminapi/login/LoginController.java:39-43,50-53,56-67`
  - 差异：`tokenInfo` 返回结构差异（`SaResult` vs `{ code,msg,data }`）；方法总数差异（v1:4 vs Java:2）

- 其他 adminapi 模块（样本）
  - sys：`sys-config.controller.ts`（v1 19，Java 19）；`sys-poster.controller.ts`（v1/Java 13）
  - site：`site.controller.ts`（v1/Java 18）；`site-group.controller.ts`（v1/Java 8）
  - notice：`niu-sms.controller.ts`（v1/Java 27）；`notice.controller.ts`（v1/Java 7）
  - diy：`diy-form.controller.ts`（v1/Java 24）；`diy.controller.ts`（v1/Java 17）
  - niucloud：`cloud.module.controller.ts`（v1/Java 8）；`module.controller.ts`（v1/Java 5）
  - pay：`pay.controller.ts`（v1/Java 8）
  - 证据来源：方法装饰器计数基于源码检索（已在“总体规模”与“分布统计”中给出），可按需继续展开到每个具体路由的 `file:line`

## 问题分类
- 缺失接口
  - v1 缺少 `GET /api/member_mobile_exist`（Java 已实现）
- 路径参数不一致
  - `GET /api/verify_detail/{code}`（Java） vs `GET /api/verify_detail/:id`（v1）
- 业务实现不一致
  - `POST /api/verify/{code}`：Java 为核销执行；v1 目前调用校验逻辑而非核销执行
- 方法数量轻微差异（需逐路由核验）
  - 管理端 login 控制器：v1 方法数 4；Java 方法数 2（可能包含额外路由或组合）
 - 响应结构不一致（新增）
   - `GET /api/wechat/user`：Java 返回 `{ data: '<json-string>' }`；v1 直接返回对象（需按 Java 包装为字符串字段）
   - `GET /adminapi/login/tokenInfo`：Java 返回 `SaResult.data(SaTokenInfo)`；v1 返回 `{ code,msg,data }` 结构（需按项目统一策略确认是否对齐 SaResult 形态）

## 证据与代码定位
- 缺失接口
  - Java `niucloud-java/niucloud-core/src/main/java/com/niu/core/controller/api/sys/SysConfigController.java:140` — `GET /api/member_mobile_exist`
  - v1 `wwjcloud-nest-v1/wwjcloud/libs/wwjcloud-core/src/controllers/api/sys/sys-config.controller.ts` — 未见对应方法
- 路径参数不一致
  - Java `niucloud-java/niucloud-core/src/main/java/com/niu/core/controller/api/sys/SysVerifyController.java:59` — `GET /api/verify_detail/{code}`
  - v1 `wwjcloud-nest-v1/wwjcloud/libs/wwjcloud-core/src/controllers/api/sys/sys-verify.controller.ts:69` — `GET /api/verify_detail/:id`
- 业务实现不一致
  - Java `niucloud-java/niucloud-core/src/main/java/com/niu/core/controller/api/sys/SysVerifyController.java:85-93` — `POST /api/verify/{code}` 调用 `verifyCode`
  - v1 `wwjcloud-nest-v1/wwjcloud/libs/wwjcloud-core/src/controllers/api/sys/sys-verify.controller.ts:85-93` — 当前调用 `checkVerifier`
- 方法数量差异（样本）
  - v1 `wwjcloud-nest-v1/wwjcloud/libs/wwjcloud-core/src/controllers/adminapi/login/login.controller.ts` — 方法装饰器计数 4
  - Java `niucloud-java/niucloud-core/src/main/java/com/niu/core/controller/adminapi/login/LoginController.java` — 方法计数 2
- 响应结构不一致（证据）
  - v1 `wwjcloud-nest-v1/wwjcloud/libs/wwjcloud-core/src/controllers/api/wechat/wechat.controller.ts:41-47` — 直接返回 service 数据对象
  - Java `niucloud-java/niucloud-core/src/main/java/com/niu/core/controller/api/wechat/WechatController.java:48-53` — 返回 `Map<String,String>{ data: '<json-string>' }`
  - v1 `wwjcloud-nest-v1/wwjcloud/libs/wwjcloud-core/src/controllers/adminapi/login/login.controller.ts:73-107` — 返回 `{ code,msg,data }`
  - Java `niucloud-java/niucloud-core/src/main/java/com/niu/core/controller/adminapi/login/LoginController.java:56-59` — 返回 `SaResult.data(StpUtil.getTokenInfo())`
- 参数命名不一致（证据）
  - Weapp 消息跳转路径：
    - v1 `wwjcloud-nest-v1/wwjcloud/libs/wwjcloud-core/src/controllers/api/weapp/weapp.controller.ts:98-105` — `@Get('getMsgJumpPath') @Query('outTradeNo')`
    - Java `niucloud-java/niucloud-core/src/main/java/com/niu/core/controller/api/weapp/WeappController.java:75-77` — `@GetMapping('/getMsgJumpPath') @RequestParam('out_trade_no')`

## 修复方案清单
- 缺失接口：补齐 `GET /api/member_mobile_exist`
  - 路由定义：`@Controller('/api') @Get('member_mobile_exist')`
  - 输入：`openid`（Query），`Channel`（Header，默认 `h5`）；对齐 Java 逻辑
  - 位置：`wwjcloud-nest-v1/wwjcloud/libs/wwjcloud-core/src/controllers/api/sys/sys-config.controller.ts`
  - 验收：返回键包含 `member_mobile_exist` 与 `member_exist`
- 路径参数一致化：`verify_detail`
  - 将 v1 路由从 `@Get('verify_detail/:id')` 改为 `@Get('verify_detail/:code')`
  - DTO/Param：统一使用 `code` 字段绑定与传递
  - 位置：`wwjcloud-nest-v1/wwjcloud/libs/wwjcloud-core/src/controllers/api/sys/sys-verify.controller.ts:69`
  - 验收：`GET /api/verify_detail/{code}` 返回明细正确，参数名与 Java 一致
- 业务实现一致化：`POST /api/verify/{code}`
  - 将 v1 方法体从 `checkVerifier` 调用改为 `verifyCode` 调用
  - 位置：`wwjcloud-nest-v1/wwjcloud/libs/wwjcloud-core/src/controllers/api/sys/sys-verify.controller.ts:85-93`
  - 验收：成功返回 `Result.success()`；失败返回 `Result.fail()`，与 Java 行为一致
- 管理端 login 差异核验
  - 对比 v1 与 Java 的管理端 login 路由明细（含路径、方法、鉴权）
  - 若 v1 存在额外路由需确认其业务来源与必要性；否则按 Java 精简或调整到对应模块
  - 位置：
    - v1 `wwjcloud-nest-v1/wwjcloud/libs/wwjcloud-core/src/controllers/adminapi/login/login.controller.ts`
    - Java `niucloud-java/niucloud-core/src/main/java/com/niu/core/controller/adminapi/login/LoginController.java`
- 响应结构一致化（新增）
  - `GET /api/wechat/user`：按 Java 将 service 返回对象序列化为 JSON 字符串并包装到 `{ data: string }`
  - `GET /adminapi/login/tokenInfo`：与团队达成统一策略后，对齐至 `SaResult.data(...)` 等效形态或保持 `{ code,msg,data }` 并在映射工具中设置例外规则
- 参数命名一致化（新增）
  - `GET /api/weapp/getMsgJumpPath`：将 v1 的 `outTradeNo` 统一为 `out_trade_no`（Query 参数名），保持服务层入参兼容；或在服务层做参数别名映射以不破坏现有前端

## 执行步骤（建议）
- 步骤 1：新增 `member_mobile_exist` 方法于 `sys-config.controller.ts`，对齐 Java 入参与服务层返回结构
- 步骤 2：统一 `verify_detail` 路由参数名为 `code`，更新 DTO/Param 绑定与服务层入参
- 步骤 3：修正 `POST /api/verify/{code}` 为 `verifyCode` 业务调用，按结果返回 success/fail
- 步骤 4：核验管理端 login 路由，清单化差异并修复（必要时迁移或删除冗余）
- 步骤 5：运行映射检查与 e2e 路由校验（含返回结构键名与 HTTP 方法）

## 验收标准
- 路由一致性：路径、HTTP 方法、参数名完全与 Java 一致
- 返回结构：键名与层级对齐（例如 `member_exist`、`member_mobile_exist`）
- 业务语义：`verifyCode` 实际执行核销流程；`verify_detail` 正确按 `code` 查询
- 安全一致：`/adminapi` 使用统一守卫（如 Jwt/Roles），`/api` 按实际要求应用公开或鉴权
- 检查通过：`auto-mapping-checker.js` 映射检查零差异；e2e 覆盖关键路径全部通过

## 全量证据索引
- 生成的路由全量报告（不做任何推断）：
  - `docs/routes-full-report.md` — 摘要与前 50 的示例列表
  - `docs/routes-full-report.json` — 完整的 Nest/Java 路由列表与差异数组，含 `file:line`
  - `docs/routes-modules-report.md` — 按模块聚合的差异统计与样例证据
  - `docs/routes-modules-report.json` — 模块字典，包含各模块的 nest/java 路由数与缺失计数

## 模块修复优先级（依据 routes-modules-report.md）
- `adminapi/goods` — 差异计数最高（缺失于 v1: 122）；证据示例：`webroot/addon/shop/java/.../AttrController.java:27`
- `adminapi/marketing` — 次高（缺失于 v1: 68）；证据示例：`.../marketing/CouponController.java:28`
- `adminapi/delivery` — 高（缺失于 v1: 52）；证据示例：`.../delivery/CompanyController.java:22`
- `adminapi/member` — 高（缺失于 v1: 28，缺失于 java: 21）；证据示例：`.../MemberAccountController.java:25`
- `adminapi/notice` — 高（缺失于 v1: 26，缺失于 java: 23）；证据示例：`.../NiuSmsController.java:19`
- `adminapi/addon` — 高（缺失于 v1: 24，缺失于 java: 19）；证据示例：`.../AddonController.java:124`
- `adminapi/order`、`api/goods`、`api/marketing`、`api/order`、`api/refund` — 与前端强相关，建议同步推进；详见 `routes-modules-report.md`

## 批次修复计划
- 批次一（前端使用密集）：`adminapi/dict`、`adminapi/channel`、`adminapi/member`
- 批次二（商城域）：`adminapi/goods`、`adminapi/marketing`、`adminapi/delivery`、`api/goods`、`api/order`、`api/refund`
- 每批次完成后：更新 `routes-full-report.{json,md}`、`routes-modules-report.{json,md}`，并在本文件标记模块“已消除”与证据 `file:line`

## AI 修复任务指令（逐项可执行）
- 任务 A：补齐 `GET /api/member_mobile_exist`（已修复）
  - 证据：Java `niucloud-java/niucloud-core/src/main/java/com/niu/core/controller/api/sys/SysConfigController.java:140`
  - 位置：v1 `wwjcloud-nest-v1/wwjcloud/libs/wwjcloud-core/src/controllers/api/sys/sys-config.controller.ts`
  - 行为：新增 `@Get('member_mobile_exist')`，读取 `openid`（Query）与 `Channel`（Header，默认 `h5`），调用对应服务方法并返回包含 `member_exist`、`member_mobile_exist`

- 任务 B：统一 `verify_detail` 路径参数名（已修复）
  - 证据：Java `SysVerifyController.java:59` 使用 `{code}`；v1 `sys-verify.controller.ts:69` 使用 `:id`
  - 位置：v1 `wwjcloud-nest-v1/wwjcloud/libs/wwjcloud-core/src/controllers/api/sys/sys-verify.controller.ts`
  - 行为：将路由改为 `@Get('verify_detail/:code')`，DTO/Param 绑定字段统一为 `code`

- 任务 C：修正 `POST /api/verify/{code}` 的业务实现（已修复）
  - 证据：Java `SysVerifyController.java:85-93` 调用 `verifyCode`；v1 `sys-verify.controller.ts:85-93` 当前调用 `checkVerifier`
  - 位置：v1 `wwjcloud-nest-v1/wwjcloud/libs/wwjcloud-core/src/controllers/api/sys/sys-verify.controller.ts`
  - 行为：方法体改为调用核销执行服务 `verifyCode`，按结果返回 `Result.success()` 或 `Result.fail()`

- 任务 D：对齐 `GET /api/wechat/user` 的返回结构（已修复）
  - 证据：Java `WechatController.java:48-53` 返回 `{ data: '<json-string>' }`；v1 `wechat.controller.ts:41-47` 返回对象本身
  - 位置：v1 `wwjcloud-nest-v1/wwjcloud/libs/wwjcloud-core/src/controllers/api/wechat/wechat.controller.ts`
  - 行为：将 service 返回对象序列化为 JSON 字符串并包装到 `{ data: string }`

- 任务 E：对齐 `GET /api/weapp/getMsgJumpPath` 的参数名（已修复）
  - 证据：Java `WeappController.java:75-77` 使用 `out_trade_no`；v1 `weapp.controller.ts:98-105` 使用 `outTradeNo`
  - 位置：v1 `wwjcloud-nest-v1/wwjcloud/libs/wwjcloud-core/src/controllers/api/weapp/weapp.controller.ts`
  - 行为：Query 参数名改为 `out_trade_no`，或在服务层增加参数别名映射以兼容现有前端

- 任务 F：管理端 `tokenInfo` 返回结构统一（需团队确认）
  - 证据：Java `adminapi/login/LoginController.java:56-59` 使用 `SaResult.data(...)`；v1 `adminapi/login/login.controller.ts:73-107` 返回 `{ code,msg,data }`
  - 位置：v1 `wwjcloud-nest-v1/wwjcloud/libs/wwjcloud-core/src/controllers/adminapi/login/login.controller.ts`
  - 行为：按统一策略对齐返回结构；若保持 `{ code,msg,data }`，在映射工具配置例外映射，确保差异不被计为错误


## 影响范围与回归建议
- 受影响模块：`sys-config`、`sys-verify`、`login(adminapi)`
- 回归建议：
  - 新增/变更路由的 4xx/5xx 行为与防抖/限流（如有）
  - 租户隔离（`siteId`/`Channel`）与鉴权策略的一致性
  - 上传/核销等接口在 H5/Weapp 渠道的参数来源与头信息

## 参考文件位置
- v1
  - `wwjcloud-nest-v1/wwjcloud/libs/wwjcloud-core/src/controllers/api/sys/sys-config.controller.ts`
  - `wwjcloud-nest-v1/wwjcloud/libs/wwjcloud-core/src/controllers/api/sys/sys-verify.controller.ts`
  - `wwjcloud-nest-v1/wwjcloud/libs/wwjcloud-core/src/controllers/adminapi/login/login.controller.ts`
- Java
  - `niucloud-java/niucloud-core/src/main/java/com/niu/core/controller/api/sys/SysConfigController.java`
  - `niucloud-java/niucloud-core/src/main/java/com/niu/core/controller/api/sys/SysVerifyController.java`
  - `niucloud-java/niucloud-core/src/main/java/com/niu/core/controller/adminapi/login/LoginController.java`