huimv-baqing/doc/共同富裕/共同富裕成果年度报告/共同富裕成果年度报告技术方案.md

共同富裕成果年度报告 — 技术方案

依据：同目录 共同富裕成果年度报告功能需求.md；数据源为《共同富裕成果技术方案》表 biz_common_prosperity_achievement。本模块只读统计，无独立业务表。

---

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.commonprosperity（与成果台账同包，建议 achievement 子包旁增 report 或合入 AchievementReportController）

分层：Controller（权限、statYear 校验、AjaxResult）→ ReportService（按年查询、缺月补 0、年度汇总）→ 复用 BizCommonProsperityAchievementMapper（或只读 SQL）。

实现要点

• 不新建业务表；按 stat_year 查询成果表，内存组装 12 个月序列 + 年度总览。
• 缺月按 0（功能需求 §2.2、§2.4）；全年无记录时 hasData=false，不返回「全 0 汇总」误导前端。
• 前端一次请求加载总览与全部图表（功能需求 §8 性能建议）。

---

2. 数据库设计

2.1 本模块表结构

无新增表。 年度报告数据全部来自既有表：

表名	用途
biz_common_prosperity_achievement	月度成果台账；按 stat_period（YYYY-MM）取数

字段、DDL、索引以《共同富裕成果技术方案》§2 为准，此处不重复。

2.2 查询与索引

项	说明
按年筛选	stat_period LIKE CONCAT(#{statYear}, '-%') 或 LEFT(stat_period, 4) = #{statYear}
排序	ORDER BY stat_period ASC（组装 1～12 月）
索引	沿用 idx_stat_period / uk_stat_period；单年最多 12 行，无额外索引要求
可选年份列表	SELECT DISTINCT LEFT(stat_period, 4) AS stat_year FROM biz_common_prosperity_achievement ORDER BY stat_year DESC

2.3 汇总计算（服务端，与大屏共同富裕一致）

类型	字段	算法
总览 summary	全部 12 项指标	取该年台账 最大统计月 的单月值
分月 monthly	同上字段	所选年 1～最大月 N；区间内缺月补 0；无数据返回空列表

hasData 判定：该年存在 ≥1 条有效台账为 true；为 false 时 summary=null，monthly=[]。

---

3. 接口设计

统一响应：AjaxResult → data 为 3.1 结构（驼峰 JSON）。

权限标识（示例）：commonProsperity:achievementReport:query（仅查询；与成果台账 CRUD 权限分离）

Base Path（示例）：/commonProsperity/achievementReport

#	说明	Method	URI	权限	要点
3.1	年度报告数据	GET	/commonProsperity/achievementReport	commonProsperity:achievementReport:query	Query：statYear（必填，4 位年）
3.2	可选年份列表	GET	/commonProsperity/achievementReport/years	同上	无参；返回台账中出现过的年份，供年份选择器

若希望接口更少，可将 3.2 的 availableYears 并入 3.1 的 data.availableYears。

3.1.1 Query 参数（年度报告）

参数	类型	必填	说明
statYear	int / string	Y	统计年份，如 2026；非法年份返回 400 业务错误

3.1.2 响应 data 结构

{
  "statYear": 2026,
  "hasData": true,
  "summary": {
    "collectiveEconomyIncome": 120.50,
    "employmentDrivenCount": 360,
    "newJobPositions": 48,
    "envProjectCount": 12,
    "newGreenArea": 85.20,
    "culturalHeritageCount": 24,
    "ethnicIntegrationProjectCount": 6,
    "ethnicUnityActivityCount": 18,
    "digitalPlatformUsageRate": 0.7250,
    "regionalPublicBrandCount": 9,
    "brandPremiumRate": 0.1500
  },
  "monthly": [
    {
      "month": 1,
      "statPeriod": "2026-01",
      "collectiveEconomyIncome": 10.00,
      "employmentDrivenCount": 30,
      "newJobPositions": 4,
      "envProjectCount": 1,
      "newGreenArea": 7.10,
      "culturalHeritageCount": 2,
      "ethnicIntegrationProjectCount": 1,
      "ethnicUnityActivityCount": 2,
      "digitalPlatformUsageRate": 0.80,
      "regionalPublicBrandCount": 1,
      "brandPremiumRate": 0.12
    }
  ]
}

字段	说明
statYear	请求年份回显
hasData	该年是否存在 ≥1 条成果记录
summary	年度总览；hasData=false 时为 null（不推荐返回全 0）
monthly	固定长度 12；month 为 1～12；statPeriod 有台账则为 YYYY-MM，缺月为 null 或省略（指标值均为 0）
monthly[].* 指标	与成果台账字段一致（驼峰）；缺月各项为 0

图表与字段映射（前端）

图表区块	取用字段
集体经济收入（横向柱）	monthly[].collectiveEconomyIncome
就业带动（双折线）	employmentDrivenCount、newJobPositions
环境治理（柱）	envProjectCount
绿化建设（折线）	newGreenArea
文化传承（柱）	culturalHeritageCount
民族团结（堆叠柱）	ethnicIntegrationProjectCount、ethnicUnityActivityCount

3.2 响应 data（可选年份）

{
  "years": [2026, 2025, 2024]
}

3.3 服务端逻辑（摘要）

1. 校验 statYear（四位数字，合理范围如 1900–2100）
2. List<Achievement> rows = mapper.selectByStatYear(statYear)
3. hasData = rows.notEmpty()
4. Map<Integer, Achievement> byMonth = 按 stat_period 月份 1-12 映射
5. for m in 1..12:
     monthly[m] = byMonth.get(m) 或 全指标 0
6. if hasData:
     summary = 按 §2.3 对 monthly 序列做 SUM / AVG(比率,÷12)
   else:
     summary = null
7. return AjaxResult.success(data)

异常：statYear 缺失/非法 → code/msg 明确；Mapper 异常走统一异常处理。

---

4. 菜单与权限（示例）

类型	名称	权限标识	组件路径（示例）
菜单	共同富裕成果年度报告	commonProsperity:achievementReport:query	commonProsperity/achievementReport/index

前端 API 建议：ruoyi-ui/src/api/commonProsperity/achievementReport.js → getAchievementAnnualReport(statYear)。

---

5. 交付清单

• AchievementReportController + IAchievementReportService（或合入现有 Service）
• Mapper 方法：selectByStatYear、selectDistinctYears（只读）
• 单元测试：全年无数据、仅 3 月有数据（其余月为 0）、比率年均、加总正确
• 前端：年份选择 + ECharts 六图 + hasData 空态；i18n 复用 commonProsperity.achievement
• 菜单权限 SQL（commonProsperity:achievementReport:query）
• 依赖成果表 DDL 已执行（biz_common_prosperity_achievement）

---

6. 修订记录

版本	说明
1.0	初稿：无新表；单接口年度报告 + 可选年份列表；缺月补 0；hasData 控制空态
1.1	与大屏对齐：总览取最大月单月；monthly 为 1～最大月