unis-oa/docs/embed-action-design.md

43 KiB
Raw Permalink Blame History

嵌入第三方页面:怎么对上话、怎么触发发起、怎么回写审批

回答三个真问题,都发生在表单里那一格嵌进了别人家页面之后:

  1. 流程创建页还没保存就返回了,我要调用第三方系统的接口,该把这个接口配在哪儿;
  2. 第三方那一页操作完了,怎么触发 OA 发起这张单,又该怎么配;
  3. 第三方系统里自己审完了,怎么告诉 OA「这一步通过了」。

配套实现:service/embed.py(配置与判据)、service/embed_session.py(这一趟的凭据)、 api/embeds.py(四条对外接口)、utils/embedBridge.ts + components/oa/EmbedFrame.vue (浏览器那一头)。免登、拼地址、回填白名单那一层在 embed-page-field-design.md,本文只讲它之后的事。 要照着配(哪一栏填什么、对方调什么、配完怎么验、排查表)看 embed-configuration-guide.md,本文只留判据与取舍。

0. 一页看完

要做的事 配在哪儿 第三方要调什么
让某个页面能嵌进表单 系统设置 → 外部数据源 → 新建 provider=embed:地址、免登方式、应用密钥 提供 URL;免登要接 POST /embed/tickets/verify
这一格打开哪个页面、带哪几个参数 表单设计器 → 选中那一格 → 外部页面面板 → 数据源 + 参数映射 —
外部页面的值能不能写进表单、写进哪几格 同一面板 → 回填白名单(默认一条都不收) 前端 oa:result,或服务端回写 kind=prefill
这一页能让 OA 做哪几件事(发起/草稿/提交本环节/重开) 同一面板 → 「这一页能让 OA 做哪几件事」(默认整档关闭) 前端 oa:action
一张单在对方系统里该有几页(默认只有一页,后面的节点与后面的人都回到那一页) 同一面板 → 「同一张单上这一格用对方哪一页」(embed.reopen,默认 share) —(对方那个建页接口 OA 只在第一次打开时打一次)
第三方从自己那边发起、并把结果回写进来 不用配新东西:用注册表上那条应用密钥 POST /embed/callback(prefill/start/decide)
第三方自己审完了,让这一步真的通过 上面勾上「提交本环节」+ 这条源配了应用密钥 POST /embed/callback 的 kind=decide

三条贯穿全文的分寸,改代码前先读:

  • 能力由后端算,前端和第三方都只是被告知。判据在 embed_session.scopes_for, 界面按后端给的 actions/scopes 决定按钮存不存在,第三方按验票响应里的 kind 决定要不要调。 谁自己判一遍,谁就会和后端漂成两套。
  • 前端通道不替人按下确认键。oa:action 里第三方能带来的只有"要办哪件事"和几个值, 做不做由屏幕前那个人点确认决定——默认必问,问的那句念的是"谁、做哪件事、带上哪几格", 不是「确定吗?」。真的办下去之后走的是引擎原来那条路(前端走页面自己那颗提交, 服务端走 engine.execute_task),环节字段权限、必填、额度、闸门一条都不因为 "来的不是浏览器"或"是第三方替我选的出口"少跑。
  • 失败即关。回填白名单空 = 一条都不收;动作整档没开 = 一个动作都不给; 没配应用密钥 = 拿不到发起与提交本环节这两档。

1. 为什么短码不够用

oa_embed_ticket 是 60 秒、用一次即烧的一次性凭据。它回答的只有一个问题: 现在站在屏幕前的是谁。这个问题问完之后,短码就不存在了。

而真正需要对上话的三件事全在验票之后,每一件都需要一个跨调用稳定、能指代 "那一趟打开"的东西:

  • 发起页还没保存就退出去了。第三方那边按某个号开了草稿,人第二天回来,双方得认得出 还是同一趟,否则 ERP 里躺着一堆没人认领的草稿;
  • 第三方那一页操作完了想请 OA 发起。它得说清"我说的是哪一格哪一次打开"—— 一个人可能同时开着两张单、同一格页面开了两次;
  • 第三方自己审完了说"张三那一步通过了"。OA 凭什么信、办哪一条待办、走哪条出口。

短码在第一步就被烧掉了,所以补一层嵌入会话(oa_embed_session)。 它与短码同样的分寸:库里只存令牌哈希、明文只在发它那一次出现、到期即废、可提前作废。 差别只在存活期与用途——短码证明"是谁",这一条证明"是哪一趟"。

2. 嵌入会话与预受理号:没保存时靠什么对上话

oa_embed_session 一行绑死在 (哪条源, 哪个人, 哪张单或哪份草稿, 哪个环节, 哪条待办) 上, 带两份对外可见的东西:

  • 会话令牌 oes_…:凭据。只存哈希,泄露了能作废,几小时就废;
  • 预受理号 prekey = PRE + 8 位去歧义字符:话题。它不是凭据——它要印在对方工单 标题上、要在电话里念出来、要在两次打开之间认得出是同一趟。所以它必须短、好念, 而且让人一眼看出"这串不是钥匙,抄给别人也没用"。

2.1 复用口径:什么叫"同一趟"

