feat: OpenAPI 契约对齐与框架优化
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 5m45s
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 5m45s
主要变更： 1. OpenAPI 文档契约对齐 - 统一错误响应字段名为 msg（非 message） - 规范 envelope 响应结构（code, msg, data, timestamp） - 个人客户路由纳入文档体系（使用 Register 机制） - 新增 BuildDocHandlers() 统一管理 handler 构造 - 确保文档生成的幂等性 2. Service 层错误处理统一 - 全面替换 fmt.Errorf 为 errors.New/Wrap - 统一错误码使用规范 - Handler 层参数校验不泄露底层细节 - 新增错误码验证集成测试 3. 代码质量提升 - 删除未使用的 Task handler 和路由 - 新增代码规范检查脚本（check-service-errors.sh） - 新增注释路径一致性检查（check-comment-paths.sh） - 更新 API 文档生成指南 4. OpenSpec 归档 - 归档 openapi-contract-alignment 变更（63 tasks） - 归档 service-error-unify-core 变更 - 归档 service-error-unify-support 变更 - 归档 code-cleanup-docs-update 变更 - 归档 handler-validation-security 变更 - 同步 delta specs 到主规范文件 影响范围： - pkg/openapi: 新增 handlers.go，优化 generator.go - internal/service/*: 48 个 service 文件错误处理统一 - internal/handler/admin: 优化参数校验错误提示 - internal/routes: 个人客户路由改造，删除 task 路由 - scripts: 新增 3 个代码检查脚本 - docs: 更新 OpenAPI 文档（15750+ 行） - openspec/specs: 同步 3 个主规范文件 破坏性变更：无 向后兼容：是
This commit is contained in:
@@ -0,0 +1,143 @@
|
||||
# OpenAPI Generation - 更新规范
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 错误响应字段名必须为 msg
|
||||
|
||||
OpenAPI 文档中的错误响应 SHALL 使用 `msg` 字段而非 `message`，与真实运行时的 Response 结构体保持一致。
|
||||
|
||||
#### Scenario: 错误响应使用 msg 字段
|
||||
|
||||
- **WHEN** 生成 OpenAPI 文档的错误响应 schema
|
||||
- **THEN** ErrorResponse 包含 `msg` 字段（类型为 string）
|
||||
- **AND** ErrorResponse 不包含 `message` 字段
|
||||
|
||||
#### Scenario: 生成的文档与真实响应一致
|
||||
|
||||
- **WHEN** API 返回错误响应
|
||||
- **THEN** 响应 JSON 包含 `msg` 字段
|
||||
- **AND** OpenAPI 文档中的 schema 定义也使用 `msg` 字段
|
||||
- **AND** 字段名完全匹配
|
||||
|
||||
### Requirement: 成功响应必须包裹在 envelope 中
|
||||
|
||||
所有成功响应 SHALL 包裹在统一的 envelope 结构中：`{code, msg, data, timestamp}`。
|
||||
|
||||
#### Scenario: 成功响应包含 envelope 结构
|
||||
|
||||
- **WHEN** 生成接口的 200 响应 schema
|
||||
- **THEN** 响应 schema 包含以下字段：
|
||||
- `code` (integer, example: 0)
|
||||
- `msg` (string, example: "success")
|
||||
- `data` (原始 DTO schema)
|
||||
- `timestamp` (string, format: date-time)
|
||||
|
||||
#### Scenario: data 字段包含实际的 DTO
|
||||
|
||||
- **WHEN** 接口返回数据（如用户列表、详情）
|
||||
- **THEN** OpenAPI 的 `data` 字段引用实际的 DTO schema
|
||||
- **AND** DTO schema 不被修改（保持原结构）
|
||||
|
||||
#### Scenario: 无返回数据的接口 data 为 null
|
||||
|
||||
- **WHEN** 接口无返回数据（如删除操作）
|
||||
- **THEN** OpenAPI 的 `data` 字段类型为 `null`
|
||||
- **AND** 响应仍包含 `code`、`msg`、`timestamp` 字段
|
||||
|
||||
### Requirement: envelope 包裹适用于所有接口类型
|
||||
|
||||
envelope 包裹 SHALL 适用于普通接口和文件上传接口。
|
||||
|
||||
#### Scenario: 普通接口使用 envelope
|
||||
|
||||
- **WHEN** 通过 `AddOperation` 添加接口
|
||||
- **THEN** 生成的 200 响应包含 envelope 结构
|
||||
|
||||
#### Scenario: 文件上传接口使用 envelope
|
||||
|
||||
- **WHEN** 通过 `AddMultipartOperation` 添加文件上传接口
|
||||
- **THEN** 生成的 200 响应包含 envelope 结构
|
||||
- **AND** envelope 结构与普通接口一致
|
||||
|
||||
### Requirement: 所有 handlers 必须在文档生成器中注册
|
||||
|
||||
文档生成器 SHALL 包含所有已实现的 handlers，确保接口文档完整。
|
||||
|
||||
#### Scenario: handlers 清单完整性
|
||||
|
||||
- **WHEN** 生成 OpenAPI 文档
|
||||
- **THEN** 所有 handler 的接口都出现在文档中
|
||||
- **AND** 不存在已实现但未出现在文档的接口
|
||||
|
||||
#### Scenario: 新增 handler 时同步更新
|
||||
|
||||
- **WHEN** 新增 handler（如 `PersonalCustomer`、`ShopPackageBatchAllocation`）
|
||||
- **THEN** 必须在 `BuildDocHandlers()` 中添加对应的构造代码
|
||||
- **AND** 重新生成文档后接口出现在 OpenAPI 文件中
|
||||
|
||||
### Requirement: handlers 构造函数统一管理
|
||||
|
||||
handlers 的构造逻辑 SHALL 由公共函数 `BuildDocHandlers()` 统一管理，避免重复。
|
||||
|
||||
#### Scenario: cmd/api/docs.go 复用 BuildDocHandlers
|
||||
|
||||
- **WHEN** 在 `cmd/api/docs.go` 中需要构造 handlers
|
||||
- **THEN** 调用 `openapi.BuildDocHandlers()` 获取 handlers
|
||||
- **AND** 不在本文件中重复构造
|
||||
|
||||
#### Scenario: cmd/gendocs/main.go 复用 BuildDocHandlers
|
||||
|
||||
- **WHEN** 在 `cmd/gendocs/main.go` 中需要构造 handlers
|
||||
- **THEN** 调用 `openapi.BuildDocHandlers()` 获取 handlers
|
||||
- **AND** 不在本文件中重复构造
|
||||
|
||||
#### Scenario: BuildDocHandlers 传入 nil 依赖
|
||||
|
||||
- **WHEN** `BuildDocHandlers()` 构造 handlers
|
||||
- **THEN** 所有 handler 构造函数的依赖参数传入 `nil`
|
||||
- **AND** 因为文档生成不执行 handler 逻辑，nil 依赖不会导致运行时错误
|
||||
|
||||
### Requirement: 个人客户路由必须使用 Register 机制
|
||||
|
||||
个人客户 API (`/api/c/v1`) SHALL 使用 `Register(...)` 机制注册，纳入 OpenAPI 文档体系。
|
||||
|
||||
#### Scenario: RegisterPersonalRoutes 使用 Register 机制
|
||||
|
||||
- **WHEN** 调用 `RegisterPersonalRoutes` 注册个人客户路由
|
||||
- **THEN** 使用 `doc.Register(RouteSpec{...})` 注册每个路由
|
||||
- **AND** 不直接调用 Fiber 的 `app.Get/Post` 方法
|
||||
|
||||
#### Scenario: 个人客户路由出现在文档中
|
||||
|
||||
- **WHEN** 生成 OpenAPI 文档
|
||||
- **THEN** 文档包含 `/api/c/v1` 路径的接口
|
||||
- **AND** 每个接口包含正确的 Summary、Tags、Auth 信息
|
||||
|
||||
#### Scenario: 个人客户路由的元数据完整
|
||||
|
||||
- **WHEN** 注册个人客户路由
|
||||
- **THEN** 每个 RouteSpec 包含：
|
||||
- Method（GET/POST/PUT/DELETE）
|
||||
- Path（完整路径）
|
||||
- Handler（fiber.Handler）
|
||||
- Summary（中文摘要）
|
||||
- Tags（包含 "个人客户"）
|
||||
- Auth（true/false）
|
||||
- Input（请求 DTO 或 nil）
|
||||
- Output（响应 DTO）
|
||||
|
||||
### Requirement: 文档生成的幂等性
|
||||
|
||||
文档生成 SHALL 是幂等的，相同的代码生成相同的文档。
|
||||
|
||||
#### Scenario: 重复生成文档内容一致
|
||||
|
||||
- **WHEN** 多次运行 `go run cmd/gendocs/main.go`
|
||||
- **THEN** 生成的 `openapi.yaml` 内容完全一致
|
||||
- **AND** 文件 hash 值相同（除 timestamp 等动态字段外）
|
||||
|
||||
#### Scenario: 代码未变更时文档不变
|
||||
|
||||
- **WHEN** 代码（handlers、路由、DTO）未变更
|
||||
- **THEN** 重新生成的文档与之前的文档一致
|
||||
- **AND** 不会因为生成逻辑的随机性导致差异
|
||||
@@ -0,0 +1,137 @@
|
||||
# Personal Customer - 更新规范
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 个人客户路由必须纳入文档体系
|
||||
|
||||
个人客户 API 路由注册 SHALL 使用 `Register(...)` 机制，与其他路由（admin、h5）保持一致。
|
||||
|
||||
#### Scenario: RegisterPersonalRoutes 函数签名变更
|
||||
|
||||
- **WHEN** 定义 `RegisterPersonalRoutes` 函数
|
||||
- **THEN** 函数签名为：
|
||||
```go
|
||||
func RegisterPersonalRoutes(doc *openapi.Generator, basePath string, handlers *bootstrap.Handlers)
|
||||
```
|
||||
- **AND** 不再接受 `*fiber.App` 参数
|
||||
|
||||
#### Scenario: 使用 RouteSpec 注册路由
|
||||
|
||||
- **WHEN** 在 `RegisterPersonalRoutes` 中注册路由
|
||||
- **THEN** 使用 `doc.Register(openapi.RouteSpec{...})` 注册
|
||||
- **AND** 每个路由包含完整的元数据（Method, Path, Handler, Summary, Tags, Auth, Input, Output）
|
||||
|
||||
#### Scenario: 路由路径保持不变
|
||||
|
||||
- **WHEN** 改造路由注册方式
|
||||
- **THEN** 路由路径保持 `/api/c/v1/xxx` 格式
|
||||
- **AND** 不修改路径结构
|
||||
- **AND** 与现有客户端保持兼容
|
||||
|
||||
### Requirement: 个人客户 API 的文档元数据
|
||||
|
||||
个人客户 API 的 RouteSpec SHALL 包含中文 Summary 和统一的 Tags。
|
||||
|
||||
#### Scenario: Summary 使用中文描述
|
||||
|
||||
- **WHEN** 定义个人客户 API 的 RouteSpec
|
||||
- **THEN** Summary 字段使用中文描述（如 "获取个人客户卡详情"）
|
||||
- **AND** 描述简洁明了（一行以内）
|
||||
|
||||
#### Scenario: Tags 统一为"个人客户"
|
||||
|
||||
- **WHEN** 定义个人客户 API 的 RouteSpec
|
||||
- **THEN** Tags 字段包含 `["个人客户"]`
|
||||
- **AND** 所有个人客户 API 使用相同的 tag
|
||||
- **AND** 在 OpenAPI 文档中归类到同一分组
|
||||
|
||||
#### Scenario: Auth 字段正确设置
|
||||
|
||||
- **WHEN** 定义个人客户 API 的 RouteSpec
|
||||
- **THEN** 需要认证的接口设置 `Auth: true`
|
||||
- **AND** 无需认证的接口（如微信登录）设置 `Auth: false`
|
||||
|
||||
### Requirement: 个人客户路由在文档中可见
|
||||
|
||||
生成的 OpenAPI 文档 SHALL 包含所有个人客户 API 路由。
|
||||
|
||||
#### Scenario: 文档包含 /api/c/v1 路径
|
||||
|
||||
- **WHEN** 生成 OpenAPI 文档（`go run cmd/gendocs/main.go`）
|
||||
- **THEN** 生成的 `logs/openapi.yaml` 包含 `/api/c/v1` 路径
|
||||
- **AND** 路径数量与 `RegisterPersonalRoutes` 中注册的一致
|
||||
|
||||
#### Scenario: 个人客户接口在文档中正确分组
|
||||
|
||||
- **WHEN** 查看生成的 OpenAPI 文档
|
||||
- **THEN** 个人客户接口在 "个人客户" tag 下
|
||||
- **AND** 与其他模块（admin、h5）分组隔离
|
||||
|
||||
#### Scenario: 接口元数据完整
|
||||
|
||||
- **WHEN** 查看个人客户接口的 OpenAPI 定义
|
||||
- **THEN** 每个接口包含：
|
||||
- Summary（中文摘要）
|
||||
- Description（详细说明，如有）
|
||||
- Parameters（路径参数、查询参数）
|
||||
- RequestBody（请求体 schema）
|
||||
- Responses（响应 schema，包含 envelope）
|
||||
- Security（认证要求）
|
||||
|
||||
### Requirement: 个人客户 Handler 在文档生成器中注册
|
||||
|
||||
个人客户 Handler SHALL 在 `BuildDocHandlers()` 中构造。
|
||||
|
||||
#### Scenario: BuildDocHandlers 包含 PersonalCustomer
|
||||
|
||||
- **WHEN** 调用 `openapi.BuildDocHandlers()`
|
||||
- **THEN** 返回的 `bootstrap.Handlers` 包含 `PersonalCustomer` 字段
|
||||
- **AND** PersonalCustomer 使用 `personal.NewPersonalCustomerHandler(nil)` 构造
|
||||
|
||||
#### Scenario: 文档生成不执行 Handler 逻辑
|
||||
|
||||
- **WHEN** 为文档生成构造 PersonalCustomer handler
|
||||
- **THEN** 所有依赖参数传入 `nil`
|
||||
- **AND** 文档生成过程不会调用 handler 的实际业务逻辑
|
||||
- **AND** nil 依赖不会导致 panic
|
||||
|
||||
### Requirement: 路由注册调用方式更新
|
||||
|
||||
`internal/routes/routes.go` 中对 `RegisterPersonalRoutes` 的调用 SHALL 传入正确的参数。
|
||||
|
||||
#### Scenario: routes.go 传入 doc 参数
|
||||
|
||||
- **WHEN** 在 `routes.go` 中调用 `RegisterPersonalRoutes`
|
||||
- **THEN** 传入 `doc *openapi.Generator` 参数
|
||||
- **AND** 传入 basePath（如 `/api/c/v1`）
|
||||
- **AND** 传入 handlers
|
||||
|
||||
#### Scenario: 文档生成时调用 RegisterPersonalRoutes
|
||||
|
||||
- **WHEN** 文档生成流程调用路由注册
|
||||
- **THEN** `RegisterPersonalRoutes` 被调用
|
||||
- **AND** 个人客户路由被注册到文档生成器
|
||||
- **AND** 不启动 Fiber 服务器
|
||||
|
||||
### Requirement: 向后兼容性
|
||||
|
||||
路由注册方式的改造 SHALL 保持 API 行为不变。
|
||||
|
||||
#### Scenario: 改造后 API 响应格式不变
|
||||
|
||||
- **WHEN** 改造路由注册方式
|
||||
- **THEN** API 的响应格式与改造前一致
|
||||
- **AND** 响应包含 envelope：`{code, msg, data, timestamp}`
|
||||
|
||||
#### Scenario: 改造后路径不变
|
||||
|
||||
- **WHEN** 改造路由注册方式
|
||||
- **THEN** 所有路径保持 `/api/c/v1/xxx` 格式
|
||||
- **AND** 客户端无需修改请求 URL
|
||||
|
||||
#### Scenario: 改造后认证逻辑不变
|
||||
|
||||
- **WHEN** 改造路由注册方式
|
||||
- **THEN** 认证中间件继续生效
|
||||
- **AND** 需要认证的接口仍需提供有效 Token
|
||||
- **AND** 认证失败时返回 401 错误
|
||||
Reference in New Issue
Block a user