完善 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

@@ -2,48 +2,48 @@ package model
// CreateEnterpriseRequest 创建企业请求
type CreateEnterpriseRequest struct {
EnterpriseName string `json:"enterprise_name" validate:"required"` // 企业名称
EnterpriseCode string `json:"enterprise_code"` // 企业编号
OwnerShopID *uint `json:"owner_shop_id"` // 归属店铺ID
LegalPerson string `json:"legal_person"` // 法人代表
ContactName string `json:"contact_name"` // 联系人姓名
ContactPhone string `json:"contact_phone"` // 联系人电话
BusinessLicense string `json:"business_license"` // 营业执照号
Province string `json:"province"` // 省份
City string `json:"city"` // 城市
District string `json:"district"` // 区县
Address string `json:"address"` // 详细地址
EnterpriseName string `json:"enterprise_name" validate:"required" required:"true" description:"企业名称"`
EnterpriseCode string `json:"enterprise_code" description:"企业编号"`
OwnerShopID *uint `json:"owner_shop_id" description:"归属店铺ID可不填则归属平台"`
LegalPerson string `json:"legal_person" description:"法人代表"`
ContactName string `json:"contact_name" description:"联系人姓名"`
ContactPhone string `json:"contact_phone" description:"联系人电话"`
BusinessLicense string `json:"business_license" description:"营业执照号"`
Province string `json:"province" description:"省份"`
City string `json:"city" description:"城市"`
District string `json:"district" description:"区县"`
Address string `json:"address" description:"详细地址"`
}
// UpdateEnterpriseRequest 更新企业请求
type UpdateEnterpriseRequest struct {
EnterpriseName *string `json:"enterprise_name"` // 企业名称
EnterpriseCode *string `json:"enterprise_code"` // 企业编号
LegalPerson *string `json:"legal_person"` // 法人代表
ContactName *string `json:"contact_name"` // 联系人姓名
ContactPhone *string `json:"contact_phone"` // 联系人电话
BusinessLicense *string `json:"business_license"` // 营业执照号
Province *string `json:"province"` // 省份
City *string `json:"city"` // 城市
District *string `json:"district"` // 区县
Address *string `json:"address"` // 详细地址
EnterpriseName *string `json:"enterprise_name" description:"企业名称"`
EnterpriseCode *string `json:"enterprise_code" description:"企业编号"`
LegalPerson *string `json:"legal_person" description:"法人代表"`
ContactName *string `json:"contact_name" description:"联系人姓名"`
ContactPhone *string `json:"contact_phone" description:"联系人电话"`
BusinessLicense *string `json:"business_license" description:"营业执照号"`
Province *string `json:"province" description:"省份"`
City *string `json:"city" description:"城市"`
District *string `json:"district" description:"区县"`
Address *string `json:"address" description:"详细地址"`
}
// EnterpriseResponse 企业响应
type EnterpriseResponse struct {
ID uint `json:"id"`
EnterpriseName string `json:"enterprise_name"`
EnterpriseCode string `json:"enterprise_code"`
OwnerShopID *uint `json:"owner_shop_id,omitempty"`
LegalPerson string `json:"legal_person"`
ContactName string `json:"contact_name"`
ContactPhone string `json:"contact_phone"`
BusinessLicense string `json:"business_license"`
Province string `json:"province"`
City string `json:"city"`
District string `json:"district"`
Address string `json:"address"`
Status int `json:"status"`
CreatedAt string `json:"created_at"`
UpdatedAt string `json:"updated_at"`
ID uint `json:"id" description:"企业ID"`
EnterpriseName string `json:"enterprise_name" description:"企业名称"`
EnterpriseCode string `json:"enterprise_code" description:"企业编号"`
OwnerShopID *uint `json:"owner_shop_id,omitempty" description:"归属店铺ID"`
LegalPerson string `json:"legal_person" description:"法人代表"`
ContactName string `json:"contact_name" description:"联系人姓名"`
ContactPhone string `json:"contact_phone" description:"联系人电话"`
BusinessLicense string `json:"business_license" description:"营业执照号"`
Province string `json:"province" description:"省份"`
City string `json:"city" description:"城市"`
District string `json:"district" description:"区县"`
Address string `json:"address" description:"详细地址"`
Status int `json:"status" description:"状态 (0:禁用, 1:启用)"`
CreatedAt string `json:"created_at" description:"创建时间"`
UpdatedAt string `json:"updated_at" description:"更新时间"`
}