refactor all

http/README.md

@@ -0,0 +1,163 @@
+# HTTP 调试与文档规范
+
+本目录下的 `.http` 文件同时承担接口调试和接口文档职责，也要保证 AIAgent 能稳定读取
+
+## 目录分工
+
+### `.http`
+
+`.http` 只描述接口级信息：
+
+1. 接口中文名
+2. 权限要求
+3. 前置条件
+4. 请求参数对应的对象说明
+5. 返回参数对应的对象说明
+
+`.http` 不重复展开对象字段明细，复杂字段、嵌套结构、枚举值统一写到 `./object` 下
+
+### `./object`
+
+`./object` 只描述对象级信息：
+
+1. 字段名
+2. 字段类型
+3. 字段说明
+4. 枚举值及含义
+
+所有模块都可能复用的通用对象必须写在 `./object/common.md`
+
+按业务领域拆分对象说明文件，例如：
+
+1. `./object/common.md`
+2. `./object/user.md`
+3. `./object/role.md`
+4. `./object/permission.md`
+
+不要把同一个对象的字段说明散落到多个文件里
+
+## 全局约定
+
+### 返回包装
+
+除使用 `IgnoreGlobalReturn` 跳过全局包装的方法外，接口默认都会经过
+[GlobalReturnHandler](E:/IDEAProject/timi-spring/src/main/java/com/imyeyu/spring/util/GlobalReturnHandler.java)
+统一包装返回
+
+因此 `.http` 里的 `返回参数` 默认只描述业务 `data` 对象，不再重复赘述全局包装结构
+
+全局返回包装、通用成功码、错误信息、常见分页壳子等内容统一维护在 `./object/common.md`
+
+如果接口使用
+[IgnoreGlobalReturn](E:/IDEAProject/timi-spring/src/main/java/com/imyeyu/spring/annotation/IgnoreGlobalReturn.java)
+跳过全局包装，必须在对应接口的 `前置条件` 或补充说明里明确写出“该接口不走全局返回包装”
+
+### 文档真实性
+
+1. 文档只记录服务端真实行为
+2. 不写猜测
+3. 不写“看代码”
+4. 接口改了就同步更新 `.http` 和 `./object`
+
+### 变量复用
+
+能复用的变量统一放在文件顶部，例如 `@user_token`、`@userId`
+
+## `.http` 模板
+
+每个接口块固定使用下面格式，不要擅自增删字段名：
+
+```http
+### <接口中文名>
+### 权限：
+### 前置条件：
+### 请求参数：
+### 返回参数：
+
+POST {{baseUrl}}/path
+Content-Type: application/json
+Token: {{user_token}}
+
+{}
+```
+
+## `.http` 填写要求
+
+### 接口中文名
+
+直接写接口用途，别写成控制器方法名
+
+### 权限
+
+1. 优先直接翻译控制器上的真实注解
+2. 同时存在角色和权限时一起写，例如 `需要 ADMIN 角色 + USER_UPDATE 权限`
+3. 只有 Token 要求时写 `需要有效 Token`
+4. 无需登录时直接写 `无需登录`
+
+### 前置条件
+
+这里只写接口调用前必须知道的约束，例如：
+
+1. 需要先登录并回填 `user_token`
+2. 需要先创建用户再传入 `userId`
+3. 重复调用可能因为唯一约束失败
+4. 接口当前实现为空
+5. 该接口不走全局返回包装
+
+没有额外限制时写 `无`
+
+### 请求参数
+
+只写请求对象名和对象说明文件，不在 `.http` 内展开字段
+
+推荐格式：
+
+1. `无`
+2. `UserCreateRequest，详见 ./object/user.md`
+3. `Page<UserQuery>，详见 ./object/common.md 和 ./object/user.md`
+
+### 返回参数
+
+只写业务返回对象名和对象说明文件，不在 `.http` 内展开字段
+
+推荐格式：
+
+1. `无`
+2. `User，详见 ./object/user.md`
+3. `PageResult<User>，详见 ./object/common.md 和 ./object/user.md`
+4. `二进制数据流，该接口不走全局返回包装`
+
+## `./object` 编写要求
+
+对象说明统一使用 Markdown 表格，推荐结构如下
+
+```md
+## User
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| name | String | 登录名，系统内唯一 |
+
+## RoleCode
+
+| 枚举 | 说明 |
+|---|---|
+| SYSTEM | 系统 |
+| ADMIN | 管理员 |
+```
+
+### 对象说明规则
+
+1. 一个对象一个标题，标题名必须和 `.http` 里引用的对象名一致
+2. 字段说明只写真实存在且调用方需要关心的内容
+3. 枚举单独列出，不要把枚举值混进普通字段表
+4. 嵌套对象、列表元素对象也要有独立标题
+5. 通用壳子对象统一写在 `./object/common.md`
+
+## 维护要求
+
+1. 一个控制器通常对应一个 `.http` 文件
+2. 新增接口时，同步补齐对应 `.http`
+3. 新增或修改对象字段时，同步更新对应 `./object/*.md`
+4. 注释语言统一用中文
+5. 示例请求优先保证可调试，其次才是看起来完整

http/common/attachment.http

