# 市场进栏登记 — 功能需求

## 1. 文档说明

| 项 | 说明 |
| --- | --- |
| 模块名称 | 市场进栏登记（交易市场平台） |
| 目标 | 登记牲畜**进入市场栏位**的时间、栏位、供应商、耳标与头数，形成可查询、可维护的进栏台账 |
| 依据 | 同目录 `市场进栏登记-草稿.md`、界面原型 `Snipaste_2026-05-22_10-29-24.jpg` |
| 范围 | **仅功能与业务规则**；不含库表、接口、报文、技术栈 |

### 1.1 谁在什么场景使用

| 角色 | 场景 |
| --- | --- |
| 交易市场运营人员 | 日常登记进栏、查询历史、修正错误、删除无效记录 |
| 系统管理员 | 配置菜单与操作权限 |

进入 **「市场进栏登记」** 后，默认打开**进栏记录列表**。

### 1.2 与上下游的关系（业务视角）

```text
供应商管理、市场栏位管理 ──► 主数据（选供应商、选栏位）
入场隔离登记 ──────────────► 提供「该供应商曾登记过哪些耳标」
隔离巡查登记 ──────────────► 提供「哪些耳标已按病死/病害处理，须剔除」
市场进栏登记（本模块） ────► 记录「哪些耳标已进入哪个市场栏位」
```

---

## 2. 核心业务概念

### 2.1 一条进栏记录表示什么

一次**进栏事件**：在**进栏时间**，**某供应商**的一批牲畜（用多个**耳标号**标识）进入**某个市场栏位**。

| 信息项 | 说明 |
| --- | --- |
| 进栏时间 | 何时进栏 |
| 栏位编号 | 进哪个市场栏位（如 `01`） |
| 供应商 | 哪一家供货 |
| 耳标号 | 本批每一头牲畜的标识，至少 1 个 |
| 数量（头） | 本批共几头，**必须等于耳标个数** |

### 2.2 记录状态

| 状态 | 用户可见 | 业务含义 |
| --- | --- | --- |
| 有效 | 列表中展示 | 参与「耳标是否已被进栏占用」判断 |
| 已删除 | 列表中不展示 | 数据保留备查；占用的耳标**释放**，可再次被选用 |

删除指业务上的**作废**，非物理抹除；**本期无回收站**。

---

## 3. 字段与录入规则

### 3.1 进栏时间

- **必填**；`YYYY-MM-DD HH:mm:ss`。  
- **新增**默认**当前时间**，可改。  
- **不得晚于**当前时间；可填当前或更早时间（允许补录）。  
- 列表按「进栏日期」筛选时，取本字段的**日期部分**。

### 3.2 栏位编号

- **必填**；下拉**单选**，**不可手输**。  
- 仅能选 **市场栏位管理** 中仍有效的栏位。  
- 栏位作废后：历史进栏仍可查；**新登记、修改**不能再选该栏位。

### 3.3 供应商

- **必填**；登记表单中可**按名称模糊搜索**后选定一条。  
- 仅能选 **供应商管理** 中仍有效的供应商。  
- **列表筛选**为下拉**精确**匹配（选中某供应商则只查该家的进栏记录）。

### 3.4 耳标号

- **必填**；**多选**（下拉或标签形式），至少 **1** 个。  
- **须先选供应商**再选耳标；未选供应商时耳标不可选或为空。  
- **更换供应商**时，已选耳标**全部清空**，按新供应商重新加载可选项。  
- 同一条记录内**不得重复**选择同一耳标。  
- 耳标号书写规则与 **入场隔离登记** 一致（单段 1～32 字符等）。

### 3.5 数量（头）

- **必填**；正整数；单位「头」。  
- **只读或自动带出**：**数量 = 当前勾选的耳标个数**。  
- 用户**不能**把数量改成与耳标数不一致。  
- 增删耳标时，数量**即时联动**。

---

## 4. 可选耳标如何产生（草稿核心规则）

