docs/test(P19IM1-5,P19IM1-6): 收口IM协同文档矩阵与回归

docs/integration-boundaries.md

@@ -1,25 +1,25 @@
-# 集成边界冻结（P19）
+# 集成边界冻结（P19 / P19+IM-1）
 
-**快照日期**：2026-03-07  
-**当前基线**：`P18B` 已完成并进入 `docs/feature-matrix.md`。  
-**目标**：冻结 `hyb-oa` 在 ERP/财务、IM/协同、AI 与 MCP 使用上的边界，作为后续专项实施的约束，不直接引入任何运行时代码。
+**快照日期**：2026-03-08  
+**当前基线**：`P19+IM-1` 已完成，当前运行时已落地企微群机器人 + 深链 + Outbox 异步派发的一期协同适配。  
+**目标**：在保持核心域稳定的前提下，冻结 ERP / IM / AI / MCP 的长期边界，并记录 IM 一期的已实现范围与后续禁入规则。
 
 ## 1. 总体原则
 
 ### 1.1 只通过边界集成
-- 外部系统只允许通过两种形式接入：
-  - 领域事件（推荐，后续可落到 Outbox）
+- 外部系统只允许通过两种方式接入：
+  - 领域事件 / Outbox 异步投递
   - 显式 API 适配层
 - 禁止外部系统直写核心业务表。
 - 禁止为了对接外部系统，在核心事务表中提前加入 ERP 私有字段、IM 私有字段或 AI 中间状态字段。
 
 ### 1.2 核心域优先
-- `purchase_request`、`asset_card`、`inventory_check` 等领域模型继续由业务服务自己维护。
+- `purchase_request`、`asset_card`、`inventory_check` 等领域模型继续由业务服务自身维护。
 - 集成层只能消费既有领域事实，不能反向篡改领域判定逻辑。
-- 若未来需要双向同步，必须先定义“系统主责方（source of truth）”，再设计幂等回写接口。
+- 若未来需要双向同步，必须先定义系统主责方（source of truth），再设计幂等回写接口。
 
 ### 1.3 回滚优先
-- 所有未来集成必须支持“关闭适配器后核心域仍可独立运行”。
+- 所有集成必须支持“关闭适配器后核心域仍可独立运行”。
 - 外部调用失败只能影响外围联动，不得阻断核心单据保存、审批和查询。
 - 对外推送必须具备可重试、可补偿、可审计能力。
 
@@ -27,54 +27,79 @@
 
 ### 2.1 允许进入适配层的对象
 - 主数据：`LegalEntity`、`CostCenter`、`Supplier`
-- 采购：`purchase_request` 的审批结果、预算占用确认结果、PO/合同归档摘要
+- 采购：`purchase_request` 审批结果、预算占用确认结果、PO / 合同归档摘要
 - 资产：`asset_card` 基础卡片信息、归属变更摘要、盘点完成摘要
 
 ### 2.2 推荐适配方式
 - **主数据同步**：
   - 由 `hyb-oa` 输出标准化读模型或事件
-  - ERP 适配器负责字段映射与批量/增量同步
-- **财务凭证/单据接口**：
-  - 先生成中间格式（例如 JSON/CSV/显式 API payload）
+  - ERP 适配器负责字段映射与批量 / 增量同步
+- **财务凭证 / 单据接口**：
+  - 先生成中间格式（JSON / CSV / 显式 API payload）
   - 再由独立适配器调用外部 ERP
 - **失败处理**：
   - 在适配层重试
-  - 失败记录在适配层日志/事件投递表，不回写核心事务状态为“失败”
+  - 失败记录在适配层日志 / Outbox 中，不回写核心事务状态为“失败”
 
 ### 2.3 明确禁止事项
 - 禁止在 `PurchaseRequest`、`AssetCard`、`BudgetPool` 等核心表中直接加入 ERP 专有主键、分录号、凭证表字段。
 - 禁止应用直接连写 ERP 主表。
 - 禁止把 ERP 状态机复制到 `hyb-oa` 核心路由中。
 
-### 2.4 建议的后续专项
+### 2.4 建议后续专项
 - `P19+ERP-1`：主数据同步协议
-- `P19+ERP-2`：采购审批结果导出/回写协议
+- `P19+ERP-2`：采购审批结果导出 / 回写协议
 - `P19+ERP-3`：资产台账摘要导出协议
 
 ## 3. IM / 协同适配边界
 
-### 3.1 允许能力
-- 飞书 / 企微消息通知
-- 待办提醒
-- 深链跳转（例如采购审批详情、资产盘点详情）
-- 审批摘要的只读推送
+### 3.1 一期已实现能力（P19+IM-1）
+- 已复用 `IntegrationOutbox` 与派发作业，实现 `notification.im` 异步派发。
+- 已新增 `NotificationChannel` 的创建 / 更新 / 列表 / 测试接口与后台页面。
+- 已接入企微群机器人两种模式：
+  - `mock`
+  - `wecom_webhook`
+- 已支持三维路由过滤：
+  - `roleCodes`
+  - `domainScopes`
+  - `allowedTypes`
+- 已支持 `APP_ORIGIN + targetPath` 生成深链；缺少 `APP_ORIGIN` 时允许发送但不阻断业务。
+- 站内通知、邮件、IM 三通道并存；业务事务内只负责写通知与 Outbox，真正派发在作业中完成。
 
