# 大屏 — 疫病风险统计 — 功能需求

## 1. 文档说明

| 项 | 说明 |
| --- | --- |
| 模块名称 | 大屏疫病风险统计 |
| 使用场景 | 领导参观、指挥调度、对外展示等**大屏端**只读看板 |
| 目标 | 按**统计年份**集中展示实验室检测、疫情上报、检疫态势与风险因子权重等疫病相关指标，支撑疾病监测与风险研判 |
| 数据来源 | **实验室检测**、**疫情上报**、**检疫站管理**、**风险因子设置**（权重只读展示）；气象展示由**前端**调用公开气象接口，**不在**本大屏业务后台数据范围内 |
| 修订依据 | 同目录 `大屏疫病风险功能需求-草稿.md`、`Snipaste_2026-05-25_19-26-51.jpg`、`Snipaste_2026-05-25_19-27-07.jpg`；指标口径与《实验室检测功能需求》《疫情上报功能需求》《检疫站管理功能需求》《风险因子设置功能需求》对齐 |
| 关联维护 | 台账补录、疫情解除、检疫站状态变更、权重调整须在对应业务后台完成；大屏刷新后展示最新结果 |

本文档仅描述**功能需求、业务规则与展示逻辑**，不涉及数据库结构、接口路径、请求体字段及技术实现选型。

---

## 2. 术语与口径

### 2.1 统计年份

- 大屏顶部（或全局筛选区）提供**统计年份**选择，格式为自然年 **YYYY**（如 `2026`）。
- 进入大屏时默认选中**当前自然年**。
- 变更统计年份后，本页**全部统计区块**须**同步**按新年份重新计算与展示，不得出现区块之间年份不一致。

### 2.2 统计月份（按月图表）

大屏存在两类按月图表，横轴规则**不同**：

| 类型 | 适用区块 | 横轴规则 |
| --- | --- | --- |
| **统计年 Y 内 1～12 月** | （本期无；样本来源等为年度汇总非按月趋势） | — |
| **滚动最近 12 个月** | **实验室检测 · 按月趋势** | 以服务器当前年月为锚点，取**含当月在内向前连续 12 个自然月**；**不**随页面「统计年份 **Y**」切换 |

**滚动最近 12 个月（实验室检测趋势）**

- 接口每条记录含 **`statYear`（自然年）**、**`month`（1～12）**；按时间升序固定返回 **12** 条。
- 缺月：`testQuantity`、`positiveCount` 为 **0**；**不**省略刻度。
- **前端横轴**仅展示月份（如 `8月`）；**鼠标悬停**展示完整年月（如 `2025年8月`）及检测量、阳性数。
- 切换统计年份 **Y** 时，该趋势图**仍展示同一滚动窗口**（与 **Y** 无关）；**样本来源检测**等仍按 **Y** 汇总（**§2.3**）。

### 2.2.1 缺月规则（滚动 12 月窗口内）

- 某自然月窗口槽位内无任何纳入 **§2.3** 检测日期的记录时，该月检测量、阳性检出数按 **0** 参与展示；**不**断线留空、**不**插值。

### 2.3 实验室检测纳入统计的规则

**样本来源检测（年度汇总）** — 选定统计年份 **Y** 后，纳入记录须满足 **检测日期**落在 **Y** 年内（`Y-01-01`～`Y-12-31`）。

**实验室检测 · 按月趋势及趋势区年度三指标（检测量/阳性数/检出率）** — 纳入 **距当前时间最近 12 个自然月**窗口内、`test_date` 落在窗口内的全部检测记录；**不**随 **Y** 切换。

### 2.4 疫情上报纳入统计年份的规则

选定统计年份 **Y** 后，不同区块对疫情上报记录的纳入范围如下（须全文统一）：

| 统计用途 | 纳入条件 |
| --- | --- |
| 按**上报日期**统计（风险等级、疫病类型、传播途径、疫情列表等） | **上报日期**落在 **Y** 年内 |
| **防控中地区**计数 | **上报日期**落在 **Y** 年内，且处置状态为**未解除** |
| **已解除地区**计数、**解除时效** | 处置状态为**已解除**，且**解除日期**落在 **Y** 年内（上报日期可早于 **Y**） |

已逻辑删除或不可见的疫情上报记录**不参与**任何统计。

### 2.5 涉疫地区（统计口径）

草稿中的「防控中地区」「已解除地区」按**涉疫点位/轨迹**字段去重计数：