find_open 按能拿到的最强标识往下退,同一趟只认一份:

  1. 有单据 → 按 work 认;
  2. 没单据有草稿 → 按 draft 认;
  3. 两个都没有(发起页刚打开、草稿还没存)→ 按「这个人 + 这一格 + 这条源」认, 而且必须 work == '' and draft == ''。

第 3 档是最宽的,也是必要的:一个人在发起页上刷新三次页面,不该在 ERP 里生出三张草稿。 最后那半句是防串台的——少了它,发起页上点开的这一趟会去复用那个人在别的单据上开着的 同一格会话,预受理号说的就不是这张单了;这类故障在联调期最难看出来,因为一切"都能用", 只是回写落错了单。

复用不是省一次 insert:open_session 每次打开都会把环节、待办、参数指纹和那份能力清单 按此刻重算一次,而预受理号不变。单子往前走了一环,这一趟能做的事跟着变, 但第三方那句「PRE7K2M9XQ4 这单审完了」始终是有唯一所指的一句话。

复用这一刻还会把存活期按这一次打开往前推一次(open_session 里那句 expires_at)。 不推的后果不是安全漏洞而是这个 bug:同一张单上午看过一次、下午再点开就跨过了那条线, 于是换一个新预受理号,对面就此是"另一趟",屏幕上那个人看见的是一张全新的页面。 推的是"这一次打开之后还活多久",不是"一共活多久"——上界仍由 session_ttl 那把尺子管, 而复用的这一刻本来就重新发过地址、重新烧过免登短码、重新判过环节可见性。

同一句话在 refresh 那一档也推一次(embed_session.touch,判据 scripts/check_embed_gc.py)。 只按"重新打开"续期留了一个洞:发起页上那份整张单底稿(remember_form)是随 refresh 落库的, 而 match_prekey / find_open 都不认过期那一趟——一个人填一张长单填过 session_ttl, 他后面敲的那些值就再也找不到该写给谁,底稿停在他第一次点开那一页的样子。刷新与"人走了补送 那一次"都是这一趟还活着的实证,该续,上界同一条尺子。

另一件相关的事写在这里,因为它同样只服务于"第三方隔天才回写":_gc 对占着一个还没变成 单的正式号的那些行多留 GC_HOLD_DAYS(7)天,那一行是那张还没发起的单在 OA 手里唯一的 底稿(认人与取值都靠它)。见 node-open-approve-design.md §4.6.2。

这一档是可配的:embed.reopen,三档(share / same / new),判据在后端读格子 (service/embed.py:reopen_of),不在调用方嘴里。它管的其实是两件事,各判一句 (reopen_reuses_trip 与 reopen_shares_page):换不换这个人那个预受理号,以及换不换 对面那一页。默认 share 之下前一件照旧复用、后一件按这张单复用;翻成 new 时 open_session 连找都不找,每次另起一趟、另发一个预受理号——只有对方那一页按打开次数建东西 (每次一张新受理单、一份新报价单)才要这一档,否则代价就是他们的系统里躺着一堆没人认领的草稿。

2.1.1 对面那一页属于这张单,不属于哪个人的一趟(oa_embed_page)

find_open 认"同一趟"的第一道条件是 EmbedSession.person == 当前这个人。这一条对凭据是对 的——decide 要落在他自己那条待办上,令牌不能外借;但它顺手把另一件本来不属于它的东西也 管住了:对面那一页的地址。于是生产上撞出第二句一模一样的抱怨:

"我在后面节点打开嵌入页面查看的时候,发现又帮我新建了一个草稿在第三方系统中。 后面的节点难道不应该看的就是第一次返回的那个查看页面么?"

链路是:发起人在发起页点开那一格 → 打一次建页接口 → ERP 建了第一张草稿,两条地址钉在 发起人那一趟上;单子提交、走到审批环节,办理人是另一个人 → find_open 按人查不到 → 手上没有地址 → build_url 只能再打一次那个每调一次建一张页的接口 → 第二张草稿。 上一节那条 reopen 修不了它,因为那一整节讲的都只有"同一个人再点开一次"。

还有一条更隐蔽的:这一层的地址原来跟着会话一起过期(默认 2 小时)。一张单走上几天是常态, 哪怕是同一个人,隔一天在后面的环节再点开也照样是新的一页。

所以把"那一页"从会话里搬出来,记在它真正的主人身上(models.EmbedPage, service/embed_session.py:page_row):

嵌入会话 oa_embed_session 页面账 oa_embed_page
一行是 某个人在这一格上的这一趟 这张单在这一格上对应的那一页
按什么认 源 + 人 + 单(没单退草稿号、再退预留号) 源 + 格子 + 单(唯一约束 uq_embed_page_anchor)
活多久 session_ttl,每次打开与刷新往前推 和这张单一样长,单删了跟着删(_WORK_TRACE_MODELS)
装什么 令牌、预受理号、scopes、该办哪条待办 那几条地址 + 那几个附带值 + 是谁在哪一环建出来的
参数指纹 对不上就作废(那一页是按旧值问出来的) 只作留痕,不作作废的理由

读的时候两层,顺序不能反(held_bundle):先认这个人那一趟,落空了才认这张单那一页。 写的时候也是两处:stamp_links 把这一次问回来的钉在会话上,share 那一档再钉一份到单的账上; stamp_work(提交那一刻把单钉回会话)顺手补写一次,为的是"建了页 → 提交 → 人关掉页面走了" 这一串之后,下一个节点上的人手上没有那一趟、单上又没账,还是得重新问一次接口。

