共同富裕

baqing-admin/src/main/java/com/ruoyi/web/modules/prosperity/domain/vo/AchievementAnnualReportVo.java

@@ -4,18 +4,27 @@ import java.io.Serializable;
 import java.util.List;
 
 /**
- * 共同富裕成果年度报告响应。
+ * 共同富裕成果年度报告 / 大屏成果区块响应。
+ * <p>
+ * 口径（管理端与大屏共用）：
+ * {@code summary} = 所选年最大统计月单月值；
+ * {@code monthly} = 该年 1～最大月（缺月补 0）；无台账时 {@code hasData=false}。
+ * </p>
  */
 public class AchievementAnnualReportVo implements Serializable
 {
     private static final long serialVersionUID = 1L;
 
+    /** 统计年份 */
     private Integer statYear;
 
+    /** 该年是否存在 ≥1 条成果台账 */
     private Boolean hasData;
 
+    /** 总览指标；无数据时为 null（勿展示全 0） */
     private AchievementAnnualSummaryVo summary;
 
+    /** 按月序列（长度 = 最大统计月）；无数据时为空列表 */
     private List<AchievementMonthlyVo> monthly;
 
     public Integer getStatYear()

baqing-admin/src/main/java/com/ruoyi/web/modules/prosperity/domain/vo/AchievementAnnualSummaryVo.java

@@ -4,32 +4,44 @@ import java.io.Serializable;
 import java.math.BigDecimal;
 
 /**
- * 年度报告 — 年度总览汇总。
+ * 成果总览指标（管理端年度报告 / 大屏总览与数字赋能）。
+ * <p>当前口径：所选年台账<strong>最大统计月</strong>的单月值（非全年加总）。</p>
  */
 public class AchievementAnnualSummaryVo implements Serializable
 {
     private static final long serialVersionUID = 1L;
 
+    /** 集体经济收入（万元） */
     private BigDecimal collectiveEconomyIncome;
 
+    /** 带动就业人数（人） */
     private Integer employmentDrivenCount;
 
+    /** 新增就业岗位（个） */
     private Integer newJobPositions;
 
+    /** 环境治理项目数（个） */
     private Integer envProjectCount;
 
+    /** 新增绿化面积（亩） */
     private BigDecimal newGreenArea;
 
+    /** 文化传承人数（人） */
     private Integer culturalHeritageCount;
 
+    /** 民族融合项目数（个） */
     private Integer ethnicIntegrationProjectCount;
 
+    /** 民族团结活动数（个） */
     private Integer ethnicUnityActivityCount;
 
+    /** 数字平台使用率（0～1） */
     private BigDecimal digitalPlatformUsageRate;
 
+    /** 区域公共品牌数（个） */
     private Integer regionalPublicBrandCount;
 
+    /** 品牌产品溢价率（0～1） */
     private BigDecimal brandPremiumRate;
 
     public BigDecimal getCollectiveEconomyIncome()

baqing-admin/src/main/java/com/ruoyi/web/modules/prosperity/domain/vo/AchievementMonthlyVo.java

@@ -4,38 +4,53 @@ import java.io.Serializable;
 import java.math.BigDecimal;
 
 /**
- * 年度报告 — 单月指标序列项。
+ * 成果按月序列单项（管理端图表 / 大屏按月图表）。
+ * <p>序列长度为所选年最大统计月 N，{@code month} 为 1～N；缺月指标为 0。</p>
  */
 public class AchievementMonthlyVo implements Serializable
 {
     private static final long serialVersionUID = 1L;
 
+    /** 所属年（与 statPeriod 前四位一致） */
     private Integer statYear;
 
+    /** 月份 1～12 */
     private Integer month;
 
+    /** 统计范围 yyyy-MM */
     private String statPeriod;
 
+    /** 集体经济收入（万元） */
     private BigDecimal collectiveEconomyIncome;
 
+    /** 带动就业人数 */
     private Integer employmentDrivenCount;
 
+    /** 新增就业岗位 */
     private Integer newJobPositions;
 
+    /** 环境治理项目数 */
     private Integer envProjectCount;
 
+    /** 新增绿化面积（亩） */
     private BigDecimal newGreenArea;
 
+    /** 文化传承人数 */
     private Integer culturalHeritageCount;
 
+    /** 民族融合项目数 */
     private Integer ethnicIntegrationProjectCount;
 
+    /** 民族团结活动数 */
     private Integer ethnicUnityActivityCount;
 
+    /** 数字平台使用率（0～1） */
     private BigDecimal digitalPlatformUsageRate;
 
+    /** 区域公共品牌数 */
     private Integer regionalPublicBrandCount;
 
+    /** 品牌产品溢价率（0～1） */
     private BigDecimal brandPremiumRate;
 
     public Integer getStatYear()

baqing-admin/src/main/java/com/ruoyi/web/modules/screen/controller/CommonProsperityScreenController.java

@@ -2,7 +2,6 @@ package com.ruoyi.web.modules.screen.controller;
 
 import java.util.List;
 import org.springframework.beans.factory.annotation.Autowired;
-import org.springframework.security.access.prepost.PreAuthorize;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RequestParam;
@@ -16,8 +15,14 @@ import com.ruoyi.web.modules.screen.service.ICommonProsperityScreenService;
 /**
  * 大屏 — 共同富裕统计（只读）。
  * <p>
- * 数据来源：年度成果报告（{@code biz_common_prosperity_achievement}）、
- * 已发布共富项目（{@code biz_common_prosperity_project}）及运营图片。
+ * 提供看板聚合与共富项目分页列表。看板含：成果总览 / 数字赋能、按月趋势图、项目分类饼图。
+ * </p>
+ * <p>
+ * 数据来源：{@code biz_common_prosperity_achievement}（成果台账）、
+ * {@code biz_common_prosperity_project}（已发布项目）、运营图片子表。
+ * 成果口径与管理端「共同富裕成果年度报告」一致（共用 {@code AchievementReportAggregator}）。
+ * </p>
+ * <p>权限标识示例：{@code bigScreen:commonProsperity:query}。</p>
  *
  * @see ICommonProsperityScreenService
  */
@@ -29,9 +34,15 @@ public class CommonProsperityScreenController extends BaseController
     private ICommonProsperityScreenService commonProsperityScreenService;
 
     /**
-     * 共富看板：年度成果摘要 + 当年已发布项目类型占比。
+     * 共同富裕看板一屏数据。
+     * <p>
+     * 成果：总览 / 数字赋能取所选年<strong>最大统计月</strong>单月值；
+     * {@code monthly} 为该年 1～最大月（缺月补 0）。
+     * 项目：仅 {@code publish_status=1} 且实施周期与统计年 Y 有交集。
+     * </p>
      *
-     * @param statYear 统计年份；项目筛选为实施周期与 Y 有交集且已发布
+     * @param statYear 统计年份，如 {@code 2026}
+     * @return {@code data} 为 {@link com.ruoyi.web.modules.screen.domain.vo.CommonProsperityScreenDashboardVo}
      */
     @GetMapping("/dashboard")
     public AjaxResult dashboard(@RequestParam("statYear") String statYear)
@@ -40,7 +51,10 @@ public class CommonProsperityScreenController extends BaseController
     }
 
     /**
-     * 当年已发布共富项目分页列表（含运营图片）。
+     * 共富项目分页列表（行内含运营图，无单独详情接口）。
+     * <p>筛选口径同看板项目：已发布且实施周期与 {@code statYear} 有交集；配合 PageHelper。</p>
+     *
+     * @param statYear 统计年份，如 {@code 2026}
      */
     @GetMapping("/projects")
     public TableDataInfo projects(@RequestParam("statYear") String statYear)

baqing-admin/src/main/java/com/ruoyi/web/modules/screen/domain/vo/CommonProsperityScreenDashboardVo.java

@@ -3,21 +3,36 @@ package com.ruoyi.web.modules.screen.domain.vo;
 import java.io.Serializable;
 import java.util.List;
 import com.ruoyi.web.modules.prosperity.domain.vo.AchievementAnnualReportVo;
+
 /**
- * 大屏共同富裕看板（{@code GET /bigScreen/commonProsperity/dashboard}）。
+ * 大屏共同富裕看板响应（{@code GET /bigScreen/commonProsperity/dashboard}）。
+ * <p>
+ * {@code achievement} 结构同管理端年度报告 VO：
+ * {@code summary} 为最大统计月单月值；{@code monthly} 为所选年 1～最大月。
+ * </p>
  */
 public class CommonProsperityScreenDashboardVo implements Serializable
 {
     private static final long serialVersionUID = 1L;
-    /** 统计年份 */
+
+    /** 回显的统计年份 Y */
     private Integer statYear;
-    /** 成果/项目数据涉及年份 */
+
+    /** 可选年份（成果台账年 ∪ 已发布项目实施年 ∪ 当前自然年），降序，供年份选择器 */
     private List<Integer> availableYears;
-    /** 年度成果报告摘要 */
+
+    /**
+     * 成果区块：{@code hasData} / {@code summary}（总览+数字赋能）/ {@code monthly}（按月图表）。
+     * 无台账时 {@code hasData=false}、{@code summary=null}、{@code monthly=[]}。
+     */
     private AchievementAnnualReportVo achievement;
-    /** 已发布项目类型占比 */
+
+    /**
+     * 共富项目分类饼图：固定 3 项（类型 1/2/3）；无项目时 count、ratio 均为 0。
+     */
     private List<ProjectTypeStatVo> projectTypeStats;
-    /** 当年是否有已发布且周期交集的项目 */
+
+    /** 该年是否存在 ≥1 条符合筛选的已发布项目（驱动饼图/列表空态） */
     private Boolean hasProjectData;
 
     public Integer getStatYear()

baqing-admin/src/main/java/com/ruoyi/web/modules/screen/domain/vo/ProjectTypeStatVo.java

@@ -2,19 +2,25 @@ package com.ruoyi.web.modules.screen.domain.vo;
 
 import java.io.Serializable;
 import java.math.BigDecimal;
+
 /**
- * 共富项目类型统计项。
+ * 大屏共富项目分类饼图单项（固定输出类型 1/2/3）。
+ * <p>展示名：1 和美乡村建设项目；2 人居环境整治提升项目；3 其他项目投入。</p>
  */
 public class ProjectTypeStatVo implements Serializable
 {
     private static final long serialVersionUID = 1L;
-    /** 类型 1共富 2农文旅 3认养 */
+
+    /** 项目类型：1 / 2 / 3 */
     private Integer projectType;
-    /** 类型名称 */
+
+    /** 类型展示名称 */
     private String projectTypeName;
-    /** 项目数 */
+
+    /** 该类型项目数 */
     private Integer count;
-    /** 占比（%） */
+
+    /** 占已发布项目总数的比例，0～1（四位小数）；无项目时为 0 */
     private BigDecimal ratio;
 
     public Integer getProjectType()

baqing-admin/src/main/java/com/ruoyi/web/modules/screen/domain/vo/ScreenProjectListItemVo.java

@@ -5,7 +5,8 @@ import java.math.BigDecimal;
 import java.util.List;
 
 /**
- * 共富项目列表项（分页 {@code /bigScreen/commonProsperity/projects}）。
+ * 共富项目列表项（分页 {@code GET /bigScreen/commonProsperity/projects}）。
+ * <p>详情不另开接口，行内一次返回封面、视频、运营图等字段。</p>
  */
 public class ScreenProjectListItemVo implements Serializable
 {
@@ -13,12 +14,15 @@ public class ScreenProjectListItemVo implements Serializable
 
     private Long id;
 
+    /** 项目类型 1/2/3 */
     private Integer projectType;
 
+    /** 类型展示名 */
     private String projectTypeName;
 
     private String projectName;
 
+    /** 项目简介 */
     private String introduction;
 
     /** 建设规模及内容 */
@@ -33,12 +37,16 @@ public class ScreenProjectListItemVo implements Serializable
     /** 实施情况 */
     private String implStatus;
 
+    /** 封面图 URL */
     private String coverFileUrl;
 
+    /** 视频 URL */
     private String videoFileUrl;
 
+    /** 发布时间 yyyy-MM-dd HH:mm:ss */
     private String publishTime;
 
+    /** 运营图片（已按 sortOrder 排序） */
     private List<ScreenProjectOpImageVo> operationImages;
 
     public Long getId()

baqing-admin/src/main/java/com/ruoyi/web/modules/screen/service/ICommonProsperityScreenService.java

@@ -6,12 +6,24 @@ import com.ruoyi.web.modules.screen.domain.vo.ScreenProjectListItemVo;
 
 /**
  * 大屏共同富裕统计服务（只读）。
+ * <p>
+ * 成果组装复用 {@link com.ruoyi.web.modules.prosperity.support.AchievementReportAggregator}，
+ * 与管理端年度报告口径一致。
+ * </p>
  */
 public interface ICommonProsperityScreenService
 {
-    /** 年度成果 + 已发布项目类型统计 */
+    /**
+     * 加载看板：成果（总览 + 1～最大月序列）+ 项目类型占比 + 可选年份。
+     *
+     * @param statYear 统计年份（四位），非法时抛业务异常
+     */
     CommonProsperityScreenDashboardVo loadDashboard(String statYear);
 
-    /** 当年已发布项目列表（含运营图片） */
+    /**
+     * 已发布且实施周期与统计年有交集的项目列表（含运营图片）。
+     *
+     * @param statYear 统计年份（四位）
+     */
     List<ScreenProjectListItemVo> listPublishedProjects(String statYear);
 }

baqing-admin/src/main/java/com/ruoyi/web/modules/screen/service/impl/CommonProsperityScreenServiceImpl.java

@@ -23,8 +23,13 @@ import com.ruoyi.web.modules.screen.support.CommonProsperityScreenSupport;
 /**
  * 大屏共同富裕统计服务实现。
  * <p>
- * 成果口径与管理端年度报告一致：总览为所选年<strong>最大统计月</strong>单月值；
- * 按月图表为该年 1～最大月（缺月补 0）；项目列表仅含已发布且实施周期与统计年有交集的记录。
+ * 成果口径（与管理端年度报告一致，见 {@link AchievementReportAggregator#buildReport}）：
+ * <ul>
+ *   <li>总览 / 数字赋能：所选年台账中<strong>最大统计月</strong>的单月指标</li>
+ *   <li>按月图表：该年 <strong>1～最大月</strong>，区间内缺月补 0；无台账则 {@code monthly} 为空</li>
+ * </ul>
+ * 项目：仅已发布且实施周期与统计年有交集；分类占比固定三类（缺类 count=0）。
+ * </p>
  */
 @Service
 public class CommonProsperityScreenServiceImpl implements ICommonProsperityScreenService
@@ -38,23 +43,34 @@ public class CommonProsperityScreenServiceImpl implements ICommonProsperityScree
     @Autowired
     private BizCommonProsperityProjectOpImageMapper opImageMapper;
 
+    /**
+     * {@inheritDoc}
+     * <p>步骤：校验年份 → 按年查成果并组装报告 → 查已发布项目做分类统计 → 合并可选年份。</p>
+     */
     @Override
     public CommonProsperityScreenDashboardVo loadDashboard(String statYear)
     {
         int year = AchievementReportValidation.parseStatYear(statYear);
         CommonProsperityScreenDashboardVo vo = new CommonProsperityScreenDashboardVo();
         vo.setStatYear(year);
+        // 成果：summary=最大月单月；monthly=1～最大月
         List<BizCommonProsperityAchievement> rows = safeAchievementsByYear(year);
         vo.setAchievement(AchievementReportAggregator.buildReport(year, rows));
+        // 项目分类饼图 + 是否有项目数据
         List<BizCommonProsperityProject> projects = safePublishedForScreen(year);
         vo.setHasProjectData(!projects.isEmpty());
         vo.setProjectTypeStats(CommonProsperityScreenSupport.buildProjectTypeStats(projects));
+        // 年份下拉：成果年 ∪ 已发布项目实施年 ∪ 当前自然年，降序
         vo.setAvailableYears(CommonProsperityScreenSupport.buildAvailableYears(
                 achievementMapper.selectDistinctStatYears(),
                 projectMapper.selectDistinctStatYearsFromPublished()));
         return vo;
     }
 
+    /**
+     * {@inheritDoc}
+     * <p>先查项目主表，再按 ID 批量查运营图并按 {@code sort_order} 组装到行内。</p>
+     */
     @Override
     public List<ScreenProjectListItemVo> listPublishedProjects(String statYear)
     {
@@ -71,12 +87,14 @@ public class CommonProsperityScreenServiceImpl implements ICommonProsperityScree
         return CommonProsperityScreenSupport.toListItems(projects, byProject);
     }
 
+    /** 大屏已发布项目（实施周期与统计年交集）；Mapper 返回 null 时转空列表 */
     private List<BizCommonProsperityProject> safePublishedForScreen(int statYear)
     {
         List<BizCommonProsperityProject> list = projectMapper.selectPublishedForScreen(statYear);
         return list != null ? list : new ArrayList<>();
     }
 
+    /** 所选年成果台账（{@code stat_period like 'Y-%'}）；null 转空列表 */
     private List<BizCommonProsperityAchievement> safeAchievementsByYear(int statYear)
     {
         List<BizCommonProsperityAchievement> list = achievementMapper.selectByStatYear(String.valueOf(statYear));

baqing-admin/src/main/java/com/ruoyi/web/modules/screen/support/CommonProsperityScreenSupport.java

@@ -21,12 +21,16 @@ import com.ruoyi.web.modules.screen.domain.vo.ScreenProjectOpImageVo;
 
 /**
  * 大屏共同富裕 — 项目筛选、分类统计、列表组装（纯逻辑，便于单测）。
+ * <p>
+ * 项目纳入规则由 Mapper SQL 保证：已发布 + 实施周期与统计年交集；
+ * 本类负责类型名解析、三类占比、可选年份并集、列表 VO 与运营图分组排序。
+ * </p>
  */
 public final class CommonProsperityScreenSupport
 {
     private static final String DATETIME_FMT = "yyyy-MM-dd HH:mm:ss";
 
-    /** 1 和美乡村建设；2 人居环境整治提升；3 其他项目投入 */
+    /** 下标 1～3 对应项目类型展示名 */
     private static final String[] TYPE_NAMES = {
             null, "和美乡村建设项目", "人居环境整治提升项目", "其他项目投入"
     };
@@ -35,6 +39,7 @@ public final class CommonProsperityScreenSupport
     {
     }
 
+    /** 解析项目类型展示名；非法类型返回空串 */
     public static String resolveProjectTypeName(Integer projectType)
     {
         if (projectType == null || projectType < 1 || projectType > 3)
@@ -45,7 +50,9 @@ public final class CommonProsperityScreenSupport
     }
 
     /**
-     * 已发布且实施年限等于统计年 Y。
+     * 是否纳入大屏统计：已发布（publish_status=1）且实施年限等于统计年 Y。
+     * <p>注：列表/分类实际筛选以 Mapper {@code selectPublishedForScreen} 的周期交集为准；
+     * 本方法用于单测与 impl_year 精确匹配场景。</p>
      */
     public static boolean matchesStatYear(BizCommonProsperityProject project, int statYear)
     {
@@ -62,6 +69,9 @@ public final class CommonProsperityScreenSupport
         return matchesStatYear(project, statYear);
     }
 
+    /**
+     * 项目分类占比：固定输出类型 1/2/3 三项；{@code ratio = count/total}（无项目时全 0）。
+     */
     public static List<ProjectTypeStatVo> buildProjectTypeStats(List<BizCommonProsperityProject> projects)
     {
         int c1 = 0;
@@ -115,6 +125,9 @@ public final class CommonProsperityScreenSupport
         return stats;
     }
 
+    /**
+     * 可选年份并集：成果台账年 + 已发布项目实施年 + 当前自然年，降序。
+     */
     public static List<Integer> buildAvailableYears(List<String> achievementYearStrs,
             List<String> projectYearStrs)
     {
@@ -141,6 +154,7 @@ public final class CommonProsperityScreenSupport
         }
     }
 
+    /** 项目主表 → 大屏列表行（含运营图 URL 列表） */
     public static List<ScreenProjectListItemVo> toListItems(List<BizCommonProsperityProject> projects,
             Map<Long, List<BizCommonProsperityProjectOpImage>> imagesByProjectId)
     {
@@ -172,6 +186,7 @@ public final class CommonProsperityScreenSupport
         return list;
     }
 
+    /** 运营图按 projectId 分组，组内按 sortOrder 升序 */
     public static Map<Long, List<BizCommonProsperityProjectOpImage>> groupImagesByProjectId(
             List<BizCommonProsperityProjectOpImage> images)
     {