4.9 KiB

Raw Blame History

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：

{
  "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}

{
  "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=全部。

4.9 KiB Raw Blame History