# 大屏 — 首页统计 — 技术方案 > 依据:同目录 `大屏首页功能需求.md`;数据来自养殖产业、流通交易、服务预约、补贴发放、养殖标准五类子表、科技资源与实战培训等**既有表**。本模块为**大屏只读看板**,无业务台账 CRUD。 --- ## 1. 技术架构 | 项 | 说明 | | --- | --- | | **后端** | RuoYi **v3.9.2**(**springboot2** 分支):JDK 8、Spring Boot 2.x、Spring MVC、MyBatis、Druid | | **数据库** | MySQL **5.7.39**,InnoDB,`utf8mb4` | | **前端** | 大屏独立首页(`ruoyi-screen`);**切换 `statYear`** 拉看板主数据,养殖标准**分页**单独请求;存栏变动/出栏统计图表见 **§4.1** | | **代码包** | `com.ruoyi.web.modules.screen`(`HomeScreenController` / `IHomeScreenService` / `vo` / `support`) | **分层**:`Controller` → `IHomeScreenService`(口径编排、按 **Y** 计算统计日)→ 扩展 Mapper / 复用 `BreedingIndustryStatsMapper` + `BreedingIndustryCalculator`(只读)。 | 场景 | 行为 | | --- | --- | | 进入 / 切换 `statYear` | 调用 **§3.1** + **§3.2**(`pageNum=1`) | | 标准列表翻页 / 切 Tab | 仅 **§3.2** | | 数据权限 | **全县**聚合:牦牛、牧场取全部 `biz_status=1` 且 `del_flag=0` 的牧场 ID(与疫病风险大屏一致,**不按**登录用户牧场过滤);草场全县 `del_flag=0` | | 统计日 | `Y = 当前年` → `statDate = 今日`;`Y` 为历史年 → `statDate = Y-12-31`(时点、月末还原、年出栏上界均据此) | | 主数据三项 | 供应商 / 承销商 / 交易市场**实时快照**,**不**随 `statYear` 变 | | 滚动 12 月图表 | 存栏变动、出栏统计、预约堆叠、培训趋势;锚点 = 当前 `YearMonth`;**不**随 `statYear` 变 | | 按月图表(Y 年内) | 已无(预约/培训已并入滚动 12 月) | | 性能 | 默认实时聚合;可选 **§2.3** 缓存表 | **依赖表(只读)** | 表 | 用途 | | --- | --- | | `biz_yak_asset` / `biz_pasture` / `biz_grassland` | 产业总览、存栏趋势、年龄结构、出栏、草场 | | `biz_supplier` / `biz_distributor` / `biz_trade_market` | 流通主数据条数(实时) | | `biz_service_appointment` | 线下服务预约 | | `biz_subsidy_grant_record` | 惠农补贴 | | `biz_breeding_standard` 等 5 张标准表 | 养殖标准分页列表 | | `biz_tech_resource` | 视频课程(`004008`) | | `biz_practical_training` | 实战培训场次与报名趋势 | | `biz_yak_herd_inventory` | 产业总览存栏、存栏变动、年龄结构、地图标注;**最近填报年月**全县合计 | | `biz_yak_outbound_report` | 产业总览出栏/农牧户、出栏统计、地图标注;**最近填报年月**全县合计 | | `sys_dept` | 地图标注 — 乡镇列表(`parent_id=100` 且 `order_num>12`) | --- ## 2. 数据库设计 ### 2.1 本模块业务表 **无新增业务台账表。** DDL 以各业务 `sql/*.sql` 为准。 ### 2.2 公共参数 记 `statYear = Y`,`statDate` 见 **§1**。 | 边界 | 表达式 | | --- | --- | | 年区间起 | `Y-01-01 00:00:00` | | 年区间止(年内累计) | `Y` 为当前年:`statDate 23:59:59`;历史年:`Y-12-31 23:59:59` | | 按月分组键 | `MONTH(日期字段)`,应用层补全 1~12 | ### 2.3 可选表 `biz_home_screen_cache`(性能优化) **非本期必建。** | 字段 | 类型 | 说明 | | --- | --- | --- | | `id` | `bigint(20)` | 主键 | | `stat_year` | `int(11)` | 统计年份 | | `payload_json` | `mediumtext` | **§3.1** 响应 JSON(不含标准分页列表) | | `expire_time` | `datetime` | 过期时间 | | `create_time` | `datetime` | 写入时间 | **索引**:`UNIQUE uk_stat_year (stat_year)`。TTL 建议 **1~5 分钟**。 ### 2.4 查询口径(按表) #### 牦牛填报(大屏首页存栏/出栏/年龄/趋势/地图) | 指标 | 要点 | | --- | --- | | 最近填报年月 | `MAX(stat_year, stat_month)` 全县;存栏与出栏表**可不同** | | 产业总览三项 | 最近年月全县 `yak_total` / `yak_outbound_count` / `farmer_household_count` | | 存栏变动 header | 最近年月全县 `bull_total`、`cow_total`、`yak_total` | | 滚动 12 月存栏趋势 | `biz_yak_herd_inventory` 按 `stat_year+stat_month` 全县 `bull_total`/`cow_total` 合计 | | 滚动 12 月出栏 | `biz_yak_outbound_report` 按 `stat_year+stat_month` 全县 `yak_outbound_count` 合计 | | 年龄结构 | 最近年月母牛两档:`cow_young_count`(0~1.5 岁)、`cow_adult_count`(1.5 岁以上) | | 地图标注 | 各乡镇在各自表最近填报年月下的 `yak_total` / `yak_outbound_count` | #### 养殖产业档案(草场等,复用 Mapper) 实现复用 `BreedingIndustryStatsMapper`;大屏传入**全县** `allowedPastureIds`(全部正常牧场 ID)。 | 指标 | 要点 | | --- | --- | | 草场 | `del_flag=0`;面积 `SUM(area_mu)`;可用/使用中/退化分组同养殖产业 | > 首页**不含**预警牦牛;不查 `biz_yak_disease_warning`。 #### 流通主数据(**实时**,与 **Y** 无关) | 表 | 指标 | 条件 | | --- | --- | --- | | `biz_supplier` | 供应商数 | `del_flag='0'` | | `biz_distributor` | 承销商数 | `del_flag='0'` | | `biz_trade_market` | 交易市场数 | `del_flag='0'` AND `operate_status=1` | #### 服务预约 `biz_service_appointment` | 项 | 条件 | | --- | --- | | 按年 | `appoint_date >= Y-01-01` AND `appoint_date <= Y-12-31` | | 状态 | `status NOT IN (2,3)`(排除已拒绝、已取消);表无 `del_flag` | | 分类 | `provider_type`:`1` 兽医 → 展示「兽医人员」;`3` 专家 →「专家人员」;`2` 机构 →「诊疗机构」 | | 统计 | 每条记录计 **1** 人次;年度卡片为三类合计;按月 `GROUP BY MONTH(appoint_date), provider_type` | #### 补贴发放 `biz_subsidy_grant_record` | 项 | 条件 | | --- | --- | | 按年 | `grant_date` 在 **Y** 年内(含起止日) | | 分组 | `subsidy_type`:`1` 农业生产、`2` 住房基建、`3` 民生保障 | | 指标 | `SUM(subsidy_amount)`;服务端换算 **万元**(÷10000,保留 2 位小数) | #### 农技课堂 | 指标 | 表 | 条件 | | --- | --- | --- | | 课程视频数 | `biz_tech_resource` | `del_flag='0'` AND `publish_status=1` AND `resource_type='004008'` AND `publish_time` 落在 **Y** 年 | | 实战培训场次 | `biz_practical_training` | `del_flag='0'` AND `publish_status=1` AND `publish_time` 落在 **Y** 年 | | 培训内容合计 | — | 视频数 + 场次数(应用层相加) | #### 实战培训报名趋势 `biz_practical_training` | 系列 | 条件 | | --- | --- | | 活动数/月 | `del_flag='0'` AND `publish_status=1` AND `YEAR(training_time)=Y` AND `MONTH(training_time)=m` → `COUNT(*)` | | 报名人数/月 | 同上月的培训行,`SUM(actual_enrolled_count)` | | 无培训 | `hasTrainingData=false`(**§3.1**),前端走空态,**不**强行全 0 曲线 | #### 养殖标准(分页,**§3.2**) **纳入**:`publish_status=1`;`DATE(create_time)` 落在 **Y** 年内(与功能需求 **§2.9** 一致)。 **Tab → 物理表与 `standard_type` 白名单** | `category`(请求枚举) | 表 | `standard_type IN` | | --- | --- | --- | | `BREEDING_MGMT` | `biz_breeding_standard` | `001001`,`001002`,`001003`,`001004` | | `FEEDING` | `biz_feeding_standard` | `001005`,`001006` | | `EQUIPMENT` | `biz_equipment_work_standard` | `001007`,`001008`,`001009`,`001010` | | `TREATMENT` | `biz_epidemic_treatment_standard` | `001013` | | `GROWTH` | `biz_growth_slaughter_standard` | `001011`,`001012` | 排序:`create_time DESC, id DESC`。 ### 2.5 索引建议(既有表) | 表 | 建议 | | --- | --- | | `biz_yak_asset` | `(pasture_id, del_flag, asset_status)`、`status_change_date` | | `biz_service_appointment` | 沿用 `idx_appoint_date`、`idx_provider` | | `biz_subsidy_grant_record` | 沿用 `idx_grant_date`、`idx_subsidy_type` | | `biz_tech_resource` | `(resource_type, publish_status, publish_time)` | | `biz_practical_training` | 沿用 `idx_training_time`、`idx_publish` | | 各 `biz_*_standard` | 沿用 `idx_create_time`、`idx_type` | ### 2.6 Mapper 扩展(建议) | Mapper | 方法 | 说明 | | --- | --- | --- | | `HomeScreenStatsMapper` | `selectLatestHerdInventoryStatPeriod`、`selectLatestOutboundReportStatPeriod`、`selectHerdInventoryBullCowByYearMonthRange`、`selectOutboundReportYakCountByYearMonthRange`、`selectTownMapMarkers` 等 | 填报表聚合 | | `BreedingIndustryStatsMapper` | (复用) | 草场统计 | | `BizSupplierMapper` / `BizDistributorMapper` / `BizTradeMarketMapper` | `countForScreen()` | 主数据条数 | | `BizServiceAppointmentMapper` | `selectStatsByYear(int y)` | 返回 appoint_date、provider_type 明细或按月聚合行 | | `BizSubsidyGrantRecordMapper` | `sumAmountByTypeForYear(int y)` | 三类金额 | | `BizTechResourceMapper` | `countPublishedVideoByYear(int y)` | `004008` | | `BizPracticalTrainingMapper` | `countPublishedByYear` / `selectPublishedByYear` | 场次与按月趋势 | | `HomeScreenStandardMapper` | `selectListForScreen(category, y, ...)` | 按 **§2.4** Tab 路由到对应表 | > 大屏首页牦牛趋势/出栏**不**调用 `BreedingIndustryCalculator` 月末还原;填报缺月由 `HomeScreenSupport.buildRolling12Month*` 补 0。 --- ## 3. 接口设计 **统一响应**:`AjaxResult`(`code` / `msg` / `data`);标准列表用 `TableDataInfo`(`rows` / `total`)。 **权限标识(示例)**:`bigScreen:home:query` **Base Path**:`/bigScreen/home` | # | 说明 | Method | URI | 权限 | | --- | --- | --- | --- | --- | | 3.1 | 看板主数据(除标准分页外全部区块) | GET | `/bigScreen/home/dashboard` | `bigScreen:home:query` | | 3.2 | 养殖标准分页列表 | GET | `/bigScreen/home/standards` | 同上 | | 3.3 | 地图标注(乡镇存栏/出栏) | GET | `/bigScreen/home/townMapMarkers` | 同上 | 前端:切换 `statYear` → **3.1** + **3.2**(`pageNum=1`);仅翻页 / 切 Tab → **3.2**;进入首页 / 地图刷新 → **3.3**(**不**随 `statYear` 参数变化,按服务器当前自然年计算)。 --- ### 3.1 看板主数据 #### Query | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `statYear` | string | Y | 四位年份;非法 → 业务异常(复用 `AchievementReportValidation.parseStatYear`) | | `forceRefresh` | boolean | N | 默认 `false`;`true` 时跳过 **§2.3** 缓存 | #### 响应 `data`(顶层) | 字段 | 类型 | 说明 | | --- | --- | --- | | `statYear` | int | 回显 | | `statDate` | string | 统计时点 `yyyy-MM-dd` | | `availableYears` | int[] | 各业务表出现过的年份并集 + 当前年,降序 | | `industryOverview` | object | 产业总览八项 **§3.1.1** | | `inventoryChange` | object | 存栏变动 **§3.1.2** | | `ageStructure` | array | 年龄结构 **§3.1.3** | | `outboundMonthly` | array | 出栏按月 **§3.1.4** | | `grassland` | object | 草场 **§3.1.5** | | `appointment` | object | 预约 **§3.1.6** | | `subsidy` | object | 补贴 **§3.1.7** | | `agriClassroom` | object | 农技课堂 **§3.1.8** | | `trainingTrend` | object | 实战培训报名 **§3.1.9** | #### 3.1.1 `industryOverview` | 字段 | 说明 | | --- | --- | | `inventoryTotal` | 牦牛存栏(头),`biz_yak_herd_inventory` **最近填报年月**全县 `yak_total` 合计 | | `annualOutbound` | 年出栏(头),`biz_yak_outbound_report` **最近填报年月**全县 `yak_outbound_count` 合计 | | `pastureCount` | 农牧户(户),`biz_yak_outbound_report` **最近填报年月**全县 `farmer_household_count` 合计 | | `grasslandCount` / `grasslandAreaMu` | 草场、面积 | | `supplierCount` / `distributorCount` / `tradeMarketCount` | 流通三项**实时**快照 | #### 3.1.2 `inventoryChange` | 字段 | 说明 | | --- | --- | | `bullCount` / `cowCount` / `unknownGenderCount` | 存栏表**最近填报年月**全县公/母/`yak_total` 合计 | | `monthlyTrend` | 固定 **12** 条;**滚动最近 12 自然月**;**不**随 `statYear` 变 | `monthlyTrend[]`: | 字段 | 说明 | | --- | --- | | `statYear` | 所属自然年 | | `month` | 所属月份 1~12 | | `bullCount` / `cowCount` | 该 `statYear-month` 全县填报合计;无数据为 **0** | #### 3.1.3 `ageStructure[]` | 字段 | 说明 | | --- | --- | | `bandCode` | `COW_YOUNG` / `COW_ADULT` | | `bandLabel` | `0~1.5岁幼畜` / `1.5岁以上成畜` | | `count` / `ratio` | 头数;占比 **0~100** 数值 | 两档固定返回;无存栏时 `count=0`,`ratio=0`。对齐存栏填报 `cow_young_count` / `cow_adult_count`。 #### 3.1.4 `outboundMonthly[]` | 字段 | 说明 | | --- | --- | | `statYear` | 所属自然年 | | `month` | 所属月份 1~12 | | `outboundCount` | 该月全县出栏头数;无数据为 **0** | 固定 **12** 条;滚动窗口规则同 **§3.1.2** `monthlyTrend`。 #### 3.1.5 `grassland` | 字段 | 说明 | | --- | --- | | `availableCount` / `inUseCount` | 可用 / 使用中(个) | | `degradationStats[]` | `degradationLevel`(1~5)、`degradationLabel`、`count`、`ratio`(% 数值) | 五档固定返回。 #### 3.1.6 `appointment` | 字段 | 说明 | | --- | --- | | `annualVetCount` / `annualExpertCount` / `annualOrgCount` | 三类年度合计 | | `monthlyStacked[]` | 固定 **12** 条;滚动最近 12 自然月;**不**随 `statYear` 变 | `monthlyStacked[]`:`statYear`、`month`、`vetCount`、`expertCount`、`orgCount`(缺月各计数为 **0**)。 #### 3.1.7 `subsidy` | 字段 | 说明 | | --- | --- | | `typeStats[]` | 固定 3 条:`subsidyType`(1~3)、`subsidyTypeName`、`amountWan`(万元) | | `hasSubsidyData` | **Y** 年是否存在任一条发放记录 | #### 3.1.8 `agriClassroom` | 字段 | 说明 | | --- | --- | | `videoCourseCount` | 视频课程数 | | `practicalTrainingCount` | 实战培训场次 | | `trainingContentTotal` | 二者之和 | | `hasAgriData` | 两项是否均为 0 | #### 3.1.9 `trainingTrend` | 字段 | 说明 | | --- | --- | | `hasTrainingData` | 滚动 12 月窗口内是否存在已发布且 `training_time` 落在窗口内的培训 | | `monthly[]` | 固定 **12** 条;`statYear`、`month`、`activityCount`、`enrolledCount` | `hasTrainingData=false` 时 `monthly` 仍为 12 条全 0(前端以 `hasTrainingData` 走空态)。 #### 响应示例(节选) ```json { "statYear": 2026, "statDate": "2026-05-20", "availableYears": [2026, 2025], "industryOverview": { "inventoryTotal": 120, "annualOutbound": 8, "pastureCount": 12, "grasslandCount": 80, "grasslandAreaMu": 12500.50, "supplierCount": 5, "distributorCount": 3, "tradeMarketCount": 2 }, "inventoryChange": { "bullCount": 45, "cowCount": 60, "unknownGenderCount": 15, "monthlyTrend": [ { "statYear": 2025, "month": 8, "bullCount": 40, "cowCount": 55 }, { "statYear": 2026, "month": 7, "bullCount": 45, "cowCount": 60 } ] }, "outboundMonthly": [ { "statYear": 2025, "month": 8, "outboundCount": 0 }, { "statYear": 2026, "month": 5, "outboundCount": 88 } ], "appointment": { "annualVetCount": 10, "annualExpertCount": 5, "annualOrgCount": 8, "monthlyStacked": [{ "month": 1, "vetCount": 2, "expertCount": 1, "orgCount": 0 }] }, "trainingTrend": { "hasTrainingData": true, "monthly": [{ "month": 3, "activityCount": 1, "enrolledCount": 20 }] } } ``` #### 服务端逻辑(摘要) ``` 1. year = parseStatYear(statYear); statDate = resolveStatDate(year) 2. anchor = YearMonth.now(Asia/Shanghai); startYm/endYm = 锚点向前 11 月~锚点(yyyyMM) 3. latestHerd / latestOutbound = 各表最近 stat_year+stat_month 4. industryOverview 三项 = 最近年月全县合计(与 year 无关) 5. inventoryChange header + ageStructure = latestHerd 年月全县合计 6. monthlyTrend = buildRolling12MonthBullCowTrend(selectHerd...Range(startYm,endYm), anchor) 7. outboundMonthly = buildRolling12MonthOutbound(selectOutbound...Range(startYm,endYm), anchor) 8. grassland / tradeCounts / appointment / subsidy / agri / training = 按 year 或实时(同前) 9. return AjaxResult.success(vo) ``` --- ### 3.2 养殖标准分页列表 #### Query | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `statYear` | string | Y | 同 **3.1** | | `category` | string | Y | `BREEDING_MGMT` / `FEEDING` / `EQUIPMENT` / `TREATMENT` / `GROWTH` | | `pageNum` | int | N | 默认 `1` | | `pageSize` | int | N | 默认 `10`;建议 **5~10** | #### 响应 `TableDataInfo`:`rows` 为 **§3.2.1** 数组,`total` 为当前 Tab 下符合条件的总数。 **不提供**大屏专用 `GET /standards/{id}`;行内详情字段一次返回(对齐共同富裕列表约定)。 #### 3.2.1 `rows[]` | 字段 | 类型 | 说明 | | --- | --- | --- | | `id` | long | 标准 ID | | `standardName` | string | 标准名称 | | `standardType` | string | 类型编码 | | `standardTypeName` | string | 类型展示名(字典/资讯类别) | | `introduction` | string | 简介 | | `contentFileUrl` | string | 正文附件 URL | | `coverFileUrl` | string | 封面 URL,可空 | | `createTime` | string | 创建时间 | | `publishTime` | string | 发布时间 | 默认排序:`create_time DESC, id DESC`。 --- ### 3.3 地图标注 #### Query 无参数。存栏/出栏各取填报表**最近 `stat_year` + `stat_month`**(两表可不同): | 字段 | 说明 | | --- | --- | | `herdStatYear` / (隐含 `herdStatMonth` 于 SQL) | 存栏表最近填报年 | | `outboundStatYear` | 出栏表最近填报年 | #### 响应 `data` | 字段 | 类型 | 说明 | | --- | --- | --- | | `herdStatYear` | int | 存栏数据最近填报年(可空) | | `outboundStatYear` | int | 出栏数据最近填报年(可空) | | `markers` | array | 乡镇标注列表,见下表 | `markers[]`: | 字段 | 类型 | 说明 | | --- | --- | --- | | `townDeptId` | long | 所属乡镇 `dept_id`(`sys_dept`) | | `townName` | string | 乡镇名称 | | `yakInventoryCount` | int | 牦牛存栏数(头),`biz_yak_herd_inventory.yak_total`;无填报为 **0** | | `yakOutboundCount` | int | 牦牛出栏数(头),`biz_yak_outbound_report.yak_outbound_count`;无填报为 **0** | #### 乡镇范围 与牦牛存栏/出栏填报模块一致:`sys_dept` 中 `parent_id = 100`、`order_num > 12`、`del_flag = '0'`、`status = '0'`,按 `order_num`、`dept_id` 升序。 #### 服务端逻辑(摘要) ``` 1. latestHerd = selectLatestHerdInventoryStatPeriod() 2. latestOutbound = selectLatestOutboundReportStatPeriod() 3. markers = selectTownMapMarkers(herdYear, herdMonth, outboundYear, outboundMonth) 4. return AjaxResult.success(vo) ``` --- ## 4. 前端实现要点 **工程**:`ruoyi-screen/src/views/home/`(`index.vue`、`chartOptions.js`)。 ### 4.1 滚动 12 月图表(存栏 / 出栏 / 预约 / 培训) | 项 | 实现 | | --- | --- | | 数据字段 | `monthlyTrend[]`、`outboundMonthly[]`、`appointment.monthlyStacked[]`、`trainingTrend.monthly[]` | | 排序 | 按 `statYear`、`month` 升序 | | 横轴 | **仅月份**(`8月`);`chartOptions.js` | | Tooltip | **完整年月**(`2025年8月`)+ 数值 | | 与 `statYear` | 切换年份**不**改变上述图表数据窗口 | --- ## 5. 菜单与权限(示例) | 类型 | 名称 | 权限标识 | | --- | --- | --- | | 菜单 | 大屏首页 | `bigScreen:home:query` | SQL 示例:`sql/big_screen_home_perm.sql`(挂载「大屏」父菜单下)。 --- ## 6. 交付清单 - [ ] `HomeScreenController` + `IHomeScreenService` + VO + `HomeScreenSupport` - [ ] 复用 `BreedingIndustryStatsMapper` / `BreedingIndustryCalculator`(按 **Y** 与全县牧场) - [ ] 预约、补贴、标准、科技资源、实战培训 Mapper 扩展(**§2.6**) - [ ] 单元测试:滚动 12 月补 0、`statYear`+`month`、主数据不随 **Y** 变、地图最近填报年月 - [ ] 接口测试:`/bigScreen/home/dashboard`、`/standards`、`/townMapMarkers` - [ ] 菜单权限 SQL;依赖各业务表 DDL 已执行 --- ## 7. 修订记录 | 版本 | 日期 | 说明 | | --- | --- | --- | | 1.3 | 2026-07-17 | 年龄结构两档 `COW_YOUNG`/`COW_ADULT`,字段 `cow_young_count`/`cow_adult_count` | | 1.2 | 2026-07-04 | 预约堆叠、培训趋势改滚动 12 月 + statYear;前端横轴/Tooltip 与存栏出栏一致 | | 1.1 | 2026-07-04 | 存栏/出栏改填报表滚动 12 月;VO 增 `statYear`;年龄四档;地图/总览最近填报年月;§4 前端横轴/Tooltip | | 1.0 | 2026-05-20 | 初稿:无新表;双接口;对齐 `大屏首页功能需求.md` v1.0 |