unis-oa/docs/embed-page-field-design.md

83 KiB
Raw Permalink Blame History

表单里嵌别的系统的页面:embed 这一格为什么这么设计

相关:form-field-catalog.md §4(加一类字段要动的那 11 处)、 form-data-integration-design.md(外部数据源注册表 L1)、 hub-integration.md §5.2(免登那一手交接)、 data-binding-unification-design.md({form.x} 那套写法)。 这一篇只回答四件事:这格存不存值、地址与密钥放哪儿、iframe 里凭什么能看到东西、 嵌不进去的时候怎么办。

要照着配(谁在哪个界面配哪一栏、每一栏填什么、对方要调什么、配完怎么验、出问题查哪一行) 看 embed-configuration-guide.md,这一篇不重复那些操作。

0. 一页看完

问题 结论
组件叫什么 字段类型 embed,界面名「外部页面」,左侧字段库摆在 版面 那一段(那一段的口径是「不往 data 里写值」,它符合)
存不存值 不存。进 NON_INPUT_TYPES / LAYOUT_ONLY_TYPES / fieldCapabilities.LAYOUT_TYPES,提交时 work.data 里不会多出这个键
地址谁填 设计者不填 URL,只从外部数据源注册表里挑一条 provider=embed 的记录。地址、密钥、免登口径都只在后端
地址是死的吗 两档(url_mode):template = 照注册表那条模板拼;api = 先调对方一个接口,用它回的链接(那一页按这张单现生成、每次链接都不一样时只能用这条)。多出来的只有"来源白名单"这一道闸,其余口径一条不松(§2.4)
免登 三档:none(公开页 / 同主域同会话)、ticket(OA 发一次性短码,对方服务端来换身份)、hub(本系统已是 Hub 应用,让 Hub 发跳转;这一档是 P2:界面选不到、存也存不下去,真收到也只回一句「还没开放」,绝不拼一个猜出来的地址)。默认以当前看单的那个人的身份进去
能不能嵌 不靠上线后撞运气:注册表那条记录上的「测试连通」顺手探一次,读目标回的 X-Frame-Options / CSP frame-ancestors / 有没有 302 到登录页;探出嵌不进就退成一张「新窗口打开」的卡片
谁能看见 四道现成的闸:源上的 min_permission + 环节的字段权限(这一格必须能被设成「隐藏」)+ 字段自己的默认隐藏 + 目标系统自己的账号权限
设计器里 不加载真页面。画布里是一张假框:源名、参数行、上次探测结果,外加一个「预览」
回写表单 已做,默认关:只收这份字段配置里点过名的格子,再按类型收值;挂额度与阈值的格子一律不收,环节隐藏与只读也收不下(§5.2)
先做什么 已落地:P0 全部(降级、探测、CSP)+ ticket 免登短码与验票接口+ P1 那条回写通道(含参数变化推送);还欠:P2 hub、移动端口径细化(见 §9 与 §12)

1. 先定一件事:这一格是"版面"还是"值"

三个候选,先摆出来:

  1. 纯版面:跟 group / description 一样,只负责把一块地方让给别人的页面,不产生值。
  2. 存一份地址快照:像 url 字段那样把最终地址存进 data,打印和导出有个凭据。
  3. 存外部回填的结果:iframe 里操作完,把对方给的单号、金额写回本单。

定 1,并且明确把 2 排除掉:那条 URL 上挂着一次性票据,存进 data 等于把会话钥匙 抄进数据库、导出表、打印件三处(service/sso_handoff.py 把短码放在地址片段而不是查询串, 就是为了这个);而且票据 60 秒就废,三个月后那格只会留一条骗人的链接。 3 是真需求,但它是另一个功能(见 §5 的回写通道),不能拿它当"这格有值"的理由—— 一旦这格有了值,必填、条件、额度、导出全都得跟着改口径,而这三样它对不上任何一档。

于是这一格进"不产生值"那一族,两边各加一次:

说的是什么 加在哪
没有录入控件、不参与必填 前端 utils/formLayout.ts:NON_INPUT_TYPES、utils/formRuntime.ts:RUNTIME_NON_INPUT_TYPES;后端 service/formruntime.py:NON_INPUT_TYPES
纯排版不能勾必填 后端 api/design.py:LAYOUT_ONLY_TYPES
挂不上取数 / 阈值 / 额度,条件里也不出现 前端 utils/fieldCapabilities.ts:LAYOUT_TYPES;后端 service/threshold.py / quota.py 的同一档
不能当明细表的一列 types/index.ts:TABLE_COLUMN_TYPES 不加
要有标题 api/design.py:LABELLESS_TYPES 不加——这一格的名字是标题行上那行字,也是留痕和导出里唯一能念出来的东西

但有一条不能含糊:embed 不是 divider。api/design.py 校验字段时对 divider 直接 continue,连字段名都不查;这一格必须走完剩下的校验,因为它的 key 是权限挂点—— 环节字段权限(formPerms)是按 key 生效的,没有 key 就没法在某个环节把它藏起来, 而"某个环节能不能看见这个外部页面"正是整套设计里最要紧的一道闸(§5)。

顺带一个巧合帮了忙:formruntime.effective_perm() 对"没有录入控件"的字段默认给 readonly,环节上仍然能显式给 hidden。也就是说这一格天生不会被当必填卡住提交, 又能被环节藏起来,现成口径直接够用,不用为它加新档位。

2. 地址、密钥、参数:不在字段上,也不在浏览器里

2.1 复用 oa_data_source,加一条 provider = "embed"

第一反应是给"可嵌入页面"单开一张表。不这么干,理由是那张表要重写的恰好是最难写对的部分: 密钥只进不出(auth_secret 从不回显,只回 secret_set)、启停、min_permission、 限流与熔断、「测试连通」那四列结果、oa_data_source_log 留痕、按环境搬运。 而这张表看起来"跟嵌页面无关"的那一多半列(method / items_path / pick / map_* / success_path / src_process / sql_text)今天已经在被别的 provider 整片忽略了—— provider=sql 不填 URL,provider=process 不打网络。往这种形状再加一条来路,是这张表本来 就在长的那个方向。它自己的注释也是这么说的:这七件杂事写在每个字段配置里迟早会漏一个。

用哪些列:

列 在 embed 上装什么
code / name / system / enabled / description 原样用。system(ERP / HR / MES…)正好当属性面板里挑页面时的分组
url 页面地址模板,参数位写 {arg.x}(写法与取数的请求体模板同一份,见 service/binding.py)
param_meta 不用。参数白名单不必另登一份:地址模板里写过哪几个 {arg.x},白名单就是那几个名字。多一栏就多一个会和模板对不上的地方,而模板说漏了才是真要命的(拼不进地址的参数是静默失效,最坏的一种 bug)
auth_type / auth_username / auth_secret ticket 模式下与对方系统共享的应用密钥,只进不出这条约定照旧
min_permission 谁能调这个页面。留空 = 登录即可,再叠加环节字段权限
timeout_seconds 探测能否被嵌的超时
last_test_* 四列 上一次探测的结论,界面上直接显示,不用翻日志
abandon_source / abandon_url / abandon_method / abandon_field / abandon_expr / abandon_body 「这一页被放弃时通知对方」那一句走哪条写回通道、或直接发到哪个地址、用什么方法、对方那个单号字段叫什么、那个值取哪儿(留空 = 这一趟预留的正式单号,要按自己的流程编号删就填取值写法)、多键请求体(abandon_body:要按好几个字段去对面删时整份发,盖过单键那一档;判据 service/embed.py:abandon_plan / abandon_body_of,配法见 embed-configuration-guide.md §1.1)。跟着源而不是跟着字段:那几样说的是那个外部系统长什么样;挑现成通道时鉴权与成功判定也照那条通道

要加的东西当初只有两列,跟 direction / success_path 是同一个做法(放弃通知那四列是后来 补的,同一个加列路子):

page_mode   none | hub | ticket     免登方式,默认 none
app_code    对方在本系统/Hub 上的应用编码   ticket 与 hub 模式要用

字段上只存"这一次嵌进来带什么",不存地址:

{
  "type": "embed",
  "key": "contractPage",
  "label": "合同详情(ERP)",
  "span": 12,
  "embed": {
    "source": "erp_contract_detail",
    "mode": "auto",
    "params": { "contractNo": "{form.contractNo}", "operator": "{auto:creatorAccount}" },
    "height": 560,
    "mobile": "button",
    "readonly": "auto",
    "writeback": { "enabled": false, "fields": [], "map": { "invoice_no": "amount" } }
  }
}

这是本仓库既有的三层配法(L1 协议与密钥归 IT,L2 业务映射归业务顾问,L3 挂在具体位置上): 源上管"这个页面长在哪、接受哪几个参数、用什么密钥",字段上管"这一单要带哪几个参数、值从哪一格来"。 同一个页面在采购申请和合同变更里各嵌一次、各带各的参数,不用复制第二条注册记录。

2.2 参数由后端渲染,浏览器只说"我要哪一格的哪一单"

前端只发 {code, field, job},后端从 work.data 现取参数值、渲染模板、再拼上票据, 返回最终地址。单据已经存在时不接受前端传来的参数值——和 service/fetch.py 开头那条 "外部回来的值以这里为准"是同一个分寸:能自由拼 URL 的那一端,等于拿 OA 当任意跳板。

唯一的例外是发起页:那几格是人在这一秒刚敲进去的,库里还没有单据可问。所以只在这条路上 认前端交回来的值,而且只认 {form.x} 那一类({auto:…} 后端自己算得出,不收前端的)。 兜住它的是三件事:只认地址模板声明过的参数名、单个值截到 500 字、短码绑在这个人身上; 何况这个人本来就要把这些值提交进这张单,对方系统那边还有一道按人判的权限。 实现见 service/embed.py:resolve_params。

