11 KiB
开放平台设计:给外部系统的接口、钥匙与事件推送
对应缺口: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 需要的是三件事,缺一件都会退化成"共享一个管理员账号":
- 一把可回收、可归责的钥匙(应用凭证 + 短期访问令牌,停用即失效,每条调用记到应用);
- 一份对方照着就能写的接口(稳定契约 + 界面上能直接看的接口清单,不跟着内部视图漂);
- 一条反过来的路(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 条断言。