# 养殖产业数据 — 前端技术方案

> 依据：`养殖产业数据功能需求.md`、`养殖产业数据技术方案.md`；布局对齐原型 `Snipaste_2026-05-19_12-33-09.jpg`。字段 **小驼峰**，与接口一致。

---

## 1. 页面与路由

| 项 | 说明 |
| --- | --- |
| **Vue 路径** | `ruoyi-ui/src/views/livestockIndustry/breedingIndustry/index.vue` |
| **组件名** | `BreedingIndustry` |
| **菜单配置** | 组件路径：`livestockIndustry/breedingIndustry/index` |
| **权限前缀** | `dataModel:breedingIndustry:query`（查看与刷新共用） |

本期**无**表单增删改、无子路由。

---

## 2. API 模块

| 项 | 说明 |
| --- | --- |
| **文件** | `ruoyi-ui/src/api/livestockIndustry/breedingIndustry.js` |
| **Base** | `/dataModel/breedingIndustry` |

| 方法 | HTTP | 说明 |
| --- | --- | --- |
| `getBreedingDashboard` | GET | `/dashboard`，Query 可选 `forceRefresh=true` |

---

## 3. 页面结构（单页四块）

纵向滚动，块标题与需求 **§5.1** 一致。

| 区块 | 组件建议 | 数据节点 |
| --- | --- | --- |
| 工具栏 | 右上角「刷新」`el-button`，`v-hasPermi` query | — |
| 产业总览 | 6 个指标卡片 | `data.overview` |
| 牦牛存栏变动 | 公/母数字 + ECharts 折线 | `data.inventoryChange` |
| 牦牛年龄结构 | ECharts 环形图 | `data.ageStructure` |
| 草场类型占比 | 可用/使用中数字 + 退化占比图 + 表格 | `data.grassland` |

页眉展示 **统计日** `statDate`、**统计年** `statYear`。

---

## 4. 图表与展示规则

| 规则 | 实现 |
| --- | --- |
| 首次进入 | `mounted` 调用 `getBreedingDashboard()`；全页 `v-loading` |
| 刷新 | `forceRefresh=true`；`refreshing` 防重复点击 |
| 失败 | `msg` 提示；**清空**本地 `dashboardData`，不保留上一用户数据 |
| 空数据 | 数字 `0` 或 `—`；图表 `emptyChart` 文案 |
| 未标注性别 | `unknownGenderCount > 0` 时展示「未标注性别：N 头」 |
| 月趋势 | `monthlyTrend` 仅 1～当前月；X 轴 1～12，无数据月份不画点 |
| 年龄/退化占比 | 接口 `ratio` 已为 0～100；展示加 `%`，保留 1 位小数 |
| 单位 | 头、个、亩，与卡片文案一致 |

**折线图**：`inventoryCount` 系列；当前月点应与总览「存栏总量」联调校验。

**退化五档**：`degradationStats` 固定 5 项；图例用 `degradationLabel`。

---

## 5. 国际化

| 项 | 说明 |
| --- | --- |
| **语言包** | `livestockIndustry.breedingIndustry`（`lang/zh/livestockIndustry.js`、`lang/bo/livestockIndustry.js`） |
| **Mixin** | `mixins/livestockIndustryLocaleMixin.js`：`biT` / `biCommon` / `biDash` |
| **注册** | `lang/zh-CN.js`、`lang/bo.js` 引入 `livestockIndustry` |

---

## 6. 权限与菜单

- 菜单进入需 `dataModel:breedingIndustry:query`。
- 无数据时仍可见页面；刷新按钮同权限。
- **无**导出、同步、编辑按钮。

---

## 7. 交付清单

- [x] `api/livestockIndustry/breedingIndustry.js`
- [x] `views/livestockIndustry/breedingIndustry/index.vue`
- [x] `lang/zh/livestockIndustry.js`、`lang/bo/livestockIndustry.js`
- [x] `mixins/livestockIndustryLocaleMixin.js`
- [ ] 菜单 SQL / 后台菜单配置（见后端技术方案 **§5**）
- [ ] Playwright：进入页、刷新、四块有数据/空态（见测试用例 UI 章节）

---

## 8. 联调说明

**请求示例**：

```http
GET /dataModel/breedingIndustry/dashboard?forceRefresh=true
Authorization: Bearer {token}
```

**响应结构**（`data` 节点）：

```json
{
  "statDate": "2026-05-23",
  "statYear": 2026,
  "overview": {
    "inventoryTotal": 0,
    "annualOutbound": 0,
    "warningYakCount": 0,
    "pastureCount": 0,
    "grasslandCount": 0,
    "grasslandAreaMu": 0
  },
  "inventoryChange": {
    "bullCount": 0,
    "cowCount": 0,
    "unknownGenderCount": 0,
    "monthlyTrend": [{ "month": 1, "inventoryCount": 0 }]
  },
  "ageStructure": [{ "bandCode": "M1_6", "bandLabel": "1-6月龄", "count": 0, "ratio": 0 }],
  "grassland": {
    "availableCount": 0,
    "inUseCount": 0,
    "degradationStats": [{ "degradationLevel": 1, "degradationLabel": "未退化", "count": 0, "ratio": 0 }]
  }
}
```
