unis-oa/docs/external-data-simplificatio...

27 KiB
Raw Permalink Blame History

外部数据源配置简化 + 字典选项来自外部系统

上游总设计:form-data-integration-design.md(五种取数形态) 与 outbound-integration-design.md(L1/L2/L3 三层)。 这一篇只讲两件事:配置为什么麻烦、砍成了什么样,以及 字典怎么吃外部系统的选项。

0. 一页看完

问题 结论
麻烦在哪 一张数据源 28 个可配字段、5 个分页;超时/重试/缓存/限流/静默这五个数字每个新源都要重新回忆一遍;pick、items_path、map_extra 要人手打 data.rows.0.balance 这种字符串
默认值有几份 改之前有三份(schemas.DataSourceBody、models.DataSource、DataSourceView.vue 的 resetForm),改一处漏两处,新配的源和半年前配的源行为悄悄分叉
怎么砍 ① 五个数字打包成可靠性画像(实时数值 / 主数据 / 慢接口 / 上游很脆);② 贴一段真实响应反推解析配置;③ 用不上的分页按方向收起,路径改成点选;④ 请求头与入参不再写 JSON 串,改成一张一行一条的表格(见 §1.4)
默认值放哪 只有 service/presets.py 一份,GET /design/data-sources/presets 回给界面,前端不再抄
必填星号 pick 与 items_path 不再必填:留空 = 响应本身就是它。取不到时由执行器说清该填什么,而不是逼人在没见过响应之前先猜一个 data.xxx
字典吃外部数据 oa_dict_type 加选项来源:手工维护 / 外部数据源。选后者就绑一张列表型数据源,把上游列表同步进 oa_dict_item
为什么是同步而不是实时 落到已有那张表,级联、字典项附加值带出、提交时的选项校验、导出、标题翻译一行都不用改;上游挂了表单照样打得开,选项停在最后一次同步那份
什么时候同步 保存外部来源的字典时同步一次;之后由「打开表单取选项」这条路顺手刷新,间隔 = 数据源上的缓存秒数(不低于 60 秒);页面上还有一个手动「同步」
撤项怎么处理 上游这次没返回的项停用而不是删掉——历史单据上那个值还要靠它显示名字
条数上限 一次同步最多 5000 项。再多说明这件事本质是「几万条里搜一条」,该用数据源的下拉搜索而不是字典

1. 配置简化:三刀

1.1 五个数字 → 一个画像

service/presets.py 里的 RELIABILITY 是唯一的默认值来源,四档画像各自带着 timeout_seconds / retries / cache_seconds / rate_limit_qpm / cooldown_seconds:

画像 用在什么接口 超时 重试 缓存 每分钟 静默
realtime 余额、库存(每次都要最新) 5 1 0 不限 60
master 成本中心、物料、组织(一天变不了几次) 8 1 300 不限 300
slow 报表、批量查询 20 0 60 60 300
guarded 上游很脆,宁可慢也别打挂 5 0 60 30 180

界面是一组卡片而不是五个输入框,五个数字收在「高级」里照旧可改。反向识别当前 数字属于哪个画像(utils/dsPreset.ts 的 reliabilityKey)而不是记住"人选过哪个"—— 从库里读出来的老源没有画像这个字段,数字对得上就认,对不上就老实显示自定义。

ENVELOPES 同理:code/data/message、code=200、success 布尔位、裸 JSON 四种外壳, 点一下填好成功判定与错误信息位置。

1.2 贴一段响应 → 解析配置自己长出来

presets.suggest(payload, kind) 把一份真实响应翻成能直接用的配置:

  • 先认外壳(detect_envelope),认出来就顺手给出 success_path / success_value / message_path 与正文所在层(data / result …);
  • 列表型:深度优先找对象数组当 items_path(常见键名 rows/list/items/records/… 排在前面), 再在第一项里挑 map_value(value/id/code/no/…,认不出精确名就按 code、id 这类片段 loose 对) 和 map_label(label/name/text/…),剩下的标量列变成 map_extra(最多 6 个);
  • 取值型:把所有标量叶子按"像不像要取的那个值"打分(balance/amount/count/… 靠前,越浅越靠前), 第一个当 pick,其余回成候选给人点。

