西藏巴青项目

大屏 — 共同富裕统计 — 技术方案

依据：同目录 大屏共同富裕功能需求.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 + ECharts 或大屏框架）；一次切换年份拉取看板主数据，项目列表分页单独请求
代码包	`com.ruoyi.web.modules.prosperity`（建议新增 `screen` 子包：`controller` / `service` / `vo`）

分层：CommonProsperityScreenController → ICommonProsperityScreenService（口径编排）→ 复用 IAchievementReportService + BizCommonProsperityProjectMapper / BizCommonProsperityProjectOpImageMapper。

场景	行为
进入 / 切换统计年份	调用 §3.1 返回成果总览、按月序列、数字赋能汇总、项目分类占比、可选年份
项目列表翻页	仅调用 §3.2，不改变成果区块
数据权限	全县共富数据，不按部门/用户过滤（与成果台账、项目维护范围一致）
汇总口径	与《共同富裕成果年度报告技术方案》§2.3 一致；`hasAchievementData=false` 时 `summary=null`
性能	单年成果 ≤12 行、项目量级有限，默认实时查询；可选 §2.3 缓存表

依赖表（只读）

表	用途
`biz_common_prosperity_achievement`	月度成果 → 总览、图表、数字赋能
`biz_common_prosperity_project`	已发布项目 → 分类饼图、列表
`biz_common_prosperity_project_op_image`	列表运营图片（1～3 张）

2. 数据库设计

2.1 本模块业务表

无新增业务台账表。 DDL 以 sql/biz_common_prosperity_achievement.sql、sql/biz_common_prosperity_project.sql 为准。

2.2 查询口径（SQL 条件）

成果（按统计年份 `Y`）

项	条件
按年取数	`stat_period LIKE CONCAT(#{statYear}, '-%')`，`ORDER BY stat_period ASC`
缺月补 0 / 年度汇总	服务端 `AchievementReportAggregator`（已实现，直接复用）
`hasAchievementData`	该年 `COUNT(*) > 0`

项目（按统计年份 `Y`）

项	条件
发布状态	`publish_status = 1`
实施年限等于 Y	`impl_year = #{statYear}`
列表默认排序	`publish_time DESC, id DESC`
分类统计	在上述集合上 `GROUP BY project_type`，得各类型 `count`、`ratio`（`ratio = count / total`，`total=0` 时占比均为 0）
运营图	`biz_common_prosperity_project_op_image` 按 `project_id IN (...)`，`sort_order ASC`

project_type 枚举：1 和美乡村建设项目；2 人居环境整治提升项目；3 其他项目投入。

