# 共同富裕成果年度报告 — 功能需求

## 1. 文档说明

| 项 | 说明 |
| --- | --- |
| 模块名称 | 共同富裕成果年度报告 |
| 目标 | 按**统计年份**汇总展示《共同富裕成果》台账中的月度指标，以总览卡片与分主题图表呈现年度共富成效，支撑管理端查阅与汇报 |
| 数据来源 | **共同富裕成果**模块已登记的月度成果记录（统计范围为 **YYYY-MM**）；本模块**不新增、不修改、不删除**成果台账数据 |
| 关联系统 | 业务后台；大屏或移动端若需同款图表，口径须与本文档一致 |
| 修订依据 | 同目录 `共同富裕成果年度报告-草稿.md`；指标定义与《共同富裕成果功能需求》对齐 |
| 原型参考 | 同目录 `共同富裕成果年度报告.png`（布局与图表类型以原型为准，业务规则以本文档为准） |

本文档仅描述**功能需求与业务规则**，不涉及库表结构、接口路径、请求体字段命名及技术栈选型。

---

## 2. 术语与说明

### 2.1 统计年份

- 用户在本模块顶部选择的**自然年**，格式 **YYYY**（如 `2026`）。
- 系统仅汇总该年内、统计范围属于 `YYYY-01`～`YYYY-12` 的**共同富裕成果**记录。
- 未选择年份时，默认展示**当前自然年**；若当前年无任何数据，按 **§7.2** 空态处理。

### 2.2 统计月份（图表横轴）

- 图表按月展示时，横轴为选定年 **1 月～该年台账中最大统计月 N**，共 **N** 个刻度（与大屏共同富裕一致）。
- **缺月规则：** 1～N 内某月**无**对应成果记录时，该月各指标按 **0** 取值（**不**断线、**不**留空、**不**跳过该月）。Tooltip 仍展示「0 + 单位」。
- 全年无任何台账时走 **§7.2** 空态，`monthly` 为空列表。

### 2.3 共富成果指标（与台账一致）

本模块展示的 **12 项指标** 与《共同富裕成果功能需求》**§5.1** 一致，含义与单位不变：

| 指标 | 单位 / 展示 |
| --- | --- |
| 集体经济收入 | 万元 |
| 带动就业人数 | 人 |
| 新增就业岗位 | 个 |
| 环境治理项目数 | 个 |
| 新增绿化面积 | 亩 |
| 文化传承人数 | 人 |
| 民族融合项目数 | 个 |
| 民族团结活动数 | 个 |
| 数字平台使用率 | 比率 0～1，展示可换算为百分比 |
| 区域公共品牌数 | 个 |
| 品牌产品溢价率 | 比率 0～1，展示可换算为百分比 |

### 2.4 汇总口径（年度总览）

**年度总览区**（见 **§5.2**）与大屏共同富裕总览口径一致：

| 指标类型 | 年度展示口径 |
| --- | --- |
| 全部 12 项指标（含比率） | 取该年台账中 **`stat_period` 最大月份** 的**单月**指标值（非全年加总、非 12 月均值） |

> **全年无任何台账记录**时仍走 **§7.2** 空态，不将「全年无数据」展示为全 0 汇总。

### 2.5 模块边界

- **只读分析页**：不提供成果台账的新增、编辑、删除；维护入口跳转至「共同富裕成果」模块（若产品配置菜单链接）。
- **权限独立**：本模块查询权限与成果台账权限可分开配置（见 **§8**）。

---

## 3. 功能范围

- 按**统计年份**筛选并刷新整页数据  
- **共富成果年度总览**：展示 12 项指标在该年的汇总结果（口径见 **§2.4**）  
- **集体经济收入**：按月横向柱状图  
- **就业带动**：按月折线图，双系列（带动就业人数、新增就业岗位）  
- **环境治理**：按月柱状图（环境治理项目数）  
- **绿化建设**：按月折线图（新增绿化面积）  
- **文化传承**：按月柱状图（文化传承人数）  
- **民族团结**：按月堆叠柱状图，双系列（民族融合项目数、民族团结活动数）  
- 无数据、部分月份缺失、切换年份时的提示与空态  

---

## 4. 业务流程概览

```mermaid
flowchart TD
    A[进入年度报告页] --> B{选择统计年份}
    B --> C[加载该年共同富裕成果月度数据]
    C --> D{是否有记录}
    D -->|否| E[展示空态与引导]
    D -->|是| F[计算年度汇总]
    F --> G[渲染总览指标]
    F --> H[渲染各主题图表]
    B --> C
    E --> B
```

