# 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 端登录、限流生效范围