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