83 KiB
表单里嵌别的系统的页面: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. 先定一件事:这一格是"版面"还是"值"
三个候选,先摆出来:
- 纯版面:跟
group/description一样,只负责把一块地方让给别人的页面,不产生值。 - 存一份地址快照:像
url字段那样把最终地址存进data,打印和导出有个凭据。 - 存外部回填的结果: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},照样只配"哪个参数从哪一格取"。
换掉的只是地址从哪来,五条规矩一条都没松:
- 调用还是在这个后端发生(
service/embed.py:resolve_link),浏览器连那个接口的地址都看不见; - 参数值还是后端算的那一份(§2.2 那句"已有单据不收前端交回来的值"照旧);
- 参数白名单变成三份模板的并集:接口地址 + 请求头 + 请求体里出现过的
{arg.x}(declared_args)。少算一份,就会把明明要用的参数报成"这个页面用不上";那句提示也跟着 换成"接口地址、请求头、请求体里都没写",同时数据源页的「入参」那一页在模板那一档会直接说 "这一档不发请求,这几行送不出去"——两头都指着同一件事,配的人才不会去地址栏里找一个 根本不写在那儿的{arg.}; - 熔断、限流、超时、重试、留痕全复用取数那一份(
fetch.outbound_guard/outbound_mark), 留痕多一类kind=link。于是"他当时到底看没看到那个页面"多了一段可对答的中间过程: 是接口没答话,是答了没给链接,还是给了一个不认识的域名; - 取回来的链接要过两道判断:
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} 推给已经开着的那个页面。三个决定值得留字:
refresh那一趟不发地址、不发短码、也不留痕(api/embeds.py:launch里那条分支)。 留痕记的是"他打开了那个页面",把每次刷新都记成一次打开,台账就没法看了;可见性照旧重算, 所以这一条不多给任何东西。- 绝不自动重载 iframe。那个人可能正在对方页面里填到一半,重载等于把他写的东西清干净——
"我这边的值变了"不该由他来付代价。对端没实现
oa:params时只标一句「这个页面还是按旧值 打开的」(form.embedStale),要不要点刷新由他自己决定。 - 能推的只有后端算过的那一份(发票时给的
params,或这条refresh重算的那一份), 所以"外部页面能看见哪些值"永远不超过地址模板声明过的那几个参数名。这条不变量是出去那条 路敢开的全部前提。 - 同一句
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 只管消息本身那三道校验,一条都不能少:
event.origin等于发票那条地址的 origin——别的站点往顶层窗口postMessage是免费的;event.source === iframe.contentWindow——少了这道,iframe 里 302 到别的站点之后,那个站点 同样能顶着它自己的 origin 冒充"我们打开的那个 frame";nonce一个字符都不差,由 OA 前端每次装载现编(crypto.getRandomValues,不用Math.random),只递给这一个 frame。
nonce 只压在想动数据的那一条上:oa:ready / oa:resize 只改那层"加载中"和框高,动不了
数据,就不逼对方带 nonce——已经照 §11 实现了 resize 的页面不用改一行就能继续用。这是权衡不是
疏忽。
再往后是 FormRenderer.vue:applyWriteback,它判的是另一件事:这一格本来收不收、这个人本来
改不改得动。这一层的组件看得见环节权限与联动锁,EmbedFrame 看不见,所以判断分两处不是随意:
- 这一格得真的在这张表单上(明细列不在这一层,回填只写主表);
- 这一格收得下:版面与系统带出那两类不存值、挂了额度或阈值的一律不收
(
service/embed.py:writeback_refusal与utils/formRuntime.ts:embedWritebackRefusal是 同一份措辞,由check_embed.py「前后端措辞对齐」对账)——外部系统只能提供值,不能决定 流转(service/fetch.py开头第 3 条); - 这一格在当前环节不是隐藏的(藏起来的格子不该被谁隔着 iframe 悄悄写一笔);
- 这一格本来就改得动:只读页、环节给了只读、联动锁了、系统带出与公式,全都收不了;
- 值得先按这一格的类型收下来(
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,画布上是一张假框。三条理由,每一条都足以单独否决:
- 画布一栏只有整页三分之一宽,别人的页面在这个宽度里根本看不出长什么样;
- iframe 会吃掉落在它上面的鼠标事件,画布的拖拽排序、选中、右键菜单会整片失灵;
- 每次打开设计器就打一次生产系统、发一批免登短码,纯粹给上游制造噪音和安全隐患。
假框里显示:源名与它属于哪个系统、要带哪几个参数、上一次探测的结论、一个「预览」按钮
(点了才走一次真发票,在弹窗里加载,看完就关)。属性面板里加一段「外部页面」:挑源(按 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 给对方系统实现时照做:
- 允许被嵌:
Content-Security-Policy: frame-ancestors https://oa.example.com(不要用X-Frame-Options,它表达不了多来源;已经设了的话必须改成允许 OA 来源); - 去掉 frame-busting,不要在检测到
window.top !== window.self时把自己弹出去; - 登录态 cookie:与 OA 同主域最省事;做不到就
SameSite=None; Secure; ticket模式:实现"拿短码换身份"——短码走服务端到服务端,带 OA 与对方约定的应用密钥, 返回sub/account/display_name/audience;短码只能用一次、60 秒过期、只存哈希;- 别把业务参数当身份用:地址上的
contractNo只表示"要打开哪一单",能不能看由第 4 步拿到的 那个人在你们系统里的权限决定; - 如果那条链接是你们现生成的(OA 配成
url_mode=api那一档):接口回一个 JSON,链接放在 约定好的那一栏(data.url之类,OA 侧填url_path),可以只回路径(OA 按接口地址补全来源)。 链接的域名要和 OA 登记一遍——没登记过的来源 OA 一律不嵌,哪怕这一页本身允许被嵌; 链接别做成"只能被打开一次",那个人点一下「刷新」就是一张新链接,而 iframe 装载常常带预取; postMessage那条通道(可选,不做也不影响打开页面):见下面 §11.1;- 别指望改 OA 界面上的字:那一格叫什么由管理员在注册表里定,OA 不接收来自内嵌页面的标题 之类文案(§5.2 末尾);
- 如果你们要在自己那边把事办完之后回写 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…'} |
是 | 同上,只多两样:这一步走哪条出口(可给可不给)与审批意见。只替审批人把出口和意见填好,提交仍由他自己点 | 出口和意见得他自己选 |
三条硬规矩:
oa:result不带nonce(或带错一个字符)就当没说;nonce每次装载都是新的一条, 缓存住上一条没用。oa:ready/oa:resize/oa:submitted不动数据,所以不逼你们带。- 只写这份表单点过名的格子。一个都没勾也没配对应时 OA 一条都不收(失败即关),你们发了
也不报错,只是界面会说这一格没收下——对接时先在 OA 的属性面板里勾上。
你们的键名不用改成 OA 的字段名:对不上号的那种(你们叫
invoice_no、他那单叫「金额」), 让配表单的人在「对方那边不叫这个名字时」那张表里一行行对上就行,对不上的键 OA 直接不理。 oa:action也一样要 nonce,而且动作必须在那份actions清单里——不在清单里的那一句 OA 当没说。submit/save/decide是真的会以这个人的名义动一张单,所以 OA 默认会 弹一句确认(念的是"要带上哪几格",不是「确定吗?」),配表的人能关掉,但默认开着;- 值请给一行文本。
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 指向单上那一格 → 填单页看它是框还是卡片。
还欠的事,都不是"顺手加一下"的那种:
hub那一档:要等 Hub 那边确认目标应用允许被嵌(§3.1),不是 OA 单方面能开的。- "某个环节把这一格设成隐藏"那一路只钉到判据层:判据(
_field_perm)在check_embed.py里钉死了,通路(真发一次POST /embed/launch收 403)在check_embed_api.py里是用"这个人与这张单没关系"那一路验的——真库里凑不出一个环节权限 正好藏了 embed 格的现成单据,造一单又要往共享开发库里留下撤不掉的流转痕迹,不值。 代码两条都挡(api/embeds.py:launch),别以为没写那条断言就是没挡。 - 回填不留独立笔迹:提交那一刻后端分不出"人敲的"与"iframe 写的"(§5.2 末),所以要审计 "这一格是谁写的"目前只能靠 OA 自己的单据修改记录。真要做,得让回填走一条独立接口、 单独留痕——那是新功能,不是这条通道的收尾。
最后记一个真踩过的坑,免得下一个人再踩:config.py 里 _coerce() 是按默认值的类型洗配置值的,
默认值是清单那一项时它把值 str() 之后再按逗号切——于是"根本没配置"的那个空清单 ()
被洗成了 ('()',),frame-src 里就此多出一个非法来源。而 CSP 里一个非法来源不是"那一个来源失效"
这么客气,严格解析下整条头都不作数,表现是"附件预览和嵌页面一起坏了,看不出头绪"。
check_embed.py「CSP 的 frame-src」那一段现在钉着这条。