huimv-baqing/doc/交易市场平台/入场隔离登记/入场隔离登记功能需求.md

入场隔离登记 — 功能需求

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 模块总览

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 分圈子流程

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 列为本期不实现；默认隔离天数关联隔离圈位管理