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

> 依据：同目录 `大屏共同富裕功能需求.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` |

#### 响应示例（节选）

```json
{
  "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`（分页、按年聚合） |