unis-oa/docs/platform-open-api-design.md

11 KiB
Raw Blame History

开放平台设计:给外部系统的接口、钥匙与事件推送

对应缺口:docs/oa-capability-review.md §3「外部系统要调 OA,只能借一个真实员工账号」。 落脚:backend/app/api/openapi.py(管理面 + 数据面)、backend/app/service/openauth.py(钥匙与限流)、 backend/app/service/events.py(事件推送)、backend/app/service/signing.py(回调签名)、 frontend/src/views/oa/design/OpenPlatformView.vue(/design/open-platform,权限 design:openapi)、 验收 backend/tests/oa_platform.py。

0. 一句话结论

外部系统对接 OA 需要的是三件事,缺一件都会退化成"共享一个管理员账号":

  1. 一把可回收、可归责的钥匙(应用凭证 + 短期访问令牌,停用即失效,每条调用记到应用);
  2. 一份对方照着就能写的接口(稳定契约 + 界面上能直接看的接口清单,不跟着内部视图漂);
  3. 一条反过来的路(OA 有动静时主动推给外部,而不是让对方每秒轮询一次待办)。

这三件都做了,全程不写代码:界面上建应用、勾授权范围、填回调地址就完事。

1. 为什么不能沿用登录会话

现状是 Authorization: Bearer <登录令牌>,那是人的会话:会跟着浏览器退出、密码一改就断、 权限是"这个人在界面上能看到的那些菜单"。把它给外部系统会出四个问题:

问题 具体表现 这一版怎么解
密码写进对方配置文件 员工离职改密码,ERP 的定时发起单据当场停 应用密钥 32 字节随机串,与人的口令毫无关系
权限说不清 那个账号在界面上有什么权限,取决于上次谁点了什么 五个作用域(§3),接口逐个点名要哪个
出事找不到人 操作日志里是"张三",其实是 ERP 的批处理 每条调用单独留痕到 oa_open_call,记应用不记人
没法立刻停 只能改密码,改完还得通知所有在用它的系统 应用停用 = 令牌当场全部失效(每次调用都查库)

关键取舍:每次调用都查一次库。 自签 JWT 能省这一趟,代价是令牌发出去就收不回来, 而"对方被拖库了,立刻让那把钥匙失效"是安全事件里的第一诉求。何况本系统的接口本来 就要查库拿权限,省这一次查询没有实际收益。

2. 鉴权链路

外部系统                                    OA
   │  POST /api/v1/open/token  {app_key, app_secret}
   │───────────────────────────────────────────▶  比对 secret_hash(SHA-256 + 恒时比较)
   │◀───────────────────────────────────────────  {accessToken, expiresIn, scopes}
   │
   │  GET /api/v1/open/works   Authorization: Bearer <accessToken>
   │───────────────────────────────────────────▶  查 oa_open_token → 查应用 → 应用没停 → 限流 → 放行

三条底线写在 service/openauth.py:

  • 密钥只存哈希(security.hash_token,与登录口令、数据源密钥同一口径)。库里读不出可用密钥, 界面上只显示尾号 a1b2****f9;明文只在创建和"重置密钥"那一次返回。
  • 令牌不透明、带过期、可吊销。默认 2 小时(token_ttl_seconds),一个应用最多同时留 20 把 (MAX_LIVE_TOKENS),换新的不会无限堆积。停用应用连带作废它名下所有令牌。
  • 限流查库不查内存。按 oa_open_call 里最近一分钟的调用数判,多副本部署时不会出现 "四个进程各自限 300,实际 1200"。超限返回 429(不是 400——对方脚本看得懂 429 才懂得退避)。

换令牌时"应用不存在"和"密钥不对"回同一句话,免得 app_key 变成可枚举的信息。

3. 作用域

service/openauth.py::SCOPES 一处定义,接口文档、界面勾选框、接口里的 ctx.need() 全从这读。 新建默认只给三个读,写两类要显式勾:

作用域 含义 覆盖接口
process:read 看得到哪些流程 GET /open/processes
work:read 查单据 GET /open/works、GET /open/works/{job}
work:write 发起与终止单据 POST /open/works、POST /open/works/{job}/terminate
task:read 查某个人的待办 GET /open/tasks
task:write 代某个待办处理人办理 POST /open/tasks/{id}/execute

身份必须显式给。 写类接口都带 identity(工号 / 用户名 / 邮箱,org.person_by_identity 那一套), 系统里查不到这个人、或这个人已停用,直接拒绝。不做"没给身份就以管理员身份跑"的兜底—— 那等于一把泄露的密钥拿到最高权限。同理,发起单据仍走 service/starters.py 的"谁能发起"判定: 开放接口不是后门,应用在 start_identity_list 之外照样发不起来。

4. 数据面接口(外部系统调)

