huimv-baqing/doc/交易市场平台/隔离圈位管理/隔离圈位管理功能需求.md

隔离圈位管理 — 功能需求

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

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 约定