unis-oa/docs/form-data-integration-desig...

65 KiB
Raw Permalink Blame History

表单字段从外部系统取数:设计方案

需求与结论对照、总架构与总路线图见 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 今天就能配(零代码,三步)

不必等本方案落地——「选一个、顺手带出几个数」这类需求现在就能配完,入口与界面文案已和设计器现状核对:

  1. 表单设计 → 数据字典(路由 /design/dicts,权限 design:form)建字典类型并逐项录入。 每条字典项的**「附加值(JSON)」**就是带出的数据来源,例如物料项填 {"price": 3.5, "tax": "13%", "owner": "张三"};
  2. 表单设计 → 选中那个下拉字段 → 「字典带出」(components/oa/design/LinkagePanel.vue), 逐行挑「取哪一列」与「写进哪个字段」,例如 附加值 · price → 单价那格。取哪一列的写法与 「显示 / 存值」那两列同一套:留空取名称、value 取键值、extra.单价 走点路径; 老表单里那句裸 price 仍旧按附加值读,一个字节都不用改(口径见 optionMap.pickFillValue ↔ dicts.pick_fill_value);
  3. 被带出的那格勾上**「只读」**,免得人手改。提交时 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 页面三)
                          └ 必填 / 范围校验

两个硬要求:

  1. 前端带回来的外部值不算数。跟 autoFill 一样:fetch.apply_form 在提交时按同样的 入参再取一次,以取回的值为准覆盖(缓存命中就不重复发请求)。这是本方案最重要的一道防线, 沿用 engine 里那句分寸——「带出值以字典为准:前端把它改成什么都覆盖回去」。 即时预取那一路(POST /data-source/fetch)只负责把数字早点显示给人看, 它既不能证明什么,也不参与任何判定;改了它什么也绕不过去。 预算余额这种字段能被前端塞假值,等于把审批变成摆设。
  2. 带出发生在公式之前,这样「预算余额 - 申请金额 >= 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. 今天就能配(零代码,全用现有能力)

  1. 字典:建 budget_center,每条附加值填 {"total": 200000, "used": 120000}。 预算系统有接口就让同步脚本每天把这两个数灌进字典(§2 半自动 / §3 全自动);
  2. 带出:budgetCode 那格选字典,budgetTotal / budgetUsed 用「字典带出」 (附加值键名 total / used)带出来,两格都勾只读;
  3. 本次申请:applyAmount 用公式字段 total(expenses, amount), 明细表金额列自动合计(total(明细, 值列) 在公式和条件分支里是同一把尺子);
  4. 算可用:availAfter 公式字段(只读)= budgetTotal - budgetUsed - applyAmount;
  5. 软拦截:「超预算说明」那格配 requiredWhen → availAfter 小于 0 (条件比的是公式字段的值,右侧是字面量 0,现有联动支持);
  6. 加环节:流程上条件分支同样写 availAfter 小于 0 → 走「财务复核-超预算」。 条件分支读的是 work.data 里的公式值,和公式共用 expressions 同一个沙箱,算不出来两边不一样;
  7. 落快照:budgetTotal / budgetUsed 随单落 work.data,审批页、打印单、导出都读快照, 界面上露一行小字「取自预算系统 12:03」。发起页要新鲜,办结后必须永远读快照(§7)。

配完的效果:超预算的单照样能提交,但必须写说明、自动多一个财务环节。 这是默认推荐的口径——单据是凭证不是闸门,卡死在人手里比多一个环节贵。

