# 草场使用记录 — 功能需求

## 1. 文档说明

| 项 | 说明 |
| --- | --- |
| 模块名称 | 草场使用记录 |
| 目标 | 登记、查询、维护草场被养殖主体实际占用的时段、面积与放牧信息，形成可追溯的利用台账，支撑监管统计与草场承载分析 |
| 关联系统 | 业务后台；依赖「草场管理」「牧场管理（养殖主体）」主数据 |
| 修订依据 | 同目录 `草场使用记录功能需求-草稿.md`、界面原型（`Snipaste_2026-05-19_11-19-52.jpg`） |

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

---

## 2. 术语与枚举

### 2.1 关联主数据

| 概念 | 说明 |
| --- | --- |
| **草场** | 来源于「草场管理」模块中**未删除**的草场台账；本模块通过下拉选择关联，展示「草场名称」 |
| **养殖主体** | 来源于「牧场管理」模块中**未删除**的养殖主体（牧场/养殖户）台账；本模块通过下拉选择关联，展示「养殖主体名称」 |

选择草场或养殖主体时，下拉须支持**关键字模糊检索**（与界面「支持模糊搜索输入」一致），仅能选择主数据中存在的有效记录，**不允许**手工输入名称替代选择（除非产品另行约定「临时主体」能力）。

### 2.2 放牧方式（单选）

| 取值 | 含义概要 |
| --- | --- |
| **轮牧** | 按小区或时段轮换放牧 |
| **自由放牧** | 在约定范围内自由采食，无固定轮牧计划 |
| **季节性放牧** | 仅在特定季节或窗口内放牧 |

### 2.3 记录说明

- 单条记录表示：**某一养殖主体在某一草场上的一次（段）使用行为**，以开始使用日期、结束使用日期界定时段。  
- 同一块草场、同一主体在时间上可存在多条记录（例如不同季节分次使用）；是否允许时段**重叠**须在评审时约定（**默认：允许重叠登记，由业务人员自行避免重复统计**；若需系统拦截重叠，单独补充规则）。  
- 删除采用**逻辑删除**（与项目其他产业台账一致）：删除后默认不在列表与常规统计中展示，数据可保留供审计（恢复能力若需实现须单独约定）。  
- 草稿列表检索写「牧场名称」为笔误，统一为**草场名称**（见 **§5.2**）。

### 2.4 字段含义（摘要）

| 字段 | 业务含义 |
| --- | --- |
| 使用面积 | 本次使用所占草场面积，单位为**亩**；不得超过所选草场的登记总面积 |
| 开始使用日期 / 结束使用日期 | 本次使用的起止自然日，格式 **YYYY-MM-DD** |
| 实际使用天数 | 由开始使用日期与结束使用日期**系统自动计算**的天数（见 **§2.5**）；界面为只读展示，用户不可手工改写以免与日期不一致 |
| 放牧数量 | 本次使用涉及的可放牧牲畜数量，单位为**头** |
| 预约日期（列表筛选项） | 界面文案；业务含义为记录的**创建日期**（登记入库日期），用于按登记时间区间筛选列表 |

---

### 2.5 实际使用天数计算规则

在满足「开始使用日期 ≤ 结束使用日期」的前提下：

- **计算方式（默认）：** 按**自然日、含起止两日**计天。  
  - 公式：`实际使用天数 = 结束使用日期 − 开始使用日期 + 1`（单位：天）。  
  - 示例：开始 `2025-06-01`、结束 `2025-06-01` → **1** 天；开始 `2025-06-01`、结束 `2025-06-03` → **3** 天。  
- 用户在新增/修改表单中变更开始使用日期或结束使用日期时，系统应**即时重算**并刷新「实际使用天数」展示；提交保存时以系统计算值为准写入台账。  
- 若县级规范要求「不含结束日」或「仅计工作日」，须在评审通过后修订本节并同步界面提示。

---

## 3. 功能范围

**本期实现：**

- 使用记录的新增、修改、逻辑删除、分页列表查询、详情查看  
- 关联草场、关联养殖主体的选择与校验  
- 使用面积、使用时段、放牧数量、放牧方式的录入与校验  
- 实际使用天数自动计算  
- 按草场名称关键字、创建日期区间的列表筛选  
- 列表操作：查看、编辑、删除  

**本期不实现：**

