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/specs/error-handling/spec.md

@@ -1,7 +1,14 @@
 # error-handling Specification
 
 ## Purpose
-TBD - created by archiving change refactor-framework-cleanup. Update Purpose after archive.
+
+定义本项目“错误产生、错误传递、错误返回”的统一规范，确保：
+
+- 对外响应结构一致（`{code, data, msg, timestamp}`）
+- 业务语义一致（可预期业务错误返回 4xx，非预期系统错误返回 5xx）
+- 不泄露内部细节（校验细节、数据库/第三方错误细节仅写日志）
+- 分层职责明确（Handler 只负责输入/输出，Service 负责业务与结构化错误）
+
 ## Requirements
 ### Requirement: Simplified AppError Structure
 
@@ -57,7 +64,27 @@ TBD - created by archiving change refactor-framework-cleanup. Update Purpose aft
 
 #### Scenario: 参数验证错误
 - **WHEN** 请求参数验证失败
-- **THEN** 返回 errors.New(CodeInvalidParam, "具体错误描述")
+- **THEN** 返回 errors.New(CodeInvalidParam)
+- **AND** 不将 validator 的 err.Error() 直接返回给客户端（避免泄露内部字段和规则）
+- **AND** 详细校验错误 SHALL 记录到日志（用于排查）
+
+### Requirement: Service Error Output Convention
+
+Service 层 SHALL 对外输出结构化错误，禁止把普通 error 直接冒泡到 Handler。
+
+#### Scenario: 预期业务错误
+- **WHEN** 业务校验失败（例如：验证码错误、资源不存在、状态不允许）
+- **THEN** 返回 errors.New(<4xx-code>[, message])
+
+#### Scenario: 非预期系统错误
+- **WHEN** 发生数据库/缓存/队列/第三方依赖错误
+- **THEN** 返回 errors.Wrap(<5xx-code>, err, "业务动作失败")
+- **AND** 客户端 msg 由全局错误映射表提供通用描述
+
+#### Scenario: 禁止 fmt.Errorf 作为对外错误
+- **WHEN** Service 需要对外返回错误
+- **THEN** 不使用 fmt.Errorf(...) 作为返回值
+- **AND** 必须转换为 AppError（errors.New/Wrap）
 
 #### Scenario: 成功响应
 - **WHEN** Handler 执行成功
@@ -78,3 +105,165 @@ TBD - created by archiving change refactor-framework-cleanup. Update Purpose aft
 - **THEN** 使用 CodeServiceUnavailable
 - **AND** 不使用 CodeAuthServiceUnavailable（别名已删除）
 
