15 — 权限分配同步（接收方视角）

已过时：用户维度 PERMISSION 旧口径。当前实现为角色维度，请改读 14-角色权限分配同步.md（页面标题：权限分配同步）。本文仅作历史对照，勿再联调。

门户在用户有效权限变更后，将映射后的第三方权限码集合以 HTTP 推送到你方「设置用户权限」接口。

方向：门户 → 你方（不是你调门户的 /api/sync/**）。
代码锚点：PermissionOutboundEventListener、PermissionOutboundService、PermissionPushDataAssembler、OutboundPayloadBuilder。

鉴权头、加密信封、管理端 Client 配置流程与 05-组织用户同步.md 相同；本文只补充 PERMISSION 报文与接收约定。

---

1. 触发时机

事件	说明
用户被分配 / 回收角色	该用户 × 已映射应用
角色权限码变更	持有该角色的用户
岗位任职变更导致有效角色变化	同角色变更链路
权限映射变更	受影响用户集（实现侧扇出）

管理端角色权限分配 API（PUT /api/system/roles/{roleId}/permissions）是门户内部操作，会间接触发出向；第三方不要调用该路径。

---

2. 管理端配置

项	说明
集成模块	PERM_MGMT（权限管理集成）
功能项	DEFAULT（回退 ALL）或 PERM_UPDATE（精确 UPDATE）
前置	门户已维护第三方权限目录与门户权限码映射（sys_app_permission / sys_permission_mapping）
接收 URL	你方「覆盖设置用户权限」完整 https://...

未配置启用的 PERMISSION endpoint 时，门户只写任务/日志，不会 HTTP 推送。

---

3. 业务对象

objectType	action	语义
PERMISSION	UPDATE	覆盖式下发该用户在指定应用下的第三方权限码全集

建议按 permSyncVersion（或 traceId + externalUserId + appCode）幂等：版本不增则忽略；版本更新则整表覆盖本地权限集合。

---

4. 明文业务报文（解密后）

{
  "syncVersion": "1.0",
  "traceId": "8f3c2a1b-...",
  "objectType": "PERMISSION",
  "action": "UPDATE",
  "timestamp": "2026-07-09T12:00:00Z",
  "data": {
    "portalUserId": "10086",
    "externalUserId": "hw_user_9527",
    "appCode": "highway",
    "permissions": [
      "HWY_DATA_QUERY",
      "HWY_TOLL_VIEW",
      "HWY_TOLL_AUDIT"
    ],
    "permSyncVersion": 20260701001
  }
}

字段	说明
portalUserId	门户用户主键字符串
externalUserId	优先用户 externalId，否则登录名
appCode	目标应用编码（与映射表一致）
permissions	映射后的第三方权限码列表（可为空数组表示清空）
permSyncVersion	下放版本号（毫秒时间戳量级），用于幂等与对账

外层信封字段（syncVersion / traceId / objectType / action / timestamp）与组织用户出向一致。

加密模式摘要见 05 §4；细节见 doc/14。

---

5. 你方接口建议

1. 校验 HTTP 鉴权（与组织用户出向同一套 endpoint 鉴权配置）。
2. 若启用加密：按 crypto_mode 解密得到上表 JSON。
3. 解析 data，按 externalUserId + appCode 覆盖本地权限。
4. 返回 HTTP 2xx 表示接收成功；非 2xx 时门户记失败，可管理端重试。
5. 保留 traceId / permSyncVersion 便于对账。

---

6. 与相关能力的边界

能力	方向	文档
组织/用户出向	门户 → 你	05-组织用户同步.md
权限分配出向	门户 → 你	本文
菜单同步	你 → 门户	14-菜单同步-HMAC.md
下放任务运维	门户管理端	/api/sync/permission-tasks（需登录，非第三方入站）

/api/sync/push/**、/api/system/** 不是第三方业务入站面。

---

7. 联调建议

1. 门户管理员：启用 Client 出向 → 配置 PERM_MGMT URL → 维护权限映射。
2. 你方：先明文 Mock 接收端，校验报文字段。
3. 在门户为测试用户分配/回收角色，确认收到覆盖式 permissions[]。
4. 向门户确认 sync_push_record（object_type=PERMISSION）与 sys_permission_sync_task 状态。

设计背景见 doc/03 §8、doc/48、doc/14。