Migu2.0/docs/superpowers/plans/2026-07-19-migu-ota-watchdog.md

# 迷榖 OTA（WatchDog）实现计划

> **状态：** 核心任务已落地（后端 API + 前端工作台）。联调 WatchDog 实车需现场验证。  
> **面向 AI 代理的工作者：** 按任务顺序实现；每完成一大任务做一次验证。规格：`docs/superpowers/specs/2026-07-19-migu-ota-watchdog-design.md`。

**目标：** 车辆运维改为「运维总览 + OTA」，平台编排 WatchDog 完成包库/下发/任务/配置/自定义文件/设置与延迟检测。  
**架构：** MiGu.Server `api/ota/*` 出站调 WatchDog `:9776`；包与任务落盘 `data/ota/`；前端 `OtaWorkbenchView` 只调平台 API。  
**技术栈：** ASP.NET Core 8、Vue 3、Element Plus、HttpClient、现有 JWT/RBAC。

---

## 文件结构

### 后端（新建）

| 文件 | 职责 |
|------|------|
| `MiGu.Server/Ota/OtaOptions.cs` | DataRoot、WatchDogPort、超时、本机接收端口 |
| `MiGu.Server/Ota/OtaModels.cs` | Package/Target/Job/Settings/VehicleRow DTO |
| `MiGu.Server/Ota/OtaPathMap.cs` | MDC 路径与组件键 |
| `MiGu.Server/Ota/OtaHash.cs` | MD5 Base64 去 `-` |
| `MiGu.Server/Ota/OtaStore.cs` | packages/target/jobs/settings/history 读写 |
| `MiGu.Server/Ota/WatchDogClient.cs` | getMDCInfo、update*、get*json、getmdcsexe、latency |
| `MiGu.Server/Ota/OtaPackageReceiver.cs` | 供 WatchDog 回传 upload-mdcs* 的内部端点宿主或同进程路由 |
| `MiGu.Server/Ota/OtaJobRunner.cs` | 分批、限速、状态机、重试/取消 |
| `MiGu.Server/Ota/OtaVehicleSource.cs` | 从 SimpleLite projection 取车列表 |
| `MiGu.Server/Controllers/OtaController.cs` | `/api/ota/*` |
| `MiGu.Server/Controllers/OtaReceiveController.cs` | WatchDog 回传 `/api/ota/receive/upload-mdcs*` |

### 后端（修改）

| 文件 | 变更 |
|------|------|
| `MiGu.Server/Program.cs` | 注册 OTA 服务 |
| `MiGu.Server/appsettings.json` | `Ota` 节 |

### 前端（新建）

| 文件 | 职责 |
|------|------|
| `src/api/ota.ts` | API 客户端 |
| `src/types/ota.ts` | 类型 |
| `src/views/shared/ota/OtaWorkbenchView.vue` | 左导航壳 + 顶条 |
| `src/views/shared/ota/OtaVehiclesPane.vue` | 车辆升级 |
| `src/views/shared/ota/OtaPackagesPane.vue` | 版本库 |
| `src/views/shared/ota/OtaJobsPane.vue` | 任务中心 |
| `src/views/shared/ota/OtaConfigPane.vue` | 配置同步 |
| `src/views/shared/ota/OtaCustomFilePane.vue` | 自定义文件 |
| `src/views/shared/ota/OtaSettingsPane.vue` | 设置 |
| `src/composables/useOtaWorkbench.ts` | 目标版本、设置、刷新 |

### 前端（修改）

| 文件 | 变更 |
|------|------|
| `src/views/shared/VehicleHubView.vue` | Tab：overview \| ota；重定向旧 tab |

---

## 任务

### 任务 1：后端基础（Options / Models / Store / Hash）

1. 创建 `OtaOptions`、`OtaModels`、`OtaPathMap`、`OtaHash`、`OtaStore`。
2. Settings 默认：bandwidth=0（不限）、maxCar=2、latencyEnabled=false、rttThresholdMs=200、overThreshold=`skip`、backupPeriodMinutes=60、backupExe=false。
3. `Program.cs` + `appsettings.json` 注册。
4. 验证：`dotnet build MiGu.Server/MiGu.Server.csproj` 通过。

### 任务 2：WatchDogClient + 车辆源 + Receive

1. `WatchDogClient`：MDCInfo、组件上传（multipart）、JSON get/put、触发 getmdcsexe、TCP/HTTP RTT。
2. `OtaVehicleSource`：HttpClient 调 SimpleLite `http://127.0.0.1:8222/api/agv/list` 或 projection cars（与现有一致优先 projection）。
3. `OtaReceiveController`：接收 upload-mdcs* 写入当前 pull 会话目录。
4. 验证：build 通过。

### 任务 3：JobRunner + OtaController API

实现规格 §4.2 全部端点；JobRunner 支持 sync/custom/config 三类 job；审计写入 `OpsAuditStore` 或 `data/ota/audit.json`。
验证：build 通过；手动 curl GET settings/packages。

### 任务 4：前端 API + 类型 + Hub Tab 切换

1. `types/ota.ts`、`api/ota.ts`。
2. `VehicleHubView` 仅 overview/ota；挂载 `OtaWorkbenchView`。
3. 验证：前端 typecheck/dev 可加载。

### 任务 5：OTA 工作台 UI（六子页）

按规格 §5 实现各 Pane；延迟检测开关在车辆升级工具条。
验证：页面可切换、设置可保存、无目标时下发被拦截。

### 任务 6：联调与验收

对照规格 §9 验收清单；修明显 bug。

---

## 关键实现约定

- MD5：`Convert.ToBase64String(MD5.HashData(bytes)).Replace("-", "")`（与参考工具一致则对照其实现）。
- 组件键：`M.exe` `M.dll` `M.pdb` `D.exe` `C.exe` `C.dll` `C.pdb`。
- Job kind：`sync` | `customFile` | `configPush`。
- 进度字段：`doneSteps` / `totalSteps`；每车每组件 `status`：pending|running|succeeded|failed|skipped。
- 拉取包：平台记录 `pendingPullId` + 本机可达 URL，调车 `getmdcsexe?time=`；车推到 `/api/ota/receive/...`。

---

## 规格覆盖自检

| 规格项 | 任务 |
|--------|------|
| IA / 删维护策略与生命周期 | 4 |
| WatchDog 编排 | 2–3 |
| 包库/目标/任务/设置/延迟 | 3、5 |
| 配置同步/自定义文件 | 3、5 |
| 审计 | 3 |
| 验收 §9 | 6 |