# 实验室检测 — 功能需求

## 1. 文档说明

| 项 | 说明 |
| --- | --- |
| 模块名称 | 实验室检测 |
| 目标 | 登记、查询、维护实验室检测台账，记录样本来源、检测量与阳性结果，并自动计算检出率，支撑疾病监测统计 |
| 关联系统 | 业务后台；**检疫点**数据来源于「检疫站管理」，仅可选**运营状态为正常**的检疫站；与「疫情上报」等业务模块的数据衔接由产品统一规划，**本模块不强制**自动回写疫情上报 |
| 修订依据 | 同目录 `实验室检测-草稿.md` |

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

---

## 2. 术语与枚举

### 2.1 样本来源（单选）

表示检测样本的**业务来源**，新增/修改时必选其一：

| 取值 | 说明 |
| --- | --- |
| 场地抽检 | 在养殖场地、圈舍等现场采集的抽检样本 |
| 疫情上报送检 | 因疫情上报流程送交实验室的样本 |
| 调运检疫 | 调运、流通环节检疫送检样本 |
| 日常检测 | 常规监测、计划内检测等其它来源 |

### 2.2 数量单位

- **检测量**、**阳性检出数**均以 **「份」** 为计量单位，界面展示时须带单位（如「份」），避免与重量、头数等混淆。

### 2.3 检出率（派生指标，非手工录入）

| 项 | 说明 |
| --- | --- |
| 含义 | 本次检测中阳性样本占比 |
| 计算 | **检出率 = 阳性检出数 ÷ 检测量** |
| 展示 | 建议以**百分比**展示（小数位数与项目全局一致，如保留 **2** 位小数）；新增/编辑表单中**只读**，随检测量、阳性检出数变化实时刷新 |
| 检测量为 0 | 仅当 **检测量 = 0** 且 **阳性检出数 = 0** 时合法；此时检出率展示为 **0%** 或 **「—」**（产品择一，全文统一）；**不允许**检测量为 0 而阳性检出数大于 0 |

---

## 3. 功能范围

- 实验室检测的新增、修改、删除、分页列表查询、详情查看  
- 检测日期、样本来源、检测量、阳性检出数、检出率的录入与校验  
- 按样本来源、**检疫点**的列表筛选  
- 面向使用方的业务错误与校验提示（见第 **8** 章）  

**不在本模块范围（除非后续单独立项）：** 检测原始报告附件上传、实验室 LIMS 对接、与疫情上报单自动关联编号、地图与预警等。

---

## 4. 业务流程概览

```mermaid
flowchart TD
    A[新增实验室检测] --> B[列表查询/按样本来源筛选]
    B --> C[查看详情]
    B --> D[修改]
    B --> E[删除]
    D --> B
    E --> B
    C --> B
```

1. **登记**：录入检测日期、样本来源、检测量、阳性检出数 → 系统计算检出率 → 形成一条可查询记录。  
2. **查询**：按样本来源精确筛选，分页浏览；默认按检测日期或创建时间倒序。  
3. **维护**：任意记录均可修改全部业务字段（须重新通过校验）。  
4. **删除**：具备权限时删除记录；删除后不再参与列表与统计。  
5. **查阅**：任意记录可查看详情（只读展示，含检出率）。

> 本模块**无**「解除 / 发布 / 下架」等状态机；草稿中「均可修改、均可查看」理解为**不区分业务状态**，与疫情上报的「未解除 / 已解除」不同。

---

## 5. 详细功能需求

### 5.1 新增实验室检测

| 字段 | 规则 |
| --- | --- |
| 检测日期 | **必填**；格式 **YYYY-MM-DD**；表示本次检测业务归属日 |
| 检疫点 | **必填**；下拉单选；选项来自「检疫站管理」中**运营状态为正常**的检疫站；保存为检疫站主键 |
| 样本来源 | **必填**；单选，取值限定为 **§2.1** |
| 检测量 | **必填**；非负**整数**；单位：份；表示本次检测样本份数 |
| 阳性检出数 | **必填**；非负**整数**；单位：份；表示阳性样本份数 |
| 检出率 | **系统计算**；规则见 **§2.3**；用户**不可手工修改** |

**必填字段汇总：** 检测日期、检疫点、样本来源、检测量、阳性检出数。

**校验：**

| 规则 | 说明 |
| --- | --- |
| 日期格式 | 检测日期非法时拒绝保存 |
| 整数与非负 | 检测量、阳性检出数须为整数且 ≥ 0；出现小数、负数或非数字时拒绝保存 |
| 数量关系 | **阳性检出数 ≤ 检测量**；违反时拒绝保存并提示（如「阳性检出数不能大于检测量」） |
| 零检测量 | 检测量为 0 时，阳性检出数必须为 0 |
| 枚举 | 样本来源须为 **§2.1** 约定取值之一 |
| 检疫点 | 须选择已存在且**运营状态为正常**的检疫站；停业、注销或已删除的检疫站不可选、不可保存 |

**保存结果：** 生成一条完整检测记录（含系统计算的检出率），可被列表查询、修改、删除、查看。

---

### 5.2 查询实验室检测列表

- **样本来源：** **精确**匹配筛选；未选择时不过滤。  
- **检疫点：** **精确**匹配筛选（按检疫站 ID）；未选择时不过滤；下拉选项与新增表单一致（仅正常运营检疫站）。  
- **分页：** 支持分页；默认 **每页 20 条**，默认首页为第一页；单页条数上限与项目列表通用规范一致（若有）。  
- **排序：** 默认按 **检测日期倒序**（最近检测在前）；相同时按 **创建时间倒序**（若有）。

