完善 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
|
||||
cmd/api/api
|
||||
2026-01-09-local-command-caveatcaveat-the-messages-below-w.txt
|
||||
api
|
||||
.gitignore
|
||||
worker
|
||||
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）
|
||||
- 缩写词: 全大写或全小写（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 模型规范
|
||||
|
||||
**必须遵守的模型结构:**
|
||||
|
||||
40
CLAUDE.md
40
CLAUDE.md
@@ -96,6 +96,46 @@ tests/
|
||||
- Go 文档注释（doc comments for exported APIs）可以使用英文以保持生态兼容性，但中文注释更佳
|
||||
- 变量名、函数名、类型名必须使用英文（遵循 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 代码风格要求:**
|
||||
|
||||
- 必须使用 `gofmt` 格式化所有代码
|
||||
|
||||
@@ -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
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:"用户名"`
|
||||
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:"密码"`
|
||||
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（代理账号必填）"`
|
||||
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:"每页数量"`
|
||||
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:"手机号模糊查询"`
|
||||
UserType *int `json:"user_type" query:"user_type" validate:"omitempty,min=1,max=4" minimum:"1" maximum:"4" description:"用户类型"`
|
||||
Status *int `json:"status" query:"status" validate:"omitempty,min=0,max=1" minimum:"0" maximum:"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:企业账号)"`
|
||||
Status *int `json:"status" query:"status" validate:"omitempty,min=0,max=1" minimum:"0" maximum:"1" description:"状态 (0:禁用, 1:启用)"`
|
||||
}
|
||||
|
||||
// AccountResponse 账号响应
|
||||
@@ -33,10 +33,10 @@ type AccountResponse struct {
|
||||
ID uint `json:"id" description:"账号ID"`
|
||||
Username string `json:"username" 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"`
|
||||
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"`
|
||||
Updater uint `json:"updater" description:"更新人ID"`
|
||||
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:"每页数量"`
|
||||
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:"手机号模糊查询"`
|
||||
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 生成）
|
||||
|
||||
@@ -2,15 +2,15 @@ package model
|
||||
|
||||
// AccountRoleResponse 账号-角色关联响应
|
||||
type AccountRoleResponse struct {
|
||||
ID uint `json:"id"`
|
||||
AccountID uint `json:"account_id"`
|
||||
RoleID uint `json:"role_id"`
|
||||
Status int `json:"status"`
|
||||
CreatedAt string `json:"created_at"`
|
||||
ID uint `json:"id" description:"关联ID"`
|
||||
AccountID uint `json:"account_id" description:"账号ID"`
|
||||
RoleID uint `json:"role_id" description:"角色ID"`
|
||||
Status int `json:"status" description:"状态 (0:禁用, 1:启用)"`
|
||||
CreatedAt string `json:"created_at" description:"创建时间"`
|
||||
}
|
||||
|
||||
// AccountRolesResponse 账号的角色列表响应
|
||||
type AccountRolesResponse struct {
|
||||
AccountID uint `json:"account_id"`
|
||||
Roles []*RoleResponse `json:"roles"`
|
||||
AccountID uint `json:"account_id" description:"账号ID"`
|
||||
Roles []*RoleResponse `json:"roles" description:"角色列表"`
|
||||
}
|
||||
|
||||
@@ -15,15 +15,15 @@ type LoginResponse struct {
|
||||
}
|
||||
|
||||
type UserInfo struct {
|
||||
ID uint `json:"id"`
|
||||
Username string `json:"username"`
|
||||
Phone string `json:"phone"`
|
||||
UserType int `json:"user_type"`
|
||||
UserTypeName string `json:"user_type_name"`
|
||||
ShopID uint `json:"shop_id,omitempty"`
|
||||
ShopName string `json:"shop_name,omitempty"`
|
||||
EnterpriseID uint `json:"enterprise_id,omitempty"`
|
||||
EnterpriseName string `json:"enterprise_name,omitempty"`
|
||||
ID uint `json:"id" description:"用户ID"`
|
||||
Username string `json:"username" description:"用户名"`
|
||||
Phone string `json:"phone" description:"手机号"`
|
||||
UserType int `json:"user_type" description:"用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)"`
|
||||
UserTypeName string `json:"user_type_name" description:"用户类型名称"`
|
||||
ShopID uint `json:"shop_id,omitempty" description:"店铺ID"`
|
||||
ShopName string `json:"shop_name,omitempty" description:"店铺名称"`
|
||||
EnterpriseID uint `json:"enterprise_id,omitempty" description:"企业ID"`
|
||||
EnterpriseName string `json:"enterprise_name,omitempty" description:"企业名称"`
|
||||
}
|
||||
|
||||
type RefreshTokenRequest struct {
|
||||
|
||||
@@ -2,48 +2,48 @@ package model
|
||||
|
||||
// CreateEnterpriseRequest 创建企业请求
|
||||
type CreateEnterpriseRequest struct {
|
||||
EnterpriseName string `json:"enterprise_name" validate:"required"` // 企业名称
|
||||
EnterpriseCode string `json:"enterprise_code"` // 企业编号
|
||||
OwnerShopID *uint `json:"owner_shop_id"` // 归属店铺ID
|
||||
LegalPerson string `json:"legal_person"` // 法人代表
|
||||
ContactName string `json:"contact_name"` // 联系人姓名
|
||||
ContactPhone string `json:"contact_phone"` // 联系人电话
|
||||
BusinessLicense string `json:"business_license"` // 营业执照号
|
||||
Province string `json:"province"` // 省份
|
||||
City string `json:"city"` // 城市
|
||||
District string `json:"district"` // 区县
|
||||
Address string `json:"address"` // 详细地址
|
||||
EnterpriseName string `json:"enterprise_name" validate:"required" required:"true" description:"企业名称"`
|
||||
EnterpriseCode string `json:"enterprise_code" description:"企业编号"`
|
||||
OwnerShopID *uint `json:"owner_shop_id" description:"归属店铺ID（可不填则归属平台）"`
|
||||
LegalPerson string `json:"legal_person" description:"法人代表"`
|
||||
ContactName string `json:"contact_name" description:"联系人姓名"`
|
||||
ContactPhone string `json:"contact_phone" description:"联系人电话"`
|
||||
BusinessLicense string `json:"business_license" description:"营业执照号"`
|
||||
Province string `json:"province" description:"省份"`
|
||||
City string `json:"city" description:"城市"`
|
||||
District string `json:"district" description:"区县"`
|
||||
Address string `json:"address" description:"详细地址"`
|
||||
}
|
||||
|
||||
// UpdateEnterpriseRequest 更新企业请求
|
||||
type UpdateEnterpriseRequest struct {
|
||||
EnterpriseName *string `json:"enterprise_name"` // 企业名称
|
||||
EnterpriseCode *string `json:"enterprise_code"` // 企业编号
|
||||
LegalPerson *string `json:"legal_person"` // 法人代表
|
||||
ContactName *string `json:"contact_name"` // 联系人姓名
|
||||
ContactPhone *string `json:"contact_phone"` // 联系人电话
|
||||
BusinessLicense *string `json:"business_license"` // 营业执照号
|
||||
Province *string `json:"province"` // 省份
|
||||
City *string `json:"city"` // 城市
|
||||
District *string `json:"district"` // 区县
|
||||
Address *string `json:"address"` // 详细地址
|
||||
EnterpriseName *string `json:"enterprise_name" description:"企业名称"`
|
||||
EnterpriseCode *string `json:"enterprise_code" description:"企业编号"`
|
||||
LegalPerson *string `json:"legal_person" description:"法人代表"`
|
||||
ContactName *string `json:"contact_name" description:"联系人姓名"`
|
||||
ContactPhone *string `json:"contact_phone" description:"联系人电话"`
|
||||
BusinessLicense *string `json:"business_license" description:"营业执照号"`
|
||||
Province *string `json:"province" description:"省份"`
|
||||
City *string `json:"city" description:"城市"`
|
||||
District *string `json:"district" description:"区县"`
|
||||
Address *string `json:"address" description:"详细地址"`
|
||||
}
|
||||
|
||||
// EnterpriseResponse 企业响应
|
||||
type EnterpriseResponse struct {
|
||||
ID uint `json:"id"`
|
||||
EnterpriseName string `json:"enterprise_name"`
|
||||
EnterpriseCode string `json:"enterprise_code"`
|
||||
OwnerShopID *uint `json:"owner_shop_id,omitempty"`
|
||||
LegalPerson string `json:"legal_person"`
|
||||
ContactName string `json:"contact_name"`
|
||||
ContactPhone string `json:"contact_phone"`
|
||||
BusinessLicense string `json:"business_license"`
|
||||
Province string `json:"province"`
|
||||
City string `json:"city"`
|
||||
District string `json:"district"`
|
||||
Address string `json:"address"`
|
||||
Status int `json:"status"`
|
||||
CreatedAt string `json:"created_at"`
|
||||
UpdatedAt string `json:"updated_at"`
|
||||
ID uint `json:"id" description:"企业ID"`
|
||||
EnterpriseName string `json:"enterprise_name" description:"企业名称"`
|
||||
EnterpriseCode string `json:"enterprise_code" description:"企业编号"`
|
||||
OwnerShopID *uint `json:"owner_shop_id,omitempty" description:"归属店铺ID"`
|
||||
LegalPerson string `json:"legal_person" description:"法人代表"`
|
||||
ContactName string `json:"contact_name" description:"联系人姓名"`
|
||||
ContactPhone string `json:"contact_phone" description:"联系人电话"`
|
||||
BusinessLicense string `json:"business_license" description:"营业执照号"`
|
||||
Province string `json:"province" description:"省份"`
|
||||
City string `json:"city" description:"城市"`
|
||||
District string `json:"district" description:"区县"`
|
||||
Address string `json:"address" description:"详细地址"`
|
||||
Status int `json:"status" description:"状态 (0:禁用, 1:启用)"`
|
||||
CreatedAt string `json:"created_at" description:"创建时间"`
|
||||
UpdatedAt string `json:"updated_at" description:"更新时间"`
|
||||
}
|
||||
|
||||
@@ -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:"每页数量"`
|
||||
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:"权限编码模糊查询"`
|
||||
PermType *int `json:"perm_type" query:"perm_type" validate:"omitempty,min=1,max=2" minimum:"1" maximum:"2" description:"权限类型"`
|
||||
Platform string `json:"platform" query:"platform" validate:"omitempty,oneof=all web h5" 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:"适用端口 (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:客户角色)"`
|
||||
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 权限响应
|
||||
@@ -46,13 +46,13 @@ type PermissionResponse struct {
|
||||
ID uint `json:"id" description:"权限ID"`
|
||||
PermName string `json:"perm_name" description:"权限名称"`
|
||||
PermCode string `json:"perm_code" description:"权限编码"`
|
||||
PermType int `json:"perm_type" description:"权限类型"`
|
||||
Platform string `json:"platform" description:"适用端口"`
|
||||
AvailableForRoleTypes string `json:"available_for_role_types" description:"可用角色类型"`
|
||||
PermType int `json:"perm_type" description:"权限类型 (1:菜单, 2:按钮)"`
|
||||
Platform string `json:"platform" description:"适用端口 (all:全部, web:Web后台, h5:H5端)"`
|
||||
AvailableForRoleTypes string `json:"available_for_role_types" description:"可用角色类型 (1:平台角色, 2:客户角色)"`
|
||||
URL string `json:"url,omitempty" description:"请求路径"`
|
||||
ParentID *uint `json:"parent_id,omitempty" description:"父权限ID"`
|
||||
Sort int `json:"sort" description:"排序值"`
|
||||
Status int `json:"status" description:"状态"`
|
||||
Status int `json:"status" description:"状态 (0:禁用, 1:启用)"`
|
||||
Creator uint `json:"creator" description:"创建人ID"`
|
||||
Updater uint `json:"updater" description:"更新人ID"`
|
||||
CreatedAt string `json:"created_at" description:"创建时间"`
|
||||
@@ -72,9 +72,9 @@ type PermissionTreeNode struct {
|
||||
ID uint `json:"id" description:"权限ID"`
|
||||
PermName string `json:"perm_name" description:"权限名称"`
|
||||
PermCode string `json:"perm_code" description:"权限编码"`
|
||||
PermType int `json:"perm_type" description:"权限类型"`
|
||||
Platform string `json:"platform" description:"适用端口"`
|
||||
AvailableForRoleTypes string `json:"available_for_role_types" description:"可用角色类型"`
|
||||
PermType int `json:"perm_type" description:"权限类型 (1:菜单, 2:按钮)"`
|
||||
Platform string `json:"platform" description:"适用端口 (all:全部, web:Web后台, h5:H5端)"`
|
||||
AvailableForRoleTypes string `json:"available_for_role_types" description:"可用角色类型 (1:平台角色, 2:客户角色)"`
|
||||
URL string `json:"url,omitempty" description:"请求路径"`
|
||||
Sort int `json:"sort" description:"排序值"`
|
||||
Children []*PermissionTreeNode `json:"children,omitempty" description:"子权限列表"`
|
||||
|
||||
@@ -2,29 +2,29 @@ package model
|
||||
|
||||
// CreatePersonalCustomerRequest 创建个人客户请求
|
||||
type CreatePersonalCustomerRequest struct {
|
||||
Phone string `json:"phone" validate:"required"` // 手机号
|
||||
Nickname string `json:"nickname"` // 昵称
|
||||
AvatarURL string `json:"avatar_url"` // 头像URL
|
||||
WxOpenID string `json:"wx_open_id"` // 微信OpenID
|
||||
WxUnionID string `json:"wx_union_id"` // 微信UnionID
|
||||
Phone string `json:"phone" validate:"required" required:"true" description:"手机号"`
|
||||
Nickname string `json:"nickname" description:"昵称"`
|
||||
AvatarURL string `json:"avatar_url" description:"头像URL"`
|
||||
WxOpenID string `json:"wx_open_id" description:"微信OpenID"`
|
||||
WxUnionID string `json:"wx_union_id" description:"微信UnionID"`
|
||||
}
|
||||
|
||||
// UpdatePersonalCustomerRequest 更新个人客户请求
|
||||
type UpdatePersonalCustomerRequest struct {
|
||||
Phone *string `json:"phone"` // 手机号
|
||||
Nickname *string `json:"nickname"` // 昵称
|
||||
AvatarURL *string `json:"avatar_url"` // 头像URL
|
||||
Phone *string `json:"phone" description:"手机号"`
|
||||
Nickname *string `json:"nickname" description:"昵称"`
|
||||
AvatarURL *string `json:"avatar_url" description:"头像URL"`
|
||||
}
|
||||
|
||||
// PersonalCustomerResponse 个人客户响应
|
||||
type PersonalCustomerResponse struct {
|
||||
ID uint `json:"id"`
|
||||
Phone string `json:"phone"`
|
||||
Nickname string `json:"nickname"`
|
||||
AvatarURL string `json:"avatar_url"`
|
||||
WxOpenID string `json:"wx_open_id"`
|
||||
WxUnionID string `json:"wx_union_id"`
|
||||
Status int `json:"status"`
|
||||
CreatedAt string `json:"created_at"`
|
||||
UpdatedAt string `json:"updated_at"`
|
||||
ID uint `json:"id" description:"客户ID"`
|
||||
Phone string `json:"phone" description:"手机号"`
|
||||
Nickname string `json:"nickname" description:"昵称"`
|
||||
AvatarURL string `json:"avatar_url" description:"头像URL"`
|
||||
WxOpenID string `json:"wx_open_id" description:"微信OpenID"`
|
||||
WxUnionID string `json:"wx_union_id" description:"微信UnionID"`
|
||||
Status int `json:"status" description:"状态 (0:禁用, 1:启用)"`
|
||||
CreatedAt string `json:"created_at" description:"创建时间"`
|
||||
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:"每页数量"`
|
||||
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:客户角色)"`
|
||||
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 角色响应
|
||||
@@ -34,8 +34,8 @@ type RoleResponse struct {
|
||||
ID uint `json:"id" description:"角色ID"`
|
||||
RoleName string `json:"role_name" description:"角色名称"`
|
||||
RoleDesc string `json:"role_desc" description:"角色描述"`
|
||||
RoleType int `json:"role_type" description:"角色类型"`
|
||||
Status int `json:"status" description:"状态"`
|
||||
RoleType int `json:"role_type" description:"角色类型 (1:平台角色, 2:客户角色)"`
|
||||
Status int `json:"status" description:"状态 (0:禁用, 1:启用)"`
|
||||
Creator uint `json:"creator" description:"创建人ID"`
|
||||
Updater uint `json:"updater" description:"更新人ID"`
|
||||
CreatedAt string `json:"created_at" description:"创建时间"`
|
||||
|
||||
@@ -2,15 +2,15 @@ package model
|
||||
|
||||
// RolePermissionResponse 角色-权限关联响应
|
||||
type RolePermissionResponse struct {
|
||||
ID uint `json:"id"`
|
||||
RoleID uint `json:"role_id"`
|
||||
PermID uint `json:"perm_id"`
|
||||
Status int `json:"status"`
|
||||
CreatedAt string `json:"created_at"`
|
||||
ID uint `json:"id" description:"关联ID"`
|
||||
RoleID uint `json:"role_id" description:"角色ID"`
|
||||
PermID uint `json:"perm_id" description:"权限ID"`
|
||||
Status int `json:"status" description:"状态 (0:禁用, 1:启用)"`
|
||||
CreatedAt string `json:"created_at" description:"创建时间"`
|
||||
}
|
||||
|
||||
// RolePermissionsResponse 角色的权限列表响应
|
||||
type RolePermissionsResponse struct {
|
||||
RoleID uint `json:"role_id"`
|
||||
Permissions []*PermissionResponse `json:"permissions"`
|
||||
RoleID uint `json:"role_id" description:"角色ID"`
|
||||
Permissions []*PermissionResponse `json:"permissions" description:"权限列表"`
|
||||
}
|
||||
|
||||
@@ -36,13 +36,13 @@ type UpdateShopAccountStatusRequest struct {
|
||||
|
||||
// ShopAccountResponse 代理商账号响应
|
||||
type ShopAccountResponse struct {
|
||||
ID uint `json:"id"`
|
||||
ShopID uint `json:"shop_id"`
|
||||
ShopName string `json:"shop_name,omitempty"` // 关联查询时填充
|
||||
Username string `json:"username"`
|
||||
Phone string `json:"phone"`
|
||||
UserType int `json:"user_type"`
|
||||
Status int `json:"status"`
|
||||
CreatedAt string `json:"created_at"`
|
||||
UpdatedAt string `json:"updated_at"`
|
||||
ID uint `json:"id" description:"账号ID"`
|
||||
ShopID uint `json:"shop_id" description:"店铺ID"`
|
||||
ShopName string `json:"shop_name,omitempty" description:"店铺名称"`
|
||||
Username string `json:"username" description:"用户名"`
|
||||
Phone string `json:"phone" 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:"更新时间"`
|
||||
}
|
||||
|
||||
@@ -1,55 +1,55 @@
|
||||
package model
|
||||
|
||||
type ShopListRequest struct {
|
||||
Page int `json:"page" query:"page" validate:"omitempty,min=1"`
|
||||
PageSize int `json:"page_size" query:"page_size" validate:"omitempty,min=1,max=100"`
|
||||
ShopName string `json:"shop_name" query:"shop_name" validate:"omitempty,max=100"`
|
||||
ShopCode string `json:"shop_code" query:"shop_code" validate:"omitempty,max=50"`
|
||||
ParentID *uint `json:"parent_id" query:"parent_id" validate:"omitempty,min=1"`
|
||||
Level *int `json:"level" query:"level" validate:"omitempty,min=1,max=7"`
|
||||
Status *int `json:"status" query:"status" validate:"omitempty,oneof=0 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" minimum:"1" maximum:"100" description:"每页数量"`
|
||||
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" maxLength:"50" description:"店铺编号模糊查询"`
|
||||
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" minimum:"1" maximum:"7" description:"店铺层级 (1-7级)"`
|
||||
Status *int `json:"status" query:"status" validate:"omitempty,oneof=0 1" description:"状态 (0:禁用, 1:启用)"`
|
||||
}
|
||||
|
||||
type CreateShopRequest struct {
|
||||
ShopName string `json:"shop_name" validate:"required,min=1,max=100"`
|
||||
ShopCode string `json:"shop_code" validate:"required,min=1,max=50"`
|
||||
ParentID *uint `json:"parent_id" validate:"omitempty,min=1"`
|
||||
ContactName string `json:"contact_name" validate:"omitempty,max=50"`
|
||||
ContactPhone string `json:"contact_phone" validate:"omitempty,len=11"`
|
||||
Province string `json:"province" validate:"omitempty,max=50"`
|
||||
City string `json:"city" validate:"omitempty,max=50"`
|
||||
District string `json:"district" validate:"omitempty,max=50"`
|
||||
Address string `json:"address" validate:"omitempty,max=255"`
|
||||
InitPassword string `json:"init_password" validate:"required,min=8,max=32"`
|
||||
InitUsername string `json:"init_username" validate:"required,min=3,max=50"`
|
||||
InitPhone string `json:"init_phone" validate:"required,len=11"`
|
||||
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" required:"true" minLength:"1" maxLength:"50" description:"店铺编号"`
|
||||
ParentID *uint `json:"parent_id" validate:"omitempty,min=1" minimum:"1" description:"上级店铺ID（一级店铺可不填）"`
|
||||
ContactName string `json:"contact_name" validate:"omitempty,max=50" maxLength:"50" description:"联系人姓名"`
|
||||
ContactPhone string `json:"contact_phone" validate:"omitempty,len=11" minLength:"11" maxLength:"11" description:"联系人电话"`
|
||||
Province string `json:"province" validate:"omitempty,max=50" maxLength:"50" description:"省份"`
|
||||
City string `json:"city" validate:"omitempty,max=50" maxLength:"50" description:"城市"`
|
||||
District string `json:"district" validate:"omitempty,max=50" maxLength:"50" description:"区县"`
|
||||
Address string `json:"address" validate:"omitempty,max=255" maxLength:"255" description:"详细地址"`
|
||||
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" required:"true" minLength:"3" maxLength:"50" description:"初始账号用户名"`
|
||||
InitPhone string `json:"init_phone" validate:"required,len=11" required:"true" minLength:"11" maxLength:"11" description:"初始账号手机号"`
|
||||
}
|
||||
|
||||
type UpdateShopRequest struct {
|
||||
ShopName string `json:"shop_name" validate:"required,min=1,max=100"`
|
||||
ContactName string `json:"contact_name" validate:"omitempty,max=50"`
|
||||
ContactPhone string `json:"contact_phone" validate:"omitempty,len=11"`
|
||||
Province string `json:"province" validate:"omitempty,max=50"`
|
||||
City string `json:"city" validate:"omitempty,max=50"`
|
||||
District string `json:"district" validate:"omitempty,max=50"`
|
||||
Address string `json:"address" validate:"omitempty,max=255"`
|
||||
Status int `json:"status" validate:"required,oneof=0 1"`
|
||||
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" maxLength:"50" description:"联系人姓名"`
|
||||
ContactPhone string `json:"contact_phone" validate:"omitempty,len=11" minLength:"11" maxLength:"11" description:"联系人电话"`
|
||||
Province string `json:"province" validate:"omitempty,max=50" maxLength:"50" description:"省份"`
|
||||
City string `json:"city" validate:"omitempty,max=50" maxLength:"50" description:"城市"`
|
||||
District string `json:"district" validate:"omitempty,max=50" maxLength:"50" description:"区县"`
|
||||
Address string `json:"address" validate:"omitempty,max=255" maxLength:"255" description:"详细地址"`
|
||||
Status int `json:"status" validate:"required,oneof=0 1" required:"true" description:"状态 (0:禁用, 1:启用)"`
|
||||
}
|
||||
|
||||
// ShopResponse 店铺响应
|
||||
type ShopResponse struct {
|
||||
ID uint `json:"id"`
|
||||
ShopName string `json:"shop_name"`
|
||||
ShopCode string `json:"shop_code"`
|
||||
ParentID *uint `json:"parent_id,omitempty"`
|
||||
Level int `json:"level"`
|
||||
ContactName string `json:"contact_name"`
|
||||
ContactPhone string `json:"contact_phone"`
|
||||
Province string `json:"province"`
|
||||
City string `json:"city"`
|
||||
District string `json:"district"`
|
||||
Address string `json:"address"`
|
||||
Status int `json:"status"`
|
||||
CreatedAt string `json:"created_at"`
|
||||
UpdatedAt string `json:"updated_at"`
|
||||
ID uint `json:"id" description:"店铺ID"`
|
||||
ShopName string `json:"shop_name" description:"店铺名称"`
|
||||
ShopCode string `json:"shop_code" description:"店铺编号"`
|
||||
ParentID *uint `json:"parent_id,omitempty" description:"上级店铺ID"`
|
||||
Level int `json:"level" description:"店铺层级 (1-7级)"`
|
||||
ContactName string `json:"contact_name" description:"联系人姓名"`
|
||||
ContactPhone string `json:"contact_phone" description:"联系人电话"`
|
||||
Province string `json:"province" description:"省份"`
|
||||
City string `json:"city" description:"城市"`
|
||||
District string `json:"district" description:"区县"`
|
||||
Address string `json:"address" description:"详细地址"`
|
||||
Status int `json:"status" description:"状态 (0:禁用, 1:启用)"`
|
||||
CreatedAt string `json:"created_at" description:"创建时间"`
|
||||
UpdatedAt string `json:"updated_at" description:"更新时间"`
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user