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

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

Browse Source 
- 修复所有 DTO 文件的 description 标签（10 个文件）
  - 枚举字段统一使用中文说明（用户类型、角色类型、权限类型等）
  - 状态字段明确说明 0/1 含义
  - validate 标签与 OpenAPI 标签保持一致

- 在 AGENTS.md 和 CLAUDE.md 添加 DTO 规范章节
  - AI 助手必须执行的 7 项检查清单
  - 常见枚举字段标准值参考
  - 确保未来 AI 助手自动遵循规范

- 创建规范文档
  - docs/code-review-checklist.md（Code Review 检查清单）
  - docs/dto-improvement-summary.md（DTO 改进总结）
  - docs/ai-dto-guidelines-update.md（AI 指引更新说明）

- 重新生成 OpenAPI 文档（375 个 description 标签）

影响：所有 API 字段现在都有清晰的中文说明，前端开发更友好
This commit is contained in:
huang
2026-01-20 15:10:11 +08:00
parent 1bee64fc65
commit 4abbf558e4
18 changed files with 1677 additions and 173 deletions
Download Patch File Download Diff File Expand all files Collapse all files

61
docs/admin-openapi.yaml
View File

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