DataOps-platform/docs/architecture/ADR-003-cross-store-consistency.md

ADR-003：跨存储最终一致性

• 状态：Accepted
• 日期：2026-07-16

背景

平台同时写 PostgreSQL、Neo4j、MinIO 和 n8n。当前部分请求在一个路由内顺序调用多个系统，失败后可能留下半完成状态，也缺少统一重试和对账证据。

决策

1. PostgreSQL 是业务命令状态、映射和一致性事件的协调源；不尝试跨四个系统实现分布式 ACID。
2. 在同一 PostgreSQL 事务写业务记录与 outbox_events。后台消费者按 event_id 幂等地更新 Neo4j、MinIO 索引、n8n 或知识库。
3. 每个外部写入使用稳定业务 UUID 和幂等键；不使用 Neo4j 内部节点 ID 作为跨系统长期主键。
4. 消费失败采用有上限的指数退避，超过阈值进入 dead-letter 状态并暴露管理告警。
5. 数据治理知识库使用“治理对象变更后增量同步 + 每日全量一致性巡检”。全量巡检比较版本号和内容哈希，只修复差异对象。
6. DataFlow/n8n 激活采用状态机和补偿动作；不能补偿时标记人工处理，禁止返回伪成功。

一致性等级

数据	源真相	目标一致性
用户、角色、布局、版本映射	PostgreSQL	强一致事务
治理对象与血缘	Neo4j	命令落库后秒级最终一致
知识库文档与向量	PostgreSQL/pgvector	增量秒至分钟级；每日校验
附件原件	MinIO	上传完成后再发布可见状态
Workflow 执行与激活	n8n	状态机协调和定期对账

可观测性和验收

• 每个跨存储操作贯穿 correlation_id、event_id、对象 UID 和操作者。
• 指标至少包含 outbox backlog、失败次数、同步延迟、知识库差异数、n8n 激活不一致数。
• 集成测试必须覆盖 PostgreSQL 成功但下游失败、重复投递、消费者重启、补偿失败和每日巡检修复。

结果

用户可看到明确的处理中/失败状态，运维可以重放和对账；系统不再依赖一次 HTTP 请求把全部存储恰好写成功。