junhong_cmp_fiber/openspec/changes/tech-debt-cleanup/specs/dto-name-fields/spec.md

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 函数返回对应的中文（如 "待支付"、"已支付"、"已完成" 等）