20 KiB
想要什么值就查什么值:把 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)
- 入参绑定:值走 DBAPI 参数,永远不进语句文本。这条不是"更安全一点", 是把注入这一整类问题从设计上删掉。
- 独立连接池(2 + 3 条,可用
[data_source.sql] dsn换成只读账号): 一条没写WHERE的大表扫描只堵自己这几条连接,不会把主池占满—— 主池满了炸的是整个平台点不开,那才是事故。 - 只读事务:
SET SESSION TRANSACTION READ ONLY,写完的语句即使漏过静态闸也会被数据库拒绝。 (设完先回滚一次:READ ONLY管的是之后的事务,而 SQLAlchemy 会替第一条语句顺手开一个。) - 语句超时:
SET SESSION MAX_EXECUTION_TIME,用的就是这张数据源上的「超时秒数」 (那一格非空且默认 5 秒,所以只有它一个说了算)。 - 行数上限:只
fetchmany(MAX_ROWS + 1)(200 行,写在代码里),多那一行只为了能说"被截断了"。 截断这句话记进留痕、并显示在测试连通的结果里,但不塞进error——error非空在界面上是红的,拿它当失败判据的调用方有的是。 - 留痕与授权:
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. 边界:说清楚没做什么
- 只查一个库:本平台的库,或
sql_dsn指定的那一个。跨库、跨实例属于接口那条通道该干的活, 别用 SQL 通道硬凑一个 dblink 出来。 - 不能往外写:
direction=out直接拒。写回是 outbound-integration-design.md 那一摊(模板、发件箱、重试、成功判定),一条 SELECT 替代不了它。 - 不碰
auto那 12 个 key:见 §1 末。它们该管发起人相关,且要能塑形成登录账号 / 部门路径。 - 不做结果集控件:明细表仍然不能整表由一条 SQL 填。那是"一次查一批、每行装进一格"
的新形态,有了需求再设计,别在带出这一格里塞个表格编辑器。
2026-11 补的是另一件事:明细列可以逐行取数(列上挂
fetch,一行一调, 见 form-data-integration-design.md §9.2)。两者不是一回事—— 前者是"一条查询生出 N 行",后者是"已有的 N 行各自去问一次",边界照旧划在行的增减由人决定 这一句上:取数只往已经在表里的那些行上写值,不替你新增行、也不删行。 - 前端那份入参识别只是提示:
utils/sqlParams.ts认:name只为边写边提醒, 保存与执行都以后端sqlsource.mask那份为准;判例两边对着写,漂了测试就红。 - 金额列转 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 秒被数据库掐断,界面上拿到的是「跑得太久被掐断」那句人话,全局没有第二处超时要猜 |