参数名的白名单就是地址模板本身:模板里没写 {arg.x} 的参数名一律拼不进去, "设计者把整张单的值都塞进查询串"这件事根本没有入口。代价只是设计期要多说一句 「这几个参数这个页面用不上」(§8)——不说的话它是静默失效,那是最难查的一种配错。 这句话里"参数该写在哪一栏"跟着 url_mode 换:模板那一档说"地址里没写",接口那一档说 "接口地址、请求头、请求体里都没写"(§2.4 第 3 条)。措辞前后端各写一份,check_embed.py 盯着。

挨着的一条同样静默:参数名写了、取值写法空着。那一格每次带过去的都是空值,上游常常 直接回一句 xxx is required,而看的人第一反应是去怪对方接口。所以设计期也挡一句 「参数「x」只写了名字、没写取值写法」,接口回 4xx 时那一句错里再补一次"这次带过去的入参 里有几个是空的"(只报名字,值一个字都不说)。

2.3 域名白名单落在 CSP 上

启动时(以及注册表变更时)把启用中那些源的 origin 汇成一份响应头:

Content-Security-Policy: frame-src 'self' blob: https://erp.example.com https://hr.example.com; frame-ancestors 'none'

为什么注册表挡住了还要这一层:表单 JSON 是能从别的门进来的(AI 起草、流程导出导入、直接调 api/design.py),得有一道不在表单校验链路上的闸。frame-ancestors 'none' 是顺手补的—— OA 自己任何时候都不该被嵌。

两个坑,别踩:

  • 'self' 和 blob: 必须留着。附件预览走的是 URL.createObjectURL 出来的 blob: 地址塞进 iframe(components/common/FilePreviewDialog.vue),PDF 那一支漏了就整块打不开; HTML 附件走的是 srcdoc,部分浏览器按 'self' 判。改完 CSP 要把 attachment-preview.md 那几条渲染路线一起回归一遍。
  • CSP 只写这一处:现在后端只有 LiveCORSMiddleware 与 gzip 两层,加一个只写响应头的中间件 就够了;别在 nginx 和后端各写一份,两份 CSP 的取舍是取交集,最后表现为"某个环境下莫名其妙嵌不进"。 白名单来源走运行配置(库里 config:security 那一份,config.toml 里给出厂默认), 与 hub / storage 那几组同一套改法:改完即生效,不重启。

2.4 地址也可以是对方接口现给的(url_mode = "api")

