csxj2026/junhong_cmp_fiber
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity

完善 DTO 规范：统一 description 标签并添加 AI 助手自动检查指引
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 4m28s
Details

Browse Source 
- 修复所有 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:
huang
2026-01-20 15:10:11 +08:00
parent 1bee64fc65
commit 4abbf558e4
18 changed files with 1677 additions and 173 deletions
Download Patch File Download Diff File Expand all files Collapse all files

61
docs/admin-openapi.yaml
View File

@@ -62,7 +62,7 @@ components:
nullable: true
type: integer
status:
description: 状态
description: 状态 (0:禁用, 1:启用)
type: integer
updated_at:
description: 更新时间
@@ -72,7 +72,7 @@ components:
minimum: 0
type: integer
user_type:
description: 用户类型
description: 用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)
type: integer
username:
description: 用户名
@@ -131,7 +131,7 @@ components:
nullable: true
type: integer
user_type:
description: 用户类型 (1:SuperAdmin, 2:Platform, 3:Agent, 4:Enterprise)
description: 用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)
maximum: 4
minimum: 1
type: integer
@@ -279,7 +279,7 @@ components:
ModelPermissionResponse:
properties:
available_for_role_types:
description: 可用角色类型
description: 可用角色类型 (1:平台角色, 2:客户角色)
type: string
created_at:
description: 创建时间
@@ -304,16 +304,16 @@ components:
description: 权限名称
type: string
perm_type:
description: 权限类型
description: 权限类型 (1:菜单, 2:按钮)
type: integer
platform:
description: 适用端口
description: 适用端口 (all:全部, web:Web后台, h5:H5端)
type: string
sort:
description: 排序值
type: integer
status:
description: 状态
description: 状态 (0:禁用, 1:启用)
type: integer
updated_at:
description: 更新时间
@@ -329,7 +329,7 @@ components:
ModelPermissionTreeNode:
properties:
available_for_role_types:
description: 可用角色类型
description: 可用角色类型 (1:平台角色, 2:客户角色)
type: string
children:
description: 子权限列表
@@ -347,10 +347,10 @@ components:
description: 权限名称
type: string
perm_type:
description: 权限类型
description: 权限类型 (1:菜单, 2:按钮)
type: integer
platform:
description: 适用端口
description: 适用端口 (all:全部, web:Web后台, h5:H5端)
type: string
sort:
description: 排序值
@@ -426,10 +426,10 @@ components:
description: 角色名称
type: string
role_type:
description: 角色类型
description: 角色类型 (1:平台角色, 2:客户角色)
type: integer
status:
description: 状态
description: 状态 (0:禁用, 1:启用)
type: integer
updated_at:
description: 更新时间
@@ -559,25 +559,34 @@ components:
ModelUserInfo:
properties:
enterprise_id:
description: 企业ID
minimum: 0
type: integer
enterprise_name:
description: 企业名称
type: string
id:
description: 用户ID
minimum: 0
type: integer
phone:
description: 手机号
type: string
shop_id:
description: 店铺ID
minimum: 0
type: integer
shop_name:
description: 店铺名称
type: string
user_type:
description: 用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)
type: integer
user_type_name:
description: 用户类型名称
type: string
username:
description: 用户名
type: string
type: object
securitySchemes:
@@ -622,20 +631,20 @@ paths:
description: 手机号模糊查询
maxLength: 20
type: string
- description: 用户类型
- description: 用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)
in: query
name: user_type
schema:
description: 用户类型
description: 用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)
maximum: 4
minimum: 1
nullable: true
type: integer
- description: 状态
- description: 状态 (0:禁用, 1:启用)
in: query
name: status
schema:
description: 状态
description: 状态 (0:禁用, 1:启用)
maximum: 1
minimum: 0
nullable: true
@@ -1153,20 +1162,20 @@ paths:
description: 权限编码模糊查询
maxLength: 100
type: string
- description: 权限类型
- description: 权限类型 (1:菜单, 2:按钮)
in: query
name: perm_type
schema:
description: 权限类型
description: 权限类型 (1:菜单, 2:按钮)
maximum: 2
minimum: 1
nullable: true
type: integer
- description: 适用端口
- description: 适用端口 (all:全部, web:Web后台, h5:H5端)
in: query
name: platform
schema:
description: 适用端口
description: 适用端口 (all:全部, web:Web后台, h5:H5端)
type: string
- description: 可用角色类型 (1:平台角色, 2:客户角色)
in: query
@@ -1185,11 +1194,11 @@ paths:
minimum: 0
nullable: true
type: integer
- description: 状态
- description: 状态 (0:禁用, 1:启用)
in: query
name: status
schema:
description: 状态
description: 状态 (0:禁用, 1:启用)
maximum: 1
minimum: 0
nullable: true
@@ -1482,11 +1491,11 @@ paths:
description: 手机号模糊查询
maxLength: 20
type: string
- description: 状态
- description: 状态 (0:禁用, 1:启用)
in: query
name: status
schema:
description: 状态
description: 状态 (0:禁用, 1:启用)
maximum: 1
minimum: 0
nullable: true
@@ -2005,11 +2014,11 @@ paths:
minimum: 1
nullable: true
type: integer
- description: 状态
- description: 状态 (0:禁用, 1:启用)
in: query
name: status
schema:
description: 状态
description: 状态 (0:禁用, 1:启用)
maximum: 1
minimum: 0
nullable: true