@@ -0,0 +1,200 @@
+### AttachmentController 接口测试
+### 在 IDEA 中选择 dev 或 prod 环境后执行
+
+@attachmentId =
+@attachmentBizType = TEMP_FILE
+@attachmentBizId = demo-biz-id
+@attachmentAttachType = SOURCE
+@attachmentName = demo.png
+@attachmentFilePath = E:/Temp/demo.png
+@attachmentTempFileId =
+
+### 查询附件详情
+### 前置条件：`id` 必须传有效附件 ID
+### 请求参数：URL 参数 `id` 为附件 ID
+### 返回参数：Attachment，详见 ./object/common.md
+POST {{baseUrl}}/attach/detail?id={{attachmentId}}
+Token: {{user_token}}
+
+### 创建附件
+### 前置条件：回填 `attachmentFilePath` 为本地文件绝对路径
+### 请求参数：multipart/form-data
+### 返回参数：Attachment，详见 ./object/common.md
+POST {{baseUrl}}/attach/create
+Content-Type: multipart/form-data; boundary=AttachmentCreateBoundary
+Token: {{user_token}}
+
+--AttachmentCreateBoundary
+Content-Disposition: form-data; name="bizType"
+
+{{attachmentBizType}}
+--AttachmentCreateBoundary
+Content-Disposition: form-data; name="bizId"
+
+{{attachmentBizId}}
+--AttachmentCreateBoundary
+Content-Disposition: form-data; name="attachType"
+
+{{attachmentAttachType}}
+--AttachmentCreateBoundary
+Content-Disposition: form-data; name="name"
+
+{{attachmentName}}
+--AttachmentCreateBoundary
+Content-Disposition: form-data; name="file"; filename="demo.png"
+Content-Type: application/octet-stream
+
+< {{attachmentFilePath}}
+--AttachmentCreateBoundary--
+
+### 更新附件元数据
+### 前置条件：`id` 必须传有效附件 ID
+### 请求参数：multipart/form-data
+### 返回参数：无
+POST {{baseUrl}}/attach/update
+Content-Type: multipart/form-data; boundary=AttachmentUpdateMetaBoundary
+Token: {{user_token}}
+
+--AttachmentUpdateMetaBoundary
+Content-Disposition: form-data; name="id"
+
+{{attachmentId}}
+--AttachmentUpdateMetaBoundary
+Content-Disposition: form-data; name="name"
+
+{{attachmentName}}-updated
+--AttachmentUpdateMetaBoundary
+Content-Disposition: form-data; name="attachType"
+
+{{attachmentAttachType}}
+--AttachmentUpdateMetaBoundary--
+
+### 更新附件文件
+### 前置条件：`id` 必须传有效附件 ID，`attachmentFilePath` 必须传本地文件绝对路径
+### 请求参数：multipart/form-data
+### 返回参数：无
+POST {{baseUrl}}/attach/update
+Content-Type: multipart/form-data; boundary=AttachmentUpdateFileBoundary
+Token: {{user_token}}
+
+--AttachmentUpdateFileBoundary
+Content-Disposition: form-data; name="id"
+
+{{attachmentId}}
+--AttachmentUpdateFileBoundary
+Content-Disposition: form-data; name="name"
+
+{{attachmentName}}-file-updated
+--AttachmentUpdateFileBoundary
+Content-Disposition: form-data; name="file"; filename="demo.png"
+Content-Type: application/octet-stream
+
+< {{attachmentFilePath}}
+--AttachmentUpdateFileBoundary--
+
+### 删除附件
+### 前置条件：`id` 必须传有效附件 ID
+### 请求参数：URL 参数 `id` 为附件 ID
+### 返回参数：无
+POST {{baseUrl}}/attach/delete?id={{attachmentId}}
+Token: {{user_token}}
+
+### 按业务查询单个附件
+### 前置条件：`bizType` 和 `bizId` 必须传有效值
+### 请求参数：URL 参数 `bizType`、`bizId`
+### 返回参数：Attachment，详见 ./object/common.md
+GET {{baseUrl}}/attach/detail/byBiz?bizType={{attachmentBizType}}&bizId={{attachmentBizId}}
+Token: {{user_token}}
+
+### 按业务和附件类型查询单个附件
+### 前置条件：`bizType`、`bizId`、`attachType` 必须传有效值
+### 请求参数：URL 参数 `bizType`、`bizId`、`attachType`
+### 返回参数：Attachment，详见 ./object/common.md
+GET {{baseUrl}}/attach/detail/byAttachType?bizType={{attachmentBizType}}&bizId={{attachmentBizId}}&attachType={{attachmentAttachType}}
+Token: {{user_token}}
+
+### 按业务查询附件列表
+### 前置条件：`bizType` 和 `bizId` 必须传有效值
+### 请求参数：URL 参数 `bizType`、`bizId`，可重复传 `attachTypeList`
+### 返回参数：Attachment[]
+GET {{baseUrl}}/attach/list/byBiz?bizType={{attachmentBizType}}&bizId={{attachmentBizId}}&attachTypeList={{attachmentAttachType}}
+Token: {{user_token}}
+
+### 按业务统计附件数量
+### 前置条件：`bizType` 和 `bizId` 必须传有效值
+### 请求参数：URL 参数 `bizType`、`bizId`，可重复传 `attachTypeList`
+### 返回参数：number
+GET {{baseUrl}}/attach/count/byBiz?bizType={{attachmentBizType}}&bizId={{attachmentBizId}}&attachTypeList={{attachmentAttachType}}
+Token: {{user_token}}
+
+### 按业务分页查询附件
+### 前置条件：`bizType` 和 `bizId` 必须传有效值
+### 请求参数：URL 参数 `bizType`、`bizId`，可重复传 `attachTypeList`，请求体为 Page
+### 返回参数：PageResult<Attachment>
+POST {{baseUrl}}/attach/page/byBiz?bizType={{attachmentBizType}}&bizId={{attachmentBizId}}&attachTypeList={{attachmentAttachType}}
+Content-Type: application/json
+Token: {{user_token}}
+
+{
+	"index": 0,
+	"size": 10
+}
+
+### 按业务差分更新附件
+### 前置条件：新增项需要传有效 `tempFileId`
+### 请求参数：BizUpdateReq
+### 返回参数：无
+POST {{baseUrl}}/attach/update/byBiz
+Content-Type: application/json
+Token: {{user_token}}
+
+{
+	"bizType": "{{attachmentBizType}}",
+	"bizId": "{{attachmentBizId}}",
+	"items": [
+		{
+			"id": "{{attachmentId}}",
+			"attachType": "{{attachmentAttachType}}",
+			"name": "{{attachmentName}}-biz-updated"
+		},
+		{
+			"tempFileId": "{{attachmentTempFileId}}",
+			"attachType": "{{attachmentAttachType}}",
+			"name": "{{attachmentName}}-from-temp"
+		}
+	]
+}
+
+### 按业务删除全部附件
+### 前置条件：`bizType` 和 `bizId` 必须传有效值
+### 请求参数：BizDeleteReq
+### 返回参数：无
+POST {{baseUrl}}/attach/delete/byBiz
+Content-Type: application/json
+Token: {{user_token}}
+
+{
+	"bizType": "{{attachmentBizType}}",
+	"bizId": "{{attachmentBizId}}"
+}
+
+### 读取附件原图
+### 前置条件：`attachmentId` 必须传有效附件 ID
+### 请求参数：路径参数 `id`
+### 返回参数：附件二进制流
+GET {{baseUrl}}/attach/read/{{attachmentId}}
+Token: {{user_token}}
+
+### 读取附件缩略图
+### 前置条件：`attachmentId` 必须传有效图片或视频附件 ID
+### 请求参数：路径参数 `id`，URL 参数 `thumbWidth`、`thumbHeight`
+### 返回参数：附件二进制流
+GET {{baseUrl}}/attach/read/{{attachmentId}}?thumbWidth=200&thumbHeight=200
+Token: {{user_token}}
+
+### 下载附件
+### 前置条件：`attachmentId` 必须传有效附件 ID
+### 请求参数：路径参数 `id`
+### 返回参数：附件二进制流
+GET {{baseUrl}}/attach/download/{{attachmentId}}
+Token: {{user_token}}