有一种页面 OA 拼不出来:对方那一页是按这张单现生成的。调它的接口、传进单据号与操作人, 它回一条带签名的临时地址(https://erp/view?k=eyJhbG…),同样的参数下次就是另一个链接。 这种时候"注册表里那条地址模板"根本没有模板可写——能写的只有"该调谁"。

于是 provider=embed 多一档 url_mode,它只回答一个问题:这一页的地址从哪来。

列 template(默认,行为一字不变) api
url 页面地址模板 取链接的那个接口地址(参数位照样写 {arg.x})
method / headers / body_template / auth_* 不用 调这个接口要用的那一份,与取数同一套,不新造一套
url_path 不用 链接在响应里的点路径(data.url / data.0.link)
url_origins 不用 接口回的链接允许挂在哪几个来源上;空 = 只认接口自己那台主机
mock_payload 不用 样例响应:对方接口还没开发完时,先拿它把解析、探测、表单那一格配通

表单上那一格什么都感觉不到——它照样只交 {code, field, job},照样只配"哪个参数从哪一格取"。 换掉的只是地址从哪来,五条规矩一条都没松:

  1. 调用还是在这个后端发生(service/embed.py:resolve_link),浏览器连那个接口的地址都看不见;
  2. 参数值还是后端算的那一份(§2.2 那句"已有单据不收前端交回来的值"照旧);
  3. 参数白名单变成三份模板的并集:接口地址 + 请求头 + 请求体里出现过的 {arg.x} (declared_args)。少算一份,就会把明明要用的参数报成"这个页面用不上";那句提示也跟着 换成"接口地址、请求头、请求体里都没写",同时数据源页的「入参」那一页在模板那一档会直接说 "这一档不发请求,这几行送不出去"——两头都指着同一件事,配的人才不会去地址栏里找一个 根本不写在那儿的 {arg.};
  4. 熔断、限流、超时、重试、留痕全复用取数那一份(fetch.outbound_guard / outbound_mark), 留痕多一类 kind=link。于是"他当时到底看没看到那个页面"多了一段可对答的中间过程: 是接口没答话,是答了没给链接,还是给了一个不认识的域名;
  5. 取回来的链接要过两道判断:url_problem 那把老尺子(https、不带账号密码、看得出主机名), 再加一道来源白名单(allowed_origins = 接口自己那台 + url_origins)。

第 5 条是这一档的命门。注册表之所以敢当那道 URL 闸,靠的是"地址写死在管理员登记的这一行里"; 地址一改由对方回,"回什么就嵌什么"就等于把那个接口变成一条能指哪儿嵌哪儿的跳板。 所以来源不认识就整件事停在这儿,并且说一句人话:指向哪个域名、这张源允许哪几个、去哪儿补。 frame-src(§2.3)跟着搬同一份清单——配置页上写了允许的来源而 CSP 里没有那台主机, 浏览器会自己把框拦下来,报错只出现在控制台里,那是最难查的一种"配好了打不开"。

三条顺手要交代的口径,界面上都写着:

  • 只回一个路径(/pages/contract/123)按接口那条地址补全来源,不当成非法地址;
  • 取不到链接时把候选念出来:_link_candidates 扫这份响应里看着像链接的那几个位置,回一句 "要的是 data.url,这份响应里看着像链接的还有 data.link"——比让人对着接口文档猜点路径快得多。 不自动改用其中任何一条:猜中的那次通常也是错的;
  • 这一档不吃 cache_seconds:那种链接多半是一次性的,缓存下去第二个人拿到的就是别人用剩的。 mock_payload 非空时干脆不打真接口,所以探测结论里一直挂着"这次用的是样例,上线前清空"那句。

参数变了还是不自动重载(§5.1 那条老理由:他可能在对方页面里填到一半),但那句提示换了说法: 链接是按旧值生成的,这一回点「刷新」不是美化,是真的得点(EmbedFrame.vue:staleDynamic)。

「测试连通」探的也不是那个接口通不通,而是取回来的那条链接让不让嵌(探接口地址毫无意义, 它压根不会被嵌):先用测试弹窗里那几行入参走一遍取链接,再拿结果去读 XFO / frame-ancestors。

钉在 check_embed.py「地址由接口现给那一档」(白名单并集、来源闸、候选提示、样例顶包、 GET 不带请求体、熔断期间一次都不外呼、地址自己带 # 时短码换个挂法)与 embed.spec.ts 里「允许的来源」那一段。

2.5 本机与内网联调:这一条什么时候不必讲 https

url_problem 那把尺子要求 https,理由只有一个:https 的页面里嵌一条 http 的 iframe, 浏览器一定拦(混合内容)。这条理由在联调时常常不成立——开发机上的目标服务就挂在 http://192.168.1.20:8000,本机那台 OA 自己也是 http://localhost:5173,两头都明文, 没有谁拦谁。所以这一条例外按"公网上路由得到吗"划界(fetch.is_private_url,环境代理绕开本机与内网用的也是它):回环、10/8、 192.168/16、172.16/12、链路本地、fc00::/7、100.64/10(Tailscale 那一类),加上 localhost 与 *.local 那些本机主机名,都可以直接写 http。三处一起松——页面地址、 「地址由接口现给」那一档的接口地址、以及接口回回来的那条链接;CSP 的 frame-src 也跟着收这些 origin。

公网地址照旧只收 https。整片内网确实一个 https 都没有的部署还有一条明路: [embed] allow_http = true(环境变量 OA_EMBED_ALLOW_HTTP)。它默认关,生产档开着会在 启动体检里点名,因为那时那条 iframe 既会被浏览器拦、又跑在明文链路上。

3. 免登:iframe 里能不能看到东西,全看这一步

一句实话先说在前面:一个没有登录态的 iframe,多数业务系统会 302 到登录页,而登录页自己也带 X-Frame-Options,于是浏览器控制台甩一句 Refused to display,用户那边只有一个白框。 所以"嵌页面"这件事的工作量大概九成在免登与浏览器策略,一成才是那个 <iframe> 标签。

3.1 三档免登

档 怎么成立 什么时候用
none 公开页,或者目标系统与 OA 同主域、登录态 cookie 本来就在浏览器里 内网看板、知识库、同一次 SSO 已经覆盖到的系统
hub 让统一门户发一次免登跳转,service/hub.py:HubClient.launch(token, {code, state, redirect_uri}) 已经写好了,这一格只是把返回的地址交给 iframe 目标系统本来就是 Hub 上注册过的应用(对接指南第 3、4 节那套)。前提:Hub 得允许这个应用被嵌,这跟 OA 无关,问 Hub 那边
ticket OA 自己发一张一次性短码,对方服务端拿短码调 OA 换身份 默认推荐。对方只要实现一个校验接口,形状照抄 OA 自己消费 Hub 票据那一份(hub.verify_ticket,反方向)

ticket 这一档的做法几乎是照抄 service/sso_handoff.py,只是方向反过来(那边是别人发票 OA 兑, 这边是 OA 发票别人兑):

新表 oa_embed_ticket:只存短码哈希与参数指纹;60 秒;用一次即烧;绑 (人, 源, 单据)
GET  /api/v1/embed/sources              设计器与填单页拿"能嵌哪些页面"(只回名称与探测结论,不回地址)
POST /api/v1/embed/launch               body 带 {code, field, job, activity};后端按当前人与
                                        当前环节重算可见性 → 返回最终地址(短码在 # 之后)
POST /api/v1/embed/tickets/verify       对方服务端调,带应用密钥 → 返回身份 + audience

对方拿到的身份是当前看单的那个人,不是发起人。这条是整个设计里最值钱的性质: 审批人点开 ERP 那一格,ERP 的日志里记的是他自己在看,权限也由 ERP 自己判—— OA 没有变成一层把权限抹平的代理。反过来说,如果某个系统的账号体系和 OA 对不上, 那这一格只能显示成"用服务账号看只读页",那是访客模式:默认关,要在源上显式勾选、 要有 design:datasource 权限、要在留痕里写清楚,因为对方日志里会看到同一个账号在看所有单。

3.2 浏览器会替你挡掉的四种部署,写进对接契约

现象 为什么 怎么解
https 的 OA 嵌 http 的页面 混合内容,浏览器直接拦,没有商量余地 目标系统上 https(本机与内网地址不受这条限制,见 §2.5)
iframe 里始终"未登录",可新窗口打开又是登录好的 第三方 Cookie 正在被逐个关掉(Safari ITP 早就全禁,Chrome 在分阶段推),跨站 iframe 里的 SameSite=Lax cookie 根本不发 目标系统的会话 cookie 改 SameSite=None; Secure;更好的解法是部署时放同一个可注册域:oa.example.com 与 erp.example.com 是 same-site,这一整类问题直接消失
页面在 iframe 里自己跳走了 目标系统里有 frame-busting(top.location = self.location) 只能让对方去掉,或这一格改用「新窗口打开」——探测探不出这种,见 §4
一进来就是个登录框 免登没配上(none 档却需要登录态) 换 ticket / hub,或者让人先在新窗口登一次再回来

4. 嵌不进去怎么提前知道:探测 + 降级

探测挂在注册表那条记录的「测试连通」上,复用 last_test_* 那四列,不新增界面。服务端 GET 一次目标地址,只看三件事,结论写成人话进 last_test_message:

可嵌入                      —— 没有 XFO,frame-ancestors 里没有排除本部署的来源
被 X-Frame-Options 挡住     —— SAMEORIGIN / DENY,附回的具体值
frame-ancestors 不含 OA 地址 —— 附对方允许哪些来源
像是要登录(302 到 …/login)  —— 免登八成没配上,先回属性面板看 page_mode

这条探测必须走 service/fetch.py 那一份 HTTP 出口(含本机直连绕环境代理那点讲究、超时、 留痕),别在 embed 里再起一个 urllib。

诚实的边界要写在界面上:发探测的是服务端,真正拒绝渲染的是浏览器。同一个地址,登录态不同 回的头可能不同;frame-ancestors 也可能是网关加的而业务页没有;JS 的 frame-busting 完全探不出来。 探测只是"别让人上线之后才发现",不是保证。

四种结论摊给界面的形状(service/embed.py:_verdict)也有讲究:弹窗只在 error / note 非空时才显示内容,所以 denied 走红的 error(它不算探测通过——清单那一行的角标和 EmbedFrame 要不要降级成卡片都把它当失败,唯独弹窗跟着 ok 绿过一次,等于探测白做了一半), unknown 走琥珀的 note(说不准不是失败,但那句"以实测为准"必须让人看见),只有 ok 是空的。 钉在 check_embed.py「探测结论摊给界面的那份形状」与 check_embed_api.py「能不能被嵌」。

所以降级路径比探测本身更要紧。mode 三档 auto | frame | link,auto 时前端遇到下面任一情况 就整块换成一张卡片,不留白框:

  • 源被停用 / 被删 / 后端说这一格在这个环节不该出现;
  • 地址拿不到(发票失败、可见性没过)——卡片上那句为什么用的是后端给的那句人话, 不是笼统一句"加载失败";
  • 属性面板把它配成「只给一张卡片」,或者窄屏而它配的是「窄屏只给按钮」,或者在只读场合而它配的是「点「打开」才加载」(默认那一档,打印那一份永远是这一档);
  • 地址要的那几个参数这份单还没给(回一句「还差这几个值没填:xxx」,比开一个空白页客气)。

卡片上是:页面名、属于哪个系统、那句为什么、「打开」(手上没票就现发一张再开)、「重试」。 没有「复制地址」这一项:那条地址上挂着刚发的免登短码,能复制就能贴到别处去, 而它 60 秒就废,复制走的只会是一条骗人的链接。

真框里那层「正在加载」只兜"整页没响应":15 秒之后自己摘掉,不装作能判成败——跨域 iframe 连 对方的错误页都会触发 load。所以后端说得出原因的走卡片,说不出原因的让那个人自己看见 对方系统回了什么,比 OA 替他猜一个"加载失败"有用。

5. 一个 iframe 摆进审批页,风险具体在哪

风险 会长什么样 怎么挡
钓鱼 设计者填一个仿 ERP 的地址,全公司在真 OA 里输密码 设计者没有填 URL 的地方;注册表要 design:datasource;地址改动留痕(从哪改到哪);CSP frame-src 白名单兜底
越权看内容 不该看 ERP 的审批人手里出现一条带票据的地址 后端在发票那一刻按当前人和当前环节重算一遍 effective_perm,不看前端传来的可见性;环节「隐藏」是这一格的第一道闸;对方系统再按自己的账号判一次
谁算与这张单有关系 一条免登地址发给了根本不该碰这张单的人,或者反过来:被抄送的人看得见整张表单,唯独这一格发不出地址 后端只认四种关系——他名下有这一单的待办、他办过这一单、他是发起人或管理员、他在这张单上有待阅 / 已阅(抄送、分享、批注提醒都算,判据与「我的待阅」那条查询同一个)。判据在 api/embeds.py:_scope_of;GET /job/{job} 那一头不问关系,所以发地址这一头必须问,否则两边口径不一致。第四种不借任何人的环节权限:他自己没有环节,别人正卡着的那一环也不是他的,借来看等于把"别人那一环恰好把这一格藏了"当成"他也不能看" —— 这一档只看表单字段自己的权限(含字段联动)
点击劫持 外页在框里画一个假「同意」,压在 OA 真按钮上方 sandbox 不给 allow-top-navigation;这一格整行占满、下面留白,OA 自己的提交按钮不与它同屏挤压;探到不可嵌就降级
票据外泄 URL 进了浏览器历史、Referer、代理日志、导出表、打印件 短码放在 # 之后(浏览器不会把片段发给第三方,也不进 Referer);60 秒 + 用一次;导出与打印里绝不落 URL(§7);日志只记参数键与指纹,不记整条地址
沙箱给多了 外页能弹窗伪造系统对话框、能带顶栏跳走 默认 sandbox="allow-scripts allow-same-origin allow-forms allow-popups",明确不给 allow-top-navigation、不给 allow-modals。注意 allow-scripts + allow-same-origin 对被嵌方等于给了它自己那份完整能力——这是它正常工作的前提,不是漏洞,但意味着只白名单 origin 才配进来
沙箱给少了(反过来的那种坏) 对方那一页显示得好好的,可什么按钮都点不动:确认框不弹、导出的文件不落、点一下本该整页跳走的什么都不跳 在这一格上按项放开(embed.sandbox,判据 service/embed.py:sandbox_of),而不是把整串 sandbox 交给人手填——手填的人一定会顺手填上 allow-top-navigation。清单只有六项,写歪的名字保存那一刻就点名
回写通道被冒用 任意页面 postMessage 就能改这张单 见 §5.2,三道校验加五道闸一条都不能少
OA 自己被嵌 OA 的页面成为别人的素材 frame-ancestors 'none',随 CSP 一起加
验票接口是匿名的 它是这个功能对外新开的唯一一个不需要登录会话的口——对方服务端来换身份,总不能先登录 OA 三条兜底:短码是 256 位随机、只用一次、60 秒就废;应用密钥常数时间比对;失败只回一句笼统话,不让它变成"这条短码存不存在"的探针。真正要防的是密钥泄露,所以那把密钥只进不出、可随时换一把,且只有 design:datasource 权限的人配得到

5.1 进来的那条路:值怎么进 iframe

地址模板就是参数白名单(§2.2),这一句决定了进来这条路的形状:注册表那条地址写成 ?no={arg.contractNo},这一格就只可能看见 contractNo 这一个值,属性面板上配了别的名字也 拼不进去。于是"设计者一高兴把整张单灌进查询串"这件事没有入口——这也是发起页敢收前端交回那 几格值的前提(§2.2)。

iframe 装载完,OA 先递一条 oa:handshake {nonce, origin, params}:一次性 nonce、OA 自己的 origin,外加后端算好的那一份参数值。值本来就在地址里,但让对端去解析自己的查询串是给自己 找麻烦(短码还在片段里),现成给一份,对接就少一处能写歪的地方。

填单途中那几格改了怎么办。参数引用的是表单上的格子,格子一改,页面要看的那一单其实就不 是原来那一单了。EmbedFrame.vue:refreshParams 盯着 watchedKeys(参数表达式引用到的那几格), 改动之后 debounce 800ms,调一次 POST /embed/launch {refresh:true} 让后端按现在这张单重算, 再用 oa:params {nonce, params} 推给已经开着的那个页面。三个决定值得留字:

  1. refresh 那一趟不发地址、不发短码、也不留痕(api/embeds.py:launch 里那条分支)。 留痕记的是"他打开了那个页面",把每次刷新都记成一次打开,台账就没法看了;可见性照旧重算, 所以这一条不多给任何东西。
  2. 绝不自动重载 iframe。那个人可能正在对方页面里填到一半,重载等于把他写的东西清干净—— "我这边的值变了"不该由他来付代价。对端没实现 oa:params 时只标一句「这个页面还是按旧值 打开的」(form.embedStale),要不要点刷新由他自己决定。
  3. 能推的只有后端算过的那一份(发票时给的 params,或这条 refresh 重算的那一份), 所以"外部页面能看见哪些值"永远不超过地址模板声明过的那几个参数名。这条不变量是出去那条 路敢开的全部前提。
  4. 同一句 refresh 还把整张单的表单值捎给后端留着(请求体里的 form → embed_session.remember_form)。这一份不出 OA:它不进地址、不进 oa:params,第 3 条那条 不变量一个字都没动。留它的地方是服务端建单——第三方一句裸回写要代发的是整张单,而那一格 通常只引用五六个参数,收款方式这种没被引用的必填格只有这一份接得住。判据与上限: 只有发起页那一路(没有单据)才收,只认这张表单定义过的格名(api/embeds.py:_form_snapshot), 键数 80 / 单值 8000 字符 / 整份 48000 字符,被上限挤掉的格名记在 _formSkipped 里供排查; 那一句没带 form 就不动已有那一份(老前端与有单据那一路都不带)。底稿顺序见 node-open-approve-design.md §4.6.2。 发起页那一路这一句的触发器也跟着换成 screenSignature(盯整张单,不只 watchedKeys 那几格)——不然"收款方式"那种没被任何参数引用到的必填格,人改了后端一次都不知道, 那份底稿就永远停在他第一次点开那一页的样子。推给对端的东西仍只按第 3 条那一份算。 还有最后一拍要接:那 800ms 还没到点而人已经走了。在 OA 里换页面(onBeforeUnmount) 与关掉页签(pagehide)两条都调 EmbedFrame.vue:flushPendingSnapshot,把同一份 refresh 报文改走 fetch(..., { keepalive: true }) 再送一次(api/embeds.ts:launchEmbedKeepalive)—— 正在卸载的那一刻 axios 发不出去,理由与 abandonEmbedSessionsKeepalive 那一条一模一样, 而"填完最后一个字段就关页面"恰是最常走的那条路。它不等回包(started / staged 是留给 还看着这一页的人的),也只在该补时补:防抖落下那一刻把 pushTimer 清成 null, 没攒着改动就不多发这一句。判据 EmbedFrame.params.spec.ts「走的那一刻补送」那 4 条。

{auto:…} / {const:…} 那两类参数不进 watchedKeys——前者后端自己算得出,后者压根不变。

5.2 出去的那条路:值怎么回表单

回写默认关,且只有属性面板上点过名的格子收。"点过名"是两份清单合成出来的那几条对应 (utils/formRuntime.ts:embedWritebackRulesOf,后端 service/embed.py:writeback_rules 同一份算法), utils/embedBridge.ts:resolveTargets 是失败即关的写法:合出来是空的(一个都没勾、也没配对应) 就等于这条通道没开,一条都不收。这个默认值值得多说一句—— 写成"空清单=不限制"太顺手也太自然,而它的后果是"什么都没勾的那一格反而什么格子都能写", 安全边界上最坏的那种默认值。这条已经被测试抓到过一次(embedBridge.spec.ts)。

一句 oa:result {values, nonce} 从 iframe 到 work.data,要过两道地方的五道闸。 EmbedFrame.vue:onMessage 只管消息本身那三道校验,一条都不能少:

  1. event.origin 等于发票那条地址的 origin——别的站点往顶层窗口 postMessage 是免费的;
  2. event.source === iframe.contentWindow——少了这道,iframe 里 302 到别的站点之后,那个站点 同样能顶着它自己的 origin 冒充"我们打开的那个 frame";
  3. nonce 一个字符都不差,由 OA 前端每次装载现编(crypto.getRandomValues,不用 Math.random),只递给这一个 frame。

nonce 只压在想动数据的那一条上:oa:ready / oa:resize 只改那层"加载中"和框高,动不了 数据,就不逼对方带 nonce——已经照 §11 实现了 resize 的页面不用改一行就能继续用。这是权衡不是 疏忽。

再往后是 FormRenderer.vue:applyWriteback,它判的是另一件事:这一格本来收不收、这个人本来 改不改得动。这一层的组件看得见环节权限与联动锁,EmbedFrame 看不见,所以判断分两处不是随意:

  1. 这一格得真的在这张表单上(明细列不在这一层,回填只写主表);
  2. 这一格收得下:版面与系统带出那两类不存值、挂了额度或阈值的一律不收 (service/embed.py:writeback_refusal 与 utils/formRuntime.ts:embedWritebackRefusal 是 同一份措辞,由 check_embed.py「前后端措辞对齐」对账)——外部系统只能提供值,不能决定 流转(service/fetch.py 开头第 3 条);
  3. 这一格在当前环节不是隐藏的(藏起来的格子不该被谁隔着 iframe 悄悄写一笔);
  4. 这一格本来就改得动:只读页、环节给了只读、联动锁了、系统带出与公式,全都收不了;
  5. 值得先按这一格的类型收下来(embedBridge.ts:coerceWritebackValue),收不下就当场说。

第 7 条是关键,它保证"外部页面"这个口子不会比填写人自己的权限更大:他改不动的格子,别人 的页面也写不进来;他改得动的格子,他自己本来就能敲——回写省的是他的字,不是他的责任。

5.2.1 对方那个键不叫这个名字:writeback.map

白名单只有 fields 那一份时,隐含一个要求:对方的键必须和 OA 的字段名一模一样。 真实对接里这个要求多半落空——回传的口径是第三个系统定的(invoice_no、ht_amount、 kpgssh),改不动,也不该为了 OA 去改;而让配表单的人去把字段名改成对方那套拼写,等于让 OA 的字段名替别人家的口径背锅,改名还会牵动条件、导出、取数落点(utils/formRename)。 所以对应关系得能在这张单上直接说清楚:

"writeback": {
  "enabled": true,
  "fields": ["contractNo"],                  // 同名直写:对方发 contractNo 就收
  "map": { "invoice_no": "amount" }          // 他发 invoice_no,写进我这单的 amount
}

四条口径:

  • 两份清单合成一份规则([{from, to}])是唯一的读法,属性面板、运行时收消息、保存那一刻 三处都只读它。各处自己算一份,就会出现"面板上看着配好了、对方发过来什么都不写"。
  • 对方那个键撞名时对应表赢:fields 里有 amount、map 里又写 amount → contractNo, 那一条就不再按同名收。改名的意思就是"别再按我这个名字认",这里不排两条并存的先后。
  • 一格只认一个来源:同名那条与某条对应同时指着同一格,由保存那一刻挡 (「amount」这一格被两条对应同时指着(amount、both))。让报文里的键顺序决定收谁, 是最难复现的一类 bug。
  • 对应只改"叫什么",不改"能不能写":那一格收不收得下、这个人在这一环改不改得动, 判的还是上面那五道闸。改名不是开后门。

面板上的样子在 §6。运行时收下来之后,往下走的只有 OA 的字段名——对方的拼写不渗到 applyWriteback 之后任何一层;只有回执例外(它回的是对方发来的那个键,见下)。

收不下的句子不静默丢:拼成一行显示在那一格下面(FormRenderer.writebackResults,按 embed 字段分开存,两个嵌入格不会互相串台),写成了 「金额」值不是一个数字 这种样子; 同一份结论还回一句 oa:ack 给对端(EmbedFrame.ackWriteback),让对面那个页面也能说清 "哪几格写进去了、哪几格为什么没写"。回执里的键回的是对方发来的那一个(invoice_no 而不是 amount):他拿回执是去对自己那份报文,回一个他名单上没有的名字等于没回;没配对应时两者本来 就一样,存量对接方不用改一行。回填最常见的故障就是对 方口径差一点,这一句是整条路上最值钱的一句话。每来一句 oa:result 就把这一格上一次的几句 换掉——留着的该是"现在还没收下"的那些。

类型口径(coerceWritebackValue):money / number 先擦千分位、全角逗号、货币符号, 剩下的必须整个是个数;switch 收 是/否、true/false、1/0、开/关、同意/不同意; 日期类只认这一格自己存的那种写法,不做"尽力解析"——new Date('1/2/2026') 那类解析会写 出一个看起来对、比一天差一天的值,那是对接问题不是运行时该猜的事;select 先按要存的值匹、 其次按唯一的候选名匹(同名两项就让他自己选,不赌第一个);checkbox / week / 多选的 select 按顿号逗号分号竖线换行拆数组;明细、附件、签名、选人、部门、级联、地点、关联单据 这些结构类的一律不收——它们的值不是一行文本能表达的。

诚实的边界:nonce 不是服务端凭证,它只证明"说话的这个 frame 是我刚装载的那个",不进地址、 不进日志、不经后端。提交那一刻后端分不出某个值是人在框里敲的还是 iframe 写进来的,所以 这条路上所有能力判断都压在两处:设计期(属性面板 + embed.problems)与写入那五道闸,事后没有 "外部写入"这条独立的留痕。真要在服务端逐笔审计"谁写了这一格",得先让回填走一条独立接口, 那是另一件事(§10)。

6. 设计器与填单页分别长什么样

设计器里不加载真 iframe,画布上是一张假框。三条理由,每一条都足以单独否决:

  1. 画布一栏只有整页三分之一宽,别人的页面在这个宽度里根本看不出长什么样;
  2. iframe 会吃掉落在它上面的鼠标事件,画布的拖拽排序、选中、右键菜单会整片失灵;
  3. 每次打开设计器就打一次生产系统、发一批免登短码,纯粹给上游制造噪音和安全隐患。

假框里显示:源名与它属于哪个系统、要带哪几个参数、上一次探测的结论、一个「预览」按钮 (点了才走一次真发票,在弹窗里加载,看完就关)。属性面板里加一段「外部页面」:挑源(按 system 分组,抄 design/ProcessPicker.vue 那个挑法,旁边给一个「去注册」的链接)、显示方式 (嵌入 / 新窗口 / 自动)、参数表格(直接复用 design/ParamTable.vue:键、取值写法、备注、停用行)、 高度、移动端表现,以及回写白名单(§5.2:点过名才收,收不下的那一行灰着并写明为什么—— 挂了额度、版面格、这一环改不动,都在这儿当场看见,不用等对方发一条过来被静默丢掉)。

白名单下面跟着一张对应表(§5.2.1):左边敲对方回传里那个键叫什么,右边从这张单的格子里挑 一格,两头像填全了那一条才存得下去(所以表末永远留一行空的,跟参数表一个规矩)。右边那一列 把收不下的格子也摆着,只是选不动——选不动比选完吃一句红字客气。上面那份勾选里被某条对应指着 的格子,行上会跟着念一句「由「invoice_no」写进来」,两份清单在界面上就对得上号,不必来回切。 这一段和「标签页」里那一页外部页面用的是同一块面板(design/EmbedPanel.vue),两处不会长成两套说法。

参数表那两列都是下拉:ParamTable 收了两个可选的清单(keyOptions / valueOptions), 给了就换成可搜可挑的框,没给的表(请求头、可带出键那些)照旧是输入框。名字那一列的候选就是这个 页面声明过的入参——后端 resolve_params 本来就只认这一份清单,清单外的名字既拼不进地址也进不了 那次接口调用,所以这一列从来就该是挑的、不是敲的。值那一列摆的是这张单上的格子(挑完写成 {form.格子名})加上一批 {auto:...} 系统值;不产生值的那几类不摆进来(utils/fieldCapabilities 的 LAYOUT_TYPES、明细行,以及附件那几类——_as_text 把它们摊成空串,挑了等于没挑)。两列都留着 可自造:{const:文字} 没人列得全,源那边刚加了一个参数而这边清单没同步时也得有路走, 敲进去的那一句照旧存得下来,只是名字不在清单里会被面板点一句名。挑完走的是整份重发 (ParamTable:setCell 换掉整个数组),不是改完行对象等下一次补行才交——中间那一行改完不碰末行, 配置会一直停在旧值上。

已经被别的行用掉的那个名字在下一行的下拉里挑不动,后面跟着写出它在第几行:那一份对象装不下 两条同名参数,真挑重了写回去会并成一条、那一行当场从表格里消失,比一列灰掉的选项难查得多。

参数表那一栏有一条容易踩空的不成文规矩:交回面板的行末尾永远得留一行空的。 ParamTable 发现末行有内容就 emit 一句"再补一行",而那份行是从 embed.params 现算的——空行 转回 record 时按名字被丢掉,行就又是一份没有空行的数组,它再 emit 一次,来回没完(vue 当场报 Maximum recursive updates)。空行由 EmbedPanel:rows 用 paramRowsWithBlankRow 补上,那句 emit 就永远不会自己响。谁换掉这块面板的绑法(比如把配置挂到别处、每次写回都换个新对象)都会把这条 踩出来——标签页里那一页外部页面就是这种绑法,design/TabsConfigDialog.spec.ts 里钉着。

填单页与审批页:标题行左边是字段标题,右边三个小按钮——刷新(重新发一次票)、展开(整屏看 这一页)、新窗口打开;下面是一整行高度的框,默认 480px 起,配了 units: 12 就整行铺开。加载 期间给一层「正在加载」,15 秒之后摘掉(§4 说了这一条只兜整页没响应);对方页面愿意发 oa:resize 报自己多高,这一框就照它给——框里不再出自己那条滚动条,人在 OA 这一页里滚 一整页,不发就用配的那个高度(配高那一栏的上界是 4000,够把一整页直出;同源那一档 OA 自己 进去量,见 form-tabs-embed-design.md §3)。

「刷新」那一下有两个坑,都在这儿填:① 成功那一次是给那一框换了一个 key,不是只换 :src——同一张单现生成的链接常常与上一次一字不差,串没变属性就没变、浏览器一次请求都不发, 而那层「正在加载」已经盖上去了,屏幕上就是一片灰一直到 15 秒兜底,人看见的是"点了刷新反而 加载不出来";② 失败那一次留着还开着的那一页,只在框上面说一句「刷新没成功:……」。 这一档每点一次刷新都打一次对方接口(service/embed.py:resolve_link),偶发 5xx、限流、60 秒 静默期都是常规事,把一次失败的取地址换成一张错误卡片,等于让人正在看的那一页、在对方页面里 填到一半的东西替这次失败付账。第一次就没打开时照旧退成卡片——那时候没什么可留的。「展开」那一层是给不肯报高度的页面留的退路:盖住整屏,报过 高度就整段铺开、没报过就铺满这一屏,ESC 或「收起」退回来,换来源换单据也会自己收。这一页 要带的那几格还空着时这一颗按钮是灰的(点也点不动)——那一屏铺开的是一张缺项的页面,等于 把报错放大到整屏。判据只有一份,见下面那一段;三条高度规则的完整口径见 form-tabs-embed-design.md §3。

要带的那几格还没填上,这一页根本不打开(openWhen,默认 filled)。这一档治的是这一格 最难看的一种屏:那几行参数的取值写法就是"取某一格的值",人还没填就点开这一页,发过去的是一串 空值,对方回一句 account is required,屏幕上红着一片——而这一页本来还没到该打开的时候。 所以现在:

  • 界面上三处锁在同一份判据上(utils/formRuntime.ts:embedPendingParams):卡片上那一句 「先填上才让打开,不是程序坏了」、「展开」那颗钮、以及收折那一种排法里的段头 (form-tabs-embed-design.md §2.5)。三处必须同时成立或同时不成立, 差一点就会出现"段头锁着、里面却已经把页面装出来了"那种自相矛盾的屏。
  • 而且一次请求都不发。发出去多半挨一句 4xx,那一次失败还要记进熔断与限流那本账—— 连着几个人先后点开,这条源能被自家闸判成"上游坏了",于是所有人也都打不开了。
  • 只认整段就是一个 {form.x} 的那几条写法:{auto:…} 后端自己算得出、{const:…} 永远不变, {form.a}{form.b} 与 {account:form.x} 这类判不准。判不准就别锁——宁可少锁几格,也不要把一段 永远解不开的死结扣在人身上。另外两类同样不锁:引用的那一格压根不在这张表单上(那是 配歪了,由保存那一刻点它的名 embedConfigProblems,不该由填单的人来还),以及那一格是 系统自己填的那两类(auto 单据编号、formula 公式)——发起页上编号是后端预留之后才写回 表单的,锁下去只会得出一句"先填:流程编号",而屏幕上那个人对着它什么也做不了。只读场合也 不锁:那里压根没有能填的格子,锁住等于把这条路整个堵死。这几种情况真到发出去还是空的那一步, 由后端那道网点名(见下面那段)。
  • 出口在属性面板:「什么时候能让这一页打开」改成「任何时候」。后端跟着这一档放行 (service/embed.py:open_when_of)——界面上说让开、后端拦着,是说一套做一套。

后端另有一道网,比界面那道宽:url_mode=api 那一档在发调用之前按"这一格配了参数名、 这一次算出来是空"(service/embed.py:unfinished_args)直接不发,留痕记成挡住的那一类。 地址模板那一档不拦:那边不发请求,空一位顶多是对方页面少一个查询参数,拦下去会误伤 "那一位本来就可以空着"的配置。两边那句人话共用同一句措辞("……不是程序坏了"), 由 scripts/check_embed.py 对账。

只读场合(已办、代看、单据详情)默认「只沿用已有那一页」:库里存过对面那一条地址就直接把真框装上,一次建页接口都不打、一条短码都不发;没存过就还是那张卡片——只留一句「外部页面:合同详情(ERP)」和一个「打开」按钮,不替你新建一页。三档(button / auto / frame,默认 auto)的取舍与那句「打开就看到的是不是配置的查看页」见 embed-configuration-guide.md §2.1.4。

只读场合自动加载之后,还得让对面认得出是同一趟:那一屏必须把 job 递到这一格上, 否则后端把这次打开当成"发起页、还没单据",会话落在最宽那一档(人 + 格子 + 源)上, 每打开一次换一个预受理号。这一档本身可配(embed.reopen,三档,判据与理由见 embed-action-design.md §2.1),钉它的断言在 FormRenderer.readonly-embed.spec.ts。 后面的人点开同一格也不再新建一页——那一页记在这张单上(oa_embed_page,§2.1.1), 换人不换页。

这一档配在格子上(embed.readonly,三档 button / auto / frame,默认 auto,判据 utils/formRuntime.ts:embedReadonly、后端同名 service/embed.py:readonly_of,认不出的值退回 auto): auto 只问库里有没有已有那一页,frame 才是每次都现问一次。现问一次的代价说清楚:每打开 一次这一屏就发一条新短码、往台账里记一次「他打开了这个页面」,而对面那个接口每问一次建一页。 回看屏那一句请求还带 viewOnly=true,它只往严收:link=auto 不再问手上有没有待办,一律查看页; 当前环节把这一格设成「隐藏」也不再把这一屏挡在门外(办理屏照旧挡)。

打印那一份不吃这一档(EmbedFrame 的 printing,由 FormRenderer 拿 flatten-tabs 递进来), 永远只给卡片:纸面上打不出 iframe,为一张纸发一条短码、记一次没发生过的访问,两头都是假的。

移动端:mobile 配 button(默认)时窄屏上不加载、只给一张卡片;iframe 里的表单在手机上 基本不可用,这是产品判断而不是技术限制,所以在字段上可配、可翻回来。

7. 值、条件、额度、导出:这一格一律不参与

  • 条件搭建器里不出现(utils/routeExpression.ts 的字段候选按 fieldCapabilities 走,落在 LAYOUT_TYPES 就自动没了);阈值、额度、外部取数三个面板也不摆(canCarry() 返回 false)。
  • 属性面板里「必填 / 可编辑」这两档对它是灰的,只有「隐藏 / 只读」有意义——和 group 现在的 表现一致,不用为它新做一套开关。
  • 导出与打印里天然什么都没有:api/export.py:cell_text 与 service/titles.py:_field_text 都是拿 data 里那个键说话,而这一格在 data 里根本没有键,所以那两处一行都不用改。 这比"落一句 (外部页面:合同详情)"更好——那种文本会让人以为导出少了东西, 而"这一格本来就没值"才是事实;更要紧的是从此杜绝了日后有人"顺手把地址也导出"。 留痕那一侧由 backend/scripts/check_embed.py 盯着(日志只落参数键名与指纹,身份证号和 单据号都不落),导出一侧则是结构性不可能,写不出断言可断言的东西。
  • utils/fieldCatalog.spec.ts 会拿前端清单去比后端源码:embed 只要照 §1 与 §8 两边都登记, 它就是绿的;这条断言正是手写签名当年被漏掉之后加的那道防线。

8. 落地清单

对着 form-field-catalog.md §4 那 11 条逐条走,一条都不能省:

# 位置 embed 要做什么
1 types/index.ts FieldType 加 embed 与 embed 那段配置;不进 TABLE_COLUMN_TYPES
2 utils/formLayout.ts FIELD_TYPES 排在 spacer 附近;NON_INPUT_TYPES / NON_FILLABLE_TYPES 加它;LABELLESS_TYPES 不动
3 design/FieldLibrary.vue META.embed = { group: 'Layout', icon: 'globe', hint: 'form.embedDragHint' }(Record<FieldType, …> 会替你数)
4 components/oa/FormFieldControl.vue 不用改:这一格不进录入控件那条路,改的是 FormRenderer.vue——在 group 那一支旁边加 embed 一支,走假框 / 真框两个态;STATIC_BLOCK_TYPES 不收它(那一支不渲染控件)
5 utils/formRuntime.ts ↔ service/formruntime.py RUNTIME_NON_INPUT_TYPES / NON_INPUT_TYPES 各加一处;提交校验不用加(没值就没得判)
6 utils/fieldCapabilities.ts ↔ threshold.py / quota.py 进 LAYOUT_TYPES 那一组
7 utils/routeExpression.ts 不用改,跟着 6 自动消失
8 api/design.py FIELD_TYPES 加 embed、LAYOUT_ONLY_TYPES 加 embed;另加一段配置校验:没选源就是错、源不存在/已停用是错、参数引用了不存在的字段是错、参数名不在源声明的白名单里是错
9 api/export.py / service/titles.py 各落一句人话,不落 URL;标题规则候选里排掉
10 i18n/locales/zh.ts 与 en.ts fieldTypeEmbed + 面板那一组词条 + 悬停说明,中英一份不缺(localeParity.spec.ts 会数)
11 pnpm vitest run 含 fieldCatalog.spec.ts 与新增断言(见下)

后端新增的东西:

文件 装什么
models.py DataSource.PROVIDER_EMBED = "embed"、page_mode / app_code 两列;新表 oa_embed_ticket(哈希、60 秒、一次性、绑人与单据)
service/embed.py 渲染地址(调 binding.render)、发票与验票、探测能否被嵌(复用 fetch.http_request 那一份出口)
api/embeds.py GET /embed/sources、POST /embed/launch、POST /embed/tickets/verify;发地址前重算可见性,挡住了也留一笔,都写进 oa_data_source_log
api/data_sources.py provider=embed 的校验分支(必须 https、必须单个 origin、参数白名单)+「测试连通」走探测
main.py 一个只写 Content-Security-Policy 的响应头中间件,frame-src 白名单来自运行配置
config.toml.example 新增 [embed] 段(总闸、CSP 开关、CSP 附加来源、短码 TTL),与 [hub] / [storage] 同一写法;生产档只列真的可能要改的那两项
permissions.py 不加新权限码:配置用现成的 design:datasource,可见性用环节字段权限

要钉住的测试,按危险程度排,以及现在钉在哪:

# 断言 钉在哪
1 环节把这一格设成隐藏时后端发票接口必须拒绝(不能只在前端不渲染) 判据钉在 check_embed.py「这一格在当前环节露不露」(含联动藏格那一路);通路钉在 check_embed_api.py「要地址时的三条拒绝」——拿一个与这张单无关的人真打一次,403 且留一笔 blocked
2 模板没用到的参数拼不进地址;已有单据时不收前端交回的值;发起页只认 {form.x} check_embed.py「参数白名单来自地址模板」
3 地址渲染编码干净:值里的 & / # / / 拼不出第二个参数位 同上「地址渲染」
4 能不能被嵌只认证据:CSP 赢过 XFO、探不准就说 unknown、'self' 不算允许 同上「能不能被嵌」
5 设计期校验:没选源、源被删、源不是这一类、参数写歪、参数只写了名字没写取值写法、高度出格、回写点了不存在的格子;而源停用不在这里挡 同上「设计期校验」+ utils/embed.spec.ts
6 短码只存哈希、绑人绑源、hub 明说没开、没身份不发地址 同上「免登短码」;用第二次必须失败与密钥不对时不烧码两条真跑通了,在 check_embed_api.py「免登短码换身份」
7 留痕里没有参数值(身份证号、单据号都不落) 同上「留痕不含参数值」
8 frame-src 里 'self' 与 blob: 永远在(附件 PDF 预览别被这道新闸关掉)、源停用之后白名单里没有它 同上「CSP 的 frame-src」
9 导出与打印里出现不了 URL 与票据 结构性不可能(这一格在 data 里没有键,见 §7)
10 这一格留在"版面 / 不产生值"那一族、不能当明细列、但要有标题也要认 key utils/embed.spec.ts + utils/fieldCatalog.spec.ts
11 注册表那条记录存下去之前:还没开放的那一档、被当写回通道、非 https 的地址、缺应用密钥的短码免登;换回别的通道时不清 page_mode / app_code check_embed.py「注册表那条记录保存那一刻」
11a https 那条硬规矩只对本机与内网让路(公网 http 照挡),要全放开得有人显式开 [embed] allow_http check_embed.py「注册表上那条地址」
12 两边各写一遍的那几句措辞不漂 check_embed.py「前后端措辞对齐」
13 回填白名单是失败即关的:清单为空一条都不收;挂了额度 / 阈值 / 版面 / 系统带出的格子收不下;点 nonexistent 的格子要说 同上「回填白名单收不收得下」+ utils/embed.spec.ts + check_embed_api.py「设计期回填白名单」
14 三道校验一条不少;nonce 只压在想动数据那一条上;改一行 nonce 就不认;oa:title 这种没开的消息一律当没说 utils/embedBridge.spec.ts
15a 那五道闸真的挡住了:额度格、环节改不动、环节隐藏、类型收不下,一个值都不进 model;两个嵌入格各说各的;回执里只有字段名没有值 components/oa/FormRenderer.embed.spec.ts
13a 对应表合成规则两边一致(同名 + map、撞名时对应表赢、目标也算点过名);写歪的三条(空行、缺一头、一格两来源)各说一句;走对应表的报错带上对方那个键 check_embed.py「回填白名单收不收得下」+ utils/embed.spec.ts + design/EmbedPanel.spec.ts
15 回填按类型收值:1,200.00 收进 money、是/true/1 收进 switch、日期只认这一格自己的写法(不做尽力解析)、候选按值或唯一名称匹、结构类一律拒收 同上
16 refresh 那一趟只回参数:不发地址、不发短码、库里两张表一条都不涨 check_embed_api.py「参数刷新:只回参数」
17 探测的四种结论摊给界面的形状:denied 走红的 error(不是绿)、unknown 走 note(否则那句话根本显示不出来) check_embed.py「探测结论摊给界面的那份形状」+ check_embed_api.py「能不能被嵌」

跑法三条:

cd backend  && python3 scripts/check_embed.py                              # 不连库,15 段口径
cd backend  && python3 scripts/check_embed_api.py --base http://127.0.0.1:8000/api/v1
                                                                           # 连库连实例,11 段
cd frontend && pnpm vitest run src/utils/embed.spec.ts src/utils/embedBridge.spec.ts \
                       src/components/oa/FormRenderer.embed.spec.ts

check_embed_api.py 不猜任何人的口令:它用本部署的 security.create_access_token 现签会话, 所以默认只肯打本机地址(指向别处要显式加 --allow-remote),并且一定直连——开发机上挂着 Clash 那类系统代理时 urllib 会把 127.0.0.1 也交出去,换来一串看不懂的 502。它只建自己那 几条带时间戳编码的数据源,跑完连同发过的短码与留痕一起删掉;库里凑不出"与这个人无关的单据" 时那一条自己跳过并说明原因,不假装验过。

9. 分期

P0(一个人 2~3 天,先解决"能用"):embed 类型按 §8 打通,注册表加 provider=embed, 只支持 none 模式,加探测,加降级卡片,加 CSP。P0 结束时能覆盖的真实场景:同主域部署的系统 (cookie 本来就在)、内网公开看板与报表、以及一切"点新窗口打开也行、但要在 OA 里有位置"的页面。 这一段没有任何免登风险,可以先上。

P1(免登 + 回写):ticket 短码、验票接口、访客模式的开关与留痕,integration-contract.md 加一节给对接方照抄,postMessage 回写(默认关 + 白名单 + 三道校验)。

P2:hub 模式(等 Hub 那边确认目标应用允许被嵌)、移动端口径、已办页的"只给按钮"策略细化。

落地的切法和这份排期差了一点,差在一处判断上:ticket 看着属于 P1,实际上它是 P0 那句 "同主域之外的系统也能用"的前提,而它抄的 sso_handoff.py 形状是现成的、风险面也就是多一张 60 秒的短码,于是跟 P0 一起做了;回写反倒往后挪——它没有取数那条"提交时再取一次覆盖掉"的退路 (§5),白名单和校验得先钉结实,宁可属性面板上先不摆那一栏。现在是这样:

期 内容 状态
P0 类型打通、注册表 provider=embed、探测、降级卡片、CSP 已落地
P1 ticket 短码 + 验票接口 + 留痕 已落地。访客模式没有:那要在源上显式勾选、还要在留痕里写清"对方日志里看到的是同一个账号",宁缺
P1 postMessage 回写 已落地,默认关:属性面板白名单(收不下的灰显并说明为什么)→ 三道校验 → 五道闸 → 按类型收值 → 界面上说清"写进了哪几格 / 哪几格没收下"(§5.2)
P1 参数变化推送 已落地:oa:params + POST /embed/launch {refresh:true},debounce 800ms、不自动重载、不发短码不留痕(§5.1)
P2 hub 模式 未做,而且三处一起挡着:界面「免登方式」那一栏只给已经能用的两档、保存时 _clean_embed 按 embed.MODE_READY 拒绝、build_url() 抛 HubNotReady 回一句人话。留一个选了必然打不开的选项比不给选更坏
P2 移动端口径 一半:mobile 可配 button / frame,窄屏默认只给一张卡片

10. 不做什么

  • 不做设计器里手填任意 URL。看起来灵活,实际是钓鱼入口,而且和"少开发一遍页面"这个目的无关。
  • 不把外部页面里的值当条件、额度、阈值的依据。红线在 service/fetch.py 开头就画过: 外部系统只能提供值,不能决定流转。iframe 里的东西后端连看都看不见,更不可能例外。
  • 不做双向同步,不去改外页的 DOM(跨域也做不到)。
  • 不做明细表某一列里嵌页面,也不做"一次嵌好几个"的容器组件——要嵌三个页面就摆三格, 格子本来就是这张表单的语言。
  • 不做把外部页面抓成截图或 PDF 存进附件。那是另一件事(见 attachment-preview.md), 而且会顺手引入"谁授权 OA 去抓别人页面"这个说不清的问题。

11. 给对接方的一页清单

抄进 integration-contract.md 给对方系统实现时照做:

  1. 允许被嵌:Content-Security-Policy: frame-ancestors https://oa.example.com (不要用 X-Frame-Options,它表达不了多来源;已经设了的话必须改成允许 OA 来源);
  2. 去掉 frame-busting,不要在检测到 window.top !== window.self 时把自己弹出去;
  3. 登录态 cookie:与 OA 同主域最省事;做不到就 SameSite=None; Secure;
  4. ticket 模式:实现"拿短码换身份"——短码走服务端到服务端,带 OA 与对方约定的应用密钥, 返回 sub / account / display_name / audience;短码只能用一次、60 秒过期、只存哈希;
  5. 别把业务参数当身份用:地址上的 contractNo 只表示"要打开哪一单",能不能看由第 4 步拿到的 那个人在你们系统里的权限决定;
  6. 如果那条链接是你们现生成的(OA 配成 url_mode=api 那一档):接口回一个 JSON,链接放在 约定好的那一栏(data.url 之类,OA 侧填 url_path),可以只回路径(OA 按接口地址补全来源)。 链接的域名要和 OA 登记一遍——没登记过的来源 OA 一律不嵌,哪怕这一页本身允许被嵌; 链接别做成"只能被打开一次",那个人点一下「刷新」就是一张新链接,而 iframe 装载常常带预取;
  7. postMessage 那条通道(可选,不做也不影响打开页面):见下面 §11.1;
  8. 别指望改 OA 界面上的字:那一格叫什么由管理员在注册表里定,OA 不接收来自内嵌页面的标题 之类文案(§5.2 末尾);
  9. 如果你们要在自己那边把事办完之后回写 OA(值回传、"我们这边发起了"、"这一步审完了"): 验票响应的 callback 里会给一把会话令牌和这一趟能做的事,之后调 POST /api/v1/embed/callback。这一条整套设计与配法在 embed-action-design.md,那一节末尾有对方照抄清单。

11.1 postMessage 协议(要做回写或自适应框高才需要)

判断口径的唯一实现在 frontend/src/utils/embedBridge.ts,下面这份是它的照抄版。

OA → 你们(都发向 iframe.contentWindow,targetOrigin 写死成你们自己的 origin,从不用 *)

// iframe 装载完之后一条:nonce 是这一趟现编的,params 是后端按地址模板算好的那几个参数值。
// 后面那三样是"这一趟"的身份与能力:prekey 是预受理号(还没保存的发起页上,那是双方唯一
// 共有的标识,建议当成你们那边草稿表的外键);actions 是这一格开放了哪几件事,
// 你们那几个按钮该不该显示就照它判,别自己猜;context 是这一趟的上下文(单号 / 环节 / 草稿)。
// session.token 只有**这条源没配应用密钥**时才有值,配了的那条从验票响应里拿。
{ type: 'oa:handshake', nonce: '9f…', origin: 'https://oa.example.com',
  params: { contractNo: 'HT-2026-0007' },
  prekey: 'PRE7K2M9XQ4', actions: ['submit', 'refresh'],
  session: { prekey: 'PRE7K2M9XQ4', token: '', scopes: ['prefill', 'start'],
             expiresAt: '2026-10-23 14:20:31', ttl: 7140, pending: [], started: null,
             context: { prekey: 'PRE7K2M9XQ4', job: '', activity: '', draft: '',
                        serial: 'BX-2026-0091', fields: ['contractNo', 'amount'] } },
  context: { /* 同上,方便少解一层 */ } }
// 填单人改了参数引用的那几格时再来一条(可能没有;OA 不会重载你们这个页面)
{ type: 'oa:params', nonce: '9f…', params: { contractNo: 'HT-2026-0008' } }
// 你们发过 oa:result 之后的一句回执:哪几格真写进去了、哪几格为什么没写进去
// 里面的键就是你们发过来的那几个(配了字段对应也一样回你们的名字)
{ type: 'oa:ack', nonce: '9f…', accepted: ['amount'], rejected: [{ key: 'signed', reason: '开关只认 是/否…' }] }

回写一定要有回执:accepted / rejected 里只有字段名和界面上那句一样的话(值是你们 自己交上来的,回出去不增加泄露面,也确实没必要回)。有了它,你们页面里那句"已同步到 OA" 才敢说出口——没有它,OA 这边挂着「金额那格:值不是一个数字」而你们那边显示成功,是联调期 最费时间的一种两边各自困惑。

你们 → OA(window.parent.postMessage(msg, oaOrigin),oaOrigin 用握手消息里给的那个)

消息 必须带 nonce? OA 拿它做什么 不发的后果
{type:'oa:ready'} 否 摘掉那层「正在加载」 等 15 秒自动摘,看不出差别
{type:'oa:submitted'} 否 你们那边刚点了提交:OA 当场问一句「这一趟成单了没有」,问到就立刻把那张作废的发起页换成详情页 靠 OA 两秒那一拍自己问,那一两秒里这一屏看上去还是编辑页
{type:'oa:resize', height:720} 否 照这个数调框高,只认 160–4000 用属性面板配的高度
{type:'oa:result', values:{amount:'1,200.00'}, nonce:'9f…'} 是 按 OA 配的那份对应写进点过名的那几格 回写就是没开
{type:'oa:action', action:'submit', values:{…}, nonce:'9f…'} 是 请 OA 替这个人做一件事:submit 发起 / save 存草稿 / decide 提交本环节 / refresh 重开这一页。只在该格勾了那一项才认 那几颗按钮就是没有
{type:'oa:action', action:'decide', route:'通过', opinion:'…', nonce:'9f…'} 是 同上,只多两样:这一步走哪条出口(可给可不给)与审批意见。只替审批人把出口和意见填好,提交仍由他自己点 出口和意见得他自己选

三条硬规矩:

  1. oa:result 不带 nonce(或带错一个字符)就当没说;nonce 每次装载都是新的一条, 缓存住上一条没用。oa:ready / oa:resize / oa:submitted 不动数据,所以不逼你们带。
  2. 只写这份表单点过名的格子。一个都没勾也没配对应时 OA 一条都不收(失败即关),你们发了 也不报错,只是界面会说这一格没收下——对接时先在 OA 的属性面板里勾上。 你们的键名不用改成 OA 的字段名:对不上号的那种(你们叫 invoice_no、他那单叫「金额」), 让配表单的人在「对方那边不叫这个名字时」那张表里一行行对上就行,对不上的键 OA 直接不理。
  3. oa:action 也一样要 nonce,而且动作必须在那份 actions 清单里——不在清单里的那一句 OA 当没说。submit / save / decide 是真的会以这个人的名义动一张单,所以 OA 默认会 弹一句确认(念的是"要带上哪几格",不是「确定吗?」),配表的人能关掉,但默认开着;
  4. 值请给一行文本。1,200.00、是 / true / 1、2026-01-31、A、B 这一类 OA 会按目标 格子自己的类型收下来;日期请给 YYYY-MM-DD(/ 会当成同一种写法),别给 1/2/2026 这种 要人猜的;下拉给要存的值,给中文名也行但必须能唯一匹到一项;明细表、附件、选人、部门、 级联这些收不了,别发。收不下的那一句 OA 会显示在那一格下面(例如 「金额」值不是一个数字), 对接期盯这一行比盯日志快。

最小一段照抄就能用:

let oaOrigin = null, nonce = null, lastHeight = 0, actions = [], prekey = '';

// 报自己有多高:OA 照这个数把框撑到一样高,于是框里不再出自己那条滚动条。
// 只想让框配多高就多大?把 reportHeight 那几行删掉就行,OA 收不到就当没这回事。
function reportHeight() {
  if (!oaOrigin) return;
  const h = Math.ceil(Math.max(
    document.documentElement.scrollHeight,
    document.body.scrollHeight
  ));
  if (h === lastHeight) return;        // 一样高就别再发,那边会真的动一次高度
  lastHeight = h;
  window.parent.postMessage({ type: 'oa:resize', height: h }, oaOrigin);  // 只认 160–4000
}

function watchHeight() {
  reportHeight();
  // 内容一改就重报:折叠段展开、表格多一行、图片加载完,都会改高度
  if (window.ResizeObserver) {
    [document.documentElement, document.body].forEach((el) => new ResizeObserver(reportHeight).observe(el));
  }
  window.addEventListener('load', reportHeight);
}

window.addEventListener('message', (event) => {
  const msg = event.data || {};
  if (msg.type !== 'oa:handshake') return;
  oaOrigin = event.origin;          // 只回这个 origin,别用 '*'
  nonce = msg.nonce;
  actions = msg.actions || [];       // 这一格开放了哪几件事,按钮该不该显示照它判
  prekey = msg.prekey || '';         // 预受理号:存进你们自己的草稿表,回写 OA 时当幂等键用
  render(msg.params);                // { contractNo: 'HT-2026-0007' }
  watchHeight();                     // 顺手报一条 oa:resize,此后内容一变就再报
});

function submitBack(values) {
  // 键用你们自己的字段名即可(invoice_no、ht_amount…),OA 那边按配好的对应落到它的格子上
  window.parent.postMessage({ type: 'oa:result', values, nonce }, oaOrigin);
}

// 「我们这边录完了,把这单发起来吧」——OA 会不会替这个人发起,看握手给的 actions 里有没有
// submit;没有就别摆这颗按钮,摆下去 OA 也只是当没说
function askOaStart(values) {
  if (!actions.includes('submit')) return;
  window.parent.postMessage({ type: 'oa:action', action: 'submit', values, nonce }, oaOrigin);
}

reportHeight 量的是文档的高度,所以那张页面得让内容自然把文档撑高:如果它本身是 "铺满视口 + 里面自己滚"那种 html, body { height: 100vh } 布局,量出来永远等于 OA 此刻给的 那点高度(480 报上去还是 480),框一辈子长不起来。这种页面只能靠「展开」整屏再在你们自己 页面里滚,或者用「新窗口打开」——跨域量不到里面的高度,OA 这边没有别的信息可用。

三条出路,按省事程度排:① 照这段报 oa:resize(最省事,OA 会一字照给,框里不再出自己 的滚动条);② 与 OA 同一个 origin(那就不用你们动,OA 自己进去量);③ 两样都不做, 那就只能请 OA 管理员把那一格的高度配到你们页面的实际高度(上界 4000),代价是窗口一变又不 合适。这一格现在挂在谁手上由配表的人定,但①与③的差别是"自动"与"每次都要有人管", 接进来时值不值得省那十来行,一目了然。

12. 落地情况

代码住在这些地方,按"谁负责说哪句话"分:

层 文件 那一层负责的那句话
注册表 models.py(PROVIDER_EMBED / page_mode / app_code / url_mode / url_path / view_url_path / view_url / url_links / url_meta / url_origins / EmbedTicket)、api/data_sources.py:_clean_embed 这个页面长在哪、地址是自己拼还是问接口要、查看页那一条在哪一栏 / 哪条模板、对方多回的那几条链接登记了哪几条(url_links:键名 + 名字 + 位置或模板)、同一次响应里还要顺手带回哪几个值(url_meta:名字 → 位置)、接受哪几个参数、用什么免登、谁能看
内核 service/embed.py 地址怎么拼、接口那条链接怎么取、取回来认不认(一次调用把这条源登记的那几条一起取回,外加 link_meta_of 点名的那几个只读值——那个接口每调一次建一张页,为第三条再打一次就多一张)、「有哪几条」这一份清单只有一处真相(link_defs / link_index:内置那两条 + 登记表里那些,判据、报错、来源白名单、界面选项全从这一份读)、这一次该递哪一条(link_kind_for:点名要哪条就是哪条,auto 才看发起人还有没有事做)、该不该发这次取链接的调用(open_when_of / unfinished_args)、能不能被嵌、短码怎么发怎么验、CSP 白名单、留痕
接口 api/embeds.py 给不给这个人这条地址——发地址之前重算一遍可见性、先查这一趟存过什么再决定打不打那个接口(顺序反了那张页已经多出来了)、那几格还空着就把这次调用挡下来,挡住了都留一笔
闸门 main.py:SecurityHeadersMiddleware、config.py 的 [embed] frame-src 白名单、frame-ancestors 'none'
表单侧 service/formruntime.py、api/design.py、utils/formRuntime.ts(含 embedPendingParams 那道闸)、utils/formLayout.ts、utils/fieldCapabilities.ts 这一格不产生值、不能勾必填、挂不上阈值额度、进不了明细列
界面 components/oa/EmbedFrame.vue、design/EmbedPanel.vue、views/oa/design/DataSourceView.vue 假框 / 卡片 / 真框三个态、「展开」那一层、那几格没填上时锁住这一页;属性面板没有填网址那一栏
通道 utils/embedBridge.ts、components/oa/FormRenderer.vue:applyWriteback、EmbedFrame.ackWriteback 消息怎么发怎么收(三道校验 + 按类型收值)、"这一格本来收不收、这个人改不改得动"那五道闸,以及处理完之后回给对端的那句 oa:ack
这一趟 / 这一页 service/embed_session.py(held_bundle 两层:先认这个人那一趟,落空再认这张单第一次那一页;stamp_links / _stamp_page 两处都钉)、models.py(EmbedSession 是凭据,含 url_edit / url_view 与装其余那几条的 url_extra / link_meta;EmbedPage 是这张单那一页的账,按「源 + 格子 + 单」唯一,活到单删)、api/embeds.py:callback、api/runtime.py:prekeys 没保存时靠什么对上话(prekey 是话题、令牌是凭据)、这一趟开放哪几档(scopes_for 一处算完)、prefill/start/decide 三档各落到哪儿、发起去重为什么两头都要记账。详见 embed-action-design.md
摊得开的那几栏 service/fetch.py:sample_paths(服务端那份摊法:探测回的 paths 与取数的「测试连通」同一份)、utils/jsonPaths.ts + components/oa/design/PathPicker.vue(浏览器里摊贴进来的样例,吐出来的写法照 fetch.pick_path 认的那一种)、service/embed.py:remote_writeback_keys 配置时唯一能替对方答话的两件事:这一份响应里有哪几栏可挑(那几栏的下拉候选),以及对方上次真回传过哪几个键名(「对方字段名」那一栏的候选,只存名字不存值)
界面(动作那一档) design/EmbedPanel.vue(actions 那几项 + decisions 那张表)、EmbedFrame.vue、views/oa/StartFormView.vue 这一格能让 OA 做哪几件事、对方那套状态词怎么翻、攒在服务端的值(staged)与已经发起的那张单(started)怎么落回界面

跑起来验,这么几条:

cd backend  && python3 scripts/check_embed.py             # 不连库,22 段口径
cd backend  && python3 scripts/check_embed_api.py         # 连库连实例,13 段(默认打本机 8000)
cd backend  && PYTHONPATH=. python3 scripts/check_embed_reopen.py
                                                          # 真建单真提交:提交后再点开这一格,认回的还是对面那一页,10 项
cd backend  && PYTHONPATH=. python3 scripts/check_embed_shared_page.py
                                                          # 真流程 + 三个真人:后面的节点、后面的人看的还是第一次那一页,17 项
cd backend  && PYTHONPATH=. python3 scripts/check_embed_decide.py
                                                          # 真流程真待办:那句「审完了」落到哪条出口,20 项
cd backend  && PYTHONPATH=. python3 scripts/check_embed_readonly_auto.py
                                                          # 只读屏「只沿用已有那一页」:没货不打建页接口,16 项
cd frontend && pnpm vitest run src/utils/embed.spec.ts src/utils/embedBridge.spec.ts \
                       src/utils/fieldCatalog.spec.ts
cd backend  && python3 scripts/check_schema_snapshot.py   # oa_embed_ticket / oa_embed_session / oa_embed_page 都在结构快照里

手工过一遍最短的路:「外部数据源」新建一条取数通道选「嵌入这个页面」→ 填地址模板 (?no={arg.contractNo})→ 点「测试连通」看探测结论 → 表单设计里拖一格「外部页面」选它、 把 contractNo 指向单上那一格 → 填单页看它是框还是卡片。

还欠的事,都不是"顺手加一下"的那种:

  1. hub 那一档:要等 Hub 那边确认目标应用允许被嵌(§3.1),不是 OA 单方面能开的。
  2. "某个环节把这一格设成隐藏"那一路只钉到判据层:判据(_field_perm)在 check_embed.py 里钉死了,通路(真发一次 POST /embed/launch 收 403)在 check_embed_api.py 里是用"这个人与这张单没关系"那一路验的——真库里凑不出一个环节权限 正好藏了 embed 格的现成单据,造一单又要往共享开发库里留下撤不掉的流转痕迹,不值。 代码两条都挡(api/embeds.py:launch),别以为没写那条断言就是没挡。
  3. 回填不留独立笔迹:提交那一刻后端分不出"人敲的"与"iframe 写的"(§5.2 末),所以要审计 "这一格是谁写的"目前只能靠 OA 自己的单据修改记录。真要做,得让回填走一条独立接口、 单独留痕——那是新功能,不是这条通道的收尾。

最后记一个真踩过的坑,免得下一个人再踩:config.py 里 _coerce() 是按默认值的类型洗配置值的, 默认值是清单那一项时它把值 str() 之后再按逗号切——于是"根本没配置"的那个空清单 () 被洗成了 ('()',),frame-src 里就此多出一个非法来源。而 CSP 里一个非法来源不是"那一个来源失效" 这么客气,严格解析下整条头都不作数,表现是"附件预览和嵌页面一起坏了,看不出头绪"。 check_embed.py「CSP 的 frame-src」那一段现在钉着这条。