junhong_cmp_fiber/docs/ai-dto-guidelines-update.md

AI 助手 DTO 规范指引更新

📋 更新概览

更新日期: 2026-01-20
目的: 确保未来的 AI 助手在创建/修改 DTO 时自动遵循规范

---

✅ 已更新的文件

1. AGENTS.md（第 96 行）

添加了完整的 DTO 规范（重要！） 章节，包括：

• ✅ Description 标签规范
• ✅ 枚举字段必须列出所有可能值（中文）
• ✅ 验证标签与 OpenAPI 标签一致
• ✅ 请求参数类型标签
• ✅ 响应 DTO 完整性
• ✅ AI 助手必须执行的检查清单
• ✅ 常见枚举字段标准值

2. CLAUDE.md（第 99 行）

添加了 DTO 规范（API 文档生成基础） 章节，包括：

• ✅ 所有字段必须使用 description 标签
• ✅ 枚举字段必须列出所有可能值（使用中文）
• ✅ validate 标签必须与 OpenAPI 标签一致
• ✅ Query 和 Path 参数必须添加对应标签
• ✅ AI 助手在创建/修改 DTO 后必须执行的检查

---

🎯 AI 助手自动检查清单

未来的 AI 助手在创建或修改任何 DTO 文件后，会自动执行以下检查：

必须执行的检查（来自 AGENTS.md）

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
• 在线引用: 两个文件都包含此引用

---

📚 标准枚举值参考

两个文件都包含了常见枚举字段的标准值：

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

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

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

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

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

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

---

🔄 工作流程

1. AI 助手创建/修改 DTO 文件

type CreateAccountRequest struct {
    Username string `json:"username" validate:"required,min=3,max=50" required:"true" minLength:"3" maxLength:"50" description:"用户名"`
    UserType int    `json:"user_type" validate:"required,min=1,max=4" required:"true" minimum:"1" maximum:"4" description:"用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)"`
    Status   int    `json:"status" validate:"required,min=0,max=1" required:"true" minimum:"0" maximum:"1" description:"状态 (0:禁用, 1:启用)"`
}

2. AI 助手自动执行检查

根据 AGENTS.md 和 CLAUDE.md 中的指引，AI 会：

• ✅ 验证所有字段都有 description 标签
• ✅ 验证枚举字段包含完整的中文说明
• ✅ 验证 validate 和 OpenAPI 标签一致性
• ✅ 执行 go run cmd/gendocs/main.go 生成文档

3. AI 助手验证生成的文档

# 检查用户类型字段
grep -A 3 "user_type:" docs/admin-openapi.yaml

# 输出应该包含完整的中文枚举说明：
# description: 用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)

4. AI 助手报告检查结果

AI 会主动告知用户：

• ✅ 所有 DTO 字段都符合规范
• ✅ OpenAPI 文档已重新生成
• ✅ 所有枚举值使用中文说明

---

📊 对比：更新前 vs 更新后

更新前 ❌

AI 助手行为：

• ❌ 可能忘记添加 description 标签
• ❌ 可能使用英文枚举值
• ❌ 可能使用行内注释而非 description
• ❌ 不会自动验证文档生成

开发者需要：

• 🔧 手动检查每个 DTO 文件
• 🔧 手动修复不符合规范的字段
• 🔧 手动重新生成文档

更新后 ✅

AI 助手行为：

• ✅ 自动为所有字段添加 description 标签
• ✅ 自动使用中文枚举值
• ✅ 自动确保 validate 和 OpenAPI 标签一致
• ✅ 自动重新生成并验证文档

开发者只需：

• 👀 Code Review 时参考 docs/code-review-checklist.md
• ✅ 信任 AI 已按规范执行

---

🎓 示例：AI 助手的标准操作流程

用户请求

"请创建一个企业管理的 DTO，包括创建、更新和列表查询"

AI 助手执行步骤

1. 读取规范（自动）

   • 从 AGENTS.md 或 CLAUDE.md 读取 DTO 规范
   • 了解必须遵循的标签格式

2. 创建 DTO（遵循规范）

   type CreateEnterpriseRequest struct {
       EnterpriseName string `json:"enterprise_name" validate:"required" required:"true" description:"企业名称"`
       Status         int    `json:"status" validate:"required,min=0,max=1" required:"true" description:"状态 (0:禁用, 1:启用)"`
   }
   

3. 执行检查（自动）

   • ✅ 所有字段都有 description
   • ✅ Status 字段说明了 0/1 含义
   • ✅ validate 和 OpenAPI 标签一致

4. 生成文档（自动）

   go run cmd/gendocs/main.go
   

5. 验证文档（自动）

   grep "状态" docs/admin-openapi.yaml
   # 确认输出包含: description: 状态 (0:禁用, 1:启用)
   

6. 报告完成（主动告知用户）

   ✅ 已创建 enterprise_dto.go
   ✅ 所有字段都符合 DTO 规范
   ✅ OpenAPI 文档已更新（docs/admin-openapi.yaml）
   ✅ 所有枚举值使用中文说明
   

---

🔗 相关文档

文档	路径	说明
AI 开发规范	AGENTS.md	包含 DTO 规范和检查清单（第 96 行）
Claude 规范	CLAUDE.md	包含 DTO 规范和检查清单（第 99 行）
Code Review 清单	docs/code-review-checklist.md	完整的检查清单
DTO 改进总结	docs/dto-improvement-summary.md	本次修复的详细记录
OpenAPI 文档	docs/admin-openapi.yaml	自动生成的 API 文档

---

🎯 预期效果

对未来 AI 助手的影响

1. ✅ 自动合规：所有新建的 DTO 自动符合规范
2. ✅ 减少返工：不再需要手动修复不规范的代码
3. ✅ 文档同步：代码即文档，文档永远是最新的
4. ✅ 一致性：所有枚举字段使用统一的中文说明格式

对开发团队的影响

1. ✅ Code Review 简化：只需对照 docs/code-review-checklist.md 快速检查
2. ✅ 前端友好：API 文档清晰，前端开发效率提升
3. ✅ 新人友好：规范明确，容易上手
4. ✅ 维护成本降低：规范统一，代码可读性强

---

📈 统计数据

文件更新统计

文件	添加行数	章节	位置
AGENTS.md	~120 行	DTO 规范（重要！）	第 96 行
CLAUDE.md	~30 行	DTO 规范（API 文档生成基础）	第 99 行

覆盖的检查项

• ✅ 7 个自动检查项（AGENTS.md）
• ✅ 5 个核心规范点（CLAUDE.md）
• ✅ 6 种标准枚举类型

---

🚀 下一步

立即生效

• ✅ 未来所有与此项目交互的 AI 助手都会自动读取这些规范
• ✅ 新建或修改 DTO 时会自动执行检查
• ✅ 文档生成和验证自动化

团队协作

• 📝 在 Code Review 时参考 docs/code-review-checklist.md
• 📝 在 PR 模板中添加"DTO 规范检查"项
• 📝 定期运行 go run cmd/gendocs/main.go 确保文档最新

---

最后更新: 2026-01-20
维护者: 开发团队