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:

{ "timeout_ms": 1200 }

Response:

{ "items": [ {"device_id":"...","ip":"...","agent_port":9100,"media_port":9000,"device_name":"...","version":"...","git_sha":"..."} ] }

4.2 Devices

GET /api/devices

Response:

{ "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:

{ "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:

{
  "type": "config_apply",
  "device_ids": ["..."],
  "payload": { "config": {} }
}

Response:

{ "task_id": "..." }

GET /api/tasks/:id/events (SSE)

Event device_update data:

{ "device_id":"...","status":"running|success|failed","progress":0.0,"error":"" }

5. 错误处理规范（managerd → 前端）

• 成功：2xx + {"ok":true} 或正常业务 JSON
• 失败：4xx/5xx +

{ "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：

{
  "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 输出逐台结果。