三条判据值得单独说:

  • 第二层不吃参数指纹。 对面那一页是按这张单建的,而 {auto:当前看单的人} 那类取值本来 每个环节都不同;拿它当作废的理由,等于把这一档在每个环节都作废一次。那一行上记的 args_digest 只用来对答"这一页当初是按哪一组值建出来的"。
  • 换人仍然新开一趟。 共用一页不等于共用凭据:审批人拿到的是他自己那个 prekey、 他自己的令牌、他自己那条待办的 decide。第三方要按这张单找回自己那张草稿,靠的是验票响应 context 里的 job / serial,或页面账上那个第一次的 prekey(linkPage.prekey)。
  • 编辑页 / 查看页照旧各拿各的。 这一层只搬"哪一页",不搬"哪一条地址": link_kind_for 仍然按"这个人是不是发起人、此刻还有没有他要做的事"判,两个人看的是同一张页 的两个看法,这正是 build_url 那句"换了个看法不该让对面多一张页"在跨人之后该有的样子。

代价说清楚:后面的人看到的是同一份内容,如果对方系统里那一页本来就分了"谁的编辑页", 这一档会把所有人都指到第一次建的那一张上——那种系统请把这一格翻回 same。

2.2 状态:claimed 也算还开着

发起成功会把状态写成 claimed,而 find_open / latest_open / resolve 都认 LIVE_STATUSES = (open, claimed)。这不是顺手写的宽容:状态记的是"这一趟走到哪一步", 不是"这把钥匙还有没有电"。发起恰恰最需要这条通道活着:第三方报完 start 之后还要能 接着 prefill / decide,而 OA 这边还开着的那一页要靠它听见"ERP 那边已经发起过了" 才收起那颗「发起」钮。那一句走的是参数刷新那一路,按这一页自己那个 prekey 认领 (embed_session.match_prekey),于是它答的永远是这一页那一趟,不会被隔壁那页顶掉。 新开的一页则不接手被认领走的那一份(open_session 那句 reuse_claimed=False), 它另起一个预受理号——被别的单认领走的账不该外借给一个还没动手的人,代价与判据见 docs/embed-configuration-guide.md 里"同一个人第二次打开发起页"那一行。作废靠到期和换令牌。

主键因此用 new_time_id 而不是随机 uuid:上面那两个查询都是 ORDER BY id DESC 取"最近在开着的那一趟",主键随机时那句倒序等于随机挑一条。

2.3 能做哪几件事:scopes_for

scope 开起来的条件
prefill 这一格的回填白名单开着
start 勾了 submit 且 这条源配了 auth_secret 且 page_mode=ticket 且 还没有单据
decide 同上三条 且 此刻这个人在该环节确实有一条没办的待办

为什么要卡"配了密钥 + 走 ticket"这两条:start 与 decide 是真的以那个人的名义动了一张 单。而 ticket 那条免登路是这套设计里唯一一条"凭据只经过两台服务器的手"的通道——没开它, 令牌就只能从浏览器绕一圈,而浏览器那句"说话的是我刚装载的那个 frame"证明得了 frame 是谁, 证明不了拿着这把钥匙的那台机器是谁。连密钥都没有的系统不配替人表态。

decide 再窄一层:那一刻必须真有一条 pending task,否则连"办哪一条"都指不出来。 与其等回写时报错,不如一开始就不给这一档。

3. 令牌怎么交出去:只在"对面确实是那台服务器"那一刻

POST /embed/launch 发地址时会建会话,但配了密钥的源这时不给令牌(判据 api/embeds.py:frontchannel_token)。令牌只在 POST /embed/tickets/verify 的响应里给:

POST /api/v1/embed/tickets/verify      Header: X-Oa-Integration-Key: {注册表那条应用密钥}
{ "code":"erp_contract", "ticket":"{地址 # 之后那个 ticket}" }
-> { "code":0, "data": {
     "sub":"u_8f21…", "account":"zhangsan", "displayName":"张三", "serial":"…",
     "argsDigest":"…",
     "callback": {
       "api":"/api/v1/embed/callback", "key_header":"X-Oa-Integration-Key",
       "token":"oes_…",                  // 只有这一次出现
       "prekey":"PRE7K2M9XQ4",
       "kind":["prefill","start"],       // 这一趟能做哪几件事,后端算好的
       "scopes":["prefill","start"],
       "expiresAt":"2026-10-23 14:20:31", "ttl":7140,
       "context":{ "prekey":"PRE7K2M9XQ4", "job":"", "activity":"", "draft":"",
                   "serial":"BX-2026-0091", "fields":["contractNo","amount"] }
     } } }

三个细节:

  • 每次验票轮换一次令牌(rotate_token)。发地址那一刻只落哈希,验票时现生成一把交出去, 上一次给出去过的那把就此失效,"这一趟"永远只有一把钥匙;
  • 一档能力都没开放就不发凭据。一份 scopes 为空的令牌只能换来一句"这一格没开放任何回写", 发出去只是多一把要人管的钥匙;
  • 没配密钥的源才在 oa:handshake 里随前端通道拿令牌。这种源拿不到 start/decide, 前端通道下发的那把最多只能往这一趟上攒几个还没落格的值。

