unis-oa/docs/embed-configuration-guide.md

90 KiB
Raw Permalink Blame History

嵌入第三方页面:配置说明书

这份是照着做的那一份:谁、在哪个界面、点哪一栏、填什么、对方系统要改什么、配完怎么验。 设计为什么这么定(判据、失效长什么样)在 embed-action-design.md 与 embed-page-field-design.md,这里不重复论证,只给操作。

三个角色各自只需读完自己那几节:

角色 读哪几节 手上要有什么
系统管理员 §1 §3 §6 对方系统的页面地址、一个双方约定的密钥串
表单设计者 §2 §5 §7 已登记好的那条嵌入源、这张单的字段清单
对方系统对接人 §4 §5 OA 的对外地址、那条源的应用密钥

最常问的三句话在哪一节,直接跳:

想问的 在哪 一句话答
流程创建没保存就返回,怎么让 OA 去打对方那个删除接口 §5.0 §1.1 §4.7 在「外部数据源」那条嵌入源上把「这一页被放弃时,通知对方」挑成那条删除接口所在的写回通道,一次配完,表单不用配
存了草稿、又在草稿箱删草稿,怎么让 OA 通知对方也删 §5.0 §1.1 §4.7 同一个配置点,不用多配:草稿真删的那一刻,OA 自己把那一句发出去,发的号是草稿上那个
「我的待办」里删掉自己创建、还没发起的那张单,对面那份怎么一起删 §5.0 §1.1 §4.7 同一个配置点,不用多配:删单那一刻发的是同一句、同一套参数,号取这张单的单号
嵌进来的那一页操作完了,怎么触发 OA 发起 §5.2 §4.3 那一格勾 submit,对方发 oa:action,OA 弹确认、人点确认,走原来那条发起
对方审完了,怎么告诉 OA 这一步通过了 §5.3 §4.5 那一格勾 decide + 配好他们那套状态词,对方服务端调 POST /embed/callback,OA 以那个人身份把待办办掉
对方一次回好几条链接(编辑页 / 查看页 / 打印页……),给谁、要哪一条、那一栏还没值时怎么办、能不能别每次新建 §1.1 §2.1.2 源上把多出来的那几条登记进「还有哪几条链接」,顺手要带回的单号写进「顺手带回的那几个值」;那一格「给哪一条地址」挑一条,默认「按人自动选」。一次调用全部取回、存在这一趟的会话上,同一趟不再问第二次

0. 先认清「四处配置 + 一个号」

# 配在哪儿 谁配 管什么 不配会怎样
① 「外部数据源」页(侧栏设计分组,/design/data-sources)新建一条 provider=embed 管理员 这个页面住在哪、怎么带登录态进去、地址自己拼还是问接口要、谁能看、应用密钥 表单上那一格连页面都出不来
② 表单设计器 → 选中 type=embed 那一格 表单设计者 带哪几个参数、回写哪几格、这一页能让 OA 做哪几件事、对方状态词怎么翻 只能看,不能往表单放值,也不能动单
③ 流程设计 → 环节的字段权限 流程设计者 这一环这个人能不能改某一格 ②里勾了的回写格子在这一环改不动,回写会被挡
④ 部署档 [embed] 运维 总闸、CSP、短码与会话秒数 总闸关了:一条短码都不发
号 预受理号 prekey(PRE + 8 位) 谁都不用配,OA 自己发 双方唯一共有的"哪一趟打开",对方拿它当草稿表外键、当发起幂等键 ——

「人没保存就返回,得通知对方把草稿删掉」那一档(§2.4)只配在①那条源上:一次选择 (不发 / 挑一条写回通道 / 直接填地址),②那一格默认什么都不用动。配那条源的人就是主张 "这家系统的草稿该由我们打招呼删"的人,再要求每张表单来勾一次只会漏勾。

还有一处只在"第三方从自己服务器发起"那条路上才需要:「开放平台」页里给那个应用 配 work:write 范围(见 §4.6)。走浏览器按钮发起的用不到它。

三条贯穿全文的口径,配之前先记住:

  • 能力由后端算。这一趟能做什么写在验票响应的 callback.kind 里,界面按它决定按钮 存不存在。前端和第三方都只是被告知,谁自己判一遍谁就会和后端漂成两套。
  • 前端通道不替人按确认键。oa:action 只能带来"要办哪件事 + 几个值",做不做由屏幕前 那个人点确认;真办下去走的是引擎原来那条路,必填、字段权限、额度、闸门一条不少。
  • 失败即关。回写白名单没开 = 一条都不收;动作整档没开 = 一个动作都不给; 没配应用密钥 = 拿不到 start / decide 这两档。

1. 管理员:登记一条「可嵌入的页面」

页面:侧栏「外部数据源」(/design/data-sources)→ 新建。取数通道选「嵌入这个页面(外部系统)」, 表单会跟着换成嵌入那一套栏位。这一条源登记好之前,表单设计器里那一格是空的, 面板上会直接写「还没有登记过可嵌入的页面」。

1.1 一栏一栏填什么

界面上的栏位 存的是 怎么填 填错/漏填的现场
编码 code 小写字母数字下划线,例如 erp_contract。这就是第三方报文里的 code,定了别再改 第三方调验票时报「免登短码无效或已过期」
名称 name 给人看的,表单面板与留痕都念它 ——
取数通道 provider=embed 选「嵌入这个页面(外部系统)」 选错通道,那一格根本选不到这条源
方向 direction 保持「取数」。这一类不能当写回通道 保存直接被挡
页面地址 url 地址模板,要带进去的值写成 {arg.参数名},如 https://erp/page/contract?no={arg.no} 模板里没写过的参数名,表单上配了也不会拼进地址
免登方式 page_mode 推荐「本系统发一次性短码」(ticket)。公开页或同主域同会话可选「不需要登录态」。「走统一门户」还没开放,保存时直接挡 选 none 时下面 start / decide 两档一律拿不到
对方应用编码 app_code 短码的收件人(audience),填对方系统自己的编码 不填不影响联调,但 A 系统就能拿自己和 OA 的密钥去换 B 系统的用户
与对方约定的应用密钥 auth_secret 和对方商量好的一串(建议 32 位以上随机串)。只进不出:保存后界面只显示「已设置」,忘了只能重发一把 不填:能嵌、能回填值,但发起与提交本环节这两档永远不给
页面地址从哪来 url_mode 多数选「照地址模板拼」。对方每次现生成一条临时链接(同样的参数下次就变了)才选「先调接口取链接」 选错表现为:嵌进去的永远是同一条链接,或每次打开都 404
取链接的接口地址 / 链接在响应里的位置 / 允许的来源 url / url_path / url_origins 只在接口取链接那一档出现。url_path 写点路径(data.url、data.0.link);url_origins 一行一个 https://主机,留空等于只认接口自己那台主机 来源不在清单里 → 取回的链接一律不嵌;这几行同时是 CSP frame-src 白名单,漏了浏览器自己把框拦了
查看页那条地址(可选) view_url_path / view_url 对方一次回两条(编辑页 + 查看页)时才填:「先调接口取链接」那一档填查看页链接在响应里的位置(如 data.viewUrl),「照地址模板拼」那一档填查看页地址模板。填了它,两条从同一次调用里一起取回,绝不会为第二条多打一次接口——多打一次对面就多一张页。留空 = 这条源只有一条地址,谁点开都拿它。那一栏回空串是正常答话:审阅页在单据进审阅之前就是没有,后端当"对方这一趟没有这一页"走退路(递编辑页那句 linkAbsent),不是失败 那一栏写歪 → 要查看页的人当场看到「取不到查看页那条链接」,并念出这份响应里像链接的位置;模板档那第二条地址的主机会自动进 CSP 白名单,不用再去「允许的来源」里抄一遍
还有哪几条链接(可选) url_links 对方一次回好几条地址时才用得上。编辑页与查看页仍归上面那两栏管,这张表登记它们之外的那几条(打印页、发票夹那种)。一行三样:键名(小写字母开头、只接小写字母数字下划线,如 print——表单那一格「给哪一条地址」点的就是它)、叫什么(给人看的名字,如「打印页」,那一框下面的灰字与面板上的下拉都念它)、它在响应里的位置(接口档,data.printUrl)或它的地址模板(模板档,参数位照写 {arg.x})。最多 8 条;edit / view 这两个键名不许写在这儿,一张表里也不能重名 撞内置键名 / 形状不对 / 重名 / 那一行没写位置 → 保存直接被挡;表单那一格点了这张表里没有的键名 → 打开时退回编辑页那一条,面板上那句说明变琥珀色
顺手带回的那几个值(可选) url_meta 只在「先调接口取链接」那一档出现:名字 → 它在响应里的位置(对方单号 → data.flow_number)。同一次调用里除了地址还有几个核对用的值(对方单号、经手人、让不让审),过去整份丢掉,现在点名的那几个摆在那一框下面当一行灰字看。只读,不进单据数据、不占回填额度、不进留痕里的参数值;最多 8 个,只收标量(位置写歪会回出一个对象或数组,那种干脆不出现,不猜) 只写名字没写位置 → 保存被挡;那个位置在这份响应里没有 → 那一行灰字少一项,页面照开;模板那一档压根不发请求,所以那一档不出现这一栏
这一页被放弃时,通知对方 abandon_source 或 abandon_url 收成一次选择:不发(默认) / 走一条写回通道 / 直接填地址。对方那个"按 OA 单号删草稿"的接口常常本来就登记过一条写回通道,挑它最省事——地址、方法、鉴权、什么算发成功都在那边,这里不抄第二份;没有通道就填地址,多数只写路径(/api/contract/oa/by-flow-number,挂在上面那条页面地址那台主机上),要发给别的系统才写完整地址 表单那一格明着说要发而这里选了「不发」:保存被挡,面板当场点名
(高级)那一句用什么方法 / 对方按哪个字段收 OA 的单号 abandon_method / abandon_field 藏在「改方法或那个单号字段名」那一行,多数对接不用动:走通道就照那条通道的方法,字段名默认 oa_flow_number。要改照对方接口文档抄;可换 POST / PUT / PATCH,没有 GET 选了那边没开的动词 → 405;字段名不对 → 那边回一句参数缺失,OA 记一条失败留痕
(高级)那个值取哪儿 / 用哪个号去对面删 abandon_expr 同一行里,方法、字段名下面那格。留空 = 这一趟预留的正式单号(没有正式号就退回预受理号)。要按自己的流程编号去对面删,就把那一格的取值写法填进来:{form.流程编号}、{auto:serial}、{arg.x},或直接写死一个值。它在打开这一刻算死记进会话,放弃那一刻照它发(发起页放弃了就没单据可回读表单,所以必须在这一刻算)。地址里写 {value} 就把这个值也填进路径或查询串——按号删那类接口常把单号放地址里而不是请求体里 取值写歪算成空 → 退回预留单号,对面要么删了别人的草稿要么没删到;想确认发的是哪个号,看这条源「留痕」里 kind=abandon 那一句
(高级)多键请求体 abandonBody 同一处「高级」里、那个值格下面那张小表:键 = 对方系统里那个字段名(照对方接口文档抄),值 = 取值写法({form.x} 或直接写死),打开那一刻逐个算死。填了就整份发,盖过上面那一对单键;不填就是那一个键。对方的删除接口要按好几个字段认那张草稿(单号 + 项目号那种)时,这是唯一正路。地址里写 {键名} 就把那个键的值也填进路径或查询串 键名抄错一个字母 → 对面当参数缺失不删,OA 记一条失败留痕;某格的取值写歪算成空 → 那一个键不发,其余键照发

