# 集成边界冻结（P19 / P19+IM-1）

**快照日期**：2026-03-08  
**当前基线**：`P19+IM-1` 已完成，当前运行时已落地企微群机器人 + 深链 + Outbox 异步派发的一期协同适配。  
**目标**：在保持核心域稳定的前提下，冻结 ERP / IM / AI / MCP 的长期边界，并记录 IM 一期的已实现范围与后续禁入规则。

## 1. 总体原则

### 1.1 只通过边界集成
- 外部系统只允许通过两种方式接入：
  - 领域事件 / Outbox 异步投递
  - 显式 API 适配层
- 禁止外部系统直写核心业务表。
- 禁止为了对接外部系统，在核心事务表中提前加入 ERP 私有字段、IM 私有字段或 AI 中间状态字段。

### 1.2 核心域优先
- `purchase_request`、`asset_card`、`inventory_check` 等领域模型继续由业务服务自身维护。
- 集成层只能消费既有领域事实，不能反向篡改领域判定逻辑。
- 若未来需要双向同步，必须先定义系统主责方（source of truth），再设计幂等回写接口。

### 1.3 回滚优先
- 所有集成必须支持“关闭适配器后核心域仍可独立运行”。
- 外部调用失败只能影响外围联动，不得阻断核心单据保存、审批和查询。
- 对外推送必须具备可重试、可补偿、可审计能力。

## 2. ERP / 财务适配边界

### 2.1 允许进入适配层的对象
- 主数据：`LegalEntity`、`CostCenter`、`Supplier`
- 采购：`purchase_request` 审批结果、预算占用确认结果、PO / 合同归档摘要
- 资产：`asset_card` 基础卡片信息、归属变更摘要、盘点完成摘要

### 2.2 推荐适配方式
- **主数据同步**：
  - 由 `hyb-oa` 输出标准化读模型或事件
  - ERP 适配器负责字段映射与批量 / 增量同步
- **财务凭证 / 单据接口**：
  - 先生成中间格式（JSON / CSV / 显式 API payload）
  - 再由独立适配器调用外部 ERP
- **失败处理**：
  - 在适配层重试
  - 失败记录在适配层日志 / Outbox 中，不回写核心事务状态为“失败”

### 2.3 明确禁止事项
- 禁止在 `PurchaseRequest`、`AssetCard`、`BudgetPool` 等核心表中直接加入 ERP 专有主键、分录号、凭证表字段。
- 禁止应用直接连写 ERP 主表。
- 禁止把 ERP 状态机复制到 `hyb-oa` 核心路由中。

### 2.4 建议后续专项
- `P19+ERP-1`：主数据同步协议
- `P19+ERP-2`：采购审批结果导出 / 回写协议
- `P19+ERP-3`：资产台账摘要导出协议

## 3. IM / 协同适配边界

### 3.1 一期已实现能力（P19+IM-1）
- 已复用 `IntegrationOutbox` 与派发作业，实现 `notification.im` 异步派发。
- 已新增 `NotificationChannel` 的创建 / 更新 / 列表 / 测试接口与后台页面。
- 已接入企微群机器人两种模式：
  - `mock`
  - `wecom_webhook`
- 已支持三维路由过滤：
  - `roleCodes`
  - `domainScopes`
  - `allowedTypes`
- 已支持 `APP_ORIGIN + targetPath` 生成深链；缺少 `APP_ORIGIN` 时允许发送但不阻断业务。
- 站内通知、邮件、IM 三通道并存；业务事务内只负责写通知与 Outbox，真正派发在作业中完成。

### 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 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 只做建议，不直接写库。
- AI 输出必须允许人工复核和拒绝。
- 任何模型调用都不得绕过现有权限校验。
- 若未来接入外部大模型，必须先明确脱敏策略与日志留存边界。

### 4.3 禁止事项
- 禁止 AI 自动创建、审批、归档业务单据。
- 禁止 AI 直接修改预算、工作流、资产归属等核心状态。

## 5. 事件与通知交付规范

### 5.1 事件最小结构
后续若继续扩展领域事件 / Outbox，建议统一包含：
- `eventName`
- `eventId`
- `occurredAt`
- `actorId`
- `entityType`
- `entityId`
- `payloadVersion`
- `payload`

### 5.2 幂等要求
- 同一 `eventId` 必须可安全重放。
- 消费端必须以 `eventId` 或 `entityId + status / version` 方式做幂等。
- 不允许消费端以“收到多次事件”为理由修改核心业务状态。

### 5.3 当前 IM 一期实现说明
- 运行时仍以通知类型驱动 IM 入队，而不是直接暴露新的领域事件名。
- `notification.im` 的 `dedupeKey` 固定为：
  - `${notificationType}:${targetType}:${targetId || targetPath}:${channelId}`
- IM 失败仅影响 Outbox 状态，不回滚业务事务。

## 6. MCP 基线

### 6.1 当前结论
- `P19+IM-1` 阶段 **不启用 MCP**。
- 当前仓库中 **仍不创建** `docs/mcp-tools.md`，因为尚未进入真实 MCP 使用场景。

### 6.2 首次启用前置条件
若未来需要启用 MCP，固定顺序如下：
1. 明确真实用途（数据库只读排障、GitHub PR / Issue / CI 协作等）
2. 新增 `docs/mcp-tools.md`
3. 使用 `mcp-tools-catalog` 生成工具目录
4. 在执行合同中记录启用原因、风险与禁用边界

### 6.3 允许的 MCP 范围
- `postgres MCP`：只读排障、迁移核对、账本核对
- `github MCP`：PR / Issue / CI 协作

### 6.4 禁止事项
- 禁止在没有 `docs/mcp-tools.md` 的前提下默认启用 MCP。
- 禁止用 MCP 绕过仓库内已存在的本地验证命令。
- 禁止将 MCP 用作写生产数据的通道。

## 7. 当前阶段明确不做
- 不新增新的集成总线表结构
- 不接入 ERP 真实写回逻辑
- 不接入飞书 / 钉钉真实生产推送
- 不新增 AI 写库动作
- 不引入绕过工作流与权限体系的外部回调路径