+## 错误报错规范（必须遵守）
+
+### Handler 层
+- ❌ **禁止直接返回/拼接底层错误信息给客户端**
+  - 例如：`"参数验证失败: " + err.Error()`、直接返回 `err.Error()`
+  - 原因：泄露内部字段名和校验规则，造成安全风险
+- ✅ **参数校验失败统一返回** `errors.New(errors.CodeInvalidParam)`
+  - 详细校验错误写日志，对外返回通用消息
+- ✅ **详细错误信息记录到日志**，用于排查问题
+  - 日志级别：参数错误使用 `WARN` 级别（客户端错误）
+  - 必须包含：`path`、`method`、完整错误信息
+  - 使用结构化日志（`zap.String`、`zap.Error`）
+
+### Service 层
+- ❌ **禁止对外返回** `fmt.Errorf(...)`
+  - 原因：未结构化的错误消息会泄露实现细节
+- ✅ **业务错误使用** `errors.New(code[, msg])`
+  - 适用场景：资源不存在、状态不允许、参数错误等预期错误
+- ✅ **系统错误使用** `errors.Wrap(code, err[, msg])`
+  - 适用场景：数据库错误、Redis 错误、队列错误等非预期错误
+
+### 示例对比
+
+**Handler 层参数校验**：
+```go
+// ❌ 错误：泄露校验细节
+if err := c.BodyParser(&req); err != nil {
+    return errors.New(errors.CodeInvalidParam, "参数解析失败: "+err.Error())
+}
+
+// ✅ 正确：通用消息 + 结构化日志
+if err := c.BodyParser(&req); err != nil {
+    logger.GetAppLogger().Warn("参数解析失败",
+        zap.String("path", c.Path()),
+        zap.String("method", c.Method()),
+        zap.Error(err),
+    )
+    return errors.New(errors.CodeInvalidParam, "请求参数格式错误")
+}
+
+// ✅ 参数验证失败示例
+if err := h.validator.Struct(&req); err != nil {
+    logger.GetAppLogger().Warn("参数验证失败",
+        zap.String("path", c.Path()),
+        zap.String("method", c.Method()),
+        zap.Error(err),
+    )
+    return errors.New(errors.CodeInvalidParam)  // 使用默认消息
+}
+```
+
+**Service 层错误处理**：
+```go
+// ❌ 错误：使用 fmt.Errorf
+if err := s.store.Create(ctx, data); err != nil {
+    return fmt.Errorf("创建失败: %w", err)
+}
+
+// ✅ 正确：使用 errors.Wrap
+if err := s.store.Create(ctx, data); err != nil {
+    return errors.Wrap(errors.CodeInternalError, err, "创建失败")
+}
+```
+
+## Service 层错误处理规范
+
+### 错误分类与映射表
+
+| 场景分类 | 错误码 | HTTP 状态码 | 使用方式 |
+|---------|-------|-----------|---------|
+| 资源不存在 | `CodeNotFound` | 404 | `errors.New(errors.CodeNotFound, "资源不存在")` |
+| 状态不允许 | `CodeInvalidStatus` | 400 | `errors.New(errors.CodeInvalidStatus, "状态不允许此操作")` |
+| 参数错误 | `CodeInvalidParam` | 400 | `errors.New(errors.CodeInvalidParam)` |
+| 重复操作 | `CodeDuplicate` | 409 | `errors.New(errors.CodeDuplicate, "资源已存在")` |
+| 余额不足 | `CodeInsufficientBalance` | 400 | `errors.New(errors.CodeInsufficientBalance)` |
+| 额度不足 | `CodeInsufficientQuota` | 400 | `errors.New(errors.CodeInsufficientQuota, "分配额度不足")` |
+| 超过限制 | `CodeExceedLimit` | 400 | `errors.New(errors.CodeExceedLimit, "超过系统限制")` |
+| 资源冲突 | `CodeConflict` | 409 | `errors.New(errors.CodeConflict, "资源冲突")` |
+| 数据库错误 | `CodeInternalError` | 500 | `errors.Wrap(errors.CodeInternalError, err, "操作失败")` |
+| 队列错误 | `CodeInternalError` | 500 | `errors.Wrap(errors.CodeInternalError, err, "任务提交失败")` |
+
+### 实际案例
+
+#### 案例 1：套餐服务（package/service.go）
+
+**场景：获取套餐**
+```go
+// ❌ 错误：使用 fmt.Errorf
+func (s *Service) Get(ctx context.Context, id uint) (*dto.PackageResponse, error) {
+    pkg, err := s.packageStore.GetByID(ctx, id)
+    if err != nil {
+        if err == gorm.ErrRecordNotFound {
+            return nil, errors.New(errors.CodeNotFound, "套餐不存在")
+        }
+        return nil, fmt.Errorf("获取套餐失败: %w", err)  // ❌ 直接返回系统错误
+    }
+    return s.toResponse(ctx, pkg), nil
+}
+
+// ✅ 正确：使用 errors.Wrap
+func (s *Service) Get(ctx context.Context, id uint) (*dto.PackageResponse, error) {
+    pkg, err := s.packageStore.GetByID(ctx, id)
+    if err != nil {
+        if err == gorm.ErrRecordNotFound {
+            return nil, errors.New(errors.CodeNotFound, "套餐不存在")
+        }
+        return nil, errors.Wrap(errors.CodeInternalError, err, "获取套餐失败")  // ✅
+    }
+    return s.toResponse(ctx, pkg), nil
+}
+```
+
+#### 案例 2：分佣提现（commission_withdrawal/service.go）
+
+**场景：余额不足**
+```go
+// ✅ 业务错误使用 errors.New
+if wallet.FrozenBalance < amount {
+    return nil, errors.New(errors.CodeInsufficientBalance, "钱包冻结余额不足")
+}
+
+// ✅ 事务中的数据库错误使用 errors.Wrap
+err = s.db.Transaction(func(tx *gorm.DB) error {
+    if err := s.walletStore.DeductFrozenBalanceWithTx(ctx, tx, wallet.ID, amount); err != nil {
+        return errors.Wrap(errors.CodeInternalError, err, "扣除冻结余额失败")
+    }
+    // ...
+})
+```
+
+#### 案例 3：店铺管理（shop/service.go）
+
+**场景：层级限制和重复检查**
+```go
+// ✅ 业务校验
+if level > 7 {
+    return nil, errors.New(errors.CodeInvalidParam, "店铺层级超过限制")
+}
+
+// ✅ 重复检查
+existing, _ := s.shopStore.GetByCode(ctx, req.ShopCode)
+if existing != nil {
+    return nil, errors.New(errors.CodeDuplicate, "店铺代码已存在")
+}
+
+// ✅ 数据库操作
+if err := s.shopStore.Create(ctx, shop); err != nil {
+    return nil, errors.Wrap(errors.CodeInternalError, err, "创建店铺失败")
+}
+```
+
+### 统一原则
+
+1. **业务错误（4xx）**：使用 `errors.New(Code4xx, msg)`
+   - 资源不存在、状态不允许、参数错误、重复操作等
+   
+2. **系统错误（5xx）**：使用 `errors.Wrap(Code5xx, err, msg)`
+   - 数据库错误、Redis 错误、队列错误、外部服务错误等
+   
+3. **错误消息保持中文**：便于日志排查和问题定位
+
+4. **禁止 fmt.Errorf 对外返回**：避免泄露内部实现细节