选完下面那行灰字会把当下这一句会发成什么样念出来(方法 + 地址 + 那个字段名 + 值取哪儿), 不用等有人放弃一张单再去翻留痕。这一份存在那条源上:接口回给表单面板的只有 abandonSet / abandonMethod / abandonField / abandonExpr / abandonBody 几个值,那条地址本身不进浏览器。

「这个页面要哪几个参数」那一块是从地址模板(或接口地址 + 入参那两页)自动读出来的, 不是手填的:它就是这一页接受的参数名白名单,表单上那一格只能往这几个名字里填值。

1.1.1 那条「写回通道」本身怎么建("调用什么"就写在这条记录上)

「走一条写回通道」这一档只是指一条记录,真正"调用什么"——往哪个地址、用什么方法、 什么算发成功——全写在那条记录上。它跟这条嵌入源一样是「外部数据源」页的一条记录,新建时就照下表填:

界面上的栏位 这条要填什么 为什么
数据源编码 / 名称 / 所属系统 reimb_api / 按 OA 单号删草稿 / reimb 名字要一眼看出它是"删草稿",别起成 reimb_api2 那种以后没人敢动的名字
取数通道 调外部接口 「嵌入这个页面」那条不能当通知出口,保存直接被挡
方向 往外写 选「只取数」的记录收不到这一句,那一栏的下拉里也不会出现它
方法 DELETE 照对方接口文档;这条接口是 DELETE
接口地址 https://reimb.oa.unissense.tech/api/reimbursements/oa/by-flow-number 这就是"调用什么"里的那个"什么"
入参(可选) 不用填 这一句的报文由 OA 拼:就一个键,值是这一趟预留的单号,不吃这条记录上的入参表
「写回判定」页签:成功判定字段 / 值 code / 0 那边业务失败也回 HTTP 200,只看状态码会把失败记成成功
上游错误信息位置 message 发不出去时留痕里念得出人话,而不是一句「对方回 200」
鉴权 那边不校验就选 none;要校验按那边要求配 配了鉴权方式就照它发;什么都没配时 OA 拿双方那把应用密钥当 X-Oa-Integration-Key 发出去,不会裸发
超时秒数 10 这一句是后台发的,慢一点没关系,别设 3 秒把自己判成失败

建完回那条嵌入源,下拉里就能挑到它。嫌两条记录麻烦就选「直接填地址」:把上面那个地址(或 只写路径 /api/reimbursements/oa/by-flow-number)填在嵌入源自己身上,方法在「改方法或那个单号 字段名」里选,成功判定退回按 HTTP 状态码认(404 一律按"那边没有这张单"算发成功)。 同一套接口既用于写回又用于通知时挑通道那条路更稳:地址只有一个主人,抄两份迟早漂开。

1.1.2 不知道对方把东西放在响应哪一栏:让它自己摊出来

data.printUrl 这一串难填,是因为那棵树长在对方那里,背不下来。这一页上有两条路能把它摊出来, 摊出来之后那几栏(url_path、view_url_path、「还有哪几条链接」的第三列、「顺手带回的那几个值」 那一列)就不再是输入框,而是点开能挑的下拉,每一项后面还跟着那一栏此刻装着的值—— 认位置靠的是那句值,不是猜键名:

手上有什么 怎么摊 说清楚
一个已经能调通的接口 点「样例响应」那一栏右上角的**「看有哪几栏能挑」** 它照现在这份配置真去取一次响应(入参用「入参」那两页声明的名字现凑),只为看清栏位。不保存、不改你填过的任何一格
只有对方文档里那段返回 JSON(接口还没开发完) 把那段 JSON 贴进**「样例响应」** 一贴上下拉就长出来。代价是这一段样例会顶掉真调用(界面会一直红字提醒),上线前记得清空

两份来源合成一份(真取回来的那份排在前面),按位置去重。清单只到标量那一层、 深度与条数都封顶,而且不是白名单:真实响应里多出来的那一栏照旧敲得进去, 最终判它的是后端 service/fetch.py:pick_path,不是这份清单。摊不出东西时那几栏退回输入框—— 摆一只空下拉只会让人以为这块坏了。

摊这份东西的代码只有一份口径:服务端 service/fetch.py:sample_paths(「测试连通」回的那份 paths),浏览器 frontend/src/utils/jsonPaths.ts(贴进来的那段样例),两边吐出来的写法 都是 pick_path 认的那一种(点分段、数组用下标 data.0.link)。

1.2 「测试连通」到底在测什么

点它探的是能不能被嵌:服务端去访问一次那条地址,读对方回的 X-Frame-Options 与 CSP frame-ancestors,顺便看有没有被 302 到登录页,结论写回这条源(可以嵌入 / 对方拒绝被嵌入 / 说不准,以实测为准 / 地址不通)。接口取链接那一档会真调一次那个接口, 取不到链接时它会把响应里看着像链接的那几个位置念给你听——url_path 不知道填什么就靠它。 而现在它回的不止一句话:那次真拿回来的响应里摊得开的每一栏都跟着回来(接口字段 paths, 带每一栏此刻的值),配置页上那几栏「在响应里的哪一栏」因此变成能挑的下拉,见 §1.1.2。

探测结论只是给界面参考:真拒绝渲染的是浏览器,页面自己往上跳那一种探不出来。 所以"说不准"的那些,表单上会退成一张「新窗口打开」的卡片而不是留个白框,这不是配坏了。

1.3 交付给对方的一样东西