http/common/multilingual.http

@@ -0,0 +1,66 @@
+### MultilingualController 接口测试
+### 在 IDEA 中选择 dev 或 prod 环境后执行
+
+@multilingualId =
+@multilingualZhCN = 测试简体中文
+@multilingualZhTW = 測試繁體中文
+@multilingualEnUS = Test English
+@multilingualRuRU = Тест
+@multilingualJaJP = テスト
+@multilingualDeDE = Test Deutsch
+@multilingualKoKR = 테스트
+
+### 查询多语言详情
+### 权限：需要 ADMIN 角色 +  MULTILINGUAL_READ 权限
+### 前置条件：需要先登录并回填 `user_token`，URL 参数 `id` 必须传有效多语言 ID
+### 请求参数：无请求体，URL 参数：`id` 为多语言 ID
+### 返回参数：Multilingual，详见 ./object/common.md
+POST {{baseUrl}}/system/multilingual/detail?id={{multilingualId}}
+Token: {{user_token}}
+
+### 创建多语言
+### 权限：需要 ADMIN 角色 +  MULTILINGUAL_CREATE 权限
+### 前置条件：需要先登录并回填 `user_token`
+### 请求参数：Multilingual，详见 ./object/common.md
+### 返回参数：Multilingual，详见 ./object/common.md
+POST {{baseUrl}}/system/multilingual/create
+Content-Type: application/json
+Token: {{user_token}}
+
+{
+	"zhCN": "{{multilingualZhCN}}",
+	"zhTW": "{{multilingualZhTW}}",
+	"enUS": "{{multilingualEnUS}}",
+	"ruRU": "{{multilingualRuRU}}",
+	"jaJP": "{{multilingualJaJP}}",
+	"deDE": "{{multilingualDeDE}}",
+	"koKR": "{{multilingualKoKR}}"
+}
+
+### 更新多语言
+### 权限：需要 ADMIN 角色 +  MULTILINGUAL_UPDATE 权限
+### 前置条件：需要先登录并回填 `user_token`，`id` 必须存在
+### 请求参数：Multilingual，详见 ./object/common.md
+### 返回参数：无
+POST {{baseUrl}}/system/multilingual/update
+Content-Type: application/json
+Token: {{user_token}}
+
+{
+	"id": "{{multilingualId}}",
+	"zhCN": "{{multilingualZhCN}}-已更新",
+	"zhTW": "{{multilingualZhTW}}-已更新",
+	"enUS": "{{multilingualEnUS}}-updated",
+	"ruRU": "{{multilingualRuRU}}-updated",
+	"jaJP": "{{multilingualJaJP}}-updated",
+	"deDE": "{{multilingualDeDE}}-updated",
+	"koKR": "{{multilingualKoKR}}-updated"
+}
+
+### 删除多语言
+### 权限：需要 ADMIN 角色 +  MULTILINGUAL_DELETE 权限
+### 前置条件：需要先登录并回填 `user_token`，URL 参数 `id` 必须传有效多语言 ID
+### 请求参数：无请求体，URL 参数：`id` 为多语言 ID
+### 返回参数：无
+POST {{baseUrl}}/system/multilingual/delete?id={{multilingualId}}
+Token: {{user_token}}

http/gao/action.http

@@ -0,0 +1,60 @@
+### GaoRegisterAction 接口测试
+### 在 IDEA 中选择 dev 或 prod 环境后执行
+
+@actionId =
+
+### 分页查询登记行为
+POST {{baseUrl}}/gao/action/list
+Content-Type: application/json
+Token: {{user_token}}
+
+{
+	"index": 0,
+	"size": 16
+}
+
+### 查询启用行为
+POST {{baseUrl}}/gao/action/enabled/list
+Token: {{user_token}}
+
+### 查询行为详情
+POST {{baseUrl}}/gao/action/detail?id={{actionId}}
+Token: {{user_token}}
+
+### 创建登记行为
+POST {{baseUrl}}/gao/action/create
+Content-Type: application/json
+Token: {{user_token}}
+
+{
+	"name": "签到",
+	"description": "客户到店签到",
+	"enabled": true,
+	"requirePhoto": false,
+	"sort": 10,
+	"permissionCodeList": [
+		"RECORD:CREATE"
+	]
+}
+
+### 更新登记行为
+POST {{baseUrl}}/gao/action/update
+Content-Type: application/json
+Token: {{user_token}}
+
+{
+	"id": "{{actionId}}",
+	"name": "物品领取",
+	"description": "登记客户领取物品",
+	"enabled": true,
+	"requirePhoto": true,
+	"sort": 20,
+	"permissionCodeList": [
+		"RECORD:CREATE",
+		"STAT:READ"
+	]
+}
+
+### 删除登记行为
+POST {{baseUrl}}/gao/action/delete?id={{actionId}}
+Token: {{user_token}}

