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 个主规范文件 破坏性变更：无 向后兼容：是
4.1 KiB
4.1 KiB
Implementation Tasks
1. 止血：限流覆盖真实 API 路由组
- 1.1 调整
cmd/api/main.go的限流挂载位置，覆盖/api/admin、/api/h5、/api/c/v1 - 1.2 明确排除
/api/callback、/health、/ready（避免误限流） - 1.3 补充/更新相关文档说明（限流生效范围）
2. 止血：短信验证码未配置不崩溃
- 2.1 为短信客户端增加初始化流程（基于配置）
- 2.2
verification.Service在 smsClient 为空时返回errors.New(CodeServiceUnavailable)（HTTP 503） - 2.3 为验证码发送/验证关键路径添加/补充测试用例（至少覆盖“未配置短信服务”的返回）
3. 全量：Service 层错误语义统一（internal/service/**）
- [~] 3.1 【部分完成】制定并落地“Service 对外错误必须结构化”的规则（
errors.New/Wrap），禁止对外直接返回fmt.Errorf - 3.2 扫描并替换
internal/service/**中所有fmt.Errorf对外返回点（全量） - 已完成文件：verification/service.go (10处), personal_customer/service.go (11处), auth/service.go (4处), device_import/service.go (2处)
- 待完成文件：24个文件，约224处 fmt.Errorf 待替换
- 3.3 对“预期业务错误”统一返回 4xx（例如验证码错误/过期、账号禁用等）
- 3.4 对“依赖/数据库/队列错误”统一使用
errors.Wrap(<5xx-code>, err, msg) - 3.5 针对变更量最大的模块补充回归测试（优先：verification / personal_customer / auth / package / order）
4. 全量：参数校验错误不泄露内部细节
- 4.1 扫描
internal/handler/**中所有"参数验证失败: "+err.Error()/ 直接返回err.Error()的位置 - 4.2 调整为：对外返回
errors.New(CodeInvalidParam)（或固定中文短消息），详细 err 仅写日志 - 4.3 补充单测/集成测试，确保返回 msg 不包含 validator 内部细节
5. OpenAPI：响应 envelope 与字段名对齐
- 5.1 修复 OpenAPI 错误响应 schema 字段名（
msg替代message） - 5.2 让 OpenAPI 200 响应体现
{code,data,msg,timestamp}envelope（data 保持具体 DTO schema） - 5.3 重新生成文档并人工抽查关键接口（admin/h5/c端）
6. OpenAPI：生成入口 handlers 清单一致且完整
- 6.1 抽取“文档生成用 handlers 构造器”，供
cmd/api/docs.go与cmd/gendocs/main.go复用 - 6.2 补齐缺失 handlers（PersonalCustomer、ShopPackageBatchAllocation、ShopPackageBatchPricing）
- 6.3 避免文档生成用 handler 需要真实依赖（保持 nil 依赖安全）
7. 路由：个人客户 /api/c/v1 纳入 Register(...) 与文档
- 7.1 改造
internal/routes/personal.go：支持 doc 生成，使用Register(...) - 7.2 更新
internal/routes/routes.go的调用方式（传入 doc/basePath） - 7.3 补充个人客户 API 的 RouteSpec（Summary/Tags/Input/Output/Auth）
8. 任务模块：移除占位与死代码
- 8.1 移除
internal/routes/task.go与routes.go中的registerTaskRoutes(...)调用 - 8.2 移除未接入路由的
internal/handler/admin/task.go - 8.3 更新文档/README（如有提及任务 API）
9. 注释与遗留一致性清理（低风险）
- 9.1 清理
internal/handler/**中残留的/api/v1/...注释（与真实/api/admin等路径一致）
10. 规范落地：把错误报错规则写入项目规范
- 10.1 更新
openspec/specs/error-handling/spec.md（Purpose + 新增“错误报错规范”条款） - 10.2 更新
AGENTS.md增加“错误报错规范”摘要与检查清单 - 10.3 更新
docs/003-error-handling/使用指南.md，形成可执行的开发/Code Review 规范 - 10.4 增加 CI/脚本检查：禁止
internal/service/**出现fmt.Errorf(（允许白名单场景需显式说明）
11. 回归验证
- 11.1
go test ./...（含必要的集成测试准备说明） - 11.2 重新生成 OpenAPI 并检查差异（接口数量、路径、响应字段）
- 11.3 手工验证关键链路：验证码发送/登录、B 端登录、限流生效范围