# Response DTO 规范规范

## MODIFIED Requirements

### Requirement: Response DTO 必须包含状态文字字段

项目所有 Response DTO 中，若包含 int 类型状态字段，必须同时包含对应的 `_name` 或 `_text` 文字字段，用于显示该状态的中文描述。

#### Scenario: 账号列表 Response DTO

- **WHEN** API 返回账号列表（`GET /api/admin/accounts`）
- **THEN** 响应中每个账号对象包含 `status` 字段（int，值：0=禁用，1=启用）
- **THEN** 响应中同时包含 `status_name` 字段（string，值："禁用"或"启用"）
- **THEN** 前端可直接使用 `status_name` 显示在 UI 上，无需维护单独的状态枚举映射表

#### Scenario: 资产详情 Response DTO

- **WHEN** API 返回单个资产信息（`GET /api/admin/assets/:id`）
- **THEN** 响应包含 `status`（int）和 `status_name`（string）
- **WHEN** 资产包含多个状态字段（如 `network_status`、`activation_status`、`online_status`）
- **THEN** 每个状态字段对应一个文字字段：`network_status_name`、`activation_status_name`、`online_status_name`

#### Scenario: 订单详情中的多重状态

- **WHEN** API 返回订单详情（`GET /api/admin/orders/:id`）
- **THEN** 订单对象包含 `payment_status`（int）和 `payment_status_name`（string）
- **THEN** 订单对象包含 `commission_status`（int）和 `commission_status_name`（string）
- **THEN** 若订单还有其他 int 类型状态字段，均配有对应的 `_name` 字段

### Requirement: DTO 文字字段命名规则

状态文字字段的命名应遵循统一规则：`{状态字段名}_name` 或 `{状态字段名}_text`。

#### Scenario: 标准命名

- **WHEN** 定义 DTO 时，状态字段为 `Status`
- **THEN** 文字字段命名为 `StatusName`（推荐）或 `StatusText`
- **WHEN** 状态字段为 `PaymentStatus`
- **THEN** 文字字段命名为 `PaymentStatusName` 或 `PaymentStatusText`

#### Scenario: JSON 序列化一致性

- **WHEN** DTO 序列化为 JSON 返回给客户端
- **THEN** 字段名使用 snake_case（符合项目 API 规范）
  - Go 字段 `Status` → JSON `status`
  - Go 字段 `StatusName` → JSON `status_name`

### Requirement: Service 层自动赋值 `_name` 字段

Service 层在构建 Response DTO 时，应自动赋值 `_name`/`_text` 字段，映射状态常量到中文描述。

#### Scenario: 获取账号详情自动赋值

- **WHEN** `AccountService.GetAccount(ctx, accountID)` 被调用
- **THEN** Service 查询数据库获取账号信息
- **THEN** Service 构建 Response DTO，自动设置 `StatusName = constants.GetAccountStatusName(account.Status)`
- **THEN** 返回完整的 DTO 给 Handler，Handler 直接序列化响应

#### Scenario: 列表查询批量赋值

- **WHEN** `AccountService.ListAccounts(ctx, query)` 被调用
- **THEN** Service 查询数据库获取账号列表
- **THEN** Service 遍历每个账号，批量赋值 `StatusName` 字段
- **THEN** 返回完整列表

### Requirement: 常量映射函数

在 `pkg/constants/` 中为每个业务模块定义 `Get{Module}StatusName(status int) string` 函数，用于映射状态值到中文描述。

#### Scenario: 账号状态映射函数

- **WHEN** Service 层需要获取账号状态的中文描述
- **THEN** 调用 `constants.GetAccountStatusName(status)`
- **THEN** 函数返回：
  - 若 `status == 0`，返回 `"禁用"`
  - 若 `status == 1`，返回 `"启用"`
  - 若状态值未知，返回 `"未知"`（不返回空字符串）

#### Scenario: 订单支付状态映射函数

- **WHEN** Service 层需要获取订单支付状态描述
- **THEN** 调用 `constants.GetOrderPaymentStatusName(status)`
- **THEN** 函数返回对应的中文（如 "待支付"、"已支付"、"已完成" 等）