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

168 lines
11 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

# 开放平台设计:给外部系统的接口、钥匙与事件推送
对应缺口:`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 条断言。