You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
115 lines
4.9 KiB
115 lines
4.9 KiB
4 weeks ago
|
# 07 · 角色配置接口契约 + 前端对接文档
|
||
|
|
|
||
|
|
Type: grilling
|
||
|
|
Status: resolved
|
||
|
|
Blocked by: 02
|
||
|
|
|
||
|
|
## Question
|
||
|
|
|
||
|
|
角色保存/详情接口的入参出参如何从「单个 dataScope」变成「按模块的档位集合」，
|
||
|
|
并产出前端对接文档？
|
||
|
|
|
||
|
|
要定的点：
|
||
|
|
|
||
|
|
- 现状：`RoleDTO.dataScope` 是单个 Integer；保存校验在 `SysRoleServiceImpl`（范围校验、禁 CUSTOM）。
|
||
|
|
- 入参：改成 `moduleScopes: [{ moduleCode/moduleId, level }]`？还是 map？未传的模块如何处理（默认 SELF？保持不变？）。
|
||
|
|
- 出参：角色详情返回各模块档位；前端渲染配置表格（线索/商机/客户/项目 × 四档单选）所需字段。
|
||
|
|
- 可选模块列表接口：前端要渲染「有哪些模块可配」，是否需要一个「列模块」的接口（依赖 01 的模块注册）。
|
||
|
|
- 校验：每模块档位范围校验、模块 code 合法性校验。
|
||
|
|
- **产出前端对接文档**（本效力目的地之一）：接口路径/入出参/示例/字段含义。
|
||
|
|
|
||
|
|
依赖 02（存储结构定 DTO 形态）；模块列表接口牵涉 01。
|
||
|
|
|
||
|
|
## Answer
|
||
|
|
|
||
|
|
全部由前面的工单 + 全局接口规范推导，无新决策。
|
||
|
|
|
||
|
|
### 1. saveOrUpdate 入参变化
|
||
|
|
|
||
|
|
**现在**：`POST /api/roles/saveOrUpdate`，表单字段含 `@RequestParam Integer dataScope`（单个 1-4）。
|
||
|
|
|
||
|
|
**改成**：去掉 `dataScope` 参数，加 `moduleScopes` JSON 字符串表单字段：
|
||
|
|
|
||
|
|
```
|
||
|
|
POST /api/roles/saveOrUpdate
|
||
|
|
Content-Type: application/x-www-form-urlencoded
|
||
|
|
|
||
|
|
id=&roleName=&roleCode=&sort=&remark=&moduleScopes=[{"moduleCode":"customer","dataScope":2},{"moduleCode":"lead","dataScope":1}]
|
||
|
|
```
|
||
|
|
|
||
|
|
- 复杂字段 JSON.stringify 后作表单字段——全局规范 2.3(3) 定死，与 `assign-resources` 的 `resourceIds` 模式一致。
|
||
|
|
- 全量替换（先删后插，与 `assign-resources` 一致）：先删该角色的所有 `sys_role_data_scope` 行，再插入前端传的。
|
||
|
|
- 未传的模块 = 无行 = 默认 SELF（02 决策 3）。
|
||
|
|
- 校验：每行 `dataScope` 必须在 1-4（删了 CUSTOM，02 决策 4）；`moduleCode` 必须在 `sys_data_scope_module` 中存在且 enabled；同一请求内 `moduleCode` 不允许重复。
|
||
|
|
|
||
|
|
### 2. detail 出参变化
|
||
|
|
|
||
|
|
**现在**：`GET /api/roles/detail?roleId=`，返回 `RoleDTO` 含 `Integer dataScope`。
|
||
|
|
|
||
|
|
**改成**：`RoleDTO` 去掉 `dataScope` 字段，加 `List<ModuleScopeDTO> moduleScopes`：
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"code": 0, "success": true, "message": "success",
|
||
|
|
"data": {
|
||
|
|
"id": "1946xxx", "roleName": "销售", "roleCode": "ROLE_SALES",
|
||
|
|
"sort": 1, "builtin": false,
|
||
|
|
"moduleScopes": [
|
||
|
|
{"moduleCode": "customer", "moduleName": "客户", "dataScope": 2},
|
||
|
|
{"moduleCode": "lead", "moduleName": "线索", "dataScope": 1}
|
||
|
|
],
|
||
|
|
"resourceIds": ["1946xxx", "1947xxx"]
|
||
|
|
}
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
- `ModuleScopeDTO`：`moduleCode`（String）+ `moduleName`（String，从注册表 join 展示名）+ `dataScope`（Integer 1-4）。
|
||
|
|
- 未配模块不返回行（前端渲染时对缺失模块显示 SELF）。
|
||
|
|
- `fromEntity` 不再映射 `dataScope`；`getRoleDetail` 额外查 `sys_role_data_scope` 填充 `moduleScopes`。
|
||
|
|
|
||
|
|
### 3. page 出参变化
|
||
|
|
|
||
|
|
**现在**：`POST /api/roles/page`，返回 `PageResult<SysRole>`（直接返回实体，含 dataScope）。
|
||
|
|
|
||
|
|
**改成**：返回 `PageResult<RoleDTO>`，不含 `moduleScopes`（列表视图不需要每模块档位，只显示角色名/编码/排序/内置标记）。
|
||
|
|
- `RoleDTO.moduleScopes` 在 page 出参中为 null（不查 `sys_role_data_scope`）。
|
||
|
|
- Controller 应改为调 service 的 `pageRoles` 方法（现 controller 绕过 service 直接查）。
|
||
|
|
|
||
|
|
### 4. 新增接口：列出可配模块
|
||
|
|
|
||
|
|
前端渲染配置表格需要知道有哪些模块可配：
|
||
|
|
|
||
|
|
```
|
||
|
|
GET /api/data-scope/modules
|
||
|
|
Authorization: Bearer {token}
|
||
|
|
```
|
||
|
|
|
||
|
|
返回：
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"code": 0, "success": true, "message": "success",
|
||
|
|
"data": [
|
||
|
|
{"code": "lead", "name": "线索", "sort": 1, "builtin": true},
|
||
|
|
{"code": "opportunity", "name": "商机", "sort": 2, "builtin": true},
|
||
|
|
{"code": "customer", "name": "客户", "sort": 3, "builtin": true},
|
||
|
|
{"code": "project", "name": "项目", "sort": 4, "builtin": true}
|
||
|
|
]
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
- 只返回 `status=enabled` 的模块。
|
||
|
|
- 权限码：`crm:data-scope:modules`（或复用 `crm:role:list`——角色列表页才需要，简化权限分配）。
|
||
|
|
|
||
|
|
### 5. 前端对接文档要点
|
||
|
|
|
||
|
|
以下为前端开发需知道的契约变化：
|
||
|
|
|
||
|
|
| 接口 | 变化 | 前端注意 |
|
||
|
|
|------|------|----------|
|
||
|
|
| saveOrUpdate | `dataScope` 参数去掉，改 `moduleScopes` JSON 字符串 | 传 `[{"moduleCode":"...","dataScope":1}]` 格式；不传的模块走 SELF 默认 |
|
||
|
|
| detail | `dataScope` 字段去掉，改 `moduleScopes` 数组 | 渲染配置表格：行=模块，列=四档单选；缺失模块显示 SELF |
|
||
|
|
| page | 去掉 `dataScope` | 列表只显示角色基本信息，不显示档位 |
|
||
|
|
| 新增 modules | `GET /api/data-scope/modules` | 渲染配置表格前先拉模块列表 |
|
||
|
|
|
||
|
|
四档档位含义不变：1=本人 / 2=本部门 / 3=本部门及子部门 / 4=全部。
|