畜牧监控功能需求.md 12KB
畜牧监控 — 功能需求
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 模块总览
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 新增与维护
flowchart LR
A[点击新增] --> B[填写表单]
B --> C{前端校验}
C -->|不通过| B
C -->|通过| D[保存]
D --> E[返回列表并可见新记录]
4.3 删除
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 + 前端播放器 |