265
docs/ai-dto-guidelines-update.md Normal file
View File

@@ -0,0 +1,265 @@
# AI 助手 DTO 规范指引更新
## 📋 更新概览
**更新日期**: 2026-01-20
**目的**: 确保未来的 AI 助手在创建/修改 DTO 时自动遵循规范
---
## ✅ 已更新的文件
### 1. `AGENTS.md`（第 96 行）
添加了完整的 **DTO 规范（重要！）** 章节，包括：
- ✅ Description 标签规范
- ✅ 枚举字段必须列出所有可能值（中文）
- ✅ 验证标签与 OpenAPI 标签一致
- ✅ 请求参数类型标签
- ✅ 响应 DTO 完整性
- ✅ **AI 助手必须执行的检查清单**
- ✅ 常见枚举字段标准值
### 2. `CLAUDE.md`（第 99 行）
添加了 **DTO 规范（API 文档生成基础）** 章节，包括：
- ✅ 所有字段必须使用 `description` 标签
- ✅ 枚举字段必须列出所有可能值（使用中文）
- ✅ validate 标签必须与 OpenAPI 标签一致
- ✅ Query 和 Path 参数必须添加对应标签
- ✅ **AI 助手在创建/修改 DTO 后必须执行的检查**
---
## 🎯 AI 助手自动检查清单
未来的 AI 助手在创建或修改任何 DTO 文件后，会**自动执行**以下检查：
### 必须执行的检查（来自 AGENTS.md）
```markdown
1. ✅ 检查所有字段是否有 `description` 标签
2. ✅ 检查枚举字段是否列出了所有可能值（中文）
3. ✅ 检查状态字段是否说明了 0 和 1 的含义
4. ✅ 检查 validate 标签与 OpenAPI 标签是否一致
5. ✅ 检查是否禁止使用行内注释替代 description
6. ✅ 检查枚举值是否使用中文而非英文
7. ✅ 重新生成 OpenAPI 文档验证：`go run cmd/gendocs/main.go`
```
### 详细检查清单位置
- **完整清单**: `docs/code-review-checklist.md`
- **在线引用**: 两个文件都包含此引用
---
## 📚 标准枚举值参考
两个文件都包含了常见枚举字段的标准值：
```go
// 用户类型
description:"用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)"
// 角色类型
description:"角色类型 (1:平台角色, 2:客户角色)"
// 权限类型
description:"权限类型 (1:菜单, 2:按钮)"
// 适用端口
description:"适用端口 (all:全部, web:Web后台, h5:H5端)"
// 状态
description:"状态 (0:禁用, 1:启用)"
// 店铺层级
description:"店铺层级 (1-7级)"
```
---
## 🔄 工作流程
### 1. AI 助手创建/修改 DTO 文件
```go
type CreateAccountRequest struct {
Username string `json:"username" validate:"required,min=3,max=50" required:"true" minLength:"3" maxLength:"50" description:"用户名"`
UserType int `json:"user_type" validate:"required,min=1,max=4" required:"true" minimum:"1" maximum:"4" description:"用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)"`
Status int `json:"status" validate:"required,min=0,max=1" required:"true" minimum:"0" maximum:"1" description:"状态 (0:禁用, 1:启用)"`
}
```
### 2. AI 助手自动执行检查
根据 `AGENTS.md` 和 `CLAUDE.md` 中的指引，AI 会：
- ✅ 验证所有字段都有 `description` 标签
- ✅ 验证枚举字段包含完整的中文说明
- ✅ 验证 validate 和 OpenAPI 标签一致性
- ✅ 执行 `go run cmd/gendocs/main.go` 生成文档
### 3. AI 助手验证生成的文档
```bash
# 检查用户类型字段
grep -A 3 "user_type:" docs/admin-openapi.yaml
# 输出应该包含完整的中文枚举说明：
# description: 用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)
```
### 4. AI 助手报告检查结果
AI 会主动告知用户：
- ✅ 所有 DTO 字段都符合规范
- ✅ OpenAPI 文档已重新生成
- ✅ 所有枚举值使用中文说明
---
## 📊 对比：更新前 vs 更新后
### 更新前 ❌
**AI 助手行为**：
- ❌ 可能忘记添加 `description` 标签
- ❌ 可能使用英文枚举值
- ❌ 可能使用行内注释而非 `description`
- ❌ 不会自动验证文档生成
**开发者需要**：
- 🔧 手动检查每个 DTO 文件
- 🔧 手动修复不符合规范的字段
- 🔧 手动重新生成文档
### 更新后 ✅
**AI 助手行为**：
- ✅ **自动**为所有字段添加 `description` 标签
- ✅ **自动**使用中文枚举值
- ✅ **自动**确保 validate 和 OpenAPI 标签一致
- ✅ **自动**重新生成并验证文档
**开发者只需**：
- 👀 Code Review 时参考 `docs/code-review-checklist.md`
- ✅ 信任 AI 已按规范执行
---
## 🎓 示例：AI 助手的标准操作流程
### 用户请求
```
"请创建一个企业管理的 DTO，包括创建、更新和列表查询"
```
### AI 助手执行步骤
1. **读取规范**（自动）
- 从 `AGENTS.md` 或 `CLAUDE.md` 读取 DTO 规范
- 了解必须遵循的标签格式
2. **创建 DTO**（遵循规范）
```go
type CreateEnterpriseRequest struct {
EnterpriseName string `json:"enterprise_name" validate:"required" required:"true" description:"企业名称"`
Status int `json:"status" validate:"required,min=0,max=1" required:"true" description:"状态 (0:禁用, 1:启用)"`
}
```
3. **执行检查**（自动）
- ✅ 所有字段都有 `description`
- ✅ Status 字段说明了 0/1 含义
- ✅ validate 和 OpenAPI 标签一致
4. **生成文档**（自动）
```bash
go run cmd/gendocs/main.go
```
5. **验证文档**（自动）
```bash
grep "状态" docs/admin-openapi.yaml
# 确认输出包含: description: 状态 (0:禁用, 1:启用)
```
6. **报告完成**（主动告知用户）
```
✅ 已创建 enterprise_dto.go
✅ 所有字段都符合 DTO 规范
✅ OpenAPI 文档已更新（docs/admin-openapi.yaml）
✅ 所有枚举值使用中文说明
```
---
## 🔗 相关文档
| 文档 | 路径 | 说明 |
|------|------|------|
| AI 开发规范 | `AGENTS.md` | 包含 DTO 规范和检查清单（第 96 行） |
| Claude 规范 | `CLAUDE.md` | 包含 DTO 规范和检查清单（第 99 行） |
| Code Review 清单 | `docs/code-review-checklist.md` | 完整的检查清单 |
| DTO 改进总结 | `docs/dto-improvement-summary.md` | 本次修复的详细记录 |
| OpenAPI 文档 | `docs/admin-openapi.yaml` | 自动生成的 API 文档 |
---
## 🎯 预期效果
### 对未来 AI 助手的影响
1. ✅ **自动合规**：所有新建的 DTO 自动符合规范
2. ✅ **减少返工**：不再需要手动修复不规范的代码
3. ✅ **文档同步**：代码即文档，文档永远是最新的
4. ✅ **一致性**：所有枚举字段使用统一的中文说明格式
### 对开发团队的影响
1. ✅ **Code Review 简化**：只需对照 `docs/code-review-checklist.md` 快速检查
2. ✅ **前端友好**：API 文档清晰，前端开发效率提升
3. ✅ **新人友好**：规范明确，容易上手
4. ✅ **维护成本降低**：规范统一，代码可读性强
---
## 📈 统计数据
### 文件更新统计
| 文件 | 添加行数 | 章节 | 位置 |
|------|---------|------|------|
| `AGENTS.md` | ~120 行 | DTO 规范（重要！） | 第 96 行 |
| `CLAUDE.md` | ~30 行 | DTO 规范（API 文档生成基础） | 第 99 行 |
### 覆盖的检查项
- ✅ **7 个自动检查项**（AGENTS.md）
- ✅ **5 个核心规范点**（CLAUDE.md）
- ✅ **6 种标准枚举类型**
---
## 🚀 下一步
### 立即生效
- ✅ 未来所有与此项目交互的 AI 助手都会自动读取这些规范
- ✅ 新建或修改 DTO 时会自动执行检查
- ✅ 文档生成和验证自动化
### 团队协作
- 📝 在 Code Review 时参考 `docs/code-review-checklist.md`
- 📝 在 PR 模板中添加"DTO 规范检查"项
- 📝 定期运行 `go run cmd/gendocs/main.go` 确保文档最新
---
**最后更新**: 2026-01-20
**维护者**: 开发团队