-### 3.2 边界约束
-- IM 适配器只消费领域事件，不直接读取或修改数据库。
-- IM 适配器可以构造消息文案、跳转链接、卡片摘要，但不能替代工作流审批判定。
-- 任何“点击消息即审批”的能力，必须仍然回到 `hyb-oa` 的鉴权与工作流接口执行。
+### 3.2 一期明确覆盖范围
+- 待办类：`workflow.task_assigned`
+- 报销结果：`reimbursement.approved / rejected / returned / paid`
+- 请假结果：`leave.approved / rejected`
+- 采购结果：`purchase_request.approved / rejected`
+- 资产流转：`asset.assigned / returned / transferred`
+- 盘点结果：`inventory_check.completed`
 
-### 3.3 禁止事项
-- 禁止把 IM 用户标识写入核心审批流状态字段。
-- 禁止在 IM 侧持久化领域真相状态并反向覆盖业务库。
+### 3.3 一期明确不做
+- 飞书、钉钉真实适配器
+- 员工 IM OpenID / UserID / UnionID 主数据
+- 点对点个人消息
+- IM 卡片回调审批
+- 新的 Outbox 表或消息总线
+- 默认全员广播频道
+
+### 3.4 运行时回滚策略
+- 设置 `IM_NOTIFIER_ENABLED=false`
+- 在管理页中禁用全部通知渠道
+- 保留 `integration_outbox` 历史记录，不回删
+- 即使 IM 全部关闭，站内通知与邮件仍继续工作
+
+### 3.5 后续专项建议
+- `P19+IM-2`：飞书 / 钉钉适配器
+- `P19+IM-3`：个人直达与 IM 身份映射
+- `P19+IM-4`：消息卡片交互与回调审批（仍必须回到 OA 鉴权）
 
 ## 4. AI 增强边界
 
 ### 4.1 允许能力
 - 审批摘要生成
-- 采购/资产异常提示
+- 采购 / 资产异常提示
 - 主数据重名与重复建议
-- 文档/制度/流程问答检索
+- 文档 / 制度 / 流程问答检索
 
 ### 4.2 强制约束
 - AI 只做建议，不直接写库。
@@ -86,10 +111,10 @@
 - 禁止 AI 自动创建、审批、归档业务单据。
 - 禁止 AI 直接修改预算、工作流、资产归属等核心状态。
 
-## 5. 领域事件交付规范
+## 5. 事件与通知交付规范
 
 ### 5.1 事件最小结构
-后续若引入事件投递，建议统一包含：
+后续若继续扩展领域事件 / Outbox，建议统一包含：
 - `eventName`
 - `eventId`
 - `occurredAt`
@@ -101,18 +126,24 @@
 
 ### 5.2 幂等要求
 - 同一 `eventId` 必须可安全重放。
-- 消费端必须以 `eventId` 或 `entityId + status/version` 方式做幂等。
+- 消费端必须以 `eventId` 或 `entityId + status / version` 方式做幂等。
 - 不允许消费端以“收到多次事件”为理由修改核心业务状态。
 
+### 5.3 当前 IM 一期实现说明
+- 运行时仍以通知类型驱动 IM 入队，而不是直接暴露新的领域事件名。
+- `notification.im` 的 `dedupeKey` 固定为：
+  - `${notificationType}:${targetType}:${targetId || targetPath}:${channelId}`
+- IM 失败仅影响 Outbox 状态，不回滚业务事务。
+
 ## 6. MCP 基线
 
 ### 6.1 当前结论
-- `P19` 阶段 **不启用 MCP**。
-- 当前仓库中 **不创建** `docs/mcp-tools.md`，因为尚未进入实际 MCP 使用场景。
+- `P19+IM-1` 阶段 **不启用 MCP**。
+- 当前仓库中 **仍不创建** `docs/mcp-tools.md`，因为尚未进入真实 MCP 使用场景。
 
 ### 6.2 首次启用前置条件
 若未来需要启用 MCP，固定顺序如下：
-1. 明确真实用途（数据库只读排障、GitHub PR/Issue/CI 协作等）
+1. 明确真实用途（数据库只读排障、GitHub PR / Issue / CI 协作等）
 2. 新增 `docs/mcp-tools.md`
 3. 使用 `mcp-tools-catalog` 生成工具目录
 4. 在执行合同中记录启用原因、风险与禁用边界
@@ -122,17 +153,13 @@
 - `github MCP`：PR / Issue / CI 协作
 
 ### 6.4 禁止事项
-- 禁止在没有 `docs/mcp-tools.md` 的前提下默认启用 MCP
-- 禁止用 MCP 绕过仓库内已存在的本地验证命令
-- 禁止将 MCP 用作写生产数据的通道
+- 禁止在没有 `docs/mcp-tools.md` 的前提下默认启用 MCP。
+- 禁止用 MCP 绕过仓库内已存在的本地验证命令。
+- 禁止将 MCP 用作写生产数据的通道。
 
-## 7. 本阶段明确不做
-- 不实现 Outbox 表
-- 不新增对外 webhook
-- 不接入 ERP、飞书、企微或大模型 SDK
-- 不修改任何路由、Prisma 模型、前端页面和工作流逻辑
-
-## 8. 下一步专项建议
-- 若优先打通 ERP，请先开“主数据同步协议”专项
-- 若优先做协同体验，请先开“IM 待办通知”专项
-- 若优先做智能化，请先开“审批摘要与异常提示”专项
+## 7. 当前阶段明确不做
+- 不新增新的集成总线表结构
+- 不接入 ERP 真实写回逻辑
+- 不接入飞书 / 钉钉真实生产推送
+- 不新增 AI 写库动作
+- 不引入绕过工作流与权限体系的外部回调路径