| 项 | 说明 |
| --- | --- |
| 地区认定 | 以一条疫情上报记录中的**涉疫点位/轨迹**全文作为地区标识；**完全相同**的文案计为 **1** 个地区 |
| 防控中地区数 | 满足 **§2.4**「防控中」条件的记录，对其涉疫点位/轨迹**去重**后的个数 |
| 已解除地区数 | 满足 **§2.4**「已解除且解除日在 Y」的记录，对其涉疫点位/轨迹**去重**后的个数 |

> 若产品后续增加结构化「行政区划」字段，须修订本节及 **§5.6**。

### 2.6 枚举与后台一致（展示用中文标签）

**样本来源**（实验室检测，单选枚举）：

| 取值 | 展示名称 |
| --- | --- |
| 场地抽检 | 场地抽检 |
| 疫情上报送检 | 疫情上报送检 |
| 调运检疫 | 调运检疫 |
| 日常检测 | 日常检测 |

**风险等级**（疫情上报）：

| 取值 | 展示名称 |
| --- | --- |
| 高危 | 高危 |
| 中危 | 中危 |
| 低危 | 低危 |

**疫病类型**（疫情上报）：

| 取值 | 展示名称 |
| --- | --- |
| 病毒性疫病 | 病毒性疫病 |
| 细菌性疫病 | 细菌性疫病 |
| 寄生虫疫病 | 寄生虫疫病 |
| 其他类疫病 | 其他类疫病 |

**传播途径**（疫情上报）：

| 取值 | 展示名称 |
| --- | --- |
| 调运传入 | 调运传入 |
| 本地扩散 | 本地扩散 |
| 环境感染 | 环境感染 |
| 其他未知 | 其他未知 |

**检疫站运营状态**（检疫站管理）：

| 取值 | 展示名称 | 大屏统计用途 |
| --- | --- | --- |
| 正常 | 正常 | 计入**可用检疫点** |
| 停业 | 停业 | 计入**停用检疫点** |
| 注销 | 注销 | 计入**停用检疫点**（与停业合并展示，或分开展示以产品定稿为准） |

> 草稿写「可用/停用」；**注销**站点不宜视为可用，默认归入**停用检疫点**统计；若原型仅两档卡片，则停业+注销合计为停用数。

**风险因子（权重展示，固定五项）**：

养殖密度、交通流动性、检疫强度、气象适宜度、既往发病水平——名称与《风险因子设置功能需求》**§2.1** 一致；大屏**只读展示**当前已保存权重，**不可**在大屏修改。

### 2.7 比率与汇总口径

| 指标 | 计算口径 |
| --- | --- |
| 阳性检出率（年度） | 当年纳入记录的 **阳性检出数合计 ÷ 检测量合计**；检测量合计为 0 时展示 **0%** 或 **—**（产品择一，全文统一） |
| 阳性检出率（单月） | 当月阳性检出数 ÷ 当月检测量；当月检测量为 0 时为 0 |
| 样本来源占比 | 某来源检测量 ÷ 当年检测量合计；合计为 0 时各来源占比为 0，走 **§7.2** 空态 |
| 风险等级占比 | 某等级上报条数 ÷ 当年按上报日纳入的上报总条数；总数为 0 时走空态 |
| 疫病类型占比 | 某类型上报条数 ÷ 当年按上报日纳入的上报总条数 |
| 传播途径占比 | 某途径上报条数 ÷ 当年按上报日纳入的上报总条数 |
| 单条解除时效（天） | **解除日期 − 上报日期**（自然日差，与后台「解除」规则一致：解除日不得早于上报日） |
| 某疫病类型解除时效（平均） | 对该类型、满足 **§2.4** 已解除条件的记录，先算每条单条解除时效，再求**算术平均值**；该类型下记录数为 0 时不参与展示或按 **§7.1** 空态 |

---

## 3. 功能范围与边界

### 3.1 范围内

- 统计年份筛选与整页刷新；
- **气象数据**展示区（由前端调用公开免费气象接口，见 **§5.1**）；
- **样本来源检测**、**实验室检测**（含按月趋势）；
- **疫病风险**（风险等级占比饼图）；
- **疫病态势**（检疫点与地区计数卡片）；
- **疫情上报情况**分页列表；
- **疫病类型分布**、**疫病解除时效**、**传播途径**统计图；
- **风险因子指数**（五项权重只读展示）；
- 无数据、加载中、加载失败等状态展示。