4. 三个问题分别怎么配、怎么调

4.1 问题一:发起页还没保存就返回了,第三方接口配在哪儿

分三处,都不在代码里:

① 系统设置 → 外部数据源 → 新建一条 provider=embed。 这一条决定"这个系统是谁、 配不配替人表态":页面地址(可含 {arg.xxx} 占位)、免登方式选 ticket、应用密钥 (只进不出,界面上只看 keySet)、参数白名单由地址模板自动导出。

② 表单设计器 → 选中那一格 type=embed 的字段。 这一格决定"这张单的这一格让它做什么":

{
  "key": "embed_erp", "type": "embed", "label": "ERP 合同详情",
  "embed": {
    "source": "erp_contract",
    "params": { "contractNo": "{form.contractNo}", "batch": "{form.batchNo}" },
    // 外部页面的值能写进哪几格。默认空 = 一条都不收
    "writeback": { "enabled": true, "fields": ["contractName"],
                   "map": { "erp.amount": "amount" } },
    // 这一页能让 OA 做哪几件事。默认整档关闭
    "actions": { "enabled": true, "allow": ["submit", "save", "refresh"], "confirm": true,
                 // 对方那套状态词怎么翻(只有勾了 decide 才用得上)
                 "decisions": { "APPROVED": "agree", "REJECTED": "refuse" } }
  }
}

配在同一格上的「这一页能让 OA 做哪几件事」那一栏会当场点名还差什么:还差这条源的应用密钥、 还差把免登改成 ticket、还差把回填白名单打开。配错不用联调才发现。

③ 第三方那侧只需要认一个号:prekey。 未保存的发起页上,OA 没有任何单据号可给, prekey 是双方唯一共有的标识。它会出现在三个地方:地址 # 之后那一串换回来的 oa:handshake(顶层 prekey + session + context)、验票响应的 callback.prekey、 以及 oa:params 推送里。第三方的草稿表用它当外键即可。

发起页还会顺手捎上两样(只是捎带给第三方看的,不参与任何判定): context.serial = serial_config.at=create 那一档预留的正式单号(第三方可以按 OA 的正式单号 直接建档,不必二次对号);context.draft = 已经存过草稿时的草稿号。

值怎么进表单。 两条路,落到同一道闸:

  • 前端 oa:result:页面当场回传,FormRenderer 立刻落格;
  • 服务端 POST /embed/callback { kind:"prefill", values:{…} }:值攒在这一趟会话上, 下一次 POST /embed/launch(打开这一格)或 refresh:true(参数变了在刷新)时随 staged 带回,界面走与 oa:result 完全相同的那道闸落格。

第二条是这次补的。之前攒下来的值没有下一步——"等这个人回 OA 时落格"这句话里那个 把值递回去的动作没人做。现在两条路共用一道闸(环节权限、只读、额度、类型转换都在那儿), 所以服务端进来那一路不比浏览器那一路多收一个字节的值。

每次打开都原样重投,不加"已投递"标记。 诱人但错的做法是只投一次、怕盖掉这个人看过之后 自己改过的那一格;但那样一来最需要它的场合(人离开页面又回来、页面整个重载、表单上的值 本来已经没了)反而会扣着值不投,那才是真把话吞了。重投最坏是把刚手改的那格按回对方给的值, 而那一次是他自己重新打开这一页引来的,屏幕上看得见,提交也还由他按。

发起页上回填白名单要按流程算。 POST /embed/launch 因此多收一个 process: 没有单据时后端问不到流程,而白名单是照着表单算的——不带它,scopes 会算成空表, 第三方回什么都被挡成「不在允许回写的字段里」。这是最常见的场景(发起页)静默失灵那一类, scripts/check_embed_api.py 有一整段钉它。

4.1.1 问题一的尾巴:对面那张草稿得有人删

问题一解决的是"人回来了,值与号都还在"。还有一个反过来的结局没人管:人不回来了。 他在发起页没保存就返回,OA 这边什么都没留下,而对方按 OA 预留的正式单号已经把草稿建起来了。 那一刻没有单据、没有环节,写回那三层(L1 源 / L2 模板 / L3 环节挂载)一条都挂不上—— 它们的幂等键里都带着单号,而这一刻恰恰没有单号。能指代这件事的只有这一趟嵌入会话, 所以这一档发在会话上,与上面那三档回写反着看:那三档是"对方 → OA",这一档是 "OA → 对方"(service/embed_session.py:apply_abandon)。

配置只有一处,这是这一档唯一需要记的形状:那条「可嵌入页面」上说清楚往哪儿发——挑一条 现成的写回通道(abandon_source)或直接写地址(abandon_url),那个外部系统长什么样由 IT 配一次,嵌它的所有表单跟着受益。表单那一格默认不参与,只留一句例外 (embed.abandon.enabled=false = 这张单不发)。

这一档因此改过两版:最早六栏全摆在表单那一格上,配表的人填不出来;上一版收成一个开关 + 地址挪到源上,可它要求每张单再勾一次,而漏勾的结局正是这一档要解决的那个问题(对面攒一堆 没人认领的草稿)——默认值不该是一种失效方式。删错草稿那一面不归开关管,归 _abandon_skip。 "发出去那一句长什么样"始终由后端念给配的人看。

