完善 DTO 规范：统一 description 标签并添加 AI 助手自动检查指引

- 修复所有 DTO 文件的 description 标签（10 个文件） - 枚举字段统一使用中文说明（用户类型、角色类型、权限类型等） - 状态字段明确说明 0/1 含义 - validate 标签与 OpenAPI 标签保持一致 - 在 AGENTS.md 和 CLAUDE.md 添加 DTO 规范章节 - AI 助手必须执行的 7 项检查清单 - 常见枚举字段标准值参考 - 确保未来 AI 助手自动遵循规范 - 创建规范文档 - docs/code-review-checklist.md（Code Review 检查清单） - docs/dto-improvement-summary.md（DTO 改进总结） - docs/ai-dto-guidelines-update.md（AI 指引更新说明） - 重新生成 OpenAPI 文档（375 个 description 标签）影响：所有 API 字段现在都有清晰的中文说明，前端开发更友好
2026-01-20 15:10:11 +08:00
parent 1bee64fc65
commit 4abbf558e4
18 changed files with 1677 additions and 173 deletions
--- a/docs/code-review-checklist.md
+++ b/docs/code-review-checklist.md
@@ -0,0 +1,326 @@
+# Code Review 检查清单
+
+## 📋 DTO 规范检查清单
+
+在提交 Pull Request 前，请确保所有 DTO 文件遵循以下规范。
+
+---
+
+## ✅ 必须项（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:企业账号)"`
+```
+
+#### 角色类型
+```go
+RoleType int `json:"role_type" description:"角色类型 (1:平台角色, 2:客户角色)"`
+```
+
+#### 权限类型
+```go
+PermType int `json:"perm_type" description:"权限类型 (1:菜单, 2:按钮)"`
+```
+
+#### 状态字段
+```go
+Status int `json:"status" description:"状态 (0:禁用, 1:启用)"`
+```
+
+#### 适用端口
+```go
+Platform string `json:"platform" description:"适用端口 (all:全部, web:Web后台, h5:H5端)"`
+```
+
+---
+
+### 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 参数必须添加对应标签**
+
+#### Query 参数
+```go
+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:"用户类型"`
+}
+```
+
+#### Path 参数
+```go
+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:"更新时间"`
+}
+```
+
+---
+
+## 🔍 推荐项（SHOULD）
+
+### 6. 字段顺序规范
+
+建议按以下顺序组织字段：
+
+1. 主键字段（ID）
+2. 业务核心字段（名称、编号等）
+3. 关联字段（外键）
+4. 状态字段
+5. 审计字段（Creator、Updater、CreatedAt、UpdatedAt）
+
+---
+
+### 7. 中文注释完整性
+
+**所有导出的结构体、方法、常量必须有中文 godoc 注释**
+
+✅ **正确示例**：
+```go
+// CreateAccountRequest 创建账号请求
+type CreateAccountRequest struct {
+    // ...
+}
+
+// AccountResponse 账号响应
+type AccountResponse struct {
+    // ...
+}
+```
+
+---
+
+### 8. 必填字段和可选字段区分
+
+**使用指针类型标识可选字段**
+
+```go
+type UpdateRequest struct {
+    Username *string `json:"username" description:"用户名（可选）"`        // 可选
+    Status   *int    `json:"status" description:"状态（可选）"`            // 可选
+}
+
+type CreateRequest struct {
+    Username string `json:"username" required:"true" description:"用户名"`  // 必填
+    Status   int    `json:"status" required:"true" description:"状态"`     // 必填
+}
+```
+
+---
+
+## 🚫 禁止项（MUST NOT）
+
+### 9. 禁止使用英文枚举值说明
+
+❌ **错误**：
+```go
+UserType int `json:"user_type" description:"用户类型 (1:SuperAdmin, 2:Platform, 3:Agent, 4:Enterprise)"`
+```
+
+✅ **正确**：
+```go
+UserType int `json:"user_type" description:"用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)"`
+```
+
+---
+
+### 10. 禁止缺失枚举值说明
+
+❌ **错误**：
+```go
+Status int `json:"status" description:"状态"`
+```
+
+✅ **正确**：
+```go
+Status int `json:"status" description:"状态 (0:禁用, 1:启用)"`
+```
+
+---
+
+### 11. 禁止不一致的 description
+
+**同一字段在不同 DTO 中必须使用一致的 description**
+
+✅ **正确示例**：
+```go
+// CreateAccountRequest
+UserType int `json:"user_type" description:"用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)"`
+
+// AccountListRequest
+UserType *int `json:"user_type" description:"用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)"`
+
+// AccountResponse
+UserType int `json:"user_type" description:"用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)"`
+```
+
+---
+
+## 📝 常见枚举字段参考
+
+### 用户类型（UserType）
+```go
+description:"用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)"
+```
+
+### 角色类型（RoleType）
+```go
+description:"角色类型 (1:平台角色, 2:客户角色)"
+```
+
+### 权限类型（PermType）
+```go
+description:"权限类型 (1:菜单, 2:按钮)"
+```
+
+### 适用端口（Platform）
+```go
+description:"适用端口 (all:全部, web:Web后台, h5:H5端)"
+```
+
+### 状态（Status）
+```go
+description:"状态 (0:禁用, 1:启用)"
+```
+
+### 店铺层级（Level）
+```go
+description:"店铺层级 (1-7级)"
+```
+
+---
+
+## 🔧 检查工具
+
+### 手动检查
+
+在提交前运行以下命令检查 DTO 文件：
+
+```bash
+# 查找没有 description 标签的 json 字段
+grep -rn 'json:"[^"]*"' internal/model/*_dto.go | grep -v 'description:'
+
+# 查找使用行内注释的字段（应该改为 description 标签）
+grep -rn '`json:.*`.*//\s' internal/model/*_dto.go
+
+# 查找可能缺少枚举值说明的 status 字段
+grep -rn 'Status.*json:"status".*description:"状态"$' internal/model/*_dto.go
+```
+
+### 自动生成文档验证
+
+```bash
+# 生成 OpenAPI 文档
+go run cmd/gendocs/main.go
+
+# 检查生成的文档中是否包含完整的枚举值说明
+grep -A 3 "user_type:" docs/admin-openapi.yaml
+grep -A 3 "status:" docs/admin-openapi.yaml
+```
+
+---
+
+## 📚 相关文档
+
+- [项目开发规范](../AGENTS.md)
+- [OpenAPI 文档生成说明](../README.md#openapi-文档)
+- [RBAC 用户类型定义](../pkg/constants/constants.go)
+
+---
+
+## ✅ Code Review 检查清单（用于审查者）
+
+在审查 Pull Request 时，请逐项检查：
+
+- [ ] 所有新增/修改的 DTO 字段都有 `description` 标签
+- [ ] 所有枚举字段的 description 包含完整的可能值和中文说明
+- [ ] 所有状态字段明确说明了 0 和 1 的含义
+- [ ] validate 标签与 OpenAPI 标签（required、minLength、maximum 等）一致
+- [ ] Query 参数添加了 `query` 标签
+- [ ] Path 参数添加了 `path` 标签
+- [ ] 响应 DTO 的所有字段都有完整说明
+- [ ] 同一字段在不同 DTO 中使用一致的 description
+- [ ] 所有枚举值使用中文说明，禁止使用英文
+- [ ] 没有使用行内注释替代 description 标签
+- [ ] 所有导出的结构体有中文 godoc 注释
+
+---
+
+## 🎯 完成标准
+
+当所有检查项都通过时，才能合并 PR。
+
+**文档生成验证**：
+```bash
+go run cmd/gendocs/main.go
+# 检查 docs/admin-openapi.yaml 中所有字段都有清晰的中文说明
+```
+
+---
+
+**最后更新**: 2026-01-20  
+**维护者**: 开发团队