huang
409a68d60b
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 个主规范文件 破坏性变更：无 向后兼容：是
63 lines
4.4 KiB
Markdown
63 lines
4.4 KiB
Markdown
# Change: 全局业务一致性修复（错误语义/文档/功能完整性）
|
||
|
||
## Why
|
||
|
||
当前代码存在多处“接口看起来存在，但对外契约/行为/可用性不一致”的问题，已经影响到：
|
||
|
||
- 对接可靠性：OpenAPI 文档与真实返回字段不一致（`msg` vs `message`），且成功响应在文档中未体现统一 envelope。
|
||
- 文档完整性：OpenAPI 生成时使用的 handlers 清单不完整，导致部分已注册路由不出现在文档；个人客户 `/api/c/v1` 路由不进入文档体系。
|
||
- 功能完整性：验证码服务在 smsClient 未配置时会触发 nil pointer；大量 Service 使用 `fmt.Errorf` 返回业务错误，最终被全局 ErrorHandler 归类为 500，导致业务语义丢失。
|
||
- 行为一致性与安全：存在 `Auth=true`（文档/元数据宣称需要认证）但真实路由未挂载认证中间件的情况；限流配置开启但实际不覆盖真实 API 路由。
|
||
|
||
本变更的目标是把“对外契约（文档 + 返回码 + 字段名 + 行为）”与“真实运行时行为”对齐，消除不可用、误导和潜在安全风险。
|
||
|
||
## What Changes
|
||
|
||
按阶段推进，优先止血，再做全量一致性修复：
|
||
|
||
### Phase A：线上止血（高优先级）
|
||
- 限流覆盖真实 API 路由组：`/api/admin` + `/api/h5` + `/api/c/v1`；明确排除 `/api/callback`、健康检查等非业务入口。
|
||
- 修复验证码链路的“未配置即崩溃”：短信服务未配置时返回 503（`CodeServiceUnavailable`），不 panic。
|
||
- 移除任务模块的占位/死代码：删除 `/api/admin/tasks/:id` 占位路由与未接入路由的 TaskHandler，避免“看似可用”且存在鉴权不一致风险。
|
||
|
||
### Phase B：错误语义全量统一（高影响面）
|
||
- **全量**替换 `internal/service/**` 中的 `fmt.Errorf` 作为对外错误返回：
|
||
- 预期业务错误返回 `errors.New(code)` 或 `errors.New(code, message)`（4xx）。
|
||
- 依赖/数据库/队列等底层错误返回 `errors.Wrap(code, err, message)`（5xx，客户端返回通用 msg）。
|
||
- 统一参数校验错误策略：对外不拼接 `validator` 的 `err.Error()`；详细信息只写日志。
|
||
|
||
### Phase C：文档契约对齐（OpenAPI 变更）
|
||
- OpenAPI 文档输出与真实响应一致：所有成功/失败响应均体现 `{code, data, msg, timestamp}`。
|
||
- 修复文档生成器 handlers 清单缺失问题，并消除 `cmd/api/docs.go` 与 `cmd/gendocs/main.go` 的重复逻辑。
|
||
- 个人客户 `/api/c/v1` 路由接入 `Register(...)`（带 RouteSpec），纳入 OpenAPI。
|
||
|
||
## Decisions（已确认）
|
||
|
||
- OpenAPI 以真实 envelope 为准：`{code, data, msg, timestamp}`。
|
||
- 限流覆盖范围：`/api/admin` + `/api/h5` + `/api/c/v1`；排除 `/api/callback`、健康检查。
|
||
- 短信服务未配置时：返回 503（`CodeServiceUnavailable`）。
|
||
- 任务模块：移除占位路由与未接入的 TaskHandler（不在本次提供任务提交 API）。
|
||
- Service 层错误处理：`internal/service/**` 内 **全量**替换 `fmt.Errorf` 对外返回方式，统一为 `errors.New/Wrap`。
|
||
|
||
## Impact
|
||
|
||
### Affected specs
|
||
- **UPDATE**: `openspec/specs/error-handling/spec.md`（补全 Purpose，新增“错误报错规范”要求：禁止泄露校验细节、Service 层对外错误必须结构化等）
|
||
- **UPDATE**: `openspec/specs/openapi-generation/spec.md`（OpenAPI 输出需要体现统一 envelope）
|
||
- **UPDATE**: `openspec/specs/personal-customer/spec.md`（个人客户 API 进入文档体系）
|
||
|
||
### Affected code (high level)
|
||
- 限流挂载与路由分组：`cmd/api/main.go`
|
||
- 验证码/个人客户登录链路：`internal/service/verification/service.go`、`internal/service/personal_customer/service.go`
|
||
- 全量 Service 错误改造：`internal/service/**`
|
||
- 参数校验错误对齐：`internal/handler/**`
|
||
- OpenAPI 生成器：`pkg/openapi/generator.go`
|
||
- 文档生成入口：`cmd/api/docs.go`、`cmd/gendocs/main.go`
|
||
- 个人客户路由注册：`internal/routes/personal.go`、`internal/routes/routes.go`
|
||
- 移除任务占位：`internal/routes/task.go`、`internal/routes/routes.go`、`internal/handler/admin/task.go`
|
||
|
||
### Breaking changes
|
||
- 移除 `/api/admin/tasks/:id` 占位接口（如有调用方，需要同步调整）。
|
||
- 多个接口的错误 HTTP 状态码会从 500 调整为 4xx（例如验证码错误、账号禁用等预期业务错误）。
|
||
- OpenAPI 文档结构变化：响应将统一包裹 envelope（生成 SDK/对接方会受到影响，但与真实行为一致）。
|