# 一键部署编排 + 回滚引擎（Issue #60 / PRD 5.6）

> 父 Issue「⑥ 一键部署脚本与回滚机制 · 0.5d」

把一键部署与回滚落为**可测试的纯标准库编排引擎**——不真执行 k8s/helm，但模拟
完整编排序列（pre_check → deploy → health_check → post_check）+ 部署前快照 +
失败回滚。对齐 `deploy/k8s/helm/iaop`（Chart）与 `deploy/k8s/healthz`（探针）。

## 1. 部署编排（`deploy_plan.py`）

- `DeployStep` —— 声明式步骤：`kind`（pre_check/deploy/health_check/post_check）
  + `name` + `action` 回调（返回 `(ok, detail)`，默认模拟成功）。
- `DeployPlan` —— 步骤序列 + 发布元信息（release/namespace/chart/version）；
  `default_helm_release()` 生成默认 4 步 Helm 发布计划；步骤顺序约束
  （pre_check < deploy < health_check < post_check）自动校验。
- `DeployOrchestrator` —— 按序执行，任何必需步骤失败即中止并标记回滚
  （`DeployOutcome.needs_rollback`），产出 `DeployReport`（逐步结果 + 日志 +
  可解释 reason）。deploy/health_check 是回滚检查点；pre_check 失败无需回滚。
- `HealthCheckContract` —— 健康检查契约（端点/超时/重试/可用率目标，对齐
  `deploy/k8s/healthz` 的 99.8%）。

```python
from deploy_plan import DeployPlan, DeployOrchestrator

plan = DeployPlan.default_helm_release(release="iaop", backend="gpu")
report = DeployOrchestrator(plan).execute()
if not report.succeeded and report.outcome.needs_rollback:
    print("需回滚：", report.outcome.reason)
```

## 2. 回滚引擎（`rollback.py`）

- `RollbackPoint` —— 部署前快照（release/namespace/version/chart/values_hash/
  created_at，不可变）。`values_hash`（SHA1）检测配置漂移。
- `RollbackManager` —— 快照栈 + 回滚执行：`snapshot(plan)` 部署前压栈；
  `rollback_to_latest()` / `rollback(n)` 失败时回滚到稳定版本。回滚失败把目标压回
  栈顶（保持栈一致性）；支持回滚后健康检查。FIFO 淘汰防内存膨胀。
- `RollbackResult` —— 回滚结果（SUCCESS/FAILED/NO_TARGET/SKIPPED + 可解释 reason）。

```python
from deploy_plan import DeployPlan, DeployOrchestrator
from rollback import RollbackManager

mgr = RollbackManager()
mgr.snapshot(plan)              # 部署前快照
report = DeployOrchestrator(plan).execute()
if not report.succeeded:
    result = mgr.rollback_to_latest(reason=report.outcome.reason)
    print(result.status.value, result.detail)
```

## 与现有部署资产的关系

- 真实环境把 `action` / `restore_action` 注入为 `helm upgrade` / `helm rollback`
  等真回调即可；本引擎只做编排与状态管理，不耦合 k8s 客户端。
- 健康检查契约对齐 `deploy/k8s/healthz/probe_availability.py`（99.8% 可用率目标）。

## 测试

```bash
python -m unittest discover -s deploy/orchestration/tests -p "test_*.py" -v
```

覆盖正常 + 边界 + 错误（30 用例）：4 步计划构造、顺序约束、全成功/各类失败、
回滚检查点判定、action 异常、dry_run、空计划、快照压栈/FIFO、回滚成功/失败/
多版本/空栈/异常、健康检查契约校验、values 漂移、报告序列化。