ADR-002：DataFlow 与 n8n Workflow 的职责和版本映射

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

背景

代码中 DataFlow、Workflow 和旧数据工厂命名曾混用。产品确认 n8n 必须保留，旧数据工厂模块可以移除；一个 DataFlow 可以有多个 Workflow 版本，并需区分环境和生效版本。

决策

DataFlow 是平台治理概念：描述数据业务流向、输入输出业务域、责任人和治理状态。
n8n Workflow 是执行引擎原生概念：保存可执行节点、凭据引用和执行记录。保留 Workflow 命名，不进行全局重命名。
PostgreSQL 新增版本映射表，将稳定 dataflow_uid 映射到 n8n_workflow_id、version_no 和 environment。
一个 DataFlow 可有多个 n8n Workflow 版本；同一环境只允许一个当前生效版本。
激活操作由平台后端串行执行：锁定映射、停用旧版本、调用 n8n 激活目标、写入状态和 outbox。失败时保留可重试状态，不直接篡改 Neo4j 图。
n8n 凭据只在 n8n 中管理；平台不保存节点凭据明文。

状态模型

draft -> validating -> active -> superseded，调用失败进入 activation_failed。只有 active 参与环境执行入口解析。

数据库使用部分唯一索引：

CREATE UNIQUE INDEX uq_dataflow_active_environment
ON dataflow_workflow_versions (dataflow_uid, environment)
WHERE status = 'active';

接口边界

/api/dataflow/*：治理定义和版本映射。
/api/datafactory/workflows/*：n8n 原生 Workflow 读取、激活、停用和执行代理。
新增 /api/dataflow/{uid}/workflow-versions 和 /activate 接口，由后端组合两侧能力。

结果

页面对用户显示“数据流程（DataFlow）”；只有查看执行实现、版本和运行记录时显示“n8n Workflow”。这避免因命名统一而丢失两个不同领域概念。