docs: auto is always async (confirm returns executing, SSE terminal); persist te…

…rminal + reconcile on reconnect; manual stays sync

docs: auto is always async (confirm returns executing, SSE terminal); persist te…
…rminal + reconcile on reconnect; manual stays sync
zichun
1 parent ef712cb9
Showing 1 changed file with 4 additions and 2 deletions
docs/agent-architecture.md
@@ -136,14 +136,16 @@ ai_op_queue(
 ```
 `sOpType + sTargetBillId + sPayload` 统一覆盖所有写。报价=generate/quote+auto；审核=examine+目标id；改删=update/delete+目标id+payload。
  
-**卡片三态状态机**：`处理中` / `待处理`(manual 终态) / `已完成·失败(重试)`(auto 终态)。用户点确认 → `/op/{sId}/confirm` → 卡片=**处理中**（不阻塞聊天，LLM 已停，仅此卡片转圈）。前端从响应（快=同步）或 SSE 推送（慢=异步）拿终态渲染，不过 LLM。
+**卡片三态状态机**：`处理中` / `待处理`(manual 终态) / `已完成·失败(重试)`(auto 终态)。用户点确认 → `/op/{sId}/confirm` → 卡片=**处理中**（不阻塞聊天，LLM 已停，仅此卡片转圈）。终态渲染由**前端**从响应或 SSE 推送拿，不过 LLM。
  
-**auto 流程**（报价）：confirm → ERP 检查暂存并**在一个事务里执行**该行 → 回响应含 `billId+link`（或 `failed+errorMsg`）→ 卡片渲染 `✅已生成[查看]` 或 `❌失败[重试]`，结果写会话。链接打开=**已建好的单据**。
+**auto 流程恒异步**（报价）：confirm → **立即回 `executing`**（卡片=处理中，永不 HTTP 死等）→ ERP 检查暂存并**在一个事务里执行**该行 → **终态经 SSE 推送**（`executed+billId+link` 或 `failed+errorMsg`）→ 卡片渲染 `✅已生成[查看]` 或 `❌失败[重试]`，结果写会话。链接打开=**已建好的单据**。
 - ⚠️ **原子**：execStaging 必须事务化，半途失败**自动回滚**，重试才安全。
 - ⚠️ **幂等**：重试仅当 `status=failed`；`sId` 作幂等键，防"执行成功但响应丢失→重试→重复建单"。
+- ⚠️ **终态落库 + 重连对账**：终态必写 `ai_op_queue.status/result`（SSE 只是实时推、非唯一真相）；前端重连/刷新用 `GET /op/{sId}/status`（或"我的近期 op"）对账，防跳变发生在断线时丢失。
  
 **manual 流程**（新增/改/删/审核）：confirm → ERP 只**校验暂存存在且有效**（失败/过期→失败卡片）→ 回 `link`（不执行）→ 卡片渲染 `待处理[去ERP操作]`。**xlyAi 到此终止，此卡片不再更新、ERP 不再回响应。** 链接打开=**字段已预填/预改的原生单据**，用户手动点 保存/审核/作废 才真正落库。
 - ⚠️ **代价**：xlyAi 拿不到最终单据 id、不知用户是否完成 → **跨 manual 写不能链式**（终态交接）。auto 写可链式。将来要 manual 链式需 ERP 完成回调。
+- manual 校验快，`/op/confirm` 可**同步**回链接直接进"待处理"（auto 才恒异步）。
 - **两种链接**：`bAutoExecute=1`（报价）→ ERP 立即执行 → 链接 `/form/{formId}?bill={sResultBillId}` **打开建好的单据**；`bAutoExecute=0`（新增/大多数）→ ERP 只校验+备预填 → 链接 `/form/{formId}?staging={sId}` **打开预填表单，用户点提交/保存**（走 addBusinessData 才真正写）。
 - **ERP 侧要新建**：① 预填加载 `/form/{formId}?staging={sId}`；② 执行端点 `/ai/execStaging/{sId}`；③ status/result 回写；④「我的 AI 待办」入口。
 - **需处理**：幂等（重复确认）、过期、确认前底层数据变化、状态机、失败回执、审计。