# 牦牛疾病预警 — 功能需求

## 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 总体

```mermaid
flowchart TB
    T[第三方生产管理系统]
    T -->|OpenAPI 检疫/诊疗/养殖过程| S[本地健康源数据]
    S -->|规则分析| W[疾病预警]
    W --> L[后台：预警列表]
    L -->|查看| D[后台：预警详情]
    W --> M[移动端：健康预警列表]
    W --> O[养殖产业数据等指标]
```

### 4.2 后台使用路径

```mermaid
flowchart LR
    A[进入模块] --> B[设置筛选条件]
    B --> C[搜索]
    C --> L[浏览列表]
    L --> V[查看详情]
    L --> Y[同步]
    Y --> C
    B --> R[重置]
    R --> A
```

**顺序说明：**

1. 授权用户**同步**第三方预警（可选定时，见 **§8**）。  
2. 按**预警日期**、**所属牧场**筛选，**分页**浏览列表。  
3. 对单条记录**查看详情**，只读核对全部字段。  
4. 移动端用户查阅**健康预警**列表（同一数据集的不同终端呈现）。  
5. 「养殖产业数据」等模块引用预警数据做「预警牦牛数量」等统计，**不在本模块维护统计界面**（口径见 **§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 |