unis-oa/docs/sql-autofill-design.md

20 KiB
Raw Permalink Blame History

想要什么值就查什么值:把 SQL 加成取数注册表的第四条通道

相关:form-data-integration-design.md(五种取数形态与七件杂事)、 data-binding-unification-design.md(取数内核只此一份)、 option-source-design.md(候选来源)、quota-control-design.md(额度吃取数)。

这一篇回答的是那句反馈:「表单的自动带出只有那固定的几个值,我想自己配 SQL。」 结论是给取数注册表加一条 provider=sql 通道,而不是在 auto 那一格里再开一个能写 SQL 的口子。

0. 一页看完

问题 结论
「自动带出」那几项到底是什么 service/autofill.py 里 12 个写死的 key(发起人、工号、部门、部门负责人、直属上级、流程名、单号、日期时间 + 环节名/处理人)。它们要的不是"查一个数",而是发起那一刻按发起人算一次并落进 work.data,其中选人/部门两类还要塑形成登录账号与部门路径
为什么只有这几个 不是因为只能做这几个,是因为每一个都得在 Python 里写一段取数逻辑。加第 13 个 = 改代码 + 发版,配置的人说了不算
值在自己库里、又没有接口的情况 以前只能等研发加一个接口,或者把值手填进去。这是这次反馈的真痛点
怎么改 给取数注册表(oa_data_source)加第四条取数通道 provider=sql:管理员写一条只读 SELECT,入参写 :name 绑定,其余(解析规则、带出去向、缓存、限流、留痕、调用权限)与调外部接口共用同一套
表单上要改什么 一个字都不用改存储结构:值型 SQL 源就是「外部取数」下拉里多出来的一张源;「自动带出」面板旁边加了同一个入口,配下去写的还是字段上那份 fetch
为什么不在 auto 里写 SQL auto 没有入参、没有失败策略、没有留痕,也回答不了「取不到数要不要挡人」。这四件正是取数注册表已经做完的事。同一件事不该有两套配置口径——与那篇「不合并那两格,合并它们底下那一层」是同一个判断
最危险的地方 这条通道读的是本平台自己的库。所以闸写在两处:保存前的静态判据(只许一条 SELECT、禁 DML/DDL/文件与时间函数、禁系统库、入参只能绑定)+ 执行时的独立连接池 / 只读事务 / 语句超时 / 行数上限。闸是拦错,只读事务是拦坏
默认开不开 不默认开。总开关只认配置文件 [data_source.sql] enabled(默认 false)与环境变量 OA_SQL_ENABLED,改完重启;界面上没有这一栏,这条通道读的是本库,开不开该由部署的人决定一次
老表单 零影响。四条通道共用 fetch.run,SQL 只是新分支;schema.sql 多一列 oa_data_source.sql_text

1. 先分清楚:那 12 个值与「我想要的那个值」不是一类东西

auto 那一格(以及普通字段上那份 auto)解决的是发起人是谁,判据很清楚:

系统值 auto 我想要带出的那个值
值住在哪 组织库 + 本次发起的上下文(work / actor) 某张业务表:成本中心、预算科目、汇率表、公司抬头、仓库主数据……
什么时候算 发起时算一次,落进 work.data 之后不再变 填单过程中就要看见,而且依赖格一变该跟着变
要不要入参 不要,永远是"当前这个人 / 这一张单" 十有八九要:按工号查、按成本中心查、按项目号查
取不到怎么办 格子空着,界面上写「提交后由系统自动填写」 得说清是等一下还是挡住提交(余额取不到就别放这张单)
要不要留痕 不需要,值是自己算的 需要:审批人问「这个余额哪来的」要能答

后四行全是取数注册表已经做完的事(form-data-integration-design.md §5、§8)。 所以"能配 SQL"不该变成 auto 的第二套取值口径,而应该是注册表多一条通道: auto 继续管"发起人相关",fetch 继续管"值从别处来",别处多了一个叫"本库某张表"的地方。

顺带说清一件没做的事:没给 auto 开自定义 key。看着更省事(下拉里直接多一组), 但那条路要么把入参、失败策略、留痕这三件事在 autofill.py 里再做一遍, 要么配出来一个"只能查常量"的半吊子。两样都不如直接用 fetch。

2. 一条 SQL 数据源长什么样

provider=sql 只多两样东西:那条查询本体,和它读表单哪几格。其余配置项与 http 通道同义。

-- 数据源:按成本中心带出余额与负责人(kind=fetch)
SELECT amount          AS balance,
       owner_name       AS owner,
       cost_center_name AS name
FROM   erp_cost_center
WHERE  cost_center_code = :costCenter
  AND  fiscal_year      = :year
