完善 DTO 规范:统一 description 标签并添加 AI 助手自动检查指引
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:
2026-01-20 15:10:11 +08:00
parent 1bee64fc65
commit 4abbf558e4
18 changed files with 1677 additions and 173 deletions

View File

@@ -5,7 +5,7 @@ type CreateAccountRequest struct {
Username string `json:"username" validate:"required,min=3,max=50" required:"true" minLength:"3" maxLength:"50" description:"用户名"`
Phone string `json:"phone" validate:"required,len=11" required:"true" minLength:"11" maxLength:"11" description:"手机号"`
Password string `json:"password" validate:"required,min=8,max=32" required:"true" minLength:"8" maxLength:"32" description:"密码"`
UserType int `json:"user_type" validate:"required,min=1,max=4" required:"true" minimum:"1" maximum:"4" description:"用户类型 (1:SuperAdmin, 2:Platform, 3:Agent, 4:Enterprise)"`
UserType int `json:"user_type" validate:"required,min=1,max=4" required:"true" minimum:"1" maximum:"4" description:"用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)"`
ShopID *uint `json:"shop_id" description:"关联店铺ID代理账号必填"`
EnterpriseID *uint `json:"enterprise_id" description:"关联企业ID企业账号必填"`
}
@@ -24,8 +24,8 @@ type AccountListRequest struct {
PageSize int `json:"page_size" query:"page_size" validate:"omitempty,min=1,max=100" minimum:"1" maximum:"100" description:"每页数量"`
Username string `json:"username" query:"username" validate:"omitempty,max=50" maxLength:"50" description:"用户名模糊查询"`
Phone string `json:"phone" query:"phone" validate:"omitempty,max=20" maxLength:"20" description:"手机号模糊查询"`
UserType *int `json:"user_type" query:"user_type" validate:"omitempty,min=1,max=4" minimum:"1" maximum:"4" description:"用户类型"`
Status *int `json:"status" query:"status" validate:"omitempty,min=0,max=1" minimum:"0" maximum:"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:企业账号)"`
Status *int `json:"status" query:"status" validate:"omitempty,min=0,max=1" minimum:"0" maximum:"1" description:"状态 (0:禁用, 1:启用)"`
}
// AccountResponse 账号响应
@@ -33,10 +33,10 @@ type AccountResponse struct {
ID uint `json:"id" description:"账号ID"`
Username string `json:"username" description:"用户名"`
Phone string `json:"phone" description:"手机号"`
UserType int `json:"user_type" description:"用户类型"`
UserType int `json:"user_type" description:"用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)"`
ShopID *uint `json:"shop_id,omitempty" description:"关联店铺ID"`
EnterpriseID *uint `json:"enterprise_id,omitempty" description:"关联企业ID"`
Status int `json:"status" description:"状态"`
Status int `json:"status" description:"状态 (0:禁用, 1:启用)"`
Creator uint `json:"creator" description:"创建人ID"`
Updater uint `json:"updater" description:"更新人ID"`
CreatedAt string `json:"created_at" description:"创建时间"`
@@ -78,7 +78,7 @@ type PlatformAccountListRequest struct {
PageSize int `json:"page_size" query:"page_size" validate:"omitempty,min=1,max=100" minimum:"1" maximum:"100" description:"每页数量"`
Username string `json:"username" query:"username" validate:"omitempty,max=50" maxLength:"50" description:"用户名模糊查询"`
Phone string `json:"phone" query:"phone" validate:"omitempty,max=20" maxLength:"20" description:"手机号模糊查询"`
Status *int `json:"status" query:"status" validate:"omitempty,min=0,max=1" minimum:"0" maximum:"1" description:"状态"`
Status *int `json:"status" query:"status" validate:"omitempty,min=0,max=1" minimum:"0" maximum:"1" description:"状态 (0:禁用, 1:启用)"`
}
// UpdatePasswordParams 修改密码参数(用于 OpenAPI 生成)