# 入场隔离登记 — 功能需求

## 1. 文档说明

| 项 | 说明 |
| --- | --- |
| 模块名称 | 入场隔离登记（交易市场平台） |
| 目标 | 在业务后台登记牲畜**进场隔离**信息（检疫证、数量、耳标、分圈及隔离期限），形成可查询、可维护的隔离台账，为隔离期满判定、隔离巡查等下游业务提供依据 |
| 关联系统 | 业务后台；**供应商管理**（供应商主数据）；**隔离圈位管理**（圈位编号、全局默认隔离天数） |
| 修订依据 | 同目录 `入场隔离登记-草稿.md`、界面原型（`入场隔离登记.png`） |

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

---

## 2. 术语与业务对象

### 2.1 入场隔离登记（一条台账记录）

- 表示一批（或一头）牲畜**进入交易市场隔离区**的一次登记事件。  
- 由运营人员在后台**手工登记**为主；检疫证文件识别（OCR）为**后续扩展**，本期默认手工录入。  
- 单条记录包含：进场时间、供应商、检疫证文件、检疫证号、总数量、耳标号集合、分圈明细、隔离天数、预计解除日期及审计信息。

### 2.2 分圈明细（子业务对象）

- 隶属于一条入场隔离登记，表示将部分耳标分配到**某一个隔离圈位**。  
- 一条登记可包含 **0～N 条**分圈明细（保存前须完成分圈且满足 **§2.6** 一致性规则，见 **§5.1**）。  
- 单条分圈包含：**圈位编号**、**本圈数量（头）**、**本圈耳标号集合**。

### 2.3 耳标号集合（主表字段）

- 在登记表单中以**文本**录入，多个耳标用**英文逗号 `,` 或中文逗号 `，`** 分隔。  
- 保存前须解析为列表：去除首尾空白、忽略空段；**同一登记内耳标号不可重复**（重复时拒绝保存并提示）。  
- 耳标号**字符规则**与项目全局牲畜耳标规则一致；若暂无全局规则，默认单段长度 **1～32** 字符，不允许仅空白。

### 2.4 数量（头）

- 表示本批进场牲畜**总头数**，单位固定为 **头**，取值为**正整数**。  
- 与耳标号集合的关系见 **§2.6**：保存时要求 **总数量 = 有效耳标个数**（每头对应一个耳标）。

### 2.5 隔离天数与预计解除日期

| 项 | 规则 |
| --- | --- |
| **隔离天数** | 正整数，单位 **天**；新增时默认值取自 **隔离圈位管理** 模块维护的**全局默认隔离天数**（见该模块功能需求 **§2.4**）；若全局未配置，界面默认 **3** 天（产品可在评审时调整兜底值） |
| **预计解除日期** | 由系统根据 **进场时间（日期部分）+ 隔离天数** 自动计算，**只读展示**；用户不可手工改日期而绕过天数逻辑 |
| **联动** | 用户修改「进场时间」或「隔离天数」时，**实时重算**预计解除日期 |

> **计算说明：** 进场时间含时分秒时，预计解除日期取**进场日期的日历日**加隔离天数（与原型「进场时间 + 隔离天数」一致）；具体是否含「进场当日为第 1 天」由评审确认，**默认：进场日为第 1 天，满 N 天后第 N 日 24:00 前解除**（仅展示日期 `YYYY-MM-DD` 时，展示为「进场日期 + (隔离天数 − 1) 天」或「进场日期 + 隔离天数 天」择一后全文一致，**默认展示：进场日期 + 隔离天数（自然日相加）**）。

### 2.6 数量、耳标与分圈一致性（核心规则）

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

| 编号 | 规则 |
| --- | --- |
| R1 | **总数量（头）** = 主表解析后的**耳标号个数** |
| R2 | 所有分圈明细的**本圈数量之和** = **总数量（头）** |
| R3 | 所有分圈明细中的耳标号**并集** = 主表耳标号集合（无遗漏、无多余） |
| R4 | 任一耳标号在分圈明细中**最多出现一次**（不可重复分圈） |
| R5 | 每条分圈明细：**本圈数量** = 该条所选耳标号**个数** |

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

