diff --git a/http/README.md b/http/README.md deleted file mode 100644 index 01372e0..0000000 --- a/http/README.md +++ /dev/null @@ -1,163 +0,0 @@ -# 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,详见 ./object/common.md 和 ./object/user.md` - -### 返回参数 - -只写业务返回对象名和对象说明文件,不在 `.http` 内展开字段 - -推荐格式: - -1. `无` -2. `User,详见 ./object/user.md` -3. `PageResult,详见 ./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. 示例请求优先保证可调试,其次才是看起来完整 diff --git a/http/common/attachment.http b/http/common/attachment.http deleted file mode 100644 index afde9b4..0000000 --- a/http/common/attachment.http +++ /dev/null @@ -1,200 +0,0 @@ -### 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 -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}} diff --git a/http/common/multilingual.http b/http/common/multilingual.http deleted file mode 100644 index 882de25..0000000 --- a/http/common/multilingual.http +++ /dev/null @@ -1,66 +0,0 @@ -### 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}} diff --git a/http/gao/action.http b/http/gao/action.http deleted file mode 100644 index 3f5dd3e..0000000 --- a/http/gao/action.http +++ /dev/null @@ -1,60 +0,0 @@ -### 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}} diff --git a/http/gao/customer.http b/http/gao/customer.http deleted file mode 100644 index c5166cb..0000000 --- a/http/gao/customer.http +++ /dev/null @@ -1,119 +0,0 @@ -### 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}} diff --git a/http/gao/record.http b/http/gao/record.http deleted file mode 100644 index 005981b..0000000 --- a/http/gao/record.http +++ /dev/null @@ -1,86 +0,0 @@ -### 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}} diff --git a/http/http-client.env.json b/http/http-client.env.json deleted file mode 100644 index 22a7d47..0000000 --- a/http/http-client.env.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "dev": { - "baseUrl": "http://localhost:8091" - }, - "prod": { - "baseUrl": "https://api.example.com" - } -} diff --git a/http/object/common.md b/http/object/common.md deleted file mode 100644 index 76ce040..0000000 --- a/http/object/common.md +++ /dev/null @@ -1,77 +0,0 @@ -# 通用对象说明 - -## TimiResponse - -| 字段 | 类型 | 说明 | -|---|---|---| -| code | Integer | 响应码,`20000` 为成功 | -| msg | String | 响应消息 | -| data | T | 业务数据体,具体结构由接口返回对象决定 | - -## Page - -| 字段 | 类型 | 说明 | -|---|---|---| -| index | int | 页码下标,从 `0` 开始 | -| size | long | 每页数量 | -| equalsExample | T | 精确匹配示例对象,非空字段参与精确查询 | -| likesExample | T | 模糊匹配示例对象,非空字段参与模糊查询 | -| equalsLogic | Logic | 精确匹配字段之间的连接逻辑,默认 `AND` | -| likesLogic | Logic | 模糊匹配字段之间的连接逻辑,默认 `OR` | -| orderMap | LinkedHashMap | 排序字段映射,键通常为字段名,值为排序方向 | - -## PageResult - -| 字段 | 类型 | 说明 | -|---|---|---| -| total | long | 总数据量 | -| pages | int | 总页数 | -| list | List | 当前页数据列表 | - -## 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 | 像素 | diff --git a/http/object/permission.md b/http/object/permission.md deleted file mode 100644 index 577f384..0000000 --- a/http/object/permission.md +++ /dev/null @@ -1,31 +0,0 @@ -# 权限对象说明 - -## 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 | 删除权限 | diff --git a/http/object/role.md b/http/object/role.md deleted file mode 100644 index 5304d45..0000000 --- a/http/object/role.md +++ /dev/null @@ -1,34 +0,0 @@ -# 角色对象说明 - -## Role - -| 字段 | 类型 | 说明 | -|---|---|---| -| id | String | 角色 ID | -| createdAt | Long | 创建时间,Unix 时间戳毫秒 | -| updatedAt | Long | 更新时间,Unix 时间戳毫秒 | -| deletedAt | Long | 删除时间,Unix 时间戳毫秒 | -| code | String | 角色代码,常见值见 `RoleCode` | -| nameLangId | String | 角色名称的多语言键 | -| description | String | 角色说明 | -| name | String | 当前语言下的角色名称 | -| permissionList | List | 角色自身直接绑定的权限列表 | -| allPermissionList | List | 角色全部权限列表,包含继承自子角色的权限 | -| childRoleList | List | 子角色列表 | -| permissionIdList | Set | 权限 ID 列表,创建或更新角色时使用 | -| childRoleIdList | Set | 子角色 ID 列表,创建或更新角色时使用 | - -## UserRoleAuthorizeReq - -| 字段 | 类型 | 说明 | -|---|---|---| -| userId | String | 目标用户 ID | -| roleIdList | List | 需要授权的角色 ID 列表 | -| roleCodeList | List | 需要授权的角色代码列表 | - -## RoleCode - -| 枚举 | 说明 | -|---|---| -| SYSTEM | 系统 | -| ADMIN | 管理员 | diff --git a/http/object/user.md b/http/object/user.md deleted file mode 100644 index 7b9c094..0000000 --- a/http/object/user.md +++ /dev/null @@ -1,73 +0,0 @@ -# 用户对象说明 - -## 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 | 角色代码列表 | -| permissionList | List | 权限代码列表 | -| attachmentList | List | 附件列表 | -| settingList | List | 设置列表 | - -## 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 | 当前密码,用于确认注销 | diff --git a/http/user/permission.http b/http/user/permission.http deleted file mode 100644 index 59d7b24..0000000 --- a/http/user/permission.http +++ /dev/null @@ -1,84 +0,0 @@ -### PermissionController 接口测试 -### 在 IDEA 中选择 dev 或 prod 环境后执行 - -@user_token = -@permissionId = -@permissionCode = TEST_PERMISSION -@permissionNameLangId = permission.test.name -@permissionDescription = 测试权限 -@moduleCode = CORE - -### 分页查询权限 -### 权限:需要 PERMISSION_READ 权限 -### 前置条件:需要先登录并回填 `user_token` -### 请求参数:Page,详见 ./http/object/permission.md -### 返回参数:PageResult,详见 ./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}} diff --git a/http/user/role.http b/http/user/role.http deleted file mode 100644 index e48bb71..0000000 --- a/http/user/role.http +++ /dev/null @@ -1,113 +0,0 @@ -### RoleController 接口测试 -### 在 IDEA 中选择 dev 或 prod 环境后执行 - -@permissionId = -@roleId = -@roleCode = TEST_ROLE -@roleNameLangId = role.test.name -@roleDescription = 测试角色 -@childRoleId = -@authorizedUserId = -@moduleCode = CORE - -### 分页查询角色 -### 权限:需要 ADMIN 角色 + ROLE_READ 权限 -### 前置条件:需要先登录并回填 `user_token` -### 请求参数:Page,详见 ./http/object/role.md -### 返回参数:PageResult,详见 ./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,详见 ./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,详见 ./http/object/permission.md -POST {{baseUrl}}/user/role/authorized/permission?userId={{authorizedUserId}} -Token: {{user_token}} diff --git a/http/user/user.http b/http/user/user.http deleted file mode 100644 index baeb74a..0000000 --- a/http/user/user.http +++ /dev/null @@ -1,186 +0,0 @@ -### 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,详见 ./http/object/user.md -### 返回参数:PageResult,详见 ./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}}" -}