# 疫情上报 — 功能需求

## 1. 文档说明

| 项 | 说明 |
| --- | --- |
| 模块名称 | 疫情上报 |
| 目标 | 登记、查询、维护畜禽疫情上报信息，支持按传播途径与风险等级筛选，并对已处置疫情执行「解除」闭环 |
| 关联系统 | 业务后台；与「疾病检测与上报」体系其它模块的衔接由产品统一规划 |
| 修订依据 | 同目录 `疫情上报-草稿.md` |

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

---

## 2. 术语与枚举

### 2.1 传播途径（单选）

表示疫情**如何传入或扩散**，新增/修改时必选其一：

| 取值 | 说明 |
| --- | --- |
| 调运传入 | 由调运、引种等带入 |
| 本地扩散 | 在本地畜群间传播、扩散（草稿「扩撒」统一为「扩散」） |
| 环境感染 | 与环境、媒介等相关的感染途径 |
| 其他未知 | 途径尚不明确 |

### 2.2 疫病类型（单选）

表示疫病**病原或类别**，与「传播途径」不同，新增/修改时必选其一：

| 取值 | 说明 |
| --- | --- |
| 病毒性疫病 | — |
| 细菌性疫病 | — |
| 寄生虫疫病 | — |
| 其他类疫病 | — |

### 2.3 风险等级（单选）

| 取值 | 说明 |
| --- | --- |
| 高危 | 传播或损失风险高，处置优先级高 |
| 中危 | — |
| 低危 | — |

### 2.4 处置状态（业务态，非独立录入项）

由是否填写 **解除日期** 推导，用于列表展示与按钮控制：

| 状态 | 条件 | 含义 |
| --- | --- | --- |
| **未解除** | 解除日期为空 | 疫情上报仍视为进行中，可编辑、可执行「解除」 |
| **已解除** | 解除日期已填写 | 疫情已结案，**不可再编辑**、**不可再次解除**；仅可查看、删除 |

> 草稿中「没有解除日期 / 有解除日期」对应上表两种状态。

---

## 3. 功能范围

- 疫情上报的新增、修改、删除、分页列表查询、详情查看  
- **解除**（填写解除日期，将记录置为已解除）  
- 传播途径、风险等级等字段的录入与校验  
- 按传播途径、风险等级的列表筛选  
- 面向使用方的业务错误与校验提示（见第 **8** 章）  

**不在本模块范围（除非后续单独立项）：** 疫情地图轨迹绘制、自动预警推送、与实验室检测单自动关联等。

---

## 4. 业务流程概览

```mermaid
flowchart TD
    A[新增疫情上报] --> B[列表查询/筛选]
    B --> C[查看详情]
    B --> D{未解除?}
    D -->|是| E[修改]
    D -->|是| F[解除并填写解除日期]
    D -->|是| G[删除]
    D -->|否| H[仅查看或删除]
    E --> B
    F --> I[已解除]
    I --> B
    G --> B
    H --> B
```

1. **上报**：录入上报日期、传播途径、涉疫点位/轨迹、疫病类型、疫病名称、风险等级 → 形成一条**未解除**记录。  
2. **查询**：按传播途径、风险等级筛选，分页浏览；默认可按上报日期或创建时间倒序。  
3. **维护（未解除）**：对未解除记录修改全部业务字段。  
4. **解除**：对未解除记录填写解除日期并确认 → 变为**已解除**，停止编辑与再次解除。  
5. **删除**：未解除、已解除均可删除（需权限与确认）；删除后不再参与列表与统计。  
6. **查阅**：任意状态可查看详情；已解除详情为只读（无编辑入口）。

---

## 5. 详细功能需求

### 5.1 新增疫情上报