### 2.7 检疫证文件

- **单文件**上传，非结构化文档。  
- 允许后缀：**pdf、md、doc、docx、xls、xlsx、ppt、pptx**（大小写不敏感）。  
- 单文件大小 **≤ 30 MB**。  
- **本期**：上传仅作存档与下载/预览（若项目支持）；**不**从文件自动填充检疫证号、数量、耳标（OCR 见 **§3.2**）。  
- 是否必填：评审确认；**默认建议选填**（有检疫证号即可业务闭环），原型有上传入口则界面保留。

### 2.8 供应商与圈位（外部主数据）

| 关联模块 | 本模块用法 |
| --- | --- |
| **供应商管理** | 登记表单、列表筛选：**单选**供应商；下拉数据来自未删除的供应商台账；支持按名称**模糊检索**后选择（登记时）；列表筛选为**下拉精确匹配**（选中某供应商则只查该供应商记录） |
| **隔离圈位管理** | 分圈时 **圈位编号** 下拉仅可选未删除的圈位；编号为系统自动生成的 2 位数字，**不可手工输入** |

### 2.9 删除与可见性

- 删除采用与项目其他业务台账一致的**逻辑删除**：删除后默认不在列表展示，数据保留供审计。  
- **本期不提供**回收站。  
- 若登记已被**隔离巡查登记**、出圈、交易等下游引用，**宜禁止删除**并提示「存在关联业务，无法删除」（**默认建议禁止**）。

---

## 3. 功能范围

### 3.1 本期实现

| 能力 | 说明 |
| --- | --- |
| 登记列表 | 进场日期范围、检疫证号、供应商筛选；分页；**§5.2** |
| 新增登记 | 主表字段 + 分圈明细；一致性校验；**§5.1** |
| 修改登记 | 主表与分圈均可改；校验同新增；**§5.3** |
| 查看登记 | 只读含分圈明细；**§5.4** |
| 删除登记 | 单条逻辑删除；**§5.5** |
| 工具栏 | 搜索、重置、新增 |

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

| 项 | 说明 |
| --- | --- |
| **检疫证 OCR 自动识别** | 自动识别检疫证号、数量、耳标并回填表单；本期仅预留上传入口与文案说明 |
| 批量导入/导出、打印检疫证 |
| 隔离期满自动出圈、消息提醒、与巡查单自动生成 |
| 圈位占用状态实时看板、同一圈位容量上限校验（若圈位模块未维护容量则不做） |
| 按耳标号单独列表筛选（原型未要求） |

---

## 4. 业务流程

### 4.1 模块总览

```mermaid
flowchart TD
    A[进入入场隔离登记] --> B[列表查询]
    B --> C{操作}
    C --> D[新增登记]
    C --> E[查看]
    C --> F[修改]
    C --> G[删除]
    D --> H[填写主表与上传检疫证]
    H --> I[录入耳标与数量]
    I --> J[添加分圈明细]
    J --> K{一致性 R1～R5}
    K -->|否| J
    K -->|是| L[保存台账]
    L --> B
    F --> M[调整主表/分圈]
    M --> K
    G --> N{有关联?}
    N -->|是| O[拒绝删除]
    N -->|否| P[逻辑删除]
    P --> B
```

### 4.2 新增登记典型顺序

1. 点击 **新增**，确认 **进场时间**（默认当前时刻）、选择 **供应商**。  
2. （可选）上传 **检疫证文件**；手工填写 **检疫证号**、**数量**、**耳标号**（逗号分隔）。  
3. 确认 **隔离天数**（默认带出全局配置），核对 **预计解除日期**。  
4. 点击 **添加分圈**，在子界面为每个圈位选择耳标（不可与其它圈重复），确认后回到主表单分圈表格。  
5. 系统校验 **§2.6**，通过后 **确定** 保存。

### 4.3 分圈子流程

```mermaid
flowchart TD
    A[点击添加分圈] --> B[选择圈位编号]
    B --> C[多选耳标号]
    C --> D[系统计算本圈数量]
    D --> E{耳标是否已被其他圈占用?}
    E -->|是| C
    E -->|否| F[确定写入分圈表格]
    F --> G[可继续添加或编辑/删除行]
    G --> H[主表单保存时校验 R1～R5]
```

