huimv-baqing/doc/产业数据模型及服务/草畜失衡预警/草畜失衡预警技术方案.md

草畜失衡预警 — 技术方案

依据：同目录 草畜失衡预警功能需求.md。本期 列表 + 详情只读；写入由家庭牧场 / 农牧户 / 养殖大户填报后端自动触发。不依赖「草畜平衡计算」模块。

---

1. 技术架构

项	说明
后端	RuoYi v3.9.2（springboot2）：JDK 8、Spring Boot 2.x、MyBatis
数据库	MySQL 5.7.39，InnoDB，utf8mb4
前端	若依 Vue2：列表筛选 + 详情只读
关联模块	家庭牧场 / 农牧户 / 养殖大户数据填报（新增、修改、导入、删除时同步）

分层：填报 ServiceImpl 判定失衡 → GrassLivestockImbalanceWarningSyncSupport upsert/删除 → 独立表；查询侧 Controller → IBizGrassLivestockImbalanceWarningService → Mapper。

代码位置：baqing-admin → com.ruoyi.web.modules.industryservice

场景	行为
失衡判定	核定年末草畜平衡载畜量 < 年底牲畜存栏（绵羊单位）；任一为空 → 不失衡
写入	失衡则按 source_key upsert；已平衡则按 source_key 物理删除
删除源填报	批量按 source_key 清除对应预警
列表/详情	只读；排序 alert_time DESC, id DESC
日期筛选	startDate/endDate（yyyy-MM-dd）转当日 00:00:00～23:59:59
与疾病预警	不再写入 biz_yak_disease_warning（原 warning_type=6 已废弃）

---

2. 数据库设计

2.1 表 biz_grass_livestock_imbalance_warning

DDL：sql/biz_grass_livestock_imbalance_warning.sql

字段	类型	非空	说明
id	bigint(20)	Y	主键
source_key	varchar(64)	Y	业务键：FR-{id} / FH-{id} / LLF-{id}
data_source	varchar(32)	Y	family_ranch / farmer_household / large_livestock_farmer
source_record_id	bigint(20)	Y	源填报记录 ID
stat_year / stat_month	int	N	所属年月
town_dept_id / town_name	—	N	乡镇
village_dept_id / village_name	—	N	村
subject_name	varchar(200)	N	主体名称（企业名或村名等）
approved_carrying_capacity	decimal(18,4)	N	核定年末草畜平衡载畜量
year_end_stock_sheep_unit	decimal(18,4)	N	年底牲畜存栏（绵羊单位）
alert_time	datetime	Y	预警时间（每次 upsert 刷新）
alert_message	varchar(1024)	Y	预警文案
create_time / update_time	datetime	—	审计

索引

索引	字段	用途
PRIMARY	id	主键
uk_source_key	source_key	每条源填报最多一条预警
idx_data_source_record	data_source, source_record_id	按来源追溯
idx_alert_time	alert_time	列表排序、日期筛选
idx_stat_year_month	stat_year, stat_month	年月查询
idx_town_dept_id / idx_village_dept_id	对应字段	区划筛选（预留）

---

3. 后端结构

类	职责
BizGrassLivestockImbalanceWarningController	列表、详情 REST
BizGrassLivestockImbalanceWarningServiceImpl	查询、日期范围校验
BizGrassLivestockImbalanceWarningMapper	CRUD / 按 source_key 删
GrassLivestockImbalanceWarningSyncSupport	失衡 upsert、平衡删除、文案组装
GrassLivestockImbalanceWarningRules	data_source / source_key 前缀常量
*DerivedSupport.isImbalanced	家庭牧场 / 农牧户 / 养殖大户各自判定

触发点（三处填报 ServiceImpl 保存成功后 / 删除时）：

来源	data_source	source_key
家庭牧场	family_ranch	FR-{id}
农牧户	farmer_household	FH-{id}
养殖大户	large_livestock_farmer	LLF-{id}

预警文案示例：

草畜失衡预警：2026年3月 XX镇XX村 主体名：核定年末草畜平衡载畜量(100)小于年底牲畜存栏绵羊单位(120)

---

4. 接口一览

Base Path：/dataModel/grassLivestockImbalanceWarning

方法	路径	权限	说明
GET	/list	dataModel:grassLivestockImbalanceWarning:list	分页；筛选项见下
GET	/{id}	dataModel:grassLivestockImbalanceWarning:query	详情

列表查询参数

参数	说明
startDate / endDate	预警日期范围（yyyy-MM-dd）
dataSource	数据来源枚举
subjectName	主体名称模糊
pageNum / pageSize	分页

无手工新增 / 修改 / 删除接口。

---

5. 前端

详见同目录 草畜失衡预警前端技术方案.md。

项	路径
页面	ruoyi-ui/src/views/dataModel/grassLivestockImbalanceWarning/index.vue
API	ruoyi-ui/src/api/dataModel/grassLivestockImbalanceWarning.js
菜单组件	dataModel/grassLivestockImbalanceWarning/index

筛选：预警日期、数据来源、主体名称；列含预警时间、来源、年月、乡镇村、主体、载畜量、存栏、预警信息；操作仅「查看」。

---

6. 部署注意

1. 执行 sql/biz_grass_livestock_imbalance_warning.sql（含清理旧 warning_type=6 的语句时一并执行）。
2. 配置菜单与权限 list / query。
3. 历史失衡数据需对源填报 重保存或再导入 后才会写入新表。

---

7. 修订记录

版本	说明
1.0	从疾病预警拆出独立表；三处填报同步写入