http/gao/customer.http

@@ -0,0 +1,119 @@
+### GaoCustomer 接口测试
+### 在 IDEA 中选择 dev 或 prod 环境后执行
+
+@customerId =
+@introducerCustomerId =
+@customerCode = GAO-0001
+
+### 分页查询客户
+POST {{baseUrl}}/gao/customer/list
+Content-Type: application/json
+Token: {{user_token}}
+
+{
+	"index": 0,
+	"size": 16
+}
+
+### 搜索客户
+POST {{baseUrl}}/gao/customer/search
+Content-Type: application/json
+Token: {{user_token}}
+
+{
+	"keyword": "张",
+	"introducerCustomerId": "{{introducerCustomerId}}"
+}
+
+### 查询客户详情
+POST {{baseUrl}}/gao/customer/detail?id={{customerId}}
+Token: {{user_token}}
+
+### 按客户编码查询
+POST {{baseUrl}}/gao/customer/detail/code?code={{customerCode}}
+Token: {{user_token}}
+
+### 查询某客户邀请了哪些人
+POST {{baseUrl}}/gao/customer/invited/list?introducerCustomerId={{customerId}}
+Token: {{user_token}}
+
+### 创建客户
+POST {{baseUrl}}/gao/customer/create
+Content-Type: application/json
+Token: {{user_token}}
+
+{
+	"code": "{{customerCode}}",
+	"name": "张三",
+	"age": 56,
+	"telephone": "020-88886666",
+	"address": "广州市天河区某街道",
+	"remark": "首诊客户",
+	"disease": "肩颈不适",
+	"conditioningPart": [
+		{
+			"code": "neck",
+			"name": "颈部"
+		},
+		{
+			"code": "shoulder",
+			"name": "肩部"
+		}
+	],
+	"introducerCustomerId": "{{introducerCustomerId}}"
+}
+
+### 更新客户
+POST {{baseUrl}}/gao/customer/update
+Content-Type: application/json
+Token: {{user_token}}
+
+{
+	"id": "{{customerId}}",
+	"code": "{{customerCode}}",
+	"name": "张三",
+	"age": 57,
+	"telephone": "020-88886667",
+	"address": "广州市天河区某街道 88 号",
+	"remark": "复诊客户",
+	"disease": "腰背调理",
+	"conditioningPart": {
+		"parts": [
+			"waist",
+			"back"
+		]
+	},
+	"introducerCustomerId": "{{introducerCustomerId}}"
+}
+
+### 删除客户
+POST {{baseUrl}}/gao/customer/delete?id={{customerId}}
+Token: {{user_token}}
+
+### 创建客户邀请关系
+POST {{baseUrl}}/gao/customer/invite/create
+Content-Type: application/json
+Token: {{user_token}}
+
+{
+	"customerId": "{{customerId}}",
+	"introducerCustomerId": "{{introducerCustomerId}}"
+}
+
+### 查询客户邀请关系详情
+POST {{baseUrl}}/gao/customer/invite/detail?customerId={{customerId}}
+Token: {{user_token}}
+
+### 更新客户邀请关系
+POST {{baseUrl}}/gao/customer/invite/update
+Content-Type: application/json
+Token: {{user_token}}
+
+{
+	"customerId": "{{customerId}}",
+	"introducerCustomerId": "{{introducerCustomerId}}"
+}
+
+### 删除客户邀请关系
+POST {{baseUrl}}/gao/customer/invite/delete?customerId={{customerId}}
+Token: {{user_token}}

http/gao/record.http

@@ -0,0 +1,86 @@
+### GaoRegisterRecord 接口测试
+### 在 IDEA 中选择 dev 或 prod 环境后执行
+
+@recordId =
+@customerId =
+@customerCode = GAO-0001
+@actionId =
+
+### 分页查询登记记录
+POST {{baseUrl}}/gao/record/list
+Content-Type: application/json
+Token: {{user_token}}
+
+{
+	"index": 0,
+	"size": 16
+}
+
+### 查询登记记录详情
+POST {{baseUrl}}/gao/record/detail?id={{recordId}}
+Token: {{user_token}}
+
+### 创建登记记录，直接传客户 ID
+POST {{baseUrl}}/gao/record/create
+Content-Type: application/json
+Token: {{user_token}}
+
+{
+	"customerId": "{{customerId}}",
+	"actionId": "{{actionId}}",
+	"remark": "客户到店签到"
+}
+
+### 创建登记记录，扫码后传客户编码
+POST {{baseUrl}}/gao/record/create
+Content-Type: application/json
+Token: {{user_token}}
+
+{
+	"customerCode": "{{customerCode}}",
+	"actionId": "{{actionId}}",
+	"remark": "扫码快速登记"
+}
+
+### 更新登记记录
+POST {{baseUrl}}/gao/record/update
+Content-Type: application/json
+Token: {{user_token}}
+
+{
+	"id": "{{recordId}}",
+	"customerId": "{{customerId}}",
+	"actionId": "{{actionId}}",
+	"remark": "补充备注",
+	"registeredAt": 1785110400
+}
+
+### 删除登记记录
+POST {{baseUrl}}/gao/record/delete?id={{recordId}}
+Token: {{user_token}}
+
+### 按日查询某个行为记录
+POST {{baseUrl}}/gao/record/period/list
+Content-Type: application/json
+Token: {{user_token}}
+
+{
+	"actionId": "{{actionId}}",
+	"periodType": "DAY",
+	"periodValue": 20260727
+}
+
+### 按月统计某个行为记录
+POST {{baseUrl}}/gao/record/period/stat
+Content-Type: application/json
+Token: {{user_token}}
+
+{
+	"actionId": "{{actionId}}",
+	"periodType": "MONTH",
+	"periodValue": 202607
+}
+
+### 查询客户所有登记统计
+POST {{baseUrl}}/gao/record/customer/stat?customerId={{customerId}}
+Token: {{user_token}}