原型要求：「该供应商下**未病死、未病害**的耳标号」。由**入场隔离**（按供应商）与**隔离巡查**（全表病死病害）两步得出候选耳标；用户选定供应商后按下述规则计算（入场隔离须满足 **§4.1**；巡查、进栏记录须为**未删除的有效**记录）：

| 场景 | 计算结果 |
| --- | --- |
| **下拉可选耳标**（选供应商后加载） | **A − B**（§4.1、§4.2） |
| **保存时最终可选** | **（A − B）− C**（§4.3 占用校验，含编辑释放本条） |

### 4.1 第一步：按供应商汇总入场隔离耳标

在 **入场隔离登记** 中按口径筛选记录，汇总**主表总耳标**并**去重**，得到集合 **A**。若 **A** 为空，可选列表为空，提示用户确认该供应商是否存在**已隔离结束**的入场隔离登记。

#### 业务口径（已确认）

| 序号 | 口径 | 说明 |
| --- | --- | --- |
| ① | **只取主表总耳标** | 仅使用入场隔离登记**主表**的**总耳标号集合**（多个耳标以逗号等方式存放的须拆分汇总）；**不包含**分圈明细中的耳标 |
| ② | **按供应商、未删除** | 以当前所选**供应商**为条件；仅纳入**未删除**的入场隔离登记（已作废/已删除的单据不参与） |
| ③ | **隔离已结束** | 仅纳入**隔离期已满、可以进入市场环节**的单据；以入场隔离登记中的**预计解除日期**与当前日期判定：**当前日期不早于预计解除日期**（即已达到或超过预计解除日）的记录才纳入；**仍在隔离期内**的单据**不纳入** |

#### 计算步骤

1. 按供应商查找**未删除**且**隔离已结束**的入场隔离登记。  
2. 对每条记录取**主表总耳标**并拆分、汇总。  
3. **去重**得集合 **A**。

### 4.2 第二步：剔除隔离巡查中的病死、病害耳标

在 **隔离巡查登记** 中筛选**全部**符合条件的巡查记录（**不按供应商过滤**），汇总病死、病害耳标，**去重**得集合 **B**；**下拉可选耳标** = **A － B**。已在巡查中登记为病死、病害的耳标，**不允许再进市场栏位**。

#### 业务口径（已确认）

| 序号 | 口径 | 说明 |
| --- | --- | --- |
| ① | **未删除** | 仅纳入**未删除**的隔离巡查登记 |
| ② | **病死、病害** | 仅纳入 **病死病害数量大于 0**，且**填写了耳标号**的巡查记录 |
| ③ | **耳标汇总** | 主表 `耳标号` 字段以逗号等方式存放多个耳标时须**拆分**后汇总、**去重** |

#### 计算步骤

1. 查询隔离巡查登记表：`del_flag` 为有效、病死病害数量 **> 0**、耳标号**非空**。  
2. 取出全部符合条件的**耳标号**（拆分、去重）得集合 **B**。  
3. **A － B** 为剔除病死、病害后的下拉候选（保存时再经 §4.3 剔除占用）。

### 4.3 第三步：保存时剔除已被其他进栏记录占用的耳标

1. 在**有效**的**市场进栏登记**中，汇总**除当前正在编辑的记录外**已登记的全部耳标，得集合 **C**。  
2. **保存校验**时，每个耳标须属于 **（A－B）－ C**；**下拉加载**仅返回 **A－B**（不含 C，已占用的耳标仍可能出现在下拉中，保存时由服务端拦截）。  
3. **修改**某条进栏记录时：该记录**原先已选的耳标**视同未占用（便于保留或调整）。

> **§4.3** 为避免同一耳标被重复进栏而补充；草稿正文仅写明 **§4.1、§4.2**。

### 4.4 耳标池与界面联动（小结）

| 时机 | 行为 |
| --- | --- |
| 选定供应商 | 调用可选耳标接口，按 §4.1、§4.2 返回 **A−B** |
| 更换供应商 | 清空已选耳标，重新计算 **A−B** |
| 勾选耳标 | 更新数量（头） |
| 保存 | 按 **（A−B）−C** 再次校验 §5（含占用） |

