# 隔离巡查登记 — 功能需求

## 1. 文档说明

| 项 | 说明 |
| --- | --- |
| 模块名称 | 隔离巡查登记（交易市场平台） |
| 目标 | 在业务后台按次登记**隔离圈位日常巡查**结果（时间、圈位、病死病害数量、关联耳标、巡查结论与处理意见、现场照片），形成可查询、可维护的巡查台账，支撑隔离期监管与异常处置追溯 |
| 关联系统 | 业务后台；**隔离圈位管理**（圈位主数据）；**入场隔离登记**（分圈后在栏耳标、在栏状态） |
| 修订依据 | 同目录 `隔离巡查登记-草稿.md`、界面原型（`隔离巡查登记.png`） |

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

---

## 2. 术语与业务对象

### 2.1 巡查记录（一条台账）

- 表示对**某一个已分圈隔离圈位**在**某一时刻**开展的一次**现场巡查**登记。  
- 由运营人员在后台**新增与维护**；保存成功后出现在巡查记录列表，供查询、修改、删除及后续统计引用。  
- 单条记录包含：**巡查时间**、**圈位编号**、**病死病害数量**、**耳标号集合**（异常时）、**巡查内容描述**、**处理情况**、**巡查照片**及审计信息（创建人、时间等，与项目其他台账一致）。

### 2.2 巡查时间

- **必填**；格式 **YYYY-MM-DD HH:mm:ss**（日期时间选择器）。  
- **新增默认值**：系统**当前时间**；用户可改选其他合法时间。  
- **不宜**选择未来时间（**默认建议**禁止或提示「巡查时间不能晚于当前时间」）。  
- 列表、筛选中的「巡查日期」取本字段的**日期部分**（`YYYY-MM-DD`）。

### 2.3 圈位编号（已分圈圈位）

- **必填**；**单选**下拉。  
- 选项范围：**已分圈且仍有在栏牲畜**的隔离圈位，即来源于 **入场隔离登记** 中、当前**尚未出圈/解除隔离**的分圈明细所涉及的圈位编号；**未分圈、已空圈、已逻辑删除**的圈位**不出现在下拉中**。  
- 展示与保存值与 **隔离圈位管理** 中的 2 位数字圈位编号一致（如 `01`、`02`），**不可手工输入**编号。  
- 若当前无任何可用圈位，新增时应提示「暂无在栏圈位，请先在入场隔离登记中完成分圈」。

### 2.4 病死病害数量（头）

- **必填**；单位固定为 **头**；取值为**非负整数**（≥0）。  
- **新增默认值**：**0**。  
- 业务含义：本次巡查在该圈位内发现的**病死或病害牲畜头数**（按现场认定登记，本期不区分病死与病害子类）。  
- 本字段为**核心驱动字段**，联动 **§2.5～§2.7** 的默认文案、耳标展示与保存校验。

### 2.5 巡查内容描述

- **必填**；多行或单行文本，**支持手工修改**。  
- **随病死病害数量联动的默认文案**（用户修改数量后宜**自动带出**，用户可立即改回）：

| 病死病害数量 | 默认文案 |
| --- | --- |
| **= 0** | 巡查结果正常 |
| **> 0** | 巡查结果异常 |

- **默认建议**长度 **1～200** 字（去除首尾空白后计数）；仅空白视为未填。

### 2.6 处理情况

- **必填**；多行或单行文本，**支持手工修改**。  
- **随病死病害数量联动的默认文案**：

| 病死病害数量 | 默认文案 |
| --- | --- |
| **= 0** | 无需处理 |
| **> 0** | 需要处理 |

- **默认建议**长度 **1～200** 字；仅空白视为未填。

### 2.7 耳标号（异常时登记）

| 场景 | 规则 |
| --- | --- |
| 病死病害数量 **= 0** | 表单**不展示**耳标号区域；保存时**不要求**耳标；列表耳标列展示「—」或留空 |
| 病死病害数量 **> 0** | **必填**；**多选**下拉（或等效多选器） |
| 选项来源 | 当前所选**圈位编号**下、**仍在栏未出圈**的耳标号（与入场隔离登记分圈明细一致；已出圈耳标不可选） |
| 选择个数 | 已选耳标个数 **必须等于** 病死病害数量（见 **§2.8**） |
| 展示 | 列表、详情多个耳标以逗号、顿号拼接；过长省略，详情可看全文 |

- 耳标号字符规则与 **入场隔离登记** **§2.3** 一致（单段 **1～32** 字符等）。