http/http-client.env.json

@@ -0,0 +1,8 @@
+{
+	"dev": {
+		"baseUrl": "http://localhost:8091"
+	},
+	"prod": {
+		"baseUrl": "https://api.example.com"
+	}
+}

http/object/common.md

@@ -0,0 +1,77 @@
+# 通用对象说明
+
+## TimiResponse<T>
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| code | Integer | 响应码，`20000` 为成功 |
+| msg | String | 响应消息 |
+| data | T | 业务数据体，具体结构由接口返回对象决定 |
+
+## Page<T>
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| index | int | 页码下标，从 `0` 开始 |
+| size | long | 每页数量 |
+| equalsExample | T | 精确匹配示例对象，非空字段参与精确查询 |
+| likesExample | T | 模糊匹配示例对象，非空字段参与模糊查询 |
+| equalsLogic | Logic | 精确匹配字段之间的连接逻辑，默认 `AND` |
+| likesLogic | Logic | 模糊匹配字段之间的连接逻辑，默认 `OR` |
+| orderMap | LinkedHashMap<String, OrderType> | 排序字段映射，键通常为字段名，值为排序方向 |
+
+## PageResult<T>
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| total | long | 总数据量 |
+| pages | int | 总页数 |
+| list | List<T> | 当前页数据列表 |
+
+## UUIDEntity
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | String | 主键 ID，UUID 字符串 |
+| createdAt | Long | 创建时间，Unix 时间戳毫秒 |
+| updatedAt | Long | 更新时间，Unix 时间戳毫秒 |
+| deletedAt | Long | 删除时间，Unix 时间戳毫秒，未删除时通常为空 |
+
+## Multilingual
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | String | 多语言 ID |
+| zhCN | String | 简体中文文本 |
+| zhTW | String | 繁体中文文本 |
+| enUS | String | 英文文本 |
+| ruRU | String | 俄文文本 |
+| jaJP | String | 日文文本 |
+| deDE | String | 德文文本 |
+| koKR | String | 韩文文本 |
+| lastAccessAt | Long | 最后访问时间，Unix 时间戳毫秒 |
+| createdAt | Long | 创建时间，Unix 时间戳毫秒 |
+| updatedAt | Long | 更新时间，Unix 时间戳毫秒 |
+| deletedAt | Long | 删除时间，Unix 时间戳毫秒，未删除时通常为空 |
+
+## Logic
+
+| 枚举 | 说明 |
+|---|---|
+| AND | 多个条件同时满足 |
+| OR | 多个条件满足其一 |
+
+## OrderType
+
+| 枚举 | 说明 |
+|---|---|
+| ASC | 升序 |
+| DESC | 降序 |
+
+## ImageType
+
+| 枚举 | 说明 |
+|---|---|
+| AUTO | 双线性 |
+| SMOOTH | 模糊 |
+| PIXELATED | 像素 |

http/object/permission.md

@@ -0,0 +1,31 @@
+# 权限对象说明
+
+## Permission
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | String | 权限 ID |
+| createdAt | Long | 创建时间，Unix 时间戳毫秒 |
+| updatedAt | Long | 更新时间，Unix 时间戳毫秒 |
+| deletedAt | Long | 删除时间，Unix 时间戳毫秒 |
+| code | String | 权限代码，需与数据库 `permission.code` 保持一致 |
+| nameLangId | String | 权限名称的多语言键 |
+| description | String | 权限说明 |
+| name | String | 当前语言下的权限名称 |
+
+## BatchCreateReq
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| prefixCode | String | 权限代码前缀，例如 `ROLE` |
+| prefixName | String | 权限名称前缀，例如 `角色` |
+| types | Type[] | 需要批量生成的权限类型列表，详见 `BatchCreateType` |
+
+## BatchCreateType
+
+| 枚举 | 说明 |
+|---|---|
+| CREATE | 创建权限 |
+| READ | 读取权限 |
+| UPDATE | 更新权限 |
+| DELETE | 删除权限 |

http/object/role.md

@@ -0,0 +1,34 @@
+# 角色对象说明
+
+## Role
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | String | 角色 ID |
+| createdAt | Long | 创建时间，Unix 时间戳毫秒 |
+| updatedAt | Long | 更新时间，Unix 时间戳毫秒 |
+| deletedAt | Long | 删除时间，Unix 时间戳毫秒 |
+| code | String | 角色代码，常见值见 `RoleCode` |
+| nameLangId | String | 角色名称的多语言键 |
+| description | String | 角色说明 |
+| name | String | 当前语言下的角色名称 |
+| permissionList | List<Permission> | 角色自身直接绑定的权限列表 |
+| allPermissionList | List<Permission> | 角色全部权限列表，包含继承自子角色的权限 |
+| childRoleList | List<Role> | 子角色列表 |
+| permissionIdList | Set<String> | 权限 ID 列表，创建或更新角色时使用 |
+| childRoleIdList | Set<String> | 子角色 ID 列表，创建或更新角色时使用 |
+
+## UserRoleAuthorizeReq
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| userId | String | 目标用户 ID |
+| roleIdList | List<String> | 需要授权的角色 ID 列表 |
+| roleCodeList | List<String> | 需要授权的角色代码列表 |
+
+## RoleCode
+
+| 枚举 | 说明 |
+|---|---|
+| SYSTEM | 系统 |
+| ADMIN | 管理员 |