### 3.2 范围外

- 实验室检测、疫情上报、检疫站、风险因子权重的**增删改**；
- 气象接口选型、密钥、调用频率等技术实现（属前端/部署）；
- 基于权重自动跑分、地图轨迹绘制、消息推送；
- 导出、打印；下钻后台维护菜单（若后续增加外链须单独评审）；
- 大屏端权限与网关策略（由部署约定，本文档不展开）。

---

## 4. 业务流程概览

```mermaid
flowchart TD
    A[打开大屏疫病风险页] --> B[默认当前统计年份]
    B --> C[加载实验室检测与疫情上报等数据]
    C --> D[渲染各统计区块与列表]
    E[前端加载气象展示] --> D
    J[用户切换统计年份] --> C
    K[后台维护数据后] --> L[刷新或重新进入大屏]
    L --> C
```

**典型使用顺序：**

1. 用户进入大屏，系统按**当前年**加载并展示各区块；气象区由前端并行获取外部数据。  
2. 用户切换统计年份 → 全页统一 Loading → 各区块按 **Y** 重算。  
3. 运营人员在后台补录检测、上报疫情、解除疫情或调整检疫站状态后，大屏通过**重新进入、手动刷新或约定自动轮播周期**更新（**不要求**秒级实时同步）。

---

## 5. 页面结构与区块需求

布局以原型 `Snipaste_2026-05-25_19-26-51.jpg`、`Snipaste_2026-05-25_19-27-07.jpg` 为准，逻辑分区如下。

### 5.1 全局：统计年份与气象数据

| 项 | 规则 |
| --- | --- |
| 统计年份 | 见 **§2.1**；变更后触发**整页**业务数据重载 |
| 气象数据 | **不由**疫病风险后台模块提供；由**前端**调用网上免费气象接口展示（温湿度、降水等，以原型为准）；接口失败时气象区单独失败提示，**不影响**其余区块是否展示（若产品要求「气象失败则整页失败」须单独定稿） |

---

### 5.2 区块一：样本来源检测

| 项 | 规则 |
| --- | --- |
| 统计对象 | **§2.3** 统计年 **Y** 内全部实验室检测记录 |
| 统计维度 | 按 **§2.6** 样本来源分类，汇总各来源 **检测量（份）** |
| 展示内容 | 各来源检测量及占当年检测量合计的**占比**；可用饼图、环形图或条形图（以原型为准） |
| 展示形式 | 须能区分四类来源；图例与标签一致 |
| 无数据 | 当年检测量合计为 0 时 **§7.2** |

---

### 5.3 区块二：实验室检测（年度 + 按月趋势）

#### 5.3.1 趋势区汇总（滚动 12 月）

| 项 | 规则 |
| --- | --- |
| 检测量 | 最近 12 月窗口内 **检测量** 合计（份） |
| 阳性检出数 | 同上 **阳性检出数** 合计 |
| 阳性检出率 | **§2.7**；建议以 **%** 展示 |

#### 5.3.2 按月趋势

| 项 | 规则 |
| --- | --- |
| 图表类型 | **折线图**（或面积图，以产品定稿为准） |
| 数据系列 | ① 检测量（份）；② 阳性检出数（份） |
| 数据范围 | **§2.2** 滚动最近 **12** 个自然月 |
| 横轴 | 12 个刻度，**仅显示月份**；悬停显 **YYYY年M月** |
| 图例 | 两系列须有明确图例与颜色区分 |
| 缺月 | 按 **§2.2.1** 为 0 |

---

### 5.4 区块三：疫病风险（风险等级占比）

| 项 | 规则 |
| --- | --- |
| 图表类型 | **饼图**（原型为饼状/3D 饼图时以视觉为准） |
| 统计对象 | **§2.4** 按上报日期纳入的疫情上报记录 |
| 统计维度 | 按 **§2.6** 风险等级（高危 / 中危 / 低危）计数 |
| 展示内容 | 各等级**条数**及占当年上报总条数的**占比** |
| 无数据 | 当年上报总条数为 0 时 **§7.2**；**不**展示 100% 单级假象 |

---

### 5.5 区块四：疫病态势（指标卡片）