配在哪 填什么 与 http 通道的对应关系
查询语句 一条 SELECT(或 WITH … SELECT),入参写 :costCenter 取代 method / url / headers / 密钥那一摊
入参 键名 costCenter,取值写 {form.costCenter}(那一格是选人控件就写 {account:form.costCenter}) 就是原来那份请求体模板 body_template,{form.x} / {account:form.x} / {auto:today:YYYY} 同一套写法
取值路径 列名 balance 原来是响应里的点路径 data.balance
可带出的键 owner → owner、name → name 原来 map_extra 指 data.owner,这里指同一行的另一列
列表节点 固定 rows(界面上锁死,不用手打) 原来是 data.rows
值 / 显示名 两个列名 原来是响应项里的两个键名

2.1 入参那一格是选人控件:先换成登录账号,SQL 才写得简单

type: user 那一格存的是登录账号的数组,和挂在账号上的那些东西 (oa_bank_account 的收款账户、财务导出的模板、上游系统里的员工编码)天生同一口径, where account = :applicant 一句就问得出来(为什么那一格存账号,见 person-reference-design.md)。以前那一格存的是身份 DN 数组, 而 DN 末段未必是账号:Hub 改过登录名的人末段还停在改之前那个,界面上手工建的号末段 干脆就是姓名——于是那句最自然的 SQL 永远查不到东西,而报回来的只是"没查到数据"。

翻译那一层留着,服务的是别人写进来的值:开放接口、找人脚本、数据源套数据源, 手上那串未必已经是账号。写法是在入参那一栏把取值写成 {account:form.申请人}, 后端按人员表把它换成登录账号再绑进 SQL(实现是 org.person_account,取数组头一个; 已经是账号的值原样通过,所以套几层都不会坏;认不出来给空串,宁可说"没查到"也不按姓名猜—— 拿错别人的收款账号比查不到人严重得多)。身份 DN 换不出账号,它不是引用口径。 于是那条查收款账户的源就退回一行谁都能读的写法:

select account, bank_name, pay_account
from oa_bank_account
where account = :applicant
要什么 入参怎么写 SQL 里就比什么
登录账号(选人那一格、以及一切本库数据) {account:form.申请人} where account = :applicant
同一格裸写(选人那一格) {form.申请人} 不行:交出来的是账号数组,绑不进 = 见下面那张口径表第一行
发起人工号(不看申请人这一格) {auto:creatorAccount} where account = :applicant

选人字段当入参一律包一层 {account:…},三处一起兜住这句话(一条真实故障:费用表单 「带出银行信息」的入参写的是 {form:applicant},运行时永远 blocked,而填单的人只看得见 "没查到数据"):

在哪一档 做了什么 位置
设计器(字段的外部取数 / 候选来源) 选中 SQL 源之后,取选人字段原值的入参当场出一句黄字,右边一个「改成认账号」按钮直接写成 {account:form.x};换源时按同名猜的默认写法也顺手包好壳 components/oa/design/SourceBindingEditor.vue
保存表单定义 同一条判据进校验,配错存不下去;只对真带 SQL 的那张源说——接口那条通道报文里放数组是正当写法 service/binding.py::bare_person_refs / arg_ref_problems(person_keys=…)
运行时 数组进 SQL 通道在查库前挡住,并点名该改成哪一格 service/fetch.py::_run_sql

{account:form.x} 浏览器算得出来(那一格存的就是账号,取头一个就是后端要用的那一个, 见 utils/binding.ts::accountFromCell),所以翻译这一层写在这两档里任何一档都即时带值: 数据源那一栏由后端渲染,字段那一档浏览器自己算完再发请求。以前它是"本地算不出来"的一员 (那一层要查身份表才能从 DN 里翻出账号),认到就整格跳过预取——DN 换成账号之后这一支 成了纯形状换算,跳过预取反而让配了认账号的取数在填单页不带值。只有 {account:work.x} 和句子里嵌着的 {account:…} 仍然交后端算。

几条把话说破的口径(都出自这一次排查,写下来省得再猜一遍):

现象 说的那句话
入参送进来是个数组/对象 查库之前就挡住,并点名这一栏该改成 {account:form.那一格}
同上,配置期 同一句话在设计器与保存校验里先说一遍(只对 SQL 源),不必等到填单页撞一条 blocked
入参翻译成了空 / 那一格没填 两种空分开说:等一等就好,还是等多久都没用
查回来一行都没有 把真正绑进去的值回显在这句话里(入参 "…"),一眼看出是不是自己以为的那个形状
取值型源查回好几行 照旧用第一行,但当场说明"只用了第一行",别让人以为取的是他刚选的那个人
候选型忘了填列表节点 SQL 通道的响应形状是自己拼的({"rows": […]}),没填就按它走