http/object/user.md

@@ -0,0 +1,73 @@
+# 用户对象说明
+
+## User
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | String | 用户 ID |
+| createdAt | Long | 创建时间，Unix 时间戳毫秒 |
+| updatedAt | Long | 更新时间，Unix 时间戳毫秒 |
+| deletedAt | Long | 删除时间，Unix 时间戳毫秒 |
+| name | String | 登录名，系统内唯一 |
+| nick | String | 用户昵称 |
+| password | String | 明文密码，请求时填写，响应通常不返回 |
+| email | String | 邮箱地址 |
+| emailVerifyAt | Long | 邮箱验证时间，Unix 时间戳毫秒 |
+| phoneNo | String | 手机号，11 位大陆手机号 |
+| phoneNoVerifyAt | Long | 手机号验证时间，Unix 时间戳毫秒 |
+| wrapperType | ImageType | 背景图渲染算法，详见 `ImageType` |
+| avatarType | ImageType | 头像渲染算法，详见 `ImageType` |
+| exp | Integer | 经验值 |
+| sex | Integer | 性别，当前代码未定义枚举说明 |
+| birthdate | Long | 出生日期，Unix 时间戳毫秒 |
+| qq | String | QQ 号 |
+| description | String | 个人说明 |
+| lastLoginIP | String | 上次登录 IP |
+| lastLoginAt | Long | 上次登录时间，Unix 时间戳毫秒 |
+| unmuteAt | Long | 解除禁言时间，Unix 时间戳毫秒 |
+| unbanAt | Long | 解除封禁时间，Unix 时间戳毫秒 |
+| roleList | List<String> | 角色代码列表 |
+| permissionList | List<String> | 权限代码列表 |
+| attachmentList | List<Attachment> | 附件列表 |
+| settingList | List<Setting> | 设置列表 |
+
+## LoginRequest
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| user | String | 用户标识，可能是 UID、邮箱或用户名 |
+| password | String | 明文密码 |
+
+## LoginResponse
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| token | String | 登录令牌 |
+| expireAt | Long | 令牌过期时间，Unix 时间戳毫秒 |
+| user | User | 当前登录用户 |
+
+## UpdatePasswordRequest
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| oldValue | String | 原密码 |
+| newValue | String | 新密码 |
+
+## PhoneVerifyCodeSendRequest
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| phoneNo | String | 手机号，必须为 11 位大陆手机号 |
+
+## PhoneVerifyRequest
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| phoneNo | String | 手机号，必须为 11 位大陆手机号 |
+| verifyCode | String | 6 位数字验证码 |
+
+## CancelRequest
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| password | String | 当前密码，用于确认注销 |

http/user/permission.http

@@ -0,0 +1,84 @@
+### PermissionController 接口测试
+### 在 IDEA 中选择 dev 或 prod 环境后执行
+
+@user_token =
+@permissionId =
+@permissionCode = TEST_PERMISSION
+@permissionNameLangId = permission.test.name
+@permissionDescription = 测试权限
+@moduleCode = CORE
+
+### 分页查询权限
+### 权限：需要 PERMISSION_READ 权限
+### 前置条件：需要先登录并回填 `user_token`
+### 请求参数：Page<Permission>，详见 ./http/object/permission.md
+### 返回参数：PageResult<Permission>，详见 ./http/object/permission.md
+POST {{baseUrl}}/user/permission/list
+Content-Type: application/json
+Token: {{user_token}}
+
+{
+	"index": 0,
+	"size": 10,
+	"likesExample": {
+		"code": "{{permissionCode}}",
+		"moduleCode": "{{moduleCode}}"
+	}
+}
+
+### 创建权限
+### 权限：当前代码要求 PERMISSION_READ 权限
+### 前置条件：需要先登录并回填 `user_token`
+### 请求参数：Permission，详见 ./http/object/permission.md
+### 返回参数：无
+POST {{baseUrl}}/user/permission/create
+Content-Type: application/json
+Token: {{user_token}}
+
+{
+	"moduleCode": "{{moduleCode}}",
+	"code": "{{permissionCode}}",
+	"nameLangId": "{{permissionNameLangId}}",
+	"description": "{{permissionDescription}}"
+}
+
+### 批量创建权限
+### 权限：需要 PERMISSION_CREATE 权限
+### 前置条件：需要先登录并回填 `user_token`
+### 请求参数：BatchCreateReq，详见 ./http/object/permission.md
+### 返回参数：无
+POST {{baseUrl}}/user/permission/create/batch
+Content-Type: application/json
+Token: {{user_token}}
+
+{
+	"moduleCode": "{{moduleCode}}",
+	"prefixCode": "ROLE",
+	"prefixName": "角色",
+	"types": ["CREATE", "READ", "UPDATE", "DELETE"]
+}
+
+### 更新权限
+### 权限：需要 PERMISSION_UPDATE 权限
+### 前置条件：需要先登录并回填 `user_token`，`id` 必须存在
+### 请求参数：Permission，详见 ./http/object/permission.md
+### 返回参数：无
+POST {{baseUrl}}/user/permission/update
+Content-Type: application/json
+Token: {{user_token}}
+
+{
+	"id": "{{permissionId}}",
+	"moduleCode": "{{moduleCode}}",
+	"code": "{{permissionCode}}",
+	"nameLangId": "{{permissionNameLangId}}",
+	"description": "测试权限-已更新"
+}
+
+### 删除权限
+### 权限：需要 PERMISSION_DELETE 权限
+### 前置条件：需要先登录并回填 `user_token`，URL 参数 `id` 必须传有效权限 ID
+### 请求参数：无请求体，URL 参数：`id` 为权限 ID
+### 返回参数：无
+POST {{baseUrl}}/user/permission/delete?id={{permissionId}}
+Token: {{user_token}}

