# 牧场管理 — 功能需求

## 1. 文档说明

| 项 | 说明 |
| --- | --- |
| 模块名称 | 牧场管理 |
| 目标 | 对养殖主体（牧场/养殖户）基础信息进行登记、查询、维护与查阅，支撑产业数据体系中的主体台账与后续业务关联 |
| 关联系统 | 业务后台 |
| 修订依据 | 同目录 `牧场管理功能需求-草稿.md`、界面原型（`Snipaste_2026-05-19_09-27-45.jpg`） |

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

---

## 2. 术语与枚举

### 2.1 牧场性质（单选）

| 取值 | 含义概要 |
| --- | --- |
| **个体** | 以个人身份经营的养殖主体 |
| **企业** | 以企业法人身份经营的养殖主体 |

### 2.2 经营状态（单选）

| 取值 | 含义概要 |
| --- | --- |
| **正常** | 在营，可参与常规业务（默认） |
| **停业** | 暂停经营，主体档案保留 |
| **注销** | 终止经营，主体档案保留但宜在业务上视为失效 |

### 2.3 证件类型与「身份证号」字段含义

界面字段标签可统一为「身份证号」，其**业务含义随牧场性质变化**：

| 牧场性质 | 字段实际含义 | 校验要求（摘要） |
| --- | --- | --- |
| 个体 | 居民身份证号码 | 18 位居民身份证格式及校验位（末位可为 `X`/`x`），与项目全局身份证规则一致 |
| 企业 | 主体识别号（如统一社会信用代码） | 符合企业主体识别号格式（建议 18 位字母数字组合；具体规则与项目全局「企业证照号」规范一致） |

保存或提交时，系统须按当前所选**牧场性质**切换校验规则，错误提示宜区分「身份证格式错误」与「主体识别号格式错误」。

### 2.4 所属区域

- **层级：** 省、市、县（区）**三级**行政区划级联选择。  
- **要求：** 须选至**县级**（含）为止，不可仅选省或市即提交（除非产品另行约定「允许只选到市级」）。

### 2.5 记录说明

- 本模块为**主体台账**，单条记录表示一个养殖主体（牧场）。  
- 删除采用**逻辑删除**：删除后默认不在列表与常规统计中展示，数据可保留供审计或恢复策略（恢复能力若需实现须单独约定）。  
- **地图标点**功能本期**不实现**（见 **§3**、**§8**）。

---

## 3. 功能范围

**本期实现：**

- 牧场的新增、修改、逻辑删除、分页列表查询、详情查看  
- 主体信息、所属区域、负责人与联系方式、经营状态、照片的录入与校验  
- 按牧场名称关键字、牧场性质的列表筛选  
- 列表操作：查看、编辑、删除；**不含**地图标点  

**本期不实现：**

- 地图标点、经纬度采集与地图展示  
- 与畜群、存栏、防疫等下游业务的关联维护（若需关联，另出需求）  

---

## 4. 业务流程概览

```mermaid
flowchart LR
    A[新增牧场] --> B[列表查询/筛选]
    B --> C[查看详情]
    B --> D[修改牧场]
    B --> E[逻辑删除]
    D --> B
    E --> B
```

1. **登记**：录入主体信息、区域与联系方式，可选上传照片 → 形成一条牧场记录；经营状态默认 **正常**。  
2. **查询**：按名称关键字、牧场性质筛选，分页浏览列表。  
3. **维护**：对已有记录修改任意业务字段；替换照片时清理旧图（实现阶段约定，需求层要求「不产生孤立文件」）。  
4. **查阅**：查看单条记录全部字段；列表可进入详情或弹窗查看。  
5. **删除**：逻辑删除；删除前宜二次确认；删除后默认列表不可见。

---

## 5. 详细功能需求

### 5.1 新增牧场