响应形状刻意贴着 http 通道,为的是 fetch.parse 一行都不用改: kind=fetch 的响应就是查出来的那一行(列名 → 值),kind=search 的响应是 {"rows": [行…]}。 于是"测试连通"的原始响应、sample_paths 那份点路径清单、presets.suggest 的 "照样例反推解析规则"三件在 SQL 通道上全都照常工作——配上 SQL 点一次测试, 取值路径与带出的键直接从样例里挑,不用手打列名。

3. 安全:两道闸,各管各的

这条通道读的是本库,配它的人有 design:datasource 权限——他本来就能配"往 ERP 发什么报文"。 信任不是问题,手滑才是。所以两道闸分工明确:静态闸拦写错的,只读事务拦想坏的。

3.1 静态闸(sqlsource.problems:保存时、发起时、设计期三处同一份)

先掩码再扫词:注释、字符串字面量、反引号标识符换成替身。这一步不是讲究,是省事—— 直接在原文上扫 update,SELECT update_time 就成了改数据、WHERE remark = 'delete' 就成了删数据; 误伤一多,配置的人就学会绕检查,那道闸等于没有。

挡什么 判据
多条语句 末尾分号之外还有分号
不是查询 必须以 SELECT / WITH 开头
写与改 INSERT / UPDATE / DELETE / REPLACE INTO / CREATE / ALTER / DROP / TRUNCATE / RENAME / GRANT / REVOKE / SET / COMMIT / ROLLBACK / SAVEPOINT / LOCK / KILL / SHUTDOWN / CALL / EXECUTE / PREPARE / HANDLER / LOAD / INTO
读文件与拖时间 OUTFILE / DUMPFILE / LOAD_FILE / SLEEP / BENCHMARK / UPDATEXML / EXTRACTVALUE / pg_* / dblink
系统库 information_schema. / mysql. / performance_schema. / sys.,任何时候都不给
拼字符串 ${…} / %s / %(x)s / {{…}} 一律报错:入参只能写 :name
入参悬空 SQL 用了 :x 而入参清单没有这一行 → 保存就挡(填单页面压根不会收集它,值永远是空)

3.2 运行时闸(sqlsource.run)

  1. 入参绑定:值走 DBAPI 参数,永远不进语句文本。这条不是"更安全一点", 是把注入这一整类问题从设计上删掉。
  2. 独立连接池(2 + 3 条,可用 [data_source.sql] dsn 换成只读账号): 一条没写 WHERE 的大表扫描只堵自己这几条连接,不会把主池占满—— 主池满了炸的是整个平台点不开,那才是事故。
  3. 只读事务:SET SESSION TRANSACTION READ ONLY,写完的语句即使漏过静态闸也会被数据库拒绝。 (设完先回滚一次:READ ONLY 管的是之后的事务,而 SQLAlchemy 会替第一条语句顺手开一个。)
  4. 语句超时:SET SESSION MAX_EXECUTION_TIME,用的就是这张数据源上的「超时秒数」 (那一格非空且默认 5 秒,所以只有它一个说了算)。
  5. 行数上限:只 fetchmany(MAX_ROWS + 1)(200 行,写在代码里),多那一行只为了能说"被截断了"。 截断这句话记进留痕、并显示在测试连通的结果里,但不塞进 error—— error 非空在界面上是红的,拿它当失败判据的调用方有的是。
  6. 留痕与授权:oa_data_source_log 照记(入参、耗时、成败、截断说明), min_permission 照挡人。SQL 通道失败不计入熔断:那多半是配置写歪了,库好得很, 与 http 通道那条「4xx 不拉闸」是同一分寸。

红线仍然一句没改:外部回来的值只能提供值,不能决定流转。SQL 取回的值落的还是 work.data, 条件分支读的还是 work.data;提交时后端按同一份配置再取一次并覆盖,在浏览器里改这一格挡不住任何校验。 另外与 ai-data-query-mcp-plan.md 那条「不给模型生成 SQL」不冲突: 这里的 SQL 是人在配置页里写的,模型生成物任何时候都不许进这条通道。

4. 配置的人在哪里做这些事

他要干什么 在哪儿
打开这条通道 / 换只读账号 部署侧:配置文件 [data_source.sql] 或环境变量 OA_SQL_ENABLED / OA_SQL_DSN,改完重启。界面上没有这一栏——这一条读的是本库,开不开由部署的人决定一次;配 SQL 的人从保存被挡那句提示里就知道该找谁
调一次取多少行、跑多久 行数写死 200(超出在留痕里写明被截断);超时用这张数据源自己的「超时秒数」,跟调外部接口时改的是同一格
写查询、看它要哪几个入参 「连接方式」那一栏选「查数据库(SQL)」:语句写在大框里,下面实时列出 :costCenter 这些入参各自配好没有
声明入参读表单哪一格 「入参」那一栏,与请求体模板同一张表
挑哪一列当值、哪几列还能带进别的格子 「解析规则」:点「测试连通」→ 从样例点进去(与调外部接口一模一样的动作)
表单上挑它 两个入口:字段检视器的「自动带出」旁边多一档「用 SQL 带出」(只列已启用的取值型 SQL 源,选完顺手锁成只读);以及原来的「外部取数」面板。两处改的是同一份 field.fetch
要按另一格的值去查 「自动带出」那一档列出所有已启用的取值型 SQL 源,带 :入参 的当场提醒「到下面「外部取数」里点明它读哪一格」——入参得在那一栏加行才能配取值写法

