# 畜牧监控 — 功能需求

## 1. 文档说明

| 项 | 说明 |
| --- | --- |
| 模块名称 | 畜牧监控（视频监控系统 · 对接畜牧监控） |
| 目标 | 在业务后台登记、查询、维护**监控点位**台账（名称、所属主体、安装位置、接入地址等），为后续对接视频监控平台、按主体维度查看实时画面提供主数据 |
| 关联系统 | 业务后台；依赖「牧场管理（养殖主体）」「交易市场管理」主数据 |
| 修订依据 | 同目录 `畜牧监控能需求-草稿.md`、界面原型（`Snipaste_2026-05-21_20-00-03.jpg`） |

本文档**仅描述功能需求与业务规则**，不涉及数据库表结构、接口路径、请求体字段命名、HTTP 报文、权限标识命名及技术栈选型。

---

## 2. 术语与业务对象

### 2.1 监控点位（一条台账记录）

- 表示在某一**养殖主体**或**交易市场**辖区内安装的一路（个）视频监控接入点。  
- 由授权用户在后台**手工登记**；外部监控系统自动同步落账可在实施阶段扩展，**本期默认手工登记为主**。  
- 每条记录**必须且仅能**关联一个**所属主体**；主体类型在登记时由所选主数据确定（养殖主体或交易市场二选一）。

### 2.2 所属主体

| 主体类型 | 数据来源（业务模块） | 选用规则 |
| --- | --- | --- |
| **养殖主体** | 「产业数据模型及服务 · **牧场管理**」 | **未逻辑删除**且**经营状态**为「**正常**」的养殖主体（牧场/养殖户） |
| **交易市场** | 「畜牧流通资源管理 · **交易市场管理**」 | **未逻辑删除**且**运营状态**为「**正常**」的交易市场 |

新增/编辑时，**所属主体**为**单选下拉**，支持输入关键字**模糊检索**选项；选项列表为上述两类主数据的**合并结果**。界面宜区分展示主体类型（如标签「养殖主体」「交易市场」），避免同名混淆。

**停业、注销**状态的养殖主体或交易市场**不可选**（与「市场行情登记」渠道选市场等模块口径一致）。

**主数据约束：**

- 仅能选择主数据中**当前有效**的记录，**不允许**手工输入名称替代选择。  
- 若对应模块尚无可用主数据，应提示用户先维护牧场或交易市场（如「请先在牧场管理中维护养殖主体」）。  
- 已保存的监控记录，若关联主体后来被逻辑删除，列表与详情**仍展示登记时的主体名称**（冗余展示名），编辑时须重新选择有效主体后方可保存。

### 2.3 记录生命周期与删除

- 采用**逻辑删除**：删除后默认不在列表展示，数据保留供审计；**本期无**回收站。  
- **本期无**发布/下架等与移动端展示相关的状态；登记保存后即可被列表查询与详情查看。

---

## 3. 功能范围

### 3.1 本期实现

| 能力 | 说明 |
| --- | --- |
| 监控列表 | 分页、筛选；**§5.1** |
| 新增监控 | 表单校验与保存；**§5.2** |
| 修改监控 | 全字段可改；**§5.3** |
| 查看监控 | 只读详情；**§5.4** |
| 删除监控 | 逻辑删除；**§5.5** |
| 列表/行内入口 | 「查看实时监控」；**§5.6**（调用 play-url 接口播放，不落库） |
| 第三方同步 | 从生产管理系统拉取监控列表 upsert；**§3.3** |

### 3.2 本期不实现

| 项 | 说明 |
| --- | --- |
| 批量导入导出 | 未要求 |
| 地图选点、经纬度维护 | 未要求 |
| 监控在线状态探测、告警、录像回放 | 未要求 |
| 移动端监控查看 | 未要求 |

### 3.3 第三方同步（v1.2 / v1.3）

| 能力 | 说明 |
| --- | --- |
| 同步入口 | 列表页 **同步** 按钮（需按钮权限） |
| 数据来源 | 第三方「查询监控数据」 |
| 落库规则 | 以**摄像头 ID**为键新增或更新点位台账（名称、圈舍、视频来源等） |
| 播放地址 | **不同步、不落库**；查看实时视频时按需调用 play-url（**§5.6**） |
| 失败处理 | 单条失败不阻断整批；完成后提示新增/更新/失败条数 |
| 与手工登记 | 同步后可继续编辑主体、安装位置；再次同步覆盖第三方映射字段，保留本地主体与安装位置 |

