# 草畜失衡预警 — 技术方案

> 依据：同目录 `草畜失衡预警功能需求.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}` |

**预警文案示例**：

```text
草畜失衡预警：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](./草畜失衡预警前端技术方案.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 | 从疾病预警拆出独立表；三处填报同步写入 |