完善 DTO 规范：统一 description 标签并添加 AI 助手自动检查指引
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 4m28s
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:
4
.gitignore
vendored
4
.gitignore
vendored
@@ -69,7 +69,7 @@ build/
|
|||||||
.claude/settings.local.json
|
.claude/settings.local.json
|
||||||
cmd/api/api
|
cmd/api/api
|
||||||
2026-01-09-local-command-caveatcaveat-the-messages-below-w.txt
|
2026-01-09-local-command-caveatcaveat-the-messages-below-w.txt
|
||||||
api
|
|
||||||
.gitignore
|
.gitignore
|
||||||
worker
|
|
||||||
ai-gateway.conf
|
ai-gateway.conf
|
||||||
|
__debug_bin1621385388
|
||||||
|
docs/admin-openapi.yaml
|
||||||
|
|||||||
138
AGENTS.md
138
AGENTS.md
@@ -93,6 +93,144 @@ Handler → Service → Store → Model
|
|||||||
- 接口命名: 使用 `-er` 后缀（Reader、Writer、Logger）
|
- 接口命名: 使用 `-er` 后缀（Reader、Writer、Logger）
|
||||||
- 缩写词: 全大写或全小写（URL、ID、HTTP 或 url、id、http）
|
- 缩写词: 全大写或全小写（URL、ID、HTTP 或 url、id、http）
|
||||||
|
|
||||||
|
## DTO 规范（重要！）
|
||||||
|
|
||||||
|
**所有 DTO 文件必须遵循以下规范，这是 API 文档生成的基础。**
|
||||||
|
|
||||||
|
### 必须项（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:企业账号)"`
|
||||||
|
|
||||||
|
// 角色类型
|
||||||
|
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端)"`
|
||||||
|
```
|
||||||
|
|
||||||
|
❌ **禁止使用英文枚举值**：
|
||||||
|
```go
|
||||||
|
UserType int `json:"user_type" description:"用户类型 (1:SuperAdmin, 2:Platform)"` // 错误！
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 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 参数必须添加对应标签**
|
||||||
|
|
||||||
|
```go
|
||||||
|
// 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` 标签**
|
||||||
|
|
||||||
|
```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:"更新时间"`
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### AI 助手必须执行的检查
|
||||||
|
|
||||||
|
**在创建或修改任何 DTO 文件后，必须执行以下检查：**
|
||||||
|
|
||||||
|
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级)"
|
||||||
|
```
|
||||||
|
|
||||||
## Model 模型规范
|
## Model 模型规范
|
||||||
|
|
||||||
**必须遵守的模型结构:**
|
**必须遵守的模型结构:**
|
||||||
|
|||||||
40
CLAUDE.md
40
CLAUDE.md
@@ -96,6 +96,46 @@ tests/
|
|||||||
- Go 文档注释（doc comments for exported APIs）可以使用英文以保持生态兼容性，但中文注释更佳
|
- Go 文档注释（doc comments for exported APIs）可以使用英文以保持生态兼容性，但中文注释更佳
|
||||||
- 变量名、函数名、类型名必须使用英文（遵循 Go 命名规范）
|
- 变量名、函数名、类型名必须使用英文（遵循 Go 命名规范）
|
||||||
|
|
||||||
|
**DTO 规范（API 文档生成基础）:**
|
||||||
|
|
||||||
|
所有 DTO 文件必须严格遵循以下规范，这是 OpenAPI 文档自动生成的基础：
|
||||||
|
|
||||||
|
1. **所有字段必须使用 `description` 标签**（禁止使用行内注释）
|
||||||
|
```go
|
||||||
|
// ✅ 正确
|
||||||
|
Username string `json:"username" description:"用户名"`
|
||||||
|
|
||||||
|
// ❌ 错误
|
||||||
|
Username string `json:"username"` // 用户名
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **枚举字段必须列出所有可能值（使用中文）**
|
||||||
|
```go
|
||||||
|
UserType int `json:"user_type" description:"用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)"`
|
||||||
|
Status int `json:"status" description:"状态 (0:禁用, 1:启用)"`
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **validate 标签必须与 OpenAPI 标签一致**
|
||||||
|
```go
|
||||||
|
Username string `json:"username" validate:"required,min=3,max=50" required:"true" minLength:"3" maxLength:"50" description:"用户名"`
|
||||||
|
```
|
||||||
|
|
||||||
|
4. **Query 和 Path 参数必须添加对应标签**
|
||||||
|
```go
|
||||||
|
Page int `json:"page" query:"page" description:"页码"`
|
||||||
|
ID uint `path:"id" description:"ID" required:"true"`
|
||||||
|
```
|
||||||
|
|
||||||
|
5. **AI 助手在创建/修改 DTO 后必须执行以下检查**：
|
||||||
|
- ✅ 所有字段都有 `description` 标签
|
||||||
|
- ✅ 枚举字段列出了所有可能值（中文）
|
||||||
|
- ✅ 状态字段说明了 0 和 1 的含义
|
||||||
|
- ✅ validate 标签与 OpenAPI 标签一致
|
||||||
|
- ✅ 禁止使用英文枚举值
|
||||||
|
- ✅ 重新生成文档验证：`go run cmd/gendocs/main.go`
|
||||||
|
|
||||||
|
详细规范参见：`docs/code-review-checklist.md`
|
||||||
|
|
||||||
**Go 代码风格要求:**
|
**Go 代码风格要求:**
|
||||||
|
|
||||||
- 必须使用 `gofmt` 格式化所有代码
|
- 必须使用 `gofmt` 格式化所有代码
|
||||||
|
|||||||
@@ -62,7 +62,7 @@ components:
|
|||||||
nullable: true
|
nullable: true
|
||||||
type: integer
|
type: integer
|
||||||
status:
|
status:
|
||||||
description: 状态
|
description: 状态 (0:禁用, 1:启用)
|
||||||
type: integer
|
type: integer
|
||||||
updated_at:
|
updated_at:
|
||||||
description: 更新时间
|
description: 更新时间
|
||||||
@@ -72,7 +72,7 @@ components:
|
|||||||
minimum: 0
|
minimum: 0
|
||||||
type: integer
|
type: integer
|
||||||
user_type:
|
user_type:
|
||||||
description: 用户类型
|
description: 用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)
|
||||||
type: integer
|
type: integer
|
||||||
username:
|
username:
|
||||||
description: 用户名
|
description: 用户名
|
||||||
@@ -131,7 +131,7 @@ components:
|
|||||||
nullable: true
|
nullable: true
|
||||||
type: integer
|
type: integer
|
||||||
user_type:
|
user_type:
|
||||||
description: 用户类型 (1:SuperAdmin, 2:Platform, 3:Agent, 4:Enterprise)
|
description: 用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)
|
||||||
maximum: 4
|
maximum: 4
|
||||||
minimum: 1
|
minimum: 1
|
||||||
type: integer
|
type: integer
|
||||||
@@ -279,7 +279,7 @@ components:
|
|||||||
ModelPermissionResponse:
|
ModelPermissionResponse:
|
||||||
properties:
|
properties:
|
||||||
available_for_role_types:
|
available_for_role_types:
|
||||||
description: 可用角色类型
|
description: 可用角色类型 (1:平台角色, 2:客户角色)
|
||||||
type: string
|
type: string
|
||||||
created_at:
|
created_at:
|
||||||
description: 创建时间
|
description: 创建时间
|
||||||
@@ -304,16 +304,16 @@ components:
|
|||||||
description: 权限名称
|
description: 权限名称
|
||||||
type: string
|
type: string
|
||||||
perm_type:
|
perm_type:
|
||||||
description: 权限类型
|
description: 权限类型 (1:菜单, 2:按钮)
|
||||||
type: integer
|
type: integer
|
||||||
platform:
|
platform:
|
||||||
description: 适用端口
|
description: 适用端口 (all:全部, web:Web后台, h5:H5端)
|
||||||
type: string
|
type: string
|
||||||
sort:
|
sort:
|
||||||
description: 排序值
|
description: 排序值
|
||||||
type: integer
|
type: integer
|
||||||
status:
|
status:
|
||||||
description: 状态
|
description: 状态 (0:禁用, 1:启用)
|
||||||
type: integer
|
type: integer
|
||||||
updated_at:
|
updated_at:
|
||||||
description: 更新时间
|
description: 更新时间
|
||||||
@@ -329,7 +329,7 @@ components:
|
|||||||
ModelPermissionTreeNode:
|
ModelPermissionTreeNode:
|
||||||
properties:
|
properties:
|
||||||
available_for_role_types:
|
available_for_role_types:
|
||||||
description: 可用角色类型
|
description: 可用角色类型 (1:平台角色, 2:客户角色)
|
||||||
type: string
|
type: string
|
||||||
children:
|
children:
|
||||||
description: 子权限列表
|
description: 子权限列表
|
||||||
@@ -347,10 +347,10 @@ components:
|
|||||||
description: 权限名称
|
description: 权限名称
|
||||||
type: string
|
type: string
|
||||||
perm_type:
|
perm_type:
|
||||||
description: 权限类型
|
description: 权限类型 (1:菜单, 2:按钮)
|
||||||
type: integer
|
type: integer
|
||||||
platform:
|
platform:
|
||||||
description: 适用端口
|
description: 适用端口 (all:全部, web:Web后台, h5:H5端)
|
||||||
type: string
|
type: string
|
||||||
sort:
|
sort:
|
||||||
description: 排序值
|
description: 排序值
|
||||||
@@ -426,10 +426,10 @@ components:
|
|||||||
description: 角色名称
|
description: 角色名称
|
||||||
type: string
|
type: string
|
||||||
role_type:
|
role_type:
|
||||||
description: 角色类型
|
description: 角色类型 (1:平台角色, 2:客户角色)
|
||||||
type: integer
|
type: integer
|
||||||
status:
|
status:
|
||||||
description: 状态
|
description: 状态 (0:禁用, 1:启用)
|
||||||
type: integer
|
type: integer
|
||||||
updated_at:
|
updated_at:
|
||||||
description: 更新时间
|
description: 更新时间
|
||||||
@@ -559,25 +559,34 @@ components:
|
|||||||
ModelUserInfo:
|
ModelUserInfo:
|
||||||
properties:
|
properties:
|
||||||
enterprise_id:
|
enterprise_id:
|
||||||
|
description: 企业ID
|
||||||
minimum: 0
|
minimum: 0
|
||||||
type: integer
|
type: integer
|
||||||
enterprise_name:
|
enterprise_name:
|
||||||
|
description: 企业名称
|
||||||
type: string
|
type: string
|
||||||
id:
|
id:
|
||||||
|
description: 用户ID
|
||||||
minimum: 0
|
minimum: 0
|
||||||
type: integer
|
type: integer
|
||||||
phone:
|
phone:
|
||||||
|
description: 手机号
|
||||||
type: string
|
type: string
|
||||||
shop_id:
|
shop_id:
|
||||||
|
description: 店铺ID
|
||||||
minimum: 0
|
minimum: 0
|
||||||
type: integer
|
type: integer
|
||||||
shop_name:
|
shop_name:
|
||||||
|
description: 店铺名称
|
||||||
type: string
|
type: string
|
||||||
user_type:
|
user_type:
|
||||||
|
description: 用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)
|
||||||
type: integer
|
type: integer
|
||||||
user_type_name:
|
user_type_name:
|
||||||
|
description: 用户类型名称
|
||||||
type: string
|
type: string
|
||||||
username:
|
username:
|
||||||
|
description: 用户名
|
||||||
type: string
|
type: string
|
||||||
type: object
|
type: object
|
||||||
securitySchemes:
|
securitySchemes:
|
||||||
@@ -622,20 +631,20 @@ paths:
|
|||||||
description: 手机号模糊查询
|
description: 手机号模糊查询
|
||||||
maxLength: 20
|
maxLength: 20
|
||||||
type: string
|
type: string
|
||||||
- description: 用户类型
|
- description: 用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)
|
||||||
in: query
|
in: query
|
||||||
name: user_type
|
name: user_type
|
||||||
schema:
|
schema:
|
||||||
description: 用户类型
|
description: 用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)
|
||||||
maximum: 4
|
maximum: 4
|
||||||
minimum: 1
|
minimum: 1
|
||||||
nullable: true
|
nullable: true
|
||||||
type: integer
|
type: integer
|
||||||
- description: 状态
|
- description: 状态 (0:禁用, 1:启用)
|
||||||
in: query
|
in: query
|
||||||
name: status
|
name: status
|
||||||
schema:
|
schema:
|
||||||
description: 状态
|
description: 状态 (0:禁用, 1:启用)
|
||||||
maximum: 1
|
maximum: 1
|
||||||
minimum: 0
|
minimum: 0
|
||||||
nullable: true
|
nullable: true
|
||||||
@@ -1153,20 +1162,20 @@ paths:
|
|||||||
description: 权限编码模糊查询
|
description: 权限编码模糊查询
|
||||||
maxLength: 100
|
maxLength: 100
|
||||||
type: string
|
type: string
|
||||||
- description: 权限类型
|
- description: 权限类型 (1:菜单, 2:按钮)
|
||||||
in: query
|
in: query
|
||||||
name: perm_type
|
name: perm_type
|
||||||
schema:
|
schema:
|
||||||
description: 权限类型
|
description: 权限类型 (1:菜单, 2:按钮)
|
||||||
maximum: 2
|
maximum: 2
|
||||||
minimum: 1
|
minimum: 1
|
||||||
nullable: true
|
nullable: true
|
||||||
type: integer
|
type: integer
|
||||||
- description: 适用端口
|
- description: 适用端口 (all:全部, web:Web后台, h5:H5端)
|
||||||
in: query
|
in: query
|
||||||
name: platform
|
name: platform
|
||||||
schema:
|
schema:
|
||||||
description: 适用端口
|
description: 适用端口 (all:全部, web:Web后台, h5:H5端)
|
||||||
type: string
|
type: string
|
||||||
- description: 可用角色类型 (1:平台角色, 2:客户角色)
|
- description: 可用角色类型 (1:平台角色, 2:客户角色)
|
||||||
in: query
|
in: query
|
||||||
@@ -1185,11 +1194,11 @@ paths:
|
|||||||
minimum: 0
|
minimum: 0
|
||||||
nullable: true
|
nullable: true
|
||||||
type: integer
|
type: integer
|
||||||
- description: 状态
|
- description: 状态 (0:禁用, 1:启用)
|
||||||
in: query
|
in: query
|
||||||
name: status
|
name: status
|
||||||
schema:
|
schema:
|
||||||
description: 状态
|
description: 状态 (0:禁用, 1:启用)
|
||||||
maximum: 1
|
maximum: 1
|
||||||
minimum: 0
|
minimum: 0
|
||||||
nullable: true
|
nullable: true
|
||||||
@@ -1482,11 +1491,11 @@ paths:
|
|||||||
description: 手机号模糊查询
|
description: 手机号模糊查询
|
||||||
maxLength: 20
|
maxLength: 20
|
||||||
type: string
|
type: string
|
||||||
- description: 状态
|
- description: 状态 (0:禁用, 1:启用)
|
||||||
in: query
|
in: query
|
||||||
name: status
|
name: status
|
||||||
schema:
|
schema:
|
||||||
description: 状态
|
description: 状态 (0:禁用, 1:启用)
|
||||||
maximum: 1
|
maximum: 1
|
||||||
minimum: 0
|
minimum: 0
|
||||||
nullable: true
|
nullable: true
|
||||||
@@ -2005,11 +2014,11 @@ paths:
|
|||||||
minimum: 1
|
minimum: 1
|
||||||
nullable: true
|
nullable: true
|
||||||
type: integer
|
type: integer
|
||||||
- description: 状态
|
- description: 状态 (0:禁用, 1:启用)
|
||||||
in: query
|
in: query
|
||||||
name: status
|
name: status
|
||||||
schema:
|
schema:
|
||||||
description: 状态
|
description: 状态 (0:禁用, 1:启用)
|
||||||
maximum: 1
|
maximum: 1
|
||||||
minimum: 0
|
minimum: 0
|
||||||
nullable: true
|
nullable: true
|
||||||
|
|||||||
265
docs/ai-dto-guidelines-update.md
Normal file
265
docs/ai-dto-guidelines-update.md
Normal 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
511
docs/api/auth.md
Normal 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
326
docs/code-review-checklist.md
Normal 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
215
docs/dto-improvement-summary.md
Normal 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
|
||||||
@@ -5,7 +5,7 @@ type CreateAccountRequest struct {
|
|||||||
Username string `json:"username" validate:"required,min=3,max=50" required:"true" minLength:"3" maxLength:"50" description:"用户名"`
|
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:"手机号"`
|
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:"密码"`
|
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（代理账号必填）"`
|
ShopID *uint `json:"shop_id" description:"关联店铺ID（代理账号必填）"`
|
||||||
EnterpriseID *uint `json:"enterprise_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:"每页数量"`
|
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:"用户名模糊查询"`
|
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:"手机号模糊查询"`
|
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:"用户类型"`
|
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:"状态"`
|
Status *int `json:"status" query:"status" validate:"omitempty,min=0,max=1" minimum:"0" maximum:"1" description:"状态 (0:禁用, 1:启用)"`
|
||||||
}
|
}
|
||||||
|
|
||||||
// AccountResponse 账号响应
|
// AccountResponse 账号响应
|
||||||
@@ -33,10 +33,10 @@ type AccountResponse struct {
|
|||||||
ID uint `json:"id" description:"账号ID"`
|
ID uint `json:"id" description:"账号ID"`
|
||||||
Username string `json:"username" description:"用户名"`
|
Username string `json:"username" description:"用户名"`
|
||||||
Phone string `json:"phone" 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"`
|
ShopID *uint `json:"shop_id,omitempty" description:"关联店铺ID"`
|
||||||
EnterpriseID *uint `json:"enterprise_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"`
|
Creator uint `json:"creator" description:"创建人ID"`
|
||||||
Updater uint `json:"updater" description:"更新人ID"`
|
Updater uint `json:"updater" description:"更新人ID"`
|
||||||
CreatedAt string `json:"created_at" description:"创建时间"`
|
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:"每页数量"`
|
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:"用户名模糊查询"`
|
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:"手机号模糊查询"`
|
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 生成）
|
// UpdatePasswordParams 修改密码参数（用于 OpenAPI 生成）
|
||||||
|
|||||||
@@ -2,15 +2,15 @@ package model
|
|||||||
|
|
||||||
// AccountRoleResponse 账号-角色关联响应
|
// AccountRoleResponse 账号-角色关联响应
|
||||||
type AccountRoleResponse struct {
|
type AccountRoleResponse struct {
|
||||||
ID uint `json:"id"`
|
ID uint `json:"id" description:"关联ID"`
|
||||||
AccountID uint `json:"account_id"`
|
AccountID uint `json:"account_id" description:"账号ID"`
|
||||||
RoleID uint `json:"role_id"`
|
RoleID uint `json:"role_id" description:"角色ID"`
|
||||||
Status int `json:"status"`
|
Status int `json:"status" description:"状态 (0:禁用, 1:启用)"`
|
||||||
CreatedAt string `json:"created_at"`
|
CreatedAt string `json:"created_at" description:"创建时间"`
|
||||||
}
|
}
|
||||||
|
|
||||||
// AccountRolesResponse 账号的角色列表响应
|
// AccountRolesResponse 账号的角色列表响应
|
||||||
type AccountRolesResponse struct {
|
type AccountRolesResponse struct {
|
||||||
AccountID uint `json:"account_id"`
|
AccountID uint `json:"account_id" description:"账号ID"`
|
||||||
Roles []*RoleResponse `json:"roles"`
|
Roles []*RoleResponse `json:"roles" description:"角色列表"`
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -15,15 +15,15 @@ type LoginResponse struct {
|
|||||||
}
|
}
|
||||||
|
|
||||||
type UserInfo struct {
|
type UserInfo struct {
|
||||||
ID uint `json:"id"`
|
ID uint `json:"id" description:"用户ID"`
|
||||||
Username string `json:"username"`
|
Username string `json:"username" description:"用户名"`
|
||||||
Phone string `json:"phone"`
|
Phone string `json:"phone" description:"手机号"`
|
||||||
UserType int `json:"user_type"`
|
UserType int `json:"user_type" description:"用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)"`
|
||||||
UserTypeName string `json:"user_type_name"`
|
UserTypeName string `json:"user_type_name" description:"用户类型名称"`
|
||||||
ShopID uint `json:"shop_id,omitempty"`
|
ShopID uint `json:"shop_id,omitempty" description:"店铺ID"`
|
||||||
ShopName string `json:"shop_name,omitempty"`
|
ShopName string `json:"shop_name,omitempty" description:"店铺名称"`
|
||||||
EnterpriseID uint `json:"enterprise_id,omitempty"`
|
EnterpriseID uint `json:"enterprise_id,omitempty" description:"企业ID"`
|
||||||
EnterpriseName string `json:"enterprise_name,omitempty"`
|
EnterpriseName string `json:"enterprise_name,omitempty" description:"企业名称"`
|
||||||
}
|
}
|
||||||
|
|
||||||
type RefreshTokenRequest struct {
|
type RefreshTokenRequest struct {
|
||||||
|
|||||||
@@ -2,48 +2,48 @@ package model
|
|||||||
|
|
||||||
// CreateEnterpriseRequest 创建企业请求
|
// CreateEnterpriseRequest 创建企业请求
|
||||||
type CreateEnterpriseRequest struct {
|
type CreateEnterpriseRequest struct {
|
||||||
EnterpriseName string `json:"enterprise_name" validate:"required"` // 企业名称
|
EnterpriseName string `json:"enterprise_name" validate:"required" required:"true" description:"企业名称"`
|
||||||
EnterpriseCode string `json:"enterprise_code"` // 企业编号
|
EnterpriseCode string `json:"enterprise_code" description:"企业编号"`
|
||||||
OwnerShopID *uint `json:"owner_shop_id"` // 归属店铺ID
|
OwnerShopID *uint `json:"owner_shop_id" description:"归属店铺ID（可不填则归属平台）"`
|
||||||
LegalPerson string `json:"legal_person"` // 法人代表
|
LegalPerson string `json:"legal_person" description:"法人代表"`
|
||||||
ContactName string `json:"contact_name"` // 联系人姓名
|
ContactName string `json:"contact_name" description:"联系人姓名"`
|
||||||
ContactPhone string `json:"contact_phone"` // 联系人电话
|
ContactPhone string `json:"contact_phone" description:"联系人电话"`
|
||||||
BusinessLicense string `json:"business_license"` // 营业执照号
|
BusinessLicense string `json:"business_license" description:"营业执照号"`
|
||||||
Province string `json:"province"` // 省份
|
Province string `json:"province" description:"省份"`
|
||||||
City string `json:"city"` // 城市
|
City string `json:"city" description:"城市"`
|
||||||
District string `json:"district"` // 区县
|
District string `json:"district" description:"区县"`
|
||||||
Address string `json:"address"` // 详细地址
|
Address string `json:"address" description:"详细地址"`
|
||||||
}
|
}
|
||||||
|
|
||||||
// UpdateEnterpriseRequest 更新企业请求
|
// UpdateEnterpriseRequest 更新企业请求
|
||||||
type UpdateEnterpriseRequest struct {
|
type UpdateEnterpriseRequest struct {
|
||||||
EnterpriseName *string `json:"enterprise_name"` // 企业名称
|
EnterpriseName *string `json:"enterprise_name" description:"企业名称"`
|
||||||
EnterpriseCode *string `json:"enterprise_code"` // 企业编号
|
EnterpriseCode *string `json:"enterprise_code" description:"企业编号"`
|
||||||
LegalPerson *string `json:"legal_person"` // 法人代表
|
LegalPerson *string `json:"legal_person" description:"法人代表"`
|
||||||
ContactName *string `json:"contact_name"` // 联系人姓名
|
ContactName *string `json:"contact_name" description:"联系人姓名"`
|
||||||
ContactPhone *string `json:"contact_phone"` // 联系人电话
|
ContactPhone *string `json:"contact_phone" description:"联系人电话"`
|
||||||
BusinessLicense *string `json:"business_license"` // 营业执照号
|
BusinessLicense *string `json:"business_license" description:"营业执照号"`
|
||||||
Province *string `json:"province"` // 省份
|
Province *string `json:"province" description:"省份"`
|
||||||
City *string `json:"city"` // 城市
|
City *string `json:"city" description:"城市"`
|
||||||
District *string `json:"district"` // 区县
|
District *string `json:"district" description:"区县"`
|
||||||
Address *string `json:"address"` // 详细地址
|
Address *string `json:"address" description:"详细地址"`
|
||||||
}
|
}
|
||||||
|
|
||||||
// EnterpriseResponse 企业响应
|
// EnterpriseResponse 企业响应
|
||||||
type EnterpriseResponse struct {
|
type EnterpriseResponse struct {
|
||||||
ID uint `json:"id"`
|
ID uint `json:"id" description:"企业ID"`
|
||||||
EnterpriseName string `json:"enterprise_name"`
|
EnterpriseName string `json:"enterprise_name" description:"企业名称"`
|
||||||
EnterpriseCode string `json:"enterprise_code"`
|
EnterpriseCode string `json:"enterprise_code" description:"企业编号"`
|
||||||
OwnerShopID *uint `json:"owner_shop_id,omitempty"`
|
OwnerShopID *uint `json:"owner_shop_id,omitempty" description:"归属店铺ID"`
|
||||||
LegalPerson string `json:"legal_person"`
|
LegalPerson string `json:"legal_person" description:"法人代表"`
|
||||||
ContactName string `json:"contact_name"`
|
ContactName string `json:"contact_name" description:"联系人姓名"`
|
||||||
ContactPhone string `json:"contact_phone"`
|
ContactPhone string `json:"contact_phone" description:"联系人电话"`
|
||||||
BusinessLicense string `json:"business_license"`
|
BusinessLicense string `json:"business_license" description:"营业执照号"`
|
||||||
Province string `json:"province"`
|
Province string `json:"province" description:"省份"`
|
||||||
City string `json:"city"`
|
City string `json:"city" description:"城市"`
|
||||||
District string `json:"district"`
|
District string `json:"district" description:"区县"`
|
||||||
Address string `json:"address"`
|
Address string `json:"address" description:"详细地址"`
|
||||||
Status int `json:"status"`
|
Status int `json:"status" description:"状态 (0:禁用, 1:启用)"`
|
||||||
CreatedAt string `json:"created_at"`
|
CreatedAt string `json:"created_at" description:"创建时间"`
|
||||||
UpdatedAt string `json:"updated_at"`
|
UpdatedAt string `json:"updated_at" description:"更新时间"`
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -34,11 +34,11 @@ type PermissionListRequest struct {
|
|||||||
PageSize int `json:"page_size" query:"page_size" validate:"omitempty,min=1,max=100" minimum:"1" maximum:"100" description:"每页数量"`
|
PageSize int `json:"page_size" query:"page_size" validate:"omitempty,min=1,max=100" minimum:"1" maximum:"100" description:"每页数量"`
|
||||||
PermName string `json:"perm_name" query:"perm_name" validate:"omitempty,max=50" maxLength:"50" description:"权限名称模糊查询"`
|
PermName string `json:"perm_name" query:"perm_name" validate:"omitempty,max=50" maxLength:"50" description:"权限名称模糊查询"`
|
||||||
PermCode string `json:"perm_code" query:"perm_code" validate:"omitempty,max=100" maxLength:"100" description:"权限编码模糊查询"`
|
PermCode string `json:"perm_code" query:"perm_code" validate:"omitempty,max=100" maxLength:"100" description:"权限编码模糊查询"`
|
||||||
PermType *int `json:"perm_type" query:"perm_type" validate:"omitempty,min=1,max=2" minimum:"1" maximum:"2" description:"权限类型"`
|
PermType *int `json:"perm_type" query:"perm_type" validate:"omitempty,min=1,max=2" minimum:"1" maximum:"2" description:"权限类型 (1:菜单, 2:按钮)"`
|
||||||
Platform string `json:"platform" query:"platform" validate:"omitempty,oneof=all web h5" description:"适用端口"`
|
Platform string `json:"platform" query:"platform" validate:"omitempty,oneof=all web h5" description:"适用端口 (all:全部, web:Web后台, h5:H5端)"`
|
||||||
AvailableForRoleType *int `json:"available_for_role_type" query:"available_for_role_type" validate:"omitempty,min=1,max=2" minimum:"1" maximum:"2" description:"可用角色类型 (1:平台角色, 2:客户角色)"`
|
AvailableForRoleType *int `json:"available_for_role_type" query:"available_for_role_type" validate:"omitempty,min=1,max=2" minimum:"1" maximum:"2" description:"可用角色类型 (1:平台角色, 2:客户角色)"`
|
||||||
ParentID *uint `json:"parent_id" query:"parent_id" description:"父权限ID"`
|
ParentID *uint `json:"parent_id" query:"parent_id" description:"父权限ID"`
|
||||||
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:启用)"`
|
||||||
}
|
}
|
||||||
|
|
||||||
// PermissionResponse 权限响应
|
// PermissionResponse 权限响应
|
||||||
@@ -46,13 +46,13 @@ type PermissionResponse struct {
|
|||||||
ID uint `json:"id" description:"权限ID"`
|
ID uint `json:"id" description:"权限ID"`
|
||||||
PermName string `json:"perm_name" description:"权限名称"`
|
PermName string `json:"perm_name" description:"权限名称"`
|
||||||
PermCode string `json:"perm_code" description:"权限编码"`
|
PermCode string `json:"perm_code" description:"权限编码"`
|
||||||
PermType int `json:"perm_type" description:"权限类型"`
|
PermType int `json:"perm_type" description:"权限类型 (1:菜单, 2:按钮)"`
|
||||||
Platform string `json:"platform" description:"适用端口"`
|
Platform string `json:"platform" description:"适用端口 (all:全部, web:Web后台, h5:H5端)"`
|
||||||
AvailableForRoleTypes string `json:"available_for_role_types" description:"可用角色类型"`
|
AvailableForRoleTypes string `json:"available_for_role_types" description:"可用角色类型 (1:平台角色, 2:客户角色)"`
|
||||||
URL string `json:"url,omitempty" description:"请求路径"`
|
URL string `json:"url,omitempty" description:"请求路径"`
|
||||||
ParentID *uint `json:"parent_id,omitempty" description:"父权限ID"`
|
ParentID *uint `json:"parent_id,omitempty" description:"父权限ID"`
|
||||||
Sort int `json:"sort" description:"排序值"`
|
Sort int `json:"sort" description:"排序值"`
|
||||||
Status int `json:"status" description:"状态"`
|
Status int `json:"status" description:"状态 (0:禁用, 1:启用)"`
|
||||||
Creator uint `json:"creator" description:"创建人ID"`
|
Creator uint `json:"creator" description:"创建人ID"`
|
||||||
Updater uint `json:"updater" description:"更新人ID"`
|
Updater uint `json:"updater" description:"更新人ID"`
|
||||||
CreatedAt string `json:"created_at" description:"创建时间"`
|
CreatedAt string `json:"created_at" description:"创建时间"`
|
||||||
@@ -72,9 +72,9 @@ type PermissionTreeNode struct {
|
|||||||
ID uint `json:"id" description:"权限ID"`
|
ID uint `json:"id" description:"权限ID"`
|
||||||
PermName string `json:"perm_name" description:"权限名称"`
|
PermName string `json:"perm_name" description:"权限名称"`
|
||||||
PermCode string `json:"perm_code" description:"权限编码"`
|
PermCode string `json:"perm_code" description:"权限编码"`
|
||||||
PermType int `json:"perm_type" description:"权限类型"`
|
PermType int `json:"perm_type" description:"权限类型 (1:菜单, 2:按钮)"`
|
||||||
Platform string `json:"platform" description:"适用端口"`
|
Platform string `json:"platform" description:"适用端口 (all:全部, web:Web后台, h5:H5端)"`
|
||||||
AvailableForRoleTypes string `json:"available_for_role_types" description:"可用角色类型"`
|
AvailableForRoleTypes string `json:"available_for_role_types" description:"可用角色类型 (1:平台角色, 2:客户角色)"`
|
||||||
URL string `json:"url,omitempty" description:"请求路径"`
|
URL string `json:"url,omitempty" description:"请求路径"`
|
||||||
Sort int `json:"sort" description:"排序值"`
|
Sort int `json:"sort" description:"排序值"`
|
||||||
Children []*PermissionTreeNode `json:"children,omitempty" description:"子权限列表"`
|
Children []*PermissionTreeNode `json:"children,omitempty" description:"子权限列表"`
|
||||||
|
|||||||
@@ -2,29 +2,29 @@ package model
|
|||||||
|
|
||||||
// CreatePersonalCustomerRequest 创建个人客户请求
|
// CreatePersonalCustomerRequest 创建个人客户请求
|
||||||
type CreatePersonalCustomerRequest struct {
|
type CreatePersonalCustomerRequest struct {
|
||||||
Phone string `json:"phone" validate:"required"` // 手机号
|
Phone string `json:"phone" validate:"required" required:"true" description:"手机号"`
|
||||||
Nickname string `json:"nickname"` // 昵称
|
Nickname string `json:"nickname" description:"昵称"`
|
||||||
AvatarURL string `json:"avatar_url"` // 头像URL
|
AvatarURL string `json:"avatar_url" description:"头像URL"`
|
||||||
WxOpenID string `json:"wx_open_id"` // 微信OpenID
|
WxOpenID string `json:"wx_open_id" description:"微信OpenID"`
|
||||||
WxUnionID string `json:"wx_union_id"` // 微信UnionID
|
WxUnionID string `json:"wx_union_id" description:"微信UnionID"`
|
||||||
}
|
}
|
||||||
|
|
||||||
// UpdatePersonalCustomerRequest 更新个人客户请求
|
// UpdatePersonalCustomerRequest 更新个人客户请求
|
||||||
type UpdatePersonalCustomerRequest struct {
|
type UpdatePersonalCustomerRequest struct {
|
||||||
Phone *string `json:"phone"` // 手机号
|
Phone *string `json:"phone" description:"手机号"`
|
||||||
Nickname *string `json:"nickname"` // 昵称
|
Nickname *string `json:"nickname" description:"昵称"`
|
||||||
AvatarURL *string `json:"avatar_url"` // 头像URL
|
AvatarURL *string `json:"avatar_url" description:"头像URL"`
|
||||||
}
|
}
|
||||||
|
|
||||||
// PersonalCustomerResponse 个人客户响应
|
// PersonalCustomerResponse 个人客户响应
|
||||||
type PersonalCustomerResponse struct {
|
type PersonalCustomerResponse struct {
|
||||||
ID uint `json:"id"`
|
ID uint `json:"id" description:"客户ID"`
|
||||||
Phone string `json:"phone"`
|
Phone string `json:"phone" description:"手机号"`
|
||||||
Nickname string `json:"nickname"`
|
Nickname string `json:"nickname" description:"昵称"`
|
||||||
AvatarURL string `json:"avatar_url"`
|
AvatarURL string `json:"avatar_url" description:"头像URL"`
|
||||||
WxOpenID string `json:"wx_open_id"`
|
WxOpenID string `json:"wx_open_id" description:"微信OpenID"`
|
||||||
WxUnionID string `json:"wx_union_id"`
|
WxUnionID string `json:"wx_union_id" description:"微信UnionID"`
|
||||||
Status int `json:"status"`
|
Status int `json:"status" description:"状态 (0:禁用, 1:启用)"`
|
||||||
CreatedAt string `json:"created_at"`
|
CreatedAt string `json:"created_at" description:"创建时间"`
|
||||||
UpdatedAt string `json:"updated_at"`
|
UpdatedAt string `json:"updated_at" description:"更新时间"`
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -26,7 +26,7 @@ type RoleListRequest struct {
|
|||||||
PageSize int `json:"page_size" query:"page_size" validate:"omitempty,min=1,max=100" minimum:"1" maximum:"100" description:"每页数量"`
|
PageSize int `json:"page_size" query:"page_size" validate:"omitempty,min=1,max=100" minimum:"1" maximum:"100" description:"每页数量"`
|
||||||
RoleName string `json:"role_name" query:"role_name" validate:"omitempty,max=50" maxLength:"50" description:"角色名称模糊查询"`
|
RoleName string `json:"role_name" query:"role_name" validate:"omitempty,max=50" maxLength:"50" description:"角色名称模糊查询"`
|
||||||
RoleType *int `json:"role_type" query:"role_type" validate:"omitempty,min=1,max=2" minimum:"1" maximum:"2" description:"角色类型 (1:平台角色, 2:客户角色)"`
|
RoleType *int `json:"role_type" query:"role_type" validate:"omitempty,min=1,max=2" minimum:"1" maximum:"2" description:"角色类型 (1:平台角色, 2:客户角色)"`
|
||||||
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:启用)"`
|
||||||
}
|
}
|
||||||
|
|
||||||
// RoleResponse 角色响应
|
// RoleResponse 角色响应
|
||||||
@@ -34,8 +34,8 @@ type RoleResponse struct {
|
|||||||
ID uint `json:"id" description:"角色ID"`
|
ID uint `json:"id" description:"角色ID"`
|
||||||
RoleName string `json:"role_name" description:"角色名称"`
|
RoleName string `json:"role_name" description:"角色名称"`
|
||||||
RoleDesc string `json:"role_desc" description:"角色描述"`
|
RoleDesc string `json:"role_desc" description:"角色描述"`
|
||||||
RoleType int `json:"role_type" description:"角色类型"`
|
RoleType int `json:"role_type" description:"角色类型 (1:平台角色, 2:客户角色)"`
|
||||||
Status int `json:"status" description:"状态"`
|
Status int `json:"status" description:"状态 (0:禁用, 1:启用)"`
|
||||||
Creator uint `json:"creator" description:"创建人ID"`
|
Creator uint `json:"creator" description:"创建人ID"`
|
||||||
Updater uint `json:"updater" description:"更新人ID"`
|
Updater uint `json:"updater" description:"更新人ID"`
|
||||||
CreatedAt string `json:"created_at" description:"创建时间"`
|
CreatedAt string `json:"created_at" description:"创建时间"`
|
||||||
|
|||||||
@@ -2,15 +2,15 @@ package model
|
|||||||
|
|
||||||
// RolePermissionResponse 角色-权限关联响应
|
// RolePermissionResponse 角色-权限关联响应
|
||||||
type RolePermissionResponse struct {
|
type RolePermissionResponse struct {
|
||||||
ID uint `json:"id"`
|
ID uint `json:"id" description:"关联ID"`
|
||||||
RoleID uint `json:"role_id"`
|
RoleID uint `json:"role_id" description:"角色ID"`
|
||||||
PermID uint `json:"perm_id"`
|
PermID uint `json:"perm_id" description:"权限ID"`
|
||||||
Status int `json:"status"`
|
Status int `json:"status" description:"状态 (0:禁用, 1:启用)"`
|
||||||
CreatedAt string `json:"created_at"`
|
CreatedAt string `json:"created_at" description:"创建时间"`
|
||||||
}
|
}
|
||||||
|
|
||||||
// RolePermissionsResponse 角色的权限列表响应
|
// RolePermissionsResponse 角色的权限列表响应
|
||||||
type RolePermissionsResponse struct {
|
type RolePermissionsResponse struct {
|
||||||
RoleID uint `json:"role_id"`
|
RoleID uint `json:"role_id" description:"角色ID"`
|
||||||
Permissions []*PermissionResponse `json:"permissions"`
|
Permissions []*PermissionResponse `json:"permissions" description:"权限列表"`
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -36,13 +36,13 @@ type UpdateShopAccountStatusRequest struct {
|
|||||||
|
|
||||||
// ShopAccountResponse 代理商账号响应
|
// ShopAccountResponse 代理商账号响应
|
||||||
type ShopAccountResponse struct {
|
type ShopAccountResponse struct {
|
||||||
ID uint `json:"id"`
|
ID uint `json:"id" description:"账号ID"`
|
||||||
ShopID uint `json:"shop_id"`
|
ShopID uint `json:"shop_id" description:"店铺ID"`
|
||||||
ShopName string `json:"shop_name,omitempty"` // 关联查询时填充
|
ShopName string `json:"shop_name,omitempty" description:"店铺名称"`
|
||||||
Username string `json:"username"`
|
Username string `json:"username" description:"用户名"`
|
||||||
Phone string `json:"phone"`
|
Phone string `json:"phone" description:"手机号"`
|
||||||
UserType int `json:"user_type"`
|
UserType int `json:"user_type" description:"用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)"`
|
||||||
Status int `json:"status"`
|
Status int `json:"status" description:"状态 (0:禁用, 1:启用)"`
|
||||||
CreatedAt string `json:"created_at"`
|
CreatedAt string `json:"created_at" description:"创建时间"`
|
||||||
UpdatedAt string `json:"updated_at"`
|
UpdatedAt string `json:"updated_at" description:"更新时间"`
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -1,55 +1,55 @@
|
|||||||
package model
|
package model
|
||||||
|
|
||||||
type ShopListRequest struct {
|
type ShopListRequest struct {
|
||||||
Page int `json:"page" query:"page" validate:"omitempty,min=1"`
|
Page int `json:"page" query:"page" validate:"omitempty,min=1" minimum:"1" description:"页码"`
|
||||||
PageSize int `json:"page_size" query:"page_size" validate:"omitempty,min=1,max=100"`
|
PageSize int `json:"page_size" query:"page_size" validate:"omitempty,min=1,max=100" minimum:"1" maximum:"100" description:"每页数量"`
|
||||||
ShopName string `json:"shop_name" query:"shop_name" validate:"omitempty,max=100"`
|
ShopName string `json:"shop_name" query:"shop_name" validate:"omitempty,max=100" maxLength:"100" description:"店铺名称模糊查询"`
|
||||||
ShopCode string `json:"shop_code" query:"shop_code" validate:"omitempty,max=50"`
|
ShopCode string `json:"shop_code" query:"shop_code" validate:"omitempty,max=50" maxLength:"50" description:"店铺编号模糊查询"`
|
||||||
ParentID *uint `json:"parent_id" query:"parent_id" validate:"omitempty,min=1"`
|
ParentID *uint `json:"parent_id" query:"parent_id" validate:"omitempty,min=1" minimum:"1" description:"上级店铺ID"`
|
||||||
Level *int `json:"level" query:"level" validate:"omitempty,min=1,max=7"`
|
Level *int `json:"level" query:"level" validate:"omitempty,min=1,max=7" minimum:"1" maximum:"7" description:"店铺层级 (1-7级)"`
|
||||||
Status *int `json:"status" query:"status" validate:"omitempty,oneof=0 1"`
|
Status *int `json:"status" query:"status" validate:"omitempty,oneof=0 1" description:"状态 (0:禁用, 1:启用)"`
|
||||||
}
|
}
|
||||||
|
|
||||||
type CreateShopRequest struct {
|
type CreateShopRequest struct {
|
||||||
ShopName string `json:"shop_name" validate:"required,min=1,max=100"`
|
ShopName string `json:"shop_name" validate:"required,min=1,max=100" required:"true" minLength:"1" maxLength:"100" description:"店铺名称"`
|
||||||
ShopCode string `json:"shop_code" validate:"required,min=1,max=50"`
|
ShopCode string `json:"shop_code" validate:"required,min=1,max=50" required:"true" minLength:"1" maxLength:"50" description:"店铺编号"`
|
||||||
ParentID *uint `json:"parent_id" validate:"omitempty,min=1"`
|
ParentID *uint `json:"parent_id" validate:"omitempty,min=1" minimum:"1" description:"上级店铺ID（一级店铺可不填）"`
|
||||||
ContactName string `json:"contact_name" validate:"omitempty,max=50"`
|
ContactName string `json:"contact_name" validate:"omitempty,max=50" maxLength:"50" description:"联系人姓名"`
|
||||||
ContactPhone string `json:"contact_phone" validate:"omitempty,len=11"`
|
ContactPhone string `json:"contact_phone" validate:"omitempty,len=11" minLength:"11" maxLength:"11" description:"联系人电话"`
|
||||||
Province string `json:"province" validate:"omitempty,max=50"`
|
Province string `json:"province" validate:"omitempty,max=50" maxLength:"50" description:"省份"`
|
||||||
City string `json:"city" validate:"omitempty,max=50"`
|
City string `json:"city" validate:"omitempty,max=50" maxLength:"50" description:"城市"`
|
||||||
District string `json:"district" validate:"omitempty,max=50"`
|
District string `json:"district" validate:"omitempty,max=50" maxLength:"50" description:"区县"`
|
||||||
Address string `json:"address" validate:"omitempty,max=255"`
|
Address string `json:"address" validate:"omitempty,max=255" maxLength:"255" description:"详细地址"`
|
||||||
InitPassword string `json:"init_password" validate:"required,min=8,max=32"`
|
InitPassword string `json:"init_password" validate:"required,min=8,max=32" required:"true" minLength:"8" maxLength:"32" description:"初始账号密码"`
|
||||||
InitUsername string `json:"init_username" validate:"required,min=3,max=50"`
|
InitUsername string `json:"init_username" validate:"required,min=3,max=50" required:"true" minLength:"3" maxLength:"50" description:"初始账号用户名"`
|
||||||
InitPhone string `json:"init_phone" validate:"required,len=11"`
|
InitPhone string `json:"init_phone" validate:"required,len=11" required:"true" minLength:"11" maxLength:"11" description:"初始账号手机号"`
|
||||||
}
|
}
|
||||||
|
|
||||||
type UpdateShopRequest struct {
|
type UpdateShopRequest struct {
|
||||||
ShopName string `json:"shop_name" validate:"required,min=1,max=100"`
|
ShopName string `json:"shop_name" validate:"required,min=1,max=100" required:"true" minLength:"1" maxLength:"100" description:"店铺名称"`
|
||||||
ContactName string `json:"contact_name" validate:"omitempty,max=50"`
|
ContactName string `json:"contact_name" validate:"omitempty,max=50" maxLength:"50" description:"联系人姓名"`
|
||||||
ContactPhone string `json:"contact_phone" validate:"omitempty,len=11"`
|
ContactPhone string `json:"contact_phone" validate:"omitempty,len=11" minLength:"11" maxLength:"11" description:"联系人电话"`
|
||||||
Province string `json:"province" validate:"omitempty,max=50"`
|
Province string `json:"province" validate:"omitempty,max=50" maxLength:"50" description:"省份"`
|
||||||
City string `json:"city" validate:"omitempty,max=50"`
|
City string `json:"city" validate:"omitempty,max=50" maxLength:"50" description:"城市"`
|
||||||
District string `json:"district" validate:"omitempty,max=50"`
|
District string `json:"district" validate:"omitempty,max=50" maxLength:"50" description:"区县"`
|
||||||
Address string `json:"address" validate:"omitempty,max=255"`
|
Address string `json:"address" validate:"omitempty,max=255" maxLength:"255" description:"详细地址"`
|
||||||
Status int `json:"status" validate:"required,oneof=0 1"`
|
Status int `json:"status" validate:"required,oneof=0 1" required:"true" description:"状态 (0:禁用, 1:启用)"`
|
||||||
}
|
}
|
||||||
|
|
||||||
// ShopResponse 店铺响应
|
// ShopResponse 店铺响应
|
||||||
type ShopResponse struct {
|
type ShopResponse struct {
|
||||||
ID uint `json:"id"`
|
ID uint `json:"id" description:"店铺ID"`
|
||||||
ShopName string `json:"shop_name"`
|
ShopName string `json:"shop_name" description:"店铺名称"`
|
||||||
ShopCode string `json:"shop_code"`
|
ShopCode string `json:"shop_code" description:"店铺编号"`
|
||||||
ParentID *uint `json:"parent_id,omitempty"`
|
ParentID *uint `json:"parent_id,omitempty" description:"上级店铺ID"`
|
||||||
Level int `json:"level"`
|
Level int `json:"level" description:"店铺层级 (1-7级)"`
|
||||||
ContactName string `json:"contact_name"`
|
ContactName string `json:"contact_name" description:"联系人姓名"`
|
||||||
ContactPhone string `json:"contact_phone"`
|
ContactPhone string `json:"contact_phone" description:"联系人电话"`
|
||||||
Province string `json:"province"`
|
Province string `json:"province" description:"省份"`
|
||||||
City string `json:"city"`
|
City string `json:"city" description:"城市"`
|
||||||
District string `json:"district"`
|
District string `json:"district" description:"区县"`
|
||||||
Address string `json:"address"`
|
Address string `json:"address" description:"详细地址"`
|
||||||
Status int `json:"status"`
|
Status int `json:"status" description:"状态 (0:禁用, 1:启用)"`
|
||||||
CreatedAt string `json:"created_at"`
|
CreatedAt string `json:"created_at" description:"创建时间"`
|
||||||
UpdatedAt string `json:"updated_at"`
|
UpdatedAt string `json:"updated_at" description:"更新时间"`
|
||||||
}
|
}
|
||||||
|
|||||||
Reference in New Issue
Block a user