| 项 | 规则 |
| --- | --- |
| 可用检疫点 | **检疫站管理**中运营状态为**正常**的站点**个数**（与统计年份无关，为**当前主数据快照**；变更年份不改变该数，除非产品要求按年快照——默认**实时**） |
| 停用检疫点 | 运营状态为**停业**或**注销**的站点个数（规则同左） |
| 防控中地区 | **§2.5** 防控中地区数（个），与统计年份 **Y** 相关 |
| 已解除地区 | **§2.5** 已解除地区数（个），与统计年份 **Y** 相关 |

> **说明：** 检疫点数为**站点台账**统计；地区数为**疫情上报**衍生统计，二者含义不同，界面文案须区分「检疫点」与「地区」。

---

### 5.6 区块五：疫情上报情况（列表）

| 项 | 规则 |
| --- | --- |
| 范围 | **§2.4** 按上报日期纳入 **Y** 年的全部疫情上报记录 |
| 展示形式 | **分页列表**；**不设**单独详情页或跳转后台详情（列表行内展示查阅所需字段即可） |
| 排序 | 默认按**上报日期**倒序，其次创建时间倒序 |
| 分页 | 支持翻页；每页条数以大屏交互为准（建议 **5～10** 条） |
| 行内至少展示 | 上报日期、传播途径、疫病类型、疫病名称、风险等级、涉疫点位/轨迹（可截断）、处置状态（未解除/已解除）、解除日期（已解除时） |

**不提供**大屏上的新增、修改、解除、删除操作。

---

### 5.7 区块六：疫病类型分布

| 项 | 规则 |
| --- | --- |
| 图表类型 | 饼图或占比条形图（以原型为准） |
| 统计对象 | **§2.4** 按上报日期纳入的记录 |
| 统计维度 | **§2.6** 疫病类型四类 |
| 展示内容 | 各类型条数及占比 |

---

### 5.8 区块七：疫病解除时效

| 项 | 规则 |
| --- | --- |
| 统计对象 | **§2.4** 已解除且解除日期在 **Y** 年内的记录 |
| 统计维度 | 按**疫病类型**分组 |
| 指标 | 各类型 **解除时效平均天数（天）** = 组内每条单条解除时效的**算术平均**，见 **§2.7**；建议保留 **1** 位小数或整数（与项目全局一致） |
| 展示形式 | 柱状图或条形图（以原型为准）；横轴为疫病类型，纵轴为「平均天数」 |
| 无数据 | 该年无任何已解除记录时本区块空态 |

---

### 5.9 区块八：传播途径

| 项 | 规则 |
| --- | --- |
| 统计对象 | **§2.4** 按上报日期纳入的记录 |
| 统计维度 | **§2.6** 传播途径四类 |
| 展示内容 | 各途径**数量**及占上报总数的**占比** |
| 展示形式 | 饼图、条形图等（以原型为准） |

---

### 5.10 区块九：风险因子指数

| 项 | 规则 |
| --- | --- |
| 数据来源 | 《风险因子设置》当前**已保存**的全局权重 |
| 展示因子 | **§2.6** 五项：养殖密度、交通流动性、检疫强度、气象适宜度、既往发病水平 |
| 展示内容 | 各因子名称及其**权重**（建议小数或百分比，与后台录入口径一致） |
| 交互 | **只读**；不提供保存、修改 |
| 未配置 | 后台从未保存过权重时，展示空态或引导「请在风险因子设置中完成配置」 |

> **气象适宜度**：权重来自后台配置；若原型另有「实时气象」数值，属 **§5.1** 前端气象接口展示，**不**与权重混为同一指标 unless 产品明确。

---

## 6. 图表与列表通用规则

| 项 | 规则 |
| --- | --- |
| 标题 | 各区块有明确中文标题（可与原型一致） |
| 单位 | 检测量、阳性数为「份」；时效为「天」；占比以 **%** 展示（建议保留 2 位小数） |
| 跨年 | 仅使用 **§2** 约定的当年纳入规则，**不得**混入其他年份数据 |
| 列表与图表一致 | 列表中的条数与饼图分母须同一纳入口径（**§2.4**） |
| 只读 | 大屏无维护类按钮 |

---

## 7. 异常、空态与刷新

### 7.1 业务数据空态

| 场景 | 展示要求 |
| --- | --- |
| 当年无实验室检测记录 | 样本来源、实验室检测（年度/趋势）展示统一空态；**不**用全 0 冒充有检测业务 |
| 当年无疫情上报（按上报日） | 疫病风险、类型分布、传播途径、上报列表等展示空态 |
| 当年无已解除记录 | 解除时效区块空态；**不影响**防控中/未解除相关区块 |
| 当年有检测但检测量合计为 0 | 按 **§2.7** 展示检出率为 0% 或 —；样本来源占比均为 0 |

