65 KiB
表单字段从外部系统取数:设计方案
需求与结论对照、总架构与总路线图见 integration-master-plan.md。
回答一个问题:表单里有些字段的值不在本系统里,得去 ERP / HR / MES / 财务 / 主数据平台拿,该怎么接。
文档定位:设计 + 落地清单,不是已实现功能的说明书。每条都标了落脚文件、表名与开关名,照着 P0 到 P3 一期一期做即可;§11 有 6 个需要你拍板的问题。
0. 一页看完
| 问题 | 结论 |
|---|---|
| 最该先问的 | 不是「怎么调接口」,而是「审批单要的是快照还是引用」——单据是凭证,上游改了成本中心的名字,去年那张单的金额含义不能跟着变 |
| 总原则 | 一律走后端代理,前端永不直连外部系统;外部回来的值走已有的「后端重算」那道关口(engine.apply_task_values),前端塞不进假值 |
| 不新造一套 | 复用三个已经在跑的骨架:数据字典(选项与带出)、Hub 同步(定时 + 增量 + run 记录)、invoke 环节(标准库 HTTP + 结果写回 work.data) |
| 统一入口 | 新增一张 oa_data_source(外部数据源注册表)+ 一个 service/fetch.py(执行器)。密钥只进不出、超时补试、缓存、脱敏、审计、限流全在这层做完,表单字段只管点名要哪个源 |
| 字段侧改动 | 只加一个可选属性 fetch(数据源编码 + 入参映射 + 取哪个键),设计器新增一块「外部取数」面板 |
| 五种取数形态 | ① 字典直落 ② 镜像表 + 定时同步 ③ 远程搜索选择 ④ 字段级即时带出 ⑤ 流转中回填/校验;按数据量与时效要求选,不要一律实时调 |
| 最硬的一条边界 | 外部系统只能提供值,不能决定流转——条件分支与审批人仍只读 work.data 里已落库的值;取数失败的兜底策略在设计期就必须定死 |
| 期次 | P0 字典/镜像(约 1 周,多数场景到这就够)→ P1 数据源注册表 + 字段级带出(约 1.5 周)→ P2 远程搜索 + 缓存与降级(约 1 周)→ P3 环节回填与批量校验(约 1 周) |
1. 先分类:这五种「取数」不是同一件事
90% 的争论来自把五类需求混成一句「要从别的系统取数」。先对号入座,再谈实现。
| 形态 | 典型场景 | 数据特征 | 什么时候取 | 走哪节 |
|---|---|---|---|---|
| ① 直落字典 | 费用类别、币种、报销标准、成本中心(小于 200 条,季度才变) | 小、稳、要人工兜底 | 提前 | §2 |
| ② 镜像表 | 客户、供应商、物料、合同、预算科目(几千到几十万,日/时级更新) | 中大、有变更流水 | 定时同步到本地 | §3 |
| ③ 远程搜索 | 物料挑一个、客户挑一个(列表大到人找不过来) | 大、只要选中那几条 | 输入时按需 | §4 |
| ④ 字段级带出 | 选成本中心带出预算余额;填工号带出职级;选合同号带出合同额 | 一对一精确查询、只读 | 上游字段变化时 + 提交时 | §5 |
| ⑤ 流转中回填 | 审批通过后写回 ERP 生成凭证、财务节点回写实际付款额、发起时冻结预算 | 要写、要在流程中间发生 | 环节到达时 | §6 |
判别口诀:
- 上游一年改不了几次、条数一屏放得下 → ①,别写代码,字典里维护或由同步任务写进字典;
- 条数上千、但审批时只用到其中一小部分 → ② 镜像 + ③ 搜索,本系统查自己的库;
- 值是「查出来的一个数」而不是「选出来的一个项」 → ④;
- 取完还要回写、或者必须卡在某个审批节点上做 → ⑤。
一句话原则:能在本地查的绝不实时调外部。实时调用把审批页的可用性和外部系统的 SLA 绑死了——ERP 半夜维护,第二天所有人的发起页都白屏,这是最难看的一类故障。
2. 形态①:直接进数据字典(零开发,先把它用足)
平台已经有了:oa_dict_type / oa_dict_item(models.py),
字典项的 extra 存附加值,配合字段的 autoFill 就能做「选了物料带出单价」,
而且带出值以字典为准——dicts.apply_auto_fill(dicts.py:366)在
engine.py:391 那一步被后端重算一遍,前端改成什么都被盖回去。
所以要外部数据,最省事的一条路是:把外部的主数据落到字典里。
- 人工维护:数据量小、变化慢的(报销标准、币种、费用类别),运营自己录;
- 半自动:写个脚本调外部接口,再调
POST /process/dicts/{code}/items灌进来 (接口已有,见 api/dicts.py); - 全自动:走 §3 的同步框架,只是落地目标是字典而不是业务表。
这条路的好处是所有下游能力白送:级联(cascadeFrom,省市区分层那种)、
条件联动(visibleWhen / requiredWhen)、只读态把值翻成中文名(option_labels)、
导出、设计器试算(POST /process/dicts/options)全部不用改一行。
extra 里塞几个业务字段(单价、负责人、税率),autoFill 声明映射,就是一台完整的带出机器。
2.1 今天就能配(零代码,三步)
不必等本方案落地——「选一个、顺手带出几个数」这类需求现在就能配完,入口与界面文案已和设计器现状核对:
表单设计 → 数据字典(路由/design/dicts,权限design:form)建字典类型并逐项录入。 每条字典项的**「附加值(JSON)」**就是带出的数据来源,例如物料项填{"price": 3.5, "tax": "13%", "owner": "张三"};表单设计 → 选中那个下拉字段 → 「字典带出」(components/oa/design/LinkagePanel.vue), 逐行挑「取哪一列」与「写进哪个字段」,例如附加值 · price→ 单价那格。取哪一列的写法与 「显示 / 存值」那两列同一套:留空取名称、value取键值、extra.单价走点路径; 老表单里那句裸price仍旧按附加值读,一个字节都不用改(口径见optionMap.pickFillValue↔dicts.pick_fill_value);- 被带出的那格勾上**「只读」**,免得人手改。提交时
dicts.apply_auto_fill会按字典重算, 前端塞什么都被盖回去。
外部主数据想走这条路,就让同步脚本(或运营自己)把它灌成字典项——
POST /process/dicts/{code}/items 是现成接口,级联、翻名、试算、导出全部复用。
什么时候不够用:条数超过约 2000(POST /process/dicts/values 会把整份选项灌给前端)、
需要按关键字搜、需要每几分钟新鲜一次、附加值多到 extra 说不清。撞到这几条再看 §3。
3. 形态②:镜像表 + 定时同步(照搬 Hub 同步那套骨架)
Hub 组织人员同步已经把这类问题做过一遍了,骨架直接搬:
| 已有 | 位置 | 镜像外部数据时对应 |
|---|---|---|
| 全量 + 增量游标 + 变更流水 | service/hub_sync.py |
上游有变更接口就增量,没有就全量 |
| 每次执行落一条 run 记录(耗时/条数/游标/操作人/失败原因) | oa_hub_sync_run(models.py:1216) |
oa_data_sync_run,页面上看「上次同步结果」 |
调度线程按天跑,只认 trigger='schedule' 的当天记录做幂等 |
main.py:_scheduler_loop(main.py:117) |
同一个线程加一个分支 |
| 配置分组 + 免重启热生效 + 来源标记 | dbconfig.GROUPS(dbconfig.py:138) |
新增 data_source 分组 |
密钥只进不出(KIND_SECRET + secret_set) |
dbconfig.py:241 |
数据源密钥同约定 |
镜像表怎么建:一张通用表,不要一个源建一张表。
CREATE TABLE oa_external_record (
id VARCHAR(32) NOT NULL PRIMARY KEY,
source VARCHAR(64) NOT NULL, -- 数据源编码,对应 oa_data_source.code
value VARCHAR(191) NOT NULL, -- 外部主键(成本中心号 / 物料号 / 合同号)
label VARCHAR(512) NOT NULL DEFAULT '',
parent VARCHAR(191) NOT NULL DEFAULT '', -- 有层级就填,直接喂给 cascadeFrom
extra JSON NOT NULL, -- 单价、余额、负责人、税率…
enabled TINYINT(1) NOT NULL DEFAULT 1,
order_number INT NOT NULL DEFAULT 0,
external_updated_at DATETIME(3) NULL, -- 上游给的时间,用来跳过没变的行
synced_at DATETIME(3) NOT NULL,
UNIQUE KEY uk_ext_value (source, value),
KEY idx_ext_label (source, enabled, label),
KEY idx_ext_parent (source, parent)
);
形状刻意与 oa_dict_item 一致(value / label / parent / extra / enabled /
order_number)。这不是巧合:为的是让前端 effectiveOptions() 与 applyAutoFill()
(formLinkage.ts:140)原样吃这份数据——
镜像表只换了「选项从哪查」,级联、带出、只读态翻名一个都不用重写。
同步实现要点(与 hub_sync 同一套纪律):
- 只写不撤:上游这次没返回的标
enabled=0而不是删掉,否则在途单据的值翻不出名字; - 逐行 upsert,用
external_updated_at跳过没变的行,别每次全表重写; - 失败不炸整轮:单个分页失败记
partial并继续,原因写进run.message; - 全量拉取加分页与并发上限,超时走配置项,不许写死;
- 镜像表只读:不给业务界面提供手工改它的入口。要人工兜底就在字典里加一条覆盖—— 两边都能改一定会打架。
关键约束:审批时只查本地镜像表,绝不在审批请求里同步去调外部。 同步失败最多是数据旧几分钟,审批页卡住是生产事故。
4. 形态③:远程搜索选择(大列表按需取)
物料几万条不能整份下发。这条也几乎是白送的:
- 前端
components/common/Select.vue已经有remote+loading两个 prop (Select.vue:172); composables/useKeyedDebouncedSearch.ts已经把防抖、请求取消、过期响应丢弃做完了, 而且按 key 隔离,正好对上「一张表单里两个搜索框互不干扰」。
要补的只有后端一个代理接口:
# 落地形状(GET + 查询参数,与单值取数分开一条路)
GET /api/v1/data-source/options?code=erp_material&keyword=笔记本电脑
-> { "items": [{"value","label","extra"}], "total": 2, ... }
设计要点:
- 关键词非空才查(建议至少 2 个字符),空关键词返回空列表并给一句提示;
limit服务端硬上限(默认 50),返回truncated让人知道「还有更多,请细化关键词」;- 搜索结果与已选值分开:选中项的回显走按值精确取数(§5 的
/values), 否则只读态和打印单会显示一串裸编码——这和现在option_labels()干的是同一件事; - 镜像表来源的走 SQL
LIKE+ 分页,实时来源的透传上游并截断。
5. 形态④:字段级即时带出(本方案的主菜)
「选了成本中心,自动带出预算余额」这类需求,结构上和已有的 autoFill
是同一件事,只是数据来源从字典项 extra 换成了外部接口。所以设计上不做新概念,
只给现有那条链路加一个来源分支。
5.1 字段配置的形状
现在(字典来源,保持不变):
{ "key": "price", "type": "number",
"autoFill": [{ "field": "material", "pick": "price", "to": "price" }] }
落地(外部来源,字段上多一个 fetch):
{ "key": "budgetLeft", "type": "number", "readonly": true,
"fetch": {
"source": "erp_budget_balance", // oa_data_source.code
"args": { // 入参映射:常量 / 其它字段 / 系统值
"costCenter": "{form.costCenter}",
"year": "{auto:today:YYYY}",
"company": "{const:1000}"
},
"picks": { // 带出映射:源上的键 -> 表单字段
"value": "budgetLeft", // value 是那个单值本身
"name": "costCenterName" // 其余键来自数据源的 mapExtra
},
"onError": "keep", // 取数失败:keep 留空 | block 挡提交 | zero 记零
"revalidateAfter": 5, // 可选:填单页每 5 秒自动重取一次,入参没变也取(不写=不主动刷)
"freezeAfterStart": true // 可选:流程发起后冻结这一格,办理环节不再改它
} }
一格要同时用好几个接口时换成 sources 那份合集写法(最多 8 个源,一个源自己一份
args / picks),再用 merge 说清怎么合成一个值:
{ "key": "budgetLeft", "type": "money", "readonly": true,
"fetch": {
"sources": [ // 按清单顺序调,一个一个来
{ "source": "erp_budget_balance", "args": { "costCenter": "{form.costCenter}" },
"picks": { "name": "costCenterName" } },
{ "source": "crm_budget_balance", "args": { "costCenter": "{form.costCenter}" } }
],
"merge": "sum", // first 顺序取第一个有值的 | sum | min | max | join
"separator": "、", // 只有 join 用得上
"onError": "block"
} }
三档语义对应三种真实问法:「ERP 有就用 ERP」是 first,「几个系统的余额看总数」是 sum,
「按最紧的那一家卡」是 min / max,「多个单号并排显示」是 join。两条硬规矩:
空返回不算取到(否则一个系统没回值就把合计拉成 0),少调成一个源只有 first 继续——
sum / min / max 缺一个数结果就是错的,一律按 onError 处理,宁可挡住也不写残缺的合计。
数值合并按分算再折回来,填单页面显示的那个数和提交后落进 work.data 的是同一个。
单源老写法继续有效,sources 配了才切过去,设计器在只剩一个源时又自动写回单源形状。
与最初草稿的两处出入,都是实现时改的:
-
取值路径(
pick/mapExtra)默认挂在数据源上而不是字段上。同一个接口的响应形状 是接口自己的事,十个字段用它的余额不该写十遍路径;字段只说「这个键我要落到哪一格」。 于是pick挪进注册表,字段侧换成picks这张映射表,顺带把「顺手带出名称」 (草稿里的labelPick)统一成picks里的一行,不再单开一个属性。 这一条后来开了一格例外:接口回了七八列、而这一格要的正是源上没声明的那一列时, 字段可以带一份解析覆盖——fetch.pick说「本格取哪一条路径」,fetch.extras说 「本格还要哪几列」,留空就是跟随源上的声明,两处都只改这一格:{ "source": "erp_budget_balance", "pick": "data.ownerName", // 本格改取这一列;留空 = 跟随源上的 data.balance "extras": { "owner": "data.ownerName" }, // 本格再要的一列:名字给下面 picks 挑,路径写在响应里 "picks": { "owner": "costOwner" } }取值路径本身认四种段:对象键、数组下标、按字段筛一行(含
^=认开头 /~=认包含), 以及把筛剩下的行算成一个数(data.expense_items[category_name^=差旅费].sum(amount))—— 对面把要的那个值装在明细列表里时,老写法只能取第一行。写法、比较口径与筛不到时那句提示见 external-data-simplification.md §1.6。不开这格例外,出路只有两条都更难堪:为同一张接口的第二种用法再注册一条源(配置页上 多三条几乎一样的源,改地址要改三处),或者去改一张正被别的字段共用的源(一改全变)。 代价是缓存键要带上这份解析形状——同一条响应被两格各取一列时,解析出来的值不是同一个 (
fetch._key_args),所以两格各占一份缓存;设计期那句「这个键声明过没有」也一并把 字段上补的列算作声明(binding.entry_problems)。 -
带出去向记的是格子名,格子被删掉时这份指向得跟着走。
picks的值、字典带出的to、 额度的show、阈值的flag存的都是字段名,格子删了它们还留在字段上,就同时坏三件事: 设计期校验从此一直报「要把 x 带进不存在的字段」;那一行的下拉因为按值找不到对应项而显示成 「不带出」,配的人既看不见也存不下去;field_text_2这种键名还很容易被后来新加的字段复用, 旧带出于是把外部数、台账数悄悄盖到不相干的那一格上。三处一起收口:- 删格子时就地清掉指向它的带出,打开改之前存下的老表单时同样自愈一次
(前端
utils/formPrune,设计器删字段 / 删整行 / 打开表单三个入口); - 界面上那条掉在地上的去向照原样列在下拉里并标红,旁边给一个当场清掉的口,
不再装作「不带出」(
SourceBindingEditor); - 运行时只往还存在的格子里写:外部取数、字典带出、额度三格、阈值标记四处共用
binding.live_target这一把闸,前端那份即时带出同口径(utils/formFetch)。
只收写入的方向。
{form.x}那种读的方向(取数入参、公式、联动条件、阈值右边)不动: 那句写法在界面上看得见,删不删是人的决定,而且少发一个入参会把接口调用变成另一种形状。 - 删格子时就地清掉指向它的带出,打开改之前存下的老表单时同样自愈一次
(前端
-
onError三档都留着,但默认是keep(取不到留空,由必填与阈值去管),zero只对比价型的格子有意义——把取不到的金额记成 0 与记成空,在报表上是两回事。
args 只认三种写法(有意不做通用表达式,避免再造一门模板语言,与 autoRule
「只认前后缀、不重造模板语法」的取舍一致):
"{form.xxx}"取同表单字段值;"{auto:xxx}"取service/autofill.py里那 10 个已落库的系统值(发起人、部门、工号…);- 其它一律当字面量。
这一整份形状明细表的列上也挂得上,键名与语义一个字都不变,只是它按行跑:{form.x}
读的是「整张单 + 这一行」,带出去向只落在同一张表的列上。见 §9.2。
5.2 数据源注册表
CREATE TABLE oa_data_source (
id VARCHAR(32) NOT NULL PRIMARY KEY,
code VARCHAR(64) NOT NULL, -- 字段上引用的编码
name VARCHAR(255) NOT NULL,
system VARCHAR(64) NOT NULL DEFAULT '', -- ERP / HR / MES / 主数据…
kind VARCHAR(16) NOT NULL DEFAULT 'fetch', -- fetch 单值 | search 列表
enabled TINYINT(1) NOT NULL DEFAULT 1,
provider VARCHAR(16) NOT NULL DEFAULT 'http', -- http 真调 | mock 样例响应
mock_payload JSON NOT NULL, -- provider=mock 时的样例响应
method VARCHAR(8) NOT NULL DEFAULT 'POST',
url VARCHAR(512) NOT NULL DEFAULT '',
headers JSON NOT NULL,
body_template JSON NOT NULL, -- 请求体模板,占位符同 args 三种写法
auth_type VARCHAR(16) NOT NULL DEFAULT 'none', -- none | api_key | basic | bearer
auth_username VARCHAR(255) NOT NULL DEFAULT '',
auth_secret VARCHAR(512) NOT NULL DEFAULT '', -- 只进不出,接口只回 secret_set
items_path VARCHAR(128) NOT NULL DEFAULT '', -- 列表在响应里的点路径
map_value VARCHAR(64) NOT NULL DEFAULT 'value',
map_label VARCHAR(64) NOT NULL DEFAULT 'label',
map_extra JSON NOT NULL, -- {extraKey: 响应里的点路径}
timeout_seconds INT NOT NULL DEFAULT 5,
retries INT NOT NULL DEFAULT 1,
cache_seconds INT NOT NULL DEFAULT 0, -- 0=不缓存
rate_limit_qpm INT NOT NULL DEFAULT 0, -- 0=不限
cooldown_seconds INT NOT NULL DEFAULT 60, -- 连续失败后的熔断静默期
min_permission VARCHAR(64) NOT NULL DEFAULT '',-- 空=登录即可
last_test_status VARCHAR(16) NOT NULL DEFAULT '',
last_test_message TEXT NOT NULL DEFAULT '',
last_test_ms INT NOT NULL DEFAULT 0,
last_test_at DATETIME NULL,
last_test_by VARCHAR(255) NOT NULL DEFAULT '',
description TEXT NOT NULL DEFAULT '',
creator VARCHAR(32) NOT NULL DEFAULT '',
creator_name VARCHAR(255) NOT NULL DEFAULT '',
UNIQUE KEY uk_data_source_code (code)
);
这张表的形状照抄 oa_ai_provider(models.py:1323):
同一套「编码 + 协议 + 密钥只进不出 + 内置『测试连通』把结果留在行上」的成熟做法,
连管理页都能照 AiProviderView.vue 抄,运维不用再学第二套配置界面。
kind 两段对应两种读法:fetch 查一个值(§5 的带出),search 查一个列表(§4 的远程搜索)。
字典那条路(§2)不走这张表——字典项本来就有自己的表和界面,
再包一层数据源只会让同一样东西有两个编辑入口,改了一边另一边不知道。
草稿里的 mirror 落地时换成了 provider:镜像同步要的是「数据先落在 OA 的表里」,
那是 §3 那套排期任务的产物,跟「这个源怎么调」是两个维度,混在一个布尔位上,
将来「镜像表 + 实时兜底」这种组合就没地方写。provider 现在只有 http | mock 两档
(§5.4),镜像源作为第三种取值留给 §3 落地时再补。
上面的 DDL 只是给人看的形状,以 sql/schema.sql 与
app/models.py 的 DataSource 为准:静态检查
scripts/check_schema_snapshot.py 每天对着这两个源对账,而本文档没人查,
所以列的准确含义看那里、这里只讲为什么这么分。
5.3 调用链路
发起页 / 审批页 后端
改 costCenter ──┐
│ 防抖 + 入参指纹变了才发(FormRenderer 里的即时预取)
├─ POST /data-source/fetch ─────────> fetch.run(source, args, user)
│ ├ 权限:min_permission 够不够
├ 只读格子显示 12300 <───────────────┤ 熔断 -> 限流 -> 缓存 -> HTTP
│ (这一路只为"早点看到数", ├ pick / mapExtra 取值
│ 不作任何判定) └ 留痕:一次调用一条
点提交 ─────────> POST /job 或 POST /task/{id}/execute
└ engine._apply_form_runtime
├ 环节字段权限:非 editable 的字段先被丢掉(已有)
├ dicts.apply_auto_fill(已有)
├ fetch.apply_form(db, fields, data) <- 与 autoFill 并列
│ 同一入参命中缓存则不重复调外部;以取回的值覆盖前端
├ formruntime.compute_formulas(已有,所以公式吃得到带出值)
├ quota.apply_and_check(额度占用与超支判定)
├ threshold.apply_check(阈值规则,见总方案 §4.7 页面三)
└ 必填 / 范围校验
两个硬要求:
- 前端带回来的外部值不算数。跟
autoFill一样:fetch.apply_form在提交时按同样的 入参再取一次,以取回的值为准覆盖(缓存命中就不重复发请求)。这是本方案最重要的一道防线, 沿用engine里那句分寸——「带出值以字典为准:前端把它改成什么都覆盖回去」。 即时预取那一路(POST /data-source/fetch)只负责把数字早点显示给人看, 它既不能证明什么,也不参与任何判定;改了它什么也绕不过去。 预算余额这种字段能被前端塞假值,等于把审批变成摆设。 - 带出发生在公式之前,这样「预算余额 - 申请金额 >= 0」这类公式和后面的条件分支读到
同一份数;与现在
apply_auto_fill到compute_formulas的顺序一致。
5.4 样例通道:上游还不存在时先怎么跑
排期上的现实是上游系统还没开发,一个取数接口都没有(总方案 §4.5)。如果注册表只会发 HTTP,
那么整条链路——字段绑定、公式、额度、阈值、审批分支——都得等上游,
而这几件事恰恰是最需要早点配出来给业务方看的。所以数据源多一个 provider=mock:
{ "code": "erp_budget_balance", "provider": "mock",
"mockPayload": { "code": 0, "data": { "balance": 12800, "costCenterName": "研发中心" } } }
mock_payload 走的是与真接口完全相同的那套解析规则:同一条 pick 点路径、同一份
mapExtra、同一个 picks 映射,值里的 {arg.costCenter} 照样会被替换。它就是一个自己家的假接口。
差别只有两条:一次 HTTP 都不发,但留痕照记(状态、耗时、入参都在,
省得排查时以为数据源没被调过)。
于是接一个真实系统的动作被压缩成:把 provider 改回 http、填上 URL 与密钥、点一次测试。
表单上一个格子都不用动——这是本节这套配置形状最主要的价值,不是省几行代码,
而是让「等上游」不再阻塞「把管控配出来」。验收里那条
上游还没开发时也能把整条链路配完验完(backend/tests/oa_fetch.py::test_mock_channel)
钉的就是这个换通道动作:中间只改数据源上的通道与地址,表单配置一字不动。
5.5 缓存
只加一个进程内 TTL 缓存,键为 (source, 规范化后的 args):
- 默认
cache_seconds=0(不缓存),由数据源自己按数据变化速度决定; - 一次提交里同一入参只调一次(请求内 map,等价于
dicts.DictCache的作用); - 明确不引入 Redis:本系统是单进程 uvicorn(
scripts/prod-api.sh),进程内缓存够用, 加一层 Redis 换来的是又一个要运维的组件。真上多副本时再把缓存后端做成可替换的; - 缓存只加速、不兜底:过期就现调,不主动预刷新。
5.6 场景范例:预算额度(报销了多少、还能报多少)
这是「取外部数」最容易出事的一类,因为它看着像展示,实际是控制。先拆数再配:
| 数 | 从哪来 | 变化频率 | 谁说了算 |
|---|---|---|---|
| 预算总额 | 预算系统 / 字典附加值 | 年度 + 调整单 | 上游 |
| 已报销(已入账) | 预算系统 | 每天 | 上游 |
| 在途未办结 | 本系统 oa_work |
每次提交 | 只有 OA 知道 |
| 本次申请 | 明细表合计 | 实时 | 本单 |
可用 = 总额 − 已入账 − 在途 − 本次申请。
开工前先问上游一句话:你们的「已用」含不含已提交未办结的在途?
- 含 → OA 只要取「可用」这一个数,剩下全是表单配置,本节 A 段就够;
- 不含 → 必须补 B 段(在途扣减),否则同一成本中心两张单一起提交,两张都显示够用。
A. 今天就能配(零代码,全用现有能力)
- 字典:建
budget_center,每条附加值填{"total": 200000, "used": 120000}。 预算系统有接口就让同步脚本每天把这两个数灌进字典(§2 半自动 / §3 全自动); - 带出:
budgetCode那格选字典,budgetTotal/budgetUsed用「字典带出」 (附加值键名total/used)带出来,两格都勾只读; - 本次申请:
applyAmount用公式字段total(expenses, amount), 明细表金额列自动合计(total(明细, 值列)在公式和条件分支里是同一把尺子); - 算可用:
availAfter公式字段(只读)= budgetTotal - budgetUsed - applyAmount; - 软拦截:「超预算说明」那格配
requiredWhen→availAfter小于0(条件比的是公式字段的值,右侧是字面量0,现有联动支持); - 加环节:流程上条件分支同样写
availAfter小于0→ 走「财务复核-超预算」。 条件分支读的是work.data里的公式值,和公式共用expressions同一个沙箱,算不出来两边不一样; - 落快照:
budgetTotal/budgetUsed随单落work.data,审批页、打印单、导出都读快照, 界面上露一行小字「取自预算系统 12:03」。发起页要新鲜,办结后必须永远读快照(§7)。
配完的效果:超预算的单照样能提交,但必须写说明、自动多一个财务环节。 这是默认推荐的口径——单据是凭证不是闸门,卡死在人手里比多一个环节贵。
B. 今天配不出来的三件事(必须开发,别硬凑)
- 硬阻断「不许提交」:
validate_submit现在只有必填、明细行数、选项越界三类; 数字字段的min/max只是设计器对账(api/design.py:283)和浏览器 input 约束, 提交时后端不卡它。要做真闸门,得给_validate_form加一条「表达式约束」校验项 (配在字段上,形如availAfter >= 0),并按项目老规矩在form_problems里加同一把尺子。 - 在途扣减:现在没有任何跨单据聚合机制(
processingTaskOnceUnderSamePerson那种「只选一次」是审批人去重,跟这不是一回事)。要么上游把在途算进used, 要么上额度台账——已成文,见 quota-control-design.md,预算与备用金共用那台机器。 - 并发防超:两个人同时提同一成本中心,都读到 1000 可用、各报 800——
表单配置层面永远无解,因为「读余额」和「落单」之间必有窗口。只有两条路:
上游提供冻结/释放接口(提交即冻结、退回与作废即释放,走 §6 的
invoke, 幂等键{job}:freeze),或本系统按budgetCode串行记账(占用表 +SELECT ... FOR UPDATE或累计唯一约束)。这是全篇唯一需要「锁」的地方,值得单独评审。
C. 目标形态(P1 之后)
把 A 段第 1~2 步换成一次真实查询,其它一步不改:
{ "key": "availAfter", "type": "number", "readonly": true,
"fetch": {
"source": "erp_budget_avail",
"args": { "budgetCode": "{form.budgetCode}", "year": "{auto:today:YYYY}" },
"pick": "data.available", "labelPick": "data.budgetName", "onError": "block"
} }
预算这种强依赖字段建议 onError: "block"——取不到余额就放人提交,等于没有控制;
这与 §9 默认 keep 的取向相反,是有意为之,字段级显式选。
6. 形态⑤:流转中回填与校验
已有 invoke(服务调用)环节:engine._run_invoke(engine.py:1322)
把 {job, work, serial, title, process, activity, data, operator} POST 给配置的 URL,
响应按 resultPath 写进 work.data,失败只写 <resultPath>_error 且不阻断流转。
它已经能用,但离「业务上可信」还差几件事,按优先级补:
- 走数据源而不是裸 URL:把
url换成source(复用 §5 的密钥、超时、重试、审计、脱敏),url保留兼容老流程。裸 URL 配在流程上意味着密钥要写进流程 JSON, 而流程设计数据是能被导出、复制、随流程版本快照留档的; - 重试与幂等:加
retries,并把X-Idempotency-Key: {work.job}:{activity.id}发出去, 让上游有能力自己挡重复。写回类调用没有幂等键就等着出重复凭证; - 失败策略显式化:现在统一「记错继续」。改成环节上三选一——
continue(现状,默认, 保持兼容)/block(卡住本环节并给处理人一条可重试的提示)/branch(失败走另一条路由)。 回填凭证这种事选continue是会出财务差异的; - 写回字段要走字段权限:
resultPath落进work.data的目标字段,必须在环节上配成readonly或hidden,否则审批人手工改了值、下一环节又被响应覆盖,两边都不知道谁对。 设计器保存时校验这条并给提示。
至于「审批时校验外部状态」(比如提交前确认付款单没被撤回):不要塞进条件表达式。
表达式沙箱(engine/expressions.py)是纯计算,加 IO 会把设计器里写的东西变成能拖垮引擎的东西。
正确做法是在流程前面加一个 invoke 环节把状态取回来落成字段,条件分支照旧读字段——
多一个环节,但引擎保持纯函数、可重放、可退回重跑。
7. 快照还是引用:落库口径
这是本方案里唯一一个做错了以后没法用补丁救的决定。
结论:值落快照,名字落快照,另存一枚来源指纹。 落到 work.data 里长这样:
{
"costCenter": "CC100200", // 字段值本身,照旧
"costCenterName": "华东销售一部", // 展示名(labelPick 或镜像表的 label)
"_fetch": { // 引擎写,不进表单,不参与字段权限
"costCenter": {
"source": "erp_cost_center",
"at": "2026-10-10T11:42:07",
"args": {"emp": "10086"},
"sig": "sha1:8f3a..." // args + 响应的摘要,用来解释「当时取到的是这个」
}
}
}
理由:
- 打印单、导出 CSV、审批记录、标题规则、
oa_work_completed归档全都直接读work.data; 存引用的话这些位置全都要长出去取数的逻辑,还会随上游变化而变脸; - 上游删了主数据(成本中心撤了),去年的单还能原样打印出来;
oa_work_completed是归档表,单据办结后早就不碰外部系统了,快照是它能自证的唯一办法;_fetch这一段以_开头,走的是apply_task_values里现成的「表单里没有的键原样保留」 这条路,不需要新增机制;它只给排错和审计用,界面上露成一行小字就够。
唯一例外:字段配成 mode: "reference"(新增,默认不给)时不落快照、每次现取。
只给「余额必须绝对新鲜」这种极端字段用,且界面上必须写明「此值每次打开都重新查询」。
8. 安全、权限与审计
| 风险 | 处理 |
|---|---|
| 前端拿到外部系统密钥 | 不可能发生:调用只在后端。密钥存 oa_data_source.auth_secret,沿用 oa_ai_provider.api_key 的「只进不出、只回 secret_set」约定;日志与报错文本按 llmconfig.py 里 redact() 的路子把密钥串抹掉 |
| SSRF / 内网探测 | 新增 data_source_allow_hosts 配置(dbconfig,逗号分隔,空=不限制,生产建议必配);只允许 http/https(http_request 现在用 urllib 且带 # noqa: S310,这里补正式校验);禁止跟随重定向,否则白名单会被 302 绕过 |
| 越权取数 | 数据源上有 min_permission(空=登录即可);args 里只允许出现当前表单字段与 {auto:*} 系统值,不能让人自己填「查别人工资」的工号;工号类入参建议由后端用当前登录人身份覆盖 |
| 把外部返回值当可信文本 | 一律当纯文本落库,不进 v-html;落库前做长度截断(label 512、extra 单值 1024),别让上游把 work.data 撑爆 |
| 拖垮本系统 | 每源超时(默认 5s,上限 30s)+ 补试次数 + rate_limit_qpm + 熔断(连续失败后 cooldown_seconds 内直接返回降级结果)。审批是人在点的交互,5 秒不返回就该给降级而不是转圈 |
| 出事查不到 | 每次调用一条 oa_data_source_call(仿 oa_hub_sync_run):数据源、工号、脱敏后的入参摘要、HTTP 状态、耗时、是否命中缓存、降级原因 |
| 数据出域 | 管理页每条数据源明确列出「会把以下字段发给 X 系统」(就是 args 的键);身份证、银行卡这类默认禁止出现在 args 里 |
熔断只为「上游不健康」计数(FetchResult.health,判定在 fetch.run 各失败出口):连接失败、超时、
5xx、响应不是 JSON 算上游病了;入参没填(排在熔断之前就地返回,一次 HTTP 都不发)、解析规则取不到值、
上游回了业务错误(200 但按 message_path 说事情不通过)、4xx 都不算,因为它们恰恰证明上游是活的。
不分这一层的代价很具体:一张还没选「相关核算项目」的报销单,连着两次空入参就能把整张余额源对所有
人关掉 cooldown_seconds,而下一个把项目选对了的人只看到一句「刚连续失败」——起因和症状隔着两个
系统,谁都不会想到要去查那张贴着没提交的单子。同一口径在前端 utils/formFetch.ts 也有一份:
引用的那一格还空着,填单页面连这一次预取都不发。
审计表:
CREATE TABLE oa_data_source_call (
id VARCHAR(32) NOT NULL PRIMARY KEY,
source VARCHAR(64) NOT NULL,
work VARCHAR(32) NOT NULL DEFAULT '',
field VARCHAR(191) NOT NULL DEFAULT '',
person VARCHAR(32) NOT NULL DEFAULT '',
person_name VARCHAR(255) NOT NULL DEFAULT '',
args_digest VARCHAR(512) NOT NULL DEFAULT '', -- 脱敏摘要,不存原始值
http_status INT NOT NULL DEFAULT 0,
duration_ms INT NOT NULL DEFAULT 0,
cached TINYINT(1) NOT NULL DEFAULT 0,
degraded TINYINT(1) NOT NULL DEFAULT 0,
message TEXT NOT NULL DEFAULT '',
created_at DATETIME(3) NOT NULL,
KEY idx_dsc_source_time (source, created_at),
KEY idx_dsc_work (work)
);
新增权限码一个:design:datasource(挂进 permissions.CATALOG 的 design 组,
与 design:form 并列,permissions.py:62),
管注册表增删改与「测试连通」。读(下拉取选项、字段带出)只要登录即可,
理由和现在读字典项一样——运行时得把表单渲染得出来。
scripts/check_route_guards.py 会盯着新接口有没有挂权限点。
9. 失败与降级:设计期就要选完
取数一定会失败(上游维护、网络抖、超时、鉴权过期)。所以「失败了怎么办」不是运行时临场决定, 而是配置项,且默认值必须偏保守:
onError |
行为 | 用在哪 |
|---|---|---|
keep(默认) |
保留字段原值(空着就空着),界面提示「外部数据未取到:ERP 连接超时,可点重试」,不阻断填单 | 绝大多数展示型字段 |
block |
当场报错、必填强制不过,人必须重试或换路径 | 预算冻结、额度校验这类强依赖 |
zero |
落一个约定空值(0 / 空串)并标灰,允许继续 | 慎用:0 和「没取到」在财务上是两件事 |
这一格在当前环节被藏起来时,block 不挡提交(判据 formruntime.field_hidden,与阈值
(threshold.onHidden)、额度(quota.onHidden)同一把口径):屏幕上没有这一格,人既看不见它
也改不动它,拿一条他无从补救的规则挡在提交按钮前面,等于把这张单卡死在这一环。放行的也只有
"当场拦人"这一件事——取数照旧发起、带出照旧写、留痕照旧记,那一格的值留在原来那一份上,
等它露出来的那一环再拦(引擎把这一环的字段权限递给 fetch.apply_form)。这一档没有
onHidden 开关:onError 本来就是它的开关,要软一点就配 keep / zero,再叠一层只会让
下一个人不知道该看哪个。判据在 backend/scripts/check_hidden_field_rules.py 第 19、20、23 句
(第 23 句走的是真链路:停在藏格子那一环的单据,把那条源停掉,审批人点「同意」照样走得完)。
9.1 什么时候取:两档可选,默认还是「每趟都取」
取数时机写在字段上,两档各自解决一件事:
| 配置 | 说的哪句话 | 落在哪 |
|---|---|---|
revalidateAfter(秒,1~86400) |
入参一个字没变,这份值多久就该嫌旧 | 只在填单页面有效:到点自动重发这一格,并带 refresh 绕开数据源缓存;页面切到后台就停表,窗口重新拿到焦点、从别的标签页切回来当场补一次。提交时后端本来就会重取,与它无关 |
freezeAfterStart |
流程一旦发起,这个接口就不再调,也别再改这几格 | 判据是「还在不在开始环节」,不是第几环:发起页、草稿、停在开始环节等提交、退回来重填,全都算「没发起」,照旧随入参变化重取;进了办理环节就一次都不外呼,本格与 picks 带出去的那几格连同 _fetch 留痕一起留在发起那一刻 |
两档都是没配就不写键,存量表单的配置形状与行为一个字都不变(默认仍是每趟提交重取一次)。
实时刷新那一档要按数据源的量级来:一秒一档等于替这一格每分钟打 60 次,rate_limit_qpm
与熔断要先抬上去,设计器把这句话写在面板上。真正要的若是「对方一变我这边立刻变」,
得等外部系统回调进来、再加一条到浏览器的长连接——这两档是拉取,不是推送。
口径两边各一份实现、一句话:service/fetch.applies_at 与 utils/formFetch.fetchAppliesAt,
验收在 scripts/check_fetch_freeze.py 与 FormRenderer.fetch.spec.ts。
再叠两条运行时规则:
- 上游字段被清空或改动时,带出来的字段一起清空(已有
dropStaleSelections的语义, 扩展成同时覆盖fetch),避免出现「成本中心已经换了、余额还是上一个人的」; - 只读态不取数:待办列表、打印单、导出 CSV 一律读
work.data里的快照, 绝不在这些批量场景发外部请求——一次导出打几百个 ERP 请求是最典型的雪崩来源。
9.2 明细表的列也挂得上:逐行取数(column.fetch,2026-11)
来的是用户那句「明细表中的字段能不能配置取数,取我配置的外部数据源」。真实的问法长这样: 收款明细每一行填了收款人,开户行和银行帐号要按这一行那个人去 ERP 查——整张表共用一个值 没有意义,逐行手填又必然填错。
配法与主表那一格是同一个形状、同一个执行器,没有新键:binding.entries 那一整套
(source / sources + merge、args、picks、onError、revalidateAfter、
freezeAfterStart)在列上照写。设计器入口是「选中明细表 → 那一列的卡 → 更多配置 → 外部取数」,
摆的就是主表那块面板(FetchPanel),只是它给的下拉少两类。
| 与主表那一格的差别 | 口径 | 为什么这么定 |
|---|---|---|
| 入参读哪一格 | 作用域是「整张单 + 这一行」,与主表字段同名的列以本行为准;{form.x} 既能读主表字段也能读本行的列 |
「本行公式」吃的就是同一份作用域(formRuntime.applyRowFormulas),配的人不用为明细列再记第二套写法 |
| 「带出去向」能落哪 | 只认同一张明细表的其它列,主表字段不进下拉,保存到后端也挡 | 一行生一格,picks 写进主表那一格等于让最后一行去盖表头:三行的表盖三次,谁赢看运气 |
| 取不到数怎么说 | 「明细表「收款明细」第 2 行的「银行帐号」的外部数据取不到:ERP 连接超时」 | 整张表共用一句不带行号的报错,八行的表没人知道该回去改哪一行 |
| 整张表在这一环被藏起来 | onError=block 降级成不挡(值留在原来那一份上),取数照旧发起、带出照旧写、留痕照旧记 |
环节权限挂的是表不是列,所以那一列露不露脸看它所属那张表在这一环露不露;与 §9 那句主表规则同一把尺子(fetch._policy_of) |
留痕不能沿用主表那份「列名当键」——两张明细表可能有同名列,同一张表每一行也都得留得开。 于是按「表名.列名」记一条,底下挂逐行那几次外呼:
"_fetch": {
"收款明细.bankAccount": {
"source": "erp_bank_account", "args": {"emp": "10086"}, // 第一行那一次,方便对表
"at": "2026-11-12 10:02:31", "merge": "first", "cached": false,
"rows": [
{ "row": 1, "source": "erp_bank_account", "args": {"emp": "10086"}, "cached": false, "at": "…" },
{ "row": 2, "source": "erp_bank_account", "args": {"emp": "10202"}, "cached": true, "at": "…" }
],
"failed": ["第 3 行:ERP 银行账号接口:连接超时"] // 只有真失败才有这一行
}
}
服务端仍旧说了算:填单页按行各取一次给人看(FormRenderer.runRowFetches,一张表把所有行的
补丁攒完再一次性写回——逐行各写一次会把前面几行的结果冲掉,model 是 props 上的 computed),
提交时 fetch.apply_form 走 _apply_rows 按同一份配置逐行再取一次并覆盖,接口直传与前端篡改
都塞不进假值。跑的是 data 里当前那几行:被人删掉的行不会再取一次,新加的那一行当场补得上。
删列时指向它的带出一起清(utils/formPrune 按这张表剩下的列名滤 picks,那句「掉在地上的指向」挂在 列名.带出键名 上)。
仍然没做的是「一次查询填整张表」(结果集控件,见
sql-autofill-design.md §6 第 4 条)。这一档是一行一调:
十行就是十次外呼,再叠 revalidateAfter 就是十次乘以刷新次数,数据源上的缓存 TTL 与
rate_limit_qpm 要先抬到量级上(面板上那句每分钟约 N 次的提醒是同一件事的另一半)。
真需要「一次查一批、每行装进一格」,那是新形态,得单独设计。
验收:PYTHONPATH=. python3 scripts/check_row_fetch.py(34 条:逐行取数与覆盖、入参作用域、
带出去向只认本表、点行号的报错、整表隐藏时降级、留痕形状、设计期那几道闸门),前端
utils/formFetch.rowFetch.spec.ts、FormRenderer.rowFetch.spec.ts、
design/FieldInspector.columnFetch.spec.ts、utils/formPrune.spec.ts。
10. 落地清单
P0 字典与镜像(不写新机制,先消化六成需求)
| # | 改动 | 文件 |
|---|---|---|
| 1 | 新增 oa_external_record + oa_data_sync_run 两表,导出结构快照 |
models.py、sql/schema.sql(跑 scripts/dump_schema.py,scripts/check_schema_snapshot.py 会对账) |
| 2 | service/extdata.py:镜像表的 upsert / 查询 / 按值反查 label |
新文件 |
| 3 | service/ext_sync.py:照 hub_sync.py 写全量同步 + run 记录;调度线程加分支 |
新文件、main.py:_scheduler_loop |
| 4 | 让 dicts.items_of() 在字典未命中时回落到镜像表 |
service/dicts.py |
| 5 | 管理页「外部数据」:数据源列表 + 同步按钮 + 上次同步结果 | 新 views/oa/DataSourceView.vue(照 AiProviderView.vue) |
第 4 条是这期的杠杆点:只在字典读取处加一个回落分支,前端、引擎、导出、设计器一行不改, 外部主数据就进到了所有已有的表单能力里(级联、带出、翻名、试算全都白送)。
P1 数据源注册表 + 字段级带出
| # | 改动 | 文件 |
|---|---|---|
| 6 | ✅ oa_data_source 表 + CRUD + 测试连通 + 调用留痕 + 引用查询与删除保护 |
api/data_sources.py(执行逻辑在 service/fetch.py,没再拆一个 service/datasource.py:CRUD 薄得没内容) |
| 7 | ✅ service/fetch.py:run() 执行器(权限→熔断→限流→缓存→HTTP→映射→留痕)与 apply_form() |
新文件 |
| 8 | ❌ 没复用 engine.http_request:fetch.py 自带一个 _http()(标准库 urllib)。反着记一笔账——超时与补试都在,不跟随重定向与域名白名单目前两处都没有,这是同一个口子开在两个地方,等接真实系统前该收成一个 |
engine.py:45 / service/fetch.py |
| 9 | ✅ 提交链路插入 fetch.apply_form,位置在 apply_auto_fill 之后、compute_formulas 之前 |
engine.py(_apply_form_runtime,非草稿才取) |
| 10 | POST /process/data-source/fetch、/valuesPOST /data-source/fetch、GET /data-source/options(单值与搜索共用一个查询参数形状) |
api/data_sources.py ✅ |
| 11 | ✅ 设计器:单独一个 design/FetchPanel.vue(塞进 LinkagePanel 会让那块面板长到没法看);设计期校验前后端同一把尺子 |
utils/formFetch.ts + api/design.py:form_problems + fetch.problems() |
| 12 | ✅ FormRenderer.vue 按入参指纹防抖预取(utils/formFetch.ts)。「取自 ERP 12:03」那行小字没做:来源与时间存在 data._fetch 里随单据落库,界面上暂时不显示 |
components/oa/FormRenderer.vue |
| 13 | ✅ 新权限码 design:datasource:permissions.py + constants/permissions.ts + i18n 中文名 + README 权限表与总数(现在 29 个) |
四处 |
第 11 条别偷懒:项目现在的规矩是「预览说能存的就一定存得下」,前后端两份校验必须同步加。
P2 远程搜索与性能
- ✅ 搜索端点已落(
GET /data-source/options,kind=search的源走它,关键字透传 + 截断 200 条); 镜像表那条 SQLLIKE分支等 §3 的镜像表落地再补; - ⬜ 没做:
FormFieldControl的 select 分支还没接Select.vue的remote模式。 现在这个端点只被数据源界面的「测试连通」用着——后端能搜,表单里的下拉还接不上, 这条是 P2 剩下的大头; - ✅ 进程内 TTL 缓存 + 连错两次熔断(冷却时长就是
cooldown_seconds)+ 每分钟限流; - ⬜ 选中项按值反查 label 的回显没做;只读态与打印不取数是天然成立的(取数只发生在 填单页的预取与提交链路里,只读渲染不预取)。
P3 环节回填
invoke环节支持source替代裸url,加幂等键、重试、continue|block|branch三态;resultPath目标字段的环节权限冲突检查;- 批量校验(一次提交校验明细表 50 行):给数据源加
batchable与批量端点, 绝不用循环调 50 次单条接口;上游没有批量接口就退化成「取不到只提示、不卡提交」。
验收
照现有习惯加一个自建临时库的端到端脚本,并挂进 scripts/run_all.py:
# 外部取数验收(自建外部数据源桩 + 临时库 unisoa_fetchtest,跑完自动删,不碰开发库)
python3 backend/tests/oa_fetch.py
# 明细列逐行取数(§9.2:内存库 + 假上游,不建库、不打真接口,秒级)
cd backend && PYTHONPATH=. python3 scripts/check_row_fetch.py
桩服务这次没单独成文件:假上游是 tests/oa_fetch.py 里的 Upstream 类
(ThreadingHTTPServer 起在本机随机端口,balance / status / fail_times 都能从用例里改,
不用重启),102 条断言与桩在同一个进程里,读起来是一条链路。真正给上游当参考实现的桩
留到上游开工时再抽成 tests/extdata_stub.py(见 integration-contract.md §5)。
覆盖到的:设计期配置错存不进来(源不存在 / 停用 / 列表型取单值 / 入参与带出键指向不存在的字段)、
密钥不回显且改配置不回填、样例通道与换回真接口、正常带出与多个带出键、上游 500 配 keep 放行、
配 block 卡住提交、审批环节按上游新值重算、前端篡改带出值被后端盖回、缓存命中不再外呼、
每分钟限流、连错两次熔断且拉闸期间零外呼、权限门槛、阈值三档下场与设计期闸门、
每次调用留痕(含耗时、单据号、成功与被挡两种状态)、被引用的源删不掉。
没覆盖的:上游超时与慢响应(桩只有秒回与 500 两种)、上游把某个键删掉以后带出值怎么清、 导出与打印路径确认不发外部请求。前两条是接真实系统最容易撞上的,桩加两个开关就能补。
11. 需要你拍板的 6 件事
- 落地目标:外部主数据统一进「镜像表 + 字典回落」(§3 的 P0,前端零改动), 还是允许直接实时查(P1 起步)?我倾向先做前者——风险最低、当天能用、还能挡掉大部分需求。
- 新鲜度要求:哪些字段必须「打开单据那一刻重新查」?这个清单直接决定要不要做 §7 的
reference模式,也决定 P95 延迟预算。 - 取数失败的默认策略:默认
keep(不阻断填单)还是block?我倾向默认keep, 把block留给少数强依赖字段——否则外部系统一抖全公司提不了单。预算额度这类「取不到就等于没控制」的 字段属于后者,见 §5.6 C。 invoke环节的历史包袱:现在裸url的配法有没有在用?如果流程 JSON 里已经写了密钥, 迁到source时要先轮换一次密钥,不能只做兼容。- 数据范围:外部数据要不要按人/部门收口(比如销售只能搜自己名下的客户单)?
要的话在数据源上声明权限码 + 由后端强制注入
args,不要指望上游过滤得对。 写回范围已定:要写回。出站(OA → 业务系统)单独成篇,见 outbound-integration-design.md;它与本方案共用数据源注册表、密钥与审计口径。
12. 明确不做的事
- 不在前端放任何外部系统凭证,也不给前端一个「自定义 URL」的口子;
- 不把外部调用塞进
expressions.py的沙箱(条件、标题模板、公式里都不能调外部); - 不在列表页、待办列表、导出、打印这些批量场景里现取外部数据;
- 不做通用「API 编排 / 可视化拼装响应体」——
items_path+pick的点路径够用, 再复杂就让上游提供一个正好合适的接口; - 不引入 Redis / 消息队列 / 新的 HTTP 客户端依赖(本仓库刻意只用标准库
urllib, 见service/hub.py与engine.http_request的注释),保持部署简单。
13. 相关文档
- architecture.md 请求生命周期、配置取值分层、接口一览
- hub-integration.md 同步骨架与密钥约定的出处
- outbound-integration-design.md 反向:OA 写回业务系统(发件箱 / 幂等 / 冲销 / 对账)
- quota-control-design.md 额度控制:预算超支与备用金冲销(跨单据累计占用)
- README「表单设计」:系统带出(
type: auto)与「申请人 / 申请部门 / 审批人怎么自动带出」两节, 以及「表单与流程怎么对上」的字段权限口径。注意 字典带出(autoFill)与级联在 README 里目前没有文档, 口径只散在设计器界面文案(frontend/src/i18n/locales/zh.ts:1190)与验收脚本tests/oa_dicts.py里, P1 落地时顺手补一节 README。 - README「引擎能力」:环节类型清单(
invoke在界面上叫服务调用,见 README「引擎能力」 的环节类型一行与元素映射表)。它的配置项url/method/headers/timeout/resultPath以及「失败只写<resultPath>_error不阻断流转」这套语义 README 未展开,权威来源是engine._run_invoke,§6 要改的就是这一段。
14. 落地补充:从另一个流程带数据 + 每个字段都能挂阈值 / 额度(2026-10-16)
§11 让我们拍板的那 6 件事里,第 3 件问的是「带别的系统的数据要带到什么程度」。真用起来最先撞上的 需求反而更近:带 OA 自己另一张单——填报销单时把上次那张批完的请假单里的出差日期、目的地点进来, 别让人再抄一遍。这一节记两件已经落地的东西,都是照 §5 的骨架加东西,没有另起一套。
14.1 多一条取数通道:provider=process
做法不是再造一个「自动带出」,而是把它做成又一个数据源(service/processdata.py):入参仍是
本表单字段({form.x},照旧经 render 渲染),产出仍走 fetch.parse 那套 pick / map_extra,
所以字段级配置、多源合集(§5 那 8 个源合成一个值)、带出去向、调用留痕、提交时服务端覆盖
全部是现成的,fetch.run 里只多一个分支。
配置只四格(srcProcess / srcMatch / pick / mapExtra,界面是
components/oa/design/ProcessSourcePanel.vue),匹配条件那些字段存在 oa_data_source.src_match,
src_process 单独一列,为的是「那个流程被删掉 / 停用时能查出谁在用它」:
| 字段 | 默认 | 说明 |
|---|---|---|
scope |
own |
own 只查调用人自己发起的单;all 不限发起人(跨人) |
person |
空 | 「按表单里指定的人查」,只在 scope=all 时生效(自己的单不该被表单里的字段指到别人身上) |
status |
completed |
只认走完的单 / 只认在途(running)/ 都算(any) |
order |
latest |
命中多单时取最近还是最早 |
days |
0 | 只看最近 N 天,0 = 不限 |
limit |
20 | 列表型(kind=search)一次回几条,上限 50 |
filters[] |
空 | 最多 8 条:field + op(eq/ne/contains/in/gt/gte/lt/lte/empty/notEmpty)+ value(可写 {form.x}) |
pick / map_extra |
— | 与 HTTP 源同一套取值路径;勾「要带出哪几格」自动把两条路径写好,不用手打 |
四条分寸值得单独说:
- 默认只查调用人自己的单。把别人的单据内容带到自己这张单上,是一件出事之前没人觉得有问题的事。
要跨人查必须显式改成
all,而且这个源得配min_permission——保存时processdata.validate挡一道,运行时fetch.run那道权限检查再挡一道。 - 默认只认审批走完的单。在途单的数字随时会变,抄进另一张单等于拿草稿当依据。
写错状态档时
clean_match退回「只认走完的单」而不是「全部都算」——认不准时退回安全的那一边。 - 匹配条件在内存里筛,而且只在最近 300 单里筛(
SCAN_LIMIT)。work.data是 JSON 列, MySQL 在不同版本上把字符串"1200"与数字1200比大小的口径并不一致,与其赌一个隐式转换, 不如把候选量卡住之后自己比;候选够不够,设计器一句话说得清。 - 一条源最多 8 个匹配条件。再多说明该去对面做一个查询接口,而不是在这里堆条件。
带出去的形状刻意做成和外部接口响应同一种形状:单值型 pick 写 data.amount,列表型
search_payload 回 {"works": [{…, "data": {…}}]},每一项里也嵌一份 data,所以 map_extra
的写法两种 kind 完全一样,界面上那份「勾选带出哪些字段」不用按类型换两套路径前缀。单据本体
另有七个能直接带的键(单号 / 标题 / 状态 / 发起人 / 发起部门 / 发起时间 / 办结时间),界面上单独一档。
14.2 挑流程:先选类型,再选流程
流程几十上百条时,「在一条长下拉里翻到那个流程」本身就是障碍,而三处都要挑流程
(关联审批单字段级、明细表列级、数据源的来源流程)。收成同一个组件
components/oa/design/ProcessPicker.vue:先选流程类型、再在那个类型里选流程,类型带条数、
没归类的单独一档「未分类」、草稿状态标出来;选中流程会把类型筛子钉到那一类,手动换类型而当前
流程不在该类就清空选择(免得存下来的类型和流程互相不打招呼)。明细表列上换两栏窄版(dense)。
存下来的仍然只有流程 id,类型只是找流程时的一级筛子,不参与任何判定。
流程清单走 utils/processCatalog():60 秒缓存 + 并发合流,三个面板同时打开只发一次请求。
14.3 带出 / 阈值 / 额度:三样都改成「每个字段都能挂」
以前这三样各在界面上写死一份类型白名单(各 7 种),三张名单互不相干:日期格能判阈值却不能带出、
人员格能选却不能问一句「有没有填」、34 种类型里二十多种在三个面板前都看不见——不是功能没有,
是界面没给入口。收成一份口径:utils/fieldCapabilities.ts,按「这一格装得下什么」分组。
| 分组 | 类型 | 带出 | 阈值面板给的比较符 | 额度 |
|---|---|---|---|---|
| 数值 | money number formula rate |
✓ | gt ge lt le eq ne empty notEmpty |
✓ |
| 日期 | date datetime time |
✓ | 同上 | ✓ |
| 文本 / 选项 | text textarea mobile email idcard url select radio auto hidden |
✓ | 同上 | ✓ |
| 开关 | switch |
✓ | eq ne empty notEmpty |
✓ |
| 一串 / 一个对象 | daterange checkbox dept cascader user relation address |
✗ | 只有 empty notEmpty |
✓ |
| 明细表 | table |
✗ | 只有 empty notEmpty(判有没有填过行) |
✓(逐行控) |
| 附件与签名 | attachment image file sign signature |
✗ | 只有 empty notEmpty |
✗ |
| 纯排版 | title divider description |
✗ | ✗ | ✗ |
(后端认得比面板宽:in / nin / contains 这些还在 dicts.CONDITION_OPS 里,只是新界面不再摆出来;
ops_for 认不出的类型一律不评判。带出只给「装得下一个数或一句话」的那些格,多源合集才有意义。)
三点容易误解的:
- 额度不要求这一格是数值格。本次花掉的钱永远来自额度配置里的金额来源(
cfg.amount, 通常是{form.x}),不是宿主字段自己的值,所以挂在一行「费用说明」文本上完全合法; 面板只在既不是数值格又没选金额来源时提示一句。 - 阈值「命中=触发下场」,所以「这一格必须填」是
op=empty+mode=block,notEmpty反过来是「填了就触发」。比较符按类型给,老配置里已经写了但不在新集合内的 op 照旧列出来(不偷改别人的配置)。 - 判定仍然只在服务端做一次。这份口径决定的是设计器摆不摆那一栏、摆哪几个比较符;提交时
service/threshold.py/service/quota.py用同一份口径再判一遍(threshold.py的ops_for(type)与后端quota.UNCONTROLABLE_TYPES是同一分组的另一份实现),配置里出现这一格比不了的比较符 会当场报「这一格比不了」,不认识的类型一律不评判(宁可不报也不误报)。 字段卡上加了三个角标(阈值 / 额度 / 带出)标出这一格挂了哪几样。 顺带对齐了布尔口径:switch存的False与规则里写的false/True/true前后端一致 (service/dicts.compare↔utils/formLinkage.sideText),不再出现界面上命中、后端不判。
14.4 代码地图与验证
| 关心的事 | 在哪 |
|---|---|
| 流程通道执行 | service/processdata.py(candidates / pick / find / payload_of / search_payload) |
| 挂进取数主流程 | service/fetch.py(provider == PROVIDER_PROCESS 那一个分支) |
| 保存期校验 | processdata.validate(跨人必配 min_permission、流程是否存在、条件条数) |
| 来源流程配置面板 | components/oa/design/ProcessSourcePanel.vue |
| 两级选流程 | components/oa/design/ProcessPicker.vue + utils/processCatalog.ts |
| 字段能力口径 | utils/fieldCapabilities.ts ↔ service/threshold.py: ops_for、service/quota.py: UNCONTROLABLE_TYPES |
| 阈值 / 额度面板 | components/oa/design/ThresholdPanel.vue、QuotaPanel.vue、画布角标在 FormSheetCanvas.vue |
落地时逐条跑过真库(整体回滚不留数据):通道本身的范围 / 状态 / 匹配条件 / 列表型 / 跨人权限、
数据源保存期校验与「这个流程能带出哪些字段」那个接口、以及 §14.3 那张能力表(含 switch 的布尔口径
前后端一致)。这类一次性验证按仓库习惯写成 backend/scripts/check_*.py 的形状,跑在 backend 目录下。
最后更新:2026-10-16(补 §14:流程数据通道、两级选流程、字段能力口径)