---
name: dto-standards
description: DTO 数据传输对象规范。创建或修改 DTO 文件、请求/响应结构时使用。包含 description 标签、枚举字段、验证标签等规范。
---

# DTO 规范

**所有 DTO 文件必须遵循以下规范，这是 API 文档生成的基础。**

## 触发条件

在以下情况下必须遵守本规范：
- 创建或修改 `internal/model/` 下的请求/响应 DTO
- 创建 `XXXRequest`、`XXXResponse`、`XXXReq`、`XXXResp` 结构体
- 添加或修改 API 接口的输入输出参数

## 必须项（MUST）

### 1. Description 标签规范

**所有字段必须使用 `description` 标签，禁止使用行内注释**

❌ **错误**：
```go
type CreateUserRequest struct {
    Username string `json:"username"` // 用户名
    Status   int    `json:"status"`   // 状态
}
```

✅ **正确**：
```go
type CreateUserRequest struct {
    Username string `json:"username" description:"用户名"`
    Status   int    `json:"status" description:"状态 (0:禁用, 1:启用)"`
}
```

### 2. 枚举字段必须列出所有可能值（中文）

**所有枚举类型字段必须在 `description` 中列出所有可能值和对应的中文含义**

```go
// 用户类型
UserType int `json:"user_type" description:"用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)"`

// 角色类型
RoleType int `json:"role_type" description:"角色类型 (1:平台角色, 2:客户角色)"`

// 权限类型
PermType int `json:"perm_type" description:"权限类型 (1:菜单, 2:按钮)"`

// 状态字段
Status int `json:"status" description:"状态 (0:禁用, 1:启用)"`

// 适用端口
Platform string `json:"platform" description:"适用端口 (all:全部, web:Web后台, h5:H5端)"`
```

❌ **禁止使用英文枚举值**：
```go
UserType int `json:"user_type" description:"用户类型 (1:SuperAdmin, 2:Platform)"` // 错误！
```

### 3. 验证标签与 OpenAPI 标签一致

**所有验证约束必须同时在 `validate` 和 OpenAPI 标签中声明**

```go
Username string `json:"username" validate:"required,min=3,max=50" required:"true" minLength:"3" maxLength:"50" description:"用户名"`
```

**标签对照表**：

| validate 标签 | OpenAPI 标签 | 说明 |
|--------------|--------------|------|
| `required` | `required:"true"` | 必填字段 |
| `min=N,max=M` | `minimum:"N" maximum:"M"` | 数值范围 |
| `min=N,max=M` (字符串) | `minLength:"N" maxLength:"M"` | 字符串长度 |
| `len=N` | `minLength:"N" maxLength:"N"` | 固定长度 |
| `oneof=A B C` | `description` 中说明 | 枚举值 |

### 4. 请求参数类型标签

**Query 参数和 Path 参数必须添加对应标签**

```go
// Query 参数
type ListRequest struct {
    Page     int  `json:"page" query:"page" validate:"omitempty,min=1" minimum:"1" description:"页码"`
    UserType *int `json:"user_type" query:"user_type" validate:"omitempty,min=1,max=4" minimum:"1" maximum:"4" description:"用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)"`
}

// Path 参数
type IDReq struct {
    ID uint `path:"id" description:"ID" required:"true"`
}
```

### 5. 响应 DTO 完整性

**所有响应 DTO 的字段都必须有完整的 `description` 标签**

```go
type AccountResponse struct {
    ID        uint   `json:"id" description:"账号ID"`
    Username  string `json:"username" description:"用户名"`
    UserType  int    `json:"user_type" description:"用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)"`
    Status    int    `json:"status" description:"状态 (0:禁用, 1:启用)"`
    CreatedAt string `json:"created_at" description:"创建时间"`
    UpdatedAt string `json:"updated_at" description:"更新时间"`
}
```

## AI 助手必须执行的检查

**在创建或修改任何 DTO 文件后，必须执行以下检查：**

1. ✅ 检查所有字段是否有 `description` 标签
2. ✅ 检查枚举字段是否列出了所有可能值（中文）
3. ✅ 检查状态字段是否说明了 0 和 1 的含义
4. ✅ 检查 validate 标签与 OpenAPI 标签是否一致
5. ✅ 检查是否禁止使用行内注释替代 description
6. ✅ 检查枚举值是否使用中文而非英文
7. ✅ 重新生成 OpenAPI 文档验证：`go run cmd/gendocs/main.go`

**详细检查清单**: 参见 `docs/code-review-checklist.md`

## 常见枚举字段标准值

```go
// 用户类型
description:"用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)"

// 角色类型
description:"角色类型 (1:平台角色, 2:客户角色)"

// 权限类型
description:"权限类型 (1:菜单, 2:按钮)"

// 适用端口
description:"适用端口 (all:全部, web:Web后台, h5:H5端)"

// 状态
description:"状态 (0:禁用, 1:启用)"

// 店铺层级
description:"店铺层级 (1-7级)"
```