| 字段 | 规则 |
| --- | --- |
| 上报日期 | **必填**；格式 **YYYY-MM-DD**；表示本条疫情信息的上报日 |
| 传播途径 | **必填**；单选，取值限定为 **§2.1** |
| 涉疫点位/轨迹 | **必填**；文字描述涉疫地点、范围或活动轨迹等；长度上限与项目全局一致（建议 **1～500** 个字符，含标点计数方式与全局一致） |
| 疫病类型 | **必填**；单选，取值限定为 **§2.2**（草稿中误写为第二项「传播途径」的，按疫病类型理解） |
| 疫病名称 | **必填**；具体疫病名称；长度建议 **1～50** 个字符 |
| 风险等级 | **必填**；单选，取值限定为 **§2.3** |
| 解除日期 | **不填**；新增时不得填写；由「解除」操作单独写入 |

**必填字段汇总：** 上报日期、传播途径、涉疫点位/轨迹、疫病类型、疫病名称、风险等级。

**校验：**

- 上报日期格式非法时拒绝保存。  
- 解除日期在新增界面**不可见或不可编辑**（避免与「解除」流程混淆）。  
- 各枚举须为约定取值之一，非法值拒绝保存。

**保存结果：** 记录处置状态为 **未解除**；可被列表查询、修改、解除、删除。

---

### 5.2 查询疫情上报列表

- **传播途径：** **精确**匹配筛选；未选择时不过滤。  
- **风险等级：** **精确**匹配筛选；未选择时不过滤。  
- **分页：** 支持分页；默认 **每页 20 条**，默认首页为第一页；单页条数上限与项目列表通用规范一致（若有）。  
- **排序：** 默认按 **上报日期倒序**（最近上报在前）；相同时按 **创建时间倒序**（若有）。

**列表宜展示：** 上报日期、传播途径、疫病类型、疫病名称、风险等级、涉疫点位/轨迹（可截断展示）、处置状态（未解除/已解除）、解除日期（已解除时）、创建时间，以及操作列。

**操作列与处置状态（与 §6 矩阵一致）：**

| 处置状态 | 操作 |
| --- | --- |
| 未解除 | 查看、编辑、解除、删除 |
| 已解除 | 查看、删除 |

---

### 5.3 修改疫情上报

- **状态约束：** **仅未解除** 记录允许修改；**已解除** 记录**不允许修改**（列表/详情不提供编辑入口；若调用修改类能力须返回明确业务错误）。  
- **可修改项：** 上报日期、传播途径、涉疫点位/轨迹、疫病类型、疫病名称、风险等级（**不含**解除日期；解除日期仅能通过 **§5.6** 写入）。  
- **保存约束：** 提交时须重新满足 **§5.1** 全部校验；必填字段不得为空。  
- **说明：** 已解除记录若需更正业务内容，产品策略为：删除后重新上报，或另立「纠错/作废」流程（当前需求未包含，须单独评审）。

---

### 5.4 删除疫情上报

- **允许删除：** **未解除**、**已解除** 记录在具备删除权限时均可删除（是否支持批量删除与项目列表惯例一致）。  
- **删除后果：** 删除后该条不再出现在列表与统计中；**无**附件联动要求（当前字段均为文本，无上传附件）。  
- **确认：** 删除前宜弹出确认提示；已解除记录删除时宜在文案中区分「删除已解除记录」（仍建议二次确认）。

---

### 5.5 查看疫情上报详情

- **展示内容：** 上报日期、传播途径、涉疫点位/轨迹、疫病类型、疫病名称、风险等级、处置状态、解除日期（未解除时展示为「—」或空）、创建人/创建时间、修改人/修改时间（若系统有审计字段）。  
- **交互：** **未解除** 且具备编辑权限时，可从详情进入编辑；**已解除** 为只读。  
- **解除入口：** 仅 **未解除** 详情或列表提供「解除」按钮。

---

### 5.6 解除疫情上报

