diff --git a/docs/superpowers/specs/2026-05-06-product-review.md b/docs/superpowers/specs/2026-05-06-product-review.md new file mode 100644 index 0000000..e9b16b4 --- /dev/null +++ b/docs/superpowers/specs/2026-05-06-product-review.md @@ -0,0 +1,134 @@ +# 产品化评估与后续规划 + +> 评估日期:2026-05-06 +> 范围:视觉识别服务(OrangePi3588Media)+ 管理后台(3588AdminBackend) + +--- + +## 一、整体架构评价 + +两个项目的架构基础扎实: + +- **media-server**:插件化 DAG 流水线,JSON 配置驱动,热更新/回滚,硬件解耦抽象清晰 +- **managerd**:分层架构(API→Service→Storage),RESTful,HTML/template 服务端渲染,无框架依赖 + +从产品化角度看,两边都有显著缺口,下面按优先级列出。 + +--- + +## 二、视觉识别服务(media-server) + +### ✅ 优势 + +| 方面 | 现状 | +|------|------| +| 架构设计 | 插件+DAG 流水线,热更新、回滚、ABI 校验都有 | +| 性能目标 | 8路1080p实时分析、延迟<500ms,文档明确 | +| 算法能力 | YOLO检测、人脸检测/识别、PPE、工鞋、行为事件,覆盖主流场景 | +| 输出能力 | RTSP/HLS推流、MinIO存储、HTTP回调报警、外部API对接 | +| 硬件适配 | NPU推理+MPP编解码+RGA图像处理,充分利用RK3588 | + +### ❌ 需要补的 + +| 缺口 | 严重程度 | 说明 | +|------|---------|------| +| Agent 和管理后端协议不统一 | 高 | `/v1/info`、`/v1/models/status`、`/v1/resources/status`、`/v1/face-gallery` 等端点是逐步增加的,没有完整 API 文档或版本号协商机制 | +| Agent 配置需要手动填写 | 高 | `deploy.sh` 模板文件名容易出错(如缺少 std_ 前缀),回退到交互式选择旧配置文件 | +| 人脸库上传靠文件拷贝 | 中 | `/v1/face-gallery` 整体 PUT,没有单个人物增删改、没有人物照片上传接口 | +| 告警无统一管理 | 中 | 告警配置嵌在 config JSON 里,规则修改需手动编辑 JSON | +| 日志无结构化 | 中 | spdlog 纯文本,无结构化字段,检索困难 | +| 监控指标无持久化 | 中 | agent 提供 `/v1/metrics` 但后端无收集和图表展示 | +| 配置变更无历史 | 低 | 有 `last_good.json` 回滚,无变更历史记录 | + +--- + +## 三、管理后台(managerd) + +### ✅ 优势 + +| 方面 | 现状 | +|------|------| +| 设备管理 | UDP 发现 + DB持久化 + 定时刷新 + 离线设备显示 | +| 配置管理 | 模板+Profile+Overlay 三层配置渲染,支持预览和下发 | +| 模型/资源管理 | 标准目录 → 设备状态矩阵比对,SHA256一致性校验 | +| 任务系统 | 批量执行 + SSE 实时推送 + 审计记录 | + +### ❌ 需要补的 + +| 缺口 | 严重程度 | 说明 | +|------|---------|------| +| **仪表盘是摆设** | **极高** | 只汇总设备数量/在线/任务统计,无实时告警、无 NPU 使用率、无识别结果概览。作为产品首页太空了 | +| **场景配置太复杂** | **高** | 模板→Profile→识别单元→设备分配 四层概念,无向导式配置流程,用户学习成本高 | +| **告警管理缺失** | **高** | 后台看不到设备告警记录、告警截图、告警趋势 | +| **实时预览缺失** | **高** | 不能从管理后台直接查看摄像头画面 | +| **人脸库管理不完整** | **高** | 只能整文件上传 .db,不能增删改单个人物、查看人物列表、上传单张人脸照片 | +| **日志检索薄弱** | 中 | 只提供设备日志入口,无关键词搜索、时间范围过滤、导出 | +| **批量操作不完善** | 中 | 无批量升级 agent 二进制、批量重启 media-server | +| **用户权限缺失** | 中 | 无登录、无多用户、无操作权限控制 | +| **配置导出/导入** | 低 | 无设备配置导出、批量导入 | +| **国际化** | 低 | 全部硬编码中文,出海需 i18n | + +--- + +## 四、两个项目之间的协同问题 + +| 问题 | 说明 | +|------|------| +| 配置下发后无验证 | 后端推送配置 → HTTP 200 → 但无法确认 media-server 热更新是否实际成功 | +| 设备重连后状态不一致 | 设备重启后 agent 不主动同步状态,需等后台 30 秒定时发现 | +| 人脸库版本漫游 | 设备上 cam1~cam5 各有一份 face_gallery.db,版本对齐全靠人工 | +| 模型版本管理弱 | 只比对 SHA256,不知道模型精度/性能差异,无效果评估 | + +--- + +## 五、优先级规划 + +### P0(必须做——否则不算完整产品) + +1. **Dashboard 实时化** + - 实时告警信息流(设备名称、告警类型、时间、截图) + - 设备 NPU/CPU/内存使用率实时图表 + - 设备在线状态实时更新 + +2. **人脸库管理** + - 人物列表查看(姓名、人脸照片、注册时间) + - 新增/编辑/删除人物 + - 上传单张人脸照片 + 自动提取 embedding + - 整库导出/导入 + +3. **告警管理** + - 告警记录列表(时间、设备、规则、截图) + - 告警趋势统计(按天/按规则/按设备) + - 告警视频回放入口 + +### P1(提升易用性) + +4. **场景配置向导** + - 逐步引导:选模板 → 填参数 → 选视频源 → 选设备 → 预览 → 下发 + - 取代当前四层概念(模板/Profile/识别单元/设备分配) + +5. **Agent 主动注册** + - agent 启动时向管理后端发心跳 + - 设备上电即可被纳管,无需等待 UDP 发现 + +6. **配置模板渲染自动化** + - deploy.sh 默认使用模板渲染,不交互选择 + - 模板文件名修正(`std_` 前缀) + +### P2(提升健壮性) + +7. **用户认证和权限** — 登录 + 角色 + 操作日志 +8. **告警规则 UI 管理** — 在后台页面上创建/编辑告警规则 +9. **日志结构化 + 检索** — agent 输出 JSON 格式日志,后端提供全文检索 + +--- + +## 六、技术债务清单(后续清理) + +| 项目 | 说明 | +|------|------| +| `cmd/managerd` 目录名歧义 | 既是源码目录又被 gitignore 匹配为二进制 | +| 模板函数分散 | `modelTypeLabel`、`resourceTypeLabel` 等散落在 NewUI 中,应集中管理 | +| agent 配置示例过时 | `agent.config.example.json` 路径与生产环境不一致 | +| deploy.sh 交互选择 | 应支持完全无交互部署(CI/CD 友好) | +| 测试覆盖率不均匀 | web 包测试 193KB,但主要是模板渲染测试,缺少 service 层集成测试 |