# 产品化评估与后续规划

> 评估日期：2026-05-06
> 范围：视觉识别服务（OrangePi3588Media）+ 管理后台（3588AdminBackend）

---

## 零、第一性原理：这个产品到底该做什么

### 核心定义

**边缘视频分析平台**——RK3588 盒子接摄像头，本地 AI 识别（人脸、安全帽、工鞋、行为），通过网络输出结果。

### 目标用户

- **运维人员**：管盒子、配摄像头、看告警、维护人脸库
- **管理者**：看统计、看趋势、做决策

### 核心价值链条

```
摄像头画面 → AI 识别 → 结果呈现 → 异常告警 → 人员处置
```

用户真正要做的事就五件：**看画面 → 收告警 → 查记录 → 管人员 → 配设备**

### 管理界面五模块

| 模块 | 用户任务 | 当前状态 |
|------|---------|--------|
| **视频监控** | 实时看画面、回放告警片段 | ❌ 完全没有 |
| **告警中心** | 查看告警、处理告警、统计趋势 | ❌ 完全没有 |
| **人脸库** | 增删改人员、上传照片、导入导出 | ❌ 只能整文件替换 |
| **设备管理** | 设备列表、配置下发、模型/资源同步 | ✅ 基本完成 |
| **系统设置** | 备份恢复、服务状态 | ✅ 基本完成 |


### 设计哲学：从"工程师界面"到"管理员界面"

当前后台是**技术视角**——直接暴露了模板、Profile、识别单元、设备分配等底层概念，强迫用户理解系统内部构造才能使用。

但管理员根本不需要知道这些。他只需要回答三个问题：

> 1. **系统在正常运行吗？**——看画面、看设备状态
> 2. **检测到什么了吗？**——看告警、看统计
> 3. **告警对不对？**——验证告警结果

所以产品应该是三层结构：

| 层级 | 面向 | 内容 |
|------|------|------|
| **监控层**（首页） | 所有人 | 实时画面、告警信息流、设备状态——看一眼就知道系统正常不正常 |
| **配置层**（场景化） | 运维人员 | ☑ 抽烟检测 ☑ 安全帽检测 → 选设备 → 一键启用——不暴露技术细节 |
| **专家层**（高级设置） | 高级用户 | 模板编辑、Profile参数、模型选择——现有功能保留但折叠隐藏 |

管理员的典型工作流：

```
新盒子到货 → 上电自动发现 → 在后台勾选检测场景 → 自动渲染配置下发 → 告警开始推送
     ↑                                        ↓
     └──────── 如果告警不对，打开专家设置微调 ──────────┘
```

技术细节（模板/Profile/Overlay/模型绑定）全部在后台自动完成，管理员只关心结果。

### 核心问题

**系统能"配"不能"看"**——配置下发做得很扎实，但管理人员看不到画面、看不到告警、看不到识别结果。就像一个监控室只有控制台没有显示器。

最紧迫的不是优化流程、加权限、做向导，而是先把"看"的能力补上。

---

## 一、整体架构评价

两个项目的架构基础扎实：

- **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. **视频监控**
   - 从管理后台直接查看摄像头实时画面（RTSP/HLS 转发）
   - 告警片段回放（关联告警记录 + 录像片段）

2. **告警中心**
   - 实时告警推送（设备 → agent → 后端 → 页面 SSE）
   - 告警记录列表（时间、设备、规则、截图、视频片段链接）
   - 告警统计趋势（按天/按规则/按设备数量变化）

3. **人脸库管理**
   - 人物列表查看（姓名、照片、注册时间）
   - 新增/编辑/删除人物
   - 上传单张人脸照片 + 自动提取特征向量
   - 增量同步到设备（而不是整文件替换）

4. **Dashboard 实时化**
   - 把视频监控 + 告警信息流 + 设备状态整合到首页

### P1（提升易用性）

4. **场景配置向导**
   - 逐步引导：选模板 → 填参数 → 选视频源 → 选设备 → 预览 → 下发
   - 取代当前四层概念（模板/Profile/识别单元/设备分配）

5. **Agent 主动注册**
   - agent 启动时向管理后端发心跳
   - 设备上电即可被纳管，无需等待 UDP 发现