---

## 5. 详细功能需求

### 5.1 新增入场隔离登记

#### 5.1.1 主表业务字段

| 字段 | 必填 | 规则摘要 |
| --- | --- | --- |
| 进场时间 | 是 | `YYYY-MM-DD HH:mm:ss`；默认**当前系统时间**；不得为空 |
| 供应商 | 是 | 单选；数据来自供应商管理；支持名称模糊搜索后选定一条 |
| 检疫证文件 | 否* | 单文件；后缀与大小见 **§2.7**；*默认选填 |
| 检疫证号 | 是 | 文本；**1～50** 字符（trim 后）；同一系统内是否唯一由评审确认，**默认建议不强制唯一** |
| 数量（头） | 是 | 正整数；与耳标个数一致见 **§2.6 R1** |
| 耳标号 | 是 | 逗号分隔多个；解析规则见 **§2.3**；至少 1 个有效耳标 |
| 隔离天数（天） | 是 | 正整数；默认取全局默认隔离天数；建议范围 **1～3650** |
| 预计解除日期 | — | **只读**；由进场时间与隔离天数自动计算，见 **§2.5** |
| 分圈明细 | 是 | 至少 **1** 条分圈记录且满足 **§2.6** |

#### 5.1.2 分圈明细表格（主表单内）

| 列/能力 | 说明 |
| --- | --- |
| 圈位编号 | 展示所选圈位编号（来自隔离圈位管理） |
| 数量（头） | 展示本圈数量（= 本圈耳标个数，**§2.6 R5**） |
| 耳标号 | 展示本圈已选耳标，多个以逗号或顿号拼接，过长省略 |
| 操作 | **编辑**、**删除** 单行分圈 |
| 添加分圈 | 打开 **§5.1.3** 子界面 |

#### 5.1.3 添加/编辑分圈（子界面）

| 字段 | 必填 | 规则摘要 |
| --- | --- | --- |
| 圈位编号 | 是 | 下拉单选；仅可选隔离圈位管理中**未删除**的圈位；**同一登记内同一圈位不可重复添加**（重复时提示） |
| 耳标号 | 是 | **多选**下拉；选项来源 = 主表「耳标号」解析列表；**已被其他分圈行占用的耳标不可再选**；至少选 1 个 |
| 数量（头） | 是 | **只读或自动带出** = 已选耳标个数；用户不可改数量而与耳标数不一致 |

| 操作 | 行为 |
| --- | --- |
| **确定** | 校验通过后，新增一行或更新当前编辑行到主表单分圈表格，关闭子界面 |
| **取消** | 关闭子界面，不改动表格（编辑中则放弃本次修改） |

#### 5.1.4 保存与取消

| 操作 | 行为 |
| --- | --- |
| **确定** | 主表 + 分圈全量校验（含 **§2.6**）通过后保存；关闭弹窗并刷新列表 |
| **取消** | 关闭弹窗，不保存 |

---

### 5.2 查询入场隔离登记列表

#### 5.2.1 筛选条件

| 条件 | 规则 |
| --- | --- |
| 进场日期 | 选填；**开始日期～结束日期**区间（一个日期范围控件）；与记录「进场时间」的**日期部分**匹配；空则不过滤 |
| 检疫证号 | 选填；对检疫证号**模糊**匹配（包含输入片段即可）；空则不过滤 |
| 供应商 | 选填；下拉**精确**匹配（选中某供应商则只查该供应商的记录）；空则不过滤 |

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

#### 5.2.2 列表规则

- 默认每页 **20** 条。  
- 默认排序：**进场时间倒序**（新的在前）。  
- 工具栏：**搜索**、**重置**、**新增**。

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

| 列 | 说明 |
| --- | --- |
| 进场时间 | 格式 `YYYY-MM-DD HH:mm:ss` |
| 供应商 | 展示供应商名称 |
| 检疫证号 | — |
| 数量（头） | — |
| 圈位分配情况 | 提供 **「圈位分配表」** 链接或按钮；点击后查看本分圈明细（弹窗只读表格，列：圈位编号、数量、耳标号） |
| 隔离天数（天） | — |
| 解除隔离日期 | 展示预计解除日期（与表单「预计解除日期」一致） |
| 操作 | **查看**、**编辑**、**删除** |

