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

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

## 背景

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

## 决策

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

## 状态模型

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

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

```sql
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”。这避免因命名统一而丢失两个不同领域概念。