# PRD ③ 管理端后端（Go managerd）V1

## 1. 目标与运行方式
- 提供本机 HTTP API 给 React UI 使用。
- 负责 UDP 广播发现（Option A），维护设备缓存与在线状态。
- 通过设备端 `rk3588-agent` 完成配置/模型等运维操作，并可通过 agent 代理读取 graphs/logs。
- 支持批量任务（并发、进度、失败原因）并通过 SSE 推送。

运行：单可执行 `managerd`，默认监听 `127.0.0.1:18080`（可配置）。

## 2. 外部依赖与约束
- Go 版本：>= 1.22（建议）
- 标准库优先；Web 框架可选 `chi`/`gin`（建议 chi + net/http）。
- 不需要数据库（V1 用内存 + 可选本地 JSON 持久化）。

## 3. 模块划分

### 3.1 Discovery
- 向所有可用网卡的广播地址发送 UDP discover。
- 监听本地 UDP socket 收集 replies（时间窗默认 1200ms）。
- 去重规则：按 `device_id` 去重，以最新 reply 为准。

### 3.2 Device Registry
- 内存缓存：
  - `device_id -> {ip, agent_port, media_port, device_name, version, git_sha, last_seen_ms, online}`
- 定时刷新（可配置间隔）：对 online 设备拉取 `GET /v1/graphs`（agent 代理），更新摘要。
- Offline 规则：超过 `offline_after_ms`（如 10000ms）未见到，则标记离线。

### 3.3 Device Client
- 统一超时：connect 1s、overall 3s（可配置）。
- 统一错误包装：返回 `error_code + message + device_id`。
- Token：
  - 全局默认 token（V1）
  - 可预留 per-device token（P1）

### 3.4 Templates/Config Builder
- 模板库来源：
  - V1：managerd 内置（embed）或本地 `templates/` 目录读取
- 返回前端表单 schema：V1 允许手工维护（避免解析占位符带来的不确定性）。
- 生成 root config：基于模板与 params，产出 `{global,templates,instances}`。

### 3.5 Task Runner
- 任务类型：
  - `config_apply`（对 N 台设备下发 config）
  - `reload`
  - `rollback`
  - `model_upload`（V1 可先做单设备；批量后续）
- 并发控制：默认 5（可配置）。
- 状态：`pending/running/success/failed`（逐设备与整体）。
- 推送：SSE `GET /api/tasks/:id/events`。

## 4. managerd 对前端 API 规格（V1）

### 4.1 Discovery
#### `POST /api/discovery/search`
Request:
```json
{ "timeout_ms": 1200 }
```
Response:
```json
{ "items": [ {"device_id":"...","ip":"...","agent_port":9100,"media_port":9000,"device_name":"...","version":"...","git_sha":"..."} ] }
```

### 4.2 Devices
#### `GET /api/devices`
Response:
```json
{ "items": [ {"device_id":"...","online":true,"last_seen_ms":0,"ip":"...","agent_port":9100,"media_port":9000,"device_name":"...","version":"...","git_sha":"...","graphs":[...]} ] }
```

#### `GET /api/devices/:id`
Response：包含 `info`、`graphs_summary`、`last_seen`。

### 4.3 Device actions（代理调用）
以下全部通过 agent：
- `POST /api/devices/:id/reload` → agent `POST /v1/media-server/reload`
- `POST /api/devices/:id/rollback` → agent `POST /v1/media-server/rollback`
- `GET /api/devices/:id/graphs` → agent `GET /v1/graphs`
- `GET /api/devices/:id/graphs/:name` → agent `GET /v1/graphs/{name}`
- `GET /api/devices/:id/logs?limit=200` → agent `GET /v1/logs/recent?limit=200`

### 4.4 Config apply
#### `POST /api/devices/:id/config/apply`
Request:
```json
{ "config": { } }
```
Behavior：调用 agent `PUT /v1/config`。

### 4.5 Model upload
#### `POST /api/devices/:id/models/upload`
Request：`multipart/form-data`，字段：
- `name`: string
- `file`: binary

Behavior：读取文件流，转发为 agent `PUT /v1/models/{name}`（raw body）。

### 4.6 Templates
- `GET /api/templates`
- `GET /api/templates/:name`

### 4.7 Tasks
#### `POST /api/tasks`
Request:
```json
{
  "type": "config_apply",
  "device_ids": ["..."],
  "payload": { "config": {} }
}
```
Response:
```json
{ "task_id": "..." }
```

#### `GET /api/tasks/:id/events` (SSE)
Event `device_update` data:
```json
{ "device_id":"...","status":"running|success|failed","progress":0.0,"error":"" }
```

## 5. 错误处理规范（managerd → 前端）
- 成功：2xx + `{"ok":true}` 或正常业务 JSON
- 失败：4xx/5xx +
```json
{ "error": { "code": "...", "message": "...", "device_id": "...", "detail": "..." } }
```

建议错误码：
- `DISCOVERY_FAILED`
- `DEVICE_NOT_FOUND`
- `DEVICE_OFFLINE`
- `DEVICE_HTTP_ERROR`
- `DEVICE_TIMEOUT`
- `TASK_NOT_FOUND`
- `VALIDATION_ERROR`

## 6. 配置文件（managerd）建议
`managerd.json`：
```json
{
  "listen": "127.0.0.1:18080",
  "discovery_port": 35688,
  "discovery_timeout_ms": 1200,
  "offline_after_ms": 10000,
  "agent_token": "CHANGE_ME",
  "concurrency": 5
}
```

## 7. 验收标准
1. Search 可发现设备并更新 registry；离线判断正确。
2. 可通过 agent 读取 graphs/logs（`GET /v1/graphs`、`GET /v1/logs/recent`）。
3. 单设备 `config/apply`、`reload`、`rollback` 可用，错误可定位。
4. 批量 `config_apply` 任务可并发执行并通过 SSE 输出逐台结果。