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