wanwu/wwjcloud-nest-v1
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
wwjcloud-nest-v1/docs/AI-FIX-REPORT.md
wanwu 7ede50739b chore: push latest changes
2025-11-16 22:13:57 +08:00

18 KiB
Raw Permalink Blame History

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
Reference in New Issue View Git Blame Copy Permalink