http/user/role.http

@@ -0,0 +1,113 @@
+### RoleController 接口测试
+### 在 IDEA 中选择 dev 或 prod 环境后执行
+
+@permissionId =
+@roleId =
+@roleCode = TEST_ROLE
+@roleNameLangId = role.test.name
+@roleDescription = 测试角色
+@childRoleId =
+@authorizedUserId =
+@moduleCode = CORE
+
+### 分页查询角色
+### 权限：需要 ADMIN 角色 +  ROLE_READ 权限
+### 前置条件：需要先登录并回填 `user_token`
+### 请求参数：Page<Role>，详见 ./http/object/role.md
+### 返回参数：PageResult<Role>，详见 ./http/object/role.md
+POST {{baseUrl}}/user/role/list
+Content-Type: application/json
+Token: {{user_token}}
+
+{
+	"index": 0,
+	"size": 16,
+	"likesExample": {
+		"moduleCode": "{{moduleCode}}"
+	}
+}
+
+### 查询角色详情
+### 权限：需要 ADMIN 角色 +  ROLE_READ 权限
+### 前置条件：需要先登录并回填 `user_token`，URL 参数 `id` 必须传有效角色 ID
+### 请求参数：无请求体，URL 参数：`id` 为角色 ID
+### 返回参数：Role，详见 ./http/object/role.md
+POST {{baseUrl}}/user/role/detail?id={{roleId}}
+Token: {{user_token}}
+
+### 创建角色
+### 权限：需要 ADMIN 角色 +  ROLE_CREATE 权限
+### 前置条件：需要先登录并回填 `user_token`
+### 请求参数：Role，详见 ./http/object/role.md
+### 返回参数：无
+POST {{baseUrl}}/user/role/create
+Content-Type: application/json
+Token: {{user_token}}
+
+{
+	"moduleCode": "{{moduleCode}}",
+	"code": "{{roleCode}}",
+	"nameLangId": "{{roleNameLangId}}",
+	"description": "{{roleDescription}}",
+	"permissionIdList": ["{{permissionId}}"],
+	"childRoleIdList": []
+}
+
+### 更新角色
+### 权限：需要 ADMIN 角色 +  ROLE_UPDATE 权限
+### 前置条件：需要先登录并回填 `user_token`，`id` 必须存在
+### 请求参数：Role，详见 ./http/object/role.md
+### 返回参数：无
+POST {{baseUrl}}/user/role/update
+Content-Type: application/json
+Token: {{user_token}}
+
+{
+	"id": "{{roleId}}",
+	"moduleCode": "{{moduleCode}}",
+	"code": "{{roleCode}}",
+	"nameLangId": "{{roleNameLangId}}",
+	"description": "测试角色-已更新",
+	"permissionIdList": ["{{permissionId}}"],
+	"childRoleIdList": ["{{childRoleId}}"]
+}
+
+### 删除角色
+### 权限：需要 ADMIN 角色 +  ROLE_DELETE 权限
+### 前置条件：需要先登录并回填 `user_token`，URL 参数 `id` 必须传有效角色 ID
+### 请求参数：无请求体，URL 参数：`id` 为角色 ID
+### 返回参数：无
+POST {{baseUrl}}/user/role/delete?id={{roleId}}
+Token: {{user_token}}
+
+### 查询用户角色
+### 权限：需要 ADMIN 角色 +  USER_ROLE_READ 权限
+### 前置条件：需要先登录并回填 `user_token`，URL 参数 `userId` 必须传有效用户 ID
+### 请求参数：无请求体，URL 参数：`userId` 为用户 ID
+### 返回参数：List<Role>，详见 ./http/object/role.md
+POST {{baseUrl}}/user/role/authorized/list?userId={{authorizedUserId}}
+Token: {{user_token}}
+
+### 设置用户角色
+### 权限：需要 ADMIN 角色 + 同时具备 USER_ROLE_CREATE 和 USER_ROLE_DELETE 权限
+### 前置条件：需要先登录并回填 `user_token`
+### 请求参数：UserRoleAuthorizeReq，详见 ./http/object/role.md
+### 返回参数：无
+POST {{baseUrl}}/user/role/authorized/create
+Content-Type: application/json
+Token: {{user_token}}
+
+{
+	"userId": "{{authorizedUserId}}",
+	"moduleCode": "{{moduleCode}}",
+	"roleIdList": ["{{roleId}}"],
+	"roleCodeList": ["{{roleCode}}"]
+}
+
+### 查询用户已授权权限
+### 权限：需要 ADMIN 角色 +  USER_ROLE_READ 权限
+### 前置条件：需要先登录并回填 `user_token`，URL 参数 `userId` 必须传有效用户 ID
+### 请求参数：无请求体，URL 参数：`userId` 为用户 ID
+### 返回参数：List<Permission>，详见 ./http/object/permission.md
+POST {{baseUrl}}/user/role/authorized/permission?userId={{authorizedUserId}}
+Token: {{user_token}}

http/user/user.http

