feat: OpenAPI 契约对齐与框架优化

主要变更：
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 个主规范文件

破坏性变更：无
向后兼容：是

openspec/changes/archive/fix-global-business-consistency-emergency-fixes/tasks.md

@@ -0,0 +1,59 @@
+# 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 端登录、限流生效范围