接口规范体检
这些数字解释「为什么新人看不懂」：不是文档写得少，而是接口本身缺少可推断的规律。下面只列事实与建议，不改动任何存量接口。
1664接口总数
97.2%是 POST
76.1%路径含 CRUD 动词
0URL 版本化（/v1）
340源码无注释（名称为推断）
3kebab 与 camel 混用
1. 事实
| HTTP 方法分布 | POST 1617、ANY 28、GET 17、PUT 2 | 97%% 以上是 POST，方法语义基本没用起来 |
| 路径含 CRUD 动词 | 1267 | 新人无法从路径判断这是读还是写 |
| URL 版本化 | 0 | 无 /v1，接口变更无法并存 |
| 同一资源多套读命名 | 22 | getX / queryXList / queryXPage / listX 并存 |
| 源码无 javadoc 注释 | 340 | 接口名称由 操作日志注解 / git 提交说明 / 方法名 推断，页面已标注来源 |
| 调用链来源 | 1660 / 1661 来自源码遍历 | 已不再依赖旧站解析结果 |
| kebab 与 camel 混用 | 3 | 路径风格不统一 |
2. 建议（新增接口生效，不动存量）
- 统一动词语义：同一资源只保留一种读接口命名（建议
queryXxxPage/getXxx）。 - 方法语义：查询类走 GET 或至少保持 POST 一致；导出/下载与写操作区分开。
- 强制摘要：CI 校验「无 javadoc 摘要的 @*Mapping 方法」直接失败，数量从 340 降到 0。
- 错误码：源码常量已入库为错误码字典；剩下要对齐的是管理后台
system_error_code表。 - 包名治理：
xuchao（分销商）、common（模板）、industry、sales、spu/sku、admissionwarning等包名无法表达业务，v2 已用业务域导航替代，建议后续重命名包。
3. 缺摘要清单（前 60，共 340）
| 路径 | 方法 | 控制器 | 域 |
|---|---|---|---|
| /promotion/coupon/couponPage | POST | PromotionCouponController | 营销与触达 |
| /promotion/coupon/getCoupon | POST | PromotionCouponController | 营销与触达 |
| /promotion/coupon/getUnusedCouponCount | POST | PromotionCouponController | 营销与触达 |
| /promotion/coupon/getCouponByGoodsId | POST | PromotionCouponController | 营销与触达 |
| /profitAccounting/cardModel | POST | CardModelProfitAccountingController | 统计与报表 |
| /statistics/statCardArea | POST | HomeStatisticsController | 统计与报表 |
| /statistics/statHomeTest | GET | HomeStatisticsController | 统计与报表 |
| /statistics/statCardStat | POST | CardStatisticsController | 统计与报表 |
| /tickets/getMemberTourist | POST | TicketsMemberTouristController | 门票与景区 |
| /tickets/order/exportTicketsOrderPage | POST | TicketsOrderController | 门票与景区 |
| /tickets/order/getTicketsOrderDetail | POST | TicketsOrderController | 门票与景区 |
| /tickets/order/getTicketsOrderTouristList | POST | TicketsOrderController | 门票与景区 |
| /tickets/order/prepay | POST | TicketsOrderController | 门票与景区 |
| /tickets/order/prepayXgh | POST | TicketsOrderController | 门票与景区 |
| /tickets/order/payNotify | POST | TicketsOrderController | 门票与景区 |
| /tickets/order/refundTicketsOrderXgh | POST | TicketsOrderController | 门票与景区 |
| /tickets/order/refundTicketsOrder | POST | TicketsOrderController | 门票与景区 |
| /tickets/order/refundNotify | POST | TicketsOrderController | 门票与景区 |
| /tickets/exportTicketsCheckPage | POST | TicketsCheckController | 门票与景区 |
| /tickets/queryTicketsShopList | POST | TicketsCheckController | 门票与景区 |
| /tickets/queryTicketsCheck | POST | TicketsCheckController | 门票与景区 |
| /tickets/countTicketsCheckToday | POST | TicketsCheckController | 门票与景区 |
| /tickets/queryTicketsPageBack | POST | TicketsController | 门票与景区 |
| /tickets/getTicketsTypes | POST | TicketsController | 门票与景区 |
| /tickets/getTicketsCities | POST | TicketsController | 门票与景区 |
| /tickets/getTicketsDetail | POST | TicketsController | 门票与景区 |
| /tickets/getSkuDetail | POST | TicketsSkuController | 门票与景区 |
| /cardAppointment/exportCardAppointment | ANY | CardAppointmentController | 旅游卡 |
| /cardAppointment/showCardAppointment | POST | CardAppointmentController | 旅游卡 |
| /cardModel/getCardModelByCardNo | POST | CardModelController | 旅游卡 |
| /cardAssignment/resignCardAssignment | POST | CardAssignmentController | 旅游卡 |
| /card/updateCardActivedZeng | POST | CardController | 旅游卡 |
| /card/queryCardChannelActiveList | POST | CardController | 旅游卡 |
| /card/exportCardChannelActive | ANY | CardController | 旅游卡 |
| /card/getOpenapiChannelInfoList | POST | CardController | 旅游卡 |
| /cardStock/countCardStockRemain | POST | CardStockController | 旅游卡 |
| /hotelApi/queryHotelInfoPage | POST | HotelApiController | 酒店 |
| /hotelApi/getHotelInfo | POST | HotelApiController | 酒店 |
| /hotel/getHotelsList | POST | HotelInfoController | 酒店 |
| /system/area/tree | POST | AreaController | 商户·店铺·基础数据 |
| /system/area/get-by-ip | POST | AreaController | 商户·店铺·基础数据 |
| /sms/smsNotifyAli | POST | SmsCardLogController | 营销与触达 |
| /checker/queryCheckerConsumeRecord | POST | CheckerConsumeRecordController | 核销 |
| /checker/getCheckerListByResourceId | POST | CheckerController | 核销 |
| /checker/version | POST | CheckerController | 核销 |
| /checker/hhQrDecode | POST | CheckerController | 核销 |
| /consumeEnd/getCardModelList | POST | ConsumeEndController | 核销 |
| /consumeEnd/queryCardCheck | POST | ConsumeEndController | 核销 |
| /consumeEnd/countCardCheckByChecker | POST | ConsumeEndController | 核销 |
| /consumeEnd/queryCardAppointment | POST | ConsumeEndController | 核销 |
| /consumeEnd/getTicketsList | POST | ConsumeEndController | 核销 |
| /consumeEnd/queryTicketsCheck | POST | ConsumeEndController | 核销 |
| /consumeEnd/statCardCheck | POST | ConsumeEndController | 核销 |
| /consumeEnd/statCardAppointment | POST | ConsumeEndController | 核销 |
| /consumeEnd/statTicketsCheck | POST | ConsumeEndController | 核销 |
| /shop/getMapAddrSuggestions | POST | ShopController | 商户·店铺·基础数据 |
| /aliyun/face/initFaceVerify | POST | AliyunRealFaceVerifyController | 开放与对接 |
| /aliyun/face/describeFaceVerify | POST | AliyunRealFaceVerifyController | 开放与对接 |
| /ssk/user/token | POST | SSKUserController | 开放与对接 |
| /ssk/user/logon | POST | SSKUserController | 开放与对接 |
4. 源码解析 vs 旧站文档（tools/parse_java.py 实测）
把解析器指向 jxxx-dscp + chaos 源码重算一遍，与旧站 HTML 逐条比对。结论：旧站文档存在漏记、幽灵接口、字段名错误三类硬伤。
| 差异 | 数量 | 说明 |
|---|---|---|
| 接口总数：源码 vs 旧站 | 1664 vs 1646 | 源码解析多出 18 个（含 238 个旧站只给了路径没有契约的条目） |
| 旧站「精简条目」被补全契约 | 238 | 这些接口在旧站只有一行路径，没有参数/响应；现在来自源码 |
| 源码有、旧站漏记 | 18 | 见 4.1 |
| 旧站有、源码没有（幽灵） | 4 | 见 4.2，源码里是 // 注释掉的映射 |
| 分页入参字段名错误 | 241 | pageNum → pageNo，见 4.3 |
| 缺中文摘要 | 340 | 旧站 187 → 真实 340（旧站有 -153 个接口在继承别人的注释，已纠正为无注释+推断名） |
| Body 无法展开的接口 | 16 | 类型在依赖 jar 内或为 Map/基础类型 |
| 必填标错（校验注解其实被注释掉了） | 20 | 旧站读到被注释掉的 //@NotNull(...) 并据此标必填；v2 按源码实际生效情况标注 |
4.1 旧站漏记的接口（源码里有、文档里没有）
| 方法 | 路径 | 摘要 | 控制器 |
|---|---|---|---|
| POST | /statistics/statHomePermission | xuchao: 首页统计可见性查询（不抛错，仅告知前端；无权限时前端隐藏统计区块） | HomeStatisticsController |
| POST | /statistics/statHomeSceneryCheckStat | xuchao: 首页-景区入园统计（人次排行·人均 单表合并分页） | HomeStatisticsController |
| POST | /statistics/statHomeBindTrend | xuchao: 首页-绑卡趋势统计（按日/月/年） | HomeStatisticsController |
| POST | /statistics/statHomeChannelSale | xuchao: 首页-渠道销售四指标统计（售卡数/售卡金额/退款数/退款金额） | HomeStatisticsController |
| POST | /statistics/statHomeCardModelResource | xuchao: 首页-卡种关联资源明细（商户仅自有卡种） | HomeStatisticsController |
| POST | /statistics/statHomeCardModelBind | xuchao: 首页-卡种绑卡数统计（并入销售情况列表展示，商户仅自有卡种） | HomeStatisticsController |
| POST | /statistics/statHomeCardModelOptions | xuchao: 首页卡种下拉（超管全量；发行商户仅自有卡种） | HomeStatisticsController |
| POST | /checker/hhQrDecode | （源码无注释） | CheckerController |
| POST | /aliyun/face/initFaceVerify | （源码无注释） | AliyunRealFaceVerifyController |
| POST | /aliyun/face/describeFaceVerify | （源码无注释） | AliyunRealFaceVerifyController |
| POST | /zhyIcbc/createOrder | （源码无注释） | ZhyIcbcController |
| POST | /zhyIcbc/payNotify | （源码无注释） | ZhyIcbcController |
| POST | /zhyIcbc/refund | （源码无注释） | ZhyIcbcController |
| POST | /zhyIcbc/refundNotify | （源码无注释） | ZhyIcbcController |
| POST | /card/disable | （源码无注释） | OpenApiCardController |
| POST | /cardBag/userCardListXgh | （源码无注释） | CardBagController |
| POST | /cardBag/qrAndUserInfoXgh | （源码无注释） | CardBagController |
| POST | /oss/uploadWithFaceHandle | （源码无注释） | OssController |
4.2 旧站幽灵接口（源码里已注释 / 已删除，文档仍在写）
| 方法 | 路径 | 旧站摘要 |
|---|---|---|
| POST | /tickets/order/refundAppointmentOrder | （无摘要） |
| POST | /tickets/order/appointmentPayNotify | — |
| POST | /tickets/order/appointmentPrepay | — |
| POST | /tickets/order/appointmentRefundNotify | — |
4.3 分页入参字段名错误
旧站对所有分页接口写的是 pageNum，而 AbstractPageRequest 的真实字段是 pageNo（另有 pageSize / orderBy）——受影响接口 241 个。按旧站文档传 pageNum 会被当成未传，走默认第 1 页。
5. 旧站已知缺陷（v2 已修）
| 问题 | 数量 | v2 处理 |
|---|---|---|
| 标「未使用」但前端确有调用 | 45 | 重扫 7 端源码，改为三态 + 证据 + 误判标记 |
| 精简接口链接指向不存在的锚点（死链） | 3 | 为这些接口生成真实条目 |
| index.html 与模块页计数不一致 | 3 处 | 全部数字由 build.py 计算 + check.py 校验 |
| 前端页「未匹配（604）」实际只渲染 61 行 | 1 页 | 重扫并输出全量清单 |
| pro 环境主机指向 uat 却逐卡片展示 | 1405 处 | 收敛到调用手册一处并标注未确认 |
| 枚举渲染出空值 chip | sms 页 14 处 | 抽取阶段丢弃空值 |
| 接口缺少「废弃」表达手段 | 全仓 @Deprecated = 0 | 有标记即自动打「已废弃」徽标 |
| @Route(auth = false) 免鉴权接口 | 430 | 旧站完全没体现；v2 卡片打「免鉴权」标记 |