这一条通道不在界面上开配置面:它读的是本库,开不开属于"部署的人决定一次"的事, 放在配置文件里比放在页面上少一个人有可能顺手点开。省下来的那一栏也没有真的消失—— 保存被挡与取数被挡说的是同一句话,句子里写清了去哪儿开、找谁开。

5. 一条通道配好,六个地方跟着能用

因为落点是注册表而不是某个面板,provider=sql 一进去,吃这张表的全都跟着多一种来源:

用在哪 配法 效果
字段带出 fetch 指向 SQL 源 填单时取一次给看,提交时后端再取一次并覆盖;revalidateAfter 到点自动重取、freezeAfterStart 发起后不再改(见 form-data-integration-design.md §9.1)
明细列逐行带出 列上那份 fetch 指向 SQL 源 一行查一次:入参读「整张单 + 这一行」,值与 picks 只落在这张表的列上(§6 第 4 条;口径见 form-data-integration-design.md §9.2)。SQL 通道 200 行上限在这里几乎用不上——每行本来就只要一行
一行带多格 同一行的其它列填进 map_extra + picks 选成本中心,余额、负责人、科目名一起落进各自的格子
多源合成 一格挂几个源(sources + merge) ERP 接口 + 本库 SQL 两张源凑一个值:first / sum / min / max / join
候选下拉 kind=search 的 SQL 源 大列表下拉直接查库搜:LIKE CONCAT('%', :keyword, '%'),:keyword 由搜索框给,不用配入参
字典选项 字典绑这张源 全量同步、级联、带出、翻名照旧(dicts.sync 吃的就是 fetch.run)
额度台账 / 阈值右值 额度源与阈值指向那张带出字段 「按台账判超支」的台账可以是本库一张表

6. 边界:说清楚没做什么

  1. 只查一个库:本平台的库,或 sql_dsn 指定的那一个。跨库、跨实例属于接口那条通道该干的活, 别用 SQL 通道硬凑一个 dblink 出来。
  2. 不能往外写:direction=out 直接拒。写回是 outbound-integration-design.md 那一摊(模板、发件箱、重试、成功判定),一条 SELECT 替代不了它。
  3. 不碰 auto 那 12 个 key:见 §1 末。它们该管发起人相关,且要能塑形成登录账号 / 部门路径。
  4. 不做结果集控件:明细表仍然不能整表由一条 SQL 填。那是"一次查一批、每行装进一格" 的新形态,有了需求再设计,别在带出这一格里塞个表格编辑器。 2026-11 补的是另一件事:明细列可以逐行取数(列上挂 fetch,一行一调, 见 form-data-integration-design.md §9.2)。两者不是一回事—— 前者是"一条查询生出 N 行",后者是"已有的 N 行各自去问一次",边界照旧划在行的增减由人决定 这一句上:取数只往已经在表里的那些行上写值,不替你新增行、也不删行。
  5. 前端那份入参识别只是提示:utils/sqlParams.ts 认 :name 只为边写边提醒, 保存与执行都以后端 sqlsource.mask 那份为准;判例两边对着写,漂了测试就红。
  6. 金额列转 float:Decimal 进不了 JSON 与留痕那一列,与 work.data 一直是 float 元同口径。

7. 验收

# 场景 期望
A 一条 SQL 带出值与另一列 fetch.run 回 value + extras,填单页显示,提交时后端重取覆盖
B kind=search 带 :keyword 候选按关键词查出来;:keyword 不配入参也算已配
C 查不到行 「这条 SQL 这次没查到数据(入参对了没有?)」,按字段 onError 决定挡不挡
D 写 DELETE … / 多条语句 / information_schema / ${x} 保存时、发起时、设计期三处同一句话挡下
E 绕过静态闸直接往只读事务里写 数据库拒绝(错误 1792),库里一个字节都没变
F 慢查询到超时 语句被数据库掐断,界面拿到一句人话
G 结果超过 200 行 只取前 200 行,留痕与测试结果里写明被截断,ok 仍是真
H 总开关关着(默认就是关着) 保存与执行都拒绝,并说清去哪儿开、找谁开
I 数据源上把超时填成 2 秒 第 2 秒被数据库掐断,界面上拿到的是「跑得太久被掐断」那句人话,全局没有第二处超时要猜