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 个主规范文件 破坏性变更：无 向后兼容：是
60 lines
4.1 KiB
Markdown
60 lines
4.1 KiB
Markdown
# Implementation Tasks
|
||
|
||
## 1. 止血：限流覆盖真实 API 路由组
|
||
- [x] 1.1 调整 `cmd/api/main.go` 的限流挂载位置，覆盖 `/api/admin`、`/api/h5`、`/api/c/v1`
|
||
- [x] 1.2 明确排除 `/api/callback`、`/health`、`/ready`（避免误限流）
|
||
- [x] 1.3 补充/更新相关文档说明（限流生效范围）
|
||
|
||
## 2. 止血：短信验证码未配置不崩溃
|
||
- [x] 2.1 为短信客户端增加初始化流程（基于配置）
|
||
- [x] 2.2 `verification.Service` 在 smsClient 为空时返回 `errors.New(CodeServiceUnavailable)`（HTTP 503）
|
||
- [x] 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 端登录、限流生效范围
|