docs: generalize staging into ai_write_queue (op-type/target/payload/status/resu…

…lt); ERP real-time exec via /ai/execStaging + two link modes

docs: generalize staging into ai_write_queue (op-type/target/payload/status/resu…
…lt); ERP real-time exec via /ai/execStaging + two link modes
zichun
1 parent c738b42d
Showing 1 changed file with 22 additions and 5 deletions
docs/agent-architecture.md
@@ -111,11 +111,28 @@
 **通用双确认流（copyto）**：① 对话内 diff + 确认按钮 → ② `ProposeWrite` 落暂存 `sp_ai_addcommonwx` + 返回 ERP 链接 → ③ 用户进 ERP 原生表单（预填）再确认 → ④ **ERP 暂存执行器**排空并执行真实写入。
-- **现状缺口**：`sp_ai_addcommonwx` 现在**没有任何消费者**（`Sp_Ai_AddCommonAfterNew` 只入队从不执行）→ **④ 执行器是必须新建的 ERP 侧组件，最重、跨团队。**
-- **统一**：报价也走此路（废 `Sp_Ai_AddQuoQuoAfter` 直连），全链一致。
-- **暂存记录（在现有列基础上扩展）**：`{sId, createdBy(用户), targetFormId, targetModuleId, op(new/copyto), payload(JSON), sourceRef, status(draft→staged→confirmed→executed/failed), link, expireAt, tCreate}`。
-- **需处理**：幂等（重复确认）、过期、确认前底层数据变化、状态机、失败回执。
-- **前端**：ERP 需一个「我的 AI 待办」入口 + 深链路由（`stagingRef` → 打开对应表单并预填）。
+- **现状缺口**：现有 `sp_ai_addcommonwx`（239 行）**完全只为"生成下游单据"设计**（字段全是 源→目标 + 合并/分单模式），且**没有消费者**（`Sp_Ai_AddCommonAfterNew` 只入队从不执行）。缺 op 类型/目标记录id/payload/**用户·租户**/status/结果/自动标志/过期 → **覆盖不了 增/改/删/审核**。
+
+**⇒ 新建通用暂存表 `ai_write_queue`**（旧表留给存量或迁移）：
+```
+ai_write_queue(
+  sId PK/深链token, sUserId, sBrandsId, sSubsidiaryId,
+  sOpType,             -- create|update|delete|examine|generate
+  sTargetFormId, sTargetModuleId, sTargetTable,
+  sTargetBillId,       -- update/delete/examine 用; create/generate 空
+  sPayload JSON,       -- 列→值(create/update) 或 动作参数(examine)
+  sSourceRef JSON,     -- generate: 源表单+选中 sSlaveId 集
+  bAutoExecute,        -- ERP 自动执行 or 等用户提交
+  sStatus,             -- draft|confirmed|executing|executed|failed|expired
+  sResultBillId, sResultMsg, sErrorMsg,
+  tCreateDate, tConfirmDate, tExecutedDate, tExpireAt)
+```
+`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）。
+- **两种链接**：`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 待办」入口。
+- **需处理**：幂等（重复确认）、过期、确认前底层数据变化、状态机、失败回执、审计。
 ## 11. KG 集成