**同步写入的核心字段**：摄像头 ID、监控名称、圈舍、视频来源、第三方主体名称（冗余 `owner_name` 文本）。

---

## 4. 业务流程

### 4.1 模块总览

```mermaid
flowchart TD
    A[进入畜牧监控] --> B[监控列表]
    B --> C{操作}
    C --> D[搜索 / 重置]
    C --> E[新增]
    C --> F[查看]
    C --> G[编辑]
    C --> H[删除]
    C --> I[查看实时监控]
    E --> B
    G --> B
    H --> B
    I --> K[拉取 play-url 并播放]
```

### 4.2 新增与维护

```mermaid
flowchart LR
    A[点击新增] --> B[填写表单]
    B --> C{前端校验}
    C -->|不通过| B
    C -->|通过| D[保存]
    D --> E[返回列表并可见新记录]
```

### 4.3 删除

```mermaid
flowchart TD
    A[点击删除] --> B[二次确认]
    B -->|取消| C[无变更]
    B -->|确定| D[逻辑删除]
    D --> E[列表不再展示该记录]
```

---

## 5. 功能需求明细

### 5.1 监控列表

**页面结构（与原型一致）**

- 顶部**筛选区**：监控名称、所属主体；按钮 **搜索**、**重置**、**新增**。  
- 下方**表格**：监控名称、所属主体、安装位置、操作列。

**筛选规则**

| 筛选项 | 规则 |
| --- | --- |
| 监控名称 | 选填；对名称**模糊**匹配（trim 后参与匹配） |
| 所属主体 | 选填；对所选主体**精确**匹配（仅列出关联该主体的监控） |
| 组合 | 多条件为 **且** 关系；空条件表示不过滤该项 |

**筛选区「所属主体」下拉**

- 与新增/编辑表单**相同数据源与交互**：养殖主体（正常）+ 交易市场（正常）合并列表，支持关键字模糊检索；**不要求**仅列出已有关联监控的主体。  
- 未选择主体时，不按主体维度过滤。

**交互**

- 仅点击 **搜索** 后按当前条件刷新列表（与平台其他台账模块一致）。  
- **重置** 清空筛选条件并恢复默认列表（通常为全部未删除记录的第一页）。  
- 默认按**创建时间倒序**展示（新登记在前）；分页默认每页 **20** 条，支持翻页。

**列表展示**

| 列 | 说明 |
| --- | --- |
| 监控名称 | 登记名称 |
| 所属主体 | 展示主体名称；宜带类型标识（养殖主体 / 交易市场） |
| 安装位置 | 登记安装位置 |
| 操作 | 查看实时监控、查看、编辑、删除（权限控制见 **§6**） |

> **列表不展示 IP 地址**；IP 仅在**查看详情**、**新增/编辑**表单中展示与维护（与列表原型列一致，完整台账字段见 **§5.2**）。

### 5.2 新增监控

**入口：** 列表页 **新增**。

**表单字段**

| 字段 | 规则 |
| --- | --- |
| 监控名称 | **必填**；**1～10** 个字符（按字符计，trim 后校验）；不可为纯空白 |
| 所属主体 | **必填**；**单选**；下拉数据 = 有效养殖主体 ∪ 有效交易市场；支持模糊搜索；见 **§2.2** |
| 安装位置 | **必填**；**1～10** 个字符；不可为纯空白 |
| IP 地址 | **必填**；须为合法 **IPv4** 地址格式（如 `192.168.1.100`）；总长度 **≤ 20** 个字符；**本期不支持** IPv6 与域名 |

**唯一性（本期）**

- **不校验**监控名称在全局或同一所属主体下是否重复；**不校验** IP 地址是否已被其他监控占用；允许多条记录名称、IP 相同（由业务自行规范，系统不拦截）。

**保存结果**

- 校验通过后写入一条新记录，**立即**在列表中可查（满足筛选条件时）。  
- 失败时停留在表单并提示具体字段原因（见 **§8**）。

**弹窗/页面**

- 与原型一致，可采用弹窗表单；表单须包含 **IP 地址** 字段（草稿要求，列表原型弹窗未画出时以本文为准）；**确定** 提交，**取消** 关闭且不保存。

### 5.3 修改监控

**前置：** 记录未逻辑删除。

**规则：**

- **§5.2** 中全部字段均可修改，校验规则与新增一致。  
- 允许更换所属主体（仍在养殖主体与交易市场有效集合内选择）。  
- 保存成功后列表与详情展示最新内容。