| 字段 | 规则 |
| --- | --- |
| 牧场名称 | **必填**；长度 **1～10** 个字符（与界面「限 10 字」一致；字符计数与项目全局一致） |
| 牧场性质 | **必填**；单选，取值 **§2.1**（个体 / 企业） |
| 身份证号 | **必填**；含义与校验见 **§2.3**；须与当前「牧场性质」一致 |
| 所属区域 | **必填**；省、市、县三级级联，须选至县级 |
| 详细地址 | **选填**；若有内容，长度不超过 **50** 个字符 |
| 负责人 | **选填**；若有内容，长度不超过 **10** 个字符 |
| 联系方式 | **必填**；须为**中国大陆手机号**格式（如 11 位、号段规则与项目全局一致） |
| 经营状态 | **必填**；单选，取值 **§2.2**；新建时默认 **正常** |
| 照片 | **选填**；**单张**图片；允许后缀 `jpg`、`jpeg`、`png`（可扩展 `webp` 须评审）；单文件 ≤ **10 MB** |

**必填字段汇总：** 牧场名称、牧场性质、身份证号（按性质校验）、所属区域（至县级）、联系方式、经营状态。

**联动与校验：**

- 切换「牧场性质」时，宜清空或重新校验「身份证号」输入，避免个体证件误用于企业。  
- 各字段校验失败时须给出**可区分**的错误提示。  
- 若业务要求「牧场名称」在管辖范围内唯一，须在评审时单独约定并写入本节。

---

### 5.2 查询牧场列表

- **关键字：** 对「牧场名称」进行**模糊**匹配；关键字为空时不按名称过滤。  
- **牧场性质：** **精确**匹配筛选；未选择时不按性质过滤。  
- **经营状态：** 本期草稿未要求列表筛选项；若界面提供「经营状态」筛选，则为精确匹配，规则与 **§2.2** 一致（实现前与产品确认）。  
- **逻辑删除：** 默认**不展示**已逻辑删除记录；是否提供「含已删除」查看能力须单独约定。  
- **分页：** 默认 **每页 20 条**，首页为第一页；单页条数上限与项目列表通用规范一致。  
- **排序：** 默认按 **创建时间倒序**（最新登记在前）；相同时间下次要排序键与项目列表规范一致（若有）。  
- **重置：** 支持一键清空查询条件并恢复默认列表（与界面「重置」一致）。

**列表宜展示：** 牧场名称、牧场性质、身份证号（可按脱敏规则展示）、所在区域（省市区拼接）、详细地址、负责人、联系方式（可脱敏）、经营状态、操作列（查看 / 编辑 / 删除）；**地图标点**入口本期不展示或置灰并提示「暂未开放」。

---

### 5.3 修改牧场

- **可修改项：** 牧场名称、牧场性质、身份证号、所属区域、详细地址、负责人、联系方式、经营状态、照片（**全部业务字段**均可修改）。  
- **保存约束：** 须重新满足 **§5.1** 全部校验；必填项不得为空。  
- **性质变更：** 若修改「牧场性质」，须按新性质重新校验「身份证号」；不允许保留与性质不匹配的证件号。  
- **照片替换：** 上传新照片并保存成功后，旧照片文件宜从存储中删除，避免残留（与项目附件管理惯例一致）。  
- **经营状态变更：** 允许在 **正常 / 停业 / 注销** 之间变更；是否限制「注销后不可改回正常」须在评审时约定（**默认：允许改回**，便于纠错）。

---

### 5.4 删除牧场（逻辑删除）

- **允许删除：** 具备删除权限的用户可对单条或多条记录执行删除（是否支持批量删除与项目列表惯例一致）。  
- **删除方式：** **逻辑删除**，非物理抹库；删除后该主体在默认列表与常规统计中不可见。  
- **删除后果：**  
  - 已逻辑删除记录**不宜**被下游业务当作有效主体引用（若存在关联，须在关联模块约定校验）。  
  - 照片文件是否立即删除或保留至归档策略，实现阶段与运维约定；需求层要求删除操作**可审计**（谁、何时删除）。  
- **确认：** 删除前宜弹出确认提示，避免误删。  
- **恢复：** 是否提供「恢复已删除」管理功能，本期不强制；若需要须单独需求。

---

