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）

```markdown
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级)"
```

---

## 🔄 工作流程

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

```go
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 助手验证生成的文档

```bash
# 检查用户类型字段
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**（遵循规范）
   ```go
   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. **生成文档**（自动）
   ```bash
   go run cmd/gendocs/main.go
   ```

5. **验证文档**（自动）
   ```bash
   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  
**维护者**: 开发团队