unis-oa/backend/app/service/binding.py

701 lines
34 KiB
Python
Raw Permalink Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

"""取数内核 -- 「从别处拿一个数」这件事只此一份口径。
字段上那些「值不在本系统里」的配置——外部取数 ``fetch``、候选来源 ``optionSource``
(字典 / 流程单据 / 外部数据源)、额度 ``quota``、阈值 ``threshold``、从另一个流程带数据
``provider=process``——本来就共用同一套取值写法、同一份多源清单形状、同一套
「这个源还在不在、停用没停用、类型对不对」的判据。过去这些各写各的:解析后端四份
(``fetch.render`` / ``quota.resolve_text`` / ``threshold.resolve`` / ``mapping`` 的 token 语言)、
前端五份,源的健康检查四套各说各话,于是"改一处漏两处"只能靠注释里那句「与后端同口径」防。
这一层把公共件收成一份(分层见 ``docs/data-binding-unification-design.md`` §4):
* **写法解析**:``{form.x}`` / ``{auto:...}`` / ``{work.x}`` / ``{const:...}`` / ``{arg.x}``;
* **多源清单与合并**:``entries`` / ``merge``;
* **源与引用的校验**:``source_problem`` / ``entry_problems`` / ``arg_ref_problems`` / ``live_target``。
**这一层不调外部系统、不查缓存、不写留痕**——那些是 ``service/fetch.py`` 的活。
它也不决定"取不到数要不要挡人":那属于角色(供给候选 / 供给值),不属于内核。
"""
from __future__ import annotations
import json
import re
from datetime import datetime
from typing import Any, Iterable
from .. import models
from . import autofill, org
# ---------------------------------------------------------------------------
# 取值写法
# ---------------------------------------------------------------------------
#: 取值只认这几种写法,其余一律当字面量(不重造模板语言:拼接与算术交给公式字段)。
#: 花括号里的空白都放过——``{form.x}`` 与 ``{ form.x }`` 是同一种意思,
#: 过去后端几种正则有的认有的不认,配的人只能靠试。
FORM_REF = re.compile(r"^\{\s*form:\s*([^}]+?)\s*\}$|^\{\s*form\.\s*([^}]+?)\s*\}$")
FORM_REF_ALL = re.compile(r"\{\s*form[.:]\s*([^}]+?)\s*\}")
AUTO_REF = re.compile(r"^\{\s*auto:\s*([^}:]+?)\s*(?::\s*([^}]+?)\s*)?\}$")
WORK_REF = re.compile(r"^\{\s*work:\s*([^}]+?)\s*\}$")
CONST_REF = re.compile(r"^\{\s*const:([\s\S]*)\}$")
#: ``{account:...}``:把选人字段那一格换成**一个登录账号**(多选取头一个)。
#: 为什么这一份只有它一个转换:``{cents:…}`` 那几支是格式,这一支是"形状"——选人字段
#: 存的永远是**数组**(``["zhangsan"]``),而 SQL 的 ``=`` 只能比标量,``oa_bank_account``、
#: 财务导出、上游系统认的都是 ``users.account``。这一层不让平台管,配 SQL 的人就只能自己
#: 拆数组,而"取头一个"这件事只有认人的那一层知道得分单多选。
#: 见 :func:`app.service.org.person_account`。
ACCOUNT_REF = re.compile(r"^account[:.]\s*([\s\S]*?)\s*$")
#: 整段就是这几种之一:``{form.x}`` 要给原类型(数字入参不该变成字符串)
WHOLE_REF = re.compile(
r"^\{\s*(account:[^}]+|form[.:][^}]+|auto:[^}]+|work:[^}]+|const:[^}]*)\}$"
)
#: 一段话里混着写的引用:只有 account / form / work / auto 参与替换,``{const:…}`` 只认整段
EMBED_REF = re.compile(r"\{\s*(account:[^}]+|form[.:][^}]+|auto:[^}]+|work:[^}]+)\}")
#: ``{arg.x}`` / ``{arg:x}``:数据源请求体模板里引用的是「本次调用的入参」,
#: 不是表单字段,给它一个不会读歪的写法(``{form.x}`` 在模板里等价,兼容既有配法)
ARG_REF = re.compile(r"\{arg[.:]\s*([^}]+?)\s*\}")
#: `{auto:today:YYYY}` 这类格式:只支持这几档,够用且不会变成模板语言
DATE_FORMATS = {"YYYY": "%Y", "YYYY-MM": "%Y-%m", "YYYYMM": "%Y%m", "YYYYMMDD": "%Y%m%d",
"YYYY-MM-DD": "%Y-%m-%d"}
#: 一个字段最多挂几个数据源。再多就不是"合集"而是"该在对面做一个聚合接口"了。
MAX_FIELD_SOURCES = 8
#: 多个源的结果怎么合成一格的值,与前端 utils/binding 的 MERGE_MODES 一一对应。
MERGE_MODES = ("first", "sum", "min", "max", "join")
#: 要数值合并的三档,目标格得是金额/数字/公式这类装得下数的。
NUMERIC_MERGE_MODES = ("sum", "min", "max")
#: 合集默认的拼接分隔符
DEFAULT_SEPARATOR = "、"
#: 一条源上的「什么时候用它」那一个键:值是一份结构化条件(与字段上的 ``visibleWhen``
#: 同一份形状,判定在 ``service/dicts.condition_ok``)。
#:
#: 为什么这一档挂在**每一条源**上而不是整份配置上:同一格常常要换家问——「费用类型是差旅
#: 就问差标接口,是招待就问 ERP 科目」。以前要么为每种组合另建一条源、要么在表单上多摆几格
#: 再拿显隐条件藏起来;清单里那几条本来就按顺序排的,加一句「这条什么时候算」就够它当路由用。
#: 没写这一项的条目恒成立,所以老配置读出来的行为一个字都不变。
ENTRY_WHEN_KEY = "when"
def entry_when(cfg: dict) -> dict | None:
"""这一条源挂的触发条件;没写、写得不成形状都回 ``None``(= 恒成立)。"""
when = cfg.get(ENTRY_WHEN_KEY) if isinstance(cfg, dict) else None
if isinstance(when, list):
when = {"match": "all", "rules": when}
if not isinstance(when, dict) or not (when.get("rules") or []):
return None
return when
def entry_active(entry: dict, data: dict | None) -> bool:
"""这一条源此刻用不用得上:没配条件恒成立,配了就问那一份结构化条件。
条件判定用的是联动那一份口径(``service/dicts.condition_ok``),于是设计器里拼得出
「报销类型 = 差旅」的那一条,运行时与提交链路里算的是同一个真假。延迟导入只为绕开
``dicts → binding`` 这一层反向依赖,不是另一套判据。
"""
when = entry_when(entry)
if when is None:
return True
from . import dicts
return dicts.condition_ok(when, data or {})
def blank(value: Any) -> bool:
"""空值:None、空串、空集合。空值不参与合并——一个系统这次没返回,不等于它返回了 0。"""
if value is None or isinstance(value, (dict, list, tuple, set)):
return not value
return str(value).strip() == ""
def to_cents(value: object) -> int | None:
"""把金额(元,float 或字符串)换成整数分;不是数字回 None。
合并与台账都用分:``work.data`` 存的是 float 元,累计几十次就会漂出零点几分,
而额度差一分都会被财务问一句「这钱去哪了」。
"""
if value is None or isinstance(value, bool):
return None
if isinstance(value, int):
return value * 100
if isinstance(value, float):
return int(round(value * 100))
text = str(value).strip().replace(",", "").replace(",", "")
if not text:
return None
try:
return int(round(float(text) * 100))
except ValueError:
return None
def from_cents(cents: object) -> float:
"""分转元(给界面显示与表单字段用,表单那边一直是元)。"""
return round(int(cents or 0) / 100, 2)
def form_ref(expr: object) -> str:
"""``{form.x}`` / ``{form:x}`` 里的字段名;不是这种写法回空串。"""
match = FORM_REF.match(str(expr if expr is not None else "").strip())
if not match:
return ""
return str(match.group(1) or match.group(2) or "")
#: 写法外面套着的转换前缀:设计期查"引用了哪一格"要透过它看里面,不然
#: ``{account:form.申请人}`` 里那一格在设计器里就被当成"没引用任何字段",字段删了也没人提醒
TRANSFORM_WRAP = re.compile(r"\{\s*account\s*[:.]\s*")
def form_refs(expr: object) -> list[str]:
"""一段写法里引用到的所有表单字段名(设计期用来检查引用有没有掉在地上)。"""
# 先剥掉转换写法的外壳再扫:``{account:form.申请人}`` 引用的还是申请人那一格
text = TRANSFORM_WRAP.sub("{", str(expr if expr is not None else ""))
return [str(item).strip() for item in FORM_REF_ALL.findall(text) if str(item).strip()]
def _auto_value(db, key: str, fmt: str | None, work=None, actor=None) -> str:
"""``{auto:...}``:日期那几档本地算,其余问系统值(发起人、部门、单号…)。"""
if key in ("today", "now"):
return datetime.now().strftime(DATE_FORMATS.get(fmt or "", DATE_FORMATS["YYYY-MM-DD"]))
return autofill.resolve(db, key, work=work, actor=actor) if db is not None else ""
def resolve(db, expr: object, data: dict, work=None, actor=None) -> Any:
"""把一个取值写法换成**原类型**的值。
整段就是一个引用时给原值(``{form:amount}`` 该是数字,不是 ``"1200"``),
一段话里混着写时按字符串拼。认不出的写法原样当字面量。
口径与前端 ``utils/binding.ts`` 的 ``resolveExpr`` 一字不差——过去后端整段以外
一律原样返回、前端却会拼接,``{form.a}-x`` 这种入参在填单页面上是对的、
提交时后端原样打给上游,两边各错一半。
"""
text = str(expr if expr is not None else "")
whole = WHOLE_REF.match(text.strip())
if whole:
return _one(db, whole.group(1), data, work=work, actor=actor)
if EMBED_REF.search(text):
return EMBED_REF.sub(lambda match: _as_text(_one(db, match.group(1), data, work, actor)), text)
return text
def _as_text(value: Any) -> str:
"""拼接进一句话时的形状:对象给 JSON,None 给空串。"""
if value is None:
return ""
if isinstance(value, str):
return value
if isinstance(value, (dict, list)):
return json.dumps(value, ensure_ascii=False)
return str(value)
def const_literal(literal: str) -> Any:
"""``{const:…}`` 里那串字面量该怎么给:能当 JSON 标量读的就给**原类型**。
``{const:1}`` 要给数字 1 而不是字符串 ``"1"``——上游 Go/Java 那种声明了
``int`` / ``*bool`` 的字段接不住带引号的值(报销那边实测直接回
``boolean value must be 0, 1, false or true``)。读不动的(``{const: A }``、
``{const:13%}``)照旧原样给,空格是配的人自己要的;数组与对象也照旧给字符串,
那是"这一格写了一串 JSON 文本",不是"这是一个数组"。
取数(``body_template``)与写回(``Integration.payload``)**共用这一份口径**:
同一种写法在两处渲染出两种类型,是"数据源测试点着是绿的、真写回就 400"的来路。
"""
try:
decoded = json.loads(literal)
except ValueError:
return literal
if decoded is None or isinstance(decoded, (str, int, float, bool)):
return decoded
return literal
def _one(db, body: object, data: dict, work=None, actor=None) -> Any:
"""整段引用(已经去掉两侧花括号)的取值。"""
raw = str(body if body is not None else "")
text = raw.strip()
if text.startswith("const:"):
return const_literal(raw[raw.index("const:") + len("const:"):])
if text.startswith("auto:"):
parts = text[len("auto:"):].split(":", 1)
return _auto_value(db, parts[0].strip(), parts[1].strip() if len(parts) > 1 else None, work, actor)
account = ACCOUNT_REF.match(text)
if account:
# 里面照旧是一写法(form / arg / const),先取值再换账号;换不出来给空串,
# 让取数那侧明说"这次没查到值",而不是拿一个猜出来的人打款
inner = re.sub(r"^arg[.:]\s*", "form.", account.group(1).strip())
return org.person_account(db, _one(db, inner, data, work=work, actor=actor)) if db is not None else ""
match = re.match(r"^form[.:]\s*([\s\S]*?)\s*$", text)
if match:
value = (data or {}).get(str(match.group(1).strip()))
return "" if value is None else value
match = re.match(r"^work:\s*([\s\S]*?)\s*$", text)
if match:
return getattr(work, match.group(1).strip(), None) if work is not None else None
return None
def resolve_text(db, expr: object, data: dict, work=None, actor=None) -> str:
"""取值写法 → 字符串值(额度维度、阈值右边那格要的就是字符串)。"""
value = resolve(db, expr, data, work=work, actor=actor)
if value is None:
return ""
if isinstance(value, str):
return value
if isinstance(value, (dict, list)):
return json.dumps(value, ensure_ascii=False)
return str(value)
def render(db, template: Any, data: dict, work=None, actor=None) -> Any:
"""把一份模板(字符串 / 字典 / 列表,或套娃)里的取值写法换成真值。
``data`` 在这里是**本次调用的入参**(由字段上的 ``args`` 从表单映射而来),
所以模板里写 ``{arg.costCenter}`` 取的就是那个入参;``{form.x}`` 写法等价。
"""
if isinstance(template, dict):
return {key: render(db, value, data, work, actor) for key, value in template.items()}
if isinstance(template, list):
return [render(db, item, data, work, actor) for item in template]
if not isinstance(template, str):
return template
return resolve(db, ARG_REF.sub(lambda match: "{form:%s}" % match.group(1), template),
data, work=work, actor=actor)
def resolve_args(db, cfg: Any, data: dict, work=None, actor=None) -> dict:
"""把配置里那份 ``args``(入参名 -> 写法)算成这次调用的入参。"""
args_cfg = cfg.get("args") if isinstance(cfg, dict) and isinstance(cfg.get("args"), dict) else {}
return {str(key): render(db, value, data or {}, work=work, actor=actor) for key, value in args_cfg.items()}
def referenced_args(template: Any) -> set[str]:
"""模板里真正读到的入参名(``{arg.x}`` 那些)。"""
names: set[str] = set()
if isinstance(template, str):
names.update(match.group(1) for match in ARG_REF.finditer(template))
elif isinstance(template, dict):
for value in template.values():
names.update(referenced_args(value))
elif isinstance(template, list):
for value in template:
names.update(referenced_args(value))
return names
def missing_args(row: models.DataSource, args: dict) -> list[str]:
"""模板要用的入参里,此刻还没有值的那几个。
只管单值取数那一条:列表型源的空关键词是正常用法(打开候选就该先给一页),
拿同一条规矩去挡会把下拉框第一页也挡掉。带点的引用写法照旧放过,
那种取值不在这张入参表的平铺键上,判不准就别判。
地址模板算一份、请求体模板算一份:按单号查的那一类接口(``?oa_flow_number={arg.x}``)
参数根本不在请求体里,只看请求体会让空单号照样外呼一次、白留一条 error、
还顺手把熔断往上推——这正是这一道闸存在的理由。
"""
if str(getattr(row, "kind", "") or "") == models.DataSource.KIND_SEARCH:
return []
names = referenced_args(getattr(row, "body_template", None) or {})
names |= referenced_args(str(getattr(row, "url", "") or ""))
names = {str(name) for name in names if "." not in str(name)}
return sorted(name for name in names if not str((args or {}).get(name) or "").strip())
def arg_names(template: Any) -> set[str]:
"""一段模板里引用了哪几个本次入参(``{arg.x}``)。
可嵌入页面那一类拿它当**参数白名单**:地址模板里没写过的名字根本拼不进去,
于是"设计者把整张单的值都塞进查询串"这件事没有入口(见 service/embed.py)。
"""
return {str(name).strip() for name in ARG_REF.findall(str(template or ""))}
def arg_names_of(*templates: Any) -> set[str]:
"""几份模板(字符串 / 请求体 / 请求头,或它们混着)合起来引用了哪几个本次入参。
可嵌入页面"先调接口拿链接"那一档要用它:那时参数白名单不只写在地址上,还写在
请求体与请求头里,三份得合成一份才说得出"这个页面到底吃哪几个参数"
(见 ``service/embed.py:declared_args``)。
"""
names: set[str] = set()
for template in templates:
names |= referenced_args(template)
return {str(name).strip() for name in names if str(name).strip()}
# ---------------------------------------------------------------------------
# 多源清单与合并
# ---------------------------------------------------------------------------
def entries(cfg: Any) -> list[dict]:
"""这一格要用的数据源清单,统一成 ``{source, args, picks, pick, extras, when}``。
配了 ``sources`` 就是「一个字段用好几个接口」的合集写法,没配就回落到
``source`` / ``args`` / ``picks`` 那份单源老写法——调用方不用管当初配的是哪一种。
候选来源那一路(``optionSource=dataSource``)也吃这份形状,
只是它只有一张源:``{source: dataSourceCode, args: dataSourceArgs}``。
这一句**只管清单全不全**,不问「此刻该不该调」——带条件的条目照原样在清单里,
要跑哪几条问 :func:`active_entries`。设计期检查(源还在不在、入参引用掉没掉在地上)
得看全量,运行时才按条件筛,两头各取所需。
"""
if not isinstance(cfg, dict):
return []
rows = cfg.get("sources")
out: list[dict] = []
if isinstance(rows, list):
for item in rows:
if not isinstance(item, dict):
continue
code = str(item.get("source") or "").strip()
if not code:
continue
out.append(
{
"source": code,
"args": item.get("args") if isinstance(item.get("args"), dict) else {},
"picks": item.get("picks") if isinstance(item.get("picks"), dict) else {},
**entry_parse(item),
**({"when": item["when"]} if entry_when(item) else {}),
}
)
if out:
return out[:MAX_FIELD_SOURCES]
code = str(cfg.get("source") or "").strip()
if not code:
return []
return [
{
"source": code,
"args": cfg.get("args") if isinstance(cfg.get("args"), dict) else {},
"picks": cfg.get("picks") if isinstance(cfg.get("picks"), dict) else {},
**entry_parse(cfg),
**({"when": cfg["when"]} if entry_when(cfg) else {}),
}
]
def active_entries(cfg: Any, data: dict | None) -> list[dict]:
"""这一格**此刻**要调的那几张源:清单里只留触发条件成立的条目。
一条都不成立就是这一格这次不取数(值留在原来那一份上,按 ``onError`` 那档兜),
和「配了源但源停了」不是一回事,所以留痕里也不会记成失败。
"""
return [entry for entry in entries(cfg) if entry_active(entry, data)]
def entry_parse(cfg: dict) -> dict:
"""这一格对**解析规则**的两处覆盖,缺省就不写这两个键(老配置的形状保持三个键)。
- ``pick``:本格取响应里的哪一条路径。留空 = 跟随源上声明的取值路径。
一张接口回七列、这张单上三格各要其中一列,靠这一格就够,不用另建两条源;
- ``extras``:本格额外声明的带出列 ``{名字: 路径}``,与源上的 ``map_extra`` 合并
(同名以字段上的为准),让"接口里还有哪几列想要"能在表单这一侧说完。
"""
out: dict = {}
pick = cfg.get("pick")
if isinstance(pick, str) and pick.strip():
out["pick"] = pick.strip()
rows = cfg.get("extras")
if isinstance(rows, dict):
clean = {name.strip(): path.strip() for name, path in rows.items()
if isinstance(name, str) and isinstance(path, str)
and name.strip() and path.strip()}
if clean:
out["extras"] = clean
return out
def merge(mode: str, values: list[Any], *, separator: str = DEFAULT_SEPARATOR) -> Any:
"""把几个源回来的值合成一格的值。
- ``first``:按配置顺序取第一个有值的("ERP 有就用 ERP,没有问 CRM")。
- ``sum`` / ``min`` / ``max``:按分算,别让浮点把金额加歪。
- ``join``:文本按分隔符拼起来,多个系统的单号并排显示就靠它。
"""
filled = [item for item in values if not blank(item)]
if not filled:
return None
kind = str(mode or "first")
if kind == "first":
return filled[0]
if kind == "join":
return (separator or DEFAULT_SEPARATOR).join(
item if isinstance(item, str) else json.dumps(item, ensure_ascii=False) for item in filled
)
cents = [to_cents(item) for item in filled]
nums = [item for item in cents if item is not None]
if not nums:
return filled[0]
total = sum(nums) if kind == "sum" else (min(nums) if kind == "min" else max(nums))
return from_cents(total)
# ---------------------------------------------------------------------------
# 设计期校验:源还在不在、入参引用有没有掉在地上、带出的键声明过没有
# ---------------------------------------------------------------------------
#: 要「取一个值」的那一类调用(字段带出、额度、阈值右值格)
WANT_FETCH = models.DataSource.KIND_FETCH
#: 要「取一批候选」的那一类调用(字典的外部来源、候选来源=外部数据源)
WANT_SEARCH = models.DataSource.KIND_SEARCH
def source_problem(code: object, row: Any, *, want: str = WANT_FETCH, want_noun: str = "这一格") -> str:
"""这一处引用的数据源能不能用,一句话说明白;没问题回空串。
**全系统只有这一句**:字段上的外部取数、字典绑的外部来源、候选来源=外部数据源,
过去三处各写一套判据与措辞,于是"能存下来但一用就错"的组合总能从某一条路漏过去。
"""
text = str(code or "").strip()
if not text:
return "还没选要用哪一张外部数据源"
if row is None:
return f"引用的数据源不存在:{text}(先到「外部数据源」页建好)"
name = str(getattr(row, "name", "") or text)
if not getattr(row, "enabled", True):
return f"引用的数据源「{name}」已停用"
kind = str(getattr(row, "kind", "") or "")
if want == WANT_SEARCH and kind != WANT_SEARCH:
return f"引用的数据源「{name}」是取一个值的,{want_noun}要的是列表型数据源"
if want == WANT_FETCH and kind == WANT_SEARCH:
return f"引用的数据源「{name}」是列表型,取不出单个值"
if str(getattr(row, "direction", "") or "") == models.DataSource.DIRECTION_OUT:
# 往外写的源,连地址和解析规则都是按"发出去"配的:请求体由写回模板渲染,
# 这张源上根本没有"值在响应哪里"这回事,拿它取值一定取不到。
# 同一个系统既要写又要带值,方向该选「双向」,那句话就写在报错里指路。
return (f"引用的数据源「{name}」的方向是往外写,{want_noun}取不到东西"
"(要往表单里带值,到「外部数据源」把这张源的方向改成「双向」)")
if str(getattr(row, "provider", "") or "") == models.DataSource.PROVIDER_SQL:
# SQL 源没有地址也没有响应可看,配歪了唯一的暴露口就是发起时那一格空着——
# 所以这一句必须在这里说,不能等到执行时才发现
from . import sqlsource # 放在函数里:内核不新增顶层依赖
issues = sqlsource.problems(
getattr(row, "sql_text", ""), (getattr(row, "body_template", None) or {}).keys(),
at=f"引用的数据源「{name}」的 SQL",
)
if issues:
return issues[0]
return ""
#: 整段是一个 ``{account:…}``:里面不再套花括号,所以"这一条引用包没包装换账号的壳"
#: 用这一条扫就够(``TRANSFORM_WRAP`` 形状相同,用途是剥壳扫字段名)。
ACCOUNT_SCOPED = re.compile(r"\{\s*account\s*[:.]\s*[^{}]*\}", re.IGNORECASE)
def person_field_keys(fields: Iterable[Any] | None) -> set[str]:
"""这一份字段清单里**选人字段**(``type=user``)的名字。
那一格存的永远是账号**数组**,SQL 的 ``=`` 绑不进数组(``service/fetch.py`` 在查库前
就会挡下来),所以设计期得按字段类型提醒一句,而不是等填单的人撞上去。
"""
out: set[str] = set()
for item in fields or []:
if not isinstance(item, dict):
continue
if str(item.get("type") or "").strip() != "user":
continue
key = str(item.get("key") or "").strip()
if key:
out.add(key)
return out
def bare_person_refs(expr: Any, person_keys: set[str]) -> list[str]:
"""写法里**没包** ``{account:…}`` 壳的那几个选人字段引用。
``form_refs`` 会先把壳剥掉再扫,所以"包了壳的"要单独按整段认一遍再排除;
同一个字段既包壳又裸写在这种写法里表达不了两件事,按"包过就算包过"处理。
"""
if not person_keys or not isinstance(expr, str):
return []
wrapped: set[str] = set()
for chunk in ACCOUNT_SCOPED.findall(expr):
wrapped.update(form_refs(chunk))
return [ref for ref in form_refs(expr) if ref in person_keys and ref not in wrapped]
def arg_ref_problems(
args: Any, keys: set[str], at: str, *,
self_ref: str = "", person_keys: set[str] | None = None
) -> list[str]:
"""入参写法里引用的字段在不在。与外部取数、候选来源共用这一句。
``at`` 说的是那一份入参表本身(如「外部取数」),拼出来就是
「……外部取数的入参「x」引用了不存在的字段「y」」。
``self_ref`` 给成这一格自己的字段名时,引用自己单独说一句:候选按这一格筛、
这一格又只能从候选里挑,是个筛不出东西的圈,跟"引用了不存在的字段"不是一回事。
"""
out: list[str] = []
if args is None:
return []
if not isinstance(args, dict):
return [f"{at}的入参格式不对"]
for name, expr in args.items():
if not isinstance(expr, str):
continue
for ref in form_refs(expr):
if not ref:
continue
if self_ref and ref == self_ref:
out.append(f"{at}的入参「{name}」引用了这一格自己:候选按这一格筛,"
"这一格又只能从候选里挑,绕成圈筛不出东西")
elif ref not in keys:
out.append(f"{at}的入参「{name}」引用了不存在的字段「{ref}」")
for ref in bare_person_refs(expr, person_keys or set()):
out.append(f"{at}的入参「{name}」取的是选人字段「{ref}」的原值:那一格是登录账号"
f"数组,绑进 SQL 的 = 永远比不中。这一栏的取值写法改成 "
f"{{account:form.{ref}}},平台按人换成账号(单选取头一个)")
return out
def field_keys(fields: Iterable[Any] | None) -> set[str]:
"""这一份字段清单里的字段名,写入方判「这一格还在不在表单上」用它。
口径与各处设计期校验(``fetch.problems`` / ``quota.problems`` / ``threshold.problems``)
一致:都看传进来的那一份 ``fields``。环节绑了自己的表单时,那份清单就是那张表单,
配带出时校验的、写入时判活的,始终是同一个参照系。
"""
out: set[str] = set()
for item in fields or []:
if not isinstance(item, dict):
continue
key = str(item.get("key") or "").strip()
if key:
out.add(key)
return out
def live_target(target: Any, keys: set[str] | None) -> str:
"""这一笔「带出」真正写得进去的那一格;目标格子不在表单上了就回空串,写入方据此跳过。
表单改过之后,字段上那份带出可能还指着早已删掉的格子。设计器删字段时会顺手清掉这类
指向(见前端 ``utils/formPrune``),但改之前存下的老表单、以及从接口直接写进来的配置
里它还在。运行时必须不写:那一格的名字是 ``field_text_2`` 这种会复用的键,删掉之后重新
加一个同名字段太常见了,把外部数、额度数悄悄盖到别人头上,比少写一格危险得多。
``keys=None`` 是调用方拿不到字段清单时的口子:照旧写,不因为这道闸反而少了原有行为。
"""
text = str(target or "").strip()
if not text:
return ""
if keys is None or text in keys:
return text
return ""
def condition_ref_problems(condition: Any, keys: set[str], at: str) -> list[str]:
"""一份结构化条件里的引用毛病:字段没了、比较符不认。
判"引用了不存在的字段"而不是判"这个值对不对":条件永远不成立时那一格只是安静地不调、
不选、不显示,没人报错,最难查的正是这种"配了个寂寞"。``keys=None`` 时不判引用
(拿不到字段清单的那几处调用方)。
"""
from . import dicts
out: list[str] = []
normalized = condition
if isinstance(normalized, list):
normalized = {"match": "all", "rules": normalized}
if not isinstance(normalized, dict):
return [f"{at}的条件格式不对"]
for rule in normalized.get("rules") or []:
if not isinstance(rule, dict):
out.append(f"{at}的条件里有认不出的写法")
continue
op = str(rule.get("op") or "").strip()
if op not in dicts.CONDITION_OPS:
out.append(f"{at}的条件里有不支持的比较符:{op or '(空)'}")
for name in ("field", "valueField"):
ref = str(rule.get(name) or "").strip()
if ref and keys is not None and ref not in keys:
out.append(f"{at}的条件引用了不存在的字段「{ref}」")
if not (normalized.get("rules") or []):
out.append(f"{at}的条件一条规则都没有,等于这条永远不成立")
return out
def entry_problems(
db, entry: dict, keys: set[str], at: str, *,
self_key: str = "", want: str = WANT_FETCH, want_noun: str = "这一格", declared_only: bool = True,
person_keys: set[str] | None = None, target_keys: set[str] | None = None, target_noun: str = "字段"
) -> list[str]:
"""一个源那条配置本身的毛病:源在不在、入参引用、带出去向。
外加这一条自己那份触发条件(``when``)——它永远不成立的话,这一条源根本不会被调。
``db=None`` 是设计器镜像那一份(拿不到库):那时只判写法与引用,不判源。
``keys`` 是**入参**能引用的那一份名字清单,``target_keys`` 是**带出去向**能写进去的那一份,
两者默认是同一份(主表字段就是这么配的)。明细列那一格必须分开传:它的入参读得到整张单
与本行的列(``{form.x}`` 在行作用域里两边都认,同名列以本行为准,跟本行公式同一分寸),
而带出去向只许落在同一张明细表的列上。``target_noun`` 只管那句报错怎么说。
"""
out: list[str] = []
if not isinstance(entry, dict):
return [f"{at}的格式不对"]
code = str(entry.get("source") or "").strip()
if not code:
out.append(f"{at}没选数据源")
row = _get_source(db, code) if (db is not None and code) else None
# 选人字段当入参这件事只有 SQL 那条通道会栽(数组绑不进 = ),HTTP 的报文里放数组
# 是正当写法,所以按源判断:只有这条源真带 SQL 才提这一句。
sql_bound = bool(person_keys) and bool(str(getattr(row, "sql_text", "") or "").strip())
out.extend(arg_ref_problems(
entry.get("args"), keys, at, person_keys=person_keys if sql_bound else None
))
allowed_targets = keys if target_keys is None else target_keys
for name, target in (entry.get("picks") or {}).items() if isinstance(entry.get("picks"), dict) else []:
target_key = str(target or "").strip()
if not target_key:
continue
if target_key not in allowed_targets:
out.append(f"{at}要把「{name}」带进不存在的{target_noun}「{target_key}」")
elif self_key and target_key == self_key:
out.append(f"{at}不能把值带进自己:取回来的那一个值本来就落在这一格上")
extra_rows = entry.get("extras") if isinstance(entry.get("extras"), dict) else {}
for name, path in extra_rows.items():
if not str(name or "").strip():
out.append(f"{at}有一行额外带出列没写名字")
elif not str(path or "").strip():
out.append(f"{at}额外带出的「{name}」没写它在响应里的路径")
when = entry_when(entry)
if when is not None:
out.extend(condition_ref_problems(when, keys, at))
if row is not None:
problem = source_problem(code, row, want=want, want_noun=want_noun)
if problem:
out.append(f"{at}{problem}")
elif declared_only and want == WANT_FETCH:
# 「声明过」的键 = 源上那几张表 + 这一格自己补的那几行,两边都算数
declared = {str(name) for name in (getattr(row, "map_extra", None) or {})}
declared |= {str(name) for name in extra_rows}
for name in (entry.get("picks") or {}):
if str(name) not in declared and str(name) != "value":
out.append(f"{at}带出的「{name}」不在该数据源声明的可带出键里")
return out
def _get_source(db, code: str):
"""按编码取数据源那一行(不 import fetch:那一层反过来要用本模块)。"""
from sqlalchemy import select
return db.execute(
select(models.DataSource).where(models.DataSource.code == str(code).strip())
).scalar_one_or_none()
def entry_labels(at: str, rows: Iterable[dict]) -> list[tuple[str, dict]]:
"""多源时把报错的门牌加上「第几个源」,只有一个源就沿用字段那一句话。"""
items = list(rows)
if len(items) <= 1:
return [(at, entry) for entry in items]
return [(f"{at}的第 {index} 个数据源", entry) for index, entry in enumerate(items, start=1)]