05 — 接收出向同步（接收方视角）

门户在组织 / 用户变更后，按管理端配置 HTTP 推送到你方系统。
本文说明第三方作为 HTTP 接收端须实现什么；管理端 CRUD、Rabbit、重试调度等见权威文档 doc/14-出向同步推送.md。

方向：门户 → 你方（不是你调门户的 /api/sync/**）。

---

1. 你需要提供什么

项	说明
接收 URL	完整 https://... 地址；由门户管理员按对象类型 / 动作配置到 endpoint
鉴权方式	门户调用你时携带：NONE / API_KEY / BASIC / BEARER_TOKEN（按 endpoint 配置）
解密能力	若启用报文加密，按约定模式解密后再解析业务 JSON
幂等 / 对账	建议按 traceId + objectType + action + 业务主键做幂等

门户侧先有 SSO Client（推荐 target_code = client_id），再开启出向同步并填写你的 URL——该流程由门户管理员完成（doc/14 §8 / §9），第三方一般只交付 URL、鉴权约定与公钥（如需）。

---

2. 业务对象与动作

objectType	含义	典型 action
DEPT	部门 / 组织	CREATE / UPDATE / DELETE
USER	用户	CREATE / UPDATE / DELETE（删除报文常仅含 username）；启停亦可能走 UPDATE

配置侧可用 ALL（管理端「默认」）让增删改共用一个 URL；报文内 action 仍是真实业务操作，与是否配置 ALL 无关。

---

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

{
  "syncVersion": "1.0",
  "traceId": "abc-123",
  "objectType": "DEPT",
  "action": "CREATE",
  "timestamp": "2026-07-09T12:00:00Z",
  "data": {
    "deptCode": "RD001",
    "deptName": "研发部",
    "parentCode": "ROOT",
    "externalId": "ext_rd001"
  }
}

字段	说明
syncVersion	报文版本
traceId	链路 ID，排障时回传门户
objectType / action	对象与操作
timestamp	事件时间（ISO-8601）
data	业务载荷（部门含 deptCode 等；用户删除可能仅 username）

你方接口建议：校验鉴权 →（如需）解密 → 解析上表 → 返回 HTTP 2xx 表示接收成功。非 2xx 时门户记失败并可重试（见 doc/14）。

---

4. 加密模式（摘要）

门户按 target 配置 crypto_mode（详情与密钥交换见 doc/14 §8.3）：

模式	接收方要做的事
ENVELOPE_SM2	用己方 SM2 私钥解国密信封，并按需验门户签名
CLIENT_CREDENTIAL_AES	用 SHA-256(client_id + "\0" + client_secret) 派生 AES-256-GCM 密钥解密（仅 CONFIDENTIAL Client）
SM4_SHARED	用预共享 SM4 密钥解密

CLIENT_CREDENTIAL_AES 外层示意：

{
  "cryptoMode": "CLIENT_CREDENTIAL_AES",
  "symmetricAlg": "AES-256-GCM",
  "iv": "Base64(...)",
  "encryptedPayload": "Base64(...)",
  "traceId": "..."
}

reset-secret 后双方须同步更新 secret，否则解密失败。

注意：client_secret 不会自动变成你方 HTTP 的 Bearer；HTTP 鉴权与报文加密是独立配置。

---

5. 与入站开放 API 的边界

能力	方向	文档
事项推送 HMAC	你 → 门户	02-事项推送-HMAC.md
任务中心 OAuth2	你 → 门户	03-任务中心-OAuth2.md
SSO 登录	用户经门户 → 你	04-SSO接入-IdP.md
组织用户出向	门户 → 你	本文 + doc/14

/api/sync/push/** 为门户管理端查配置与推送记录，第三方集成方无需也不应依赖其作为业务入站接口。

---

6. 联调建议

1. 与门户约定：URL、HTTP 鉴权类型、加密模式、样例报文。
2. 先用明文 / 测试环境打通鉴权与幂等。
3. 触发一次部门或用户变更，向门户确认 sync_push_record 是否 SUCCESS。
4. 失败时保留 traceId 与响应体，便于门户侧按记录重试。

完整字段、Rabbit / 直推、管理端 API 与运维排查：以 doc/14-出向同步推送.md 为准。