### 7.2 加载与失败

| 场景 | 展示要求 |
| --- | --- |
| 切换年份加载中 | 整页或分区块 Loading，避免显示上一年残留数据 |
| 业务数据加载失败 | 明确失败提示，支持**重试** |
| 气象接口失败 | 气象区单独提示；其余区块若已成功加载则照常展示（默认策略） |

### 7.3 数据刷新

- 大屏为**只读**；后台维护后，须通过**重新进入、手动刷新或轮播周期自动刷新**更新（周期建议 **1～5 分钟**，由实施配置）。
- **不要求**与后台变更秒级同步。

---

## 8. 与后台模块的关系

| 后台模块 | 大屏如何使用 |
| --- | --- |
| 实验室检测 | 按检测日期汇总检测量、阳性数、检出率、样本来源、按月趋势 |
| 疫情上报 | 风险等级、类型、途径、列表、解除时效、地区计数（涉疫点位去重） |
| 检疫站管理 | 可用/停用检疫点个数（运营状态） |
| 风险因子设置 | 只读展示五项权重 |
| 气象 | **不经过**上述后台；前端自备 |

---

## 9. 验收要点（功能）

| 编号 | 场景 | 通过标准 |
| --- | --- | --- |
| DYFX-01 | 默认年份 | 进入大屏默认当前年，各区块年份口径一致 |
| DYFX-02 | 切换年份 | 切换后检测/疫情类区块同步更新，无旧年残留 |
| DYFX-03 | 缺月 | 滚动 12 月窗口内仅部分月份有检测时，趋势图仍为 12 槽位，缺月为 0；横轴仅月、悬停显年月 |
| DYFX-04 | 样本来源 | 四类来源占比之和为 100%（有检测时） |
| DYFX-05 | 年度检出率 | 与手工按当年合计计算一致 |
| DYFX-06 | 风险等级饼图 | 仅统计当年上报日记录；占比之和为 100%（有数据时） |
| DYFX-07 | 检疫点 | 可用数=正常站；停用数含停业/注销（与 §2.6 一致） |
| DYFX-08 | 防控/解除地区 | 去重规则与 §2.5 一致；切换年份数字变化正确 |
| DYFX-09 | 上报列表 | 分页正常；仅当年上报日记录；大屏无维护按钮 |
| DYFX-10 | 解除时效 | 仅已解除且解除日在当年；按类型**平均天数**与手工核算一致 |
| DYFX-11 | 风险因子 | 展示与后台已保存权重一致；大屏不可改 |
| DYFX-12 | 后台补录后刷新 | 补录检测或上报后，大屏刷新可见 |
| DYFX-13 | 气象 | 气象由前端展示；失败时不导致业务区块误显示旧气象为「官方数据」 |

---

## 10. 修订记录

| 版本 | 日期 | 说明 |
| --- | --- | --- |
| 1.0 | 2026-05-25 | 由草稿优化：补全流程、口径、十区块需求；对齐疾病检测与上报体系；不涉及库表与接口 |
| 1.1 | 2026-05-25 | 解除时效由加总改为按疫病类型的**平均天数**（§2.7、§5.8、DYFX-10） |
| 1.2 | 2026-07-04 | 实验室检测按月趋势改为**滚动最近 12 月**；接口增 `statYear`+`month`；样本来源仍按 **Y** |

---

## 11. 相对草稿的优化说明

| 草稿问题 | 处理方式 |
| --- | --- |
| 条目罗列、无流程与边界 | 增加 **§3、§4、§7、§9** |
| 气象由前端实现 | 明确 **§5.1** 后台不关注，与业务区块加载解耦 |
| 「地区」未定义 | **§2.5** 按涉疫点位/轨迹去重；与检疫点区分 |
| 疫情统计未区分上报日/解除日 | **§2.4** 分场景约定 |
| 解除时效「总时效」 | **§2.7** 明确为同类型**解除时效平均天数**（非加总） |
| 注销检疫站是否停用 | **§2.6** 默认归入停用检疫点 |
| 样本来源/风险/类型/途径 | 与后台枚举表对齐 **§2.6** |
| 未写空态、刷新、只读 | **§3.2、§7** |
| 参考疾病检测与上报 | **§8** 列明四模块数据来源 |