- 草场/养殖主体主数据的新增与维护（分别在「草场管理」「牧场管理」完成）  
- 与畜群个体、防疫、补贴等下游业务的自动联动  
- 地图轨迹、GPS 围栏、现场拍照取证  
- 审批流、预约占位冲突自动仲裁（仅登记既成事实）  

---

## 4. 业务流程概览

```mermaid
flowchart LR
    A[选择草场与主体] --> B[填写使用与放牧信息]
    B --> C[系统计算使用天数]
    C --> D[保存记录]
    D --> E[列表查询/筛选]
    E --> F[查看详情]
    E --> G[修改记录]
    E --> H[逻辑删除]
    G --> E
    H --> E
```

1. **登记**：从主数据选择草场、养殖主体 → 填写使用面积、起止日期、放牧数量与方式 → 系统计算实际使用天数 → 保存。  
2. **查询**：按草场名称关键字、创建日期区间筛选，分页浏览。  
3. **维护**：修改时重新选择或调整各字段；日期变更后重新计算使用天数；须重新满足 **§5.1** 校验。  
4. **查阅**：查看单条记录全部业务字段及登记人、登记时间等审计信息（若系统提供）。  
5. **删除**：逻辑删除；删除前宜二次确认。

---

## 5. 详细功能需求

### 5.1 新增草场使用记录

| 字段 | 规则 |
| --- | --- |
| 草场名称 | **必填**；自「草场管理」有效台账中**单选**；下拉支持名称模糊搜索；选定后宜展示或引用该草场登记总面积供填写「使用面积」时参考 |
| 使用面积 | **必填**；**正数**；单位为**亩**；须 **> 0** 且 **≤ 所选草场登记总面积**（总面积以草场主数据为准；若主数据面积后续被调小，已存在记录是否回溯校验须单独约定） |
| 养殖主体名称 | **必填**；自「牧场管理」有效台账中**单选**；下拉支持名称模糊搜索 |
| 开始使用日期 | **必填**；**YYYY-MM-DD** |
| 结束使用日期 | **必填**；**YYYY-MM-DD**；**不得早于**开始使用日期 |
| 实际使用天数 | **系统自动计算**（**§2.5**）；保存时写入；界面只读，不要求用户填写 |
| 放牧数量 | **必填**；**正整数**（≥ 1）；单位为**头** |
| 放牧方式 | **必填**；**单选**，取值见 **§2.2**（轮牧 / 自由放牧 / 季节性放牧） |

**必填字段汇总：** 草场、养殖主体、使用面积、开始使用日期、结束使用日期、放牧数量、放牧方式；实际使用天数由系统生成。

**联动与校验：**

- 未选择草场时不允许提交；未选择养殖主体时不允许提交。  
- 变更开始使用日期或结束使用日期时，实时重算实际使用天数。  
- 使用面积超过所选草场总面积时，须明确提示（如「使用面积不能大于草场总面积 xx 亩」）并阻止提交。  
- 所选草场或主体若在保存瞬间已被主数据逻辑删除，须提示「主数据不存在或已失效」并阻止提交。  
- 各字段校验失败时须给出**可区分**的错误提示。

---

### 5.2 查询草场使用记录列表

- **关键字：** 对关联的「**草场名称**」进行**模糊**匹配；关键字为空时不按名称过滤。  
  - 说明：草稿写「牧场名称」为笔误；本模块不以养殖主体名称作为该关键字（主体名称筛选若需支持，评审后单独增加）。  
- **预约日期（创建日期）：** 按记录**创建日期**闭区间筛选；提供开始日、结束日（与界面「预约日期」起止一致）；仅填一端时，按项目日期筛选惯例处理（如「≥ 开始日」「≤ 结束日」）；开始日晚于结束日时，查询前须提示错误或自动纠正。  
- **逻辑删除：** 默认**不展示**已逻辑删除记录。  
- **分页：** 默认 **每页 20 条**；单页条数上限与项目列表通用规范一致。  
- **排序：** 默认按 **创建时间倒序**（最新登记在前）；相同时间下次要排序键与项目列表规范一致（若有）。  
- **重置：** 支持一键清空查询条件并恢复默认列表。

**列表宜展示：** 草场名称、使用面积（亩）、养殖主体名称、开始使用日期、结束使用日期、实际使用天数（天）、放牧数量（头）、放牧方式、操作列（查看 / 编辑 / 删除）。

---

