隔离巡查登记 — 功能需求
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 |
需要处理 |
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 总览
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 典型使用顺序
- 牲畜经 入场隔离登记 完成分圈后，圈位进入「在栏」状态。
- 巡检员进入本模块，按 巡查日期、圈位编号 查询历史记录。
- 点击 新增，选择 圈位编号 与 巡查时间，填写 病死病害数量。
- 系统按数量带出 巡查内容描述、处理情况 默认文案，巡检员可据实修改。
- 若数量 > 0，在 耳标号 中勾选对应头数的在栏耳标，必要时上传 巡查照片，保存。
- 发现登记错误时 修改；误登记录 删除（逻辑删除）。
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 约定 |
