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.4 KiB

Raw Blame History

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/对接方会受到影响，但与真实行为一致）。

4.4 KiB Raw Blame History Unescape Escape