# 隔离圈位管理 — 功能需求

## 1. 文档说明

| 项 | 说明 |
| --- | --- |
| 模块名称 | 隔离圈位管理（交易市场平台） |
| 目标 | 在业务后台维护交易市场**隔离圈位台账**（圈位编号、备注等），并维护**全局默认隔离天数**等参数，为入场检疫、隔离观察、圈位分配等后续业务提供基础主数据 |
| 关联系统 | 业务后台；本模块为圈位与隔离参数的**主档维护**，不替代牲畜入圈登记、隔离期满判定、自动出圈等作业流程（若需联动，另出集成需求） |
| 修订依据 | 同目录 `隔离圈位管理-草稿.md`、界面原型（`隔离圈位管理.png`） |

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

---

## 2. 术语与业务对象

### 2.1 隔离圈位（一条台账记录）

- 表示交易市场内用于**隔离观察**的一个物理或逻辑**圈位**（栏位）。  
- 由运营人员在后台**登记与维护**；保存成功后出现在圈位列表，供后续业务按圈位编号引用、分配或展示状态。  
- 单条记录包含：**圈位编号**、**备注**（选填）及审计信息（创建人、时间等，与项目其他台账一致）。

### 2.2 圈位编号

- **系统自动生成**，用户**不可手工录入或修改**（新增弹窗中只读或「保存后自动生成」占位；修改、查看时只读）。  
- 格式：**2 位数字**字符串，建议左侧补零（如 `01`、`02` … `99`）。  
- **全局唯一**：同一系统内未删除的圈位不得重复；编号用尽（如已达 `99`）时拒绝继续新增并提示「圈位编号已达上限，请联系管理员」。  
- 生成时机：用户点击新增「确定」且校验通过后分配。

> **说明：** 草稿写「修改时所有均可修改」指**业务可编辑字段**；**圈位编号不在可改范围内**，与自动生成语义一致。

### 2.3 备注（圈位）

- 对圈位的补充说明（如位置、容量提示等）。  
- **选填**；有内容时长度 **1～50** 个字符（去除首尾空白后计数）；仅空白视为未填。

### 2.4 默认隔离天数（全局配置）

- 与单条圈位台账**相互独立**，表示系统级**默认隔离观察天数**（单位：**天**）。  
- 通过列表页工具栏 **「设置隔离天数」** 进入专用弹窗维护；**全系统仅保留一份当前生效配置**（再次保存即覆盖更新，不产生多条并列「当前默认」）。  
- 业务含义：后续入圈、检疫等流程在需要「默认隔离期」时，优先引用此处配置；具体引用规则由下游模块定义，本模块只负责维护数值与备注。  
- 字段：**默认隔离天数**（必填）、**备注**（选填，≤50 字）。

#### 2.4.1 默认隔离天数取值规则

| 规则 | 说明 |
| --- | --- |
| 类型 | **正整数**（不含小数、不含字母） |
| 必填 | 保存时不得为空 |
| 建议范围 | **1～3650** 天（评审可按业务调整为 1～999 等；超出上限拒绝保存并提示） |
| 展示 | 输入框旁或标签标明单位「天」 |

### 2.5 删除与可见性

- 圈位删除采用与项目其他业务台账一致的**逻辑删除**：删除后默认不在列表与常规查询中展示，数据保留供审计。  
- **本期不提供**回收站界面。  
- 若圈位已被入圈登记、检疫单、栏位占用等下游业务引用，**宜禁止删除**并提示「存在关联业务，无法删除」（**默认建议禁止**）。

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

| 筛选项 | 与记录字段关系 |
| --- | --- |
| 圈位编号 | 选填；对「圈位编号」**模糊**匹配（包含输入片段即可，如输入 `1` 可命中 `01`、`11` 等，与项目全局模糊查询一致） |
| （无其他筛选项） | 原型仅提供圈位编号筛选；空则不过滤 |

---

## 3. 功能范围

**本期实现：**

| 能力 | 说明 |
| --- | --- |
| 圈位列表 | 圈位编号模糊筛选；分页；见 **§5.2** |
| 新增圈位 | 录入备注；编号自动生成；见 **§5.1** |
| 修改圈位 | 仅备注可改；见 **§5.3** |
| 查看圈位 | 只读展示；见 **§5.4** |
| 删除圈位 | 单条删除；见 **§5.5** |
| 设置隔离天数 | 维护全局默认隔离天数及备注；见 **§5.6** |
| 工具栏 | 搜索、重置、新增；**设置隔离天数**（与列表同页，见原型） |

**本期不实现（除非后续单独立项）：**