---

## 5. 保存时必须满足的规则

新增、修改点击**确定**时，全部满足方可保存；否则提示原因且不保存：

| 编号 | 规则 | 内容 |
| --- | --- | --- |
| **R1** | 必填完整 | 进栏时间、栏位、供应商、至少 1 个耳标 |
| **R2** | 时间合法 | 进栏时间不晚于当前时间 |
| **R3** | 主数据有效 | 栏位、供应商在各自管理中仍为可选状态 |
| **R4** | 耳标在可选池内 | 每个耳标均属于 **（A−B）−C**（§4.1～§4.3）；病死、病害及他单占用均不可保存 |
| **R5** | 耳标不重复 | 本条记录内耳标互不重复 |
| **R6** | 数量一致 | 数量（头）= 本条已选耳标个数 |

---

## 6. 功能清单

### 6.1 新增进栏记录

| 项 | 要求 |
| --- | --- |
| 入口 | 列表「新增」 |
| 表单 | §3 各字段；§4 耳标池；§5 保存校验 |
| 确定 | 保存为**有效**记录，关闭表单，刷新列表 |
| 取消 | 不保存 |

**推荐操作顺序**：打开新增 → 确认进栏时间 → 选栏位 → 选供应商 → 多选耳标 → 核对数量 → 确定。

### 6.2 查询进栏记录列表

| 项 | 要求 |
| --- | --- |
| 筛选 | 进栏日期（起～止，闭区间）；栏位编号**模糊**；供应商**精确**；耳标号**模糊**；条件**同时**生效 |
| 日期校验 | 开始日期晚于结束日期时提示修正，不执行查询 |
| 默认排序 | 进栏时间**从新到旧** |
| 分页 | 默认每页 **20** 条 |
| 范围 | 仅**有效**记录 |
| 工具栏 | 搜索、重置、新增 |
| 列 | 进栏时间、栏位编号、供应商、耳标号、数量（头）、操作 |
| 操作 | 查看、编辑、删除 |

### 6.3 修改进栏记录

- 草稿要求：**所有业务字段均可修改**（进栏时间、栏位、供应商、耳标及联动数量）。  
- 规则同新增（§4、§5）；更换供应商须清空耳标重选。  

### 6.4 查看进栏记录

- **只读**展示 §3 全部业务字段；耳标**完整**展示；宜展示创建/修改人及时间。  
- 可提供「编辑」「删除」（受权限控制）。

### 6.5 删除进栏记录

| 项 | 要求 |
| --- | --- |
| 方式 | 列表单条删除；**二次确认**（确认语宜含供应商、栏位、时间或头数） |
| 结果 | 记录变为**已删除**；列表不再显示 |
| 约束 | 若已被结算、开单等**下游业务引用**，**不允许删除**并提示 |
| 耳标 | 删除后，该记录占用的耳标回到可选范围（§4.3） |

### 6.6 本期不做

检疫证上传、栏位占用看板、批量导入导出、与结算/称重自动联动、栏位超容预警等（见原范围评审）。

---

## 7. 业务流程图

### 7.1 模块主流程

```mermaid
flowchart TD
    A[进栏记录列表] --> B{操作}
    B --> C[新增]
    B --> D[查看]
    B --> E[修改]
    B --> F[删除]
    C --> G[填写时间/栏位/供应商]
    G --> H[计算可选耳标 A-B-C]
    H --> I[勾选耳标/自动数量]
    I --> J{R1-R6 通过?}
    J -->|否| I
    J -->|是| K[保存]
    K --> A
    E --> G
    F --> L{下游引用?}
    L -->|是| M[提示不可删]
    L -->|否| N[确认后删除]
    N --> A
```

### 7.2 可选耳标计算

```mermaid
flowchart LR
    A[选供应商] --> B[入场隔离汇总耳标 A]
    B --> C[减去巡查病死病害 B]
    C --> D[减去他单已进栏 C]
    D --> E[用户多选]
    E --> F[数量=勾选数]
```

