# FlashOps — 存储实验室无人值守执行层

> 固件回归测试的**控制平面**：把一条真实 SOP 变成可执行、可恢复、可取证的状态机，
> 让工程师不必通宵值守。

**命名是临时的。** `FlashOps` 只是后端代号，控制台目前仍显示 `STORAGE LABOS`；
商标与最终品牌确认后，需要统一后端常量、控制台标题和文档。

---

## 当前可运行基线

现在已有一条**无需硬件即可端到端跑通**的真实纵向链路：

```
建任务 → 六项安全预检 → 资源加锁 → N 次模拟循环
      → 注入 Agent 心跳丢失 → L1/L2 失败 → L3 带外 Reset 恢复
      → 从循环检查点续跑 → Evidence Bundle 打包 → 前端实时可见
```

全程使用内置模拟 DUT、测试主机与带外控制器，一条命令即可完成。当前实现重点是
事件溯源写路径、安全门禁、状态转移、恢复记录和可复现演示；独立 Host Agent
已经完成注册、token 与心跳最小链路，但步骤租约、真实硬件适配器、失败聚类执行逻辑
与完整权限体系仍是后续工作，不在此基线中伪装完成。

---

## 快速开始

前置：Python 3.9+。**不需要 Node 或 Docker。**

```bash
make setup      # 建 venv、装依赖、建库、灌种子数据
make demo       # 跑一条 8 轮模拟回归（含故障注入、恢复与证据包）
make dev        # 起控制平面与控制台 :8000
make dev-agent  # 注册独立 Host Agent 并发送一次心跳
make test       # 控制平面 + Agent + API 端到端测试
```

`make demo` 结束会打印 Run ID 与 Evidence Bundle 路径；`make dev` 后打开
<http://localhost:8000/console/Tasks.dc.html>，运行预检并创建任务，再进入“实时运行”
即可看到同一条 Run 的事件时间线。API 文档在 <http://localhost:8000/docs>。

---

## 仓库结构

```
flashops/
├─ docs/                        架构与规范（先读这里）
│  ├─ architecture.md           五层架构 → 代码目录的逐层映射
│  ├─ domain-model.md           7 个核心领域对象 → 数据库表
│  ├─ state-machine.md          Run/Step 状态机、恢复阶梯、检查点语义
│  ├─ adapter-sdk.md            工具适配器契约（产品扩张的关键边界）
│  ├─ workflow-spec.md          SOP → YAML 工作流的 schema
│  └─ decisions/                ADR：为什么这么选，以及什么时候该推翻
├─ services/
│  ├─ control-plane/            FastAPI 控制平面（事件、安全、模拟执行、证据）
│  └─ host-agent/               独立拉模式 Agent（注册、凭据、心跳）
├─ ../前端UI八页面完成/          控制台原型；由 FastAPI 挂载到 /console
├─ docker-compose.yml           目标生产拓扑草案（尚未作为发布物验收）
└─ Makefile
```

---

## 三条必须守住的架构红线

写后续代码时，这三条一旦破了，返工成本最高：

1. **控制面与数据面分离**——任务状态的唯一真相在控制平面数据库，测试主机本地只有缓存。
   Agent 挂了、主机重装了，Run 状态不丢。

2. **事件溯源**——所有状态变化以 append-only 事件写入 `run_events`，
   当前状态是事件的投影而非独立真相。时间线、审计、复现全部由此派生。
   *禁止*绕过 `events/recorder.py` 直接 UPDATE Run 状态。

3. **安全默认拒绝**——当前序列号、破坏性授权、系统盘、固件型号、Host 与 OOB
   任一不满足即在 `safety/` 层拒绝。真实 Agent 接入前还必须补签名命令模板，
   保证 Agent 只执行控制平面批准的动作。

---

## 当前状态与下一步

| 能力 | 状态 | 说明 |
|---|---|---|
| 14 张持久化表 | ✅ 已落地 | SQLite 建表与种子数据可重复执行 |
| Run 事件溯源 | ✅ 已落地 | 状态只能经 `events/recorder.py` 投影 |
| Run 状态转移 | ✅ 已落地 | 纯函数转移表，终态不可恢复 |
| 六项安全门禁 | ✅ 已落地 | 序列号、破坏性授权、系统盘、固件、Host、OOB |
| L1–L5 恢复决策 | ✅ 已落地 | 纯函数；演示链路实际执行 L1–L3 |
| 循环检查点续跑 | ✅ 模拟落地 | 循环边界保存，恢复后续跑 |
| Evidence Bundle | ✅ 最小实现 | `manifest.json` + `events.ndjson`，完整率 100% |
| 控制台 | 🟨 部分接入 | 任务中心与实时运行接 API；其余页面仍为静态样例 |
| 独立 Host Agent | 🟨 部分落地 | 注册、token 摘要、心跳、主机探针与 15s/30s 状态老化已实现；Step 租约待实现 |
| 真实 nvme-cli 与 OOB | ⬜ 待实现 | 需要可牺牲 DUT 与 JetKVM/PDU |
| 失败签名执行与聚类 | ⬜ 待实现 | 数据表已定义，服务逻辑未接入 |
| 多工位调度、认证与权限 | ⬜ 待实现 | 进入真实实验室前必须补齐 |

下一步建议实现 Step 租约、ACK、续租、完成上报与幂等事件，再把内置模拟执行器迁到
独立 Agent；完成这层后再接真实 `nvme-cli` 与 JetKVM，才能保证硬件接入不绕过
控制面安全规则。