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/proposal.md

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