一条规矩:认不出就留空,不猜一个"看着配好、实际取不到数"的配置出来——那种错要到 填单页面才暴露,比配不全难查得多。两个入口:

  • POST /design/data-sources/suggest:贴上游文档里那段 JSON(上游还没开发时就用这条);
  • preview() 的返回值里多带一份 suggestions:拉取样例的这一刻顺手反推,界面上一个按钮贴上去。

1.2.1 新建就自带一份样例

反推再好用的前提是框里得有一段响应。以前新建一张源时那个框是空的,而「解析」那几栏 (取值路径 / 列表节点 / 可带出键)全得照着响应写——于是人得先凭空想象出一棵 JSON 树, 这张配置页"看不懂"的账大半记在这里。现在新建那一刻就摆一份形状正确的样例进去:

  • 样例本体在 presets.py 的 SAMPLES,键是 通道:类型,GET …/presets 一并回给界面—— 与可靠性画像、默认值同一处,界面不自己抄一份;
  • 四条通道四份形状:SQL 的响应就是查出来的那一行(所以样例就是一行列名, 不是 data.rows.0.x 那种),流程通道固定套 work / data 壳, 列表型给 data.rows 两行;换类型 / 换通道时那份没人动过的样例跟着换, 人贴过真实返回就留着他的,不盖;
  • 框下面一句话说清"这是自带样例",换成真实返回或点过「拉取样例」那句话就消失—— 假样例离「照样例填好」只有一颗按钮,得让人知道自己在拿什么反推;
  • 编辑已存在的源不摆:那份假样例一旦贴上去,一键就能把真源的取值路径改掉。 前端另存一份 http 两档同形状兜底,预设接口没起来时也不给空框。

1.3 用不上的格子不要出现

  • 方向是「只取数」时不再显示「写回判定」分页(那四个格子对入站取数毫无意义, 过去多数人随手填一个,反倒把错的成功判定写了进去);
  • pick / items_path 的必填星号摘掉(见 §0);
  • 样例通道的响应体直接当反推的输入,不用再贴一遍。

往外写的源同样收起取数那一栏(2026-10-21 补),判据不是"看着用不用得上", 而是执行器到底读不读它:outbox.send 只读数据源上的 headers、鉴权、超时、 success_path / success_value / message_path / ref_path 与 url + method, body_template 与 pick / items_path / map_extra 一次都不看——出站报文由写回模板 (L2 的 payload.fields)渲染。于是:

分页 方向=往外写时 为什么
解析 整页收掉 那一页管的是"值在响应哪一格",往外写的源没有这件事;成功与否在「写回判定」判
入参 留着,但开场白改成"这几行不进真报文,只给本页的「测试连通」用" 执行器不读它,而 fetch.preview(测试连通)读;直接收掉会让人以为连测试都配不了
写回判定 出现(direction !== in) 与「只取数收掉写回判定」是同一条规矩的两半

顺带三处:往外写的源开着影子模式时「测试连通」也不外呼(fetch.run 挡住并说明, 与 outbox.send 同一个口径),否则"上游还没就绪、先配着"的那一次点测试就在生产落了张真单据; 测试弹窗里对往外写的源先把"这一次会真的调用写接口"说在前面;direction=out 的源不再能被 表单当取数来源——binding.source_problem 原来只挡候选那一支,取一个值那一支照样能配上, 现在一句都挡,并指路"把方向改成「双向」"。

1.4 入参与请求头:像调接口那样填表格

固定请求头原来是一格 JSON 文本域,入参那页是自己拼的三列输入框。两种写法有个共同的坑: 要等保存了、后端解析了,才知道写错了——少一个引号、Authorization 写了两遍、 只有值没填名字,全都是这么一路混进库里的。现在三处(固定请求头 / 入参 / 可带出键) 都用同一张表格 components/oa/design/ParamTable.vue,形状照着 Postman 那张参数表来:

表格里多出来的东西 为什么要有
每行一个勾选框 排查时想临时不发某个入参,勾掉就行;行还留着,不用删了再凭记忆加回来
备注列 「这个入参上游要的是成本中心编码,不是名称」这句话以前只能贴在群里
末行永远是空的 敲完一行直接往下写,不用每行都去够一次「加一行」
当场标出来的问题 重复键(请求头还不分大小写)、只有值没名字、空值、以及会被「鉴权方式」覆盖掉的 Authorization——都在那一行下面说,不给它留到后端
常用请求头 / 批量编辑 点一下加一行,省去手敲大小写;要一次贴进来十条就切文本模式,写成 名: 值(行首 # 表示先停用),不用拼 JSON 括号
报文预览 入参页下面直接把 POST 地址 + 请求头 + 请求体 摆出来,改一行就跟着变,配完不用再点一次测试才看见

存的还是原来那三份对象,执行器一行都没改:headers / bodyTemplate / mapExtra 照旧是发给上游的东西,表格比它们多出来的两样(备注、被停用的行)单独记在 oa_data_source.param_meta 里,只有配置界面看得懂。停用的行根本不写进那三份对象, 所以"不勾就不会发出去"这件事不需要后端配合。取值那一格整段写成合法 JSON ({"page": {"size": 10}})就按结构存,上游那种嵌套请求体也能配——老写法会把这种值 String() 成 [object Object],打开再保存一次就毁了,顺手修掉。

JSON 文本域只留在它本来就该是报文的地方(样例响应、贴一段响应反推), 但补了即时校验与「排一下格式」,至少不用猜是少了个引号还是逗号。

1.5 地址上也能带参数:{arg.x} 走的是同一张入参表

上一节把入参与请求头收成表格之后,还剩一类接口配不出来:参数不写在请求体里,写在地址上。 报销那个服务就是典型:

GET https://reimb.example.com/api/reimbursements/oa/by-flow-number?oa_flow_number=FYBX202610260014

单号是每张单都不一样的值,地址就成了"拼出来"的那一条。2026-10-27 起,provider=http 那条通道上 地址与请求体同源:{arg.x} / {form.x} / {auto:today} / {work:serial} 四种写法照旧 (口径在 service/binding.py),只是换进去的每一个值都过一遍 URL 编码 (service/fetch.py:render_url)。于是这一条就是配得上的一条源:

格子 填什么
方法 GET
接口地址 https://reimb.example.com/api/reimbursements/oa/by-flow-number?oa_flow_number={arg.processNo}
入参 processNo ← {form.流程编号}(这一格取哪一栏的值)
取值路径 对面响应里那个值的位置,如 data.amount;值在明细列表里就写 data.items[字段=值].amount(§1.6)

四件事一起说清:

  • 编码是这一条的全部难度:值里一个 & 会凭空多带出一个参数,一个 # 把后半截吃成锚点, 一个中文或空格就是一句非法 URL。编码之后拼在路径段上(/by-flow-number/{arg.processNo}) 也是同一条规矩,不用为"参数在路径里"再配第二套。
  • 入参表是唯一那份来源:地址上的 {arg.processNo} 读的就是入参表里那一行,所以"这一格取哪一栏" 仍然只在表单上那一格配,同一条源给两个字段用没问题。没填就先不外呼——binding.missing_args 现在连地址一起看,挡下来的话点名是哪个入参空着。
  • 缓存键认地址:?no={work:serial} 这一类值根本不落在入参表里,不进键就是全公司的单据共用一份缓存, 第二张单拿到第一张单的余额。写死的地址换前换后一模一样,键不动,存量缓存不作废。
  • 只有取数这一条通道:往外写(direction=out)的真报文由「集成写回」模板渲染, 那里的 {...} 在模板的「路径」格里照旧不替换(mapping.url_for 拼原字符串), 两句不冲突,见 node-writeback-config.md §12。

1.6 明细列表里按字段挑一行(2026-10-27 补)

对面把明细装进列表是常态。报销那张单回的就是这个形状:

{"code": 0, "data": {"expense_items": [
  {"category_name": "其它",   "amount": 5643.84, "invoice_count": 1},
  {"category_name": "差旅费", "amount": 120.0,  "invoice_count": 2}]}}

而同一张单上差旅被拆成了三条(差旅费(含高铁、机票)/ 差旅费-住宿费 / 差旅费-出差补贴), 表单上只要一个「差旅合计」:

data.expense_items[category_name^=差旅费].sum(amount)

^= 认开头,三条一起进来;sum(amount) 把筛剩下的行加成一个数。要平均就写 avg(amount), 要行数就写 count()(数行不用列名,count(列) 数的是那一列有值的行)。 筛空了时 sum 回的是取不到而不是 0——类目名打错的人看见 0 会以为"这单就是 0 元", 看见报错才知道自己筛空了;count() 是唯一的例外,0 行本身就是那句答案。 金额按 Decimal 加,三条加起来是 400.5 不是 400.49999999999998;上游把金额写成 "1,200.00" 这种带千分位的字符串也算数,null 与文本不算,true 也不算(不会当成 1 混进钱里)。

而只要其中「差旅费那一行的金额」时,以前取值路径只认点号与下标,能写的只有 data.expense_items.0.amount——永远拿第一行,而"第一行恰好是不是那一行"没人担保。 现在多一种段:

data.expense_items[category_name=差旅费].amount
写法 意思
data.items[字段=值].列 筛出 字段 等于 值 的行,取第一条匹配行的那一列
data.items[字段=值] 筛完仍是列表,所以「列表节点」也能这么写(候选下拉只留那些行)
data.items[字段=值][1].列 要第 2 条匹配行就自己写下标
data.items[amount>5000].列 也能比大小:> >= < <= != 与 = 同一套写法
data.items[字段^=前缀].列 只认开头:[category_name^=差旅费] 同时罩住差旅费-住宿费、差旅费-出差补贴
data.items[字段~=一段].列 只认包含:[description~=机票]
data.items.sum(列) / 明细[…].sum(列) 把剩下的那些行算成一个数:sum avg max min count
data.items.0.列 / data.items[0].列 老写法一个字不变:固定取第一行
data.items.amount 仍算配错:没筛没下标就不悄悄拿第一行,宁可明说取不到

比大小、认开头、认包含、算成一个数都不是另一套东西:明细列表里"取等于某个值的那一行"、 "取超过某个数的那一行"、"把同族那几行算成一笔"是同一句话的几种写法, 分几套语法只会让人先去翻文档。> >= < <= 两边都能读成数字就按数字比 ("5643.84" 与 5643.84 必须是同一个数),读不成数字按文本比,2026-10-01 这一类定长日期串 正好吃字典序;取不到键与 null 不参与比大小(不会被当成 0)。!= 用的就是 = 那条判据取反, 所以 remark!= 筛的是非空行。

四条口径值得写下来,因为每一条都是配的人凭感觉猜不到的地方:值两边都能读成数字就按数字比 (amount=5643.84 对得上游的小数、invoice_count=2 对得上整型),否则去掉首尾空格按文本比, remark= 筛的是空值那一行;中括号里的点不切开(金额与日期恰是最常被拿去筛的两类值, [amount=5643.84] 里那个点属于值本身);筛不到时那句错误带得上「这一列现有的是哪几个值」 (按 category_name=交通费 没筛到行,现有的是其它、差旅费),因为配错的多半就是那个值, 比大小筛不到时同样报这一句;[字段=值] 只筛列表里的对象行,字典键名里真带等号({"a=b": 1}) 照旧当键名——筛选只在脚下是一份列表时生效。判据 service/fetch.py:pick_path (认运算符的是 parse_filter,认 sum(列) 的是 parse_aggregate, 界面在 utils/dsPreset.ts:pickFilter / pickAggregate 各有一份一模一样的), 验收 backend/scripts/check_pick_filter.py。

界面这一侧跟着补了三件事,都为同一句话服务:配取值路径的这一刻,手上正有一份真实响应。

  • 摊路径的深度从 4 放到 5:根 → data → 列表 → 第 0 行 → 那一列 正好五层, 以前列表点得开、行里那一列却一条都不出现,而"从明细里挑一个数"恰是最常见的用法;
  • 「解析」页在取值路径落到某份列表上时,把那份列表真有的那几个值列成可点的按钮 (后端 presets.row_filter 随反推回 listFilters),点一下就换成 明细[字段=值].列, 不用回去翻上游文档;人写的是比大小时按钮上跟着写 amount>5643.84,点下去只换那个数, 不会把 >5000 偷偷改成 =5000;
  • 反推挑中的主值正好在列表里时,直接给一条能照抄的筛选写法(pickFilter);
  • 同一片建议里还摆着 sum avg max min count 五颗小按钮,点一下就把 明细[字段=值].amount 换成 明细[字段=值].sum(amount),换算法不用回去把整句重写一遍。

「拉取样例」不再说假话(同一批改的):以前只要后端回了对象,界面就显示「已经拿到真实响应」, 而 suggestions 在什么都没认出来时回的就是 {}——JS 里 Boolean({}) === true。 于是点「照样例填好」什么都不填、也什么都不报,看起来像按钮坏了。判据换回唯一那句 result.ok:失败把 error 摊在这一栏,成功把按现在这份解析规则取到的那个值回显在这里, 一格都认不出来时给一句提示而不是静默。同批填掉的还有两记同源的坑:入参清单过去只看请求体, ?oa_flow_number={arg.processNo} 那一类接口于是一个入参都不发,后端当场判 「入参还是空的,本次没有外呼」(binding.missing_args 早把地址算进去了,前端没跟上)—— 现在「解析」页上能直接填这一次要发的入参值(留空仍按 test 发);以及草稿那一次测试过去 连一条调用留痕都不落(只有按编码测已保存的源才 commit),现在两种都落。

2. 字典的选项来自外部数据源

2.1 表结构

oa_dict_type 新增:source(manual / data_source)、source_code、 source_args(同步用的固定入参,写法同数据源请求体模板)、synced_at、 synced_count、sync_status、sync_message。synced_at 不论成败都更新—— 失败了也要有个间隔再试,不能每打开一张单就打一次上游。

2.2 同步(service/dicts.sync)

字典(选项来源=data_source) --source_code--> oa_data_source(kind=search)
                                                   │ fetch.run(缓存/限流/熔断/留痕照旧)
                                                   ▼
                                    items: [{value,label,extra}]
                                                   │ 按 value upsert
                                                   ▼
                                      oa_dict_item(顺序照上游,撤的置 enabled=false)

三条分寸:只增改不删(历史单据要能翻出名字);顺序照上游(少一层 "为什么页面顺序和 ERP 不一样");失败不留半成品(拉不到就一句话说明原因, 上一次同步的选项原样留着)。第四条是这一篇后面要单讲的:上游那份不是全部—— 人补的那一项同步一律不碰。

上游愿意给 parent 列时白捡一个层级字典:_from_remote 把 extra.parent 提到 oa_dict_item.parent,表单上的 cascadeFrom 直接能用。

source_args 存在的理由:同一个源常常要按年度、公司口径取列表,写法 {"year": "{auto:today:YYYY}"} 由 fetch.render 解析,与请求体模板同一门语言。

2.3 上游缺项时,人能在 OA 里补(oa_dict_item.source)

外部来源的字典原先一刀切:选项来自数据源就不许手改。可上游经常缺项——新物料还没录、 行政区域少一条、财务口径刚改——人只能等 IT 改数据源,或者干脆让业务同学在单子上手填 一个不在选项里的值(然后被提交校验挡下)。所以现在外部字典照样给「加字典项」和「导入」, 代价是同步只该动它自己写下来的那一份。

归属记在 oa_dict_item.source,判据只有一处(dicts.item_is_manual):

source 这一项是谁写下来的 外部字典里的待遇 手工字典里的待遇
manual 人在 OA 里加的 / 导入的 同步不覆盖、不停用、不改顺序、不改附加值 归人(这一格无所谓)
data_source 同步写下来的 照旧由同步维护 归人——这本再没有同步会盖它
空 分家之前就有 归上游:跑一次同步就补上 data_source 印记 归人

空串那一档是给老数据留的:以前外部字典压根不让人手工加项,所以老行只可能是同步写的, 交给上游才对得上历史单据;换成手工字典之后它们又全都归人,不会出现"这本已经没有同步了, 却不能改"。

于是同步的口径变成四条(apply_items,手动同步与开表单时的自动刷新共用):

  • 人补的那一项不碰:不覆盖、不停用、不按上游顺序挪走;上游这次也给了同一个取值时 不抢,只在报告里点一名(preserved「N 项已改为手工维护,同步没动它」),想并回上游那份由人点「交还」。
  • 停用只停上游那一项:上游撤了才停,人补的跟"上游撤没撤"没关系。
  • 上游那一项仍旧只读:改了活不过下一次同步,所以编辑/删除照样挡,但话要说清楚, 并且当场给一把「接手为手工维护」(POST /process/dict-items/{id}/own)。
  • 导入同样分主人:导进来的新行标 manual,撞上上游那一项原样放过(synced)。

字典列表上那本外部字典会标出「手工 N 项」,头部那行写「上游 N 项 · 手工补 M 项」—— 补进去的项混在上千条里时,谁也说不清它哪来的。

2.4 权限这一格怎么填

数据源上可以配 min_permission(谁能调这个源)。外部字典取选项时不再按调用人挡 (fetch.run(..., check_permission=False)):能把字典绑到这张源上的人已经决定了 "这份列表给全员看",再让源的门槛挡在普通员工面前,只会变成一个查不出原因的空白下拉。 调用照旧留痕、调用人照记。这条口子只开给"系统替全员调一次"这一种场合。

2.5 什么时候刷

时机 谁触发 说明
保存外部来源的字典 POST /process/dicts 配完当场就能看到选项,错也当场暴露
打开表单取选项 POST /process/dicts/values → ensure_fresh 间隔 = max(60, 源.cache_seconds);没到期一次都不打上游
页面上点「同步」 POST /process/dicts/{code}/sync dryRun=true 只拉不落库,给设计页预览用

3. 落在哪些文件

文件 干了什么
backend/app/service/presets.py 新增:默认值、画像、外壳、样例反推;SAMPLES 新建时自带的样例
backend/app/service/fetch.py preview 回 suggestions;run 多一个 check_permission;解析失败的话说清楚该填什么
backend/app/api/data_sources.py GET …/presets、POST …/suggest;删源时挡住"被字典当选项来源";usage 回字典引用
backend/app/service/dicts.py is_remote / source_of / remote_problem / apply_items / sync / ensure_fresh;归属一处判:item_source / item_is_manual / item_write_problem / set_item_source
backend/app/api/dicts.py 保存时校验来源;字典项按行挡(_guard_item);POST …/sync、POST /process/dict-items/{id}/own;批量取值先刷新
backend/app/models.py + sql/schema.sql oa_dict_type 那七列、oa_dict_item.source(快照同步更新);oa_data_source.param_meta 一列同上
frontend/src/utils/dsPreset.ts 画像反识别、「照样例填好」与自带样例的取法(带单测)
frontend/src/utils/paramRows.ts 新增:表格行 ↔ headers/bodyTemplate/mapExtra + paramMeta 的互转、批量文本、当场校验(带单测)
frontend/src/components/oa/design/ParamTable.vue 新增:请求头 / 入参 / 可带出键共用的参数表格(带单测)
frontend/src/views/oa/design/DataSourceView.vue 画像卡片、高级折叠、照样例填好、按方向收分页、新建自带样例(带组件测)
frontend/src/views/oa/design/DictListView.vue 选项来源、同步入参、同步/预览;外部来源时按行给操作(上游那项「接手」,人补的照常编辑删除 +「交还」),并标出来源与「上游 N 项 · 手工补 M 项」
backend/tests/oa_fetch.py 新增两节:预设与反推;字典选项来自数据源

4. 没做的与边界

  • 大列表(>5000 项)仍然走数据源的下拉搜索 /data-source/options,不塞进字典;
  • 同步是全量覆盖式 upsert,上游没有增量口径就别指望增量;
  • 定时任务(没人打开表单就一直不刷)留给 sync_minutes 那类需求出现时再加, 现在这条惰性刷新已经覆盖"总得有人开单"的多数场景;
  • 字典改成外部来源时,原本手工维护的字典项保留:那些行还没标归属(source 是空串), 第一次同步会把上游没有的那些置为停用;此后人补的项才受 §2.3 那套保护。 反过来换回手工字典时,所有项一律归人,不会再有同步来盖;
  • 参数表格只管平铺的键值:请求体要套几层,靠那一格写一段 JSON(或整个嵌套值), 不做 Postman 那种 tree 编辑器——真要维护复杂报文,那属于写回模板(L2)的范围;
  • GET 的查询参数仍然写在地址里(?a=1),没有单独一张 query 表格: 执行器只发 headers + 请求体,加一张表得先给执行器加发 query 的口径。