@@ -0,0 +1,186 @@
+### UserController 接口测试
+### 在 IDEA 中选择 dev 或 prod 环境后执行
+
+@userId =
+@name = System
+@password = u#HA027xq$i9]P}uB]LweJspTb!3oS^.
+@newPassword = qwe123
+@nick = 测试用户
+@email = test@example.com
+
+### 分页查询用户
+### 权限：需要 ADMIN 角色 + USER_READ 权限
+### 前置条件：需要先登录并回填 `user_token`
+### 请求参数：Page<User>，详见 ./http/object/user.md
+### 返回参数：PageResult<User>，详见 ./http/object/user.md
+POST {{baseUrl}}/user/list
+Content-Type: application/json
+Token: {{user_token}}
+
+{
+	"index": 0,
+	"size": 16
+}
+
+### 查询用户详情
+### 权限：需要 ADMIN 角色 + USER_READ 权限
+### 前置条件：需要先登录并回填 `user_token`，URL 参数 `id` 必须传有效用户 ID
+### 请求参数：无请求体，URL 参数：`id` 为用户 ID
+### 返回参数：User，详见 ./http/object/user.md
+POST {{baseUrl}}/user/detail?id={{userId}}
+Token: {{user_token}}
+
+### 创建用户
+### 权限：需要 ADMIN 角色 + USER_CREATE 权限
+### 前置条件：需要先登录并回填 `user_token`，重复用户名通常会失败
+### 请求参数：User，详见 ./http/object/user.md
+### 返回参数：无
+POST {{baseUrl}}/user/create
+Content-Type: application/json
+Token: {{user_token}}
+
+{
+	"name": "{{name}}",
+	"nick": "{{nick}}",
+	"email": "{{email}}",
+	"phoneNo": "13800138000",
+	"password": "{{password}}"
+}
+
+### 更新用户
+### 权限：需要 ADMIN 角色 + USER_UPDATE 权限
+### 前置条件：需要先登录并回填 `user_token`，`id` 必须存在
+### 请求参数：User，详见 ./http/object/user.md
+### 返回参数：无
+POST {{baseUrl}}/user/update
+Content-Type: application/json
+Token: {{user_token}}
+
+{
+	"id": "{{userId}}",
+	"name": "{{name}}",
+	"nick": "{{nick}}",
+	"email": "{{email}}",
+	"phoneNo": "13800138000"
+}
+
+### 删除用户
+### 权限：需要 ADMIN 角色
+### 前置条件：需要先登录并回填 `user_token`，URL 参数 `id` 必须传有效用户 ID
+### 请求参数：无请求体，URL 参数：`id` 为用户 ID
+### 返回参数：无
+POST {{baseUrl}}/user/delete?id={{userId}}
+Token: {{user_token}}
+
+### 注册
+### 权限：无需登录
+### 前置条件：重复用户名通常会失败
+### 请求参数：User，详见 ./http/object/user.md
+### 返回参数：LoginResponse，详见 ./http/object/user.md
+POST {{baseUrl}}/user/register
+Content-Type: application/json
+
+{
+	"name": "Test",
+	"nick": "测试用户",
+	"phoneNo": "13800138000",
+	"password": "qwe123"
+}
+
+### 登录
+### 权限：无需登录
+### 前置条件：成功后需要把响应中的 token 回填到 `user_token`
+### 请求参数：LoginRequest，详见 ./http/object/user.md
+### 返回参数：LoginResponse，详见 ./http/object/user.md
+POST {{baseUrl}}/user/login
+Content-Type: application/json
+
+{
+	"user": "{{name}}",
+	"password": "{{password}}"
+}
+
+> {%
+client.global.set("user_token", response.body?.data?.token)
+%}
+
+### 令牌登录
+### 权限：需要有效 Token
+### 前置条件：需要先登录并回填 `user_token`
+### 请求参数：无
+### 返回参数：LoginResponse，详见 ./http/object/user.md
+GET {{baseUrl}}/user/login/token
+Token: {{user_token}}
+
+### 登出
+### 权限：当前控制器未声明 RequiredToken/权限注解，按服务端实际会话处理
+### 前置条件：当前接口通常用于退出当前登录态
+### 请求参数：无
+### 返回参数：无
+POST {{baseUrl}}/user/logout
+Token: {{user_token}}
+
+### 修改当前用户密码
+### 权限：需要 USER_UPDATE 权限
+### 前置条件：需要先登录并回填 `user_token`
+### 请求参数：UpdatePasswordRequest，详见 ./http/object/user.md
+### 返回参数：无
+POST {{baseUrl}}/user/update/password
+Content-Type: application/json
+Token: {{user_token}}
+
+{
+	"oldValue": "{{password}}",
+	"newValue": "{{newPassword}}"
+}
+
+### 修改当前用户邮箱
+### 权限：需要 USER_UPDATE 权限
+### 前置条件：当前方法体为空，接口尚未实现
+### 请求参数：无
+### 返回参数：无
+POST {{baseUrl}}/user/update/email
+Content-Type: application/json
+Token: {{user_token}}
+
+{}
+
+### 发送当前用户手机号验证码
+### 权限：需要 USER_UPDATE 权限
+### 前置条件：需要先登录并回填 `user_token`
+### 请求参数：PhoneVerifyCodeSendRequest，详见 ./http/object/user.md
+### 返回参数：无
+POST {{baseUrl}}/user/phone/verify/send
+Content-Type: application/json
+Token: {{user_token}}
+
+{
+	"phoneNo": "13800138000"
+}
+
+### 验证当前用户手机号
+### 权限：需要 USER_UPDATE 权限
+### 前置条件：需要先调用手机号验证码发送接口获取验证码
+### 请求参数：PhoneVerifyRequest，详见 ./http/object/user.md
+### 返回参数：无
+POST {{baseUrl}}/user/phone/verify
+Content-Type: application/json
+Token: {{user_token}}
+
+{
+	"phoneNo": "13800138000",
+	"verifyCode": "123456"
+}
+
+### 注销当前用户
+### 权限：需要 USER_DELETE 权限
+### 前置条件：需要先登录并回填 `user_token`
+### 请求参数：CancelRequest，详见 ./http/object/user.md
+### 返回参数：无
+POST {{baseUrl}}/user/cancel
+Content-Type: application/json
+Token: {{user_token}}
+
+{
+	"password": "{{password}}"
+}