登记完,把这三样发给对方对接人(口头、邮件都行,prekey 本来就是要念的):

  1. OA 的对外地址(例如 https://oa.example.com);
  2. 这条源的 code(如 erp_contract);
  3. 那串应用密钥(走加密渠道单独发,别和上一条同一条消息)。

密钥是验票和回写共用的一把,不再另发开放平台那套 app_key / app_secret。 需要第三方从自己服务器直接发起单据时,另外到「开放平台」页(/design/open-platform)给它建一个应用、 勾 work:write(见 §4.5)。

2. 表单设计者:那一格 type=embed 怎么配

页面:侧栏「表单设计」→ 打开这张表单 → 拖入「外部页面」这一格 → 右侧属性面板; 回写要落的那几格还得在「流程设计 → 那一环节 → 表单与字段权限」里是可改的。 设计器里不加载真页面(画布太窄看不出效果,而且每开一次设计器就打一次对方系统), 想看效果点面板上的「预览真页面」。

2.1 面板从上到下

栏位 存的是 说明
要嵌哪个页面 embed.source 下拉里只有已登记、provider=embed 的那几条。旁边会显示探测结论与「链接每次打开现取一次」
显示方式 embed.mode 自动(能嵌就嵌,嵌不进退成卡片)/ 一定嵌进去 / 只给一张「新窗口打开」的卡片
窄屏上 embed.mobile 默认只给卡片;确认对方页面在手机宽度能用再改成照样嵌
只读场合(已办、代看、单据详情) embed.readonly 三档。默认「只沿用已有那一页」(auto):这一屏只问库里有没有对面那一条地址,有就地嵌进去、一次建页接口都不打;没存过还是那张卡片,不替你新建一页。「点「打开」才加载」(button)一次都不问,每张单都要亲手点一下;「自动加载」(frame)一律现问,代价是每打开一次发一条新短码、多一条留痕、对面多半多一页。打印那份永远是卡片,纸上印不出 iframe。见 §2.1.4
同一张单上这一格用对方哪一页 embed.reopen 三档。默认「只用第一次那一页」(share):一张单在对方系统里只有一页——谁先点开这一格那一页就是那一次建出来的,后面每个环节、每个来看的人都回到那一页(按「源 + 格子 + 这张单」认,oa_embed_page 那一行活到单删)。「每个人各用一趟」(same)是旧口径,对方那一页按打开的人建东西(每人一张自己的受理单)才要;「每次开新的一页」(new)连同一个人都复用不了,留给按打开次数建东西的那类页面。判据与代价见 §2.1.3
这一页能不能操作 embed.interactive 默认「一直能操作」。四档,见 §2.1.1
给哪一条地址 embed.link 对方一次回好几条地址时才用得上。默认「按人自动选」:发起人还没办完给编辑页,其余人一律查看页;只想看一眼的场合连发起人自己也一律查看页,选「发起那一屏之外都给查看页」。除此之外这一格还能点名要另一条(print 那种),下拉里的候选直接从那条源登记的链接清单长出来——能挑哪几条 = 管理员登记了哪几条。见 §2.1.2,判据在后端,前端改不动
这一页在框里还能做什么 embed.sandbox 默认只给脚本、同源、表单、新窗口四项。对方那一页「什么按钮都点不动」,八成是差这里一项:确认框 → allow-modals、导出 → allow-downloads、点一下要整页跳走 → 那两条 allow-top-navigation*
要带的参数 embed.params 两列都是下拉:参数名挑这条源声明过的那几个,取值写法挑这张单的格子({form.x})或系统值({auto:today} 等)。清单外写 {const:文字} 是固定值 那一格存的是一串值(选人、多选)时,交出去的是按顿号拼起来的那一句话(zhangsan、zhangsan、lisi),不是 [zhangsan] 那种带方括号的形状;要的是登录账号就写 {account:form.x}
什么时候能让这一页打开 embed.openWhen 默认「要带的参数都填上之后」:那几格空着时对方多半回一句缺参数,人点开只看到一张报错页。本来就能空着的页面改成「任何时候」
内嵌框高度 / 给多高 embed.height / embed.fit 对方按对接文档报 oa:resize 就不用配高度
要回填给表单的字段 embed.writeback 见 §2.2
这一页能让 OA 做哪几件事 embed.actions 见 §2.3
这一页被放弃时 embed.abandon 默认不用配:那条源配好了,面板只念一句"会发出去的是这一句";这里只留一句例外——这张单不发。见 §2.4

这一格本身不产生值:不能勾必填、挂不上额度或阈值、进不了明细列,版面格子、明细行、 附件也进不了"取值写法"那一列(挑了也带不出值,面板里根本没有它们)。

那一格带出去的值,发起页与每个审批环节必须是同一组字。发起页上那几格只有浏览器里有, 值由前端拼好交上去;单据发出去之后由后端从单据里算。这两处一旦拼法不一样(前端把数组拼成 zhangsan,后端照存储形状给 ["zhangsan"]),参数名、参数个数、留痕里的 keys 还是一模一样, 看不出错——于是同一张页面在发起页打得好好的,一到部门主管、财务经理那些环节就报"账户未绑定", 屏幕上只剩一句"这个页面暂时打不开"。现在两边共用一份口径(service/embed.py:arg_text 与 utils/embedParamText):数组按顿号拼、开关给 true、金额那种浮点给 2 而不是 2.0,钉它的断言在 scripts/check_embed.py 的「这一格交出去的那几个值」那一段。

2.1.1 这一页能不能操作:四档,不是一个开关

档 存的是 什么时候点得动 给谁用
一直能操作(默认) full 什么时候都点得动,包括已办和单据详情 绝大多数。把别人的页面嵌进 OA,为的就是在这一屏把事办完
只在发起那一屏能操作 start 还没生成单号、或草稿还没提交的那一屏;单据一提交,往后每一环都只展示 "开始节点能填、其余环节只许看" ——就是这一档,配一次管全流程,不用逐个环节去勾权限
跟着环节权限走 perm 这一格在当前环节没被点名设成只读就点得动;环节把它锁成只读、或整屏是回看,就点不动 要按环节分别收紧的:主管那一环能在里面改,到财务那一环只许看
一直只展示 view 什么时候都点不动 对面已经归档的那一张,留一张能点的页面反而误事

三件事得说在前面:

  1. "点不动"是真的不吃鼠标事件(那一框上写 pointer-events: none):框里点什么都没反应, 滚轮也归 OA 这一页。翻成点不动那几档之后,界面上会跟着挂一句为什么点不动—— 下一来看的人不会当成系统坏了。
  2. perm 那一档要去环节里点名。路径是「流程设计 → 环节 → 表单与字段权限」,找到这一格, 给它点「只读」;那一颗**「全部只读」也会连它一起锁**——那一栏里只有配成这一档的嵌入页 真的在听 formPerms,其余没有录入框的格子(分隔线 / 说明 / 取数 / 公式)一律不动。 没点名的环节一律算"改得动",也就是照常能点。
  3. 标签页里那一整页的嵌入格,perm 跟的是「标签页」那一片的权限,不是标签页里每一页的。 那一屏上这一格是平铺时现合成的,用的是标签页那个宿主格子的 key,所以要在环节里锁它, 动的是「标签页」那一行(它有完整的四档可点);下面那些「本页签」的行只有「沿用 / 隐藏」。 只想让其中某一页点不动,perm 做不到,用 start 更实在。

顺带分清两栏:embed.readonly 管的是只读场合装不装这一框(默认不装,给一张卡片), embed.interactive 管的是装上了之后让不让点。只在回看屏上收紧,两栏要一起看。

2.1.2 给哪一条地址:编辑页、查看页,与另外登记的那几条

对面那一类接口是每调一次建一张页的,而一次回好几条地址是常事:编辑页(改得动这张单)、 查看页(只读),有时还有打印页、发票夹那几条。这一栏回答的是"这一格递哪一条"。

档 存的是 递哪一条 给谁用
按人自动选(默认) auto "这张单的发起人、且此刻还有他要做的事"那一个人拿编辑页:发起页、草稿、退回本人。提交之后他自己回来看也是查看页 绝大多数。发起人接着填,审批人 / 已办 / 代看 / 办结回看一律只读那一条
发起那一屏之外都给查看页 start 只问一条:这一屏手上有没有这张单。没有(发起页、还没存的草稿)给编辑页让他接着填;有就一律查看页,连发起人自己也一样 「我的发起」「我的已办」「待办审批页」那些点开只是看一眼的场合,偏偏对面那个建页接口每调一次建一张页——auto 在发起人还有代办时给他编辑页,管不了这一句。这一档要这条源配了查看页那一栏才有效果
都给编辑页 edit 每一个人都是编辑页 审批动作就在对方那一页里做的那种系统——递查看页等于没人办得成事
都给查看页 view 每一个人都是查看页 这一格只负责"看一眼对方那边长什么样",动手一律回对方系统
另外登记的那几条 键名(print 这种) 谁点开都是那一条,不看这一刻站着的是谁 这一格要摆的就是对面的打印页、发票夹时。那一条是管理员在源上的「还有哪几条链接」里登记的,那一屏究竟是什么、改不改得动这张单,只有配那条源的人说得上话,所以要与他对一下再选

这一格点得到哪几条,等于那条源登记了哪几条:面板上那个下拉的候选来自 GET /embed/sources 回的 links(每一项是键名、名字、是不是内置那两条),名字念管理员起的 那个。位置与地址模板不进浏览器,配表单的人用不着抄第二份。存量配置里写着一条这条源今天 没登记的键名(源改过、表单没跟着改)时,面板照样把它摆出来、染成琥珀色说清"打开时会退回 编辑页",而不是悄悄改掉人配的那一栏。

判据全在后端(service/embed.py:link_kind_for:是不是 work.creator,加上这一刻有没有 属于他的待办)。前端与第三方都改不动它——"拿查看页那条链接去改单"不该由浏览器说了算。 POST /embed/launch 回一句 link,说的是实际给出去的那一条(edit / view / 那个键名), 另回一句 linkName 说那一条在管理员那里叫什么:这一格要查看页而这条源只有一条地址时给的就是 edit,那一框下面挂的那行灰字因此不会撒谎。

对方那一栏回的是空串,不是"这栏配歪了"。 生产上撞的就是这一式:那条源一次回两条 (填报页 data.fill_url、审阅页 data.review_url),而单据没进审阅之前审阅页回的是空串 (跟着 is_review_allowed:false 一起回)。"键在、值是空的"说的是对方这一趟没有这一页, 与"位置写歪取不到"是两件事:前者走退路(递填报页那一条)并回 linkAbsent=true,后者照旧当场 失败并念出这份响应里像链接的位置。以前两者都算"取不到",于是只读场合(一律要审阅页) 在流程在途时谁都打不开,屏幕上那句「那个接口没有回链接」还把配对了的人一起带走。 回包里 linkWanted / linkWantedName 说的是这一屏要的那一条,link 是实际递出去的, 两者不一样时那一框下面那句灰字分两种话说:「对方这一趟还没给出那一条(等一等就有)」与 「这条源眼下给不出那一条(去那条记录上把那一栏补上)」。

同一趟只问一次,那几条存进库。 这才是"打开一次创建一次"的正解:

  1. 第一次打开时问对方要地址,一次调用把这条源登记的那几条一起取回(外加「顺手带回的 那几个值」),钉在这一趟的嵌入会话上(oa_embed_session 的 url_extra / link_meta; 早先那两列 url_edit / url_view 还在,只装编辑页与查看页那两条)。于是"对面是不是已经 建过这一页了"在 OA 里第一次变成一个查库就能答的问题,而"这一格要第三条"也不会因此 多打一次接口。
  2. 同一趟再打开(刷新、提交后落到单据页、换个环节回看)一次接口都不打,直接用存过的那条, 免登短码每次现发一条挂上去。只有一个例外:这一屏要的那一条这条源确实配了位置、而存过的 那几条里恰恰没有它——那种"没有"是对方上一次回话时这一页还不存在(审阅页在进审阅之前一律 回空串),一直沿用等于把"这一屏是对面的哪一页"永远钉在第一次那一次的答案上,也就是 「已经进审阅了,已办里点开还是填报页」。这一种再问一次:问到的只用来补空(认过的那几条 不被顶掉,同一张单上这一格始终指同一张页),问不成也照旧递手上那一页,不把这一屏关在门外。 代价说清楚:对方一直不给那一页时,只读场合每点开一次会多打一次接口(对面按单号幂等时 不多建一页,生产那条就是);不想吃这一次代价,就把那一栏留着别配,那一档自然塌回编辑页。 那一框下面那句「这一条是这一趟之前就用过的那一页,没有让对方 再新建一张」说的就是这件事(接口字段 linkReused)。
  3. 换一个人、换到后面的节点再点开,也一次接口都不打(默认那一档 embed.reopen=share): 这一趟没有地址时后端再问一层——这张单第一次建出来的那一页记在 oa_embed_page (按「源 + 格子 + 单」唯一,活得和这张单一样长)。那一框下面因此换成另一句实话: 「这一屏是这张单第一次在对方系统里建好的那一页,没有再新建」,并点出那一页是谁、 在哪个环节、什么时候打开时建出来的(接口字段 linkShared + linkPage)。 为什么要有第二层:一张单在 OA 里注定要经过好几个人、好几天,而会话是按人认的、 几小时就过期——只按人复用的话,审批人点开就是第二张草稿,第三方那边躺一排没人认领的东西。
  4. 该重问的几种情形还是会重问:这个人这一趟的参数指纹变了而这一格翻成了 same (旧地址是拿旧值问出来的那一页,留着就是一张"值还是上一刻"的旧页;share 那一档不吃 指纹,因为对面那一页是按这张单建的,{auto:当前看单的人} 那类取值本来每次都不同); 这一格翻成「每次开新的一页」(embed.reopen=new,连预受理号都要换); 这一趟过期或被放弃了(下一趟本来就该是新的一张页)。

灵活性上有两个地方不用改代码就能调:源上那几栏留空 = 这条源只有编辑页那一条地址,auto 自动退回"谁都拿编辑页",存量表单一条都不受影响;url_path、view_url_path 与那张 「还有哪几条链接」表只是同一份响应里的几个位置,对方回几条、那几条叫什么名字都随它, 只要求同一次回完。

顺手带回的那几个值(url_meta)跟的是同一句:它们来自同一次取链接的调用,所以不会 为了"想知道对面那个单号"再多建一张页。界面拿到的是 linkMeta,摆在那一框下面当灰字, 沿用旧地址那一次也跟着沿用——一次接口都不打的那一次,灰字不能凭空变空。它不是回填: 要往单据里写字,走取数(fetch)或回写(writeback)那两条正路。

顺带把三栏分清楚,别再叠在一起猜:embed.readonly 管装不装这一框, embed.interactive 管让不让点,embed.link 管递哪一条地址、 embed.reopen 管这一格在对方系统里该有几页。

2.1.4 只读那一屏要不要自己把页面装起来:embed.readonly 三档

「我的发起」「我的已办」「单据详情」「代看」那一类屏上没有录入框,装不装这一框是产品选择, 所以它单独一档,跟 §2.1.1 那四档(装上了让不让点)互不越界。三档:

档 值 那一屏上发生什么 什么时候选它
点「打开」才加载 button 只有一张卡片和一个按钮,一次都不问后端 对面那一页很贵(每问一次建一页),宁可让人多点一下
只沿用已有那一页(默认) auto 库里存过这一页 → 直接嵌进来;没存过 → 还是那张卡片 绝大多数。同一张单只要有人在发起页或待办里点开过这一格,回看屏就看得见那一页,而一次建页接口都不打、一条短码都不发、一笔留痕都不记
自动加载 frame 一律现问一次,问不到才退回卡片 对方那一页每次都值得为这一屏现建一张(比如按这次打开建的看板)

三句要说明白的:

  1. 认不出来的值退回 auto,不退回 button:配歪一个字母不该把人踢回「每张单都要亲手点一次」。
  2. auto 那一档不会凭空造出对面那一页。它发的请求多带一句 reuseOnly=true,后端库里 没货就回 held: false,界面照旧摆卡片。要「这一屏顺手把页面建出来」就点卡片上那颗「打开」 ——点了就地嵌,不再跳新窗口,也不额外多建一页。
  3. 同一句请求还带 viewOnly=true:那一屏是回看屏。它只往严的方向收窄——link=auto 不再问「这个人手上还有没有待办」,一律给查看页那一条地址;当前环节把这一格设成「隐藏」 也不再把这一屏拒在门外(那一屏本来就把整张表单的值摊开给他看,拦他的那句 「这一格在当前环节是隐藏的」从来不是权限,只是审批屏的渲染效果)。 跟这张单没关系的人照旧一句「你看不到这一格」。

「打开就看到的那一页」就是这条源配的那条查看页地址:库里那一行 (oa_embed_page.url_view)记的是对面第一次建页时回给你的那一条,回看屏认的就是它。 库里只存过编辑页、而这一屏要查看页时仍会再问一次(只补那一条空着的地址,不换页、不新建页), 问不到就照旧递手上那一页,并在回包里说实话(linkAbsent)。

判据在 service/embed.py:readonly_of 与 utils/formRuntime.ts:embedReadonly(同一份三档), 契约在 EmbedLaunchBody.reuse_only / view_only,钉它的是 backend/scripts/check_embed_readonly_auto.py 与 frontend/src/components/oa/EmbedFrame.readonly.spec.ts。

2.1.3 这一格在对方系统里该有几页:embed.reopen 三档

这一档管的是"一张单在对方系统里应该躺着几页"。三档,默认那一档按这张单复用:

档 界面上 一行页面账按什么认 什么时候要它
share 只用第一次那一页(默认) 源 + 格子 + 这张单(oa_embed_page,活到单删) 绝大多数。对方那一页就是"这张单在那边的样子",后面每个环节、每个人都该看同一页
same 每个人各用一趟 源 + 这个人 + 这张单(oa_embed_session,session_ttl) 对方那一页按打开的人建自己的东西(每人一张自己的受理单、按人记操作日志)
new 每次开新的一页 谁都不认,每次现问 对方那一页按打开次数建东西(每次一张新报价单)

两句容易搞错的:

  • 共用一页不等于共用凭据。 share 之下换一个人点开,仍然新开一趟会话、另发一个预受理号、 decide 仍然只落在他自己那条待办上——共用的只是"对面那一页是哪几条地址"。第三方要按这张单 找回自己那张草稿,用验票响应 context 里的 job / serial,或 linkPage.prekey (第一次建这一页那一趟的号)。
  • 编辑页 / 查看页照旧各拿各的。 这一档只搬"哪一页",不搬"哪一条地址":embed.link 与 后端那句按人判(发起人且还有事要办 = 编辑页,其余 = 查看页)一个字都没改,两个人看的是 同一张页的两个看法。

为什么默认要从 same 挪到 share:会话是按人认的、几个小时就过期,而一张单在 OA 里 注定要经过好几个人、好几天。只按人复用的话,发起人建第一页、审批人点开第二页、 分管领导点开第三页,对方系统里就此躺一排没人认领也没人删得掉的草稿(abandon 那三条腿 只认发起页占下的那个号,救不回后面那几张)。判据与代价见 embed-action-design.md §2.1.1,钉它的是 backend/scripts/check_embed_shared_page.py(真流程 + 三个真人 + 数那个建页接口被打了几次):

cd backend && PYTHONPATH=. python3 scripts/check_embed_shared_page.py

2.2 回写白名单(writeback)

"writeback": {
  "enabled": true,
  "fields": ["contractName", "amount"],      // 允许对方写进哪几格,默认一条都不收
  "map": { "erp.amount": "amount" }          // 对方回传的键名跟你的字段名不一样时才要
}

配的时候只有收得下的格子会出现在勾选列表里:文本、数字、日期那一类,而且必须是 填写人这一环本来就改得动的格子。挂了额度或阈值的格子一律不收(外部系统只能提供值, 不能决定流转)。对方给的值按这一格的类型收(数字、日期、开关、候选里已有的那一项), 收不下的会当场说是哪一格、为什么。不填 map 就是同名直写。 「对方字段名」那一栏怎么知道该填什么——它是对方报文里的键名(invoice_no、ht_amount、 kpgssh……),OA 说不上话,只有三个来源:① 对方接口文档;② 对方回写过而 OA 没收下的那些键名, oa:ack 的 rejected 会点名是哪几个、为什么(这一条最准,因为它就是对面真发出来的东西); ③ 这条源最近真回传过的键名——回写留痕里存着当次收到的键名(只存名字,值一个字不入库), 属性面板上那一栏因此也是能挑的下拉(接口字段 GET /embed/sources 的 remoteKeys)。 一次都没回写过时它还是输入框。这一份同样不是白名单,对方换了名字照旧填得进去。

map 里填的是"他的名字 → 我的格子",两边都在清单里的格子以这张表为准;不填这张表就是 同名直写(要求对方照抄 OA 的字段名)。白名单外与表里没有的键一律静默不收, 所以那句 rejected 值得每次联调都看一眼。

2.3 动作那一档(actions)

"actions": {
  "enabled": true,
  "allow": ["submit", "save", "decide", "refresh"],   // 默认整档关着
  "confirm": true,                                     // 默认必问,别轻易关
  "decisions": { "APPROVED": "agree", "REJECTED": "refuse" }
}

四件事各自的用处:submit 发起这张单(发起页)、save 存为草稿(发起页)、 decide 提交本环节(审批页)、refresh 请 OA 重新取一次地址。 勾上的每一项都只在这个人亲自点过确认之后才发生;confirm 关掉意味着对方页面里 一次误触就能发出一张单,所以面板上那句提示写得很直白。

decisions 那一栏只在勾了「提交本环节」时出现,配的是「他们那边的写法 → 算成 OA 的」, 值只有 agree / refuse / submit 三种。键照对方系统里那一列原样抄(大小写不改, 读的时候两边都 casefold)。这里映射不到出口名——走哪条出口仍由 OA 按这一环真实存在的 出口判,多出口时对方给准名或让 OA 把候选念回去。

2.4 这一页被放弃时那一档(abandon)

这一档不在写回那三层(源 / 模板 / 环节挂载)里,在「集成写回」的模板上看不到它——那一层的 每一样都以"已经有一张单"为前提。要配就来「外部数据源」,见 §1.1 那一栏。

表单设计者这一头默认什么都不用配。 那条「可嵌入页面」上说了往哪儿发(§1.1),这一格就 跟着发;面板上那一栏只是把会发出去的那一句念给你听,一个字段都不往表单上写。

发起页嵌了对方那个新建页时,对方是按 OA 预留的正式单号先把草稿建起来的;人在 OA 这边 没保存就返回,OA 什么都没留下,对面却躺着一张没人认领的单。这一档就是"给那边打个招呼删掉它"。 那一刻没有单据、没有环节,写回那三层挂不上(它们的幂等键里都带着单号),能指代这件事的 只有这一趟嵌入会话——所以它既不在写回模板里,也不在环节上。

这一格上只剩一句例外:

"abandon": { "enabled": false }     // 这张单不发那句通知(不写 = 跟着那条源走)

为什么默认不再要求勾一次:往哪儿发、用什么方法、对方那个单号字段叫什么,说的是那个外部 系统长什么样,配一次所有用它页面的表单都跟着受益;而会去配那条通道/地址的人,本来就是 主张"这家系统的草稿该由我们打招呼删"的人。再压一张"每张单来勾一次"只会漏勾,漏勾的结局 正是对面攒一堆没人认领的草稿。真危险的那一面(删掉还在用的草稿)不靠这个开关挡,靠后端 那三条"不许删"。

三条要记住的:

  • 说要发也不等于一定发。这一趟变成了单、挂着 OA 草稿、或那个号已经落在别的草稿上,后端 一律不发——删错一张草稿比不删糟得多。完整的"发与不发"清单在 §4.7;
  • 那条源没配通知方式、这一格却留着一条"要发"的老配置,保存这一刻就挡(§2.5 那一栏念同一句话);
  • 这一档只删对面那张草稿,不动 OA 这边任何东西:OA 的草稿该走 OA 的草稿列表找回。

2.5 配错了不用等联调

面板会当场点名还差什么,出现红字就别保存了:

面板上念的话 去改哪儿
「一个动作都没勾:这一档等于没开」 actions.allow 勾一个,或把整档关掉
「还要外部数据源那条记录上配了应用密钥」 §1.1 的「与对方约定的应用密钥」
「还要把那条记录的免登方式改成一次性短码」 §1.1 的免登方式
「还要把上面要回填给表单的字段打开」 §2.2 的 writeback.enabled
「这一格收不下」 那一格挂了额度/阈值,或这一环改不动它(§0 的 ③)
「这张表单上还没有收得下回填的格子」 这张单全是版面/明细/附件,换一张单试
「这一格要「被放弃时通知对方」,可这一页所属的外部系统还没配通知方式」 那一格留着一条要发的老配置(embed.abandon.enabled: true),而那条源上通知方式选的是「不发」

3. 运维:部署档 [embed]

都在配置文件(config.<env>.toml 的 [embed] 段)或环境变量里,刻意不收进系统设置页: CSP 是整站级别的响应头,改错一次会让所有页面打不开。

键 环境变量 默认 什么时候动它
enabled OA_EMBED_ENABLED true 总闸。关掉之后所有嵌入格都退成卡片,一条短码都不发
csp OA_EMBED_CSP true frame-src 开关。跟某个环境的预览/报表打架时先关它排查
frame_extra OA_EMBED_FRAME_EXTRA 空 偶尔要留一个不在注册表里的来源时用,属于绕道,能不用就不用
ticket_ttl OA_EMBED_TICKET_TTL 60 对方服务端验票慢(跨机房、要过一层网关)才调大
allow_http OA_EMBED_ALLOW_HTTP false 整片内网确实没有 https 才开。生产开着它,启动体检会点名
session_ttl OA_EMBED_SESSION_TTL 7200(夹在 300~86400) 那把会话令牌能回写多久(打开与每次刷新都往前挪一格)。跨天的审批不要靠调大它撑,那种集成走开放平台长期凭据;开始环节「没有单据时代为发起」不受它管,见 §8 最后一条
callback_dedupe OA_EMBED_CALLBACK_DEDUPE 300 同一趟两次回写的静默期,只压重试风暴;0 = 不压。正确性由引擎那条待办负责

4. 给对方系统的一页纸

4.1 一次打开的完整时序

  1. 人在 OA 填单,点开那一格 → OA 前端调自己的 POST /api/v1/embed/launch;
  2. OA 后端算参数、拼地址、发免登短码,短码挂在地址 # 之后(#…&ticket=…;放片段是为了 不进 Referer、不进对方访问日志);
  3. iframe 装载那条地址,# 后面的东西只有对方前端脚本读得到,服务端收不到;
  4. 对方前端把 ticket 交给自己后端,自己后端调 OA 的 POST /embed/tickets/verify (带应用密钥)换"现在站在屏幕前的是谁",顺带拿回这一趟的凭据 callback;
  5. 页面正常渲染,权限由对方按这个人判;
  6. 之后任何一方要对上话,都凭 §4.5 那三档回写,prekey 认趟、令牌认凭据。

4.2 iframe 里会收到的第一条消息 oa:handshake

iframe 触发 load 之后,OA 朝那一页发一条(targetOrigin 写死成发票那条地址的来源, 永远不是 *)。对方那一侧照同样规矩收:只认 event.origin 等于 OA 地址、 event.source 是自己那个父窗口的那一条,别的直接丢。

字段 是什么 对方要做什么
nonce 一次性口令 之后发 oa:result / oa:action 必须原样带回,差一个字符就被丢
params 后端实际拼进地址的那几个参数值 页面自己取号用,别再从查询串猜
prekey 预受理号(顶层,也重复在 session / context 里) 存进自己的草稿表当外键,回写时当幂等键
actions 这一格开放了哪几件事(submit / save / decide / refresh) 按它决定要不要摆那颗按钮,别自己判
session prekey / scopes / scopeLabels / expiresAt / ttl / pending / started / context scopes 是这一趟能回写哪几档;started 非空说明这一趟已经是一张单了
context job / work / activity / activityName / task / draft / serial / identity / fields 发起页上 serial 是 OA 预留的正式单号,可以直接照它建档

之后 OA 还会随表单上的值变化推 oa:params(同样带 nonce),那是同一份参数的最新值。

4.3 对方能发给 OA 的四条消息

// 只回几个值进格子
parent.postMessage({ type: 'oa:result', nonce, values: { contractName: '…', 'erp.amount': '12800' } }, 'https://oa.example.com')

// 请 OA 真的动一张单(这件事必须在这格开放清单里,且默认会弹一次确认)
parent.postMessage({ type: 'oa:action', nonce, action: 'submit', values: { amount: '12800' } }, 'https://oa.example.com')

// 本环节已经审完,请 OA 按这个出口办(审批页;同样要人点确认)
parent.postMessage({ type: 'oa:action', nonce, action: 'decide', route: '送审', opinion: '票据已核验' }, 'https://oa.example.com')

// 页面高度(160~4000 之外的一律不收);另有 type:'oa:ready' 收掉那层"加载中",
// 以及 type:'oa:submitted'——你们点完提交那一刻报一句,OA 当场去问"成单了没有"(不用带 nonce)
parent.postMessage({ type: 'oa:resize', height: 720 }, 'https://oa.example.com')

OA 处理完 oa:result 一定回一句 oa:ack:{ type, nonce, accepted: [...], rejected: [{ key, reason }] }, 里面的键回的是对方发来的那个键名。回执为空数组等同于"一格都没写进去",一定要打日志—— 两边看见的不是同一件事是联调期最费时间的故障。oa:action 里第三方能带来的只有"要办哪件事" 和几个值,做不做由屏幕前那个人点确认;values 先走与 oa:result 完全相同的那道回填闸, 有一个没落成就整句不往上抛(那时屏幕上正红着下面那格,交出去的是半张单)。

4.4 换身份:POST /api/v1/embed/tickets/verify

POST /api/v1/embed/tickets/verify
X-Oa-Integration-Key: {那条源的应用密钥}
Content-Type: application/json

{ "code": "erp_contract", "ticket": "从地址 # 后面读到的那一串" }

成功回(code / msg 外壳略,下同):

{
  "sub": "u_…",                      // OA 里这个人的 id
  "account": "zhangsan",             // 账号:对方系统拿它认人,日志也记它
  "displayName": "张三", "email": "…", "serial": "10086",
  "audience": "ERP_CONTRACT",        // 那条源上的「对方应用编码」,没填就是源的 code
  "argsDigest": "…",                 // 这一次打开的参数指纹,对不上会验不过
  "callback": {                      // 这一格开放了回写能力时才有这一段
    "api": "/api/v1/embed/callback",
    "key_header": "X-Oa-Integration-Key",
    "kind": ["prefill", "start", "decide"],   // 这一趟能做哪几件事,后端算好的
    "prekey": "PRE7K2M9XQ4",
    "token": "oes_…",                // 会话令牌,明文只在这次出现
    "scopes": ["prefill", "start", "decide"],
    "expiresAt": "2026-10-23 14:20:11", "ttl": 7140,
    "pending": [], "started": null,
    "context": { "prekey": "PRE7K2M9XQ4", "job": "", "work": "", "activity": "",
                 "draft": "", "serial": "BX20261023001", "fields": ["amount"] }
  }
}

四条要注意的:

  • 短码默认 60 秒、用一次即烧。对方重试请重新点开那一格,别拿旧码重试;
  • 密钥不对不会烧码——这一条是特意留的,免得对方配错一次就把人这一次打开作废掉;
  • 失败只回一句笼统话(「免登短码无效或已过期…」),真实原因在 OA 侧日志,不把这个接口 变成"某条短码存不存在"的探针;
  • callback.token 是这一趟的凭据,只存在对方服务端,别写进前端、别进日志。它每次验票 轮换一次,所以每次验票都要用最新那把。这一格没开放任何能力时 callback 整段都不发。

4.5 回写结果:POST /api/v1/embed/callback

同一通道、同一把密钥、同一把会话令牌,kind 分三档:

// ① 把值攒在这一趟上(不碰流转;人回 OA 打开这一格时按同一道回填闸落格)
{ "code": "erp_contract", "token": "oes_…", "kind": "prefill",
  "values": { "amount": "12800", "contractName": "…" } }

// ② 这一趟已经在你们那边发起成一张单了(OA 不再重复发起)
{ "code": "erp_contract", "token": "oes_…", "kind": "start",
  "job": "JOB…", "serial": "BX20261023001" }

// ③ 你们审完了,以打开这一页的那个人身份办掉本环节那条待办
{ "code": "erp_contract", "token": "oes_…", "kind": "decide",
  "decision": "APPROVED",            // 或 agree / refuse / submit,或直接给 route
  "route": "", "opinion": "票据已核验无误", "data": {} }
kind 落在哪儿 收什么、不收什么
prefill 攒在会话上,下一次 POST /embed/launch 或参数刷新时随 staged 带回界面 只收那一格回写白名单里的字段;每次打开都原样重投,不设"已投递"标记
start 会话上记下你们的单号;发起页因此收起那颗「发起」并显一句"已经在外部系统发起(单号 X)" 只记账,不建单;记的是那一趟,新开的一页不受影响
decide 走 engine.execute_task,跟人在 OA 点提交同一条路 必填、环节字段权限、额度、闸门一条不少;办的是打开这一页那个人手上那条待办

三条口径:

  • 出口由 OA 匹。只给 decision 时按这一环真实存在的出口翻;多个出口而匹不出唯一一条时, 回的是那几条候选名,绝不猜。多出口环节建议直接给 route。
  • 被人先办掉了回 200 + already: true,不是失败。两个入口同时办是同意的正常结局, 报成失败只会让对方重试。这句话里会说是谁在什么时候办掉的。
  • decide 需要这一格勾了「提交本环节」+ 这条源配了应用密钥,缺一条就是 EMBED_SCOPE_MISSING。同一趟在静默期(默认 300 秒,callback_dedupe)里再回一次结论, 回的是 already: true + deduped: true 并且什么都不改——那一档只压重试风暴, 正确性由引擎那条待办负责。

4.6 对方从自己服务器直接发起(可选,路 B)

人不坐在 OA 前、要在 ERP 那条链路上就把单发出去时,走开放平台,不用会话令牌:

POST /api/v1/open/works
Authorization: Bearer {开放平台访问令牌,范围 work:write}

{ "identity": "zhangsan", "process": "p_…", "data": { … }, "title": "…",
  "bizKey": "PRE7K2M9XQ4" }

bizKey 填那一趟的 prekey,它是幂等键:这一趟已经发起过,OA 不新建,回原单 + alreadyStarted: true + 一句"本次调用没有新建任何东西"。去重是双向的——人在 OA 里先点了 「发起」,OA 也会把这张单记回那一趟上,ERP 再拿同一个号来调就认得出是重复。 认不出来的号、号是别人的、这一趟已被别的单认领,三种情况一律安静忽略,不会回滚一次已成功的发起。

OA 那个还开着的发起页会自己说一句话。这一趟的发起是服务端到服务端进来的,屏幕上那个人 原本听不见——OA 现在每 20 秒问一句「我这一趟变成单了没」(POST /api/v1/embed/state, 切回这一屏、重新装载那一刻也各问一次),问到就把这一页作废:那颗「发起」收起来,浮出 「这一趟已经在外部系统里发起成一张单了(单号 …)」加一个「去看这张单」。 问的是轻的那一条:不重算地址、不再外呼你们的取链接接口、也不记"他打开了那个页面"的留痕。 你们那边不用为此多调任何一个接口——它认的是这一趟自己的预受理号,以及 OA 占给这一趟的 那个正式单号(你们把号写在地址里、bizKey 填自己那套流水号那种接法,同样认得出)。

4.7 OA 主动打给你们的那一句(可选:删掉那张草稿)

人在发起页没保存就返回、或那份草稿在 OA 草稿箱里被真删掉时,OA 都可以通知你们把按那个号 建起来的草稿删掉。发不发、往哪儿发、发哪些键,全配在你们这条源上(§1.1 那一栏:挑一条 写回通道,或直接填地址),表单上那一格默认不参与:

DELETE /api/contract/oa/by-flow-number        # 方法可换 POST / PUT / PATCH,没有 GET
Content-Type: application/json
X-Oa-Integration-Key: {那条源上的应用密钥}      # 与 §4.4 验票同一把;那条源上另配了鉴权方式就照那套发

{ "oa_flow_number": "BX20261023001" }

默认请求体就一个键:键名 = 你们那条源上的「对方按哪个字段收 OA 的单号」(默认 oa_flow_number),值 = 这一趟预留的正式单号(还没排上号时退回预受理号 prekey)。你们的 删除接口要按好几个字段认那张草稿(单号 + 项目号那种),就在 §1.1 填那张多键请求体表 (abandonBody:键 = 你们那边的字段名,值 = 取值写法)——填了就整份发,盖过上面那一对单键; 每个值在打开那一刻算死。地址里写 {value} / {键名},那个值也会填进路径或查询串。

这一档有三条腿,发的是同一个形状、记的是同一本账(留痕里 reason 分得出是哪条腿): 页面被放弃、连草稿都没存那一趟(浏览器报一句 + 会话过期清扫兜底,两条前后脚踩到同一趟 是常态)、草稿真删了那一趟(草稿箱里删的那份草稿,发的是草稿上那个号——你们在那一 页建草稿用的就是它,reason=draft-deleted),以及还没发起流转的单被删了那一趟(发起人在 「我的待办」或「我发起的」里删掉自己创建、还停在开始环节的那张单,发的是这张单的单号—— 草稿占下的那个号在发起那一刻原样交给这张单,所以那两条腿报的常常本来就是同一个号, reason=work-deleted;同一次删除里那几条打开会话只通知一次)。你们那一侧只做一件事: 这条接口要幂等。同一趟可能被报到两次,OA 对同一次删除只发一次,但两次之间不做互斥, 重复调用请回同样的成功。

什么情况 OA 根本不会打过来(这是刻意的,别当成丢了调用):

  • 你们那条源上「这一页被放弃时,通知对方」选的是「不发」(默认就是不发);
  • 这一趟已经发起成一张单了;
  • 那个预留单号已经落在另一份草稿/单据上(删了就是把别人的草稿删了);
  • 这一趟上一次已经发成功;上一次没发成时一分钟内不重发;
  • 这条源被熔断或限流挡着。

还挂着草稿的那一趟单独说:页面被放弃那一刻 OA 故意不发(你们那张草稿还在那份草稿上 用着,删了就是把人在用的单删了);等 OA 这边真删掉那份草稿,同一句才发出去。发起页上存草稿 的那一刻,OA 会自动把这份草稿挂到还开着的那几趟上(存草稿成功即报上来,尽力而为、不挡存草稿), 所以发起页存下来的草稿删掉时找得到那一趟、号也问得到;那份草稿当初不是在嵌入页上存的 (没有对应的那趟打开会话),才找不到人问"你们那边那张叫什么号",不发。删单那一条腿同样 绕开还挂着这份草稿的那几趟——那份草稿人还要用,对面那张也该留着,等他自己删草稿时由 删草稿那一条腿去发那一句。

回 404 按"那边没有这张单"处理,OA 记成已删掉(删除不认"没有"就没法幂等)。其余按你们 这条源上配的出站成功判定认(success_path / success_value,与其他写回同一份判据, 只看 HTTP 码不够)。发不出去不影响 OA 这边任何操作,只在数据源留痕里记一条 kind=abandon。

5. 三个场景照抄清单

5.1 场景 A:发起页还没保存就返回了,接口配在哪儿

配置动作(一次配好,长期有效):

  1. 数据源:page_mode=ticket、填应用密钥、地址模板写好 {arg.*};
  2. 那一格:params 指向发起页上那几格、writeback.enabled=true 并点名要回的格子、 actions.allow 里勾 submit(要顺手存草稿就再加 save);
  3. 那几格在这个环节的字段权限是"可改"(回写要落的就是它们);
  4. 不想让对面攒一堆没人认领的草稿,就到那条源上把「这一页被放弃时,通知对方」挑成那条 「按 OA 单号删草稿」的写回通道(§1.1、§2.4、§4.7)——表单上不用再配任何东西。

跑起来的形状:OA 发一个 prekey → 第三方拿它当草稿外键 → 人走了也没关系, prekey 认得回来(同一趟只认一份,刷新三次不会生三张草稿)→ 第三方 verify 拿到令牌 → prefill 攒值、start 记单号 → 人回来打开这一格, 攒下的值随 staged 落格,"发起"那颗钮收起并写着已经在 ERP 发起(单号 X)。人要是直接返回 不发了,开了那一档的话对面还会收到一句 DELETE,那张草稿不至于留下来。

"同一趟"到哪儿为止:有单据按单据认,没单据按草稿认;发起页刚打开、连草稿都没有的那一刻, 认的是这一页占下的那个流程编号(serial_config.at=create 那一档)——ERP 建草稿用的也是 这一个号,号不一样就是另一趟。而 start 记上一次账,这一趟就到头了:再开一页是新的一趟, 拿新的预受理号,屏幕上不会显上一张的那句提示;还开着的那一页照旧听得见那句"已经发起了" (它按自己手上那个预受理号问)。去重挡的是同一趟发两次,不是这个人在这一格上一辈子只能发一次。

5.2 场景 B:第三方那一页操作完,触发 OA 发起

人在场 → oa:action {action:'submit', values}(§4.3),OA 弹确认,人点确认, 走 useStartForm.submit() 原来那份校验与提交。人不在场 → §4.6 那条 POST /open/works。 两条都带 prekey(前者 OA 自己知道,后者写在 bizKey),所以不会发成两张单。

他们在自己那一页点了提交,OA 这一屏跟着走。 这一路最常见的一句疑问是「点了提交,OA 里 确实多了张单,可这一页还停在编辑页,我以为没发起成」。OA 这边的动作是:那一格收到对方任何 一句话(oa:submitted 报的那一句、oa:ready 那一屏重新加载、oa:result 回写值)就当场问一次 POST /embed/state「这一趟成单了吗」,并按 0.4 / 1.2 / 3 秒追问几拍(他们那边成单要过自己的 后端,前后差一两秒,只问一次容易问早了);平时那一拍是两秒,且只在发起页、还没成单、 页面在眼前时才问,人一走开就停。问到之后发起页收起「发起」那颗(再点就是一张重复单)、 把单号与发起时间摆出来,并立刻跳到那张单的详情页——历史里不留这张空表单,那句交代挂在 跳转前的一次 toast 上(跳过去之后还在)。

对接方想让这一屏"当场"动,就发 oa:submitted。 你们在自己页面上点提交成功的那一刻发一句:

window.parent.postMessage({ type: 'oa:submitted' }, '*')   // 目标域写成 OA 那一个更稳

它不动 OA 的任何数据,因此不需要带 nonce(同 oa:ready / oa:resize 一个待遇), OA 收到只是去问一句「这一趟成单了没有」。不发也完全不影响正确性——OA 靠两秒那一拍自己也会 问到,只是那一两秒里这一屏看上去还是一张编辑页。已经会发 oa:ready 的对接方不用改: 那一屏重新加载本身就是同一件事的迹象。

5.0 实例:费用报销接「财务数字助手」(这套库里真配着的那一条)

一个真实形状走完三件事,照着换编码就能用。对方是 https://reimb.oa.unissense.tech, 发起时对方按 OA 预留的正式单号(FYBX + 日期 + 序号)先建一张报销草稿。

「外部数据源」里两条记录,各管一头:

编码 通道 / 方向 干什么 关键几栏
reimb_shfp 嵌入这个页面 / 取数 发起页那个「费用报销发票信息」页签嵌的就是它 页面地址从哪来 = 先调接口取链接,接口 POST /api/reimbursements/oa/create-link,链接在响应里的位置 data.fill_url,允许的来源 https://reimb.oa.unissense.tech;免登方式 none(那边自己的会话);入参里 oa_flow_number = {arg.processNo}
reimb_api 调外部接口 / 写回 人没保存就返回时,按 OA 单号删掉对面那张草稿 方法 DELETE,地址 https://reimb.oa.unissense.tech/api/reimbursements/oa/by-flow-number,成功判定 code == 0,错误信息在 message

reimb_api 这条就是 §1.1.1 那张表建出来的(库里那条「往外写」的记录如果本来就还没有, 在 reimb_shfp 那一栏下点「就地新建一条写回通道」,建完会自动回到这一栏并替你挑上)。

管理员要动的只有一栏:打开 reimb_shfp →「这一页被放弃时,通知对方」选走一条写回通道 → 挑 reimb_api → 保存。方法、单号字段名都不用填(走通道就照那条通道,字段名默认 oa_flow_number,正好是他们那边的键名)。那个值也不用填:留空就是这一趟预留的正式单号 (对方建草稿时用的就是同一个号),要按别的号删才展开填 abandon_expr。

那条接口一次其实回三条地址,外加几个不是地址的值。 POST /api/reimbursements/oa/create-link 回的 data 里是 fill_url(填报页)、review_url(审阅页)、url(那张报销单的页面), 另有 flow_number(对面那个单号,形如 RE-20261027-004)、employee_name、 is_review_allowed 几样。上面那两栏收的是头两条;第三条与那几个值要想看得见,就在同一张源上补两栏:

// 「还有哪几条链接」
[{ "key": "page", "name": "报销单页面", "path": "data.url" }]
// 「顺手带回的那几个值」
{ "对方单号": "data.flow_number" }

补完之后:那一格「给哪一条地址」的下拉里多出「报销单页面」,那一框下面多一行灰字 「对方单号:RE-20261027-004」,而一次调用还是一次调用——三条地址与那个单号出自同一份响应。 is_review_allowed 那种没被点名的值照旧不收,那一行灰字只念管理员点过名的那几个。

表单设计者一栏都不用动。「费用报销单」那个页签上 embed 配的只有"要带的参数"和 "这一页能让 OA 做哪几件事";放弃通知在源上配好之后,那一格面板只会念一句会发出去的是哪一句。

跑出来的形状是:

DELETE https://reimb.oa.unissense.tech/api/reimbursements/oa/by-flow-number
Content-Type: application/json

{ "oa_flow_number": "FYBX20261023001" }

那边回 {"code":0} 算通知到了;回 404(未找到对应 OA 流程编号的报销单)也按通知到了算—— 这一趟压根没在对面建过东西,或者早删过了,删除不认"没有"就永远红着。这条源上配了通知方式, 不等于每次返回都会打过去:存过草稿、已经发起成单、号落在别的草稿上,OA 故意不发(§4.7)。

想验一句又不想动真单子,就拿一个不可能的单号打一次,回 404 就说明地址、方法、键名三样都对得上。 发出去与没发出去都在「外部数据源」→ 那条记录 → 留痕里,kind=abandon 那几行。

5.3 场景 C:第三方审完,告诉 OA 这一步通过了

  1. 那一格 actions.allow 勾 decide,decisions 配好对方那套状态词;
  2. 数据源配了应用密钥、page_mode=ticket;
  3. 第三方在自己的审批页调 §4.5 的 kind=decide;
  4. OA 以打开这一页那个人身份、走引擎把那条待办办掉,走的出口由 OA 按这一环真实出口匹。

6. 配完怎么验(照着勾)

界面侧,用那个人的账号:

  • 表单上那一格出的是真页面,不是卡片也不是白框;
  • 页面里能看到对方系统里这个人该看的数据(不是管理员、不是空列表);
  • 让对方发一句 oa:result,OA 这一侧格子真的写进去了,且对方收到了 oa:ack;
  • 没勾的格子写不进来,页面上会说"这几格没写进来:……";
  • 点第三方那颗「发起」,OA 弹出确认,念的是"哪一页、做哪件事、带上哪几格";
  • 审批页上让对方向 OA 发一次结论,OA 流程前进一条,办理人是那个人本人;
  • 同一条结论再发一次,对方收到的是成功 + "已被办掉",流程没有走两遍;
  • (那条源配了放弃通知才验)在发起页点开那一格、什么也不填就返回,对方收到一句 DELETE, 带的是这一趟预留的单号;再进去一次、这回存了草稿再返回,对方不该再收到;
  • 数据源那一栏选完通道,下面那行灰字念出来的地址与方法是你们那边真正开的那一条。

脚本侧(口径全靠这几条钉着):

cd backend  && python3 scripts/check_embed.py             # 不连库,19 段
cd backend  && python3 scripts/check_embed_api.py         # 连库连实例,13 段
cd backend  && PYTHONPATH=. python3 scripts/check_embed_decide.py   # 真流程真待办,31 项
cd frontend && pnpm vitest run src/utils/embedBridge.spec.ts src/components/oa/design/EmbedPanel.spec.ts

check_embed_decide.py 会自己建一张真单据、真待办,跑完连源带会话带单据一起删干净。

7. 排查表

现场 十有八九是因为 改哪儿
那一格是一个白框,或自动退成「新窗口打开」卡片 对方用 X-Frame-Options / frame-ancestors 拒绝被嵌,或被 302 到登录页;页面自己往上跳那种探不出来 让对方放开被嵌;放不开就把 embed.mode 定成 link,别硬嵌
「这一页要带的那几格还没填上:合同号」 这一格 openWhen=filled 而取值那几格空着 先填那几格;这类页面本来可以空着就改成「任何时候」
每打开一次都是对面系统里新的一页、多出一份草稿 三条路:① 这一格 embed.reopen=new(明说要每次新开);② 那一屏没把单据号递下来(job 空 = 后端当成发起页,落最宽那一档);③ 这一趟在库里没有存过地址——地址每次现问,那个接口每问一次就在对面建一张页 那一档改回默认的「只用第一次那一页」;确认看的是同一张单;再看那一框下面有没有那句「没有让对方再新建一张」(linkReused)——没有就说明这一趟每次都重新问了一次,多半是值在变或会话没接上,让 IT 升级 OA
提交之后再点开这一格,对面又是一张空页 同一件事的另一张脸:会话是接上了(预受理号没换),地址却重新问了一次 202610271015 起修好(会话上钉着那两条地址);排查时看 oa_embed_session 那一行的 url_edit / url_view 有没有值
走到后面的节点、换一个人点开,对面又新建了一张草稿(发起人看到的是一页,审批人点开是另一页) 会话是按人认的,而那一页原来只记在第一个打开它的人那一趟上;两个人(或同一趟过期之后)就是两趟,于是又打一次那个建页接口 默认的 embed.reopen=share 已修:那一页改记在 oa_embed_page(源 + 格子 + 单,活到单删)。排查看那张表这一单有没有一行、url_edit / url_view 有没有值,以及那一框下面那句「这一屏是这张单第一次在对方系统里建好的那一页」(linkShared)。确实要每人一页,就把那一格翻回 same
流程在途时点开嵌入页说「那个接口没有回链接」(发起页打得开,单据页打不开) 那条源配了查看页那一栏的位置,而对方在单据进审阅之前那一栏回的是空串;只读场合一律要查看页,于是整次打开失败 升级到本版本即可(空串 = 对方这一趟没有那一页,走退路递填报页,linkAbsent 说实话);想让只读场合以后必然换成查看页,把那一格「给哪一条地址」定成「发起那一屏之外都给查看页」(§2.1.2)
只想看一眼,却在对面又建了一份草稿(发起人自己回「我的发起」看也一样) 这一格停在「按人自动选」,而他手上还有代办(退回本人、发起人也要办的那种流程),后端照口径给他编辑页那条——那一条是对面每调一次建一页的建页接口给的 把这一格改成「发起那一屏之外都给查看页」(start),并确认这条源配了查看页那一栏(§2.1.2)
回看屏(我的发起 / 我的已办 / 单据详情)点开那一格,屏幕上只有一句「这一格在当前环节是隐藏的,看不到这个页面」 这张单此刻停着的那一环把这一格设成了「隐藏」,而过去发地址那一头把这一档当硬闸,不管来问的是办理屏还是回看屏 升级到本版本即可:回看屏带着 viewOnly,那句环节隐藏不再挡它(那一屏本来就把整张表单摊开给他看);办理屏照旧挡,两边说同一句话。确实谁都不许看这一格,就在字段自己那一栏勾「默认隐藏」(§2.1.4)
只是点开看一眼,对面又多一页(frame 那一档) 「只读场合」停在「自动加载」= 明说每次都要现问一次,而那个建页接口每问一次建一页 改回默认的「只沿用已有那一页」(auto,§2.1.4);「给哪一条地址」停在「都给编辑页」也照旧给编辑页,一并检查(§2.1.2)
已经进审阅了,已办里点开还是填报页 这一趟第一次打开时对方还没有审阅页,存进库的只有填报页那一条;沿用不看"要的是哪一条" 升级到本版本即可:要的那一条配了位置却没存过就再问一次,问到就换成查看页(§2.1.2)
第三方那一页点了提交,OA 的发起页还停在编辑态 那一屏只能靠自己去问「这一趟成单了吗」,原来这一问挂在改格子那一路与人停手之后的二十秒一拍上 升级到本版本即可:对方一回话就立刻问并追问几拍,问到之后发起页自己跳到那张单(§5.2)
审批人只想看一眼,却在对方那一页里改动了这张单 这一格「给哪一条地址」停在「都给编辑页」,或这条源根本没配查看页那条地址(面板上那句琥珀色提醒就是它) 改回「按人自动选」,并在「外部数据源」那条记录上把查看页那条补上(§1.1 §2.1.2)
那一格明明点了另一条链接(打印页那种),打开却还是编辑页 这条源没登记过被点名的那个键名(源改过、表单没跟着改),后端按退路给编辑页;面板上那句琥珀色说明讲的就是这件事 到「外部数据源」那条记录的「还有哪几条链接」看它现在登记了哪几条,把键名补上,或把那一格改回上面那三档(§1.1 §2.1.2)
想知道对面那个单号,只能翻留痕或打电话问对接的人 那个值同一次调用就带回去了,只是这一条源没点名要它 在「顺手带回的那几个值」里加一行 对方单号 → data.flow_number,那一框下面就多那行灰字;它只读,不进单据数据(§1.1)
页面显示得出来,但点什么都没反应 这一格那四档里选了点不动的那一档(interactive=view 任何时候都点不动;start 是单据已提交;perm 是这一环节被点名设了只读),或整屏本来就是回看,或对方那一页缺 sandbox 里某项能力 那一框下面挂的那句话会说明是哪一种。要放开就翻回「一直能操作」;再看它要的是确认框、下载还是整页跳转,把对应那一项勾上
想让嵌入页只在开始节点能填、其余环节只许看 这不是 bug,是要选对那一档 「这一页能不能操作」选「只在发起那一屏能操作」(start);要按环节分别收紧就选「跟着环节权限走」(perm),再去「表单与字段权限」里给这一格点只读
「免登短码无效或已过期」 超过 60 秒才来验;同一条码用了第二次;code 或密钥不对 对方收到 ticket 立刻验;核对 code 与密钥;真要放宽调 ticket_ttl
「这一趟嵌入会话无效或已过期」 令牌过期(默认 2 小时);用了上一次验票那把(每次验票会轮换);令牌是别人那一趟的 每次验票后取用最新那把;跨天的集成改走 §4.6 的长期凭据,别调大 session_ttl
回写被挡 EMBED_SCOPE_MISSING 那一格没勾「提交本环节」,或这条源没配应用密钥 见 §2.3、§1.1
回写被挡 EMBED_TASK_NOT_FOUND 这个人这一环已经没有待办(已在 OA 办过 / 单走到下一环);或打开这一页的人不是当前办理人 让对方查一下自己的触发时机;需要别人代办走 OA 的转办/委托,不是回写
「这一环有好几个出口,得说清走哪一条」/匹不到出口 只给了 decision 而这一环多出口;或对方状态词没进对照表 报文直接给 route;并在 decisions 里补那条状态词
值发过来了格子却是空的 白名单没开、那一格这一环只读、挂了额度/阈值、或值按类型收不下 看 oa:ack 的 rejected,那句 reason 就是界面上那句
那几栏只能手敲、挑不出位置 没贴「样例响应」,也没点过「看有哪几栏能挑」——那份清单是从一次真响应里摊出来的 见 §1.1.2:有接口就点那一颗,接口还没开发完就先把对方文档里那段返回 JSON 贴进样例
一张业务生成了两张单 两边发起都没带 bizKey=prekey ERP 侧发起一律带上当前的 prekey(§4.6)
对方在他们那边发起成功了,OA 这一屏还是原样,人也以为没发起 那是服务端到服务端进来的一趟,OA 那个开着的发起页原本只在"人改格子"那一路才听得见;现在它自己每 20 秒问一句(§4.6)。问不出的只有三种:这一格从没被打开过(没有预受理号)、那一趟已过期、以及这一屏根本不在发起页 成单后发起页会浮出「这一趟已经在外部系统里发起成一张单了(单号 …)」并收起那颗「发起」。没浮出来就查 oa_embed_session 上这一趟的 serial / claim_job:两个都空 = 那次发起没认到这一趟(号没带、或带的号不是 OA 排出去的那个)。口径由 backend/scripts/check_embed_api.py 那一段「这一趟发起出去了没有」钉着
探测说「可以嵌入」,浏览器却报 CSP 接口取链接那档 url_origins 少登记了这个来源 补「允许的来源」(它同时是 frame-src 白名单)
发起页上回写全被挡成「不在允许回写的字段里」 发起页没有单据,launch 必须带上 process 才算得出白名单 用标准前端组件即可;自研发起页记得带
点第三方那颗「发起」直接发出去了,没问人 actions.confirm=false 改回 true;这个默认值写得很值钱
在「集成写回 → 新建模板」的「什么时候发」里找不到这一档 那一刻还没有这张单,模板的报文 / 条件 / 幂等键 / 发件箱全都以单号为前提,所以它不是一条模板 §2.4:配在那条「可嵌入页面」上;那条下拉里的点名项会把你送回来
面板上念「还没配通知方式」 那条源上那一栏选的是「不发」(或挑的那条写回通道被停用/删掉了),而表单那一格还留着一条要发的老配置 §1.1 那一栏挑一条方向为「写回」的记录,或填地址(只写路径也行)
人回去了,对面那张草稿还躺在他们那儿 那条源上选的是「不发」;或这一趟变成了单、那个号落在别的草稿上,后端故意不发。挂着草稿的那一趟不是"不发",是"等草稿真删了才发"(看下一行) §2.4、§4.7 那份"发与不发"清单
同一个人第二次(第三次)打开发起页之后,那一句删除就再也不发了;界面上还可能冒出一句「这一趟已经在外部系统发起成 …」 新开的那一页复用了上一趟的会话,而上一趟已经发起成一张单了:_abandon_skip 那句「这一趟已经发起成一张单了,不删」把这一趟的删除一起挡下,而这一趟占的号、对面按它建的那份草稿都是新的。号与号不一样都算同一趟,是因为那一档只能按「这个人 + 这一格 + 这条源」认人 已收口:开新页按自己那个预留单号认趟,被单据认领走的那一份不再外借(service/embed_session.py:find_open 的 serial / reuse_claimed),口径由 backend/scripts/check_embed_abandon.py 钉着。查法:看这条源「留痕」kind=abandon 里有没有那一句,再查 oa_embed_session 上这一趟的 serial / claim_job
对面说同一句删除收到了两次 OA 那一腿有两处会报(浏览器报一句 + 会话过期兜底)前后脚到,是常态 对面那条接口做幂等(§4.7);OA 侧同一趟只记一次成功
被抄送/分享的人点开这一格,屏幕上只有「你看不到这一格」 单据详情页本身不问关系(谁在列表里看得见这张单,谁就读得到整张表单),只有发地址这一头问;而过去"有关系"只数办过单的人、发起人和管理员,待阅收件人不算 现在的判据把待阅 / 已阅也算作关系(api/embeds.py:_scope_of),给的是字段自己的权限,不借别人那一环的权限。确实不想让抄送的人打开这一格,就在环节里把这一格设成「隐藏」 — 那是一道硬闸,不是界面效果
这一页只有发起页打得开,单据发出去之后每个环节都打不开(对方回一句账号查不到/未绑定) 取值写法指的是一格存着数组的格子(选人、多选):这一条不报错,只是交出去的值多了一层方括号和引号,对方按账号查人查不到 取值写法改成 {account:form.x}(要的是登录账号时,§2.1 那一行),或确认这套口径已在(service/embed.py:arg_text)。是哪一次带的什么值被打回去,看这条源的「留痕」——参数值不进留痕,但那句失败原因里通常带着对方念回来的那个值
对面回 405 / 参数缺失 方法或那个单号字段名跟他们接口对不上 §1.1 展开「改方法或那个单号字段名」(abandon_method / abandon_field),照对方接口文档抄
对面说删错了 / 没删到那张草稿 那个值取错了(默认是预留单号,可对方按别的号建的草稿),或取值写歪算成空退回预留号 §1.1 同一行填 abandon_expr(你的流程编号那格的取值写法);对方的删除要按好几个字段认那张草稿,就填那张多键请求体表(abandonBody);单号要放地址里就把 {value} 写进 abandon_url。发的是哪个号看「留痕」kind=abandon
待办里删掉一张还没发起的单,对面那份还躺着 那条源上选的是「不发」;或删除的那一刻那几趟会话都已过期被清掉(这张单从没打开过那一格);或那一趟还挂着一份没删的草稿(刻意不发);或那张单其实已经发起流转、走的不是删除 §1.1 那条源配好;发的号是这张单的单号,看「留痕」kind=abandon、reason=work-deleted 那一句
存了草稿、在草稿箱删草稿,对面那张还躺着 那条源上选的是「不发」;或打开那一页的那趟会话已过期被清掉;或那份草稿不是在发起页打开嵌入页时存的(没有对应的那趟打开会话),找不到人问"对面那张叫什么号" §1.1 那条源配好;发的号是草稿上那个号,看「留痕」kind=abandon、reason=draft-deleted 那一句——没有这句留痕,说明删的那一刻那一趟已经不在(或这份草稿压根不是在嵌入页上存的)

8. 别这么配

  • 别把 decisions 当出口映射表。它只翻到"同意 / 不同意 / 提交"三种结论,走哪条出口 永远由 OA 按这一环真实存在的出口判;设计期就收不到出口名,正是因为一上映射表就等于 让外部系统隔空改了流程图。
  • 别为了跨天的审批调大 session_ttl。那一趟该由开放平台的长期凭据负责, 这把令牌管的是"这一趟打开",到期就该废。 这一条说的是对面拿会话令牌主动写 OA 那一路。反过来、第三方只回一句结论词而 OA 替人 把流程发起起来那一档(开始环节「外部审批」里的「没有单据时代为发起」)不归它管:OA 是拿 自己排出去的那个单号回查自己库里的行,那种行占着号又还没成单时会多留七天 (embed_session.GC_HOLD_DAYS,判据 scripts/check_embed_gc.py),所以"今天填、明后天审" 本来就走得通,不用为此把 session_ttl 调到 86400。
  • 别关 confirm。关掉之后对方页面里一次误触就发出一张单。
  • 别把会话令牌放进前端存储、日志、或对方数据库的明文字段。它是凭据,泄露了只能等它过期。
  • 别把「这一页被放弃时,通知对方」挑成会重建草稿的那条通道。那一句的语义是"删掉这一趟 那张草稿",指错了地方就是每次有人返回都凭空多一张单。挑通道之前先确认那条通道真的是"按 OA 单号删";要发给另一个系统就直接填完整地址,并确认那边的鉴权与这把密钥对得上。
  • 别为了这一档再抄一条新地址。那边"按 OA 单号删草稿"的接口如果已经登记过一条写回通道, 挑它:一条地址只有一个主人,抄两份迟早会漂开,而漂开之后发出去的那一句打在旧地址上。
  • 别指望它替 OA 收草稿。这一档只通知对面删对面那张,OA 这边的草稿在草稿列表里, 两边本来就该各删各的。
  • 别指望这一格当写回通道。provider=embed 的方向只能是取数,保存时直接挡; 真要往外部系统写东西,走写回集成那一套。
  • 公网地址别用 http,也别为了省事开 allow_http:那条 iframe 在 https 页面上会被 浏览器拦,明文地址在中间路上是看得见的。

9. 速查

要什么 在哪儿
那一格的完整 JSON 骨架 §2.1 + §2.2 + §2.3 三段合起来
四条对外接口 POST /embed/launch(OA 前端自己用)、POST /embed/tickets/verify、POST /embed/callback、POST /open/works
浏览器消息 oa:handshake oa:params oa:ack(OA → 对方);oa:ready oa:resize oa:submitted oa:result oa:action(对方 → OA,后两条要 nonce)
三档回写 prefill 攒值 / start 记单号 / decide 办待办
放弃通知(OA → 对方)配在哪儿 就一处:那条源 §1.1(abandonSource 挑通道,或 abandonUrl 填地址,加 abandonMethod / abandonField / abandonExpr,要多键就填 abandonBody 那张表)。那一格只留一句例外 embed.abandon.enabled=false(§2.4)
放弃通知那条地址配没配(面板与接口) /embed/sources 回 abandonSet / abandonMethod / abandonField / abandonExpr / abandonBody,地址本身不回
放弃通知会发什么 DELETE + {对方那个单号字段: 那个值},那个值默认这一趟预留的单号(abandonExpr 可改成任意取值写法),填了多键请求体(abandonBody)就整份发、盖过那一个键;地址里写 {value} / {键名} 就把那个值填进路径或查询串;凭证头 X-Oa-Integration-Key;判据 service/embed_session.py:apply_abandon(页面被放弃那一路)、abandon_on_draft_deleted(草稿真删了那一路)与 abandon_on_work_deleted(还没发起的单被删那一路),三条腿发同一个形状、记同一本账
落在哪几张表 oa_data_source(那条源)、oa_embed_ticket(短码)、oa_embed_session(这一趟)、oa_data_source_log(谁打开了哪个页面、回写过什么,只记字段名与数量,不记值)
判据住在哪个文件 backend/app/service/embed.py(配置与判据)、backend/app/service/embed_session.py(这一趟)、backend/app/api/embeds.py(四条接口)、frontend/src/utils/embedBridge.ts(浏览器那一头)
设计论证 embed-action-design.md · embed-page-field-design.md · integration-contract.md §7.1