### 2.8 病死病害数量与耳标一致性（核心规则）

保存（新增/修改）前必须满足：

| 编号 | 规则 |
| --- | --- |
| P1 | 病死病害数量 **= 0** 时：耳标集合为空（不校验耳标） |
| P2 | 病死病害数量 **> 0** 时：至少选择 **1** 个耳标，且 **已选耳标个数 = 病死病害数量** |
| P3 | 所选耳标均须属于当前圈位在栏集合，且**同一记录内耳标不可重复** |

不满足时拒绝保存，并提示（示例见 **§8**）。

### 2.9 巡查照片

- **单张**图片上传（非多图）。  
- 允许后缀：**jpg、jpeg、png**（大小写不敏感）。  
- 单文件大小 **≤ 10 MB**。  
- **是否必填**：**默认建议选填**（无照片也可保存；有异常时建议上传现场照片，可在界面提示文案体现）。  
- 列表宜展示缩略图或「查看」入口；详情支持预览/下载（与项目文件预览惯例一致）。

### 2.10 删除与可见性

- 删除采用与项目其他业务台账一致的**逻辑删除**：删除后默认不在列表与常规查询中展示，数据保留供审计。  
- **本期不提供**回收站。  
- **本期不限制**删除后是否影响入场隔离登记（巡查为记录型下游；入场登记删除约束见该模块需求，**不因本模块单独禁止删除入场登记**）。

### 2.11 列表筛选项与记录字段的关系

| 筛选项 | 与记录字段关系 |
| --- | --- |
| 巡查日期 | 选填；对「巡查时间」的**日期部分**做**闭区间**范围匹配（开始日期 ≤ 记录日期 ≤ 结束日期）；仅填开始或仅填结束按项目日期区间惯例处理（**默认建议**缺省结束视为开始当日，或结束不得早于开始） |
| 圈位编号 | 选填；对「圈位编号」**模糊**匹配（包含输入片段即可，与项目全局模糊查询一致） |

支持多条件**组合筛选**（同时满足）。

---

## 3. 功能范围

### 3.1 本期实现

| 能力 | 说明 |
| --- | --- |
| 巡查记录列表 | 巡查日期范围、圈位编号筛选；分页；**§5.2** |
| 新增巡查记录 | 表单联动与一致性校验；**§5.1** |
| 修改巡查记录 | 各字段均可修改；校验同新增；**§5.3** |
| 查看巡查记录 | 只读展示全部字段；**§5.4** |
| 删除巡查记录 | 单条逻辑删除；**§5.5** |
| 工具栏 | 搜索、重置、新增 |

### 3.2 本期不实现（除非后续单独立项）

- 移动端现场扫码巡查、GPS 定位、巡查任务自动下发与到期提醒  
- 巡查记录批量导入/导出、审批流、签字确认  
- 与病死无害化处理、出圈指令的自动联动（本期仅登记结论与处理意见文本）  
- 按耳标号、按供应商的列表筛选（原型未要求）  
- 视频、多图附件  

---

## 4. 业务流程概览

### 4.1 总览

```mermaid
flowchart TD
    A[进入隔离巡查登记] --> B{用户操作}
    B -->|查询| C[设置巡查日期范围/圈位编号]
    C --> D[搜索刷新列表]
    B -->|新增| E[打开新增巡查记录]
    E --> F[选择圈位与时间]
    F --> G[填写病死病害数量]
    G --> H{数量是否大于0?}
    H -->|否| I[带出正常/无需处理默认文案]
    H -->|是| J[带出异常/需要处理默认文案]
    J --> K[多选耳标且个数等于数量]
    I --> L[可选上传巡查照片]
    K --> L
    L --> M{保存前校验 P1～P3}
    M -->|通过| N[保存并刷新列表]
    M -->|未通过| E
    B -->|查看/编辑/删除| O[行内或详情操作]
    O --> D
```

### 4.2 典型使用顺序

1. 牲畜经 **入场隔离登记** 完成分圈后，圈位进入「在栏」状态。  
2. 巡检员进入本模块，按 **巡查日期**、**圈位编号** 查询历史记录。  
3. 点击 **新增**，选择 **圈位编号** 与 **巡查时间**，填写 **病死病害数量**。  
4. 系统按数量带出 **巡查内容描述**、**处理情况** 默认文案，巡检员可据实修改。  
5. 若数量 **> 0**，在 **耳标号** 中勾选对应头数的在栏耳标，必要时上传 **巡查照片**，保存。  
6. 发现登记错误时 **修改**；误登记录 **删除**（逻辑删除）。

