牦牛疾病预警 — 功能需求
1. 文档说明
| 项 |
说明 |
| 模块名称 |
牦牛疾病预警 |
| 目标 |
汇聚、查询与展示物联监测或第三方平台产生的牦牛健康异常预警，支撑牧场巡护与产业侧风险发现，并为「养殖产业数据」等看板的「预警牦牛数量」等指标提供数据基础 |
| 关联系统 |
业务后台（列表、详情、同步）；移动端（「健康预警」列表查阅） |
| 修订依据 |
同目录 牦牛疾病预警功能需求-草稿.md；界面原型（Snipaste_2026-05-19_12-32-20.jpg 后台列表；Snipaste_2026-05-21_15-06-50.jpg 移动端列表） |
本文档仅描述功能需求与业务规则，不涉及库表结构、接口路径、请求参数字段命名、技术栈选型及实现方案。
2. 术语与枚举
2.1 预警记录
- 以单次异常事件为粒度的一条记录：某头牦牛在某一时刻因监测指标越界或规则命中而产生的预警。
- 同一牦牛可存在多条历史预警；列表按条展示，不合并为一条（若第三方重复推送，同步层宜去重，见 §5.3）。
- 本模块以查询、同步、只读详情为主；不提供界面内手工新建、修改、删除预警。
2.2 字段含义
| 字段 |
说明 |
| 牦牛编号 |
与「牦牛资产档案管理」、第三方生产管理系统一致，用于关联单头牦牛 |
| 预警时间 |
事件时间，展示到秒（YYYY-MM-DD HH:mm:ss），时区与项目统一（默认 Asia/Shanghai） |
| 所属牧场 |
预警发生时牦牛归属牧场名称；宜与「牧场管理」或第三方映射名称一致 |
| 预警信息 |
面向用户的自然语言说明（见 §2.3） |
详情页须展示上述全部业务字段；若第三方同步扩展字段（如预警类型、实测值、参考范围），宜在详情中一并只读展示，列表可不全部展开。
2.3 预警信息（内容要求）
预警信息为只读文案，由第三方或规则引擎生成，不在本模块编辑。宜包含可理解的要素：
| 要素 |
示例 |
| 实测值 |
当前实测体温 39.8℃ |
| 参照标准 |
正常体温参考范围 |
| 触发结论 |
超出参考范围，触发体温异常预警 |
原型示例：「当前实测体温39.8℃，超出正常体温参考范围，触发体温异常预警。」
预警类型（示例，全集以对接为准）：
| 类型 |
含义概要 |
| 体温异常 |
体温超出阈值或参考区间（物联监测，若第三方提供） |
| 运动量异常 |
运动量显著偏离常态（若第三方提供） |
| 检疫集中预警 |
某自然日、某地区检疫结果异常或阳性记录集中（≥3 条） |
| 诊疗集中预警 |
某自然日、某地区发病/诊疗记录集中（≥3 条） |
| 其他 |
第三方扩展指标，文案由数据源给出 |
本期列表可不单独增加「预警类型」列，类型含义宜体现在「预警信息」中；若产品要求列表筛选「预警类型」，须评审后增补。
2.4 数据来源
| 来源 |
说明 |
| 第三方生产管理系统 |
主要来源；用户触发同步时依次拉取检疫记录、诊疗记录、养殖过程记录三类 OpenAPI 列表，落库后由本系统规则集中分析生成预警（与牦牛资产、牧场同源 third-party.farming） |
| 物联监测（可选） |
若第三方仍推送体温/运动量类单条预警，可经分析或直写 biz_yak_disease_warning；本期以检疫/诊疗集中规则为主 |
| 本系统规则引擎 |
对本地健康源表未分析记录执行集中判断；分析后置 已分析，同一条源记录不再重复判断 |
2.5 与主数据、他模块
- 牦牛编号宜能在「牦牛资产档案」中查到；档案缺失时仍展示预警，并可提示「档案未同步」。
- 所属牧场宜对应「牧场管理」养殖主体；名称不一致时以预警数据展示名为准。
- 预警为监测风险提示，不自动发起疫病诊疗、AI 诊断、兽医接诊等流程。
3. 功能范围
本期实现：
| 能力 |
说明 |
| 预警列表（后台） |
预警日期范围、所属牧场筛选；分页；列见 §5.1 |
| 查看详情（后台） |
只读展示本条预警全部字段，见 §5.4 |
| 数据同步 |
从第三方拉取/更新，见 §5.3 |
| 健康预警列表（移动端） |
只读列表，见 §5.5 |
| 工具栏 |
搜索、重置、同步（后台） |
本期不实现：
- 预警手工录入、编辑、删除、批量「已处理」
- 处置闭环（派单、回访、关闭）及处置记录
- 预警规则/阈值配置界面
- 消息推送、短信、强提醒（仅列表/详情查阅）
- 地图、轨迹、实时物联大屏
- 导出、打印（另立需求）
4. 业务流程
4.1 总体
flowchart TB
T[第三方生产管理系统]
T -->|OpenAPI 检疫/诊疗/养殖过程| S[本地健康源数据]
S -->|规则分析| W[疾病预警]
W --> L[后台：预警列表]
L -->|查看| D[后台：预警详情]
W --> M[移动端：健康预警列表]
W --> O[养殖产业数据等指标]
4.2 后台使用路径
flowchart LR
A[进入模块] --> B[设置筛选条件]
B --> C[搜索]
C --> L[浏览列表]
L --> V[查看详情]
L --> Y[同步]
Y --> C
B --> R[重置]
R --> A
顺序说明：
- 授权用户同步第三方预警（可选定时，见 §8）。
- 按预警日期、所属牧场筛选，分页浏览列表。
- 对单条记录查看详情，只读核对全部字段。
- 移动端用户查阅健康预警列表（同一数据集的不同终端呈现）。
- 「养殖产业数据」等模块引用预警数据做「预警牦牛数量」等统计，不在本模块维护统计界面（口径见 §5.6）。
5. 详细功能需求
5.1 查询预警列表（业务后台）
筛选条件
| 条件 |
规则 |
| 预警日期 |
日期范围：开始日期、结束日期；按「预警时间」的日历日过滤（含起止日当天 00:00:00～23:59:59） |
| 所属牧场 |
精确匹配；下拉来自用户可见牧场；未选则不过滤牧场 |
| 逻辑 |
条件之间为 且 |
日期边界：
| 情形 |
规则（默认约定） |
| 起止均空 |
不按日期过滤 |
| 仅开始日期 |
开始日及之后，至当前日期止 |
| 仅结束日期 |
结束日及之前 |
| 开始晚于结束 |
提示「开始日期不能晚于结束日期」，不查询 |
列表展示
| 列 |
说明 |
| 预警时间 |
§2.2 |
| 牦牛编号 |
§2.2 |
| 所属牧场 |
§2.2 |
| 预警信息 |
§2.3；过长时换行或悬停展示全文 |
| 操作 |
查看（进入 §5.4） |
列表规则
- 分页：默认每页 20 条。
- 排序：默认 预警时间倒序（最新在前）；相同时刻宜有稳定次序（如按记录标识）。
- 搜索：按当前条件查询；重置：清空条件并恢复默认列表。
- 数据权限：仅展示用户权限范围内牧场的预警；牧场下拉与结果一致。
空态
| 情形 |
提示方向 |
| 无任何预警 |
暂无预警数据 |
| 有筛选无结果 |
未找到符合条件的预警 |
5.2 列表工具栏
| 按钮 |
行为 |
| 搜索 |
按 §5.1 条件刷新列表 |
| 重置 |
清空筛选并恢复默认列表 |
| 同步 |
执行 §5.3；进行中宜防重复点击 |
5.3 第三方同步
| 项 |
要求 |
| 触发 |
用户点击「同步」；定时任务是否启用另定（§8） |
| 权限 |
仅具备同步权限的角色可执行 |
| 拉取范围 |
分页拉取三类 OpenAPI：检疫记录、诊疗记录、养殖过程记录（与 Apifox 文档一致）；按 external_id 合并写入本地健康源表 |
| 分析生成 |
同步完成后，对 analyzed_flag=0 的源记录执行集中判断：检疫同地区同日异常/阳性 ≥3 条 → 健康预警；诊疗同地区同日 ≥3 条 → 健康预警；养殖过程本期仅标记已分析、不产预警 |
| 已分析标记 |
参与判断的源记录在分析后置 已分析，下次同步不再重复判断 |
| 预警去重 |
源记录分析后置 已分析，同一条健康源不再重复触发；预警表无第三方 ID，按分析批次插入 |
| 成功反馈 |
提示完成及摘要（源记录新增/更新条数、预警生成计入新增摘要）；列表宜可刷新 |
| 失败反馈 |
明确原因（超时、鉴权失败等）；不删除已有本地数据 |
| 部分成功 |
宜区分成功/失败条数（单条源记录映射失败记 failCount） |
| 时区 |
入库与展示统一为项目约定时区（Asia/Shanghai） |
| 与档案同步 |
本模块「同步」仅健康源 + 分析预警；不强制连带「牦牛资产档案」同步 |
同步成功后，列表/详情展示最近一次成功结果；可选展示「数据截至：{最近同步时间}」。
5.4 查看预警详情（业务后台）
| 项 |
要求 |
| 入口 |
列表操作「查看」 |
| 权限 |
具备查询权限即可；须校验该条预警属于用户可见牧场 |
| 模式 |
只读；无保存、编辑、删除按钮 |
展示内容（至少包含）：
- 牦牛编号、预警时间、所属牧场、预警信息（§2.2 全部字段）。
- 若同步数据含扩展项（如预警类型、实测值、参考阈值、设备编号、采集时间等），详情页全部展示；列表未出现的字段仅在详情呈现。
- 可选展示：最近同步时间、数据来源说明（第三方名称）。
交互建议：
- 点击牦牛编号可跳转「牦牛资产档案」详情（只读）；档案不存在时提示「档案未找到，请先同步档案」。本期不强制，未实现不影响预警详情验收。
- 提供返回列表。
5.5 健康预警列表（移动端）
界面标题「健康预警」，与后台为同一预警数据集。
| 项 |
要求 |
| 用户 |
已登录移动端用户（牧民、牧场管理员等） |
| 范围 |
与后台一致的数据权限：仅可见关联牧场下预警 |
| 条目内容 |
牦牛编号（或展示名）、预警时间、预警信息全文（原型在列表直接展示说明，本期可无独立详情页；若文案过长须支持展开或详情页，评审确认） |
| 头像 |
有则展示，无则占位图 |
| 排序 |
预警时间倒序 |
| 加载 |
分页或上拉加载更多，符合移动端通用规范 |
| 能力 |
只读；无删除、编辑、标记已读（除非另立需求） |
| 空态 |
暂无健康预警 |
说明： 移动端原型未体现日期、牧场筛选；本期可不提供筛选；若需与后台一致，作为扩展（§8）。
5.6 与其他模块及统计口径
| 模块 |
关系 |
| 牧场管理 |
牧场下拉、所属牧场展示名与养殖主体主数据一致 |
| 牦牛资产档案管理 |
共用牦牛编号与第三方；详情可跳转档案 |
| 养殖产业数据 |
「预警牦牛数量」：当前自然年 1 月 1 日 0:00 至看板统计日 23:59:59 内，至少 1 条未删除预警的去重牦牛编号头数；牦牛须满足「养殖产业数据」§2.9 纳入范围；本模块不提供统计配置界面 |
| 牧业疫病诊疗服务 |
预警不自动生成诊疗单或接诊会话 |
6. 操作权限矩阵
| 操作 |
后台 |
移动端 |
| 查询列表 |
✓ |
✓ |
| 查看详情 |
✓ |
—（列表直显全文时可为 —） |
| 同步 |
✓ |
— |
| 新增/修改/删除 |
— |
— |
菜单与按钮权限（查询、同步等）按项目角色配置；牧场数据权限同 §5.1。
7. 错误与提示约定
采用项目统一业务错误呈现（如含 code、msg、data），不定义接口形态。
| 场景 |
提示方向（示例） |
| 日期范围非法 |
开始日期不能晚于结束日期 |
| 同步进行中 |
正在同步，请稍候 |
| 同步失败 |
同步失败：{原因摘要} |
| 无权查看 |
无权查看该预警 |
| 记录不存在 |
预警记录不存在或已失效 |
| 列表无数据 |
暂无预警数据 / 未找到符合条件的预警 |
8. 非功能需求（建议）
| 类别 |
建议 |
| 权限 |
查询、同步分权；牧场隔离 |
| 审计 |
同步记操作日志（操作人、时间、结果摘要） |
| 性能 |
默认宜引导或隐含「近 30 天」等时间范围，避免一次加载全量历史 |
| 定时同步 |
逻辑与手动同步一致，频率可配置 |
| 双语 |
标签与固定文案符合 i18n（汉语 + 藏文） |
| 扩展 |
预警类型筛选、已处理状态、推送、导出、移动端筛选、跳转档案 |
9. 修订说明（相对草稿）
| 草稿条目 |
优化处理 |
列表筛选 startDate/endDate |
改为业务表述「预警日期范围」及边界规则（§5.1） |
| 列表字段 |
明确列顺序、操作「查看」、分页排序（§5.1） |
| 查看所有字段 |
独立 §5.4 详情只读及扩展字段展示 |
| 第三方拉取 |
扩展为 §5.3 同步、去重、失败策略 |
code/msg/data、技术栈 |
技术栈删除；统一错误呈现仅保留 §7（不涉及接口设计） |
| 未写移动端 |
依据原型补充 §5.5 |
| 未写他模块关系 |
§5.6 与产业数据统计口径 |
10. 功能追溯
| 草稿/原型能力 |
章节 |
| 预警列表 + 日期 + 牧场 + 分页 |
§5.1 |
| 牦牛编号、预警时间、所属牧场、预警信息 |
§2.2、§5.1 |
| 查看预警（全部字段） |
§5.4 |
| 第三方数据 |
§5.3 |
| 后台列表原型 |
§5.1、§5.2 |
| 移动端健康预警 |
§5.5 |
11. 修订记录
| 版本 |
日期 |
说明 |
| 1.0 |
2026-05-21 |
初版：草稿 + 双端原型整理，仅功能需求 |
| 1.1 |
2026-05-20 |
对齐草稿：三类健康源 OpenAPI 同步 + 集中分析规则；预警类型 3/4 |