openspec/specs/openapi-generation/spec.md

@@ -81,3 +81,187 @@ TBD - created by archiving change auto-generate-openapi-docs. Update Purpose aft
 - **AND** 通过参数区分输出路径
 - **AND** 避免逻辑重复
 
+### Requirement: 响应格式规范
+
+系统 SHALL 在 OpenAPI 文档中正确体现统一的响应 envelope 格式。
+
+#### Scenario: 成功响应包裹 envelope
+
+- **WHEN** 接口定义了 Output DTO
+- **THEN** OpenAPI 文档中的成功响应包含以下结构:
+  ```yaml
+  properties:
+    code:
+      type: integer
+      example: 0
+      description: 响应码
+    msg:
+      type: string
+      example: success
+      description: 响应消息
+    data:
+      $ref: '#/components/schemas/OutputDTO'
+    timestamp:
+      type: string
+      format: date-time
+      description: 时间戳
+  ```
+
+#### Scenario: 错误响应字段名对齐
+
+- **WHEN** 生成错误响应 schema
+- **THEN** 使用 `msg` 字段名（与真实运行时一致）
+- **AND** 不使用 `message` 字段名
+
+#### Scenario: 无返回数据的接口
+
+- **WHEN** 接口的 Output 为 nil（如删除操作）
+- **THEN** `data` 字段类型设为 `null`
+- **AND** 保持 envelope 结构完整
+
+#### Scenario: DTO 定义保持简洁
+
+- **WHEN** 开发者定义 DTO
+- **THEN** 只需定义 `data` 字段的内容
+- **AND** 无需在 DTO 中包含 envelope 字段（code、msg、timestamp）
+
+### Requirement: 错误响应字段名必须为 msg
+
+OpenAPI 文档中的错误响应 SHALL 使用 `msg` 字段而非 `message`，与真实运行时的 Response 结构体保持一致。
+
+#### Scenario: 错误响应使用 msg 字段
+
+- **WHEN** 生成 OpenAPI 文档的错误响应 schema
+- **THEN** ErrorResponse 包含 `msg` 字段（类型为 string）
+- **AND** ErrorResponse 不包含 `message` 字段
+
+#### Scenario: 生成的文档与真实响应一致
+
+- **WHEN** API 返回错误响应
+- **THEN** 响应 JSON 包含 `msg` 字段
+- **AND** OpenAPI 文档中的 schema 定义也使用 `msg` 字段
+- **AND** 字段名完全匹配
+
+### Requirement: 成功响应必须包裹在 envelope 中
+
+所有成功响应 SHALL 包裹在统一的 envelope 结构中：`{code, msg, data, timestamp}`。
+
+#### Scenario: 成功响应包含 envelope 结构
+
+- **WHEN** 生成接口的 200 响应 schema
+- **THEN** 响应 schema 包含以下字段：
+  - `code` (integer, example: 0)
+  - `msg` (string, example: "success")
+  - `data` (原始 DTO schema)
+  - `timestamp` (string, format: date-time)
+
+#### Scenario: data 字段包含实际的 DTO
+
+- **WHEN** 接口返回数据（如用户列表、详情）
+- **THEN** OpenAPI 的 `data` 字段引用实际的 DTO schema
+- **AND** DTO schema 不被修改（保持原结构）
+
+#### Scenario: 无返回数据的接口 data 为 null
+
+- **WHEN** 接口无返回数据（如删除操作）
+- **THEN** OpenAPI 的 `data` 字段类型为 `null`
+- **AND** 响应仍包含 `code`、`msg`、`timestamp` 字段
+
+### Requirement: envelope 包裹适用于所有接口类型
+
+envelope 包裹 SHALL 适用于普通接口和文件上传接口。
+
+#### Scenario: 普通接口使用 envelope
+
+- **WHEN** 通过 `AddOperation` 添加接口
+- **THEN** 生成的 200 响应包含 envelope 结构
+
+#### Scenario: 文件上传接口使用 envelope
+
+- **WHEN** 通过 `AddMultipartOperation` 添加文件上传接口
+- **THEN** 生成的 200 响应包含 envelope 结构
+- **AND** envelope 结构与普通接口一致
+
+### Requirement: 所有 handlers 必须在文档生成器中注册
+
+文档生成器 SHALL 包含所有已实现的 handlers，确保接口文档完整。
+
+#### Scenario: handlers 清单完整性
+
+- **WHEN** 生成 OpenAPI 文档
+- **THEN** 所有 handler 的接口都出现在文档中
+- **AND** 不存在已实现但未出现在文档的接口
+
+#### Scenario: 新增 handler 时同步更新
+
+- **WHEN** 新增 handler（如 `PersonalCustomer`、`ShopPackageBatchAllocation`）
+- **THEN** 必须在 `BuildDocHandlers()` 中添加对应的构造代码
+- **AND** 重新生成文档后接口出现在 OpenAPI 文件中
+
+### Requirement: handlers 构造函数统一管理
+
+handlers 的构造逻辑 SHALL 由公共函数 `BuildDocHandlers()` 统一管理，避免重复。
+
+#### Scenario: cmd/api/docs.go 复用 BuildDocHandlers
+
+- **WHEN** 在 `cmd/api/docs.go` 中需要构造 handlers
+- **THEN** 调用 `openapi.BuildDocHandlers()` 获取 handlers
+- **AND** 不在本文件中重复构造
+
+#### Scenario: cmd/gendocs/main.go 复用 BuildDocHandlers
+
+- **WHEN** 在 `cmd/gendocs/main.go` 中需要构造 handlers
+- **THEN** 调用 `openapi.BuildDocHandlers()` 获取 handlers
+- **AND** 不在本文件中重复构造
+
+#### Scenario: BuildDocHandlers 传入 nil 依赖
+
+- **WHEN** `BuildDocHandlers()` 构造 handlers
+- **THEN** 所有 handler 构造函数的依赖参数传入 `nil`
+- **AND** 因为文档生成不执行 handler 逻辑，nil 依赖不会导致运行时错误
+
+### Requirement: 个人客户路由必须使用 Register 机制
+
+个人客户 API (`/api/c/v1`) SHALL 使用 `Register(...)` 机制注册，纳入 OpenAPI 文档体系。
+
+#### Scenario: RegisterPersonalRoutes 使用 Register 机制
+
+- **WHEN** 调用 `RegisterPersonalRoutes` 注册个人客户路由
+- **THEN** 使用 `doc.Register(RouteSpec{...})` 注册每个路由
+- **AND** 不直接调用 Fiber 的 `app.Get/Post` 方法
+
+#### Scenario: 个人客户路由出现在文档中
+
+- **WHEN** 生成 OpenAPI 文档
+- **THEN** 文档包含 `/api/c/v1` 路径的接口
+- **AND** 每个接口包含正确的 Summary、Tags、Auth 信息
+
+#### Scenario: 个人客户路由的元数据完整
+
+- **WHEN** 注册个人客户路由
+- **THEN** 每个 RouteSpec 包含：
+  - Method（GET/POST/PUT/DELETE）
+  - Path（完整路径）
+  - Handler（fiber.Handler）
+  - Summary（中文摘要）
+  - Tags（包含 "个人客户"）
+  - Auth（true/false）
+  - Input（请求 DTO 或 nil）
+  - Output（响应 DTO）
+
+### Requirement: 文档生成的幂等性
+
+文档生成 SHALL 是幂等的，相同的代码生成相同的文档。
+
+#### Scenario: 重复生成文档内容一致
+
+- **WHEN** 多次运行 `go run cmd/gendocs/main.go`
+- **THEN** 生成的 `openapi.yaml` 内容完全一致
+- **AND** 文件 hash 值相同（除 timestamp 等动态字段外）
+
+#### Scenario: 代码未变更时文档不变
+
+- **WHEN** 代码（handlers、路由、DTO）未变更
+- **THEN** 重新生成的文档与之前的文档一致
+- **AND** 不会因为生成逻辑的随机性导致差异
+