**限制：**

- 已逻辑删除的记录不可编辑。

### 5.4 查看监控

**入口：** 列表 **查看**。

**规则：**

- 只读展示 **§5.2** 全部字段（含 IP 地址、所属主体类型与名称）。  
- 可提供 **编辑** 快捷入口（有编辑权限时），跳转或打开编辑表单。

### 5.5 删除监控

**入口：** 列表 **删除**。

**规则：**

- 操作前须**二次确认**（如「是否确认删除该监控？」）。  
- 确认后执行**逻辑删除**，列表默认不再展示。  
- **本期不校验**下游视频平台、大屏等是否引用（若后续对接产生引用，删除约束另文约定）。

### 5.6 查看实时监控（v1.3）

**入口：** 列表 **查看实时监控**。

**行为：**

- 须已登记 **摄像头 ID**（`monitor_id`）；无则提示先维护点位。  
- 点击后由后台按摄像头 ID 调用第三方「获取监控视频播放地址」，返回 **videoUrl**（如 HLS/m3u8）；**不持久化**到台账表。  
- 前端弹窗内嵌入播放器播放；失败时展示可读错误（第三方不可用、点位不存在、播放地址为空等）。  
- 须具备 **查询** 类权限（与查看详情同级）。

**说明：** 播放地址有时效性，每次预览宜重新拉取；与 **§3.3 同步** 解耦。

---

## 6. 操作与权限

| 操作 | 说明 |
| --- | --- |
| 列表查询 | 进入模块、搜索、重置 |
| 新增 | 打开新增表单并保存 |
| 查看 | 只读详情 |
| 编辑 | 修改未删除记录 |
| 删除 | 逻辑删除 |
| 查看实时监控 | 按摄像头 ID 拉取 play-url 并播放（v1.3） |
| 第三方同步 | 从生产管理系统拉取监控列表 upsert（v1.2+） |

列表级按钮与行内操作须受平台**菜单与按钮权限**控制；无权限时不展示或禁用，与若依惯例一致（具体权限命名由技术方案定义，本文不展开）。

---

## 7. 与上下游模块关系

| 模块 | 关系 |
| --- | --- |
| **牧场管理** | 提供「养殖主体」主数据；仅有效主体可被关联 |
| **交易市场管理** | 提供「交易市场」主数据；仅有效市场可被关联 |
| **视频监控平台（规划）** | v1.3 已通过 play-url 接口支持列表内实时预览；播放地址不落库 |
| **养殖产业数据 / 大屏等** | 本期**无**直接引用；若未来按主体统计监控路数，口径以本文台账为准 |

---

## 8. 提示与校验约定（示例）

| 场景 | 示例文案 |
| --- | --- |
| 必填 | 「请填写监控名称」「请选择所属主体」 |
| 长度 | 「监控名称不能超过 10 个字」「安装位置不能超过 10 个字」 |
| IP | 「请输入正确的 IP 地址」「IP 地址不能超过 20 个字符」 |
| 主数据为空 | 「请先在牧场管理/交易市场管理中维护正常状态的主体数据」 |
| 主体不可选 | 「该主体已停业或注销，请重新选择」 |
| 删除确认 | 「是否确认删除该监控？」 |
| 实时监控 | 「无法获取播放地址」「监控点位不存在或已删除」 |
| 已删除 | 「记录不存在或已删除」 |

---

## 9. 非功能建议

- 列表分页在常规数据量下响应可接受；主体下拉模糊搜索宜防抖，避免一次输入触发过多请求。  
- 操作日志：新增、修改、删除宜记入平台审计日志（与若依其他业务模块一致）。  
- 用语与原型、菜单名称「畜牧监控」「监控列表」保持一致。

---

## 10. 修订记录

| 版本 | 说明 |
| --- | --- |
| 1.0 | 依据草稿与原型整理：监控点位 CRUD、主体双源下拉、列表筛选、实时监控本期不实现；剔除库表/接口/技术栈描述 |
| 1.1 | 评审确认：列表不展示 IP；筛选/表单主体下拉一致且仅「正常」主数据；本期不校验名称/IP 唯一；实时监控采用可点击提示方案 |
| 1.2 | **第三方同步**（§3.3）：拉取监控点位；字段扩展为摄像头 ID、圈舍、视频来源；移除 IP；主体与安装位置可选 |
| 1.3 | 同步**不再**落库播放地址；**§5.6** 实时预览：按需 play-url + 前端播放器 |