16 — 角色同步（HMAC）

第三方对本应用（Client 绑定 system_code）下的 BUSINESS 角色做 upsert / delete。

方向：你 → 门户（入向）。
代码锚点：OpenRoleController、OpenRoleHmacFilter、OpenRoleInboundService、RoleManageService.upsertFromOpenApi。

基路径：/api/open/roles
方法：全部为 POST（含删除语义的 /delete）。

管理端角色 CRUD（/api/system/roles）需门户登录 + 权限码，不是第三方入站面。
角色权限分配出向（门户 → 你）见 14-角色权限分配同步.md。

1. 鉴权头

Header	必填	说明
`X-Client-Id`	是	SSO `client_id`
`X-Timestamp`	是	Unix 秒（epoch seconds）
`X-Signature`	是	HMAC-SHA256 的 Hex（大小写不敏感比对）
`X-Idempotency-Key`	否	可选；记入 `sync_role_push_log`，管理端「消息日志 · 角色」可查；业务幂等键为 `system_code + roleCode`

时间窗：±300 秒。超出返回 code=401。

Client 须：存在、启用、绑定 system_code（且不得为 PLATFORM）、CONFIDENTIAL 且可解析 client_secret。否则 401/403。

system_code 始终取自 Client 绑定，请求体无法覆盖。

2. 签名算法

与 14-菜单同步-HMAC.md / 02-事项推送-HMAC.md 一致：

text

{clientId}\n{timestamp}\n{rawBody}

HmacSHA256，密钥为 client_secret UTF-8 字节，输出 Hex → X-Signature。

3. 接口清单

方法	路径	语义
POST	`/api/open/roles/upsert`	按绑定 `system_code` + `roleCode` 创建或更新 BUSINESS 角色
POST	`/api/open/roles/delete`	按 `roleCode` 删除；级联清理绑定对齐管理端

成功响应 data：

字段	说明
`roleId`	门户 `sys_role.id`（删除后可空）
`roleCode`	角色编码
`systemCode`	Client 绑定系统编码
`roleType`	恒为 `BUSINESS`

仅落库成功才 code=0。

4. 隔离规则

规则	行为
仅 BUSINESS	目标为 SYSTEM / 内置 → `code=409`
PLATFORM Client	Filter 直接 `code=403`
来源	不强制 `sourceType=API`：同系统管理端已建的 BUSINESS 可被开放接口改/删
新建标记	新建角色 `sourceType=SYNC`；更新已有 LOCAL 不强制改写 sourceType

5. UPSERT — `POST /api/open/roles/upsert`

字段	必填	说明
`roleCode`	是	角色编码
`roleName`	是	角色名称
`parentRoleCode`	否	同系统父角色；须存在
`status`	否	0 正常 / 1 停用；默认新建 0；更新时省略则不改
`sortOrder`	否	排序
`remark`	否	备注
`dataScope`	否	ALL / DEPT / DEPT_AND_CHILD / SELF / CUSTOM；默认 SELF
`deptCodes`	否	`dataScope=CUSTOM` 时部门编码列表

示例

bash

BODY='{"roleCode":"OPS_ADMIN","roleName":"运维管理员","dataScope":"SELF","sortOrder":10}'
TS=$(date +%s)
SIG=$(…HMAC Hex…)
curl -sS -X POST "https://portal.example.com/api/open/roles/upsert" \
  -H "Content-Type: application/json" \
  -H "X-Client-Id: demo-client" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: $SIG" \
  -d "$BODY"

6. DELETE — `POST /api/open/roles/delete`

json

{ "roleCode": "OPS_ADMIN" }

错误	说明
400	存在子角色无法删、参数非法等
404	角色不存在
409	SYSTEM / 非 BUSINESS，禁止删除

7. 边界

能力	方向	文档
角色同步（本文）	你 → 门户	HMAC `/api/open/roles`
菜单同步	你 → 门户	14-菜单同步-HMAC.md
权限分配出向	门户 → 你	14-角色权限分配同步.md
管理端角色	门户会话	`/api/system/roles`（非开放面）

非目标：角色权限码分配、用户绑角色、角色组、字段权限、全量批次、objectType=ROLE 出向。

16 — 角色同步（HMAC） ​

1. 鉴权头 ​

2. 签名算法 ​

3. 接口清单 ​

4. 隔离规则 ​

5. UPSERT — POST /api/open/roles/upsert ​

示例 ​

6. DELETE — POST /api/open/roles/delete ​

7. 边界 ​