huimv-baqing/doc/产业数据模型及服务/草场使用记录/草场使用记录功能需求.md

草场使用记录 — 功能需求

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. 业务流程概览

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