huimv-baqing/doc/产业数据模型及服务/草场管理/草场管理技术方案.md

草场管理 — 技术方案

依据：同目录 草场管理功能需求.md。草场台账 CRUD + 逻辑删除；不含地图标点、附件上传。

---

1. 技术架构

项	说明
后端	RuoYi v3.9.2（springboot2 分支）：JDK 8、Spring Boot 2.x、Spring MVC、MyBatis、Druid
数据库	MySQL 5.7.39，InnoDB，utf8mb4
前端	若依 Vue2（本方案不展开页面实现）

分层：Controller（@PreAuthorize、AjaxResult / TableDataInfo）→ Service（GrasslandValidation 业务校验）→ Mapper/XML → domain。

代码位置（建议）：baqing-admin → com.ruoyi.web.modules.industryservice（与「牧场管理」同模块：BizGrassland、Mapper、Service、Controller）。

业务摘要

场景	行为
新增	校验 §3.5；del_flag='0'
修改	全字段可改；重新校验；update 带 del_flag='0' 条件
列表/详情	仅 del_flag='0'；排序 create_time DESC, id DESC
删除	逻辑删除：del_flag 置 '2'（若依惯例）

---

2. 数据库设计

2.1 表 biz_grassland（草场）

字段	类型	非空	默认值	说明
id	bigint(20)	Y	自增	主键
grassland_name	varchar(32)	Y	—	草场名称（需求 1～10 字）
area_mu	decimal(12,2)	Y	—	面积（亩），> 0
grazing_ban_area	decimal(12,2)	N	NULL	禁牧面积（亩），有值须 > 0
grass_balance_area	decimal(12,2)	N	NULL	草畜平衡面积（亩），有值须 > 0
degradation_level	tinyint(4)	N	NULL	退化等级 §2.2
utilization_type	tinyint(4)	N	NULL	利用类型 §2.2
grass_yield_per_mu	decimal(12,2)	N	NULL	亩产草量（kg/亩），有值须 > 0
utilization_rate	decimal(5,4)	N	NULL	利用率 0～1（闭区间）
grazing_ban_start_date	date	N	NULL	禁牧开始日期（与结束成对）
grazing_ban_end_date	date	N	NULL	禁牧结束日期；有值时 ≥ 开始日
rotation_plot_count	int(11)	N	NULL	轮牧小区数量（块），有值须 ≥ 1
rotation_grazing_days	int(11)	N	NULL	小区放牧天数（天），有值须 ≥ 1
rotation_cycle_days	int(11)	N	NULL	轮牧周期（天），有值须 ≥ 1
del_flag	char(1)	Y	'0'	0 存在 2 删除
create_by / create_time / update_by / update_time	若依惯例	—	—	审计
remark	varchar(200)	N	NULL	备注（≤100 字）

索引：PRIMARY KEY (id)；KEY idx_grassland_name (grassland_name)；KEY idx_utilization_type (utilization_type)；KEY idx_degradation_level (degradation_level)；KEY idx_create_time (create_time)；KEY idx_del_flag (del_flag)。

DDL（MySQL 5.7）：见 sql/biz_grassland.sql；已有库升级见 sql/biz_grassland_fields_alter.sql。

2.2 枚举常量

字段	值	含义
degradation_level	1	未退化
	2	轻度
	3	中度
	4	重度
	5	极重度
utilization_type	1	禁牧
	2	轮牧
	3	全年放牧
del_flag	0	正常
	2	已逻辑删除

---

3. 接口设计

统一响应：AjaxResult（code / msg / data）或分页 TableDataInfo（rows、total）。

权限标识：dataModel:grassland:list|query|add|edit|remove|export

Base Path：/dataModel/grassland

