unis-oa/backend/scripts/check_embed.py

1876 lines
122 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.

"""表单嵌外部页面(``type=embed``)的验收脚本(不连库,跑在 backend 目录下)::
python3 scripts/check_embed.py
方案见 ``docs/embed-page-field-design.md``。那篇 §8 按危险程度排了六条要钉住的断言,
这里能不连库钉的都钉上,钉不住的(环节权限那条要真库)留在方案里没删。
五件事必须一直成立:
1. **地址模板就是参数白名单**:模板里没写 ``{arg.x}`` 的参数名,配了也拼不进地址——
这条挡的是"设计者把整张单的值都灌进查询串",也是发起页肯收前端交回值的前提;
2. **URL 拼不出越权的形状**:参数值一律按查询参数编码,``&`` / ``#`` / ``/`` 加不进去;
3. **能不能被嵌只认证据**:CSP ``frame-ancestors`` 说了算(它比 XFO 新,浏览器也是这么
取舍的),探不准的一律回 ``unknown`` 让前端降级成卡片,不猜"应该能嵌";
4. **短码只留哈希、只认发出时那个源、用过就废**;换身份那一侧的密钥比对是常数时间;
5. **留痕里没有参数值**、CSP 里 ``blob:`` 不能丢——前者是薪资和身份证号不外泄,
后者是附件 PDF 预览(``URL.createObjectURL``)别被这道新闸顺手关掉。
最后把前后端各写一遍的那几句措辞对一遍:漂了这里就红。
"""
from __future__ import annotations
import logging
import pathlib
import re
import sys
import types
from datetime import timedelta
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent.parent))
from app import models # noqa: E402 (需要上面那行把 backend 目录放进 sys.path)
from app import config # noqa: E402
from app.config import settings # noqa: E402
from app.service import embed # noqa: E402
# 这一篇会**故意**让取链接失败好几回(挡来源、挡解析、挡熔断),那些 warning 是脚本
# 自己招来的,不是发现了什么;静音掉,让终端上只剩断言结果
logging.getLogger("app.service.embed").setLevel(logging.ERROR)
class Source:
"""顶替 ``oa_data_source`` 上那一条:``embed`` 只用 getattr 读几个属性。"""
def __init__(self, code: str = "erp_contract", *, name: str = "", enabled: bool = True,
provider: str = models.DataSource.PROVIDER_EMBED,
url: str = "https://erp.example.com/contract/detail",
page_mode: str = embed.MODE_NONE, app_code: str = "",
auth_secret: str = "", timeout_seconds: int = 5,
url_mode: str = embed.URL_TEMPLATE, url_path: str = "",
url_origins: list[str] | None = None, method: str = "POST",
headers: dict | None = None, body_template: dict | None = None,
mock_payload: dict | None = None, auth_type: str = "none",
auth_username: str = "", retries: int = 1, rate_limit_qpm: int = 0,
cooldown_seconds: int = 60, view_url_path: str = "", view_url: str = "",
url_links: list[dict] | None = None, url_meta: dict | None = None) -> None:
self.code = code
self.name = name or code
self.enabled = enabled
self.provider = provider
self.url = url
self.page_mode = page_mode
self.app_code = app_code
self.auth_secret = auth_secret
self.timeout_seconds = timeout_seconds
# 地址由接口现给那三格(service/embed.py:url_mode_of)
self.url_mode = url_mode
self.url_path = url_path
# 查看页那两条(接口那一档看位置,模板那一档看第二条地址模板)
self.view_url_path = view_url_path
self.view_url = view_url
# 对方还回了哪几条链接,以及同一次响应里顺手带回的那几个只读值
self.url_links = list(url_links or [])
self.url_meta = dict(url_meta or {})
self.url_origins = list(url_origins or [])
# 调那个接口要用的几格,与 oa_data_source 上同名的列一一对应
self.method = method
self.headers = dict(headers or {})
self.body_template = dict(body_template or {})
self.mock_payload = dict(mock_payload or {})
self.auth_type = auth_type
self.auth_username = auth_username
self.retries = retries
# 熔断与限流读写的几格(fetch.outbound_guard / outbound_mark)
self.rate_limit_qpm = rate_limit_qpm
self.cooldown_seconds = cooldown_seconds
self.fail_count = 0
self.open_until = None
class Result:
def __init__(self, rows) -> None:
self._rows = rows
def scalar_one_or_none(self):
return self._rows[0] if self._rows else None
def scalars(self):
return self
def all(self):
return list(self._rows)
class FakeDB:
"""顶替 ``Session``:查一条源走 ``scalar_one_or_none``,列源走 ``scalars().all()``。
写进去的行都收在 ``added`` 里——留痕那条断言要看的就是"落库那一行长什么样"。
"""
def __init__(self, *rows) -> None:
self.rows = [row for row in rows if isinstance(row, Source)]
self.added: list = []
def execute(self, _statement):
return Result(list(self.rows))
def add(self, row) -> None:
self.added.append(row)
def commit(self) -> None:
pass
def field(source: str = "erp_contract", **cfg) -> dict:
"""字段上那一份 ``embed`` 配置,够短一点。"""
body = {"source": source}
body.update(cfg)
return {"key": "contractPage", "type": "embed", "label": "合同详情", "embed": body}
# ---------------------------------------------------------------------------
# 1. 地址模板就是参数白名单
# ---------------------------------------------------------------------------
def check_param_allowlist() -> None:
row = Source(url="https://erp.example.com/contract/detail?no={arg.contractNo}")
eq("模板声明的参数名就是白名单", sorted(embed.arg_names(row.url)), ["contractNo"])
args, missing = embed.resolve_params(
None, row, field(params={"contractNo": "{form.contractNo}", "salary": "{form.salary}"}),
data={"contractNo": "HT-001", "salary": "30000"},
)
eq("模板用不上的参数拼不进地址", args, {"contractNo": "HT-001"})
eq("地址要而这份单没给的参数要报出来",
embed.resolve_params(None, row, field(params={"contractNo": "{form.contractNo}"}), data={})[1],
["contractNo"])
# 单据已经存在时(传了 work),参数只认后端自己算的那一份
args2, _ = embed.resolve_params(
None, row, field(params={"contractNo": "{form.contractNo}"}),
data={"contractNo": "HT-后端"}, work=object(),
client_args={"contractNo": "HT-前端改的"},
)
eq("已有单据时不收前端交回来的值", args2, {"contractNo": "HT-后端"})
# 发起页没有单据可问,才认前端交回来的那几格,而且只认 {form.x}
args3, _ = embed.resolve_params(
None, row, field(params={"contractNo": "{form.contractNo}", "operator": "{auto:creatorAccount}"}),
data={}, client_args={"contractNo": "HT-新填的", "operator": "随便谁"},
)
eq("发起页收 {form.x} 那一类", args3.get("contractNo"), "HT-新填的")
ok("发起页不收 {auto:…},那种后端自己算", args3.get("operator") != "随便谁", args3)
many = {f"k{i}": "{form.x}" for i in range(40)}
got = embed.resolve_params(None, Source(url="https://a.example.com/p?" + "&".join(
f"p{i}={{arg.k{i}}}" for i in range(40))), field(params=many),
data={f"x": "v"})[0]
ok("一格最多带这么多个参数", len(got) <= embed.MAX_ARGS, len(got))
long_args = embed.resolve_params(
None, Source(url="https://a.example.com/p?no={arg.contractNo}"),
field(params={"contractNo": "{form.contractNo}"}),
data={"contractNo": "长" * 2000})[0]
ok("单个值再长也有上限", len(long_args["contractNo"]) <= embed.MAX_ARG_CHARS,
len(long_args["contractNo"]))
def check_param_text() -> None:
"""**选人那一格交出去的是账号本身,不是 ["zhangsan"] 这么一串 JSON。**
这一条是"嵌入页只有发起页打得开"那件真事的根:选人字段存的永远是数组,发起页那一头
前端按顿号拼过(``EmbedFrame.clientParams``),这一头过去走的是
``binding.resolve_text``——它给的是存储形状。参数名、参数个数、留痕里的 keys 全一样,
只有值多了一层方括号和引号,对方按账号查人查不到,于是每张单据一发出去那一格就再也
打不开了,屏幕上只剩一句"这个页面暂时打不开"。
"""
row = Source(url="https://erp.example.com/create?account={arg.applicant}&dept={arg.applyDept}")
cfg = field(params={"applicant": "{form.applicant}", "applyDept": "{form.applyDept}"})
args, _ = embed.resolve_params(None, row, cfg, data={"applicant": ["zhangsan"], "applyDept": "研发"})
eq("数组那一格拼成账号本身", args, {"applicant": "zhangsan", "applyDept": "研发"})
eq("多选按顿号拼",
embed.resolve_params(None, row, field(params={"applicant": "{form.applicant}"}),
data={"applicant": ["zhangsan", "lisi"]})[0]["applicant"],
"zhangsan、lisi")
eq("套着物件的那几项不参与拼接",
embed.resolve_params(None, row, field(params={"applicant": "{form.applicant}"}),
data={"applicant": [{"account": "zhangsan"}, "lisi"]})[0]["applicant"],
"lisi")
eq("开关给 true / false,不是 True / False",
embed.resolve_params(None, row, field(params={"applicant": "{form.applicant}"}),
data={"applicant": True})[0]["applicant"],
"true")
eq("金额那一格给 2,不给 2.0(浏览器那一份就是 2,声明成 int 的字段收不下 2.0)",
embed.resolve_params(None, row, field(params={"applicant": "{form.applicant}"}),
data={"applicant": 2.0})[0]["applicant"], "2")
eq("真有小数的照给", embed.resolve_params(None, row, field(params={"applicant": "{form.applicant}"}),
data={"applicant": 2.5})[0]["applicant"], "2.5")
eq("空数组等于没给:这个参数压根不带",
embed.resolve_params(None, row, cfg, data={"applicant": [], "applyDept": "研发"})[0],
{"applyDept": "研发"})
# 同一张单在两个场合算出来的必须是同一组字:发起页认前端交回来的,环节认单据里的
start, _ = embed.resolve_params(
None, row, cfg, data={}, client_args={"applicant": "zhangsan", "applyDept": "研发"})
later, _ = embed.resolve_params(
None, row, cfg, data={"applicant": ["zhangsan"], "applyDept": "研发"}, work=object())
eq("发起页与审批环节带的是同一组值", start, later)
ok("拼好的值里不许有方括号", "[" not in embed.render_url(row.url, later),
embed.render_url(row.url, later))
def check_render_url() -> None:
out = embed.render_url("https://a.example.com/p?no={arg.no}&tab={arg.tab}",
{"no": "HT-1&ticket=abc", "tab": "a b/c#d"})
ok("参数值编码干净,拼不出第二个 ticket", "ticket=abc" not in out, out)
ok("没配的参数换成空串而不是留个 {arg.x}", "{arg." not in out, out)
eq("斜杠与井号也编码", out,
"https://a.example.com/p?no=HT-1%26ticket%3Dabc&tab=a%20b%2Fc%23d")
eq("地址模板没写参数位时一个字都不加",
embed.render_url("https://a.example.com/board", {"no": "X"}), "https://a.example.com/board")
# ---------------------------------------------------------------------------
# 2. 注册表上那条地址能不能用
# ---------------------------------------------------------------------------
def check_url_problem() -> None:
eq("空的要说什么", embed.url_problem(""), "页面地址不能为空")
ok("没协议要说什么", embed.url_problem("erp.example.com/p"), embed.url_problem("erp.example.com/p"))
ok("http 的非本机地址要挡", "https" in embed.url_problem("http://erp.example.com/p"),
embed.url_problem("http://erp.example.com/p"))
eq("本机自解放行(开发机上目标系统常是 http://127.0.0.1:5173)",
embed.url_problem("http://127.0.0.1:5173/p"), "")
eq("localhost 同样放行", embed.url_problem("http://localhost:5173/p"), "")
# 内网联调那一截:目标服务常常挂在内网 IP 上而不是回环,而本机 OA 自己也是 http,
# 混合内容那条理由根本不成立(见 service/embed.py:is_private_host)
for local in ("http://192.168.1.20:8000/p", "http://10.100.52.100:8000/p",
"http://172.16.3.9:3000/p", "http://169.254.10.1:8000/p",
"http://[fd00::7]:8000/p", "http://100.64.0.1:8000/p",
"http://dev.local:8000/p", "http://mybox.localhost:8000/p"):
eq(f"公网上路由不到的地址写 http 放行:{local}", embed.url_problem(local), "")
ok("公网 http 挡下来时要点名那两条出路",
"allow_http" in embed.url_problem("http://erp.example.com/p"), embed.url_problem("http://erp.example.com/p"))
from app.service import fetch as fetch_module # 同一把尺子两处用,这里钉第二处
ok("环境代理那一环认的也是这一把尺子(内网地址不该被 Clash 那类 TUN 代理吞掉)",
fetch_module.is_private_url("http://192.168.1.20:8000/p")
and not fetch_module.is_private_url("http://erp.example.com/p"))
# [embed] allow_http:整片内网没有 https 的部署才开它,默认关着
spec = config._BOOTSTRAP["embed_allow_http"]
config._BOOTSTRAP["embed_allow_http"] = (spec[0], spec[1], True)
try:
eq("开了 allow_http 才收公网 http", embed.url_problem("http://erp.example.com/p"), "")
eq("私网那一条本来就通,开关打开也不改变", embed.url_problem("http://192.168.1.20:8000/p"), "")
finally:
config._BOOTSTRAP["embed_allow_http"] = spec
ok("地址里带账号密码要挡", "@" in embed.url_problem("https://u:p@erp.example.com/p") or
embed.url_problem("https://u:p@erp.example.com/p") != "",
embed.url_problem("https://u:p@erp.example.com/p"))
ok("地址里有空格要挡(参数位该写 {arg.x})",
embed.url_problem("https://erp.example.com/p?no=1 2") != "", "")
eq("https 正常地址没毛病", embed.url_problem("https://erp.example.com/p?no={arg.no}"), "")
eq("origin 只看协议+主机+端口", embed.origin_of("https://ERP.example.com:8443/a/b?c=1#d"),
"https://erp.example.com:8443")
eq("读不出形状回空串", embed.origin_of("not a url"), "")
def check_source_problem() -> None:
eq("没挑页面", embed.source_problem("", None), "还没选择要嵌入哪个页面")
ok("页面被删了要说清是哪一条", "erp_contract" in embed.source_problem("erp_contract", None),
embed.source_problem("erp_contract", None))
row = Source(provider="http")
ok("不是可嵌入那一类要说清", "不是可嵌入页面" in embed.source_problem("erp_contract", row),
embed.source_problem("erp_contract", row))
ok("停用要说停用", "已被管理员停用" in embed.source_problem(
"erp_contract", Source(enabled=False)), embed.source_problem("erp_contract", Source(enabled=False)))
eq("启用中的可嵌入页面没毛病", embed.source_problem("erp_contract", Source()), "")
# ---------------------------------------------------------------------------
# 3. 能不能被嵌:只认证据
# ---------------------------------------------------------------------------
def check_frame_verdict() -> None:
anc = "https://oa.example.com"
eq("CSP 允许就放行",
embed.frame_verdict({"Content-Security-Policy": "frame-ancestors https://oa.example.com"}, anc)[0],
embed.FRAME_OK)
eq("CSP 说不含这个来源就拒绝",
embed.frame_verdict({"content-security-policy": "frame-ancestors 'none'"}, anc)[0],
embed.FRAME_DENIED)
# 浏览器同时收到两份时以 CSP 为准,结论跟着 CSP 走
eq("CSP 与 XFO 同时存在时以 CSP 为准",
embed.frame_verdict({"X-Frame-Options": "DENY",
"Content-Security-Policy": "frame-ancestors https://oa.example.com"}, anc)[0],
embed.FRAME_OK)
eq("只有 XFO: DENY", embed.frame_verdict({"X-Frame-Options": "deny"}, anc)[0], embed.FRAME_DENIED)
eq("只有 XFO: SAMEORIGIN", embed.frame_verdict({"X-Frame-Options": "SAMEORIGIN"}, anc)[0],
embed.FRAME_DENIED)
eq("ALLOW-FROM 早已废弃,不下结论",
embed.frame_verdict({"X-Frame-Options": "ALLOW-FROM https://oa.example.com"}, anc)[0],
embed.FRAME_UNKNOWN)
eq("看不懂的 XFO 也不下结论", embed.frame_verdict({"X-Frame-Options": "TRUSTNO1"}, anc)[0],
embed.FRAME_UNKNOWN)
ok("什么头都没有只能说「没禁止」,不是「保证能嵌」",
"建议实际打开" in embed.frame_verdict({}, anc)[1], embed.frame_verdict({}, anc)[1])
eq("通配子域匹得上", embed.frame_verdict(
{"Content-Security-Policy": "frame-ancestors *.example.com"}, anc)[0], embed.FRAME_OK)
eq("通配子域不匹主域本身", embed.frame_verdict(
{"Content-Security-Policy": "frame-ancestors *.other.com"}, anc)[0], embed.FRAME_DENIED)
eq("'self' 指的是被嵌那个页面自己,嵌进来的是别人", embed._host_matches("'self'", anc), False)
eq("只写主机名不限协议", embed._host_matches("oa.example.com", anc), True)
eq("写了协议就得对协议", embed._host_matches("http://oa.example.com", anc), False)
eq("写了端口就得对端口", embed._host_matches("https://oa.example.com:8443", anc), False)
eq("源里带别的路径也只比 origin", embed._host_matches("https://oa.example.com/oa", anc), True)
eq("由请求头算嵌进来的那个来源", embed.ancestor_origin("https", "oa.example.com"),
"https://oa.example.com")
eq("Host 头写得歪就回空串(不拿它拼 CSP)", embed.ancestor_origin("https", "oa.exa mple.com"), "")
eq("带路径的 Host 也不认", embed.ancestor_origin("https", "oa.example.com/oa"), "")
def check_probe_shape() -> None:
"""探测结论摊给「测试连通」弹窗那一份的映射(接口侧另有 check_embed_api.py 跑真的)。
界面只在 ``error`` / ``note`` 非空时才显示内容,所以"结论下出来了、那句话却没送到人前"
是一种会悄悄发生的丢失:``denied`` 要走红的 ``error``,``unknown`` 要走琥珀的 ``note``,
两者都别只剩一句「测试通过」。
"""
good = embed._verdict(embed.FRAME_OK, "能嵌")
eq("能嵌:成", (good["ok"], good["error"], good["note"]), (True, "", ""))
denied = embed._verdict(embed.FRAME_DENIED, "对方拒绝被嵌")
eq("明确不让嵌:按不成算,句子进 error", (denied["ok"], denied["error"], denied["note"]),
(False, "对方拒绝被嵌", ""))
unknown = embed._verdict(embed.FRAME_UNKNOWN, "以实测为准")
eq("说不准:不算失败,但句子要进 note 让人看得见", (unknown["ok"], unknown["error"], unknown["note"]),
(True, "", "以实测为准"))
bad = embed._verdict(embed.FRAME_ERROR, "连不上")
eq("探测本身失败:不成", (bad["ok"], bad["error"], bad["note"]), (False, "连不上", ""))
eq("结论原文两边都留着,界面想怎么用都行", denied["verdict"], embed.FRAME_DENIED)
def check_activity_form() -> None:
"""这一环该按**哪一张表单**判字段:环节指定的 > 这张单实际用的 > 流程最新的。
钉的是一件不会报错的事:只读 ``node.form`` 的话,**单表单流程**(环节上那一栏本来就是
空的,绝大多数流程都这样)拿到的是空字段清单,于是环节设的「隐藏」白设,回填白名单还算成
空表——第三方回写的值全部被挡成「不在允许回写的字段里」,而表单上配得一字不差。
"""
from app.api import embeds as embed_api
definition = types.SimpleNamespace(latest_form="F_LATEST")
work = types.SimpleNamespace(form="F_WORK")
eq("环节自己指定了表单就用它",
embed_api.activity_form_id(types.SimpleNamespace(form="F_NODE"), work, definition), "F_NODE")
eq("环节没指定就用这张单实际用的那张(单表单流程正是这一档)",
embed_api.activity_form_id(types.SimpleNamespace(form=""), work, definition), "F_WORK")
eq("连单据都没有表单号时退回流程最新那一张",
embed_api.activity_form_id(None, types.SimpleNamespace(), definition), "F_LATEST")
eq("三处都空就回空串(由调用方当作没表单)",
embed_api.activity_form_id(None, types.SimpleNamespace(), types.SimpleNamespace()), "")
def check_field_perm() -> None:
"""发票那一刻那道"这一格现在露不露"的判定(``api/embeds.py:_field_perm``)。
这条是纯函数,能在不连库的地方钉住:接口侧真跑起来那一条(环节设成隐藏时
``POST /embed/launch`` 必须 403)在 ``check_embed_api.py``,但那一个只能验到
"这个人与这张单没关系"那一路——真库里凑不出"某个环节把这一格藏了"的现成单据。
两头的判断都从 ``formruntime.effective_perm`` 出,所以判据钉在这儿、通路钉在那儿。
"""
from app.api import embeds as embed_api
view = {"key": "view", "label": "合同详情", "type": "embed", "embed": {"source": "erp_contract"}}
scoped = lambda perms: [{"activity": "a1", "fields": [view], "perms": perms}] # noqa: E731
eq("环节把这一格设成隐藏,判成 hidden",
embed_api._field_perm(scoped({"view": "hidden"}), "view", {}), "hidden")
eq("字段自己勾了默认隐藏,也一样藏",
embed_api._field_perm([{"activity": "a1", "fields": [dict(view, hidden=True)], "perms": {}}],
"view", {}), "hidden")
ok("环节给了只读也算露着(给地址,只是这一格本来就改不动)",
embed_api._field_perm(scoped({"view": "readonly"}), "view", {}) != "hidden",
embed_api._field_perm(scoped({"view": "readonly"}), "view", {}))
# 几个环节里只要有一个露着就放行:这个人确实有地方看得着这一格
eq("两个环节一个藏一个露,按露的算",
embed_api._field_perm([{"activity": "a1", "fields": [view], "perms": {"view": "hidden"}},
{"activity": "a2", "fields": [view], "perms": {}}], "view", {}),
"readonly")
# 标签页里那一页单独藏起来:那一"格"用的是标签页自己的 key,档位挂在 ``标签页key#页签key``
# 上,``perm_map`` 的展开落不到它身上(那一页里没有格子可落),只有这一支判得到
page = {"key": "pages", "label": "标签页", "type": "tabs",
"tabs": [{"key": "t1", "kind": "form", "label": "基本信息"},
{"key": "t2", "kind": "embed", "label": "合同详情", "embed": {"source": "erp_contract"}}]}
scoped_page = lambda perms: [{"activity": "a1", "fields": [page], "perms": perms}] # noqa: E731
eq("环节只藏标签页里那一页,也判成 hidden",
embed_api._field_perm(scoped_page({"pages#t2": "hidden"}), "pages", {}, "t2"), "hidden")
ok("藏的是别的那一页,这一页照旧露着",
embed_api._field_perm(scoped_page({"pages#t1": "hidden"}), "pages", {}, "t2") != "hidden",
embed_api._field_perm(scoped_page({"pages#t1": "hidden"}), "pages", {}, "t2"))
eq("两个环节里这一页有一个是露的,按露的算",
embed_api._field_perm([{"activity": "a1", "fields": [page], "perms": {"pages#t2": "hidden"}},
{"activity": "a2", "fields": [page], "perms": {}}], "pages", {}, "t2"),
"readonly")
ok("没带 slot 上来时不按页签判(那是标签页整格的权限)",
embed_api._field_perm(scoped_page({"pages#t2": "hidden"}), "pages", {}) != "hidden",
embed_api._field_perm(scoped_page({"pages#t2": "hidden"}), "pages", {}))
hidden_when = {"match": "all", "rules": [{"field": "kind", "op": "eq", "value": "框架合同"}]}
eq("联动条件把这格藏起来了,后端也不给地址",
embed_api._field_perm([{"activity": "a1", "fields": [dict(view, visibleWhen=hidden_when)],
"perms": {}}], "view", {"kind": "采购合同"}), "hidden")
ok("联动条件成立时照常露着",
embed_api._field_perm([{"activity": "a1", "fields": [dict(view, visibleWhen=hidden_when)],
"perms": {}}], "view", {"kind": "框架合同"}) != "hidden", "hidden")
eq("表单里根本没这一格时回空串(不拿它挡人)",
embed_api._field_perm([{"activity": "a1", "fields": [], "perms": {}}], "view", {}), "")
# ---------------------------------------------------------------------------
# 4. 设计期校验:配歪了要在保存那一刻说
# ---------------------------------------------------------------------------
def check_problems() -> None:
row = Source(url="https://erp.example.com/contract/detail?no={arg.contractNo}")
db = FakeDB(row)
keys = {"contractNo", "amount"}
eq("没选页面要挡", embed.problems(field(source=""), None, at="第 1 格「合同详情」"),
["第 1 格「合同详情」还没选择要嵌入哪个页面"])
ok("不查库时不说源的事(源没了不该让人存不下表单)",
embed.problems(field(), None, at="X", field_keys=keys) == [],
embed.problems(field(), None, at="X", field_keys=keys))
eq("源被删了要指名道姓",
embed.problems(field(source="gone"), FakeDB(), at="X")[0].startswith("X要嵌入的页面(gone)"), True)
ok("源不是可嵌入那一类要挡",
any("不是可嵌入页面" in line for line in embed.problems(field(), FakeDB(Source(provider="http")), at="X")))
ok("源停用**不在**设计期挡(管理员临时停一下不该连表单都存不下去)",
embed.problems(field(), db, at="X", field_keys=keys) == [],
embed.problems(field(), db, at="X", field_keys=keys))
bad = embed.problems(field(params={"salary": "{form.salary}"}), db, at="X", field_keys=keys)
ok("这个页面用不上这几个参数——最要紧的一句", any("用不上" in line for line in bad), bad)
eq("模板那一档:那句话指的地方是地址,花括号一对(与前端一字不差)",
[line for line in bad if "用不上" in line],
["X这几个参数「salary」这个页面用不上——地址里没写 {arg.名称},配了也不会拼进地址"])
blanked = embed.problems(field(params={"contractNo": " "}), db, at="X", field_keys=keys)
ok("参数只写了名字、取值写法空着要挡(那一位永远是空值,上游只回一句参数必填)",
any("没写取值写法" in line for line in blanked), blanked)
dangling = embed.problems(field(params={"contractNo": "{form.nope}"}), db, at="X", field_keys=keys)
ok("参数引用了不存在的字段要挡", any("引用了不存在的字段" in line for line in dangling), dangling)
ok("高度出格要挡", any("内嵌框高度" in line for line in
embed.problems(field(height=99999), db, at="X", field_keys=keys)))
eq("高度在区间内不吵", embed.problems(field(height=480), db, at="X", field_keys=keys), [])
ok("显示方式不认识要挡", any("显示方式" in line for line in
embed.problems(field(mode="popup"), db, at="X", field_keys=keys)))
ok("窄屏表现不认识要挡", any("窄屏" in line for line in
embed.problems(field(mobile="iframe"), db, at="X", field_keys=keys)))
ok("只读场合的表现不认识要挡", any("只读场合" in line for line in
embed.problems(field(readonly="yes"), db, at="X", field_keys=keys)))
eq("只读场合三档各配一遍都不吵",
[embed.problems(field(readonly=kind), db, at="X", field_keys=keys)
for kind in ("button", "auto", "frame")], [[], [], []])
ok("重复打开的表现不认识要挡", any("重复打开" in line for line in
embed.problems(field(reopen="every"), db, at="X", field_keys=keys)))
eq("重复打开配成每次新开不吵",
embed.problems(field(reopen="new"), db, at="X", field_keys=keys), [])
eq("重复打开配成整张单共用一页也不吵(那是新的默认)",
embed.problems(field(reopen="share"), db, at="X", field_keys=keys), [])
ok("这一页能不能操作那一档写歪了要挡",
any("能不能操作" in line for line in
embed.problems(field(interactive="maybe"), db, at="X", field_keys=keys)))
ok("sandbox 里写了白名单外的名字要挡(默默丢掉只会让人以为放开了)",
any("allow-modals" in line and "不认识" in line for line in
embed.problems(field(sandbox=["allow-modals", "allow-everything"]), db, at="X", field_keys=keys)))
eq("sandbox 写成清单内的那几项不吵",
embed.problems(field(sandbox=["allow-modals", embed.SANDBOX_TOP_CLICK]), db, at="X", field_keys=keys), [])
ok("sandbox 不是清单那一形状要挡",
any("要写成清单" in line for line in
embed.problems(field(sandbox="allow-modals"), db, at="X", field_keys=keys)))
wb = embed.problems(field(writeback={"enabled": True, "fields": ["amount", "ghost"]}),
db, at="X", field_keys=keys)
ok("回填白名单里不存在的格子要挡(那份清单就是权限边界)",
any("ghost" in line for line in wb), wb)
eq("回填点名的格子都在表单上就不吵",
embed.problems(field(writeback={"enabled": True, "fields": ["amount"]}), db, at="X", field_keys=keys),
[])
eq("没开回填时白名单不校验",
embed.problems(field(writeback={"enabled": False, "fields": ["ghost"]}), db, at="X", field_keys=keys),
[])
eq("writeback 关着就当没有", embed.writeback_fields_of(field(writeback={"enabled": False,
"fields": ["amount"]})), [])
eq("writeback 开着才认那份清单",
embed.writeback_fields_of(field(writeback={"enabled": True, "fields": ["amount", " "]})), ["amount"])
def check_helpers() -> None:
eq("高度配歪退回默认值", embed.height_of(field(height="不是数")), embed.DEFAULT_HEIGHT)
eq("高度超上界截到上界", embed.height_of(field(height=99999)), embed.MAX_HEIGHT)
eq("高度低于下界顶到下界", embed.height_of(field(height=10)), embed.MIN_HEIGHT)
eq("没配高度用默认", embed.height_of({}), embed.DEFAULT_HEIGHT)
eq("显示方式配歪退回 auto", embed.display_of(field(mode="popup")), embed.DISP_AUTO)
eq("窄屏默认只给按钮", embed.mobile_of({}), embed.MOBILE_BUTTON)
# 默认那一档从 button 换成了 auto:只读屏**该**把对方已有那一页直接显示出来,
# 而 auto 自己不会造代价(沿用一次接口都不打),所以配歪也退回它,不退回"什么都不问"
eq("只读场合默认只沿用已有那一页(不为看一眼去对方建页)",
embed.readonly_of({}), embed.READONLY_AUTO)
eq("只读场合写歪了退回同一档", embed.readonly_of(field(readonly="yes")), embed.READONLY_AUTO)
eq("写了 button 才是老的「一次都不问」", embed.readonly_of(field(readonly="button")),
embed.READONLY_BUTTON)
eq("写了 frame 才是一律自动加载", embed.readonly_of(field(readonly="frame")), embed.READONLY_FRAME)
eq("重复打开这一格默认认回**这张单**第一次那一页(换个人就是对面多一份草稿)",
embed.reopen_of({}), embed.REOPEN_SHARE)
eq("重复打开写歪了也回到这一档", embed.reopen_of(field(reopen="reuse")), embed.REOPEN_SHARE)
eq("写了 same 才退回旧的「每人各一趟」口径", embed.reopen_of(field(reopen="same")), embed.REOPEN_SAME)
eq("写了 new 才每次另起一趟", embed.reopen_of(field(reopen="new")), embed.REOPEN_NEW)
# 那一档真正管的是两件事,各判一句:换不换预受理号、换不换对面那一页。
# 合成一句判的写法迟早要把"共用一页"当成"共用凭据",那是另一种事故
eq("share 与 same 都认这个人自己那一趟(预受理号不换)",
[embed.reopen_reuses_trip(item) for item in embed.REOPENS], [True, True, False])
eq("只有 share 认这张单那一页(凭据各是各的,共用的是那一页)",
[embed.reopen_shares_page(item) for item in embed.REOPENS], [True, False, False])
eq("那一页默认能操作,写歪了也能操作", embed.interactive_of(field(interactive="readonly")),
embed.INTERACTIVE_FULL)
eq("写了 view 才只展示", embed.interactive_of(field(interactive="view")), embed.INTERACTIVE_VIEW)
eq("只许在发起那一屏点", embed.interactive_of(field(interactive="start")), embed.INTERACTIVE_START)
eq("跟着这一格在当前环节的可改性走", embed.interactive_of(field(interactive="perm")), embed.INTERACTIVE_PERM)
eq("四档之外一个都不认(少一档或多一档都是两边对不上)", len(embed.INTERACTIVES), 4)
eq("配成空串也算没配,退回能操作", embed.interactive_of(field(interactive=" ")), embed.INTERACTIVE_FULL)
eq("sandbox 没配只给那四项基础的", embed.sandbox_of({}), " ".join(embed.SANDBOX_BASE))
eq("sandbox 多给的几项按白名单顺序拼,清单外的丢掉",
embed.sandbox_of(field(sandbox=["allow-downloads", "allow-modals", "allow-scripts", "看心情"])),
" ".join([*embed.SANDBOX_BASE, "allow-modals", "allow-downloads"]))
eq("两条「整页跳走」同时给时只留不限时机的那一条",
embed.sandbox_extra_of(field(sandbox=[embed.SANDBOX_TOP_CLICK, embed.SANDBOX_TOP])),
[embed.SANDBOX_TOP])
eq("老表单没有这一段也不炸", embed.source_code_of({"key": "a"}), "")
ok("hub 这一档 P2 才开,现在必须说人话而不是猜",
embed.MODE_HUB not in embed.MODE_READY, embed.MODE_READY)
def check_open_gate() -> None:
"""那几格没填上就别让打开这一页:界面锁段头,后端不发那次注定挨一句 400 的请求。"""
eq("没写就是「填齐才让开」", embed.open_when_of(field()), embed.OPEN_FILLED)
eq("写歪了也按「填齐才让开」(宁可锁着,也别放人进一张打不开的页面)",
embed.open_when_of(field(openWhen="alwayz")), embed.OPEN_FILLED)
eq("写了 always 才是任何时候", embed.open_when_of(field(openWhen="always")), embed.OPEN_ALWAYS)
api = Source(url="https://reimb.example.com/api/create-link", url_mode=embed.URL_API,
body_template={"account": "{arg.applicant}", "project_number": "{arg.project}"})
cfg = field(params={"applicant": "{form.applicant}", "project": "{form.project}"})
eq("这一格配了参数名、这一次算出来是空的,点它的名",
embed.unfinished_args(api, cfg, {"applicant": "hsq"}), ["project"])
eq("都算出了值就一个都不点", embed.unfinished_args(api, cfg, {"applicant": "hsq", "project": "P-1"}), [])
eq("这个页面用不上的那几个参数不点(那是配歪了,由设计期那句管)",
embed.unfinished_args(api, field(params={"ghost": "{form.ghost}"}), {}), [])
eq("任何时候那一档后端跟着放行,不然那句「任何时候」是说一套做一套",
embed.unfinished_args(api, field(params={"applicant": "{form.applicant}"}, openWhen="always"), {}), [])
eq("地址模板那一档不拦:那边不发请求,空一位顶多是少一个查询参数",
embed.unfinished_args(Source(url="https://erp.example.com/p?no={arg.contractNo}"),
field(params={"contractNo": "{form.contractNo}"}), {}), [])
ok("那一句说清了缺哪几个、也说了不是程序坏了",
"还空着" in embed.unfinished_message(["applicant"]) and "不是程序坏了" in embed.unfinished_message(["applicant"]),
embed.unfinished_message(["applicant"]))
# ---------------------------------------------------------------------------
# 4b. 注册表那条记录保存那一刻的收尾检查
# ---------------------------------------------------------------------------
def check_clean_embed() -> None:
"""``provider=embed`` 那条记录存下去之前要过的几道,全部在 ``api/data_sources.py``。
这一处单独测:它是**界面**唯一能碰到的写入路径,报错是给人看的,
而且"还没开放的那一档"必须在这里就挡住,不该存下一条永远打不开的配置。
"""
from app.api import data_sources as api
def values(**over):
out = {"provider": models.DataSource.PROVIDER_EMBED, "page_mode": embed.MODE_NONE,
"app_code": "", "direction": models.DataSource.DIRECTION_IN,
"url": "https://erp.example.com/p?no={arg.no}"}
out.update(over)
return out
def refused(v, want: str) -> None:
try:
api._clean_embed(v)
except Exception as exc: # noqa: BLE001 - 只看它拦不拦、说的是哪一句
ok(f"挡下来说的是「{want}」", want in str(exc), str(exc))
return
ok("该挡的没挡", False, f"{want}:居然后续存下去了")
eq("正常那条一个字都不改", api._clean_embed(values(page_mode=embed.MODE_TICKET, app_code="ERP"))["page_mode"],
embed.MODE_TICKET)
refused(values(page_mode="magic"), "免登方式只支持")
refused(values(page_mode=embed.MODE_HUB), "还没开放")
refused(values(direction=models.DataSource.DIRECTION_OUT), "不能当写回通道")
refused(values(url="http://erp.example.com/p"), "要用 https")
refused(values(url_mode="magic"), "地址来源只支持")
refused(values(url_mode=embed.URL_API), "链接在接口返回的哪一栏")
refused(values(url_mode=embed.URL_API, url_path="data.url", url_origins=["docs.example.com"]),
"要写成 https://主机")
eq("接口那一档的来源清单会归一化",
api._clean_embed(values(url_mode=embed.URL_API, url_path="data.url",
url_origins=["https://docs.example.com/"]))["url_origins"],
["https://docs.example.com"])
eq("切回模板那一档就把样例清空(留着它会悄悄顶掉真接口)",
api._clean_embed(values(url_mode=embed.URL_API, url_path="data.url",
mock_payload={"data": {"url": "https://erp.example.com/x"}}))["mock_payload"],
{"data": {"url": "https://erp.example.com/x"}})
eq("切回模板那一档就把样例清空(留着它会悄悄顶掉真接口)",
api._clean_embed(values(url_mode=embed.URL_TEMPLATE,
mock_payload={"data": {"url": "https://erp.example.com/x"}}))["mock_payload"], {})
# 切回别的通道时不清 page_mode / app_code:临时试个通道不该把人配好的免登口径一起带走
kept = api._clean_embed(values(provider="http", page_mode=embed.MODE_TICKET, app_code="ERP"))
eq("换回 http 通道不动那两格", (kept["page_mode"], kept["app_code"]), (embed.MODE_TICKET, "ERP"))
# 短码免登离了那把共享密钥就是废的,缺了当场说,别等人在表单上点开
try:
api._need_embed_key(values(page_mode=embed.MODE_TICKET), "")
ok("短码免登缺密钥要挡", False, "居然放过去了")
except Exception as exc: # noqa: BLE001
ok("短码免登缺密钥要挡", "应用密钥" in str(exc), str(exc))
api._need_embed_key(values(page_mode=embed.MODE_NONE), "")
api._need_embed_key(values(page_mode=embed.MODE_TICKET), "一把密钥")
# ---------------------------------------------------------------------------
# 4c. 回填白名单:外面那个页面能改这张单的哪几格
# ---------------------------------------------------------------------------
def check_writeback() -> None:
"""``writeback`` 那份清单的判据(方案 §5 第三条)。
这道判断只能全部压在**保存**这一刻:提交时后端拿到的是 ``data``,它没法分辨某个值是
人在框里敲的还是 iframe 写进来的。所以"挂额度与阈值的格子一律不收"这一条必须在设计期
挡住——那是这张单被外部系统写歪的唯一入口(红线:外部系统只能提供值,不能决定流转)。
"""
text = {"key": "no", "type": "text"}
layout = {"key": "g", "type": "group"}
auto = {"key": "no1", "type": "auto"}
with_quota = {"key": "budget", "type": "money", "quota": {"def": "Q1"}}
with_threshold = {"key": "over", "type": "number", "threshold": {"op": "gt"}}
fields = [text, layout, auto, with_quota, with_threshold]
eq("普通文本格收", embed.writeback_refusal(text), "")
ok("版面那一类不收", "不存值" in embed.writeback_refusal(layout), embed.writeback_refusal(layout))
ok("系统带出那一类不收", "不存值" in embed.writeback_refusal(auto), embed.writeback_refusal(auto))
ok("挂了额度的一律不收", "不能决定流转" in embed.writeback_refusal(with_quota),
embed.writeback_refusal(with_quota))
ok("挂了阈值的一律不收", "不能决定流转" in embed.writeback_refusal(with_threshold),
embed.writeback_refusal(with_threshold))
picked = field(writeback={"enabled": True, "fields": ["no", "budget", "no1", "ghost"]})
eq("清单里只留收得下的那几个", embed.writeback_targets(picked, fields), ["no"])
eq("没开回填就当没有这份清单",
embed.writeback_targets(field(writeback={"enabled": False, "fields": ["no"]}), fields), [])
out = embed.problems(picked, None, at="X", field_keys={"no", "g", "no1", "budget", "over"}, targets=fields)
joined = ";".join(out)
ok("额度那一格点名说收不下", "「budget」收不下" in joined and "不能决定流转" in joined, out)
ok("找不到的那格照说", "「ghost」在表单上找不到" in joined, out)
ok("收得下的那格不说", "「no」" not in joined, out)
# 只给 keys、没给字段清单的调用方:存在性照判,"收不收得下"不说——手上没有那一格的样子,别瞎判
both = field(writeback={"enabled": True, "fields": ["budget", "ghost"]})
eq("没给字段清单时存在性照判", embed.problems(both, None, at="X", field_keys={"budget"}),
["X要回填的字段「ghost」在表单上找不到"])
eq("没给字段清单时不说收不下",
embed.problems(both, None, at="X", field_keys={"budget", "ghost"}), [])
many = field(writeback={"enabled": True, "fields": [f"k{index}" for index in range(embed.MAX_WRITEBACK + 3)]})
ok("点太多也要说", "个回填字段,现在点了" in ";".join(
embed.problems(many, None, at="X", field_keys=None)), embed.problems(many, None, at="X", field_keys=None))
eq("全收得下就一句都不说",
embed.problems(field(writeback={"enabled": True, "fields": ["no"]}), None, at="X",
field_keys={"no"}, targets=fields), [])
# 对应表:对方回传里那个键不叫 OA 这个名时的那份对应(前端 utils/formRuntime.ts 同名函数同一算法)
eq("同名与对应表合成一份规则",
embed.writeback_rules(field(writeback={"enabled": True, "fields": ["no"],
"map": {"invoice_no": "budget", "ht": "no"}})),
[{"from": "no", "to": "no"}, {"from": "invoice_no", "to": "budget"}, {"from": "ht", "to": "no"}])
eq("对方那个键撞上同名时对应表赢",
embed.writeback_rules(field(writeback={"enabled": True, "fields": ["no"], "map": {"no": "budget"}})),
[{"from": "no", "to": "budget"}])
eq("对应表里的目标也算被点过名",
embed.writeback_targets(field(writeback={"enabled": True, "map": {"invoice_no": "no"}}), fields), ["no"])
eq("没开回填时对应表整个不认",
embed.writeback_rules(field(writeback={"enabled": False, "map": {"invoice_no": "no"}})), [])
eq("写歪的那几条留着给人点名",
embed.writeback_map_of(field(writeback={"enabled": True, "map": {"": "no", "invoice_no": ""}})),
[("", "no"), ("invoice_no", "")])
messy = ";".join(embed.problems(
field(writeback={"enabled": True, "fields": ["no"], "map": {"": "budget", "invoice_no": "", "also": "no"}}),
None, at="X", field_keys={"no", "budget"}, targets=fields))
ok("没写对方键名的那条点名说", "回填对应里有一条没写对方那个字段叫什么(要写进「budget」)" in messy, messy)
ok("没写落到哪一格的那条点名说", "「invoice_no」那条对应没写要写进哪一格" in messy, messy)
ok("一格被两条对应同时指着要挡", "「no」这一格被两条对应同时指着(no、also)" in messy, messy)
eq("走对应表那几条报错时带上对方那个键",
embed.problems(field(writeback={"enabled": True, "map": {"invoice_no": "budget"}}), None, at="X",
field_keys={"budget"}, targets=fields),
["X「invoice_no」要写进的那一格「budget」收不下:" + embed.writeback_refusal(with_quota)])
clean = [text, {"key": "amount", "type": "money"}]
eq("对应表配得干净就一句都不说",
embed.problems(field(writeback={"enabled": True, "fields": ["no"], "map": {"invoice_no": "amount"}}), None,
at="X", field_keys={"no", "amount"}, targets=clean), [])
# 那几把尺子两边各写了一份,数字必须一样(前端读的是 utils/formRuntime.ts 与 embedBridge.ts)
root = pathlib.Path(__file__).resolve().parents[2]
front_runtime = (root / "frontend/src/utils/formRuntime.ts").read_text(encoding="utf-8")
front_bridge = (root / "frontend/src/utils/embedBridge.ts").read_text(encoding="utf-8")
def front_number(text: str, name: str) -> str:
found = re.search(rf"export const {name} = (\d+)", text)
return found.group(1) if found else "(前端找不到这个常量)"
eq("回填字段个数上限两边一个数", str(embed.MAX_WRITEBACK), front_number(front_runtime, "EMBED_MAX_WRITEBACK"))
eq("一句回填最多几个键", str(embed.RESULT_MAX_KEYS), front_number(front_bridge, "EMBED_RESULT_MAX_KEYS"))
eq("单个回填值最多多少字", str(embed.RESULT_MAX_CHARS), front_number(front_bridge, "EMBED_RESULT_MAX_CHARS"))
eq("框高下界两边一个数", str(embed.RESIZE_MIN), front_number(front_bridge, "EMBED_RESIZE_MIN"))
eq("框高上界两边一个数", str(embed.RESIZE_MAX), front_number(front_bridge, "EMBED_RESIZE_MAX"))
# ---------------------------------------------------------------------------
# 4d. 地址由对方接口现给(url_mode=api)
# ---------------------------------------------------------------------------
def check_dynamic_link() -> None:
"""``url_mode=api``:先调接口拿链接,再嵌那一条。
这一档只该多一件事——**地址从哪来**,别的都不能松。所以钉这五条:
参数白名单要把请求体一起算上;取回来的链接只认登记过的来源;取不到链接时
要说得出该往哪一栏改;样例响应能顶掉真接口(并一直提醒着);成没成都落一条
``kind=link`` 的痕。
"""
from app.service import fetch
row = Source(url="https://erp.example.com/api/page-link", url_mode=embed.URL_API,
url_path="data.url", body_template={"no": "{arg.contractNo}", "who": "{arg.operator}"})
eq("接口这一档的白名单把请求体也算上", sorted(embed.declared_args(row)), ["contractNo", "operator"])
eq("模板那一档还是只数地址",
sorted(embed.declared_args(Source(url="https://erp.example.com/p?no={arg.no}&x={arg.x}"))), ["no", "x"])
eq("来源模式认错一律按模板算(不去猜该往哪儿打)",
embed.url_mode_of(Source(url_mode="magic")), embed.URL_TEMPLATE)
# 那句"参数写在哪"要跟着档位换:接口那一档的参数不拼地址,还让人去地址栏找只会白跑
odd = embed.problems(field(params={"salary": "{form.salary}"}), FakeDB(row), at="X",
field_keys={"salary"})
ok("接口那一档那句改口说接口地址与请求头、请求体",
any("接口地址、请求头、请求体里都没写" in line and "配了也不会带过去" in line for line in odd), odd)
eq("允许的来源留空 = 只认接口自己那一台", embed.allowed_origins(row), ["https://erp.example.com"])
eq("多写的斜杠与空格各归各位,认不出的先点名",
embed.clean_origins(["https://docs.example.com/ http://127.0.0.1:5173", "docs.example.com"]),
["http://127.0.0.1:5173", "https://docs.example.com"])
ok("认不出的那条要说出来,不能悄悄丢掉",
"docs.example.com" in embed.origins_problem(["docs.example.com", "https://a.example.com"]),
embed.origins_problem(["docs.example.com", "https://a.example.com"]))
eq("写法都对就一句不说", embed.origins_problem(["https://a.example.com"]), "")
eq("接口自己那台的链接放行", embed.link_origin_problem(row, "https://erp.example.com/view?k=1"), "")
ok("没登记的域名挡下来", "不在这张源允许的来源里" in embed.link_origin_problem(row, "https://evil.example.com/p"),
embed.link_origin_problem(row, "https://evil.example.com/p"))
ok("接口回了个 http 的地址也照 https 那把尺子挡", "https" in embed.link_problem("http://erp.example.com/p"),
embed.link_problem("http://erp.example.com/p"))
eq("样例那一档不受影响:模板源不该来取链接",
embed.resolve_link(FakeDB(Source()), Source(), {})["error"], "这张源配的是地址模板,不该走取链接这一条路")
sent: dict = {}
reply: dict = {"status": 200, "text": '{"code":0,"data":{"url":"https://erp.example.com/view?k=abc"}}'}
def fake_request(method, url, body, headers, timeout, **_kwargs):
sent.clear()
sent.update(method=method, url=url, body=(body or b"").decode("utf-8"),
auth=headers.get("Authorization", ""), accept=headers.get("Accept", ""))
return int(reply["status"]), {}, str(reply["text"]), str(url)
original = fetch.http_request_full
fetch.http_request_full = fake_request
try:
db = FakeDB(row)
got = embed.resolve_link(db, row, {"contractNo": "HT-1", "operator": "zhang"}, work=None)
eq("按配好的位置取出链接", got["url"], "https://erp.example.com/view?k=abc")
ok("取到了就不带原因", got["ok"] and not got["error"], got)
eq("请求体里 {arg.x} 换成了真值", sent["body"], '{"no": "HT-1", "who": "zhang"}')
eq("方法跟着源上那格走", sent["method"], "POST")
eq("留痕落的是 kind=link", [line.kind for line in db.added], ["link"])
eq("留痕里没有参数值", db.added[0].args["keys"], ["contractNo", "operator"])
# 只回一个路径也是常见写法:按接口那条地址补全来源,而不是当它是非法地址
reply["text"] = '{"data":{"url":"/view?k=1"}}'
eq("只回路径时按接口地址补全",
embed.resolve_link(FakeDB(row), row, {})["url"], "https://erp.example.com/view?k=1")
# 取不到链接:要说清"要的是哪一栏",并把这份响应里像链接的位置念出来
reply["text"] = '{"code":0,"data":{"link":"https://erp.example.com/view?k=1"}}'
missed = embed.resolve_link(FakeDB(row), row, {})
ok("取不到链接时说清了要的是哪一栏", "data.url" in missed["error"], missed["error"])
ok("顺手把像链接的位置念出来", "data.link" in missed["error"], missed["error"])
reply["text"] = '{"data":{"url":{"a":1}}}'
ok("取到的不是字符串也要说人话", "不是一条地址" in embed.resolve_link(FakeDB(row), row, {})["error"],
embed.resolve_link(FakeDB(row), row, {})["error"])
reply["text"] = '{"code":0,"data":{"url":"https://evil.example.com/p"}}'
ok("接口回一个没登记的域名,整件事就停在这儿",
"不在这张源允许的来源里" in embed.resolve_link(FakeDB(row), row, {})["error"])
# 4xx 是我们的事:那一句要点名这次哪几个入参压根是空的(对方回 "x is required"
# 时,看的人第一反应是怪对方,真凶通常在那一格没配取值写法)
reply["status"], reply["text"] = 400, '{"code":400,"message":"no is required"}'
partial = embed.resolve_link(FakeDB(row), row, {"operator": "zhang"}, work=None)
ok("接口回 4xx 时点出哪几个入参是空的",
"400" in partial["error"] and "是空的" in partial["error"] and "contractNo" in partial["error"],
partial["error"])
ok("补的那一句里不许带参数值", "zhang" not in partial["error"], partial["error"])
reply["status"], reply["text"] = 500, "boom"
failed = embed.resolve_link(FakeDB(row), row, {})
ok("上游 5xx 要说清是它回了 500", "500" in failed["error"], failed["error"])
ok("5xx 是对方病了,不顺带怀疑自己的参数", "是空的" not in failed["error"], failed["error"])
reply["status"], reply["text"] = 200, "not json at all"
ok("回的不是 JSON 也要说一句", "不是 JSON" in embed.resolve_link(FakeDB(row), row, {})["error"])
# GET 不带请求体:多带那一份在不少网关那儿直接是 400
get_row = Source(url="https://erp.example.com/api/page-link?a={arg.no}", url_mode=embed.URL_API,
url_path="data.url", method="GET", body_template={"no": "{arg.no}"})
reply["status"], reply["text"] = 200, '{"data":{"url":"https://erp.example.com/view"}}'
embed.resolve_link(FakeDB(get_row), get_row, {"no": "HT-9"})
eq("GET 不发请求体", sent["body"], "")
eq("地址上的 {arg.x} 照样换", sent["url"], "https://erp.example.com/api/page-link?a=HT-9")
# 鉴权那一格对这一档同样有意义(调那个接口要带头)
keyed = Source(url="https://erp.example.com/api/page-link", url_mode=embed.URL_API,
url_path="data.url", auth_type=models.DataSource.AUTH_BEARER, auth_secret="s3cr3t")
embed.resolve_link(FakeDB(keyed), keyed, {})
eq("密钥按鉴权方式带出去了", sent["auth"], "Bearer s3cr3t")
# 样例响应顶掉真接口(对方还没开发完时先配通),并且一次都不打出去
sampled = Source(url="https://erp.example.com/api/page-link", url_mode=embed.URL_API,
url_path="data.url",
mock_payload={"data": {"url": "https://erp.example.com/mock/{arg.no}"}})
sent.clear()
got2 = embed.resolve_link(FakeDB(sampled), sampled, {"no": "HT-7"})
eq("样例响应里 {arg.x} 也换", got2["url"], "https://erp.example.com/mock/HT-7")
eq("用了样例就一次都没外呼", sent, {})
# 熔断开着的时候一次都不该打出去,也不该再往账上加
blocked = Source(url="https://erp.example.com/api/page-link", url_mode=embed.URL_API, url_path="data.url")
blocked.open_until = models.localnow() + timedelta(minutes=1)
sent.clear()
stopped = embed.resolve_link(FakeDB(blocked), blocked, {})
ok("熔断开着就直接说别打,且没有外呼", "刚连续失败" in stopped["error"] and not sent, stopped["error"])
eq("被自家闸挡住的不写库里的失败账", blocked.fail_count, 0)
# build_url 这一档拼出来的是刚取到的那条,并明说是动态的
built = embed.build_url(FakeDB(row), row, {"contractNo": "HT-1"}, person="P1")
eq("发票据那一档以外也照用接口回的地址", built["url"], "https://erp.example.com/view")
ok("地址是现取的要标出来", built["dynamic"] is True, built)
reply["text"] = '{"data":{"url":"https://evil.example.com/p"}}'
try:
embed.build_url(FakeDB(row), row, {}, person="P1")
ok("取不到链接要挡在发地址这一步", False, "居然回了一条地址")
except embed.LinkError as exc:
ok("取不到链接要挡在发地址这一步", "允许的来源" in str(exc), str(exc))
finally:
fetch.http_request_full = original
# ---------------------------------------------------------------------------
# 5. 免登短码
# ---------------------------------------------------------------------------
def check_ticket() -> None:
eq("参数指纹与顺序无关",
embed.args_digest_of({"a": "1", "b": "2"}), embed.args_digest_of({"b": "2", "a": "1"}))
ok("参数值换了指纹就变",
embed.args_digest_of({"a": "1"}) != embed.args_digest_of({"a": "2"}))
eq("空参数也有个指纹", embed.args_digest_of({}), embed.args_digest_of(None))
db = FakeDB(Source(page_mode=embed.MODE_NONE))
built = embed.build_url(db, db.rows[0], {"no": "HT-1"}, person="P1")
eq("none 模式不掺短码", built["url"], "https://erp.example.com/contract/detail")
eq("none 模式不说存活秒数", built["ttl"], 0)
eq("发地址这一步不写库", db.added, [])
hub = Source(page_mode=embed.MODE_HUB)
try:
embed.build_url(FakeDB(hub), hub, {}, person="P1")
ok("hub 模式要明说没开", False, "居然拼出地址了")
except embed.HubNotReady as exc:
ok("hub 模式要明说没开", "还没开放" in str(exc), str(exc))
ticket_row = Source(page_mode=embed.MODE_TICKET)
try:
embed.build_url(FakeDB(ticket_row), ticket_row, {}, person="")
ok("ticket 模式没有身份就不发地址", False, "没有 person 也拼下去了")
except ValueError as exc:
eq("ticket 模式没有身份就不发地址", str(exc), "EMBED_NEED_PERSON")
# 短码放在 # 之后:浏览器不会把片段发给第三方,也不写进 Referer 和服务端访问日志
db2 = FakeDB(ticket_row)
built2 = embed.build_url(db2, ticket_row, {"no": "HT-1"}, person="P1", work="W1")
ok("短码在 # 之后,不在查询串里", "#ticket=" in built2["url"] and "?ticket=" not in built2["url"],
built2["url"])
eq("查询串里原有的参数还在", built2["url"].split("#")[0], "https://erp.example.com/contract/detail")
eq("票据行只存哈希", len(db2.added[0].code_hash), 64)
ok("库里不留明文短码", "#ticket=" not in str(getattr(db2.added[0], "code_hash", "")),
db2.added[0].code_hash)
eq("票据绑在这个人身上", db2.added[0].person, "P1")
eq("票据绑在这条源上", db2.added[0].source, ticket_row.code)
# 接口回的链接常常自己就带片段(SPA 的 #/contract/1)。这时候再拼一个 # 上去,
# 浏览器只认第一个片段,短码连同它后面那一段会一起被丢掉
hashed = Source(url="https://erp.example.com/contract/detail#/view", page_mode=embed.MODE_TICKET)
built3 = embed.build_url(FakeDB(hashed), hashed, {}, person="P1")
eq("地址只留一个 #", built3["url"].count("#"), 1)
ok("带片段的地址也挂得上短码", "&ticket=" in built3["url"], built3["url"])
ok("存活秒数在配置的区间里", embed.ticket_ttl_seconds() > 0, embed.ticket_ttl_seconds())
# ---------------------------------------------------------------------------
# 6. 留痕里没有参数值
# ---------------------------------------------------------------------------
def check_log() -> None:
row = Source()
db = FakeDB(row)
embed.log_open(db, row, actor=None, work="W1", job="JOB1", activity="A1",
args={"contractNo": "HT-001", "idcard": "330102199001010011"})
line = db.added[0]
eq("留痕落在取数那张表上(同一件事不查两个地方)", line.kind, "embed")
eq("参数只留键名", line.args["keys"], ["contractNo", "idcard"])
eq("值换成指纹", line.args["digest"], embed.args_digest_of(
{"contractNo": "HT-001", "idcard": "330102199001010011"}))
dumped = repr(vars(line))
ok("身份证号不落进日志", "330102199001010011" not in dumped, "值出现在留痕里")
ok("单据号也不落进日志", "HT-001" not in dumped, "值出现在留痕里")
# ---------------------------------------------------------------------------
# 7. CSP:frame-src 白名单
# ---------------------------------------------------------------------------
def check_frame_src() -> None:
embed.cache_urls()
api_row = Source(url="https://erp.example.com/api/page-link", url_mode=embed.URL_API,
url_path="data.url", url_origins=["https://docs.example.com"], enabled=True)
value = embed.frame_src(FakeDB(api_row), refresh=True)
ok("接口那一档:接口自己那台进白名单", "https://erp.example.com" in value, value)
ok("接口那一档:登记的那几台也进白名单", "https://docs.example.com" in value, value)
value = embed.frame_src(FakeDB(Source(url="https://erp.example.com/p?no={arg.no}")), refresh=True)
ok("'self' 必须在", "'self'" in value, value)
ok("blob: 必须留着,否则附件 PDF 预览整块打不开", "blob:" in value, value)
ok("启用中的页面来源进白名单", "https://erp.example.com" in value, value)
embed.cache_urls()
off = embed.frame_src(FakeDB(Source(enabled=False, url="https://gone.example.com/p")), refresh=True)
ok("源停用之后白名单里就没有它了", "gone.example.com" not in off, off)
embed.cache_urls()
weird = embed.frame_src(FakeDB(Source(url="不是个地址"), Source(url="")), refresh=True)
eq("地址读不出形状时只剩兜底那两项", weird, "'self' blob:")
# 这一条看着小,栽过一次:配置项没写值时那个空清单被 str() 成了 "()",
# 于是 frame-src 里混进一个非法来源,整条头在严格解析下就不作数了
eq("没配置的兜底项就是空清单,不会变成 ('()',)", tuple(settings.embed_frame_extra or ()), ())
eq("环境变量那一串逗号照旧切开", config._coerce("https://a,,https://b ", ()),
("https://a", "https://b"))
eq("配置文件写成数组也照收", config._coerce(["https://a", " https://b "], ()),
("https://a", "https://b"))
# 注册表之外还能兜一个来源(个别环境要留一个不在注册表里的地址),验的是它真进得去
original = embed.settings
try:
embed.settings = types.SimpleNamespace(embed_frame_extra=("https://extra.example.com",))
embed.cache_urls()
extra = embed.frame_src(FakeDB(), refresh=True)
ok("注册表之外那个兜底来源进得了 CSP", "https://extra.example.com" in extra, extra)
finally:
embed.settings = original
# 中间件那一条路径:缓存热着的时候不该再碰库(每一个响应都要这个值)
embed.cache_urls()
warmed = embed.frame_src(FakeDB(Source(url="https://erp.example.com/p")), refresh=True)
ok("缓存热着就不需要库", embed.frame_src_cached(None) == warmed, embed.frame_src_cached(None))
embed.cache_urls()
multi = embed.frame_src(FakeDB(Source(url="https://b.example.com/p"),
Source(code="hr", url="https://a.example.com/p")), refresh=True)
ok("白名单是排过序的(同样的库永远拼出同一串头)",
multi.index("https://a.example.com") < multi.index("https://b.example.com"), multi)
embed.cache_urls()
# ---------------------------------------------------------------------------
# 8. 前后端措辞对齐
# ---------------------------------------------------------------------------
#: 两边各写一遍、必须一字不差的几句:一份写在后端,一份镜像在前端
PARALLEL: list[tuple[tuple[str, str], list[str]]] = [
(("backend/app/service/embed.py", "frontend/src/utils/formRuntime.ts"),
["还没选择要嵌入哪个页面",
"这个页面用不上",
"配了也不会拼进地址",
"接口地址、请求头、请求体里都没写",
"配了也不会带过去",
"只写了名字、没写取值写法",
"的内嵌框高度要在 ",
"px 之间",
"在表单上找不到",
"收不下:",
"个回填字段,现在点了",
"回填对应里有一条没写对方那个字段叫什么",
"那条对应没写要写进哪一格",
"这一格被两条对应同时指着",
"要写进的那一格",
"这一格不存值(它是版面或系统带出的那一类),外部页面回填不进去",
"这一格挂着额度控制,外部页面不能往里写——外部系统只能提供值,不能决定流转",
"这一格挂着阈值规则,外部页面不能往里写——外部系统只能提供值,不能决定流转"]),
# 界面那几句是人话版本,措辞跟着后端那句走,别各说一套
(("backend/app/service/embed.py", "frontend/src/i18n/locales/zh.ts"),
["已被管理员停用", "暂时打不开", "已经不在了", "不是程序坏了"]),
(("backend/app/service/embed.py", "frontend/src/components/oa/design/EmbedPanel.vue"),
["还没选择要嵌入哪个页面"]),
]
def check_wording_parity() -> None:
"""同一句判据在两边各写了一份(前端拿不到库,只能自己算),措辞必须一样。"""
root = pathlib.Path(__file__).resolve().parents[2]
for (backend_file, frontend_file), phrases in PARALLEL:
right = root / frontend_file
if not right.exists():
print(f"[跳过] 找不到前端那份 {right}(只部署后端时正常)")
continue
left_text = (root / backend_file).read_text(encoding="utf-8")
right_text = right.read_text(encoding="utf-8")
for phrase in phrases:
missing = "后端缺" if phrase not in left_text else ""
if phrase not in right_text:
missing = missing or "前端缺"
ok(f"「{phrase}」前后端都在", not missing, f"{missing}:{backend_file} / {frontend_file}")
# ---------------------------------------------------------------------------
# 这一页能让 OA 做哪几件事 / 第三方回写的落点
# (docs/embed-action-design.md:未保存时怎么对上话、怎么触发发起、怎么回写审批)
# ---------------------------------------------------------------------------
def check_actions() -> None:
"""动作那一档:失败即关、顺序稳定、认不出的名字不长出按钮。"""
eq('没配 = 一个动作都不开放', embed.actions_allowed({'embed': {}}), [])
eq('整档没开 = 一个都不开放',
embed.actions_allowed({'embed': {'actions': {'allow': ['submit']}}}), [])
eq('开放清单按固定顺序回(界面与留痕都按它排)',
embed.actions_allowed({'embed': {'actions': {'enabled': True, 'allow': ['decide', 'submit']}}}),
['submit', 'decide'])
eq('认不出的动作名直接丢,不往清单里带',
embed.actions_allowed({'embed': {'actions': {'enabled': True, 'allow': ['submit', 'delete']}}}),
['submit'])
ok('一个都没勾要说一句', bool(embed.actions_problem(
{'embed': {'actions': {'enabled': True}}})))
ok('勾了却没写全也要说', bool(embed.actions_problem(
{'embed': {'actions': {'enabled': True, 'allow': []}}})))
ok('认不出的名字要说一句', '认不出来' in embed.actions_problem(
{'embed': {'actions': {'enabled': True, 'allow': ['nope']}}}))
eq('开着且勾对了就没话说',
embed.actions_problem({'embed': {'actions': {'enabled': True, 'allow': ['submit']}}}), '')
# 默认必须确认。写成默认关是很顺手的,而它的失效方式是"对方页面一次误触发出一张单"
eq('没配 = 要确认', embed.actions_confirm({'embed': {}}), True)
eq('配了 true = 要确认',
embed.actions_confirm({'embed': {'actions': {'enabled': True, 'confirm': True}}}), True)
eq('只有明着关掉才不确认',
embed.actions_confirm({'embed': {'actions': {'enabled': True, 'confirm': False}}}), False)
# 设计期校验要真的挂进 problems(),否则这一档配歪了要到填单页才看得见
bad = embed.problems(field(actions={'enabled': True, 'allow': []}), FakeDB(), at='X',
field_keys={'contractNo'})
ok('设计期就要说了:开了整档却没勾动作', any('一个动作都没勾' in item for item in bad), bad)
ok('动作配对了就不吵', embed.problems(
field(actions={'enabled': True, 'allow': ['submit']}), FakeDB(), at='X',
field_keys={'contractNo'}), [])
def check_decision_words() -> None:
"""对方那套状态词怎么翻:只翻到三种结论,翻不出来原样交回,绝不直接映射到出口名。"""
from app.service import embed_session as session_svc
cfg = {'embed': {'actions': {'enabled': True, 'allow': ['decide'], 'decisions': {
'APPROVED': 'agree', 'rejected': 'REFUSE', ' 退回 ': 'submit', '空值': '', '没这档': '走错分支'}}}}
eq('键与值两边都不计较大小写,空键丢掉,翻不出那三种结论的一律不收',
embed.decision_map_of(cfg), {'approved': 'agree', 'rejected': 'refuse', '退回': 'submit'})
eq('没配就是只认那三个词', embed.decision_map_of({'embed': {}}), {})
mapping = embed.decision_map_of(cfg)
eq('原样命中优先(agree 就是 agree,不必再配一条自己映射自己)',
session_svc.decision_kind('agree', mapping), 'agree')
eq('对方写大写也能翻成同意', session_svc.decision_kind('APPROVED', mapping), 'agree')
eq('对方写小写也能翻成不同意', session_svc.decision_kind('Rejected', mapping), 'refuse')
eq('翻不出来的原样交回给出口匹配那一步——那儿会把候选念给对方听',
session_svc.decision_kind('RETURNED', mapping), 'RETURNED')
eq('没配对照表时大写也不认,交回原词', session_svc.decision_kind('APPROVED', None), 'APPROVED')
eq('空词就是空', session_svc.decision_kind('', mapping), '')
# 表里配了内置写法,就以表为准:这一格的配置比内置那几个词更知道对方在说什么
mapping2 = embed.decision_map_of({'embed': {'actions': {'enabled': True, 'allow': ['decide'],
'decisions': {'AGREE': 'submit'}}}})
eq('表里把 AGREE 配成提交:翻成 submit,不再原样命中内置的 agree',
session_svc.decision_kind('AGREE', mapping2), 'submit')
eq('表里没写的内置写法照旧原样命中', session_svc.decision_kind('refuse', mapping2), 'refuse')
# 配歪了要说:映射到出口名这一步不开放,说清楚比让人猜强
bad = embed.actions_problem({'embed': {'actions': {'enabled': True, 'allow': ['decide'],
'decisions': {'PASS': '通过'}}}})
ok('把对方状态词直接映射成出口名要当场挡', '只能翻成' in bad, bad)
eq('配对了就没话说', embed.actions_problem(
{'embed': {'actions': {'enabled': True, 'allow': ['decide'], 'decisions': {'PASS': 'agree'}}}}), '')
blocked = embed.problems(field(actions={'enabled': True, 'allow': ['decide'],
'decisions': {'PASS': '通过'}}), FakeDB(), at='X',
field_keys={'contractNo'})
ok('这一条也要挂进设计期校验', any('只能翻成' in item for item in blocked), blocked)
def check_writeback_scopes() -> None:
"""回写开放哪几档:由后端算,前端与第三方都只是被告知。"""
from app.service import embed_session as session_svc
keyed = Source('erp_contract', page_mode=embed.MODE_TICKET, app_code='ERP',
auth_secret='s' * 32, url='https://erp.example.com/c?a={arg.no}')
plain = Source('erp_contract', url='https://erp.example.com/c?a={arg.no}')
open_page = {'key': 'page', 'embed': {
'writeback': {'enabled': True, 'fields': ['amount']},
'actions': {'enabled': True, 'allow': ['submit', 'decide']},
}}
task = types.SimpleNamespace(id='t1')
eq('回填开着才有 prefill',
session_svc.scopes_for(keyed, open_page, task=task),
['prefill', 'start', 'decide'])
eq('没配密钥的系统不配替人表态',
session_svc.scopes_for(plain, open_page, task=task), ['prefill'])
eq('没开免登短码也一样:凭据不能只从浏览器绕',
session_svc.scopes_for(Source('erp_contract', auth_secret='s' * 32,
url='https://erp.example.com/c?a={arg.no}'),
open_page, task=task), ['prefill'])
eq('已经有单据就没有"再发起一次"这一档',
session_svc.scopes_for(keyed, open_page, task=task, has_work=True), ['prefill', 'decide'])
eq('这个人在这一环没有待办,就没有提交这一档',
session_svc.scopes_for(keyed, open_page, task=None), ['prefill', 'start'])
eq('动作没勾就一档都不多给',
session_svc.scopes_for(keyed, {'embed': {'writeback': {'enabled': True, 'fields': ['a']}}},
task=task), ['prefill'])
# 回写表单值:白名单是后端给的,不在清单里的一个都不收,而且不收在入库之前
row = _StubSession()
out = session_svc.apply_prefill(_StubDb(), row, {'amount': '1200', 'salary': '9'},
allowed=['amount'])
eq('没收下的那个键要被点名', out['rejected'], ['salary'])
eq('收下的只回字段名,不回值', out['accepted'], ['amount'])
eq('值留在这一趟上,没往单据上写', row.result['prefill'], {'amount': '1200'})
empty = session_svc.apply_prefill(_StubDb(), _StubSession(), {'amount': '1'}, allowed=[])
eq('白名单是空的就一条都不收(失败即关)', empty['accepted'], [])
ok('一条都没收也要说没收下几个', empty['rejected'] == ['amount'], empty)
def check_decision_route() -> None:
"""第三方那句"审完了"落到哪条出口:匹不上就说不清,绝不替它赌方向。"""
from app.service import embed_session as session_svc
eq('只有一个出口时 submit 就够', session_svc.match_route(['同意'], decision='submit')[0], '同意')
eq('出口名给准了就用准的',
session_svc.match_route(['同意', '不同意'], route='不同意')[0], '不同意')
eq('「不同意」里含着「同意」也不能被匹成同意',
session_svc.match_route(['同意', '不同意'], decision='refuse')[0], '不同意')
eq('按最长的词判:不通过 归驳回那一边',
session_svc.match_route(['不通过', '通过'], decision='refuse')[0], '不通过')
eq('三条出口时"同意"只有一条像就用它', session_svc.match_route(
['同意并转财务', '不同意', '退回补件'], decision='agree')[0], '同意并转财务')
eq('两条都像就说不清,不赌', session_svc.match_route(
['同意并转财务', '同意并抄送'], decision='agree', activity='总经理')[1][1],
'EMBED_ROUTE_AMBIGUOUS')
ok('说不清那句要把候选念出来', '同意并转财务' in session_svc.match_route(
['同意并转财务', '同意并抄送'], decision='agree', activity='总经理')[1][0])
eq('多个出口时 submit 也不算方向', session_svc.match_route(
['同意', '驳回'], decision='submit', activity='总经理')[1][1], 'EMBED_ROUTE_AMBIGUOUS')
eq('认不出的结论要说可以填哪三种', session_svc.match_route(
['同意', '驳回'], decision='ok', activity='总经理')[1][1], 'EMBED_DECISION_UNKNOWN')
eq('给了不存在的出口名要点名并念出候选', session_svc.match_route(
['同意', '驳回'], route='通过', activity='总经理')[1][1], 'EMBED_ROUTE_NOT_FOUND')
class _StubSession:
"""顶替 ``oa_embed_session`` 那一条:``apply_prefill`` 只读 result、只写 result。"""
def __init__(self) -> None:
self.result: dict = {}
self.last_callback = None
class _StubDb:
def flush(self) -> None: # _touched 会 flush 一下,离线跑没得落库,空着就行
return None
def check_abandon() -> None:
"""「这一页被放弃时通知对方」那一档:一处配(那条源上),表单默认不用动。
这一档是反着来的那半件事(OA → 对方),偏偏跑在**还没有单据**那一刻。配法收在
一条记录上之后,最容易坏的四件事都得钉住:走现成写回通道时那三样要跟着通道走、
地址写歪时要当场说、那一格没表态时要跟着源、上一版摆在格子上的六栏存量配置
不能悄悄失效。
"""
from types import SimpleNamespace
from app.service import embed as embed_svc
from app.service import embed_session
def source(url="", method="", field="", via="", expr="", body=None):
return SimpleNamespace(code="erp_page", url="https://erp.example.com/page/contract?no={arg.no}",
abandon_url=url, abandon_source=via,
abandon_method=method, abandon_field=field,
abandon_expr=expr, abandon_body=dict(body or {}))
channel = SimpleNamespace(code="erp_api", name="按单号删草稿", provider="http",
direction="out", enabled=True, method="DELETE",
url="https://erp.example.com/api/reimbursements/oa/by-flow-number")
real_get = embed_svc.channel_source
# 连 db 都没带上就当找不到:真的那条函数是这个规矩(没库不猜地址)
embed_svc.channel_source = (
lambda db, code: channel if db is not None and code == channel.code else None) # type: ignore[assignment]
try:
eq("只写路径时挂在页面地址那台主机上",
embed_svc.abandon_plan(source("/api/contract/oa/by-flow-number")),
{"method": "DELETE", "url": "https://erp.example.com/api/contract/oa/by-flow-number",
"field": "oa_flow_number", "via": "", "expr": "", "body": {}})
eq("写全地址就照它发,方法与字段名按配的来",
embed_svc.abandon_plan(source("https://other.example.com/del", "POST", "flowNo")),
{"method": "POST", "url": "https://other.example.com/del", "field": "flowNo", "via": "", "expr": "", "body": {}})
eq("那条源两样都没配 = 这一档发不出去", embed_svc.abandon_plan(source()), {})
eq("会改对方数据的调用不给 GET,退回默认方法",
embed_svc.abandon_plan(source("/del", "GET")).get("method"), "DELETE")
eq("对方那个单号字段有个默认叫法,不用配",
embed_svc.abandon_plan(source("/del")).get("field"), "oa_flow_number")
# 走一条现成的写回通道:URL 与方法跟它走,鉴权/判定也归它(见 apply_abandon)
eq("挑了写回通道就照那条通道上的地址发",
embed_svc.abandon_plan(source(via=channel.code), db=object()),
{"method": "DELETE", "url": channel.url, "field": "oa_flow_number", "via": channel.code, "expr": "", "body": {}})
eq("两个都填时以地址为准,通道仍留着管鉴权",
embed_svc.abandon_plan(source("/other/path", via=channel.code), db=object()).get("url"),
"https://erp.example.com/other/path")
eq("指了通道却没带库时按没配处理(半截配置不往外发)",
embed_svc.abandon_plan(source(via=channel.code)), {})
embed_svc.channel_source = lambda db, code: None # type: ignore[assignment]
eq("那条通道不在了也按没配处理", embed_svc.abandon_plan(source(via="gone"), db=object()), {})
# 连 db 都没带上就当找不到:真的那条函数是这个规矩(没库不猜地址)
embed_svc.channel_source = (
lambda db, code: channel if db is not None and code == channel.code else None) # noqa: E731
# 那一格上那三态
silent = {"key": "f", "embed": {}}
on = {"key": "f", "embed": {"abandon": True}}
off = {"key": "f", "embed": {"abandon": {"enabled": False}}}
eq("那一格没表态是第三种值(不是\"关\")", embed_svc.abandon_choice(silent), None)
eq("写 true 算表了态", embed_svc.abandon_choice(on), True)
eq("写 enabled:false 算显式关掉", embed_svc.abandon_choice(off), False)
ok("那一格没表态时跟着源:源上配了就发",
embed_svc.abandon_wanted(silent, source("/del")))
ok("源上没配又没人表态,就不发", not embed_svc.abandon_wanted(silent, source()))
ok("那一格说不发,源上配了也不发", not embed_svc.abandon_wanted(off, source("/del")))
eq("没表态也发时带走的那份快照 = 那一句长什么样",
embed_svc.abandon_of(silent, source("/del")),
{"enabled": True, "method": "DELETE", "url": "https://erp.example.com/del",
"field": "oa_flow_number", "via": "", "expr": ""})
eq("显式关掉时一份快照都不带", embed_svc.abandon_of(off, source("/del")), {})
# 值那一格:配了取值写法就在打开这一刻算死记走,没配退回预留单号(见 apply_abandon)
eq("值留空时不算(退回预留单号那一路)", embed_svc.abandon_number(object(), ""), "")
eq("值是写死的一个值就原样给", embed_svc.abandon_number(object(), "XS20261023"), "XS20261023")
eq("值是表单那一格就读表单上的值",
embed_svc.abandon_number(object(), "{form.流程编号}", data={"流程编号": "PC-88"}), "PC-88")
eq("值算成空串也当没配", embed_svc.abandon_number(object(), "{form.流程编号}", data={}), "")
eq("没带库时不猜,退回预留单号那一路", embed_svc.abandon_number(None, "{form.x}", data={"x": "1"}), "")
snap = embed_svc.abandon_of(silent, source("/del", expr="{form.流程编号}"), db=object(),
data={"流程编号": "PC-88"})
eq("配了值的那份快照带着算好的值", snap.get("number"), "PC-88")
eq("没配值的那份快照不带 number 键", "number" in embed_svc.abandon_of(silent, source("/del")), False)
# 多键请求体:每个键的值各走一遍取值写法,打开这一刻算死;全算成空就当没配
eq("多键没配时回空表", embed_svc.abandon_body_of(object(), {}), {})
eq("多键里写死的值原样给", embed_svc.abandon_body_of(object(), {"a": "X"}), {"a": "X"})
eq("多键里读表单的那一格就读表单上的值",
embed_svc.abandon_body_of(object(), {"b": "{form.y}"}, data={"y": "Z"}), {"b": "Z"})
eq("多键里算成空的键丢掉,不发空值过去",
embed_svc.abandon_body_of(object(), {"a": "X", "c": "{form.缺}"}, data={"y": "Z"}), {"a": "X"})
eq("多键没带库时不猜,回空表", embed_svc.abandon_body_of(None, {"a": "X"}), {})
multi = embed_svc.abandon_of(silent, source("/del", body={"oa_flow_number": "{form.流程编号}"}),
db=object(), data={"流程编号": "PC-88"})
eq("配了多键的那份快照带着算好的那份请求体", multi.get("body"), {"oa_flow_number": "PC-88"})
eq("配了多键时不再带单键那个 number 键", "number" in multi, False)
# 上一版摆在格子上的那六栏:不能因为收成一个开关就悄悄失效
legacy = {"key": "f", "embed": {"abandon": {
"enabled": True, "source": channel.code, "method": "DELETE",
"body": {"oa_flow_number": "{serial}"}, "missingOk": True}}}
eq("老那六栏翻得出现在这一份(地址照那条通道、键名照那份请求体)",
embed_svc.abandon_legacy(legacy, db=object()),
{"method": "DELETE", "url": channel.url, "field": "oa_flow_number", "via": channel.code})
eq("源上配好了就优先照源上那份",
embed_svc.abandon_plan_of(legacy, source("/del"), db=object()).get("url"),
"https://erp.example.com/del")
eq("新版那一份就一个 enabled,不被当成老配置", embed_svc.abandon_legacy(on, db=object()), {})
eq("老配置指的那条通道不在了就按没配", embed_svc.abandon_legacy(legacy, db=None), {})
# 保存那一刻的三句闸
problem = embed_svc.abandon_url_problem("del/x", "https://erp.example.com/p")
ok("地址既不是完整地址也不是路径时要点名", "要么写完整" in problem, problem)
problem = embed_svc.abandon_url_problem("/del", "")
ok("只写路径而页面地址没主机,得说清拼不出去", "没有主机" in problem, problem)
eq("只写路径而页面地址有主机就能过", embed_svc.abandon_url_problem("/del", "https://erp.example.com/p"), "")
eq("完整地址走地址那套规矩", embed_svc.abandon_url_problem("https://erp.example.com/del", ""), "")
ok("挑了个不存在的通道要在保存那一刻就挡住",
"不存在" in embed_svc.abandon_source_problem("nope", "erp_page", db=object()),
embed_svc.abandon_source_problem("nope", "erp_page", db=object()))
ok("指自己当通道要挡住",
"自己" in embed_svc.abandon_source_problem("erp_page", "erp_page", db=object()),
embed_svc.abandon_source_problem("erp_page", "erp_page", db=object()))
embed_svc.channel_source = lambda db, code: SimpleNamespace( # type: ignore[assignment]
code="erp_fetch", name="取余额", provider="http", direction="in", enabled=True)
ok("挑了一条方向为取数的要挡住并说清该挑哪种",
"取数" in embed_svc.abandon_source_problem("erp_fetch", "erp_page", db=object()),
embed_svc.abandon_source_problem("erp_fetch", "erp_page", db=object()))
# 连 db 都没带上就当找不到:真的那条函数是这个规矩(没库不猜地址)
embed_svc.channel_source = (
lambda db, code: channel if db is not None and code == channel.code else None) # noqa: E731
eq("挑对了就没问题", embed_svc.abandon_source_problem(channel.code, "erp_page", db=object()), "")
# 设计期那一句只在"这一格明确要发、可源上没配"时念
eq("那一格没表态就不催(跟着源,源上没配自然不发)", embed_svc.abandon_problem(silent, source()), "")
ok("明确要发而源上没配才点名",
"还没配" in embed_svc.abandon_problem(on, source(), db=object()),
embed_svc.abandon_problem(on, source(), db=object()))
eq("源上配好了就没问题", embed_svc.abandon_problem(on, source("/del"), db=object()), "")
# 那一句通知带出去的头,必须就是接口收的那个名:拼错的那一侧只会安静地不认账
from app.api import embeds as embeds_api
eq("往外发那句通知用的凭证头,与接口收的那个同名",
embed_session.INTEGRATION_KEY_HEADER, embeds_api.KEY_HEADER)
finally:
embed_svc.channel_source = real_get # type: ignore[assignment]
def check_link_kinds() -> None:
"""对面回好几条链接(编辑页 / 查看页 / 还有哪几条):给谁、取几条、同一趟能不能少问一次。
用户那句"打开一次创建一次"在这一段有两个落点,都得钉死:
1. **取几条**:一次调用把**全部**取回来。为"顺便看看还有没有别的链接"再打一次,
对面就多一张页——那是这个接口自己的语义,OA 替不了它省。
2. **问几次**:这一趟问过就不再问,那几条存在会话上(``url_edit`` / ``url_view`` /
``url_extra``,外加同一份响应里顺手带回的那行灰字 ``link_meta``)。
顺序也算判据:**先查库再决定打不打**。反过来(打完再回头查)那张多余的页已经建出来了。
剩下的都是"给谁"那一档的口径:``auto`` 只在发起人还有事要做时给编辑页,
认不出的值一律退回 ``auto``,而界面拿到的永远是**实际给出去的那一条**。
"""
from app.service import embed_session, fetch
# ---- 1) 三档读数,以及 auto 到底落在哪一格 ----
eq("没配过就是「按人自动选」", embed.link_policy_of(field()), embed.LINK_AUTO)
eq("点了查看页就认查看页", embed.link_policy_of(field(link="view")), embed.LINK_VIEW)
eq("点了编辑页就认编辑页", embed.link_policy_of(field(link="edit")), embed.LINK_EDIT)
eq("写法根本不成键名(大写)退回自动,不自己发明宽容",
embed.link_policy_of(field(link="ReadOnly")), embed.LINK_AUTO)
# 小写那几种(readonly / print)今天**可能**是管理员在源上登记的链接名,所以读数这一层
# 原样放过,"这条源到底有没有这一条"由设计期那句判断挡——两处各判一半才不会漂
eq("成形的键名原样放过(它可能是源上登记过的一条链接)",
embed.link_policy_of(field(link="readonly")), "readonly")
auto = field()
eq("发起页(手上还没这张单)给编辑页",
embed.link_kind_for(auto, has_work=False, is_creator=False, can_act=False), embed.LINK_EDIT)
eq("发起人在自己那张单上还有事要做:编辑页",
embed.link_kind_for(auto, has_work=True, is_creator=True, can_act=True), embed.LINK_EDIT)
eq("他自己提交完回来看:查看页",
embed.link_kind_for(auto, has_work=True, is_creator=True, can_act=False), embed.LINK_VIEW)
eq("审批人手里有待办也只给查看页",
embed.link_kind_for(auto, has_work=True, is_creator=False, can_act=True), embed.LINK_VIEW)
eq("点了「都给编辑页」就不再问人",
embed.link_kind_for(field(link="edit"), has_work=True, is_creator=False, can_act=False), embed.LINK_EDIT)
eq("点了「都给查看页」连发起人自己也是查看页",
embed.link_kind_for(field(link="view"), has_work=False, is_creator=True, can_act=True), embed.LINK_VIEW)
# 第四档只问「这一屏有没有这张单」:它治的是「我的发起 / 我的已办 / 待办」那些只读场合
# 还去递建页接口那一条,对面凭空多一张草稿(而对方只有填报页时干脆打不开,见下面 4b)
eq("那一档的读数认得(不是源上登记的键名)", embed.link_policy_of(field(link="start")), embed.LINK_START)
eq("发起那一屏(手上还没这张单)还是编辑页,发起人自己也一样",
embed.link_kind_for(field(link="start"), has_work=False, is_creator=True, can_act=True), embed.LINK_EDIT)
eq("单据一存在就一律查看页:发起人自己在「我的发起」里点开也是",
embed.link_kind_for(field(link="start"), has_work=True, is_creator=True, can_act=False), embed.LINK_VIEW)
eq("连他手里还有没办完的待办也给查看页——这一档不看站着的是谁,只看有没有这张单",
embed.link_kind_for(field(link="start"), has_work=True, is_creator=True, can_act=True), embed.LINK_VIEW)
eq("待办上那个审批人也是查看页(流程在途同理)",
embed.link_kind_for(field(link="start"), has_work=True, is_creator=False, can_act=True), embed.LINK_VIEW)
# 这一档两边各写了一份(后端判给哪一条,前端那一栏列得出哪几档)。清单不一致的下一站
# 一定是"界面上能选、后端念成 auto"或反过来,所以在这儿把两份清单钉成一个数
front = pathlib.Path(__file__).resolve().parents[2] / "frontend/src/utils/formRuntime.ts"
runtime = front.read_text(encoding="utf-8")
listed = re.search(r"export const EMBED_LINK_POLICIES = \[([^\]]*)\]", runtime)
values = dict(re.findall(r"export const (EMBED_LINK_\w+) = '([^']*)'", runtime))
front_policies = [values.get(f"EMBED_LINK_{item.strip().split('_')[-1].upper()}", "?")
for item in (listed.group(1).split(",") if listed else []) if item.strip()]
eq("「给哪一条地址」那几档两边一份清单", front_policies, list(embed.LINK_POLICIES))
# ---- 2) 这条源到底给不给得出查看页(两档各看各的那一栏)----
api_two = Source(url="https://erp.example.com/api/page-link", url_mode=embed.URL_API,
url_path="data.url", view_url_path="data.viewUrl")
api_one = Source(url="https://erp.example.com/api/page-link", url_mode=embed.URL_API, url_path="data.url")
eq("接口那一档看「查看页链接在响应里的位置」", embed.view_link_ready(api_two), True)
eq("那一栏空着就是给不出", embed.view_link_ready(api_one), False)
eq("模板那一档看第二条地址模板",
embed.view_link_ready(Source(view_url="https://erp.example.com/view")), True)
eq("模板那一档没第二条就是给不出", embed.view_link_ready(Source()), False)
twin = Source(url="https://erp.example.com/api/page-link", view_url="https://view.example.com/p")
ok("第二条地址那台主机也白送进 CSP 白名单",
"https://view.example.com" in embed.allowed_origins(twin), embed.allowed_origins(twin))
# ---- 3) 设计期那两句:显式要查看页而这条源给不出,要当场说 ----
odd = embed.problems(field(link="Magic"), FakeDB(api_two), at="X")
ok("那一档写歪了要点名可写哪几档", any("给哪一条地址那一档不认识" in line for line in odd), odd)
unregistered = embed.problems(field(link="print"), FakeDB(api_two), at="X")
ok("点了这条源没登记过的那一条,保存那一刻就点名并念出它现在有哪几条",
any("没登记过它" in line and "查看页" in line for line in unregistered), unregistered)
registered = embed.problems(
field(link="print"),
FakeDB(Source(url="https://erp.example.com/api/page-link", url_mode=embed.URL_API,
url_path="data.url",
url_links=[{"key": "print", "name": "打印页", "path": "data.printUrl"}])),
at="X")
ok("登记过就不再啰嗦", not any("没登记过它" in line for line in registered), registered)
nag = embed.problems(field(link="view"), FakeDB(api_one), at="X")
ok("点了「只给查看页」而这条源只有一条地址,保存那一刻就说",
any("只给查看页" in line and "还是会给编辑页" in line for line in nag), nag)
start_nag = embed.problems(field(link="start"), FakeDB(api_one), at="X")
ok("点了「发起那一屏之外都给查看页」而这条源没有查看页,保存那一刻同样点名这一档",
any("发起那一屏之外都给查看页" in line and "还是会给编辑页" in line for line in start_nag),
start_nag)
start_quiet = embed.problems(field(link="start"), FakeDB(api_two), at="X")
ok("配好了那一栏就不再多说这一档",
not any("还是会给编辑页" in line for line in start_quiet), start_quiet)
quiet = embed.problems(field(link="view"), FakeDB(api_two), at="X")
ok("配好了那一栏就不再啰嗦", not any("只给查看页" in line for line in quiet), quiet)
# 默认那一档不给存量表单添噪音:它们一条都没配过第二条地址,行为本来就没变
by_default = embed.problems(field(), FakeDB(api_one), at="X")
ok("「按人自动选」不报警(存量一格都不该多出一句话)",
not any("只给查看页" in line for line in by_default), by_default)
# ---- 4) 一次调用取两条 ----
two = Source(url="https://erp.example.com/api/page-link", url_mode=embed.URL_API,
url_path="data.url", view_url_path="data.viewUrl",
mock_payload={"data": {"url": "https://erp.example.com/edit?k=1",
"viewUrl": "https://erp.example.com/view?k=1"}})
got = embed.resolve_link(FakeDB(two), two, {}, want=embed.LINK_VIEW)
eq("要查看页就取查看页那一条", got["url"], "https://erp.example.com/view?k=1")
eq("回话说清实际给的是哪一条", got["link"], embed.LINK_VIEW)
eq("两条一起交回去,好让调用方钉在这一趟上",
got["links"], {"edit": "https://erp.example.com/edit?k=1", "view": "https://erp.example.com/view?k=1"})
eq("要编辑页时取的是编辑页那条",
embed.resolve_link(FakeDB(two), two, {}, want=embed.LINK_EDIT)["url"], "https://erp.example.com/edit?k=1")
single = Source(url="https://erp.example.com/api/page-link", url_mode=embed.URL_API, url_path="data.url",
mock_payload={"data": {"url": "https://erp.example.com/edit?k=1"}})
fell = embed.resolve_link(FakeDB(single), single, {}, want=embed.LINK_VIEW)
ok("这条源只有一条地址就退回那条,并且说实话",
fell["link"] == embed.LINK_EDIT and fell["url"].endswith("/edit?k=1"), fell)
broken = Source(url="https://erp.example.com/api/page-link", url_mode=embed.URL_API, url_path="data.url",
view_url_path="data.viewLink",
mock_payload={"data": {"url": "https://erp.example.com/edit?k=1"}})
bad = embed.resolve_link(FakeDB(broken), broken, {}, want=embed.LINK_VIEW)
ok("配了位置却没取到就是配歪:点名哪一栏,不悄悄把人塞进编辑页",
(not bad["ok"]) and "查看页" in bad["error"] and "data.viewLink" in bad["error"], bad)
# ---- 4b) **键在、值是空的**:对方这一趟压根没有那一页,不是我们这一栏写歪 ----
# 生产上撞的就是这一式:那条源把查看页配在 data.review_url,而对方在单据进审阅之前
# 一律回 "review_url": ""。当成配歪 = "流程在途时这一格谁都打不开",
# 而那句「那个接口没有回链接」还把配好的人一起误导了(明明回了填报页)
notyet = Source(url="https://erp.example.com/api/page-link", url_mode=embed.URL_API,
url_path="data.url", view_url_path="data.viewUrl",
mock_payload={"data": {"url": "https://erp.example.com/edit?k=1",
"viewUrl": ""}})
waited = embed.resolve_link(FakeDB(notyet), notyet, {}, want=embed.LINK_VIEW)
ok("对方回一条空的查看页地址就退到编辑页,这一格照样打得开",
waited["ok"] and waited["link"] == embed.LINK_EDIT
and waited["url"].endswith("/edit?k=1"), waited)
eq("要的是查看页、给的是填报页,两句分开说实话(界面那句退路说明全靠这一对)",
(waited["wanted"], waited["link"]), (embed.LINK_VIEW, embed.LINK_EDIT))
eq("而这一条是对方没给,不是这条源没配上——界面要说的是另一句话", waited["absent"], True)
eq("空的那一条不钉在这一趟上,别把空串当一条地址存进会话",
waited["links"], {"edit": "https://erp.example.com/edit?k=1"})
ok("等对方有了那一页,同一句要查看页就拿查看页(不改配置,只认这一趟回了什么)",
embed.resolve_link(FakeDB(two), two, {}, want=embed.LINK_VIEW)["link"] == embed.LINK_VIEW)
only_empty = Source(url="https://erp.example.com/api/page-link", url_mode=embed.URL_API,
url_path="data.url",
mock_payload={"data": {"url": " "}})
empty = embed.resolve_link(FakeDB(only_empty), only_empty, {})
ok("唯一那一条也空着时说清是哪一条空着,不再是一句「接口没有回链接」",
(not empty["ok"]) and "编辑页" in empty["error"] and "是空的" in empty["error"], empty)
# ---- 5) 同一趟只问一次(build_url 这一头)----
calls = {"n": 0}
def fake_request(method, url, body, headers, timeout, **_kwargs):
calls["n"] += 1
return 200, {}, ('{"data":{"url":"https://erp.example.com/edit?k=1",'
'"viewUrl":"https://erp.example.com/view?k=1"}}'), str(url)
original = fetch.http_request_full
fetch.http_request_full = fake_request
try:
live = Source(url="https://erp.example.com/api/page-link", url_mode=embed.URL_API,
url_path="data.url", view_url_path="data.viewUrl")
first = embed.build_url(FakeDB(live), live, {}, person="P1", want=embed.LINK_VIEW)
eq("第一次要打一次接口", calls["n"], 1)
eq("给的是查看页那一条", first["link"], embed.LINK_VIEW)
eq("两条都带回去存", sorted(first["links"]), ["edit", "view"])
held = dict(first["links"])
again = embed.build_url(FakeDB(live), live, {}, person="P1", want=embed.LINK_VIEW, stored=held)
eq("沿用存过那一条时一次接口都不打——对面不再多一张页", calls["n"], 1)
eq("地址与上一次一字不差", again["url"], first["url"])
ok("界面因此说得出「这一条是沿用来的」", again["reused"] is True, again)
other = embed.build_url(FakeDB(live), live, {}, person="P1", want=embed.LINK_EDIT, stored=held)
eq("换要另一条也还是不问", other["url"], "https://erp.example.com/edit?k=1")
eq("打了几个电话?还是一个", calls["n"], 1)
# 只存过填报页、而这一屏要查看页,且这条源**配了查看页那一栏的位置**:再问一次。
# 这三句原来钉的是"照用存过的那条、一个电话都不打",那正是「审阅页在单据进审阅之前
# 回空串」那种源打不开的另一半后果——沿用等于把"这一屏是对面的哪一页"永远钉在第一次
# 那一次的答案上,「已经进审阅了,已办里点开还是填报页」断在这儿。判据与理由写在
# ``build_url`` 里那一句 ``stale``;对面按单号幂等时(生产那条就是)多问一次不多建一页
only = embed.build_url(FakeDB(live), live, {}, person="P1", want=embed.LINK_VIEW,
stored={"edit": "https://erp.example.com/edit?k=1"})
eq("只存过填报页而这一屏要查看页:再问一次,问到就给查看页", only["url"],
"https://erp.example.com/view?k=1")
eq("实际给的就是要的那一条,没什么可说实话的退路", only["link"], embed.LINK_VIEW)
eq("多打的那一个电话问的是「他们那边有了吗」", calls["n"], 2)
ok("刚问回来的那一条不叫沿用", only["reused"] is False, only)
# 而**没配那一栏位置**的源一次都不许多问:那一屏要的就是填报页,沿用照旧
one_link = Source(url="https://erp.example.com/api/page-link", url_mode=embed.URL_API,
url_path="data.url")
kept = embed.build_url(FakeDB(one_link), one_link, {}, person="P1", want=embed.LINK_VIEW,
stored={"edit": "https://erp.example.com/edit?k=1"})
eq("源上没配查看页那一栏:沿用存过的那条,一个电话都不多打", calls["n"], 2)
eq("给的还是那一条,并说自己要的就是它",
(kept["url"], kept["wanted"]), ("https://erp.example.com/edit?k=1", embed.LINK_EDIT))
finally:
fetch.http_request_full = original
# 模板那一档没有"打电话"这件事,但认不认这一档、说不说真话得一样
tpl = Source(url="https://erp.example.com/edit?no={arg.no}",
view_url="https://erp.example.com/view?no={arg.no}")
eq("模板档换的是第二条地址模板",
embed.build_url(FakeDB(tpl), tpl, {"no": "HT-1"}, person="P", want=embed.LINK_VIEW)["url"],
"https://erp.example.com/view?no=HT-1")
honest = embed.build_url(FakeDB(Source()), Source(), {"no": "HT-1"}, person="P", want=embed.LINK_VIEW)
eq("没有第二条就退回模板,并说自己给的是编辑页", honest["link"], embed.LINK_EDIT)
# ---- 5b) 清单:对方回三条链接、还捎带几个只读值 ----
three = Source(url="https://erp.example.com/api/page-link", url_mode=embed.URL_API,
url_path="data.url", view_url_path="data.viewUrl",
url_links=[{"key": "print", "name": "打印页", "path": "data.printUrl"}],
url_meta={"对方单号": "data.flow_number", "审核状态": "data.review_status"})
eq("清单从编辑页排起,登记的那几条跟在后面",
[item["key"] for item in embed.link_defs(three)], ["edit", "view", "print"])
eq("界面那份清单念得出管理员起的名字",
[item["name"] for item in embed.link_brief(three)], ["编辑页", "查看页", "打印页"])
eq("这一档没配位置的那一条根本不摆",
[item["key"] for item in embed.link_defs(api_two)], ["edit", "view"])
ok("具名那一条也算「这条源给得出」",
embed.link_ready(three, "print") and not embed.link_ready(three, "invoice"))
ok("那一行没写位置:点名是哪一条、少了哪一格",
"打印页" in embed.links_problem([{"key": "print", "name": "打印页"}], mode=embed.URL_API),
embed.links_problem([{"key": "print", "name": "打印页"}], mode=embed.URL_API))
ok("键名不许占用内置那两条",
"留给上面那两栏用" in embed.links_problem([{"key": "view", "path": "data.v"}], mode=embed.URL_API))
ok("两条链接不能共用一个名字",
"重名" in embed.links_problem([{"key": "print", "path": "data.a"},
{"key": "print", "path": "data.b"}], mode=embed.URL_API))
ok("模板档要的是地址模板,不是位置",
"地址模板" in embed.links_problem([{"key": "print", "name": "打印页", "path": "data.a"}],
mode=embed.URL_TEMPLATE))
ok("带值的某一格只写了名字:保存那一刻就挡",
"没写位置" in embed.link_meta_problem({"对方单号": ""}))
eq("带回的值只收标量:位置写歪或回了一份对象,那一行干脆不出现",
embed.link_meta_of({"data": {"flow_number": "RE-1", "review_status": {"code": 2}}}, three),
{"对方单号": "RE-1"})
def three_request(method, url, body, headers, timeout, **kwargs):
calls3["n"] += 1
return 200, {}, ('{"code":0,"data":{"url":"https://erp.example.com/edit?k=1",'
'"viewUrl":"https://erp.example.com/view?k=1",'
'"printUrl":"https://print.example.com/p/1",'
'"flow_number":"RE-20261027-004","review_status":"待复审"}}'), str(url)
calls3 = {"n": 0}
original3 = fetch.http_request_full
fetch.http_request_full = three_request
try:
# 第三条链接挂在另一台主机上:没进「允许的来源」之前,它一条都不该嵌进来
off_host = Source(url=three.url, url_mode=embed.URL_API, url_path=three.url_path,
view_url_path=three.view_url_path, url_links=list(three.url_links))
try:
embed.build_url(FakeDB(off_host), off_host, {}, person="P1", want="print")
said = ""
except embed.LinkError as exc:
said = str(exc)
calls3["n"] = 0 # 那一次失败已经打过电话了,下面要数的是"点名要打印页"这一趟打几次
ok("清单里那一条也要过来源那道闸(配了却没取到是配歪,不悄悄把人塞进另一页)",
"不在这张源允许的来源里" in said, said)
three.url_origins = ["https://print.example.com"]
first3 = embed.build_url(FakeDB(three), three, {}, person="P1", want="print")
eq("点名要打印页就给打印页", (first3["link"], first3["url"]),
("print", "https://print.example.com/p/1"))
eq("三条从同一次调用里一起取回", sorted(first3["links"]), ["edit", "print", "view"])
eq("那行灰字搭同一趟车回来", first3["meta"],
{"对方单号": "RE-20261027-004", "审核状态": "待复审"})
eq("一次电话", calls3["n"], 1)
again3 = embed.build_url(FakeDB(three), three, {}, person="P1", want="invoice",
stored=dict(first3["links"]), stored_meta=dict(first3["meta"]))
eq("这一趟要的那一条这条源给不出:退回编辑页,并说实话", again3["link"], embed.LINK_EDIT)
eq("沿用存过的那一条,一次接口都不打", calls3["n"], 1)
eq("沿用旧链接时那行灰字还在(不然屏幕上就是一句空白)",
again3["meta"], {"对方单号": "RE-20261027-004", "审核状态": "待复审"})
named = embed.build_url(FakeDB(three), three, {}, person="P1", want="print",
stored=dict(first3["links"]))
eq("清单里那几条一样能沿用", (named["url"], named["reused"]),
("https://print.example.com/p/1", True))
finally:
fetch.http_request_full = original3
# 清单里那条模板档地址的主机,与编辑页/查看页同一个待遇:自动进 CSP 白名单
tpl_three = Source(url="https://erp.example.com/edit?no={arg.no}",
url_links=[{"key": "print", "name": "打印页",
"template": "https://print.example.com/p/{arg.no}"}])
ok("清单里每一条模板档地址的主机都白送进 CSP",
"https://print.example.com" in embed.allowed_origins(tpl_three),
embed.allowed_origins(tpl_three))
ok("模板档的参数白名单也读清单里那几条地址",
embed.declared_args(tpl_three) == {"no"}, embed.declared_args(tpl_three))
eq("模板档换的是清单里那一条的地址模板",
embed.build_url(FakeDB(tpl_three), tpl_three, {"no": "HT-1"}, person="P",
want="print")["url"], "https://print.example.com/p/HT-1")
# ---- 6) 存进库与"先查再打"那个顺序 ----
class Held:
url_edit = ""
url_view = ""
class Flusher:
def flush(self) -> None:
return
stored_row = Held()
embed_session.stamp_links(Flusher(), stored_row, {"edit": "https://erp/e1", "view": "https://erp/v1"})
eq("两条都钉在这一趟上", (stored_row.url_edit, stored_row.url_view), ("https://erp/e1", "https://erp/v1"))
embed_session.stamp_links(Flusher(), stored_row, {"edit": "https://erp/e2"})
eq("只补空、不覆盖:同一趟指的就是那一页", stored_row.url_edit, "https://erp/e1")
eq("没给的那一栏留着不动", stored_row.url_view, "https://erp/v1")
eq("什么也没带着来时不写", (embed_session.stamp_links(Flusher(), stored_row, {}) or stored_row.url_edit),
"https://erp/e1")
class Held3(Held):
url_extra: dict = {}
link_meta: dict = {}
row3 = Held3()
embed_session.stamp_links(Flusher(), row3,
{"edit": "https://erp/e1", "print": "https://print/e1"},
{"对方单号": "RE-20261027-004"})
eq("内置那两条照旧各占一列,清单里那几条摊进 url_extra",
(row3.url_edit, dict(row3.url_extra)), ("https://erp/e1", {"print": "https://print/e1"}))
eq("那一行灰字也钉在这一趟上", dict(row3.link_meta), {"对方单号": "RE-20261027-004"})
embed_session.stamp_links(Flusher(), row3, {"print": "https://print/e9"}, {"对方单号": "RE-9"})
eq("仍是只补空、不覆盖:同一趟对同一件事只有一个说法",
(row3.url_extra["print"], row3.link_meta["对方单号"]),
("https://print/e1", "RE-20261027-004"))
root = pathlib.Path(__file__).resolve().parents[2]
api_text = (root / "backend" / "app" / "api" / "embeds.py").read_text(encoding="utf-8")
held_at = api_text.index("embed_session.held_bundle(")
built_at = api_text.index("built = embed.build_url(")
ok("先查这一趟存过什么,再决定打不打那个接口(顺序反了那张页已经多出来了)",
held_at < built_at, f"查库在第 {held_at} 字,打接口在第 {built_at} 字")
ok("查到就交给 build_url 用", "stored=held" in api_text)
ok("这一次取回来的两条钉回这一趟", 'stamp_links(db, session, built.get("links")' in api_text)
ok("实际给了哪一条、是不是沿用,都说给界面",
'"link": built["link"]' in api_text and '"linkReused": bool(built.get("reused"))' in api_text)
s2s = (root / "backend" / "app" / "service" / "embed_session.py").read_text(encoding="utf-8")
ok("要带过去的值换了就把存过的那些作废(连那行灰字一起,它们是同一次调用的产物)",
'existing.url_edit = ""' in s2s and 'existing.url_view = ""' in s2s
and 'existing.url_extra = {}' in s2s and 'existing.link_meta = {}' in s2s, "找不到那几行清空")
ok("「每次开新的一页」那一档不去沿用旧地址",
"if not reopen_reuses_trip(mode):" in s2s and '"links": {}, "meta": {}, "shared": False' in s2s)
# 对面那一页属于这张单,不属于哪个人的一趟:判据分两层,顺序与理由见
# docs/embed-action-design.md §2.1.1。这几句钉的是"别把第二层悄悄删回去"
ok("先认这个人那一趟,落空了才认这张单那一页(顺序反了就是每人各一页)",
s2s.index("existing = find_open(") < s2s.index("page = page_row("))
ok("这一层只按「源 + 格子 + 这张单」认,不认人",
"def page_row(" in s2s and "EmbedPage.person ==" not in s2s)
ok("这张单那一页不吃参数指纹(对面那一页是按这张单建的)",
s2s.index("def held_bundle(") < s2s.index("page = page_row(")
and "args_digest_of(args)" in s2s.split("def held_bundle(")[1].split("def held_links(")[0])
ok("问回来的那几条同时钉到这张单头上,认到单据的那一刻就钉(不等下一次打开)",
"_stamp_page(db, session, links, meta)" in s2s and "_stamp_page(db, session, None, None)" in s2s)
api_s = api_text
ok("接口那一头把那一档一次读出来,交给自己用到的每一处",
"reopen = embed.reopen_of(field)" in api_s
and api_s.count("mode=reopen") >= 2
and "embed.reopen_of(field) ==" not in api_s, "同一档在 api 里各判了一套")
ok("沿用来自哪一层、那一页是谁建的,都说给界面",
'"linkShared": bool(held.get("shared"))' in api_s and '"linkPage": embed_session.page_brief(' in api_s)
models_text = (root / "backend" / "app" / "models.py").read_text(encoding="utf-8")
ok("一张单 × 一条源 × 一个格子只留一行账(对面只有一页这件事写在唯一约束上)",
'UniqueConstraint("source", "field", "work", name="uq_embed_page_anchor")' in models_text)
page_block = models_text.split("class EmbedPage")[1].split("class NodeDecision")[0]
ok("那一行账没有 expires_at:它活得和这张单一样长,会话那把尺子量不了它",
"class EmbedPage" in models_text and "expires_at: Mapped" not in page_block,
"给这一行加了存活期,就等于把过期这件事又交回会话那把尺子")
ok("两条地址在会话表上各有自己的列",
"url_edit: Mapped[str] = mapped_column(String(2048)" in models_text
and "url_view: Mapped[str] = mapped_column(String(2048)" in models_text)
ok("清单里那几条与那行灰字也有地方存",
"url_extra: Mapped[JsonDict]" in models_text and "link_meta: Mapped[JsonDict]" in models_text,
"会话表上少了那一列:沿用旧链接时那行灰字会跟着变空")
def check_manual() -> None:
"""那份说明书不能和代码漂开。
它写的是"谁在哪一栏填什么、对方调哪条接口"。代码改了名而文档没跟着改时,
照着做的人会配出一个"看着没错却不通"的东西,而现场看不出是文档的错——所以这里
只钉那些**改了名就一定会照错**的东西:相对链接、环境变量名、路由、消息名、
密钥头、reason 码,以及它让人跑的那几条命令。整段文字的措辞不归这里管。
"""
root = pathlib.Path(__file__).resolve().parents[2]
guide = root / "docs" / "embed-configuration-guide.md"
if not guide.exists():
ok("配置说明书在", False, str(guide))
return
text = guide.read_text(encoding="utf-8")
for target in sorted(set(re.findall(r"\]\(([a-z0-9-]+\.md)\)", text))):
ok(f"说明书里那个链接指得着:{target}", (guide.parent / target).exists())
config_text = (root / "backend" / "app" / "config.py").read_text(encoding="utf-8")
known = set(re.findall(r'"(OA_EMBED_[A-Z_]+)"', config_text))
cited = sorted(set(re.findall(r"`(OA_EMBED_[A-Z_]+)`", text)))
ok("说明书把部署档那几项都列了", len(cited) >= 6, f"只提到 {cited}")
for name in cited:
ok(f"说明书里那个环境变量代码认:{name}", name in known, "config.py 里没有它")
for key in ("enabled", "csp", "frame_extra", "ticket_ttl", "allow_http",
"session_ttl", "callback_dedupe"):
ok(f"部署档那一项在:[embed] {key}", f'("embed", "{key}")' in config_text)
routes = "\n".join((root / "backend" / "app" / "api" / name).read_text(encoding="utf-8")
for name in ("embeds.py", "openapi.py"))
s2s = (root / "backend" / "app" / "service" / "embed_session.py").read_text(encoding="utf-8")
for path in sorted(set(re.findall(r"`(?:GET|POST) /(?:api/v1)?/?(embed/[a-z/]+|open/works)`", text))):
ok(f"说明书里那条接口还挂在路由上:/{path}", f'"/{path}"' in routes)
bridge = (root / "frontend" / "src" / "utils" / "embedBridge.ts").read_text(encoding="utf-8")
words = sorted(set(re.findall(r"`(oa:[a-z]+)`", text)))
ok("说明书把那些消息都写了", len(words) >= 6, f"只提到 {words}")
for name in words:
ok(f"消息名前端有这个名字:{name}", f"'{name}'" in bridge)
for phrase in ("X-Oa-Integration-Key", "EMBED_SCOPE_MISSING", "EMBED_TASK_NOT_FOUND",
"alreadyStarted", "deduped", "staged", "prekey", "oes_"):
ok(f"说明书里提到的那个名字确有其物:{phrase}", phrase in routes or phrase in s2s)
# 后半件事(人没保存就返回 → OA 通知对方删草稿)摊在四个文件里,说明书提了哪个名字
# 这几个文件里就得有哪个:这一档最容易漂,因为它的配置天生分在两处
corpus = "\n".join([
routes, s2s,
(root / "backend" / "app" / "service" / "embed.py").read_text(encoding="utf-8"),
(root / "backend" / "app" / "schemas.py").read_text(encoding="utf-8"),
(root / "frontend" / "src" / "components" / "oa" / "design" / "EmbedPanel.vue").read_text(encoding="utf-8"),
(root / "frontend" / "src" / "views" / "oa" / "design" / "DataSourceView.vue").read_text(encoding="utf-8"),
(root / "frontend" / "src" / "i18n" / "locales" / "zh.ts").read_text(encoding="utf-8"),
])
def mentions(haystack: str, needle: str) -> bool:
"""按整词找。裸 ``in`` 会让 ``abandonField`` 冒充 ``abandonFieldName``,
改了名的说明书照样通过,而照着配的人这才刚要开始撞。"""
return re.search(rf"(?<![A-Za-z0-9]){re.escape(needle)}(?![A-Za-z0-9])", haystack) is not None
# 这一档的配置天生分在两处(开关在格子上、地址在源上),漂一次就是"两个人都以为对方删过了",
# 所以这几个名字**必须写**、而且代码里必须确有其物
for phrase in ("放弃时通知对方", "oa_flow_number", "abandonSource", "abandonUrl",
"abandonMethod", "abandonField", "abandonExpr", "abandonBody",
"abandonSet"):
ok(f"说明书写了这一档的这个名字:{phrase}", mentions(text, phrase))
ok(f"说明书里那个名字代码里确有其物:{phrase}", mentions(corpus, phrase))
for rel in ("scripts/check_embed.py", "scripts/check_embed_api.py",
"scripts/check_embed_decide.py"):
if rel in text:
ok(f"说明书让人跑的那条命令有这个脚本:{rel}", (root / "backend" / rel).exists())
for rel in ("src/utils/embedBridge.spec.ts", "src/components/oa/design/EmbedPanel.spec.ts"):
if rel in text:
ok(f"说明书让人跑的那条命令有这个文件:{rel}", (root / "frontend" / rel).exists())
# ---------------------------------------------------------------------------
FAILS: list[str] = []
def eq(name: str, got, want) -> None:
"""取值相等;不等就把两边都打出来,方便一眼看出是形状变了还是值变了。"""
if got != want:
FAILS.append(f"{name}:期望 {want!r},实得 {got!r}")
def ok(name: str, condition, detail=None) -> None:
if not condition:
FAILS.append(f"{name}:{detail if detail is not None else '条件不成立'}")
def main(argv: list[str]) -> int:
stages = [
("参数白名单来自地址模板", check_param_allowlist),
("这一格交出去的那几个值", check_param_text),
("地址渲染", check_render_url),
("注册表上那条地址", check_url_problem),
("源还在不在、启用没启用", check_source_problem),
("能不能被嵌", check_frame_verdict),
("探测结论摊给界面的那份形状", check_probe_shape),
("这一环该按哪张表单判字段", check_activity_form),
("这一格在当前环节露不露", check_field_perm),
("设计期校验", check_problems),
("字段上那份配置的兜底", check_helpers),
("那几格没填上就不让打开这一页", check_open_gate),
("注册表那条记录保存那一刻", check_clean_embed),
("地址由接口现给那一档", check_dynamic_link),
("回填白名单收不收得下", check_writeback),
("免登短码", check_ticket),
("留痕不含参数值", check_log),
("CSP 的 frame-src", check_frame_src),
("前后端措辞对齐", check_wording_parity),
("这一页能让 OA 做哪几件事", check_actions),
("第三方回写开放哪几档", check_writeback_scopes),
("对方那套状态词怎么翻", check_decision_words),
("回写那句审完了落到哪条出口", check_decision_route),
("这一页被放弃时通知对方", check_abandon),
("给哪一条地址:编辑页与查看页", check_link_kinds),
("说明书与代码同源", check_manual),
]
for title, stage in stages:
before = len(FAILS)
stage()
marks = "通过" if len(FAILS) == before else f"{len(FAILS) - before} 条不对"
print(f"[{marks}] {title}")
for line in FAILS:
print(f"[FAIL] {line}")
if FAILS:
print(f"共 {len(FAILS)} 条不对")
return 1
print("通过:表单嵌外部页面这一格的口径一致")
return 0
if __name__ == "__main__":
raise SystemExit(main(sys.argv[1:]))