/api/v1/open/*,Bearer 令牌鉴权,不吃本系统菜单权限码。清单同时由 GET /design/open/catalog 返回,界面上的"接口文档"页签直接渲染它——文档与代码同源,不会过期。

方法 路径 作用域 说明
POST /open/token — 换访问令牌
GET /open/processes process:read 指定身份发得起来的流程(含表单字段定义,对方才知道要填什么)
POST /open/works work:write 发起单据(identity + process + data),返回 job 与落定的环节
GET /open/works work:read 按流程 / 状态 / 单号 / 发起人 / 时间查列表
GET /open/works/{job} work:read 单据详情 + 流转记录
POST /open/works/{job}/terminate work:write 终止单据
GET /open/tasks task:read 某个人的待办
POST /open/tasks/{task_id}/execute task:write 同意 / 退回(只在该 task 确实属于这个 identity 时放行)
GET /open/events — 事件清单与推送格式(给订阅方自查)

响应字段是自己定、自己稳的一份,不复用内部列表的视图函数。内部接口改字段是常事, 外部对接一改就要拉对方一起发版。宁可字段冗余,也不跟着内部结构漂。

统一信封沿用系统既有的一套(code / message / data),错误照样 401 / 403 / 404 / 429 / 422, 对方一次实现就与内部接口对齐。

5. 事件推送(OA 主动通知外部)

七个事件(service/events.py::CATALOG):work.submitted、task.arrived、task.completed、 work.completed、work.terminated、work.canceled、work.overdue。 订阅方在界面上填:回调地址、密钥、勾事件、限定哪些流程、要不要带表单数据。

默认不带表单数据。 事件里塞整份表单等于把业务数据复制一份给每一个订阅方, 勾上 send_data 才带。默认信封只有单据标识 + 标题 + 单号 + 当前环节 + 处理人 + 打开链接。

签名与投递:

X-Unisoa-Event:     work.completed
X-Unisoa-Delivery:  本次投递 id(重投不变,对方拿去去重)
X-Unisoa-Timestamp: 秒级时间戳
X-Unisoa-Signature: t=<ts>,v1=sha256=<HMAC-SHA256(secret, "ts.原始请求体")>

对方必须同时校验签名与时间窗(建议 ±300 秒),否则一条旧报文可以无限重放。 signing.verify() 是本系统自己实现的一份校验,拿来写对接测试正好。

投递底线与写回发件箱一模一样(docs/outbound-integration-design.md §5):与业务动作 同一事务入队 oa_open_event,后台线程按 60s / 5min / 15min / 1h / 4h 退避重投,用满进死信, 停在 sending 超过 300 秒当结果未知、不盲发第二遍。入队这一步绝不往业务代码里抛异常—— 订阅方挂了不该让审批人办不成单。

和「写回模板」的分工(会被问,写在明处)

写回模板 oa_integration 事件订阅 oa_open_webhook
发的是什么 业务凭证(对方定的报文格式) 事件通知(本系统定的信封)
发错的代价 上游多一张凭证,要走冲销 少一条通知,重推即可
字段映射 逐格映射 + 幂等键 + 结果未知人工确认 没有映射,信封固定
对账口径 必须逐条对平 允许重复,靠 X-Unisoa-Delivery 去重

两张表因此分开,不合并成"一个通用的外发表"。

6. 留痕与清理

main.py::_open_call_log 中间件给每一次 /api/v1/open/* 调用记一行 oa_open_call:应用、路径、 HTTP 状态、业务码、令牌前 8 位、IP、耗时。放在中间件而不是各接口里写一遍,因为失败的 那一次最需要留痕,而接口函数抛错时函数体里的收尾代码根本不会执行。

留痕同时是限流的数据源(§2)和扯皮时的证据。保留天数在系统设置里(open_call_keep_days,默认 90 天), 调度线程每天清一次。

7. 界面

/design/open-platform(OpenPlatformView.vue)五个页签:应用(建应用时明文密钥只显示一次,立刻复制走)、 事件订阅、接口文档(catalog 渲染,含签名说明,不给对方一份会过期的 Word)、事件留痕(按状态筛,死信 就地重推)、调用留痕(按应用筛,看得到 429)。 开关在系统设置:open_events_enabled 关掉只停推送,不影响取数与写回。

8. 明确不做

  • 不做 OAuth2 授权码流程:那是"第三方应用代表用户登录"的场景,这里是服务器对服务器。
  • 不做 API 计费 / 配额 / 版本协商:企业内网对接用不上,做了只会让对接文档更厚。
  • 不把内部接口整层暴露:只有清单里这九个。内部视图一改就要对方跟着发版,所以宁缺。
  • 不做 IP 白名单:内网环境的边界该由网关 / 防火墙划,应用层再划一道只会两边不一致; 真要限源,把 rate_limit_qpm 配上并让网关挡。
  • 不做沙箱环境:样例通道(docs/form-data-integration-design.md §5.4)在取数方向已经解决了 "上游还没有"的问题,反向同理——界面上的「测试」按钮真发一条,不需要第二套环境。

9. 验收

backend/tests/oa_platform.py 在唯一的开发库 unis_oa 上跑(用 e2e_<时间戳>_ 前缀建自己的 夹具,跑完删自己那几行,不建库不删库):换令牌 / 错密钥 / 停用即失效 / 作用域越权 / 限流 429 / 身份不存在 / 非待办处理人办理被拒 / 事件入队与签名 / 死信与人工重推 / 留痕条数,共 97 条断言。