1. **进入**：用户打开「共同富裕成果年度报告」菜单，系统按默认年份（当前年）请求并展示。  
2. **筛选**：用户变更统计年份后，**整页**总览与各图表同步刷新，不得出现总览与图表年份不一致。  
3. **展示**：有数据则按 **§5** 渲染；无数据则 **§7.2** 空态。  
4. **维护**：若需补录或修正某月数据，用户前往「共同富裕成果」台账操作后，返回本页**重新选择年份或刷新**即可看到更新（刷新方式与项目列表惯例一致，如重新进入页、刷新按钮等）。

---

## 5. 详细功能需求

### 5.1 按年查询与筛选

| 项 | 规则 |
| --- | --- |
| 筛选控件 | **统计年份**；年份选择器，可选范围宜覆盖台账已有数据年份及当前年前后若干年（具体上下限与产品一致） |
| 默认值 | 进入页面时默认 **当前自然年** |
| 触发方式 | 变更年份后**自动**重新加载本页全部区块（总览 + 全部图表）；宜有加载中状态，避免重复提交 |
| 数据范围 | 仅包含「共同富裕成果」中 `统计范围` 年份部分等于所选年份的记录 |
| 排序依据 | 按月汇总时，月份顺序为 **1→12**；同月仅允许一条记录（与成果台账唯一性一致） |

**说明：** 本模块**不支持**按月份区间、按指标区间等二次筛选；若后续需要，须单独修订。

---

### 5.2 共富成果年度总览

在页面显著区域（原型中「共富成果」区块）展示选定年份的 **12 项指标**汇总值：

| 展示要求 | 说明 |
| --- | --- |
| 指标项 | 与 **§2.3** 一致，名称与单位须与成果台账、双语规范一致 |
| 数值格式 | 金额、面积保留约定小数位；整数类不带小数；比率类与台账一致（小数或百分比，全站统一） |
| 汇总口径 | 遵循 **§2.4**；建议在区块标题或 Tooltip 注明「加总」或「月均」 |
| 缺数据 | 该年**无任何**月度记录时，总览区进入 **§7.2** 空态（与「缺月按 0」区分：后者指年内**至少有一条**台账时的未登记月份） |
| 部分月份缺失 | 按 **§2.4**：缺月按 **0** 参与全年加总或 12 个月平均；帮助文案中注明口径 |

---

### 5.3 图表通用规则

适用于 **§5.4～5.9** 全部图表：

| 项 | 规则 |
| --- | --- |
| 标题 | 各图表具备明确标题（与草稿主题一致：集体经济收入、就业带动、环境治理等） |
| 横轴 | **月份**（1～该年最大统计月）；标签格式与原型一致（如 `1月`…`N月`） |
| 纵轴 | 带单位或图例说明（万元、人、个、亩、% 等） |
| 缺月 | 该月无台账记录：柱状图、折线图、堆叠柱状图**均显示为 0**（柱高为 0、折线落点为 0）；**12 个月均须渲染**，不得省略横轴刻度 |
| 单点数据 | 仅 1 个月有数据时，图表仍须正常渲染，不得报错 |
| 交互 | 至少支持 **Tooltip** 展示该月具体数值与单位；是否支持图例开关、数据缩放与原型一致 |
| 响应式 | 窄屏下图表可横向滚动或等比缩放，须保证坐标轴与图例可读 |

---

### 5.4 集体经济收入

| 项 | 规则 |
| --- | --- |
| 图表类型 | **横向柱状图**（草稿：按月统计，横向柱状） |
| 数据系列 | 单月「集体经济收入」（万元） |
| 数据含义 | 各月值为该月成果台账中**当月登记值**，非累计 |

---

### 5.5 就业带动

| 项 | 规则 |
| --- | --- |
| 图表类型 | **折线图** |
| 数据系列 | **两个维度**：① 带动就业人数（人）；② 新增就业岗位（个） |
| 图例 | 须区分两条系列，颜色与图例文案与原型一致 |
| 数据含义 | 各月对应该月台账中的两项指标，不做跨年累计 |

---

### 5.6 环境治理

| 项 | 规则 |
| --- | --- |
| 图表类型 | **柱状图**（竖向，除非原型另有约定） |
| 数据系列 | 单月「环境治理项目数」（个） |

---

### 5.7 绿化建设

| 项 | 规则 |
| --- | --- |
| 图表类型 | **折线图** |
| 数据系列 | 单月「新增绿化面积」（亩） |
| 小数 | 与台账一致，展示保留约定小数位 |

---

### 5.8 文化传承

| 项 | 规则 |
| --- | --- |
| 图表类型 | **柱状图** |
| 数据系列 | 单月「文化传承人数」（人） |

---

### 5.9 民族团结