- **适用：** 仅 **未解除** 记录可执行「解除」。**已解除** 记录不得再次解除。  
- **录入：** 须填写 **解除日期**，格式 **YYYY-MM-DD**，**必填**。  
- **日期关系：** 解除日期**不得早于**上报日期；若违反须拒绝并提示（如「解除日期不能早于上报日期」）。  
- **默认：** 解除日期选择器默认可选**当天**；是否允许未来解除日期由产品约定（默认**不允许未来日期**，表示已实际解除）。  
- **确认：** 执行解除前宜二次确认（如「确认解除该疫情上报？」）。  
- **结果：** 保存解除日期后，处置状态变为 **已解除**；该记录**不可再编辑**、**不可再次解除**；操作列仅保留查看、删除。  
- **与删除区别：** 「解除」为业务结案，保留历史用于统计与追溯；「删除」为物理/逻辑移除整条记录。

---

## 6. 操作权限矩阵（汇总）

在**已授权**前提下（菜单与按钮级权限按项目角色配置）：

| 处置状态 | 查看 | 新增 | 修改 | 解除 | 删除 |
| --- | --- | --- | --- | --- | --- |
| 未解除 | ✓ | ✓（独立新增入口） | ✓ | ✓ | ✓ |
| 已解除 | ✓ | — | ✗ | ✗ | ✓ |

**说明：**

- 「新增」为列表页/global 按钮，不依赖行状态。  
- 矩阵与草稿第 7 条一致：**无解除日期** → 查看、解除、编辑、删除；**有解除日期** → 查看、删除。

---

## 7. 列表筛选与业务约束补充

| 约束 | 说明 |
| --- | --- |
| 枚举存储与展示 | 传播途径、疫病类型、风险等级在列表/详情中展示为中文标签，与 **§2** 一致 |
| 涉疫点位/轨迹 | 允许多行文本；列表可用省略号展示，详情全文展示 |
| 统计口径 | 若大屏或报表统计「在途疫情」，仅计 **未解除** 记录；「已解除」计入历史结案量 |
| 并发 | 同一记录解除操作宜防重复提交（前端禁用按钮或后端幂等，实现阶段约定） |

---

## 8. 错误与提示约定

- 业务与校验错误宜采用项目统一的 **`code`、`msg`、`data`** 结构呈现（不涉及具体协议与路径设计）。  
- 常见提示宜可区分，例如：  
  - 必填项缺失、日期格式错误；  
  - 解除日期早于上报日期；  
  - 已解除记录不可修改、不可再次解除；  
  - 删除/解除确认取消与操作失败原因。

---

## 9. 非功能需求（建议）

| 类别 | 建议 |
| --- | --- |
| 权限 | 查询、新增、修改、删除、解除等是否分角色（如仅管理员可删除已解除记录） |
| 审计 | 新增、修改、解除、删除记操作日志；解除日期变更可追溯 |
| 安全 | 涉疫点位/轨迹可能含敏感地址，按角色控制导出范围（若后续有导出） |
| 双语 | 后台字段标签与提示与项目 i18n 规范一致（汉语 + 藏文，若适用） |

---

## 10. 修订说明（相对草稿）

| 草稿问题 | 优化处理 |
| --- | --- |
| 第 5 行两项「传播途径」 | 第二项更正为 **疫病类型**（§2.2），与传播途径（§2.1）区分 |
| 「扩撒」 | 统一为 **本地扩散** |
| 解除规则仅列操作 | 增补 **§2.4 处置状态**、**§5.6 解除**、日期先后约束 |
| 修改「所有均可修改」 | 明确 **仅未解除** 可改；已解除不可改 |
| 第 8、9 条接口与技术栈 | 技术栈移出本文档；错误结构保留于 **§8**（不写接口） |
| 无流程与矩阵 | 增补 **§4 流程图**、**§6 操作矩阵** |
| 列表字段与排序未写 | **§5.2** 补充展示列、排序、筛选规则 |
| 删除与解除语义混用 | **§5.4** 与 **§5.6** 分别定义 |

---

## 11. 与相关文档关系

| 文档 | 关系 |
| --- | --- |
| `疫情上报-草稿.md` | 初稿功能列表 |
| 《疫情上报技术方案》（待编） | 库表、接口、权限标识 |
| 《疫情上报管理测试用例》（待编） | 用例与本文档章节对应 |