csxj2026/junhong_cmp_fiber

Files

构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 5m45s

Details

主要变更：
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 个主规范文件

破坏性变更：无
向后兼容：是

2026-01-30 11:40:36 +08:00

4.7 KiB

Raw Blame History

Personal Customer - 更新规范

MODIFIED Requirements

Requirement: 个人客户路由必须纳入文档体系

个人客户 API 路由注册 SHALL 使用 Register(...) 机制，与其他路由（admin、h5）保持一致。

Scenario: RegisterPersonalRoutes 函数签名变更

WHEN 定义 RegisterPersonalRoutes 函数

THEN 函数签名为：

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 错误

4.7 KiB Raw Blame History Unescape Escape