huang
d9de704d73
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 49s
84 lines
3.7 KiB
Markdown
84 lines
3.7 KiB
Markdown
# 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** 函数返回对应的中文（如 "待支付"、"已支付"、"已完成" 等）
|