**列表宜展示：** 检测日期、**检疫点（检疫站名称）**、样本来源、检测量（份）、阳性检出数（份）、检出率、创建时间，以及操作列。

**操作列（与 §6 矩阵一致）：**

| 记录状态 | 操作 |
| --- | --- |
| 任意有效记录 | 查看、编辑、删除 |

---

### 5.3 修改实验室检测

- **状态约束：** **所有**已存在记录均允许修改（无「已结案不可改」类限制）。  
- **可修改项：** 检测日期、检疫点、样本来源、检测量、阳性检出数（检出率随保存前校验重新计算）。  
- **保存约束：** 提交时须重新满足 **§5.1** 全部校验；必填字段不得为空。  
- **检出率：** 修改检测量或阳性检出数后，表单内检出率应**实时重算**；保存后以最新数量为准持久化展示值。

---

### 5.4 删除实验室检测

- **允许删除：** 任意记录在具备删除权限时均可删除（是否支持批量删除与项目列表惯例一致）。  
- **删除后果：** 删除后该条不再出现在列表与统计中。  
- **确认：** 删除前宜弹出确认提示；批量删除时宜提示选中条数。

---

### 5.5 查看实验室检测详情

- **展示内容：** 检测日期、样本来源、检测量、阳性检出数、检出率、创建人/创建时间、修改人/修改时间（若系统有审计字段）。  
- **交互：** 详情为只读展示；具备编辑权限时，可提供「编辑」入口跳转至编辑（与列表「编辑」等价）。  
- **检出率：** 详情页展示与列表一致的计算结果，不单独维护第二套口径。

---

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

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

| 能力 | 查看 | 新增 | 修改 | 删除 |
| --- | --- | --- | --- | --- |
| 任意有效记录 | ✓ | — | ✓ | ✓ |
| 列表/global | — | ✓ | — | — |

**说明：**

- 「新增」为列表页或工具栏独立入口，不依赖行状态。  
- 与草稿一致：**查看、修改、删除**对全部记录开放；无额外状态分支。

---

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

| 约束 | 说明 |
| --- | --- |
| 枚举展示 | 样本来源在列表/详情中展示为中文标签，与 **§2.1** 一致 |
| 检出率口径 | 统计报表、大屏若引用本模块检出率，须与 **§2.3** 公式一致；跨模块汇总时避免重复计数同一份样本（若后续与送检单关联，另文约定） |
| 检测量为 0 | 仅用于「当日无样本但需占位登记」等少数场景；若产品禁止 0 检测量，可在实现前将规则收紧为「检测量 ≥ 1」并同步修订本文档 |
| 并发 | 同一条记录连续保存时，以后提交的检测量、阳性检出数为准；宜防重复提交（前端禁用或后端幂等，实现阶段约定） |

---

## 8. 错误与提示约定

面向使用方的提示宜**语义明确、可区分**，例如：

| 场景 | 提示方向（示例） |
| --- | --- |
| 必填项缺失 | 标明缺失项（如「请选择检测日期」） |
| 日期格式错误 | 「检测日期格式不正确」 |
| 非整数或负数 | 「检测量须为非负整数」「阳性检出数须为非负整数」 |
| 阳性大于检测量 | 「阳性检出数不能大于检测量」 |
| 检测量为 0 但阳性大于 0 | 「检测量为 0 时阳性检出数须为 0」 |
| 样本来源非法 | 「样本来源不在可选范围内」 |
| 删除确认取消 | 不执行删除，无成功提示 |

本文档**不约定** HTTP 状态码、错误码字段名及接口报文结构。

---

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

| 类别 | 建议 |
| --- | --- |
| 权限 | 查询、新增、修改、删除是否分角色（如仅实验室人员可新增） |
| 审计 | 新增、修改、删除记操作日志 |
| 统计 | 按样本来源、时间区间汇总检测量、阳性数、加权或简单平均检出率时，口径在报表需求中单独定义 |
| 双语 | 后台字段标签与提示与项目 i18n 规范一致（汉语 + 藏文，若适用） |

---

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

| 草稿条目 | 优化处理 |
| --- | --- |
| 检出率「必填」易误解为手填 | 明确为 **§2.3 系统计算、只读** |
| 检测量/阳性仅写「非负数」 | 补充 **整数**、**阳性 ≤ 检测量**、**零检测量** 规则 |
| 列表写「分页列疫情上报列表」 | 更正为 **实验室检测分页列表**；筛选仅 **样本来源** |
| 「所有均可修改」 | 保留，并写入 **§5.3**；与疫情上报「仅未解除可改」区分 |
| 第 6、7 条接口与技术栈 | **移出**本文档 |
| 无流程与矩阵 | 增补 **§4 流程图**、**§6 操作矩阵** |
| 样本来源四项 | 固化为 **§2.1** 枚举表 |

---

## 11. 与相关文档关系

| 文档 | 关系 |
| --- | --- |
| `实验室检测-草稿.md` | 初稿功能列表 |
| 《实验室检测技术方案》 | 库表、接口、权限标识 |
| 《实验室检测管理测试用例》 | 用例与本文档章节对应 |
| 《实验室检测前端技术方案》 | 前端页面、API、i18n |
| 《疫情上报功能需求》 | 同属「疾病检测与上报」；样本来源含「疫情上报送检」，业务关联规则可后续统一 |