归档

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

@@ -0,0 +1,45 @@
+# 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 个，按模块分组）：
+  ```go
+  Account               *admin.AccountHandler
+  AdminOrder           *admin.OrderHandler
+  AgentRecharge        *agent.RechargeHandler
+  Asset                *admin.AssetHandler
+  AssetWallet          *admin.AssetWalletHandler
+  Authorization        *admin.AuthorizationHandler
+  // ... 共 48 个
+  ```
+- **THEN** 注释中标注每个 Handler 对应的路由前缀和功能模块