docs: 更新用户/角色/机构删除接口为批量删除契约
halo
parent
f3461fc7e3
commit
2d6d43761f
56
缺失的后端接口.md
56
缺失的后端接口.md
|
|
@ -8,6 +8,7 @@
|
|||
> - 日期时间字段格式统一为 `yyyy-MM-dd HH:mm:ss`。
|
||||
> - `access_token` 建议有效期 30 分钟,`refresh_token` 建议有效期 7 天,通过 `Set-Cookie`(`HttpOnly`)下发,前端请求需 `withCredentials: true`。
|
||||
> - 所有按 `{id}` 修改/删除/查看的接口,若目标资源不存在,统一返回 `40404`(资源不存在);`access_token` 失效或缺失统一返回 HTTP 401(mock-server 中对应业务码 `40100`)。
|
||||
> - 所有 `DELETE .../batch` 批量删除接口统一约定:请求 Body 为 `{ ids: string[] }`(至少 1 项);响应 `data` 为 `{ successIds: string[], failed: Array<{ id, name, reason }> }`;`code` 始终为 200,部分/全部业务失败通过 `data.failed` 体现,不使用错误 code;`ids` 为空数组时返回业务错误码 `40024`(msg 按资源区分)。
|
||||
|
||||
## 8.1 通用鉴权接口
|
||||
|
||||
|
|
@ -211,11 +212,22 @@
|
|||
|
||||
响应 `data`:`null`;校验规则同新增(手机号格式/唯一性、机构有效性、角色非空)。
|
||||
|
||||
### 15. 删除用户
|
||||
### 15. 批量删除用户
|
||||
|
||||
`DELETE /system/user/{id}`
|
||||
`DELETE /system/user/batch`
|
||||
|
||||
响应 `data`:`null`
|
||||
请求参数(Body):`{ ids: string[] }`(至少 1 项)
|
||||
|
||||
响应 `data`:
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| successIds | string[] | 删除成功的用户 ID 列表 |
|
||||
| failed | array | 删除失败项,元素结构 `{ id, name, reason }` |
|
||||
|
||||
`code` 始终为 200(接口调用本身成功);部分/全部业务失败通过 `data.failed` 体现,不使用错误 code。原单个 `DELETE /system/user/{id}` 接口已废弃,以 `ids: [singleId]` 覆盖单删场景。
|
||||
|
||||
可能的失败原因(`failed[].reason`):用户不存在。`ids` 为空数组时返回业务错误码 40024。
|
||||
|
||||
### 16. 锁定 / 解锁用户
|
||||
|
||||
|
|
@ -257,9 +269,9 @@
|
|||
|
||||
响应 `data`:`{ list: RoleItem[], total: number }`,`RoleItem` 字段:`{ id, name, orgId, orgName, status, builtin, createdAt }`
|
||||
|
||||
### 20. 新增 / 修改 / 删除 / 查看角色
|
||||
### 20. 新增 / 修改 / 查看角色 / 批量删除角色
|
||||
|
||||
`POST /system/role`、`PUT /system/role/{id}`、`DELETE /system/role/{id}`、`GET /system/role/{id}`
|
||||
`POST /system/role`、`PUT /system/role/{id}`、`GET /system/role/{id}`、`DELETE /system/role/batch`
|
||||
|
||||
新增/修改请求参数(Body):
|
||||
|
||||
|
|
@ -273,15 +285,22 @@
|
|||
|
||||
查看接口 `GET /system/role/{id}` 响应 `data` 在上述字段基础上附加 `id、builtin、status、createdAt`。
|
||||
|
||||
删除接口无请求参数,响应 `data`:`null`。
|
||||
批量删除角色 `DELETE /system/role/batch`,请求参数(Body):`{ ids: string[] }`(至少 1 项)。响应 `data`:
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| successIds | string[] | 删除成功的角色 ID 列表 |
|
||||
| failed | array | 删除失败项,元素结构 `{ id, name, reason }` |
|
||||
|
||||
`code` 始终为 200,部分/全部业务失败通过 `data.failed` 体现。原单个 `DELETE /system/role/{id}` 接口已废弃,以 `ids: [singleId]` 覆盖单删场景。`ids` 为空数组时返回业务错误码 40024。
|
||||
|
||||
业务规则:
|
||||
|
||||
- 内置角色(`builtin=true`,如【内置】系统管理员)不可删除、不可改名(如 `PUT` 请求体 `name` 与原值不同则拒绝)。
|
||||
- 同一 `orgId` 下 `name` 不可重复。
|
||||
- 已被任意用户 `roleIds` 引用的角色禁止删除,需先解除关联。
|
||||
- 已被任意用户 `roleIds` 引用的角色禁止删除(体现为该条在 `failed` 中,`reason` 说明已关联用户数),需先解除关联。
|
||||
|
||||
可能的业务错误码:角色名称为空(40016)、未选择页面权限(40017)、数据权限范围无效(40018)、同机构下角色名重复(40019)、内置角色不可改名(40020)、内置角色不可删除(40021)、角色已关联用户不可删除(40022)。
|
||||
可能的业务错误码:角色名称为空(40016)、未选择页面权限(40017)、数据权限范围无效(40018)、同机构下角色名重复(40019)、内置角色不可改名(40020)、内置角色不可删除(40021,现体现为批量删除响应中的 failed 项)、角色已关联用户不可删除(40022,现体现为批量删除响应中的 failed 项)。
|
||||
|
||||
### 21. 获取权限字典树(菜单+按钮)
|
||||
|
||||
|
|
@ -325,9 +344,9 @@
|
|||
| createdAt | string | 创建时间 |
|
||||
| children | array | 下级机构(结构同上,递归) |
|
||||
|
||||
### 23. 新增 / 修改 / 删除机构
|
||||
### 23. 新增 / 修改机构 / 批量删除机构
|
||||
|
||||
`POST /system/org`、`PUT /system/org/{id}`、`DELETE /system/org/{id}`
|
||||
`POST /system/org`、`PUT /system/org/{id}`、`DELETE /system/org/batch`
|
||||
|
||||
新增/修改请求参数(Body):
|
||||
|
||||
|
|
@ -337,14 +356,21 @@
|
|||
| parentId | string | 一级机构(内置根机构)本身除外均为是 | 上级机构 ID,不可选择自身或自身下级 |
|
||||
| remark | string | 否 | 备注 |
|
||||
|
||||
删除接口无请求参数,响应 `data`:`null`。
|
||||
批量删除机构 `DELETE /system/org/batch`,请求参数(Body):`{ ids: string[] }`(至少 1 项)。后端需按机构 `level` 降序处理(先判定/删除层级更深的下级机构,再处理上级机构),以支持"勾选整棵已选子树一次性批量删除"。响应 `data`:
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| successIds | string[] | 删除成功的机构 ID 列表 |
|
||||
| failed | array | 删除失败项,元素结构 `{ id, name, reason }` |
|
||||
|
||||
`code` 始终为 200,部分/全部业务失败通过 `data.failed` 体现。原单个 `DELETE /system/org/{id}` 接口已废弃,以 `ids: [singleId]` 覆盖单删场景。`ids` 为空数组时返回业务错误码 40024。
|
||||
|
||||
业务规则:
|
||||
|
||||
- 一级机构(内置根机构,`builtin=true`)不可删除。
|
||||
- 存在下级机构时禁止删除。
|
||||
- 存在下级机构时禁止删除(若该下级机构在同一批次中已先被删除,则不再计入)。
|
||||
- 已关联用户(`user.orgId` 命中)时禁止删除。
|
||||
- 同一 `parentId` 下 `name` 不可重复。
|
||||
- **已知限制**:业务需求文档中"存在已关联核心企业时禁止删除机构"的规则,因"核心企业"功能属于后续阶段(基础配置模块),本阶段尚无该数据源,暂未实现该项校验,待核心企业模块上线后需补充。
|
||||
- 同一 `parentId` 下 `name` 不可重复(新增/修改校验,与删除无关)。
|
||||
- **已知限制**:业务需求文档中"存在已关联核心企业时禁止删除机构"的规则,阶段2引入核心企业(渠道)模块后仍**暂未实现**该项校验(设计阶段已与产品侧确认本阶段不做,待后续阶段评估是否补充)。
|
||||
|
||||
可能的业务错误码:机构名称为空(40004)、上级机构无效(40004)、同上级下机构名重复(40005)、上级机构选择了自身或下级(40006)、一级机构不可删除(40007)、存在下级机构不可删除(40008)、已关联用户不可删除(40009)。
|
||||
可能的业务错误码:机构名称为空(40004)、上级机构无效(40004)、同上级下机构名重复(40005)、上级机构选择了自身或下级(40006)、一级机构不可删除(40007,现体现为批量删除响应中的 failed 项)、存在下级机构不可删除(40008,现体现为批量删除响应中的 failed 项)、已关联用户不可删除(40009,现体现为批量删除响应中的 failed 项)。
|
||||
|
|
|
|||
Loading…
Reference in New Issue