### 5.3 修改草场使用记录

- **可修改项：** 草场、养殖主体、使用面积、开始使用日期、结束使用日期、放牧数量、放牧方式（**全部业务字段**均可修改）。  
- **不可由用户直接改：** 实际使用天数（随日期自动重算）。  
- **保存约束：** 须重新满足 **§5.1**；更换草场后须重新校验使用面积不超过新草场总面积。  
- **主数据变更：** 若修改时更换草场或养殖主体，须重新从下拉选择有效主数据项。

---

### 5.4 删除草场使用记录（逻辑删除）

- **允许删除：** 具备删除权限的用户可对单条或多条记录执行删除（是否支持批量删除与项目列表惯例一致）。  
- **删除方式：** **逻辑删除**；删除后记录在默认列表与常规统计中不可见。  
- **确认：** 删除前宜弹出确认提示，避免误删。  
- **恢复：** 是否提供「恢复已删除」管理功能，本期不强制。

---

### 5.5 查看草场使用记录详情

- **展示内容：** 草场名称、使用面积、养殖主体名称、开始使用日期、结束使用日期、实际使用天数、放牧数量、放牧方式；宜展示创建人、创建时间、最后修改人、最后修改时间。  
- **展示格式：** 日期 **YYYY-MM-DD**；数值带单位（亩、天、头）。  
- **交互：** 具备编辑权限的用户可从详情进入编辑（见 **§5.3**）；只读账号仅可查看。

---

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

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

| 操作 | 说明 |
| --- | --- |
| 查看 | 具备查询权限即可 |
| 新增 | 具备新增权限即可 |
| 修改 | 具备修改权限即可 |
| 删除 | 具备删除权限即可；逻辑删除前确认 |

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

---

## 7. 错误与提示约定

- 业务与校验错误宜采用项目统一的提示方式呈现，便于用户理解与前端统一处理；**不约定**具体 HTTP 状态码或接口字段名。  
- 常见提示宜可区分，例如：  
  - 草场或养殖主体未选择、主数据已失效；  
  - 使用面积为空、非正数或超过草场总面积；  
  - 开始使用日期晚于结束使用日期；  
  - 放牧数量非正整数；  
  - 放牧方式未选择；  
  - 创建日期区间非法；  
  - 删除确认取消与删除失败原因。  

---

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

| 类别 | 建议 |
| --- | --- |
| 权限 | 菜单与按钮：查询、新增、修改、删除；是否限制跨乡镇数据 |
| 审计 | 新增、修改、逻辑删除记操作日志 |
| 性能 | 下拉远程搜索草场/主体名称响应及时；列表按名称与日期筛选满足通用体验 |
| 数据质量 | 主数据删除后，历史使用记录仍可查详情但不宜再被复制为新记录模板 |
| 双语 | 字段标签与提示符合项目 i18n 规范（汉语 + 藏文） |
| 扩展 | 时段重叠校验、按养殖主体/放牧方式统计、导出、与承载量预警联动 |

---

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

| 草稿问题 | 优化处理 |
| --- | --- |
| 条目编号跳跃（1～5 后直接 10～12） | 重整为 **§5** 分节与连续叙述 |
| 混入技术栈、接口响应格式 | 技术栈移除；提示约定保留于 **§7** |
| 列表关键字写「牧场名称」 | 统一为**草场名称**（**§5.2**） |
| 「预约日期」含义不清 | 明确为记录**创建日期**筛选（**§2.4、§5.2**） |
| 实际使用天数由用户填 | 改为**系统按 §2.5 自动计算**、界面只读 |
| 使用面积无上限 | 增加 **≤ 所选草场登记总面积**（**§5.1**） |
| 删除方式未说明 | 明确**逻辑删除**（**§2.3、§5.4**） |
| 草场/主体来源未写 | 新增 **§2.1** 主数据关联与下拉规则 |
| 列表缺排序、重置、展示列 | **§5.2** 补充 |

---

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

| 能力 | 对应章节 |
| --- | --- |
| 新增与主数据选择、字段校验 | §5.1、§2.1、§2.5 |
| 使用天数自动计算 | §2.5、§5.1、§5.3 |
| 列表查询与筛选 | §5.2 |
| 修改 | §5.3 |
| 逻辑删除 | §5.4 |
| 详情查看 | §5.5 |
| 权限与错误提示 | §6、§7 |