# Kestra V55 阶段验收记录

- 代码分支：`codex/kestra-v55`
- 基线提交：`945d680`
- 验收日期：2026-07-19
- Python：3.11.15
- 结论：V55 双轨迁移、对账、事务化单流程切换、自动回切、批次门禁和退役审计
  框架完成；本地可进入 `kestra_primary_n8n_standby`。n8n 统一退出门禁未满足，
  不批准进入 `kestra_primary`，也不移除 n8n。

## 完成范围

### 双轨与转换

- 实现四种迁移模式及相邻状态转换约束。
- n8n 转换器只自动转换受控触发器、显式只读 SQL、GET HTTP 和条件节点；未知
  节点生成阻断报告，不降级为任意脚本。
- 数据源只通过 UID 映射，转换结果不复制凭据。
- n8n 正式执行与 Kestra 影子执行共享同一不可变输入快照和摘要。
- 影子写必须指向声明的隔离目标；否则失败关闭。

### 对账、切换与持久化

- 对账状态、行数、主键摘要、内容摘要、异常、聚合、耗时和资源消耗。
- 对账策略允许显式忽略非确定性指标或声明数值容差，但核心正确性指标不可忽略。
- 新增迁移状态、双跑、对账报告和切换操作四张 PostgreSQL 控制表。
- 切换请求、状态更新和 Outbox 事件在同一事务提交；相同幂等键不会重复发事件。
- 切换消费者先停 n8n 再启 Kestra；Kestra 激活失败自动恢复 n8n。
- 显式回切先停 Kestra 再启 n8n。审计只保留有界状态和安全原因码。

### 分批推广和退役保护

- 固定四批顺序：只读低频、幂等分区写、核心多节点、特殊高风险。
- 进入门禁覆盖资产、WorkflowSpec、策略、回滚目标、影子次数、失败恢复、对账、
  连接预算、峰值并发和 SLA。
- 退出门禁覆盖观察窗口、数据差异、重复写、SLA、暂停/重试/回切演练及 n8n
  Standby 未被外部修改。
- n8n 退役清单失败关闭，并要求独立评审及唯一一次最终 L4。

## 验证结果

### L1：V55 领域与命令

```bash
PYTHONPATH=. .venv/bin/python -m pytest -q \
  tests/integration/test_n8n_kestra_dual_run.py \
  tests/integration/test_workflow_reconciliation.py \
  tests/integration/test_workflow_engine_cutover.py \
  tests/integration/test_workflow_engine_rollback.py \
  tests/integration/test_workflow_migration_rollout.py \
  tests/integration/test_n8n_retirement_audit.py \
  tests/test_v55_migration_commands.py
```

结果：`34 passed`。

### L2：受影响边界与迁移

- 最终合并执行 V55、V54 回归、受影响边界、真实持久化、真实切换回切和迁移测试：
  `113 passed`。
- 编排核心、Scheduling/Context MCP、安全边界、n8n 清单和客户端配置：
  `48 passed`。
- Alembic 全新临时库升级、重复升级和单版本回退：`3 passed`。
- V54 Agent、MCP、真实 Kestra/Runner Canary 和模型离线回归：`40 passed`。
- V55 引擎角色顺序、真实 PostgreSQL 状态/双跑/对账/Outbox：
  `3 passed`。

### L3：真实切换与回切

使用本地 Docker 中运行的 PostgreSQL、n8n 和 Kestra 完成一个受控流程演练：

1. n8n 已激活、Kestra Flow 已禁用；
2. 先停用 n8n，再使用不存在的 Kestra Flow 模拟激活失败；
3. 系统自动重新激活 n8n，操作落库为 `rolled_back`；
4. 使用有效 Kestra Flow 再次切换，n8n 变为禁用、Kestra 变为启用；
5. 显式回切先禁用 Kestra，再激活 n8n。

结果：`1 passed`。演练后的临时 n8n Workflow、Kestra Flow、迁移状态和 Outbox
事件均已清理；数据库处于 `20260719_90 (head)`。

### 静态和安全检查

- Ruff：通过。
- V55 新增生产模块 Pyright：`0 errors, 0 warnings`。
- `git diff --check`：通过。
- 新增范围未发现 API Key、云访问密钥、私钥或本地测试密码硬编码。

未执行全仓 Python、前端构建和完整栈 L4。V55 当前明确不退役 n8n，也没有修改
前端、Docker Compose 或公共启动入口；按验证计划，只有正式移除 n8n 前才执行
唯一一次 L4。

## 未退役 n8n 的原因

本地实时清单为零只能证明当前本地实例没有持久业务 Workflow，不能替代生产
资产处置证据。当前也没有完整业务周期、Standby 观察期、生产依赖扫描、安全
归档恢复、独立评审和最终 L4 证据。

因此：

- 不修改 Docker Compose 移除 n8n；
- 不删除 n8n API、前端入口、历史执行或兼容字段；
- 不宣称 n8n 已经下线；
- 生产逐流程切换仍须为每个实际 Workflow 补齐真实双跑、对账和观察证据。

详细缺口见 `docs/validation/kestra-v55-retirement-audit.json`。