docs: card 3-state machine; auto flow atomic+idempotent w/ rollback; manual flow…

… terminal (no chaining), validate-only

docs: card 3-state machine; auto flow atomic+idempotent w/ rollback; manual flow…
… terminal (no chaining), validate-only
zichun
1 parent b09b1aa7
Showing 1 changed file with 8 additions and 1 deletions
docs/agent-architecture.md
@@ -136,7 +136,14 @@ ai_op_queue(
 ```
 `sOpType + sTargetBillId + sPayload` 统一覆盖所有写。报价=generate/quote+auto；审核=examine+目标id；改删=update/delete+目标id+payload。
  
-**ERP 实时处理（推模式，推荐）**：xlyAi 落暂存(confirmed) → 同步调 **`POST /ai/execStaging/{sId}`**（带 token）→ ERP 按 `bAutoExecute` 分叉，回写 status/result → xlyAi 拿结果给链接。慢操作转异步（先 executing，xlyAi 轮询/ERP 回调到 executed）。
+**卡片三态状态机**：`处理中` / `待处理`(manual 终态) / `已完成·失败(重试)`(auto 终态)。用户点确认 → `/op/{sId}/confirm` → 卡片=**处理中**（不阻塞聊天，LLM 已停，仅此卡片转圈）。前端从响应（快=同步）或 SSE 推送（慢=异步）拿终态渲染，不过 LLM。
+
+**auto 流程**（报价）：confirm → ERP 检查暂存并**在一个事务里执行**该行 → 回响应含 `billId+link`（或 `failed+errorMsg`）→ 卡片渲染 `✅已生成[查看]` 或 `❌失败[重试]`，结果写会话。链接打开=**已建好的单据**。
+- ⚠️ **原子**：execStaging 必须事务化，半途失败**自动回滚**，重试才安全。
+- ⚠️ **幂等**：重试仅当 `status=failed`；`sId` 作幂等键，防"执行成功但响应丢失→重试→重复建单"。
+
+**manual 流程**（新增/改/删/审核）：confirm → ERP 只**校验暂存存在且有效**（失败/过期→失败卡片）→ 回 `link`（不执行）→ 卡片渲染 `待处理[去ERP操作]`。**xlyAi 到此终止，此卡片不再更新、ERP 不再回响应。** 链接打开=**字段已预填/预改的原生单据**，用户手动点 保存/审核/作废 才真正落库。
+- ⚠️ **代价**：xlyAi 拿不到最终单据 id、不知用户是否完成 → **跨 manual 写不能链式**（终态交接）。auto 写可链式。将来要 manual 链式需 ERP 完成回调。
 - **两种链接**：`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 待办」入口。
 - **需处理**：幂等（重复确认）、过期、确认前底层数据变化、状态机、失败回执、审计。