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