csxj2026/junhong_cmp_fiber

Files

huang 9795bb9ace 重构规范文档：提取详细规范为 6 个 Skills 实现模块化和按需加载

- 新增 6 个 Skill 文件：api-routing, db-migration, db-validation, doc-management, dto-standards, model-standards
- 简化 AGENTS.md 和 CLAUDE.md，保留核心规范，详细内容移至 Skills
- 添加 Skills 触发表格，说明各规范的加载时机
- 优化规范文档结构，提升可维护性和可读性

2026-01-21 11:19:13 +08:00

4.7 KiB

Raw Blame History

name, description

name	description
dto-standards	DTO 数据传输对象规范。创建或修改 DTO 文件、请求/响应结构时使用。包含 description 标签、枚举字段、验证标签等规范。

DTO 规范

所有 DTO 文件必须遵循以下规范，这是 API 文档生成的基础。

触发条件

在以下情况下必须遵守本规范：

创建或修改 internal/model/ 下的请求/响应 DTO
创建 XXXRequest、XXXResponse、XXXReq、XXXResp 结构体
添加或修改 API 接口的输入输出参数

必须项（MUST）

1. Description 标签规范

所有字段必须使用 description 标签，禁止使用行内注释

❌ 错误：

type CreateUserRequest struct {
    Username string `json:"username"` // 用户名
    Status   int    `json:"status"`   // 状态
}

✅ 正确：

type CreateUserRequest struct {
    Username string `json:"username" description:"用户名"`
    Status   int    `json:"status" description:"状态 (0:禁用, 1:启用)"`
}

2. 枚举字段必须列出所有可能值（中文）

所有枚举类型字段必须在 description 中列出所有可能值和对应的中文含义

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

// 角色类型
RoleType int `json:"role_type" description:"角色类型 (1:平台角色, 2:客户角色)"`

// 权限类型
PermType int `json:"perm_type" description:"权限类型 (1:菜单, 2:按钮)"`

// 状态字段
Status int `json:"status" description:"状态 (0:禁用, 1:启用)"`

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

❌ 禁止使用英文枚举值：

UserType int `json:"user_type" description:"用户类型 (1:SuperAdmin, 2:Platform)"` // 错误！

3. 验证标签与 OpenAPI 标签一致

所有验证约束必须同时在 validate 和 OpenAPI 标签中声明

Username string `json:"username" validate:"required,min=3,max=50" required:"true" minLength:"3" maxLength:"50" description:"用户名"`

标签对照表：

validate 标签	OpenAPI 标签	说明
`required`	`required:"true"`	必填字段
`min=N,max=M`	`minimum:"N" maximum:"M"`	数值范围
`min=N,max=M` (字符串)	`minLength:"N" maxLength:"M"`	字符串长度
`len=N`	`minLength:"N" maxLength:"N"`	固定长度
`oneof=A B C`	`description` 中说明	枚举值

4. 请求参数类型标签

Query 参数和 Path 参数必须添加对应标签

// Query 参数
type ListRequest struct {
    Page     int  `json:"page" query:"page" validate:"omitempty,min=1" minimum:"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:企业账号)"`
}

// Path 参数
type IDReq struct {
    ID uint `path:"id" description:"ID" required:"true"`
}

5. 响应 DTO 完整性

所有响应 DTO 的字段都必须有完整的 description 标签

type AccountResponse struct {
    ID        uint   `json:"id" description:"账号ID"`
    Username  string `json:"username" description:"用户名"`
    UserType  int    `json:"user_type" description:"用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)"`
    Status    int    `json:"status" description:"状态 (0:禁用, 1:启用)"`
    CreatedAt string `json:"created_at" description:"创建时间"`
    UpdatedAt string `json:"updated_at" description:"更新时间"`
}

AI 助手必须执行的检查

在创建或修改任何 DTO 文件后，必须执行以下检查：

✅ 检查所有字段是否有 description 标签
✅ 检查枚举字段是否列出了所有可能值（中文）
✅ 检查状态字段是否说明了 0 和 1 的含义
✅ 检查 validate 标签与 OpenAPI 标签是否一致
✅ 检查是否禁止使用行内注释替代 description
✅ 检查枚举值是否使用中文而非英文
✅ 重新生成 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级)"

4.7 KiB Raw Blame History Unescape Escape