发的是 DELETE(可换 POST/PUT/PATCH,不给 GET:会改对方数据的调用不该是幂等读)、请求体 默认是固定一个键那一对,值默认是这一趟预留的单号、也可在源上配成任意取值写法(abandon_expr, 比如你的流程编号那一格 {form.流程编号})——值在打开那一刻算死记进会话,放弃那一刻照它发。 对方的删除接口要按好几个字段认那张草稿(单号 + 项目号那种),就在源上填那张多键请求体表 (abandon_body:键 = 对方字段名、值 = 取值写法,逐个算死)——填了就整份发,盖过那一对单键; 不填还是那一个键,默认行为一个字不变。地址里写 {value} / {键名} 就把那个值填进路径或查询串。 所以对面那条接口只需一样品质:幂等。回 404 按"那边没有这张单"记成已删掉,因为删除不认 "没有"就永远红着,而服务端兜底那一路会一分钟撞一次。

开了也不等于发,不发也不等于永不再发。 这一趟变成了单、或那个预留号已经落在别的草稿上, 哪条腿都不发——发起页上"先占号 → 再存草稿"是两条会话,只按 session.draft 判就会把刚存好草稿 的人在那边的单子删掉,而他回头打开草稿,对面是一张被删过的。挂着一份 OA 草稿的那一趟,页面 被放弃那一条腿故意不发(那一刻对面那张草稿还在用),轮到草稿真删了那一腿(草稿箱删除 → abandon_on_draft_deleted)才把同一句发出去,标识用草稿上那个号——对方在那一页建草稿 用的就是它。第三条腿是本人创建、还没发起流转的那张单在待办里被删掉(engine.delete_unstarted → abandon_on_work_deleted),标识用这张单的单号(草稿占下的号在发起那一刻原样交给这张单, 与删草稿那一条报的常常本来就是同一个号),还挂着没删的草稿的那几趟刻意绕开。三条腿共用同一段 发送与记账(_abandon_notice + _send_abandon):发同一个形状、记同一本账,reason 分得出是 哪条腿;页面被放弃那一条腿另有两条调用点(人离开时浏览器报一句 POST /embed/abandon、 会话过期时清扫兜底),前后脚踩到同一趟是常态,所以幂等记在会话上、没发成的一分钟内不重发。账本认的是号不是会话:会话会被下一趟复用(重新占一个新号),上一个号的「已发」不能把新号吞了——对方按新号建的那张草稿是另一张。 草稿真删那一腿要按草稿号找到那一趟,而发起页上"先开页面 → 再存草稿"是先后两件事:存草稿成功 的那一刻,发起页把还开着的那几趟的预受理号与这份草稿号一起报上来(POST /embed/link-draft), 草稿号就落在会话上。只认这个人的那几趟(预受理号不是凭据,拿别人的号挂不上),尽力而为—— 挂不上也不挡存草稿,页面被放弃那一腿与过期兜底照旧。存第二份草稿时同一会话被新草稿号覆盖, 最新一份为准。没有这一句挂接,发起页存的草稿在删的那一刻永远只有"没有会话"。 完整的"发与不发"清单在 embed-configuration-guide.md §4.7。

4.2 问题二:第三方操作完了,怎么触发 OA 发起

两条路,按"谁的手最终按下去"分。

路 A:屏幕前那个人还坐着 → 前端 oa:action。 第三方在页面里放一个按钮:

parent.postMessage({
  type: 'oa:action', nonce: NONCE,          // nonce 必须,来自 oa:handshake
  action: 'submit',                          // submit / save / decide / refresh
  values: { amount: '12800', contractName: '…' }   // 顺手带上的表单值,照走白名单
}, 'https://oa.example.com')

OA 侧发生的事:① 后端在发票时就给了 actions,没开放 submit 时这句话在 readEmbedMessage 里就被丢;② values 先过回填那五道闸落格,有一个没落成就整句不往上抛 (值落坏的红字正显示在下面,这时提交交出去的是半张单);③ 弹确认框,念的是 "「ERP 合同详情」那一页要发起这张单;会带上这几格:amount、contractName。现在真的就替您做吗?" ④ 人点确认,走的是 useStartForm.submit() 原来那一份校验与提交。

confirm 默认为真。默认关是很好写但失效最难看的一种选择:一次误触就把单子发出去了, 而屏幕上那个人可能根本没注意。

路 B:人不在这页 / 第三方自己那条链路上就得发出去 → 服务端。

POST /api/v1/open/works        Header: Authorization: Bearer {开放平台访问令牌}   scope: work:write
{ "identity":"zhangsan", "process":"p_…", "data":{…}, "title":"…",
  "bizKey":"PRE7K2M9XQ4" }
-> { "code":0, "data":{ "work":{…}, "tasks":[…] } }

bizKey 就填预受理号。它是幂等键:这一趟已经被认领过,OA 不新建,回原单 + alreadyStarted:true + 一句"这一趟已经发起过一张单了(单号 …)"。