---

## 8. 权限（业务层）

| 能力 | 说明 |
| --- | --- |
| 查列表 | 进入模块、筛选浏览 |
| 看详情 | 只读 |
| 新增 | 创建记录 |
| 修改 | 变更记录 |
| 删除 | 作废记录 |

无权限则不显示对应按钮。具体权限项由实施配置，本文档不命名编码。

---

## 9. 关联模块约定

| 模块 | 本模块如何使用 |
| --- | --- |
| 市场栏位管理 | 提供可选栏位 |
| 供应商管理 | 提供可选供应商；列表筛选 |
| 入场隔离登记 | §4.1 耳标来源（主表总耳标；按供应商、未删除、**隔离已结束**） |
| 隔离巡查登记 | §4.2 全表未删除、病死病害数量>0 且填耳标的巡查记录汇总耳标（逗号拆分）后从 A 中剔除 |
| 供应商结算等 | 可引用进栏数据；删除前检查是否被引用 |

**说明**：入场隔离（隔离圈位）与市场进栏（市场栏位）为不同业务；**默认不规定**同一耳标不能同时出现在两类登记中，若产品要求互斥须另行立项。

---

## 10. 提示语（示例）

| 情况 | 示例文案 |
| --- | --- |
| 缺栏位/供应商/耳标 | 请选择栏位编号 / 请选择供应商 / 请至少选择一个耳标号 |
| 未先选供应商 | 请先选择供应商 |
| 无可选耳标 | 该供应商暂无可进栏耳标，请确认是否存在已隔离结束的入场隔离登记 |
| 耳标重复 | 存在重复耳标：{耳标号} |
| 耳标已被其他进栏占用 | 耳标 {耳标号} 已被其他进栏记录占用 |
| 耳标不可进栏 | 耳标 {耳标号} 不可进栏或不在可选范围 |
| 进栏时间超前 | 进栏时间不能晚于当前时间 |
| 筛选日期颠倒 | 开始日期不能晚于结束日期 |
| 主数据失效 | 市场栏位不存在或已删除 / 供应商不存在或已删除 |
| 删除被引用 | 存在关联业务，无法删除 |

---

## 11. 非功能建议

| 项 | 建议 |
| --- | --- |
| 权限 | 查询、新增、修改、删除分权 |
| 审计 | 增删改留痕 |
| 易用性 | 删除二次确认；列表耳标过长可省略、详情看全文 |
| 正确性 | 保存时**系统**须按 §5 再次校验，不能仅依赖页面上的数量与勾选 |

---

## 12. 草稿对照

| 草稿条目 | 对应章节 |
| --- | --- |
| 1 新增与字段、数量=勾选耳标数 | §3、§6.1 |
| 2 入场隔离汇总耳标，减去巡查病死病害 | **§4.1、§4.2** |
| 3 列表筛选 | §6.2 |
| 4 修改均可改 | §6.3 |
| 5 删除 | §6.5（业务作废） |
| 6 查看 | §6.4 |
| 7～8 异常格式、技术栈 | **不纳入本文档** |

---

## 13. 修订记录

| 版本 | 说明 |
| --- | --- |
| 1.2 | 按草稿 §2 明确耳标池两步算法；流程与 R1～R6 规则 |
| 1.3 | 纯需求优化：不参照实现方案；精简结构；R 规则替代 M 编号；明确 §4.3 为进栏互斥补充；去除「服务端」等实现用语 |
| 1.4 | §4.1：仅主表总耳标；按供应商查**未删除、隔离已结束**的入场隔离单（当前日期 ≥ 预计解除日期） |
| 1.5 | §4.2：按供应商相关的**未删除**巡查记录；病死病害数量>0 且填耳标；明确供应商关联判定 |
| 1.6 | §4.2：巡查**不按供应商**过滤，全表病死病害耳标汇总为 B；下拉 **A−B**；保存 **(A−B)−C**；`supplierEarTags` 仅 `supplierId` |