01 — 接入准备

面向第三方集成方：在调用开放 API / SSO 之前，完成 Client 注册与公共约定对齐。

---

1. 注册 OAuth2 / SSO Client

门户侧 Client 落库表 sys_sso_client，由门户管理员通过管理端维护：

项	说明
管理端入口	/api/sso/clients（需门户登录 + SSO 管理权限，非第三方自助）
创建后交付给你	client_id、client_secret（仅 CONFIDENTIAL 创建/重置时可见一次）、绑定的 system_code、允许的 scopes / redirect_uris 等

开放 API 硬性要求

要求	原因
clientType=CONFIDENTIAL 且具备 client_secret	事项 / 公告 / 知识库 HMAC 验签、任务 OAuth 换票、部分出向加密均依赖 secret
绑定 system_code（关联已注册应用 sys_system.system_code）	事项 / 公告 / 任务写入时 只认 Client 绑定值，请求体无法覆盖
Client 启用（enabled）	停用后 HMAC / Token 鉴权均失败

grant_type 说明

• 默认与 Discovery 支持：authorization_code、refresh_token。
• client_credentials 未开通，勿按机器账号直取 Token 设计联调。
• 任务中心开放接口须通过**用户授权码（或 refresh）**拿到带 api:read / api:write 的 access_token。

scope（与任务 / userinfo 相关）

scope	用途
profile	/oauth2/userinfo
permissions	introspect 扩展权限快照
api:read	/api/open/tasks 查询
api:write	/api/open/tasks 写操作（蕴含读）
openid	OIDC Client 换票时额外返回 JWT id_token（access_token 仍为 opaque）

事项 / 通知公告推送 不走 OAuth scope，只走 HMAC + Client 绑定。

---

2. system_code 归属规则

规则	说明
来源	仅 sys_sso_client.system_code
请求体	忽略 / 不可覆盖；开放事项、开放公告与开放任务均从鉴权上下文注入
未绑定	HMAC：HTTP 200 + code=403「Client 未绑定 system_code」；任务：业务 400
业务含义	事项 / 公告按 system_code + externalId 定位；任务按应用归属隔离（TaskAccessContext.forApp）

---

3. 统一响应 ApiResult

业务开放接口（/api/open/**）与门户多数 REST 一致：

{
  "code": 0,
  "message": "success",
  "data": { },
  "traceId": "a1b2c3d4e5f6"
}

字段	说明
code	0 成功；非 0 为业务/鉴权失败
message	提示文案
data	成功时的载荷；失败常为 null
traceId	链路追踪，排障时提供给门户运维

重要：鉴权失败（如 HMAC 缺头、验签失败、时间窗外）也常返回 HTTP 200，靠 body 的 code（如 401/403）判断。联调请以 code===0 为准，不要只看 HTTP 状态。

OAuth2 / CAS / SAML 协议端点本身不一定包 ApiResult（如 302、XML、Token JSON），见 04-SSO接入-IdP.md。

---

4. 公共错误与重试建议

场景	典型 code	建议
缺鉴权头 / 签名错误 / 时间戳无效	401	核对时钟、签名串、secret
Client 停用 / 无 secret / 未绑 system_code	403	联系门户管理员
参数校验失败	400	按字段表修正
资源不存在	404	核对 externalId / taskCode
事项 / 公告落库成功	0	才可认为推送成功；失败应重试
公告同键再次 publish	409	勿重复发布；需新内容请换 externalId

---

5. 联调检查清单

1. 管理端已创建 CONFIDENTIAL Client，并拿到 client_id / client_secret。
2. 已绑定正确 system_code，且 Client 启用。
3. 事项 / 公告推送：本机时间与门户偏差 < 5 分钟；能正确计算 HMAC。
4. 任务中心：Client scopes 含 api:write（或读接口仅需 api:read）；能走授权码换票。
5. SSO：redirect_uris / CAS service / SAML ACS 已登记且与线上一致。

下一步：

• 待办 + 公告选型与示例 → 08-待办与通知公告-集成手册.md
• 或直接：02 / 07 / 03 / 04 / 05 / 06。

---

6. 下载 Demo

用途	下载
HMAC 入站 Java	/downloads/hmac-java.zip
Bash HMAC	/downloads/bash-hmac-scripts.zip
任务 OAuth2 Java	/downloads/oauth2-tasks-java.zip
SSO OAuth2 客户端 Java	/downloads/sso-oauth2-client-java.zip

索引与说明：sdk/README.md。