diff --git a/缺失的后端接口.md b/缺失的后端接口.md index 70b70a4..17e94ed 100644 --- a/缺失的后端接口.md +++ b/缺失的后端接口.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 项)。