junhong_cmp_fiber/docs/code-review-checklist.md

# Code Review 检查清单

## 📋 DTO 规范检查清单

在提交 Pull Request 前，请确保所有 DTO 文件遵循以下规范。

---

## ✅ 必须项（MUST）

### 1. Description 标签规范

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

❌ **错误示例**：
```go
type CreateUserRequest struct {
    Username string `json:"username"` // 用户名
    Status   int    `json:"status"`   // 状态
}
```

✅ **正确示例**：
```go
type CreateUserRequest struct {
    Username string `json:"username" description:"用户名"`
    Status   int    `json:"status" description:"状态 (0:禁用, 1:启用)"`
}
```

---

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

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

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

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

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

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

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

---

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

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

✅ **正确示例**：
```go
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 参数
```go
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:"用户类型"`
}
```

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

---

### 5. 响应 DTO 完整性

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

✅ **正确示例**：
```go
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:"更新时间"`
}
```

---

## 🔍 推荐项（SHOULD）

### 6. 字段顺序规范

建议按以下顺序组织字段：

1. 主键字段（ID）
2. 业务核心字段（名称、编号等）
3. 关联字段（外键）
4. 状态字段
5. 审计字段（Creator、Updater、CreatedAt、UpdatedAt）

---

### 7. 中文注释完整性

**所有导出的结构体、方法、常量必须有中文 godoc 注释**

✅ **正确示例**：
```go
// CreateAccountRequest 创建账号请求
type CreateAccountRequest struct {
    // ...
}

// AccountResponse 账号响应
type AccountResponse struct {
    // ...
}
```

---

### 8. 必填字段和可选字段区分

**使用指针类型标识可选字段**

```go
type UpdateRequest struct {
    Username *string `json:"username" description:"用户名（可选）"`        // 可选
    Status   *int    `json:"status" description:"状态（可选）"`            // 可选
}

type CreateRequest struct {
    Username string `json:"username" required:"true" description:"用户名"`  // 必填
    Status   int    `json:"status" required:"true" description:"状态"`     // 必填
}
```

---

## 🚫 禁止项（MUST NOT）

### 9. 禁止使用英文枚举值说明

❌ **错误**：
```go
UserType int `json:"user_type" description:"用户类型 (1:SuperAdmin, 2:Platform, 3:Agent, 4:Enterprise)"`
```

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

---

### 10. 禁止缺失枚举值说明

❌ **错误**：
```go
Status int `json:"status" description:"状态"`
```

✅ **正确**：
```go
Status int `json:"status" description:"状态 (0:禁用, 1:启用)"`
```

---

### 11. 禁止不一致的 description

**同一字段在不同 DTO 中必须使用一致的 description**

✅ **正确示例**：
```go
// CreateAccountRequest
UserType int `json:"user_type" description:"用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)"`

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

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

---

## 📝 常见枚举字段参考

### 用户类型（UserType）
```go
description:"用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)"
```

### 角色类型（RoleType）
```go
description:"角色类型 (1:平台角色, 2:客户角色)"
```

### 权限类型（PermType）
```go
description:"权限类型 (1:菜单, 2:按钮)"
```

### 适用端口（Platform）
```go
description:"适用端口 (all:全部, web:Web后台, h5:H5端)"
```

### 状态（Status）
```go
description:"状态 (0:禁用, 1:启用)"
```

### 店铺层级（Level）
```go
description:"店铺层级 (1-7级)"
```

---

## 🔧 检查工具

### 手动检查

在提交前运行以下命令检查 DTO 文件：

```bash
# 查找没有 description 标签的 json 字段
grep -rn 'json:"[^"]*"' internal/model/*_dto.go | grep -v 'description:'

# 查找使用行内注释的字段（应该改为 description 标签）
grep -rn '`json:.*`.*//\s' internal/model/*_dto.go

# 查找可能缺少枚举值说明的 status 字段
grep -rn 'Status.*json:"status".*description:"状态"$' internal/model/*_dto.go
```

### 自动生成文档验证

```bash
# 生成 OpenAPI 文档
go run cmd/gendocs/main.go

# 检查生成的文档中是否包含完整的枚举值说明
grep -A 3 "user_type:" docs/admin-openapi.yaml
grep -A 3 "status:" docs/admin-openapi.yaml
```

---

## 📚 相关文档

- [项目开发规范](../AGENTS.md)
- [OpenAPI 文档生成说明](../README.md#openapi-文档)
- [RBAC 用户类型定义](../pkg/constants/constants.go)

---

## ✅ Code Review 检查清单（用于审查者）

在审查 Pull Request 时，请逐项检查：

- [ ] 所有新增/修改的 DTO 字段都有 `description` 标签
- [ ] 所有枚举字段的 description 包含完整的可能值和中文说明
- [ ] 所有状态字段明确说明了 0 和 1 的含义
- [ ] validate 标签与 OpenAPI 标签（required、minLength、maximum 等）一致
- [ ] Query 参数添加了 `query` 标签
- [ ] Path 参数添加了 `path` 标签
- [ ] 响应 DTO 的所有字段都有完整说明
- [ ] 同一字段在不同 DTO 中使用一致的 description
- [ ] 所有枚举值使用中文说明，禁止使用英文
- [ ] 没有使用行内注释替代 description 标签
- [ ] 所有导出的结构体有中文 godoc 注释

---

## 🎯 完成标准

当所有检查项都通过时，才能合并 PR。

**文档生成验证**：
```bash
go run cmd/gendocs/main.go
# 检查 docs/admin-openapi.yaml 中所有字段都有清晰的中文说明
```

---

**最后更新**: 2026-01-20  
**维护者**: 开发团队