---

### 5.3 修改入场隔离登记

| 项 | 规则 |
| --- | --- |
| 可改范围 | **主表全部业务字段**及**全部分圈明细**（增删改分圈行）均可修改 |
| 校验 | 与 **§5.1** 相同（含 **§2.6**、耳标不可跨圈重复、圈位不可重复） |
| 进场时间/隔离天数 | 修改后**重新计算**预计解除日期 |
| 保存后 | 不自动触发下游出圈或巡查；仅更新本台账 |

> **说明：** 草稿写「所有均可修改」；**进场时间、检疫证号等业务字段均可改**；分圈须重新满足一致性。若未来存在「已解除隔离不可改」等状态，须单独立项，**本期无状态机，默认可改**。

---

### 5.4 查看入场隔离登记

- **任意记录**可查看；只读展示主表全部字段、检疫证文件（可下载/预览）、预计解除日期、分圈明细表。  
- 列表「圈位分配表」与查看内分圈展示**数据一致**。  
- 查看界面可提供 **编辑** 入口（跳转或打开编辑弹窗，权限控制见 **§6**）。

---

### 5.5 删除入场隔离登记

| 项 | 规则 |
| --- | --- |
| 方式 | **单条**删除；二次确认；确认文案宜展示检疫证号或进场时间便于识别 |
| 效果 | **逻辑删除**；删除后列表不可见 |
| 拒绝 | 存在下游关联时禁止删除（见 **§2.9**） |

---

## 6. 操作与权限（业务层）

| 操作 | 说明 |
| --- | --- |
| 列表查询 | 进入模块、搜索、重置 |
| 新增 | 工具栏「新增」 |
| 查看 | 行内「查看」、圈位分配表 |
| 修改 | 行内「编辑」、查看页进入编辑 |
| 删除 | 行内「删除」 |

无权限时对应按钮不展示或禁用（权限标识命名由实施阶段定义，**本文档不展开**）。

---

## 7. 与下游及关联模块衔接

| 模块/下游 | 本模块提供 |
| --- | --- |
| **供应商管理** | 登记与筛选时选择合法供应商 |
| **隔离圈位管理** | 分圈选择合法圈位；新增默认隔离天数引用全局配置 |
| **隔离巡查登记**（规划） | 可按本台账进场时间、圈位、耳标开展巡查（集成规则另文档约定） |
| **隔离期满/出圈**（规划） | 可参考「预计解除日期」与隔离天数（自动出圈本期不做） |

---

## 8. 提示约定（示例）

| 场景 | 示例文案 |
| --- | --- |
| 必填 | 「请填写检疫证号」「请选择供应商」 |
| 耳标格式 | 「耳标号格式不正确」「存在重复耳标：{tag}」 |
| 数量与耳标 | 「总数量须与耳标个数一致」 |
| 分圈一致性 | 「分圈数量之和须等于总数量」「存在未分圈的耳标」「耳标 {tag} 已分配至其他圈位」 |
| 圈位重复 | 「圈位 {code} 已添加，不可重复」 |
| 文件 | 「仅支持 pdf/doc/docx 等格式，且不超过 30MB」 |
| 删除 | 「确认删除该条入场隔离登记？」「存在关联业务，无法删除」 |
| OCR 预留 | 「检疫证自动识别功能即将上线，请手工填写」 |

---

## 9. 非功能建议（业务侧）

- 进场登记、分圈调整、删除宜记**操作审计**（操作人、时间）。  
- 列表与表单文案支持 **i18n**（汉语 + 藏文），与项目前端规范一致。  
- 耳标、数量、分圈校验宜在**保存前**前端预校验，服务端**再次校验**以保证 **§2.6** 不被绕过。

---

## 10. 修订记录

| 版本 | 说明 |
| --- | --- |
| 1.0 | 依据草稿与原型整理：主表/分圈结构、一致性规则 R1～R5、流程图；剔除库表/接口/技术栈；OCR 列为本期不实现；默认隔离天数关联隔离圈位管理 |