### 5.5 查看牧场详情

- **展示内容：** 牧场名称、牧场性质、身份证号、所属区域（省 / 市 / 县）、详细地址、负责人、联系方式、经营状态、照片（可预览）；宜展示创建人、创建时间、最后修改人、最后修改时间（若系统有审计字段）。  
- **敏感信息：** 身份证号、手机号在列表/详情是否脱敏，按项目安全规范与角色权限约定。  
- **交互：** 具备编辑权限的用户可从详情进入编辑（见 **§5.3**）；只读账号仅可查看。

---

### 5.6 地图标点（本期不实现）

- 列表操作列原型含「地图标点」；**本期不实现**点位采集、地图展示与坐标存储。  
- 若后续实现，须单独修订本文档，约定：坐标字段、与地址关系、权限及是否在「注销」主体上禁止标点等。

---

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

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

| 操作 | 说明 |
| --- | --- |
| 查看 | 具备查询权限即可 |
| 新增 | 具备新增权限即可 |
| 修改 | 具备修改权限即可 |
| 删除 | 具备删除权限即可；逻辑删除前确认 |
| 地图标点 | 本期无 |

菜单与按钮级权限（查询、新增、修改、删除、导出等）按项目角色配置，具体标识在技术方案或权限配置文档中定义。

---

## 7. 错误与提示约定

- 业务与校验错误宜采用项目统一的 **`code`、`msg`、`data`** 结构呈现，便于前端统一处理。  
- 常见提示宜可区分，例如：  
  - 必填项缺失、字段超长或格式不符；  
  - 个体身份证与企业主体识别号校验失败；  
  - 所属区域未选至县级；  
  - 照片格式或大小不符；  
  - 删除确认取消与删除失败原因。  

---

## 8. 非功能需求（建议）

| 类别 | 建议 |
| --- | --- |
| 权限 | 菜单与按钮：查询、新增、修改、删除；敏感字段完整查看是否分角色 |
| 审计 | 新增、修改、逻辑删除记操作日志 |
| 安全 | 上传照片类型与大小校验；预览与下载鉴权 |
| 性能 | 列表按名称、性质筛选满足后台通用体验 |
| 数据质量 | 行政区划数据与国家标准或项目区划库一致，避免「市辖区」等异常选项 |
| 双语 | 字段标签与提示符合项目 i18n 规范（汉语 + 藏文） |
| 扩展 | 地图标点、主体与产业业务关联、名称唯一性、已删除恢复 |

---

## 9. 修订说明（相对草稿）

| 草稿问题 | 优化处理 |
| --- | --- |
| 条目编号跳跃（1～5 后直接 10～12） | 重整为 **§5** 分节与连续叙述 |
| 混入技术栈、接口响应格式 | 技术栈移除；错误结构保留于 **§7**（不涉及接口设计） |
| 「身份证号」未区分个体/企业 | 新增 **§2.3** 联动校验说明 |
| 所属区域、详细地址、负责人必填性不清 | 区域必填至县；地址、负责人选填；与界面必填项对齐并注明差异 |
| 逻辑删除后果未写清 | **§2.5、§5.2、§5.4** 补充默认不可见、关联与审计建议 |
| 地图标点写在需求条目中 | 明确 **§3、§5.6** 本期不实现 |
| 列表缺重置、排序、展示列 | **§5.2** 补充 |
| 经营状态仅枚举未说明默认 | **§2.2** 默认「正常」及变更策略 |
| 界面称「养殖户」、文档称「牧场」 | **§1** 统一为养殖主体（牧场），允许界面文案沿用「养殖户」 |

---

## 10. 功能需求追溯（自查）

| 能力 | 对应章节 |
| --- | --- |
| 新增与字段校验 | §5.1、§2.3 |
| 列表查询与筛选 | §5.2 |
| 修改与照片替换 | §5.3 |
| 逻辑删除 | §5.4 |
| 详情查看 | §5.5 |
| 地图标点（不做） | §3、§5.6 |
| 权限与错误提示 | §6、§7 |