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（本方案不展开页面实现）
依赖主数据	biz_grassland（草场管理）、biz_pasture（牧场管理 / 养殖主体）

分层：Controller → Service（GrasslandUsageValidation、天数计算、主数据校验）→ Mapper/XML（列表 JOIN 主数据取名称）→ domain。

代码位置（建议）：baqing-admin → com.ruoyi.web.modules.industryservice（BizGrasslandUsageRecord、Mapper、Service、Controller）。

业务摘要

场景	行为
新增/修改	校验草场、主体 del_flag='0'；usage_area_mu ≤ grassland.area_mu；重算 actual_use_days；del_flag='0'
列表/详情	仅 del_flag='0'；JOIN 展示 grasslandName、pastureName；排序 create_time DESC, id DESC
删除	逻辑删除：del_flag 置 '2'
使用天数	服务端：actual_use_days = DATEDIFF(end, start) + 1（含起止日）；忽略客户端传入天数

---

2. 数据库设计

2.1 表 biz_grassland_usage_record（草场使用记录）

字段	类型	非空	默认值	说明
id	bigint(20)	Y	自增	主键
grassland_id	bigint(20)	Y	—	关联 biz_grassland.id
pasture_id	bigint(20)	Y	—	关联 biz_pasture.id（养殖主体）
usage_area_mu	decimal(12,2)	Y	—	使用面积（亩），> 0
use_start_date	date	Y	—	开始使用日期
use_end_date	date	Y	—	结束使用日期；≥ 开始日
actual_use_days	int(11)	Y	—	实际使用天数（服务端计算入库）
grazing_head_count	int(11)	Y	—	放牧数量（头），≥ 1
grazing_method	tinyint(4)	Y	—	放牧方式 §2.2
del_flag	char(1)	Y	'0'	0 存在 2 删除
create_by / create_time / update_by / update_time	若依惯例	—	—	审计；列表「预约日期」筛 create_time
remark	varchar(500)	N	NULL	备注（可选扩展）

索引：PRIMARY KEY (id)；KEY idx_grassland_id (grassland_id)；KEY idx_pasture_id (pasture_id)；KEY idx_create_time (create_time)；KEY idx_del_flag (del_flag)；KEY idx_use_start (use_start_date)。

关联约定：逻辑外键，不在库层强制 FOREIGN KEY（与项目其他业务表一致）；保存前 Service 校验主数据存在且 del_flag='0'。

DDL（MySQL 5.7）