#	说明	Method	URI	权限	要点
3.1	分页列表	GET	/dataModel/grassland/list	dataModel:grassland:list	Query 3.1.1；del_flag='0'；create_time DESC, id DESC
3.2	详情	GET	/dataModel/grassland/{id}	dataModel:grassland:query	全字段；del_flag='0'，否则无数据
3.3	新增	POST	/dataModel/grassland	dataModel:grassland:add	Body 3.3.1；del_flag='0'
3.4	修改	PUT	/dataModel/grassland	dataModel:grassland:edit	Body 含 id；全量校验
3.5	删除	DELETE	/dataModel/grassland/{ids}	dataModel:grassland:remove	逻辑删除；ids 逗号分隔批量

3.1.1 列表 Query

参数	类型	必填	说明
pageNum / pageSize	int	N	默认 1 / 20
keyword	string	N	草场名称模糊；空不过滤
utilizationType	int	N	1～3 精确；空不过滤
degradationLevel	int	N	1～5 精确（可选扩展筛选项）；空不过滤

3.3.1 新增 / 修改 Body（驼峰）

字段	必填	说明
id	修改 Y	主键
grasslandName	Y	1～10 字符
areaMu	Y	正数（亩）
grazingBanArea	N	正数（亩）；空不校验
grassBalanceArea	N	正数（亩）；空不校验
degradationLevel	N	1～5；空不校验
utilizationType	N	1～3；空不校验
grassYieldPerMu	N	正数（kg/亩）；空不校验
utilizationRate	N	0～1（含端点）；空不校验
grazingBanStartDate	N	yyyy-MM-dd；与结束成对
grazingBanEndDate	N	yyyy-MM-dd；有值时 ≥ grazingBanStartDate
rotationPlotCount	N	正整数（块）；空不校验
rotationGrazingDays	N	正整数（天）；空不校验
rotationCycleDays	N	正整数（天）；空不校验
remark	N	≤100 字

列表行字段（示例）：id、grasslandName、areaMu、grazingBanArea、grassBalanceArea、degradationLevel、utilizationType、grassYieldPerMu、utilizationRate、grazingBanStartDate、grazingBanEndDate、rotationPlotCount、rotationGrazingDays、rotationCycleDays、createTime。

日期序列化：JSON 使用 yyyy-MM-dd；与若依 JsonFormat / 全局 Jackson 配置一致。

3.4 Mapper 约定

• 列表、详情、更新：and del_flag = '0'。
  
• 逻辑删除：update biz_grassland set del_flag='2', update_by=?, update_time=now() where del_flag='0' and id in (...)。
  
• 删除前查询可用 selectByIdAny（不过滤 del_flag），用于审计或幂等。

3.5 服务端校验（摘要）

项	规则
草场名称	必填；1～10 字符
面积	必填；> 0
禁牧面积 / 草畜平衡面积	选填；有值须 > 0
退化等级	选填；有值 ∈ {1, 2, 3, 4, 5}
利用类型	选填；有值 ∈ {1, 2, 3}
亩产草量	选填；有值须 > 0
利用率	选填；有值 0 ≤ x ≤ 1
禁牧日期	选填；同时有值或同时为空；有值时 start ≤ end
轮牧三项	选填；有值均为 ≥ 1 的整数
备注	可空；有值 ≤100 字

校验类建议：GrasslandRules（枚举常量）、GrasslandValidation（validateRowForSave）。

---

4. 菜单与权限（示例）

类型	名称	权限标识
菜单	草场管理	dataModel:grassland:list
按钮	查询	dataModel:grassland:query
按钮	新增	dataModel:grassland:add
按钮	修改	dataModel:grassland:edit
按钮	删除	dataModel:grassland:remove
按钮	导出	dataModel:grassland:export

组件路径建议：dataModel/grassland/index（菜单挂载在「产业数据模型及体系」下）。

---

5. 交付清单

• sql/biz_grassland.sql、菜单与按钮权限 SQL
  
• BizGrassland Domain / Mapper / XML / Service / Controller
  
• GrasslandRules、GrasslandValidation
  
• 逻辑删除
  
• 单元测试 / 接口测试（MockMvc）
  

---

6. 修订记录

版本	说明
1.0	初稿：对齐功能需求；biz_grassland；逻辑删除 del_flag；无地图与附件接口
1.1	新增禁牧面积、草畜平衡面积；除名称与面积外字段改为可空/选填