### 4.3 与关联模块的关系

| 关联模块 | 本模块用法 |
| --- | --- |
| **隔离圈位管理** | 圈位编号展示与主数据一致；仅作编号参照，本模块不维护圈位台账 |
| **入场隔离登记** | 提供「已分圈在栏」圈位及每圈在栏耳标；出圈或登记删除后，对应圈位/耳标不再出现在本模块下拉中 |
| **下游（规划）** | 监管报表、异常统计、隔离期满判定等可引用本台账；集成规则另文档约定 |

---

## 5. 详细功能需求

### 5.1 新增巡查记录

#### 5.1.1 业务字段

| 字段 | 必填 | 规则摘要 |
| --- | --- | --- |
| 巡查时间 | 是 | **§2.2**；默认当前时间 |
| 圈位编号 | 是 | **§2.3**；单选已分圈在栏圈位 |
| 病死病害数量（头） | 是 | **§2.4**；非负整数，默认 0 |
| 巡查内容描述 | 是 | **§2.5**；随数量默认，可改 |
| 处理情况 | 是 | **§2.6**；随数量默认，可改 |
| 耳标号 | 条件必填 | **§2.7、§2.8**；数量 > 0 时必填且个数一致 |
| 巡查照片 | 否 | **§2.9**；单图 jpg/jpeg/png，≤10MB |

#### 5.1.2 表单联动（新增/修改共用）

| 触发 | 行为 |
| --- | --- |
| 变更 **圈位编号** | 清空已选耳标；耳标下拉选项切换为**新圈位**在栏耳标 |
| 变更 **病死病害数量** | 按 **§2.5、§2.6** 刷新默认文案；若数量变为 0，隐藏耳标区并清空已选耳标 |
| 变更 **病死病害数量** 且 > 0 | 若已选耳标个数 **大于** 新数量，宜提示并清空或要求用户减选至相等（**默认建议**保存前校验，不等则拒绝） |

#### 5.1.3 保存与取消

| 操作 | 行为 |
| --- | --- |
| **确定** | 通过 **§2.8** 及字段校验后保存；关闭弹窗并**刷新列表** |
| **取消** | 关闭弹窗，不保存 |

#### 5.1.4 校验摘要

| 规则 | 说明 |
| --- | --- |
| 巡查时间 | 为空、格式非法、晚于当前时间（若启用）时拒绝保存 |
| 圈位 | 未选择或圈位已非在栏时拒绝保存 |
| 病死病害数量 | 非整数、负数时拒绝保存 |
| 文案长度 | 巡查内容描述、处理情况超过约定字数拒绝保存 |
| P1～P3 | **§2.8** 耳标与数量一致性 |
| 照片 | 超大小、格式不符时拒绝保存 |

---

### 5.2 查询巡查记录列表

#### 5.2.1 筛选

| 条件 | 规则 |
| --- | --- |
| 巡查日期 | 选填；**起止日期**区间（`daterange`，**§2.11**）；与项目其他模块日期区间组件一致 |
| 圈位编号 | 选填；**模糊**匹配 |

#### 5.2.2 列表规则

- 默认每页 **20** 条。  
- 默认排序：**巡查时间降序**（最近一次巡查在前）。  
- 工具栏：**搜索**、**重置**、**新增**。

#### 5.2.3 展示列（与原型一致）

巡查时间、圈位编号、巡查照片、巡查内容描述、处理情况、病死病害数量(头)、耳标号、操作。

| 列 | 展示说明 |
| --- | --- |
| 巡查时间 | `YYYY-MM-DD HH:mm:ss` |
| 圈位编号 | 2 位数字编号 |
| 巡查照片 | 有图：缩略图或「查看」；无图：「—」或留空 |
| 巡查内容描述 | 过长省略；详情全文 |
| 处理情况 | 过长省略；详情全文 |
| 病死病害数量(头) | 非负整数 + 单位「头」 |
| 耳标号 | 数量 = 0 时「—」；> 0 时拼接展示 |
| 操作 | 查看、编辑、删除（权限见 **§6**） |

---

### 5.3 修改巡查记录

| 项 | 要求 |
| --- | --- |
| 入口 | 列表「编辑」；详情可提供「编辑」 |
| 可改范围 | **全部业务字段**均可修改（含圈位、时间、数量、耳标、文案、照片） |
| 圈位/数量变更 | 联动规则同 **§5.1.2** |
| 照片 | 可重新上传替换；宜支持清除已传照片（与项目上传组件惯例一致） |
| 校验 | 同 **§5.1.4** |
| 保存 | **确定** 保存并刷新列表；**取消** 放弃 |