2.3 可选表 `biz_common_prosperity_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 分钟（与功能需求 §7.4 一致）。

2.4 索引建议（既有表）

表	建议
`biz_common_prosperity_achievement`	沿用 `uk_stat_period` / `idx_stat_period`
`biz_common_prosperity_project`	沿用 `idx_publish`、`idx_impl_year`

2.5 Mapper 扩展（建议方法名）

Mapper	方法	说明
`BizCommonProsperityProjectMapper`	`selectPublishedForScreen(statYear)`	分类统计用，返回 `project_type` 列表或 `GROUP BY` 结果
同上	`selectPublishedListForScreen(statYear)`	列表分页（配合 PageHelper）
`BizCommonProsperityProjectOpImageMapper`	`selectByProjectIds(ids)`	批量加载运营图

3. 接口设计

统一响应：AjaxResult（code / msg / data）；项目分页列表使用 TableDataInfo（rows / total）。

权限标识（示例）：bigScreen:commonProsperity:query（仅查询；与成果/项目 CRUD 分离）

Base Path：/bigScreen/commonProsperity

大屏若部署为免登录展示，可调用 《大屏免密登录技术方案》（doc/大屏/免密登录/大屏免密登录技术方案.md）中 POST /bigScreen/login 换取 JWT；看板接口仍走 Token + 权限，不在各看板 Controller 使用 @Anonymous 写死。

#	说明	Method	URI	权限
3.1	看板主数据（成果 + 分类）	GET	`/bigScreen/commonProsperity/dashboard`	`bigScreen:commonProsperity:query`
3.2	共富项目分页列表	GET	`/bigScreen/commonProsperity/projects`	同上

前端：切换 statYear → 调 3.1 + 3.2（pageNum=1）；仅翻页 → 调 3.2。

3.1 看板主数据

Query

参数	类型	必填	说明
`statYear`	string	Y	四位年份，如 `2026`；非法 → 业务异常（复用 `AchievementReportValidation`）
`forceRefresh`	boolean	N	默认 `false`；`true` 时跳过 §2.3 缓存

响应 `data`

字段	类型	说明
`statYear`	int	回显
`availableYears`	int[]	成果表与项目表出现过的年份并集，降序；供年份选择器
`achievement`	object	成果区块，结构同 `AchievementAnnualReportVo`（见下）
`projectTypeStats`	array	项目分类饼图，见 §3.1.1
`hasProjectData`	boolean	该年是否存在 ≥1 条符合 §2.2 的已发布项目

achievement 节点（复用年度报告 VO，勿改口径）：

字段	说明
`hasData`	即 `hasAchievementData`；全年无成果台账为 `false`
`summary`	总览 / 数字赋能；取所选年台账最大统计月单月值；`hasData=false` 时为 `null`
`monthly`	所选年 1～最大统计月 N，共 N 条；每项含 `statYear`、`month`、`statPeriod`；缺月指标为 0；无数据时为空列表

图表字段映射（与功能需求 §5、年度报告一致）

大屏区块	取用
总览卡片 / 数字赋能	`achievement.summary.*`
集体经济收入（横向柱）	`achievement.monthly[].collectiveEconomyIncome`
就业带动（双折线）	`employmentDrivenCount`、`newJobPositions`
环境治理 / 文化传承（柱）	`envProjectCount` / `culturalHeritageCount`
绿化建设（折线）	`newGreenArea`
民族团结（堆叠柱）	`ethnicIntegrationProjectCount`、`ethnicUnityActivityCount`

3.1.1 `projectTypeStats[]`

字段	类型	说明
`projectType`	int	`1` / `2` / `3`
`projectTypeName`	string	和美乡村建设项目 / 人居环境整治提升项目 / 其他项目投入
`count`	int	数量
`ratio`	decimal	占比 0～1；`hasProjectData=false` 时三项 `count=0`、`ratio=0`

响应示例（节选）

{
  "statYear": 2026,
  "availableYears": [2026, 2025],
  "hasProjectData": true,
  "achievement": {
    "statYear": 2026,
    "hasData": true,
    "summary": { "collectiveEconomyIncome": 120.50, "digitalPlatformUsageRate": 0.7250 },
    "monthly": [{ "month": 1, "collectiveEconomyIncome": 10.00 }]
  },
  "projectTypeStats": [
    { "projectType": 1, "projectTypeName": "和美乡村建设项目", "count": 5, "ratio": 0.50 }
  ]
}

服务端逻辑（摘要）

1. year = parseStatYear(statYear)
2. rows = achievementMapper.selectByStatYear(year)
3. achievement = AchievementReportAggregator.buildReport(year, rows)
   — summary = 最大月单月；monthly = 1～最大月缺月补 0；无数据 monthly=[]、summary=null
4. projects = mapper.selectPublishedForScreen(year)
5. projectTypeStats = groupByType(projects); hasProjectData = total > 0
6. availableYears = union(achievementMapper.selectDistinctStatYears(), projectYears)
7. return AjaxResult.success(vo)

3.2 共富项目分页列表

Query

参数	类型	必填	说明
`statYear`	string	Y	同 3.1
`pageNum`	int	N	默认 `1`
`pageSize`	int	N	默认 `8`；建议 5～10

响应

TableDataInfo：rows 为 §3.2.1 结构数组，total 为符合条件的项目总数。

不提供 GET /project/{id} 大屏专用详情接口；列表行内字段一次返回（对齐功能需求 §5.11）。

3.2.1 `rows[]` 单条

字段	类型	说明
`id`	long	项目 ID
`projectType` / `projectTypeName`	int / string	类型枚举与展示名
`projectName`	string	项目名称
`introduction`	string	简介
`projectContent`	string	内容
`implYear`	int	实施年限
`investmentAmount`	number	投资金额（万元），可空
`implStatus`	string	实施情况，可空
`coverFileUrl`	string	封面 URL，可空
`videoFileUrl`	string	运营视频 URL，可空
`publishTime`	string	发布时间
`operationImages`	array	`{ fileUrl, sortOrder }`，1～3 条，按 `sortOrder` 升序

3.3 共富项目分类情况明细

Query

参数	类型	必填	说明
`statYear`	int	N	所属年份（实施年限）；未传默认当前自然年
`pageNum`	int	N	默认 `1`
`pageSize`	int	N	默认若依分页

响应

TableDataInfo：按 impl_year 倒序；口径与看板分类一致（publish_status=1）。

3.3.1 `rows[]` 单条

字段	类型	说明
`statYear`	int	所属年份（`impl_year`）
`totalCount`	int	项目总数（个）
`heMeiVillageCount`	int	和美乡村建设项目数（`project_type=1`）
`habitatImproveCount`	int	人居环境整治提升项目数（`project_type=2`）
`otherProjectCount`	int	其他项目投入数（`project_type=3`）

GET /bigScreen/commonProsperity/projectTypeDetails

4. 菜单与权限（示例）

类型	名称	权限标识	说明
菜单	大屏共同富裕	`bigScreen:commonProsperity:query`	路由指向大屏页面组件
按钮	查看	`bigScreen:commonProsperity:query`	与菜单共用

SQL 示例：sql/big_screen_common_prosperity_perm.sql（挂载「大屏」父菜单下）。

5. 交付清单

CommonProsperityScreenController + ICommonProsperityScreenService + VO
BizCommonProsperityProjectMapper 大屏查询 SQL（§2.2 条件）
复用 IAchievementReportService / AchievementReportAggregator（禁止大屏单独写一套汇总）
单元测试：全年无成果（summary=null）、缺月补 0、项目年份交集、仅项目无成果、分类占比、分页列表含运营图
接口测试：/bigScreen/commonProsperity/dashboard、/projects、/projectTypeDetails
菜单权限 SQL；依赖成果/项目表 DDL 已执行
大屏前端页面（另见前端技术方案，本期可后补）

6. 修订记录

版本	日期	说明
1.0	2026-05-20	初稿：无新业务表；复用成果年度报告聚合；双接口（看板 + 项目分页）；对齐功能需求 v1.0
1.1	2026-07-24	看板 `monthly` 改回所选年 1～12 月（与 `summary` 同源），不再覆盖为滚动 12 月
1.2	2026-07-24	看板 `summary` 改为所选年最大统计月单月值；`monthly` 仍为该年 1～12 月
1.3	2026-07-24	`monthly` 改为所选年 1～最大月；与管理端年度报告共用 Aggregator 口径
1.4	2026-07-24	新增共富项目分类情况明细 `GET /projectTypeDetails`（分页、按年聚合）

大屏共同富裕技术方案.md 12KB Historie Surový

大屏 — 共同富裕统计 — 技术方案

1. 技术架构

2. 数据库设计

2.1 本模块业务表

2.2 查询口径（SQL 条件）

成果（按统计年份 Y）

项目（按统计年份 Y）

2.3 可选表 biz_common_prosperity_screen_cache（性能优化）

2.4 索引建议（既有表）

2.5 Mapper 扩展（建议方法名）

3. 接口设计

3.1 看板主数据

Query

响应 data

3.1.1 projectTypeStats[]

响应示例（节选）

服务端逻辑（摘要）

3.2 共富项目分页列表

Query

响应

3.2.1 rows[] 单条

3.3 共富项目分类情况明细

Query

响应

3.3.1 rows[] 单条

4. 菜单与权限（示例）

5. 交付清单

6. 修订记录

大屏共同富裕技术方案.md 12KB

Historie Surový

成果（按统计年份 `Y`）

项目（按统计年份 `Y`）

2.3 可选表 `biz_common_prosperity_screen_cache`（性能优化）

响应 `data`

3.1.1 `projectTypeStats[]`

3.2.1 `rows[]` 单条

3.3.1 `rows[]` 单条