完善 DTO 规范：统一 description 标签并添加 AI 助手自动检查指引
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 4m28s
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 4m28s
- 修复所有 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 字段现在都有清晰的中文说明，前端开发更友好
This commit is contained in:
215
docs/dto-improvement-summary.md
Normal file
215
docs/dto-improvement-summary.md
Normal file
@@ -0,0 +1,215 @@
|
||||
# DTO 规范完善总结
|
||||
|
||||
## 📊 修复概览
|
||||
|
||||
**修复日期**: 2026-01-20
|
||||
**修复范围**: 所有 DTO 文件的 `description` 标签规范化
|
||||
|
||||
---
|
||||
|
||||
## ✅ 已修复的文件清单
|
||||
|
||||
### 1. 账号模块
|
||||
- ✅ `internal/model/account_dto.go`
|
||||
- 修复 `CreateAccountRequest.UserType` - 添加完整中文枚举说明
|
||||
- 修复 `AccountListRequest.UserType` - 添加完整中文枚举说明
|
||||
- 修复 `AccountListRequest.Status` - 添加 0/1 含义
|
||||
- 修复 `AccountResponse.UserType` - 添加完整中文枚举说明
|
||||
- 修复 `AccountResponse.Status` - 添加 0/1 含义
|
||||
- 修复 `PlatformAccountListRequest.Status` - 添加 0/1 含义
|
||||
|
||||
### 2. 认证模块
|
||||
- ✅ `internal/model/auth_dto.go`
|
||||
- 为 `UserInfo` 所有字段添加完整的 `description` 标签
|
||||
- `UserType` 使用完整中文枚举说明
|
||||
|
||||
### 3. 角色模块
|
||||
- ✅ `internal/model/role_dto.go`
|
||||
- 修复 `RoleListRequest.Status` - 添加 0/1 含义
|
||||
- 修复 `RoleResponse.RoleType` - 添加完整中文枚举说明
|
||||
- 修复 `RoleResponse.Status` - 添加 0/1 含义
|
||||
|
||||
### 4. 权限模块
|
||||
- ✅ `internal/model/permission_dto.go`
|
||||
- 修复 `PermissionListRequest.PermType` - 添加完整中文枚举说明
|
||||
- 修复 `PermissionListRequest.Platform` - 添加完整中文枚举说明
|
||||
- 修复 `PermissionListRequest.Status` - 添加 0/1 含义
|
||||
- 修复 `PermissionResponse.PermType` - 添加完整中文枚举说明
|
||||
- 修复 `PermissionResponse.Platform` - 添加完整中文枚举说明
|
||||
- 修复 `PermissionResponse.Status` - 添加 0/1 含义
|
||||
- 修复 `PermissionTreeNode` - 所有字段添加完整说明
|
||||
|
||||
### 5. 店铺模块
|
||||
- ✅ `internal/model/shop_dto.go`
|
||||
- 从无 `description` 标签 → 所有字段添加完整的 `description` 标签
|
||||
- 添加 validate 对应的 OpenAPI 标签（required、minLength、maxLength 等）
|
||||
- `Status` 字段添加 0/1 含义说明
|
||||
- `Level` 字段说明店铺层级范围
|
||||
|
||||
### 6. 企业模块
|
||||
- ✅ `internal/model/enterprise_dto.go`
|
||||
- 从行内注释 → 改为 `description` 标签
|
||||
- `Status` 字段添加 0/1 含义说明
|
||||
- 所有字段添加清晰的中文说明
|
||||
|
||||
### 7. 个人客户模块
|
||||
- ✅ `internal/model/personal_customer_dto.go`
|
||||
- 从行内注释 → 改为 `description` 标签
|
||||
- `Status` 字段添加 0/1 含义说明
|
||||
- 所有字段添加清晰的中文说明
|
||||
|
||||
### 8. 代理商账号模块
|
||||
- ✅ `internal/model/shop_account_dto.go`
|
||||
- 从行内注释 → 改为 `description` 标签
|
||||
- `UserType` 和 `Status` 字段添加完整枚举说明
|
||||
|
||||
### 9. 角色-权限关联模块
|
||||
- ✅ `internal/model/role_permission_dto.go`
|
||||
- 从无 `description` 标签 → 所有字段添加完整说明
|
||||
- `Status` 字段添加 0/1 含义说明
|
||||
|
||||
### 10. 账号-角色关联模块
|
||||
- ✅ `internal/model/account_role_dto.go`
|
||||
- 从无 `description` 标签 → 所有字段添加完整说明
|
||||
- `Status` 字段添加 0/1 含义说明
|
||||
|
||||
---
|
||||
|
||||
## 📈 修复前后对比
|
||||
|
||||
### 修复前 ❌
|
||||
|
||||
**问题 1**: 枚举值使用英文
|
||||
```go
|
||||
UserType int `json:"user_type" description:"用户类型 (1:SuperAdmin, 2:Platform, 3:Agent, 4:Enterprise)"`
|
||||
```
|
||||
|
||||
**问题 2**: 缺少枚举值说明
|
||||
```go
|
||||
Status int `json:"status" description:"状态"`
|
||||
```
|
||||
|
||||
**问题 3**: 使用行内注释而非 description 标签
|
||||
```go
|
||||
EnterpriseName string `json:"enterprise_name"` // 企业名称
|
||||
```
|
||||
|
||||
**问题 4**: 完全没有 description 标签
|
||||
```go
|
||||
type ShopResponse struct {
|
||||
ID uint `json:"id"`
|
||||
ShopName string `json:"shop_name"`
|
||||
Status int `json:"status"`
|
||||
}
|
||||
```
|
||||
|
||||
### 修复后 ✅
|
||||
|
||||
**所有枚举值使用完整中文说明**
|
||||
```go
|
||||
UserType int `json:"user_type" description:"用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)"`
|
||||
```
|
||||
|
||||
**状态字段明确说明 0/1 含义**
|
||||
```go
|
||||
Status int `json:"status" description:"状态 (0:禁用, 1:启用)"`
|
||||
```
|
||||
|
||||
**统一使用 description 标签**
|
||||
```go
|
||||
EnterpriseName string `json:"enterprise_name" description:"企业名称"`
|
||||
```
|
||||
|
||||
**所有字段都有完整说明**
|
||||
```go
|
||||
type ShopResponse struct {
|
||||
ID uint `json:"id" description:"店铺ID"`
|
||||
ShopName string `json:"shop_name" description:"店铺名称"`
|
||||
Status int `json:"status" description:"状态 (0:禁用, 1:启用)"`
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 统计数据
|
||||
|
||||
### 生成的 OpenAPI 文档
|
||||
|
||||
- **文件路径**: `docs/admin-openapi.yaml`
|
||||
- **Description 字段数量**: **375 个**
|
||||
- **覆盖的 DTO 文件**: **10 个**
|
||||
- **修复的字段**: **100+ 个**
|
||||
|
||||
### 枚举字段标准化
|
||||
|
||||
| 枚举类型 | 标准 Description | 使用次数 |
|
||||
|---------|-----------------|---------|
|
||||
| 用户类型 | `用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)` | 6 处 |
|
||||
| 角色类型 | `角色类型 (1:平台角色, 2:客户角色)` | 3 处 |
|
||||
| 权限类型 | `权限类型 (1:菜单, 2:按钮)` | 3 处 |
|
||||
| 适用端口 | `适用端口 (all:全部, web:Web后台, h5:H5端)` | 5 处 |
|
||||
| 状态 | `状态 (0:禁用, 1:启用)` | 15+ 处 |
|
||||
|
||||
---
|
||||
|
||||
## 🎯 达成的效果
|
||||
|
||||
### 1. 前端开发友好
|
||||
- ✅ 所有 API 字段都有清晰的中文说明
|
||||
- ✅ 枚举字段明确列出所有可能值
|
||||
- ✅ 导入 Swagger UI/Apifox 后可直接使用
|
||||
|
||||
### 2. 文档自动生成
|
||||
- ✅ OpenAPI 文档完全自动生成，无需手动编写
|
||||
- ✅ 字段说明与代码同步，避免文档过期
|
||||
|
||||
### 3. 代码可维护性
|
||||
- ✅ 统一的规范，新人容易上手
|
||||
- ✅ Code Review 有明确的检查标准
|
||||
|
||||
---
|
||||
|
||||
## 📋 后续维护
|
||||
|
||||
### 新增 DTO 时必须遵循
|
||||
|
||||
1. ✅ 所有字段添加 `description` 标签
|
||||
2. ✅ 枚举字段列出所有可能值（中文）
|
||||
3. ✅ validate 标签与 OpenAPI 标签保持一致
|
||||
4. ✅ 使用 `query` 和 `path` 标签标记参数类型
|
||||
|
||||
### Code Review 检查清单
|
||||
|
||||
详见：[docs/code-review-checklist.md](./code-review-checklist.md)
|
||||
|
||||
### 验证方法
|
||||
|
||||
```bash
|
||||
# 生成文档
|
||||
go run cmd/gendocs/main.go
|
||||
|
||||
# 检查特定字段的说明
|
||||
grep -A 3 "user_type:" docs/admin-openapi.yaml
|
||||
grep -A 3 "status:" docs/admin-openapi.yaml
|
||||
|
||||
# 统计 description 数量
|
||||
grep -c "description:" docs/admin-openapi.yaml
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔗 相关文档
|
||||
|
||||
- [Code Review 检查清单](./code-review-checklist.md)
|
||||
- [项目开发规范](../AGENTS.md)
|
||||
- [README](../README.md)
|
||||
|
||||
---
|
||||
|
||||
## 👥 贡献者
|
||||
|
||||
- 开发团队
|
||||
|
||||
---
|
||||
|
||||
**最后更新**: 2026-01-20
|
||||
Reference in New Issue
Block a user