> **说明：** 修改时若所选圈位、耳标在保存瞬间已出圈，应拒绝保存并提示「圈位或耳标状态已变更，请重新选择」。

---

### 5.4 查看巡查记录详情

| 项 | 要求 |
| --- | --- |
| 展示内容 | **§5.1.1** 全部字段；耳标、照片完整展示 |
| 只读 | 全部不可编辑 |
| 操作 | 可提供 **编辑**、**删除**（与列表权限一致）；**关闭** 返回列表 |
| 审计信息 | 宜含创建人、创建时间、修改人、修改时间（与项目其他台账一致） |

---

### 5.5 删除巡查记录

| 项 | 要求 |
| --- | --- |
| 入口 | 列表「删除」；详情可提供「删除」 |
| 确认 | 删除前**二次确认**（宜展示巡查时间、圈位编号） |
| 删除方式 | **逻辑删除**（**§2.10**） |
| 批量删除 | **本期不提供** |

---

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

在**已授权**前提下：

| 操作 | 列表/详情/弹窗 | 说明 |
| --- | --- | --- |
| 查询列表、筛选 | 列表页 | 需列表查询权限 |
| 新增巡查记录 | 「新增」 | 需新增权限 |
| 查看 | 行内/详情 | 需查看权限 |
| 修改 | 行内/详情 | 需修改权限 |
| 删除 | 行内/详情 | 需删除权限 |

无权限的按钮**不展示或禁用**（与若依按钮权限惯例一致）。

---

## 7. 与同类模块对照（便于评审）

| 维度 | 入场隔离登记 | 隔离巡查登记（本模块） |
| --- | --- | --- |
| 业务性质 | 进场、分圈、隔离期 | 对在栏圈位的**巡检记录** |
| 时间字段 | 进场时间 | 巡查时间 |
| 圈位 | 分圈明细多行 | 单条记录对应**一个**圈位 |
| 耳标 | 主表 + 分圈分配 | 仅异常时按头数勾选在栏耳标 |
| 数量含义 | 进场总头数 | 病死病害头数 |
| 核心一致性 | R1～R5 分圈与耳标 | P1～P3 数量与耳标 |
| 附件 | 检疫证文档 | 现场照片（单图） |
| 列表筛选 | 进场日期、检疫证号、供应商 | 巡查日期、圈位编号 |

---

## 8. 异常与提示（业务侧）

| 场景 | 提示方向（示例） |
| --- | --- |
| 无在栏圈位 | 暂无在栏圈位，请先在入场隔离登记中完成分圈 |
| 巡查时间为空 | 请选择巡查时间 |
| 巡查时间晚于当前 | 巡查时间不能晚于当前时间 |
| 未选圈位 | 请选择圈位编号 |
| 数量非法 | 请输入正确的病死病害数量（非负整数） |
| 耳标个数不一致 | 病死病害数量与已勾选耳标号数量不一致 |
| 未选耳标（数量>0） | 请选择耳标号 |
| 耳标不在栏 | 耳标 {tag} 不在当前圈位或已出圈 |
| 文案超长 | 巡查内容描述/处理情况长度不能超过 N 个字符 |
| 照片格式/大小 | 仅支持 jpg、jpeg、png，且不超过 10MB |
| 圈位状态变更 | 圈位或耳标状态已变更，请重新选择 |

**本期不涉及** HTTP 响应结构、错误码表等技术约定（草稿中的统一返回格式由技术方案另行描述）。

---

## 9. 非功能需求（摘要）

| 项 | 要求 |
| --- | --- |
| 易用性 | 数量 = 0 时隐藏耳标，避免误填；数量变更时默认文案与原型橙色说明一致 |
| 一致性 | 逻辑删除、分页、日期区间筛选、模糊查询、校验风格与交易市场平台其他台账模块一致 |
| 数据可信 | 保存前前端预校验 **§2.8**，服务端须再次校验，防止绕过 |
| 可追溯 | 异常记录宜鼓励上传巡查照片；列表可快速识别「数量 > 0」记录 |

---

## 10. 修订记录

| 版本 | 说明 |
| --- | --- |
| 1.0 | 初版：依据草稿与原型；巡查记录 CRUD；数量驱动文案与耳标联动；已分圈在栏圈位/耳标范围；剔除库表、接口、技术栈与 HTTP 约定 |