B. 今天配不出来的三件事(必须开发,别硬凑)

  1. 硬阻断「不许提交」:validate_submit 现在只有必填、明细行数、选项越界三类; 数字字段的 min / max 只是设计器对账(api/design.py:283)和浏览器 input 约束, 提交时后端不卡它。要做真闸门,得给 _validate_form 加一条「表达式约束」校验项 (配在字段上,形如 availAfter >= 0),并按项目老规矩在 form_problems 里加同一把尺子。
  2. 在途扣减:现在没有任何跨单据聚合机制(processingTaskOnceUnderSamePerson 那种「只选一次」是审批人去重,跟这不是一回事)。要么上游把在途算进 used, 要么上额度台账——已成文,见 quota-control-design.md,预算与备用金共用那台机器。
  3. 并发防超:两个人同时提同一成本中心,都读到 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 且不阻断流转。 它已经能用,但离「业务上可信」还差几件事,按优先级补:

  1. 走数据源而不是裸 URL:把 url 换成 source(复用 §5 的密钥、超时、重试、审计、脱敏), url 保留兼容老流程。裸 URL 配在流程上意味着密钥要写进流程 JSON, 而流程设计数据是能被导出、复制、随流程版本快照留档的;
  2. 重试与幂等:加 retries,并把 X-Idempotency-Key: {work.job}:{activity.id} 发出去, 让上游有能力自己挡重复。写回类调用没有幂等键就等着出重复凭证;
  3. 失败策略显式化:现在统一「记错继续」。改成环节上三选一——continue(现状,默认, 保持兼容)/ block(卡住本环节并给处理人一条可重试的提示)/ branch(失败走另一条路由)。 回填凭证这种事选 continue 是会出财务差异的;
  4. 写回字段要走字段权限: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、/values 实际落在 POST /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 远程搜索与性能

  1. ✅ 搜索端点已落(GET /data-source/options,kind=search 的源走它,关键字透传 + 截断 200 条); 镜像表那条 SQL LIKE 分支等 §3 的镜像表落地再补;
  2. ⬜ 没做:FormFieldControl 的 select 分支还没接 Select.vue 的 remote 模式。 现在这个端点只被数据源界面的「测试连通」用着——后端能搜,表单里的下拉还接不上, 这条是 P2 剩下的大头;
  3. ✅ 进程内 TTL 缓存 + 连错两次熔断(冷却时长就是 cooldown_seconds)+ 每分钟限流;
  4. ⬜ 选中项按值反查 label 的回显没做;只读态与打印不取数是天然成立的(取数只发生在 填单页的预取与提交链路里,只读渲染不预取)。

P3 环节回填

  1. invoke 环节支持 source 替代裸 url,加幂等键、重试、continue|block|branch 三态;
  2. resultPath 目标字段的环节权限冲突检查;
  3. 批量校验(一次提交校验明细表 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 件事

  1. 落地目标:外部主数据统一进「镜像表 + 字典回落」(§3 的 P0,前端零改动), 还是允许直接实时查(P1 起步)?我倾向先做前者——风险最低、当天能用、还能挡掉大部分需求。
  2. 新鲜度要求:哪些字段必须「打开单据那一刻重新查」?这个清单直接决定要不要做 §7 的 reference 模式,也决定 P95 延迟预算。
  3. 取数失败的默认策略:默认 keep(不阻断填单)还是 block?我倾向默认 keep, 把 block 留给少数强依赖字段——否则外部系统一抖全公司提不了单。预算额度这类「取不到就等于没控制」的 字段属于后者,见 §5.6 C。
  4. invoke 环节的历史包袱:现在裸 url 的配法有没有在用?如果流程 JSON 里已经写了密钥, 迁到 source 时要先轮换一次密钥,不能只做兼容。
  5. 数据范围:外部数据要不要按人/部门收口(比如销售只能搜自己名下的客户单)? 要的话在数据源上声明权限码 + 由后端强制注入 args,不要指望上游过滤得对。
  6. 写回范围 已定:要写回。出站(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 源同一套取值路径;勾「要带出哪几格」自动把两条路径写好,不用手打

四条分寸值得单独说:

  1. 默认只查调用人自己的单。把别人的单据内容带到自己这张单上,是一件出事之前没人觉得有问题的事。 要跨人查必须显式改成 all,而且这个源得配 min_permission——保存时 processdata.validate 挡一道,运行时 fetch.run 那道权限检查再挡一道。
  2. 默认只认审批走完的单。在途单的数字随时会变,抄进另一张单等于拿草稿当依据。 写错状态档时 clean_match 退回「只认走完的单」而不是「全部都算」——认不准时退回安全的那一边。
  3. 匹配条件在内存里筛,而且只在最近 300 单里筛(SCAN_LIMIT)。work.data 是 JSON 列, MySQL 在不同版本上把字符串 "1200" 与数字 1200 比大小的口径并不一致,与其赌一个隐式转换, 不如把候选量卡住之后自己比;候选够不够,设计器一句话说得清。
  4. 一条源最多 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:流程数据通道、两级选流程、字段能力口径)