去重是双向的,两头都得记账才挡得住:

  • ERP 先发 → apply_start 把单号记在会话上;OA 这边还开着的那一页靠参数刷新那一路带回的 started 显示横幅、把「发起」那颗钮收起来(刷新带上自己那个 prekey,答的就是这一趟)。 人如果是在发起之后重新打开发起页,那是另外一趟:看不见那句提示,也就不用它替自己 做主,真再点一次「发起」生成的是一张新单——这是"少一句提示"换"不借别人的账";
  • OA 先发 → POST /job 收一个 prekeys: string[](发起页上每格外部页面各有一趟, 所以是清单不是一个号),发起成功后 claim_by_prekeys 把这张单记回那些趟上, ERP 再拿同一个 bizKey 来调就被认成重复。

claim_by_prekeys 挂在一次已经成功的发起后面,因此它对三种情况一律安静忽略且不抛错: 号认不出来、号是别人的(person 对不上)、这一趟已被别的单认领过。为一句"顺手记个账" 把人的单子回滚掉,是拿真实业务换数据整洁。认不出来的号也绝不搅动一次正常发起。

4.3 问题三:第三方审完了,怎么算这一步通过

同一个回写通道,换一档:

POST /api/v1/embed/callback     Header: X-Oa-Integration-Key: {同一条应用密钥}
{ "code":"erp_contract", "token":"oes_…",
  "kind":"decide", "decision":"agree",       // agree / refuse / submit,或直接给 route
  "route":"", "opinion":"票据已核验无误" }
-> { "code":0, "data":{ "handled":true, "route":"通过", "activity":"财务复核",
     "status":"running", "done":false,
     "work":{"job":"…","serial":"BX-2026-0091","status":"running"},
     "tasks":[{"id":"…","activity":"总经理审批","identity":"…"}],
     "routeChoices":["同意","不同意","退回修改"] } }

三条要紧的:

  1. 以打开这一页的那个人身份办,走的还是 engine.execute_task 那一条路。环节字段权限、 必填、公式、额度、外部核验闸门一条都不因为"来的不是浏览器"少跑;引擎里那句 "该待办不属于当前身份"照旧挡冒名顶替。账号停用回一句人话,不硬办。
  2. 出口不由第三方指定具体那条。它只能说"同意 / 不同意 / 提交",OA 按这一环真实存在的 出口去匹。让外部系统直接写出口名,等于让它维护一份 OA 流程图抄本,图一改就静默走错分支 ——那是最难查的一种集成事故。
  3. 已经被人办过了回 200 + alreadyHandled,不是失败(判据 service/tasktrail.py): 两个入口同时办是同意的正常结局,报成失败只会让对方重试到限流打满。

出口匹名用"最长匹配定边"。 「不同意」里面明明白白含着一个「同意」,按"含不含某个词"判 会把一条驳回出口匹成同意。两个出口的环节报"歧义"还算运气好,三个出口的环节会匹错一条、 真的走错分支,而两边日志上都写着成功。side_of 因此比的是谁的线索词长: 「不同意」里「不同意」(3 字) 赢「同意」(2 字),「同意并转财务」里只有「同意」,各归各位。 中英线索词都收(对接方界面文案是哪种真说不准)。

匹不唯一就不猜,回候选让它说清:

-> 400 { "message":"环节「财务复核」有 3 个出口(同意、不同意、退回修改),
        「同意」匹不到唯一那一条。请把这一步走哪条出口名一起回传",
        "reason":"EMBED_ROUTE_AMBIGUOUS" }

只有一个出口时 submit 一个词就够——一级审批那种流程不该逼人再写一个方向词。 而多出口时 submit 会被挡:它只说"这一步我签了",本来就没带方向, 拿一个没方向的词去赌方向,输的是分支。

他们那个词可以不叫 agree。 对方系统里那一列十有八九是 APPROVED / REJECTED, 逼他们为接 OA 改自己库里的枚举、或者在报文里现翻一道,两边都会翻错、而且翻错的那一次 看不出来。所以翻译摆在 OA 这边的配置里(表单那一格 → 「这一页能让 OA 做哪几件事」→ 勾了「提交本环节」之后那张表):

"actions": { "enabled": true, "allow": ["decide"],
             "decisions": { "APPROVED": "agree", "REJECTED": "refuse", "RETURNED": "refuse" } }

键与值两边都不计较大小写与首尾空格(decision_kind)。表里配了这个原词就以表为准, 没配的才按内置三词认——agree 这种内置写法也能在表里改判(第三方那一套词不肯改时靠这一条); 配了 agree → agree 那种自己映自己的,与不配同解。只能映射到那三种结论, 映射不到出口名——design 期就挡(actions_problem 点名哪几条翻不出来), 因为一旦开放"直接映射到出口",这条通道就退化成让第三方维护一份流程图抄本。 翻不出来的词原样交给上面的匹配那一步,那儿会把候选念回给对方。

待办落在哪一条:先认会话上记着的那条(打开这一页时那个人手上就是它), 再按"这个人在这张单上还没办的那条"兜一次(转办、加签之后手上那条可能换过)。 两条都指不出来就是不指,不猜。

4.4 那一屏凭什么知道自己已经被代发了(POST /embed/state)

服务端代发那一刻,OA 这个还开着的发起页是全场唯一不知道的人:started 那一句原本只挂在 launch 的 refresh 那一路,而刷新是"人改了格子"才跑的——人停手之后第三方才点他们那句 确认,这一屏就永远停在"还没发起"的样子。生产上问的就是这一句:

"第三方发起后,OA 的前端没有变化,让人误以为没有发起流程。"

于是给界面单开一条只问一句话的接口:POST /embed/state,带 code + field + prekey,回 {started, found}。发起页每 20 秒问一次,切回这一屏与重新装载那一刻各问一次 (去报销系统点完确认再切回来,那一刻就该看见结果)。三条分寸:

  • 轻。它只查一趟的归属:不重算地址(url_mode=api 那条源每次都得外呼对方接口一次)、 不发短码、不记"他打开了那个页面"的留痕。把 launch 的轮询调密是同样能做到的实现, 代价是每 20 秒打一次对方接口 + 把台账里那一句"打开过"刷成几十条;
  • 认趟有两条来路。账上有 claim_job(第三方拿预受理号发起、或人在 OA 自己发起)就照账念; 账上是空的,再看这一趟占下的那个正式号是不是已经落在一张单上——生产上他们是拿号发起的、 bizKey 填自己那套流水号,那条路根本不会写 claim_job。号只有一个主人,按号认不算猜。 少了第二条,这条通道只对"肯把预受理号当 bizKey 用"的那一类对接方成立;
  • 只读。这一句是轮询,不该每 20 秒为一句话写一次库;"这一趟留下了东西,别删对面那页" 那一道判据本来就自己按号看过一次(_abandon_skip)。

界面那一头跟着改了一条:那句提示可以关掉,但关掉不等于这一趟没成单。原来「关闭」把 embedStarted 整个置空,收起来的那颗「发起」当场复活——屏幕上刚读完"已经发起成一张单了", 转脸又能点一次发起。现在事实留在 embedStarted(那颗钮归它管),话留在 embedStartedNote(可以不说)。判据:frontend/src/views/oa/StartFormView.spec.ts、 frontend/src/components/oa/EmbedFrame.started.spec.ts、 backend/scripts/check_embed_api.py 那段「这一趟发起出去了没有」。

4.5 挂在单据上开出来的那一屏,问的是另一句(同一个接口的第二问)

第 4.4 节那一句「这一趟变成单了没」只在发起页问得出来。会话一旦挂在一张已有的单上, 那一句根本不成其为问题——_started_of 直接回 null,问一百次也是那句"没这回事"。 可"点了没反应"在生产上还有第二种来路,而且比第一种更常见:

"费用报销撤回之后,点了嵌入页面里的提交,页面没刷新,我以为没提交成功。"

这一屏等的不是"成单",是我打开的那一环、我手上那条待办动过了没。同一条轮询因此一并 答第二问:moved 加一份 state({job, activity, status, task_open},只为对答得出 "凭什么这一屏自己刷新了")。判据三条,成立任何一条都算动了——每一条都对应一颗已经没意义 的按钮:单据落定、走去了别的环节、那条待办不再挂在待办表里(谁办的都算,会签凑够数也算)。

一条容易写错的:停在开始环节而手上没有待办的那些趟(第三方接管开始环节建的那一单, hold_at_begin)不能因为"查不到那条待办"就被判成已经动了——那一档压根没有待办可问, 只能按环节判。写错的样子是每次点开都白刷一次,而没人说得出为什么。并行分支上 work.activity 是逗号串,认自己那一环要用成员判断,不能拿整串相等。

前端那一头的分寸:

  • 只在对方说话之后按 PROBE_SOON_MS 那几拍问(400 / 1200 / 3000 毫秒),不给单据那一屏 开一条 20 秒的长轮询——那一屏可能一直开着,而"人不在这一屏"根本不该问;
  • 后端说动了才刷新,不是听见对方说话就刷新:oa:ready 只说"页面自己刷了一下",拿它 当凭据会让每一次打开都白重取整屏。只有对方明说 oa:submitted 才允许在答不出 moved 的旧后端那一档兜一次——宁可多刷一下,也不退回那种点了像坏了的静默;
  • 报一次就停,剩下的归上面那一层:待办那一屏重取之后显示的是后端认出来的那个下场 (vanished),比守着一张办不动的表单诚实。

判据收在 work_moved 这一个纯函数里(不碰库),所以 backend/scripts/check_embed_moved.py 那十三条不需要数据库就能跑;真表那几条要库,连不上时脚本自己说清跳过了什么,不把环境 问题报成判据错。

5. 安全边界:哪些是闸,哪些是界面效果

位置 是什么 少了它会怎样
oa:action 必须带 nonce 证明说话的是我刚装载的那个 frame 页面上任何一段脚本都能请 OA 发起单子
actions 由后端给 界面按钮的存在与否 前端自己读一遍表单配置 = 两套判据,"有按钮但后端说没权限"
scopes 由后端算并存在会话上 回写时照着这张清单判 调用方申报什么就信什么
prefill 白名单在入库之前筛 不在清单里的一条都不写 等前端去筛不是闸,是装饰
挂额度 / 阈值的格子一律不收 外部系统只能提供值,不能决定流转 别人家的一个数改掉了 OA 的审批走向
decide 走 engine.execute_task 引擎的全部校验照跑 开第二条办理通路,权限形同虚设
出口必须精确命中这一环真实存在的那条:只给方向时按最长匹配匹,匹不唯一就不猜、回候选 流程图一改就当场报错,而不是静默走错分支 第三方维护一份流程图抄本,图一改就走错
失败只给一句笼统话 这接口不该成为"某把令牌存不存在"的探针 令牌枚举
留痕只记字段名和数量,不记值 与"打开页面"那条留痕同一条规矩 审批数据散进日志