| 项 | 规则 |
| --- | --- |
| 图表类型 | **堆叠柱状图** |
| 数据系列 | **两个维度**：① 民族融合项目数（个）；② 民族团结活动数（个） |
| 堆叠含义 | 同月两系列在同一柱上堆叠，柱高为两值之和；Tooltip 须分别展示两项 |
| 命名 | 界面文案与《共同富裕成果》一致（「民族融合项目数」「民族团结活动数」）；草稿中「民族融合案例」视为同一指标 |

---

### 5.10 页面布局与加载顺序

- 布局顺序建议与原型一致：顶部**年份筛选** → **共富成果总览** → 各主题图表区块（顺序可与原型 `共同富裕成果年度报告.png` 对齐）。  
- 加载失败时：总览与图表均提示失败，并提供重试；不得仅部分区块静默失败。  
- 切换年份时：宜统一 Loading，避免旧年数据与新选年份图表短暂并存（闪烁）。

---

## 6. 数据依赖与一致性

| 场景 | 规则 |
| --- | --- |
| 台账新增/修改/删除 | 年度报告**不实时推送**；用户刷新页面或重新进入后反映最新数据 |
| 同月唯一 | 依赖成果台账「同一统计范围不可重复」；若台账允许多条，本模块须约定取数规则（默认取**最新创建**一条）并修订本文档 |
| 比率展示 | 与成果台账列表、详情百分比/小数规则**一致** |
| 跨年数据 | 仅展示所选年内月份；不得将相邻年份记录纳入当前年图表 |

---

## 7. 异常、空态与提示

### 7.1 错误提示

- 加载失败：统一提示（如「数据加载失败，请稍后重试」），可区分网络错误与服务端错误（若项目有统一规范）。  
- 年份非法或超出可选范围：由年份控件约束，不应提交无效年份。

### 7.2 空态

| 条件 | 表现 |
| --- | --- |
| 选定年份**无任何**成果记录 | 页面级或区块级空态；文案宜引导用户前往「共同富裕成果」补录数据 |
| 某图表对应指标全年无有效值 | 该图表单独空态或「暂无数据」，不影响其他图表 |
| 仅部分月份有数据 | 有数据月份展示台账值，无数据月份按 **0** 展示，不视为错误 |

### 7.3 边界情况

- **闰年 / 2 月**：统计范围仍为 `YYYY-MM`，不单独处理 2 月 29 日。  
- **未来年份**：允许选择但通常无数据，走空态。  
- **极大数值**：坐标轴刻度自动适配，避免标签重叠（实现阶段与图表库能力相关，需求层要求「可读」即可）。

---

## 8. 权限与非功能需求

| 类别 | 建议 |
| --- | --- |
| 权限 | 独立菜单「共同富裕成果年度报告」；至少配置**查询**权限；本模块无新增/修改/删除按钮 |
| 审计 | 访问日志可按项目规范记录（年份、用户、时间）；图表数据变更审计落在成果台账模块 |
| 性能 | 单年最多 12 条月度记录，数据量小；仍宜一次请求返回汇总与分月序列，避免 7 次以上串行请求 |
| 双语 | 指标名称、单位、空态文案与 `commonProsperity` 等业务文案包一致（汉语 + 藏文） |
| 打印/导出 | 若需导出 PDF 或图片，作为迭代项单列，不在初版范围 |

---

## 9. 修订说明（相对草稿）

| 草稿条目 | 优化处理 |
| --- | --- |
| 仅罗列 8 条功能点 | 拆为 **§2 术语**、**§5 分节**、**§6 数据依赖**、**§7 异常空态** |
| 「按年统计查询」未说明数据来源 | 明确数据来自**共同富裕成果**月度台账，本模块只读 |
| 12 项指标未写单位与汇总口径 | **§2.3、§2.4** 补充加总 / 月均规则 |
| 各图表仅写类型 | **§5.3** 统一缺月、坐标轴、Tooltip；**§5.4～5.9** 逐图约定系列 |
| 缺月展示未定论 | **产品定论：缺月统一按 0**（图表 + 年度汇总，见 **§2.2、§2.4、§5.3**） |
| 就业、民族团结「2 个维度」 | 明确对应台账字段名称，避免与「案例」歧义 |
| 无流程说明 | 增补 **§4** 流程图与切换年份刷新规则 |
| 未写空态与权限 | **§7、§8** 补充 |
| 未涉及库表与接口 | 全文仅功能需求，技术实现见后续技术方案 |

---

## 10. 与相关文档关系

| 文档 | 关系 |
| --- | --- |
| 《共同富裕成果功能需求》 | 指标定义、月度登记、按年筛列表的唯一数据源 |
| `共同富裕成果年度报告-草稿.md` | 初稿功能列表 |
| `共同富裕成果年度报告.png` | UI 布局与图表类型参考 |
| 《共同富裕成果年度报告技术方案》（待编） | 接口、库表、图表组件选型 |