# Kestra V50 验证记录

- 代码版本：`codex/kestra-v50`，基线 `38326506f09a467d598cdcfba06b1993af65e792`
- 验证日期：2026-07-18
- 变更范围：n8n 迁移资产清单、WorkflowSpec/SchedulePlan、机器策略、
  引擎无关数据库迁移与仓储兼容

## 已执行验证

### 基线

```text
tests/test_database_migrations.py
tests/test_workflow_version_schema.py
tests/test_workflow_repository.py
tests/test_workflow_activation.py

8 passed, 1 skipped
```

跳过项需要临时 PostgreSQL；后续已单独启动 PostgreSQL 并实际执行通过。

### TDD 过程

- n8n 资产清单：先确认 2 个测试因模块不存在失败，实现后转绿；真实调用又发现
  直接 CLI 导入路径和 Flask 超时上下文两个问题，分别补充失败测试并修复，最终
  该模块 `4 passed`。
- WorkflowSpec/SchedulePlan/策略：先确认 9 个测试因模块不存在失败，实现后
  `9 passed`。
- 通用仓储与迁移：先确认 6 个测试因模块/迁移不存在失败，实现后相关集合
  `11 passed, 1 skipped`。
- 旧 n8n 仓储通用字段兼容测试先失败，补充通用字段写入后通过。

### V50 L1/L2 增量验证

```text
tests/test_n8n_migration_inventory.py
tests/core/orchestration/test_spec.py
tests/core/orchestration/test_repository.py
tests/core/orchestration/test_policy.py
tests/test_database_migrations.py
tests/test_workflow_engine_abstraction_schema.py
tests/test_workflow_version_schema.py
tests/test_workflow_repository.py
tests/test_workflow_activation.py

29 passed
```

其中 PostgreSQL 集成测试已实际验证：

- 从空数据库升级到 Alembic head。
- 对同一数据库重复执行升级。
- 确认 V50 新表存在。
- 从 `20260718_60` 降级一版并保留既有基础表。

n8n 本地集成已实际验证：

- 在本地 n8n 创建 `DataOps V50 Local Test` API Key，有效期至 2026-08-17。
- Key 写入 Git 忽略的本地 `.env`，文件权限为 `0600`，验证输出不包含明文 Key。
- 使用资产清单 CLI 通过 n8n API 完成采集，结果为 `collection_status=complete`。
- 当前本地测试实例没有 Workflow，覆盖结果为 0 个 Workflow、0 个活跃流程、
  0 个近 90 天执行流程和 0 个阻塞项。
- DataOps 后端容器已加载该 Key，并通过平台自身 `N8nClient` 成功读取
  Workflow 列表。

附加检查：

- V50 新增 Python 文件字节码编译通过。
- `git diff --check` 通过。
- 仅启动/复用本地 PostgreSQL 完成迁移测试，没有执行全量测试、前端构建或
  完整容器栈验收。

## 未执行验证及原因

- 未运行全仓库 Python 测试：V50 计划要求增量验证，本次变更范围可以由上述
  L1/L2 集合覆盖。
- 未运行前端构建：V50 没有前端变更。
- 未运行 Kestra、Runner 或 MCP 测试：这些能力分别属于 V51–V53。
- 未通过 `/api/datafactory/health` 做匿名验证：该接口受 DataOps RBAC 保护，
  未登录请求按预期返回 401。已改用后端容器内部的 DataOps `N8nClient`
  验证 Key，不绕过平台认证。

## 安全与兼容结果

- 资产清单不保存 Credential ID、密码、API Key、Token、连接串或执行数据。
- WorkflowSpec 拒绝秘密字段、未知节点、环形 DAG 和缺少幂等声明的写任务。
- SchedulePlan 拒绝无限重试和无界回填。
- 现有 n8n 版本继续保留 `n8n_workflow_id` 和原激活状态机，同时写入通用
  `engine_type='n8n'` 与 `engine_definition_id`。
- 数据库约束同一 DataFlow/环境最多一个启用的 Primary 和一个启用的 Shadow。
- API Key 没有写入 Git 跟踪文件、测试报告或终端输出。

## 已知限制与回滚点

- V50 尚未接入 Kestra，不支持引擎切换。
- 当前完成的是本地 Docker n8n 资产基线；接入包含正式流程的受控 n8n 实例时，
  必须重新生成对应环境清单，不能沿用本地 0 Workflow 结论。
- 可通过 Alembic 降级移除 V50 新表和通用字段；存在非 n8n 版本时，迁移会拒绝
  破坏性降级。
- 回滚不会修改或删除现有 n8n Workflow。

## 结论

V50 代码实现、本地 n8n 资产采集和增量技术验证全部通过，当前
**允许进入 V51**。本结论只覆盖本地 Docker 测试环境；后续迁移任何包含正式
Workflow 的 n8n 环境时，仍必须先生成该环境的独立清单。