511
docs/api/auth.md Normal file
View File

@@ -0,0 +1,511 @@
# B 端认证 API 文档
本文档描述君鸿卡管系统 B 端认证接口（后台管理和 H5），包括登录、登出、Token 刷新、用户信息查询和密码修改功能。
---
## 概述
### 基础信息
- **后台 API 前缀**: `/api/admin`
- **H5 API 前缀**: `/api/h5`
- **认证方式**: Bearer Token (存储在 Redis)
- **Token 类型**:
- Access Token：24 小时有效期，用于 API 访问
- Refresh Token：7 天有效期，用于刷新 Access Token
### 用户类型限制
| 平台 | 允许的用户类型 |
|------|---------------|
| 后台 | SuperAdmin(1)、Platform(2)、Agent(3) |
| H5 | Agent(3)、Enterprise(4) |
---
## 公开接口（无需认证）
### 1. 用户登录
**后台**: `POST /api/admin/login`
**H5**: `POST /api/h5/login`
使用用户名或手机号 + 密码登录，返回访问令牌。
#### 请求体
```json
{
"username": "admin",
"password": "Admin@123456",
"device": "web"
}
```
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| username | string | 是 | 用户名或手机号 |
| password | string | 是 | 密码 |
| device | string | 否 | 设备标识（web/ios/android） |
#### 响应示例
**成功（200）**:
```json
{
"code": 0,
"message": "操作成功",
"data": {
"access_token": "550e8400-e29b-41d4-a716-446655440000",
"refresh_token": "660f9500-f39c-52e5-b827-557766551111",
"expires_in": 86400,
"user": {
"id": 1,
"username": "admin",
"phone": "13800000000",
"user_type": 1,
"user_type_name": "超级管理员",
"shop_id": 0,
"enterprise_id": 0
},
"permissions": [
"user:create",
"user:update",
"user:delete",
"role:manage"
]
},
"timestamp": "2026-01-15T16:05:00+08:00"
}
```
#### 错误码
| 错误码 | 消息 | 说明 |
|--------|------|------|
| 1001 | 参数验证失败 | 请求参数不完整或格式错误 |
| 1040 | 用户名或密码错误 | 凭证无效 |
| 1011 | 账号已禁用 | 账号被禁用，无法登录 |
| 1041 | 账号已锁定 | 账号被锁定 |
#### cURL 示例
```bash
# 后台登录
curl -X POST http://localhost:8080/api/admin/login \
-H "Content-Type: application/json" \
-d '{
"username": "admin",
"password": "Admin@123456",
"device": "web"
}'
# H5 登录
curl -X POST http://localhost:8080/api/h5/login \
-H "Content-Type: application/json" \
-d '{
"username": "agent001",
"password": "password123",
"device": "ios"
}'
```
---
### 2. 刷新访问令牌
**后台**: `POST /api/admin/refresh-token`
**H5**: `POST /api/h5/refresh-token`
使用 Refresh Token 获取新的 Access Token。
#### 请求体
```json
{
"refresh_token": "660f9500-f39c-52e5-b827-557766551111"
}
```
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| refresh_token | string | 是 | 刷新令牌 |
#### 响应示例
**成功（200）**:
```json
{
"code": 0,
"message": "操作成功",
"data": {
"access_token": "770a0600-a40d-63f6-c938-668877662222",
"expires_in": 86400
},
"timestamp": "2026-01-15T16:06:00+08:00"
}
```
#### 错误码
| 错误码 | 消息 | 说明 |
|--------|------|------|
| 1001 | 参数验证失败 | refresh_token 缺失 |
| 1003 | 无效或过期的令牌 | Refresh Token 无效或已过期 |
#### cURL 示例
```bash
curl -X POST http://localhost:8080/api/admin/refresh-token \
-H "Content-Type: application/json" \
-d '{
"refresh_token": "660f9500-f39c-52e5-b827-557766551111"
}'
```
---
## 受保护接口（需要认证）
所有受保护接口需在请求头中携带 Access Token：
```
Authorization: Bearer {access_token}
```
---
### 3. 用户登出
**后台**: `POST /api/admin/logout`
**H5**: `POST /api/h5/logout`
撤销当前 Access Token 和 Refresh Token（如果提供）。
#### 请求头
```
Authorization: Bearer 550e8400-e29b-41d4-a716-446655440000
```
#### 请求体（可选）
```json
{
"refresh_token": "660f9500-f39c-52e5-b827-557766551111"
}
```
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| refresh_token | string | 否 | 如果提供，同时撤销 Refresh Token |
#### 响应示例
**成功（200）**:
```json
{
"code": 0,
"message": "操作成功",
"data": null,
"timestamp": "2026-01-15T16:07:00+08:00"
}
```
#### 错误码
| 错误码 | 消息 | 说明 |
|--------|------|------|
| 1002 | 缺失认证令牌 | 请求头未携带 Authorization |
| 1003 | 无效或过期的令牌 | Access Token 无效或已过期 |
| 1004 | 未授权访问 | Token 已被撤销 |
#### cURL 示例
```bash
curl -X POST http://localhost:8080/api/admin/logout \
-H "Authorization: Bearer 550e8400-e29b-41d4-a716-446655440000" \
-H "Content-Type: application/json" \
-d '{
"refresh_token": "660f9500-f39c-52e5-b827-557766551111"
}'
```
---
### 4. 获取当前用户信息
**后台**: `GET /api/admin/me`
**H5**: `GET /api/h5/me`
获取当前登录用户的详细信息和权限列表。
#### 请求头
```
Authorization: Bearer 550e8400-e29b-41d4-a716-446655440000
```
#### 响应示例
**成功（200）**:
```json
{
"code": 0,
"message": "操作成功",
"data": {
"user": {
"id": 1,
"username": "admin",
"phone": "13800000000",
"user_type": 1,
"user_type_name": "超级管理员",
"shop_id": 0,
"enterprise_id": 0,
"status": 1,
"created_at": "2026-01-01T00:00:00+08:00"
},
"permissions": [
"user:create",
"user:update",
"user:delete",
"role:manage",
"permission:manage"
]
},
"timestamp": "2026-01-15T16:08:00+08:00"
}
```
#### 错误码
| 错误码 | 消息 | 说明 |
|--------|------|------|
| 1002 | 缺失认证令牌 | 请求头未携带 Authorization |
| 1003 | 无效或过期的令牌 | Access Token 无效或已过期 |
| 1004 | 未授权访问 | 用户信息查询失败 |
#### cURL 示例
```bash
curl -X GET http://localhost:8080/api/admin/me \
-H "Authorization: Bearer 550e8400-e29b-41d4-a716-446655440000"
```
---
### 5. 修改密码
**后台**: `POST /api/admin/password`
**H5**: `POST /api/h5/password`
修改当前用户密码，修改成功后所有旧 Token 将失效。
#### 请求头
```
Authorization: Bearer 550e8400-e29b-41d4-a716-446655440000
```
#### 请求体
```json
{
"old_password": "Admin@123456",
"new_password": "NewPassword@2026"
}
```
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| old_password | string | 是 | 当前密码 |
| new_password | string | 是 | 新密码（6-20 位，包含字母和数字） |
#### 响应示例
**成功（200）**:
```json
{
"code": 0,
"message": "操作成功",
"data": null,
"timestamp": "2026-01-15T16:09:00+08:00"
}
```
#### 错误码
| 错误码 | 消息 | 说明 |
|--------|------|------|
| 1001 | 参数验证失败 | 密码格式不符合要求 |
| 1002 | 缺失认证令牌 | 请求头未携带 Authorization |
| 1003 | 无效或过期的令牌 | Access Token 无效或已过期 |
| 1043 | 旧密码错误 | 提供的旧密码不正确 |
#### cURL 示例
```bash
curl -X POST http://localhost:8080/api/admin/password \
-H "Authorization: Bearer 550e8400-e29b-41d4-a716-446655440000" \
-H "Content-Type: application/json" \
-d '{
"old_password": "Admin@123456",
"new_password": "NewPassword@2026"
}'
```
---
## 错误码对照表
### 认证相关错误（1000-1099）
| 错误码 | 消息 | HTTP 状态码 | 说明 |
|--------|------|-------------|------|
| 1001 | 参数验证失败 | 400 | 请求参数不完整或格式错误 |
| 1002 | 缺失认证令牌 | 401 | Authorization 请求头缺失 |
| 1003 | 无效或过期的令牌 | 401 | Token 无效或已过期 |
| 1004 | 未授权访问 | 401 | 无权访问该资源 |
| 1005 | 禁止访问 | 403 | 用户类型不允许访问 |
| 1040 | 用户名或密码错误 | 401 | 登录凭证错误 |
| 1011 | 账号已禁用 | 403 | 账号被管理员禁用 |
| 1041 | 账号已锁定 | 403 | 账号因安全原因被锁定 |
| 1042 | 密码已过期 | 403 | 需要更新密码 |
| 1043 | 旧密码错误 | 400 | 修改密码时提供的旧密码不正确 |
### 服务端错误（2000-2999）
| 错误码 | 消息 | HTTP 状态码 | 说明 |
|--------|------|-------------|------|
| 2001 | 内部服务器错误 | 500 | 服务器内部错误 |
| 2002 | 数据库错误 | 500 | 数据库操作失败 |
| 2003 | Redis 错误 | 500 | Redis 操作失败 |
| 2004 | 服务不可用 | 503 | 服务暂时不可用 |
---
## 使用场景示例
### 场景 1：完整登录流程
```bash
# 1. 用户登录
curl -X POST http://localhost:8080/api/admin/login \
-H "Content-Type: application/json" \
-d '{"username":"admin","password":"Admin@123456"}' \
| jq
# 响应获取 access_token 和 refresh_token
# {
# "code": 0,
# "data": {
# "access_token": "550e8400-...",
# "refresh_token": "660f9500-..."
# }
# }
# 2. 使用 access_token 访问受保护接口
curl -X GET http://localhost:8080/api/admin/me \
-H "Authorization: Bearer 550e8400-..." \
| jq
# 3. Access Token 过期后，使用 Refresh Token 刷新
curl -X POST http://localhost:8080/api/admin/refresh-token \
-H "Content-Type: application/json" \
-d '{"refresh_token":"660f9500-..."}' \
| jq
# 4. 登出
curl -X POST http://localhost:8080/api/admin/logout \
-H "Authorization: Bearer 550e8400-..." \
-H "Content-Type: application/json" \
-d '{"refresh_token":"660f9500-..."}' \
| jq
```
### 场景 2：修改密码
```bash
# 1. 登录获取 token
TOKEN=$(curl -s -X POST http://localhost:8080/api/admin/login \
-H "Content-Type: application/json" \
-d '{"username":"admin","password":"Admin@123456"}' \
| jq -r '.data.access_token')
# 2. 修改密码
curl -X POST http://localhost:8080/api/admin/password \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"old_password": "Admin@123456",
"new_password": "NewPassword@2026"
}' \
| jq
# 3. 旧 token 失效，需要重新登录
curl -X POST http://localhost:8080/api/admin/login \
-H "Content-Type: application/json" \
-d '{"username":"admin","password":"NewPassword@2026"}' \
| jq
```
---
## 安全注意事项
1. **Token 存储**：
- 前端应将 Token 存储在安全位置（如 HttpOnly Cookie 或 secure storage）
- 不要将 Token 暴露在 URL 中
2. **Token 传输**：
- 始终使用 HTTPS 传输 Token
- Token 仅在 Authorization 请求头中传递
3. **密码要求**：
- 长度：6-20 位
- 必须包含字母和数字
- 建议包含特殊字符
4. **Token 生命周期**：
- Access Token：24 小时自动过期
- Refresh Token：7 天自动过期
- 修改密码后所有旧 Token 立即失效
5. **并发登录**：
- 系统支持同一用户多设备同时登录
- 每个设备拥有独立的 Token 对
- 登出只撤销当前设备的 Token
---
## 常见问题
**Q: 如何判断 Access Token 是否过期？**
A: 接口返回 `1003` 错误码时表示 Token 过期，应使用 Refresh Token 刷新。
**Q: Refresh Token 过期后怎么办？**
A: Refresh Token 过期后需要重新登录。
**Q: 修改密码后需要重新登录吗？**
A: 是的，修改密码后所有设备的 Token 都会失效，需要重新登录。
**Q: 后台用户可以使用 H5 接口吗？**
A: 不可以。后台和 H5 有不同的用户类型限制，使用错误的端点会返回 `1005` 错误。
**Q: 如何撤销所有设备的登录状态？**
A: 调用 `/api/admin/password` 修改密码，所有设备的 Token 会自动失效。
---
## 相关文档
- [使用指南](../auth-usage-guide.md) - 如何在代码中集成认证
- [架构说明](../auth-architecture.md) - 认证系统架构设计
- [错误处理指南](../003-error-handling/使用指南.md) - 统一错误处理
---
**文档版本**: v1.0
**最后更新**: 2026-01-15
**维护者**: 君鸿卡管系统开发团队

326
docs/code-review-checklist.md Normal file
View File

@@ -0,0 +1,326 @@
# 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
**维护者**: 开发团队

215
docs/dto-improvement-summary.md Normal file
View 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