junhong_cmp_fiber/openspec/specs/api-doc-coverage/spec.md

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 对应的路由前缀和功能模块