CREATE TABLE `biz_grassland_usage_record` (
  `id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT '主键',
  `grassland_id` bigint(20) NOT NULL COMMENT '草场ID biz_grassland',
  `pasture_id` bigint(20) NOT NULL COMMENT '养殖主体ID biz_pasture',
  `usage_area_mu` decimal(12,2) NOT NULL COMMENT '使用面积(亩)',
  `use_start_date` date NOT NULL COMMENT '开始使用日期',
  `use_end_date` date NOT NULL COMMENT '结束使用日期',
  `actual_use_days` int(11) NOT NULL COMMENT '实际使用天数',
  `grazing_head_count` int(11) NOT NULL COMMENT '放牧数量(头)',
  `grazing_method` tinyint(4) NOT NULL COMMENT '放牧方式1轮牧2自由3季节',
  `del_flag` char(1) NOT NULL DEFAULT '0' COMMENT '0存在 2删除',
  `create_by` varchar(64) DEFAULT '' COMMENT '创建者',
  `create_time` datetime DEFAULT NULL COMMENT '创建时间',
  `update_by` varchar(64) DEFAULT '' COMMENT '更新者',
  `update_time` datetime DEFAULT NULL COMMENT '更新时间',
  `remark` varchar(500) DEFAULT NULL COMMENT '备注',
  PRIMARY KEY (`id`),
  KEY `idx_grassland_id` (`grassland_id`),
  KEY `idx_pasture_id` (`pasture_id`),
  KEY `idx_create_time` (`create_time`),
  KEY `idx_del_flag` (`del_flag`),
  KEY `idx_use_start` (`use_start_date`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='草场使用记录';

2.2 枚举常量

字段	值	含义
grazing_method	1	轮牧
	2	自由放牧
	3	季节性放牧
del_flag	0	正常
	2	已逻辑删除

2.3 列表查询 JOIN（示意）

列表、详情需展示名称时关联主表（仅有效主数据用于新增校验；历史记录列表仍展示当时关联 id 对应名称，主数据已删时名称可为空或仍显示冗余策略由实现约定）：

-- 列表片段
FROM biz_grassland_usage_record r
LEFT JOIN biz_grassland g ON r.grassland_id = g.id
LEFT JOIN biz_pasture p ON r.pasture_id = p.id
WHERE r.del_flag = '0'

---

3. 接口设计

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

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

Base Path：/dataModel/grasslandUsage

#	说明	Method	URI	权限	要点
3.1	分页列表	GET	/dataModel/grasslandUsage/list	dataModel:grasslandUsage:list	Query 3.1.1；JOIN 名称；create_time DESC, id DESC
3.2	详情	GET	/dataModel/grasslandUsage/{id}	dataModel:grasslandUsage:query	含 grasslandId、pastureId 及名称展示字段
3.3	新增	POST	/dataModel/grasslandUsage	dataModel:grasslandUsage:add	Body 3.3.1；服务端算天数
3.4	修改	PUT	/dataModel/grasslandUsage	dataModel:grasslandUsage:edit	Body 含 id；忽略客户端 actualUseDays
3.5	删除	DELETE	/dataModel/grasslandUsage/{ids}	dataModel:grasslandUsage:remove	逻辑删除；ids 逗号分隔批量

主数据下拉（复用，不重复建设）

用途	建议接口	说明
草场选择	GET /dataModel/grassland/list	keyword 模糊名称；仅 del_flag=0；前端取 id、grasslandName、areaMu
养殖主体选择	GET /dataModel/pasture/list	keyword 模糊 pastureName；仅有效主体

若需轻量选项列表，可增加 GET .../optionList（返回 id+name），本期非必须。

3.1.1 列表 Query

参数	类型	必填	说明
pageNum / pageSize	int	N	默认 1 / 20
keyword	string	N	关联草场名称模糊（g.grassland_name）；空不过滤
startDate	string	N	创建日期起 yyyy-MM-dd（界面「预约日期」起）
endDate	string	N	创建日期止 yyyy-MM-dd；date(create_time) 闭区间

日期区间 Service 校验：若 startDate、endDate 均非空且 startDate > endDate，抛业务异常。

3.3.1 新增 / 修改 Body（驼峰）

字段	必填	说明
id	修改 Y	主键
grasslandId	Y	草场主键
pastureId	Y	养殖主体主键
usageAreaMu	Y	正数（亩）；≤ 该草场 area_mu
useStartDate	Y	yyyy-MM-dd
useEndDate	Y	yyyy-MM-dd；≥ useStartDate
actualUseDays	N	服务端覆盖；客户端传值忽略
grazingHeadCount	Y	正整数（头）
grazingMethod	Y	1～3
remark	N	备注

列表/详情响应扩展字段（非表字段）：grasslandName、pastureName（JOIN 或二次查询填充）。

3.4 使用天数计算（服务端）

actual_use_days = (use_end_date - use_start_date) 的自然日差 + 1

• Java 实现：GrasslandUsageValidation.resolveActualUseDays(start, end)。
  
• 保存前统一调用，写入 actual_use_days。

3.5 Mapper 约定

• 业务表 CRUD 均带 r.del_flag = '0'（列表、详情、更新）。
  
• 逻辑删除：update ... set del_flag='2', update_by=?, update_time=now() where del_flag='0' and id in (...)。
  
• 列表按 §3.1.1 过滤；keyword 作用在 biz_grassland.grassland_name。

3.6 服务端校验（摘要）

项	规则
草场 / 主体	grasslandId、pastureId 非空；对应记录存在且 del_flag='0'
使用面积	> 0；≤ 所选草场 area_mu
使用日期	非空；useStartDate ≤ useEndDate
实际使用天数	由 §3.4 计算后入库
放牧数量	≥ 1 整数
放牧方式	∈ {1, 2, 3}
列表创建日期区间	startDate ≤ endDate（均填时）

校验类建议：GrasslandUsageRules、GrasslandUsageValidation（validateRowForSave、validateDateRangeForList）。

---

4. 菜单与权限（示例）

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

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

---

5. 交付清单

• sql/biz_grassland_usage_record.sql、菜单与按钮权限 SQL
  
• BizGrasslandUsageRecord Domain / Mapper（含 JOIN 列表）/ Service / Controller
  
• GrasslandUsageRules、GrasslandUsageValidation（主数据、面积上限、天数计算）
  
• 逻辑删除
  
• 单元测试 / 接口测试（MockMvc）
  

---

6. 修订记录

版本	说明
1.0	初稿：对齐功能需求；biz_grassland_usage_record；关联 biz_grassland/biz_pasture；天数服务端计算；逻辑删除