openspec/specs/personal-customer/spec.md

@@ -199,3 +199,167 @@ sms:
 
 ---
 
+### Requirement: OpenAPI 文档集成
+
+个人客户 API SHALL 纳入项目的 OpenAPI 文档生成体系，使用统一的 `Register()` 机制注册路由。
+
+#### Scenario: 路由注册纳入文档
+
+- **WHEN** 个人客户路由使用 `Register()` 函数注册
+- **THEN** 路由自动出现在生成的 OpenAPI 文档中
+- **AND** 文档包含完整的请求/响应结构、认证信息和中文描述
+
+#### Scenario: 文档标签分类
+
+- **WHEN** 生成 OpenAPI 文档
+- **THEN** 个人客户 API 使用 "个人客户 - 认证" 和 "个人客户 - 账户" 等中文标签分类
+- **AND** 与后台管理 API 标签区分
+
+#### Scenario: 响应格式统一
+
+- **WHEN** 个人客户 API 返回响应
+- **THEN** 使用统一的 envelope 格式：`{code, msg, data, timestamp}`
+- **AND** 与后台管理 API 响应格式一致
+
+**实现位置**: `internal/routes/personal.go`
+
+**文档路径**: `/api/c/v1` 路由组在 `docs/admin-openapi.yaml` 中可见
+
+---
+
+### Requirement: 个人客户路由必须纳入文档体系
+
+个人客户 API 路由注册 SHALL 使用 `Register(...)` 机制，与其他路由（admin、h5）保持一致。
+
+#### Scenario: RegisterPersonalRoutes 函数签名变更
+
+- **WHEN** 定义 `RegisterPersonalRoutes` 函数
+- **THEN** 函数签名为：
+  ```go
+  func RegisterPersonalRoutes(doc *openapi.Generator, basePath string, handlers *bootstrap.Handlers)
+  ```
+- **AND** 不再接受 `*fiber.App` 参数
+
+#### Scenario: 使用 RouteSpec 注册路由
+
+- **WHEN** 在 `RegisterPersonalRoutes` 中注册路由
+- **THEN** 使用 `doc.Register(openapi.RouteSpec{...})` 注册
+- **AND** 每个路由包含完整的元数据（Method, Path, Handler, Summary, Tags, Auth, Input, Output）
+
+#### Scenario: 路由路径保持不变
+
+- **WHEN** 改造路由注册方式
+- **THEN** 路由路径保持 `/api/c/v1/xxx` 格式
+- **AND** 不修改路径结构
+- **AND** 与现有客户端保持兼容
+
+### Requirement: 个人客户 API 的文档元数据
+
+个人客户 API 的 RouteSpec SHALL 包含中文 Summary 和统一的 Tags。
+
+#### Scenario: Summary 使用中文描述
+
+- **WHEN** 定义个人客户 API 的 RouteSpec
+- **THEN** Summary 字段使用中文描述（如 "获取个人客户卡详情"）
+- **AND** 描述简洁明了（一行以内）
+
+#### Scenario: Tags 统一为"个人客户"
+
+- **WHEN** 定义个人客户 API 的 RouteSpec
+- **THEN** Tags 字段包含 `["个人客户"]`
+- **AND** 所有个人客户 API 使用相同的 tag
+- **AND** 在 OpenAPI 文档中归类到同一分组
+
+#### Scenario: Auth 字段正确设置
+
+- **WHEN** 定义个人客户 API 的 RouteSpec
+- **THEN** 需要认证的接口设置 `Auth: true`
+- **AND** 无需认证的接口（如微信登录）设置 `Auth: false`
+
+### Requirement: 个人客户路由在文档中可见
+
+生成的 OpenAPI 文档 SHALL 包含所有个人客户 API 路由。
+
+#### Scenario: 文档包含 /api/c/v1 路径
+
+- **WHEN** 生成 OpenAPI 文档（`go run cmd/gendocs/main.go`）
+- **THEN** 生成的 `logs/openapi.yaml` 包含 `/api/c/v1` 路径
+- **AND** 路径数量与 `RegisterPersonalRoutes` 中注册的一致
+
+#### Scenario: 个人客户接口在文档中正确分组
+
+- **WHEN** 查看生成的 OpenAPI 文档
+- **THEN** 个人客户接口在 "个人客户" tag 下
+- **AND** 与其他模块（admin、h5）分组隔离
+
+#### Scenario: 接口元数据完整
+
+- **WHEN** 查看个人客户接口的 OpenAPI 定义
+- **THEN** 每个接口包含：
+  - Summary（中文摘要）
+  - Description（详细说明，如有）
+  - Parameters（路径参数、查询参数）
+  - RequestBody（请求体 schema）
+  - Responses（响应 schema，包含 envelope）
+  - Security（认证要求）
+
+### Requirement: 个人客户 Handler 在文档生成器中注册
+
+个人客户 Handler SHALL 在 `BuildDocHandlers()` 中构造。
+
+#### Scenario: BuildDocHandlers 包含 PersonalCustomer
+
+- **WHEN** 调用 `openapi.BuildDocHandlers()`
+- **THEN** 返回的 `bootstrap.Handlers` 包含 `PersonalCustomer` 字段
+- **AND** PersonalCustomer 使用 `personal.NewPersonalCustomerHandler(nil)` 构造
+
+#### Scenario: 文档生成不执行 Handler 逻辑
+
+- **WHEN** 为文档生成构造 PersonalCustomer handler
+- **THEN** 所有依赖参数传入 `nil`
+- **AND** 文档生成过程不会调用 handler 的实际业务逻辑
+- **AND** nil 依赖不会导致 panic
+
+### Requirement: 路由注册调用方式更新
+
+`internal/routes/routes.go` 中对 `RegisterPersonalRoutes` 的调用 SHALL 传入正确的参数。
+
+#### Scenario: routes.go 传入 doc 参数
+
+- **WHEN** 在 `routes.go` 中调用 `RegisterPersonalRoutes`
+- **THEN** 传入 `doc *openapi.Generator` 参数
+- **AND** 传入 basePath（如 `/api/c/v1`）
+- **AND** 传入 handlers
+
+#### Scenario: 文档生成时调用 RegisterPersonalRoutes
+
+- **WHEN** 文档生成流程调用路由注册
+- **THEN** `RegisterPersonalRoutes` 被调用
+- **AND** 个人客户路由被注册到文档生成器
+- **AND** 不启动 Fiber 服务器
+
+### Requirement: 向后兼容性
+
+路由注册方式的改造 SHALL 保持 API 行为不变。
+
+#### Scenario: 改造后 API 响应格式不变
+
+- **WHEN** 改造路由注册方式
+- **THEN** API 的响应格式与改造前一致
+- **AND** 响应包含 envelope：`{code, msg, data, timestamp}`
+
+#### Scenario: 改造后路径不变
+
+- **WHEN** 改造路由注册方式
+- **THEN** 所有路径保持 `/api/c/v1/xxx` 格式
+- **AND** 客户端无需修改请求 URL
+
+#### Scenario: 改造后认证逻辑不变
+
+- **WHEN** 改造路由注册方式
+- **THEN** 认证中间件继续生效
+- **AND** 需要认证的接口仍需提供有效 Token
+- **AND** 认证失败时返回 401 错误
+
+---
+