kra-new/docs/API_REVIEW.md

当前接口审查（2026-11-04）

范围

以 internal/routecatalog/catalog.go 与实际 Gin 注册为基线：共 252 个接口，其中商务 55 个（包括 4 个找回密码接口），原生框架 197 个。公开接口 15 个，其余 237 个均检查认证入口；分别在空前缀和 /api 前缀下执行未登录请求，共 474 项认证回归。

路由完整性与鉴权检查覆盖全部入口。按领域审查商务查询、权限范围、输入/排序/分页、写入事务、导出和定时任务，以及原生认证、权限、上传、支付、集成配置和审计的公共处理。真实外部支付、短信发送、OA 审批和所有原生管理写操作未在共享测试数据上逐一执行，不能将路由覆盖等同于这些外部流程全量验收。

本轮修复

问题	修改与回归
渠道激活只按商务账号名授权，跨平台同名可能串数据	列表和流水明细均按已通过绑定的“平台＋账号”匹配；测试同名异平台、无绑定、管理员及状态范围
日期只传一端时被忽略，统计结果悄悄回到默认区间	商务列表、注册/充值、渠道/游戏统计、区服分析及排行榜统一拒绝不完整/非法/倒置范围；合法默认与单日保留
审计写入无 deadline，数据库异常可能拖住退出	每批写入限时 2 秒，Close 最多等 5 秒；关闭后拒绝入队，测试阻塞写入被取消
证书的 content/path/file 别名未脱敏	配置读回、掩码提交合并与审计共享识别；覆盖内联证书、密钥、PKCS12、嵌套字段和普通 content 字段
支付测试的结构化步骤消息透传适配器原始错误	HTTP 返回安全错误和步骤信息，服务端保留诊断；避免 URL、凭据、SQL 经 data 字段泄露
已有错误弹窗时 401 回调被丢弃	会话失效立即清理并跳转，不依赖弹窗确认；旧请求不覆盖新令牌或注销新会话；真实 Chrome 验证
Swagger 的环境判定与启动日志不同，空环境默认开放	配置统一判定，仅显式 dev/development/test/local 开放；启动地址和路由一致，包含缺省及 qa/uat 测试
媒体分类保存原名会把自身当重复记录	重名检查排除当前 ID，仍拒绝其他同名分类；媒体重命名缺失记录映射领域 NotFound
偏好对比脚本在 HTTP 恢复失败时跳过数据库恢复	双层 finally 确保尝试恢复原行和更新时间

本次提交也包含此前完成但尚未提交的迁移任务、SQL 修正、查询索引、性能优化及页面修复。性能和统计口径见 商务验收。

验证结果与数据漂移

• make generate、go test ./...、go vet ./...、服务构建通过；Wire 由工具重新生成。
• 独立 MySQL 5.7 的 5 组测试通过：预警并发去重、渠道并发创建、注册 CAST 索引、区服时间索引、查询索引幂等及冲突拒绝。
• 前端完整 ESLint 和生产构建通过；构建仍提示大分块及第三方 BigInt 目标兼容告警，没有把告警视为旧浏览器兼容验证。Chrome 实测覆盖另一个错误弹窗已打开时的 401 清理和跳转。
• 新旧真实读取共 75 组：管理员 36，绑定三级 21，专用一级/二级/三级各 6。73 组相等，2 组预警列表因数据快照不同而不等，失败原始报告已保留。
• 漂移核实：sw8 的预警在 2026-11-04 14:00 被更新，当前 480 条；sw9 为原快照 478 条，其中 55 个同 ID 记录的时间已不同。本机旧服务配置仍关闭调度，未从其日志确认更新来源；没有覆盖、删除或回写 sw8 的新记录。
• 使用之前保存的同参数 sw8 快照重新核对当前 sw9 的完整预警列表，通过；报告明确 source_capture_reused=true。这证明当前列表符合该快照，不代表两库当前内容相等。
• 新版已启动在日常 8000；8 组工作台、排行榜、激活第二页、偏好和任务注册结果与验证实例一致。

本轮原始报告位于仓库外 D:/Users/Yvan/backups/sw9/20261104_rehearsal/review_20261104/。此前完整写入/导出/重建及恢复证据见 历史综合索引。本机无可用 CGO 编译环境，未运行 -race，不宣称竞态检测通过。

保留的框架风险与验证边界

旧审查材料中尚未消除的内容移到这里，避免删除历史文档时丢失问题。它们不属于“已修复”清单：

范围	当前边界
媒体并发	删除只有进程内互斥，秒传复用创建与删除缺少统一的跨实例引用锁；长时间合并仍受陈旧会话清理宽限影响，需要独立并发/故障方案
配置保存	storage、email 和配置文件分步持久化，中途失败可能形成部分成功；尚无跨存储的原子提交/补偿流程
历史支付订单	请求指纹严格匹配；缺少旧指纹样本的幂等重放验证，不直接放宽金额、业务身份的冲突检查
错误协议	框架仍有裸错误与字符串拼接、响应净化规则；此次堵住支付测试 data 泄露，但未统一全框架 typed error 协议
认证与前端路由	token 仍由既有 localStorage 方案保存，登录与守卫仍各有动态路由注册；改成仅 HttpOnly cookie 或统一注册需要独立兼容设计
调度启动	永久非法 cron 会保持旧计划并继续启动重试；数据库读失败不清空既有计划，但固定重试间隔仍可改成有界退避
审计可读性	一些通用 key/序列号字段仍被旧脱敏策略掩盖；未为恢复可读性而放宽密钥保护

文档与脚本清理

首次清理将 104 份阶段报告、重复 JSON、旧目录审查和独立菜单 SQL，以及 26 个旧脚本移出项目。用户追加要求后，剩余 14 个验证工具、脚本说明和 Python 缓存也全部移出，scripts 目录已删除。所有移除文件均在仓库外归档并校验 SHA-256；统一迁移 SQL、业务口径与综合验收索引保留。

真实本地配置 configs/config.yaml、私有运行数据，以及其他会话的 V2 估算和 outputs 成果不纳入本次提交。未推送远端。