- 圈位占用状态、在栏牲畜清单、实时空满率看板  
- 按备注、按占用状态的列表筛选  
- 批量导入/导出、编号手工指定  
- 单圈位单独设置隔离天数（本期仅全局默认）  
- 隔离期满自动提醒、与检疫流程的自动联动  

---

## 4. 业务流程概览

### 4.1 总览

```mermaid
flowchart TD
    A[进入隔离圈位管理] --> B{用户操作}
    B -->|维护圈位| C[圈位台账分支]
    B -->|维护参数| D[设置隔离天数]
    C --> E{圈位操作}
    E -->|新增| F[填写备注并保存]
    F --> G[系统分配圈位编号]
    G --> H[刷新圈位列表]
    E -->|查询| I[输入编号片段模糊搜索]
    I --> H
    E -->|查看/编辑/删除| J[行内或详情操作]
    J --> H
    D --> K[填写默认天数与备注]
    K --> L{校验}
    L -->|通过| M[保存全局配置]
    L -->|未通过| D
    M --> H
```

### 4.2 典型使用顺序

1. 管理员首次进入模块，通过 **「设置隔离天数」** 配置全局默认隔离期（如 7 天）及说明备注。  
2. 运营人员按现场布局 **新增** 圈位，系统分配 `01`、`02` … 等编号，必要时填写备注。  
3. 日常按圈位编号 **模糊** 查询台账。  
4. 圈位信息变更时 **修改** 备注（编号不变）；废弃圈位在确认无关联后 **删除**。  
5. 隔离政策调整时，再次打开 **设置隔离天数** 更新全局默认值（不影响已发生的历史业务数据，仅影响后续按默认天数计算的流程）。

### 4.3 圈位台账与全局配置的关系

| 维度 | 圈位台账 | 默认隔离天数配置 |
| --- | --- | --- |
| 数据粒度 | 多条（每个圈位一条） | 全系统一份当前生效值 |
| 入口 | 新增 / 行内编辑 | 工具栏「设置隔离天数」 |
| 列表是否展示 | 是 | 否（不在列表列中展示） |
| 删除 | 支持单条逻辑删除 | 不支持「删除配置」；仅支持修改覆盖 |

---

## 5. 详细功能需求

### 5.1 新增隔离圈位

#### 5.1.1 业务字段

| 字段 | 必填 | 规则摘要 |
| --- | --- | --- |
| 圈位编号 | — | **只读**；保存成功后展示系统生成的 2 位数字编号 |
| 备注 | 否 | 文本；**0～50** 字（有内容时按 1～50 校验） |

#### 5.1.2 保存与取消

| 操作 | 行为 |
| --- | --- |
| **确定** | 校验通过后保存；分配圈位编号；关闭弹窗并**刷新圈位列表** |
| **取消** | 关闭弹窗，不保存 |

#### 5.1.3 校验摘要

| 规则 | 说明 |
| --- | --- |
| 备注长度 | 超过 50 字拒绝保存 |
| 编号上限 | 已达 `99` 且无法再分配时拒绝新增 |

---

### 5.2 查询隔离圈位列表

#### 5.2.1 筛选

| 条件 | 规则 |
| --- | --- |
| 圈位编号 | 选填；**模糊**匹配（**§2.6**） |

#### 5.2.2 列表规则

- 默认每页 **20** 条。  
- 默认排序：**圈位编号升序**（产品若选用创建时间倒序，须全文一致；**默认建议编号升序**）。  
- 工具栏：**搜索**、**重置**、**新增**；**设置隔离天数**（位置与原型一致，通常位于筛选区右侧或列表卡片标题栏）。

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

圈位编号、备注、操作。

| 列 | 展示说明 |
| --- | --- |
| 圈位编号 | 2 位数字编号 |
| 备注 | 过长省略；详情可看全文；无内容展示「—」或留空（与项目统一空值展示一致） |
| 操作 | 查看、编辑、删除（权限见 **§6**） |

---

### 5.3 修改隔离圈位

| 项 | 要求 |
| --- | --- |
| 入口 | 列表「编辑」；详情可提供「编辑」 |
| 不可改字段 | **圈位编号**（只读） |
| 可改范围 | **备注** |
| 校验 | 同 **§5.1.3** |
| 保存 | **确定** 保存并刷新列表；**取消** 放弃 |

---

### 5.4 查看隔离圈位详情

| 项 | 要求 |
| --- | --- |
| 展示内容 | 圈位编号、备注全文 |
| 只读 | 全部不可编辑 |
| 操作 | 可提供 **编辑**、**删除**（与列表权限一致）；**关闭** 返回列表 |
| 审计信息 | 宜含创建人、创建时间、修改人、修改时间（与项目其他台账一致） |
| 全局隔离天数 | **不在此展示**（属于全局配置，非单条圈位属性） |