6. **配置模板渲染自动化**
   - deploy.sh 默认使用模板渲染，不交互选择
   - 模板文件名修正（`std_` 前缀）

### P2（提升健壮性）

7. **用户认证和权限** — 登录 + 角色 + 操作日志
8. **告警规则 UI 管理** — 在后台页面上创建/编辑告警规则
9. **日志结构化 + 检索** — agent 输出 JSON 格式日志，后端提供全文检索

---

## 五.五、检测场景扩展规划

### 当前已有检测能力

| 场景 | 实现方式 | 状态 |
|------|---------|------|
| 安全帽/工鞋/工服 | YOLOv8 PPE 检测 | ✅ 已部署 |
| 人脸检测 + 识别 | SCRFD + ArcFace | ✅ 已部署 |
| 通用目标检测 | YOLOv8n COCO | ✅ 已部署 |
| 区域入侵 | region_event 行为节点 | ✅ 已实现 |
| 摔倒/打架 | action_recog 行为节点 | ✅ 已实现 |

### 需要新增的检测场景

| 场景 | 实现思路 | AI 依赖 | 管理界面需求 | 优先级 |
|------|---------|---------|-------------|--------|
| **抽烟检测** | 训练抽烟行为分类模型，或 YOLO 检测烟头+手部 | 需新模型 | 告警规则：灵敏度、时间段、区域 | P0 |
| **睡岗检测** | 姿态估计 + 静止时长判断；或检测人体趴卧姿势 | 需新模型或复用 pose | 告警规则：静止时长阈值、豁免区域 | P0 |
| **打电话检测** | 检测手部靠近耳侧 + 手机目标 | 需新模型 | 同抽烟检测 | P1 |
| **明火/烟雾检测** | YOLO 火灾检测模型 | 需新模型 | 告警规则：灵敏度 | P1 |
| **离岗检测** | 检测区域无人 + 超时告警 | 复用现有检测 | 告警规则：岗位区域、超时时长 | P1 |
| **通道堵塞** | 检测通道区域内目标数量和停留时间 | 复用现有检测 | 告警规则：通道区域、堵塞阈值 | P2 |
| **反光衣检测** | 高可见度服装分类模型 | 需新模型 | 同 PPE 检测 | P2 |
| **车辆违停** | 车辆检测 + 停留超时 | 需车辆检测模型 | 告警规则：禁停区域、停留时长 | P2 |

### 实现架构

所有新场景统一走现有插件架构，不增加新的系统复杂度：

```
摄像头 → 预处理 → AI检测节点 → 结果后处理 → 行为判定节点 → 告警
                                                    ↓
                                              OSD叠加 → 推流/录像
```

- **新增 AI 模型**：编译为 `.rknn`，通过模型管理页面上传到设备
- **新增插件**：如果现有 `ai_yolo` / `ai_face_det` 无法覆盖，实现新插入（如 `ai_smoking`）
- **管理界面**：在告警中心增加新规则类型；在识别场景配置中增加场景选择

### 管理界面的场景化演进

当前配置是"技术视角"（模板→Profile→实例→设备分配），最终演进为"业务视角"：

```
场景选择：☑ 安全帽检测  ☑ 抽烟检测  ☐ 睡岗检测  ☑ 人脸识别
    ↓
区域设定：标定摄像头监控区域（ROI）
    ↓
规则配置：灵敏度 / 时间段 / 告警动作
    ↓
一键下发：选择设备 → 渲染配置 → 下发
```

---

## 六、技术债务清单（后续清理）

| 项目 | 说明 |
|------|------|
| `cmd/managerd` 目录名歧义 | 既是源码目录又被 gitignore 匹配为二进制 |
| 模板函数分散 | `modelTypeLabel`、`resourceTypeLabel` 等散落在 NewUI 中，应集中管理 |
| agent 配置示例过时 | `agent.config.example.json` 路径与生产环境不一致 |
| deploy.sh 交互选择 | 应支持完全无交互部署（CI/CD 友好） |
| 测试覆盖率不均匀 | web 包测试 193KB，但主要是模板渲染测试，缺少 service 层集成测试 |