回写通道的鉴权用注册表上那条应用密钥(和验票同一把),不发开放平台那套应用令牌: 对方为了免登已经配过一次密钥,再来一套 app_key/app_secret 只会两边各记一份、各漂一份。 代价是这把钥匙只绑这一趟、几小时就废——比一把能发起任意单据的长期令牌小得多,正合适。 要长期、批量、跨系统的集成,走的是 POST /open/works / POST /open/tasks/{id}/execute 那条开放平台的路(见 platform-open-api-design.md)。

config.dev.toml 里 [embed] 那一段管两件事的存活期,都有界:

[embed]
# session_ttl = 7200        # 嵌入会话存活秒数(OA_EMBED_SESSION_TTL,300~86400)
# callback_dedupe = 300     # 同一趟两次回写之间的静默期,0 = 不压(OA_EMBED_CALLBACK_DEDUPE)

callback_dedupe 只用来压重试风暴,不承担正确性:正确性由引擎那条待办负责, 办过第二次自然被挡并回"已由谁办掉"。这一档只是别让人对着超时重试连打二十次、留二十行一样的痕。

6. 验收

  • scripts/check_embed.py —— 纯函数口径(不连库):动作清单、能力档位、出口匹名三段的 判据与前端逐字对齐;
  • scripts/check_embed_api.py —— 连真库真服务,段名「这一趟的凭据与那三档回写」: 预受理号复用、令牌只从验票响应出去、白名单为空时全拒、没开放的档位必挡、 start 之后重新打开仍认同一趟、staged 两条投递路径都带回;
  • scripts/check_embed_decide.py —— 跑一张真流程验第 4.3 节那一条:发起真单据 → 按那个人手上那条真待办开一趟会话 → 拿会话令牌调回写 → 看引擎那本账(待办进没进已办、 办理人是不是他本人、出口是不是这一环真实存在的那一条、第二次回写是不是 200 + already)。 上面那两段只能验到"该挡的挡住了",这一条才验到"该成的真成了"。它跑完连自己造的 源、会话、单据一起删干净;
  • frontend/src/utils/embedAction.spec.ts + embedBridge.spec.ts —— nonce 校验、 动作必须在开放清单内、values 过白名单;
  • frontend/src/components/oa/FormRenderer.embed.spec.ts —— 值落坏就不往上抛;
  • scripts/check_embed_moved.py —— 第 4.5 节那第二问的判据,不连库跑那十三条(判据收在 纯函数 work_moved 里就是为了这一条);真表那几条要库,连不上会明说跳过了什么;
  • frontend/src/components/oa/EmbedFrame.action.spec.ts —— 装载 → 握手 → 回话这一整条通道: 开放清单必须交进解析器,否则每一条 oa:action 都被当没听见,而三个页面全都毫无反应。 这一条曾经零覆盖:解析函数测得足,把清单交给它的那一步没人测,所以测试全绿而线上失灵;
  • frontend/src/components/oa/EmbedFrame.moved.spec.ts —— 单据那一屏的那几拍:动了才报、 没动不报、只报一次、旧后端那一次兜底;
  • frontend/src/components/oa/FormRenderer.embedAction.spec.ts —— 页签里那一页被挡下的值 落不回自己那一格时,得把那一页翻到屏幕上并把原因喊出来,不能静默吞掉;
  • frontend/src/components/oa/mobile/MobileTaskView.embed.spec.ts 与 .embedRoutes.spec.ts、 frontend/src/views/oa/WorkDetailView.embedSubmit.spec.ts、 frontend/src/views/oa/TaskDetailView.embedSubmit.spec.ts —— 桌面与手机同一份判据 (composables/useEmbedDecide.ts):两个词怎么算、出口匹名、要不要问那一句、不归他办 怎么说,都在那一份里。两边各写一遍的结局就是"电脑上能提交、手机上点了没反应"。

check_embed_api.py 的 sweep() 会连 oa_embed_session 一起删。这一条不能省: 它是这段验收里唯一会被反复复用的表,留着上一趟那几条,下一趟就会认到旧预受理号上, "两次打开是不是同一趟"那条断言就此变成永远为真的空话。

7. 已知边界

  • 前端那条 oa:action 会真的办下去,但按下确认键的必须是人(配表的人能关掉这一问, 默认开着)。第三方只能提出"要办哪件事、带上哪几格",它自己按不动那颗钮;要全自动, 请走服务端 kind=decide;
  • 回写以"打开这一页的那个人"身份办。第三方想以另一个人的名义办,用开放平台的 POST /open/tasks/{id}/execute 并显式带 identity,这条通道不开这个口子;
  • 会话到期就是到期。第三方那边如果是一个跨天的审批,请走开放平台那条长期凭据的路, 不要指望这里把 TTL 调到很大——它绑的是"这一趟打开",不是一个集成账号。