huang
d9de704d73
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 49s
2.0 KiB
2.0 KiB
API 文档完整性规范
MODIFIED Requirements
Requirement: OpenAPI 文档 100% 覆盖所有路由接口
系统的 OpenAPI 文档应包含所有已注册的 HTTP 路由接口，覆盖率达到 100%。
Scenario: 文档注册所有 Handler
- WHEN 系统启动或生成 OpenAPI 文档
- THEN
cmd/api/docs.go中的bootstrap.Handlers结构体包含全部 48 个 Handler（包括 Account、AdminOrder、AgentRecharge、Asset、AssetWallet 等） - THEN 每个 Handler 对应一个已注册的路由组（如
/api/admin/accounts→handlers.Account） - THEN 生成的 OpenAPI 文档包含这 48 个 Handler 对应的全部接口
Scenario: 新增 Handler 时同步文档生成器
- WHEN 开发者在
internal/router/中新增一个 Handler 并注册到路由 - THEN 开发者必须同时在
cmd/api/docs.go和cmd/gendocs/main.go中的bootstrap.Handlers结构体添加该 Handler 字段 - THEN 若遗漏，代码审查应拒绝合并（检查清单项：新增 Handler 时是否同步更新 docs.go/gendocs/main.go）
Scenario: OpenAPI 文档校验完整性
- WHEN 执行
go run cmd/gendocs/main.go生成 OpenAPI 文档 - THEN 文档应包含所有已注册的接口路由
- THEN 无"缺失文档"的警告或错误信息
Requirement: 文档生成器不遗漏 Handler
文档生成器的 bootstrap.Handlers 结构体应显式列出所有 Handler，避免新增后遗漏。
Scenario: 完整的 Handler 清单
- WHEN 审阅
cmd/api/docs.go的bootstrap.Handlers结构体定义 - THEN 该结构体包含以下字段（至少 48 个，按模块分组）：
Account *admin.AccountHandler AdminOrder *admin.OrderHandler AgentRecharge *agent.RechargeHandler Asset *admin.AssetHandler AssetWallet *admin.AssetWalletHandler Authorization *admin.AuthorizationHandler // ... 共 48 个 - THEN 注释中标注每个 Handler 对应的路由前缀和功能模块