---

### 5.5 删除隔离圈位

| 项 | 要求 |
| --- | --- |
| 入口 | 列表「删除」；详情可提供「删除」 |
| 确认 | 删除前**二次确认**（宜展示圈位编号，有备注时一并展示） |
| 删除方式 | **逻辑删除**（**§2.5**） |
| 关联约束 | 存在下游引用时**拒绝删除**并提示原因 |
| 批量删除 | **本期不提供** |

---

### 5.6 设置隔离天数（全局配置）

#### 5.6.1 入口与界面

| 项 | 要求 |
| --- | --- |
| 入口 | 列表页 **「设置隔离天数」** 按钮（与原型一致） |
| 展现形式 | 独立弹窗（标题宜为「设置隔离天数」或「默认隔离天数」） |
| 与圈位新增区别 | 不分配圈位编号、不增加列表行 |

#### 5.6.2 业务字段

| 字段 | 必填 | 规则摘要 |
| --- | --- | --- |
| 默认隔离天数 | 是 | 正整数；单位 **天**；范围见 **§2.4.1** |
| 备注 | 否 | 文本；**0～50** 字 |

#### 5.6.3 打开弹窗时的数据回显

| 场景 | 行为 |
| --- | --- |
| 已配置过 | 回显当前生效的默认隔离天数与备注 |
| 从未配置 | 字段为空；用户填写后首次保存即建立当前配置 |

#### 5.6.4 保存与取消

| 操作 | 行为 |
| --- | --- |
| **确定** | 校验通过后**覆盖保存**全局配置；关闭弹窗；**不要求**刷新圈位列表（无列表列变化）；宜给出「保存成功」类提示 |
| **取消** | 关闭弹窗，不保存 |

#### 5.6.5 校验摘要

| 规则 | 说明 |
| --- | --- |
| 默认隔离天数 | 为空、非整数、小于 1 或超过约定上限时拒绝保存 |
| 备注 | 超过 50 字拒绝保存 |

---

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

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

| 操作 | 列表/详情/弹窗 | 说明 |
| --- | --- | --- |
| 查询列表、筛选 | 列表页 | 需列表查询权限 |
| 新增圈位 | 「新增」 | 需新增权限 |
| 查看圈位 | 行内/详情 | 需查看权限 |
| 修改圈位 | 行内/详情 | 需修改权限；编号不可改 |
| 删除圈位 | 行内/详情 | 需删除权限 |
| 设置隔离天数 | 工具栏按钮及配置弹窗 | 需配置类权限（**默认建议**独立按钮权限；若项目惯例合并到修改权限，须在实施说明中明确） |

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

---

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

| 维度 | 承销商/供应商等台账 | 隔离圈位管理（本模块） |
| --- | --- | --- |
| 编号规则 | 2 位自动、不可改 | 同左 |
| 列表筛选 | 承销商等为编号模糊等 | 仅**圈位编号模糊** |
| 业务字段复杂度 | 多字段 | 圈位仅**备注**；另含**全局隔离天数** |
| 全局配置 | 无 | **设置隔离天数**（单份生效配置） |
| 列表列 | 多列 | 编号、备注、操作 |

---

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

| 场景 | 提示方向（示例） |
| --- | --- |
| 备注超长 | 备注长度不能超过 50 个字符 |
| 未填默认隔离天数 | 请输入默认隔离天数 |
| 隔离天数非正整数 | 请输入正确的隔离天数（正整数，单位：天） |
| 隔离天数超范围 | 隔离天数不能超过 N 天 |
| 编号用尽 | 圈位编号已达上限，请联系管理员 |
| 删除受阻 | 存在关联业务，无法删除 |

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

---

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

| 项 | 要求 |
| --- | --- |
| 易用性 | 圈位编号只读状态明确；「设置隔离天数」与「新增圈位」入口区分清晰，避免误操作 |
| 一致性 | 逻辑删除、分页、模糊筛选、校验风格与交易市场平台其他台账模块一致 |
| 可理解性 | 全局默认隔离天数与单条圈位备注用途区分，界面文案宜体现「默认」「全局」含义 |

---

## 10. 修订记录

| 版本 | 说明 |
| --- | --- |
| 1.0 | 初版：依据草稿与原型；圈位 CRUD + 全局默认隔离天数；编号 2 位自动生成、列表模糊筛选；剔除库表、接口、技术栈与 HTTP 约定 |