# Personal Customer - 更新规范

## MODIFIED Requirements

### 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 错误