# 共同富裕成果 — 功能需求

## 1. 文档说明

| 项 | 说明 |
| --- | --- |
| 模块名称 | 共同富裕成果 |
| 目标 | 按月度统计范围录入、查询、维护共富成效指标数据，支撑成果台账管理与按年汇总查阅 |
| 关联系统 | 业务后台；大屏、报表或移动端可按产品约定引用已维护数据（见 **§8**） |
| 修订依据 | 同目录 `共同富裕成果-草稿.md` |

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

---

## 2. 术语与说明

### 2.1 统计范围（月度）

- 表示本条成果数据所对应的**统计月份**，格式 **YYYY-MM**（如 `2026-05`）。
- 一条记录对应**一个统计月份**的一个统计快照；同一统计月份在适用范围（如租户 / 组织）内**不得重复**登记（若业务允许多条须单独评审并写入 **§5.1**）。

### 2.2 指标字段类型（摘要）

| 类型 | 适用字段 | 规则概要 |
| --- | --- | --- |
| 金额（万元） | 集体经济收入 | ≥ 0；小数位数与项目金额规范一致（建议最多 **2** 位） |
| 非负整数 | 人数、岗位数、项目数、活动数、品牌数等 | ≥ 0；须为**整数**（无小数） |
| 非负数值（可含小数） | 新增绿化面积（亩） | ≥ 0；小数位数建议最多 **2** 位 |
| 比率（0～1） | 数字平台使用率、品牌产品溢价率 | ≥ 0 且 ≤ **1**；表示比例（如 `0.85` 表示 85%）；展示时可按产品约定换算为百分比 |

### 2.3 记录说明

本模块为**成果台账类数据**，单条记录表示某一统计月份的共富成效指标集合；**不设**发布/下架等上架状态。新建成功后即可被查询、修改、删除（在权限允许前提下）。

---

## 3. 功能范围

- 共富成果的新增、修改、删除、分页列表查询、详情查看
- 统计范围（月度）及各项成效指标的录入与校验
- 按**统计年份**筛选列表
- 面向使用方的业务错误与校验提示（见第 **7** 章）

---

## 4. 业务流程概览

```mermaid
flowchart LR
    A[新增月度成果] --> B[列表查询/按年筛选]
    B --> C[查看详情]
    B --> D[修改记录]
    B --> E[删除记录]
    D --> B
    E --> B
```

1. **登记**：选择统计范围（月份），录入各项必填指标 → 形成一条月度成果记录。  
2. **查询**：按统计年份筛选，分页浏览台账；默认可按统计范围倒序（最近月份在前）。  
3. **维护**：对已有记录进行修改（全字段可改，校验规则与新增一致）。  
4. **查阅**：查看单条记录全部指标字段；列表支持进入详情。  
5. **删除**：删除整条记录（无附件联动）；删除前宜二次确认。

---

## 5. 详细功能需求

### 5.1 新增共富成果

| 字段 | 规则 |
| --- | --- |
| 统计范围 | **必填**；格式 **YYYY-MM**；表示本条数据所属统计月份 |
| 集体经济收入 | **必填**；单位 **万元**；须为 **≥ 0** 的数值；建议最多 **2** 位小数 |
| 带动就业人数 | **必填**；单位 **人**；须为 **≥ 0** 的**整数** |
| 新增就业岗位 | **必填**；单位 **个**；须为 **≥ 0** 的**整数** |
| 环境治理项目数 | **必填**；单位 **个**；须为 **≥ 0** 的**整数** |
| 新增绿化面积 | **必填**；单位 **亩**；须为 **≥ 0** 的数值；建议最多 **2** 位小数 |
| 文化传承人数 | **必填**；单位 **人**；须为 **≥ 0** 的**整数** |
| 民族融合项目数 | **必填**；单位 **个**；须为 **≥ 0** 的**整数** |
| 民族团结活动数 | **必填**；单位 **个**；须为 **≥ 0** 的**整数** |
| 数字平台使用率 | **必填**；须为 **≥ 0 且 ≤ 1** 的数值；建议最多 **4** 位小数（或按产品展示精度约定） |
| 区域公共品牌数 | **必填**；单位 **个**；须为 **≥ 0** 的**整数** |
| 品牌产品溢价率 | **必填**；须为 **≥ 0 且 ≤ 1** 的数值；建议最多 **4** 位小数 |

**必填字段汇总：** 上表全部字段均为必填。

**校验：**

- 统计范围格式非法（非 `YYYY-MM`）时须拒绝保存并提示。
- 整数类字段含小数、为负数时须拒绝并给出**可区分**提示。
- 比率类字段 **> 1** 或 **< 0** 时须拒绝（如「使用率须在 0～1 之间」）。
- 若约定「同一统计范围不可重复」，保存时须校验唯一性；冲突时提示（如「该月份成果已存在」）且不变更已有记录。

**保存结果：** 新建成功后记录可被列表查询与详情查看；无发布状态字段。

---

### 5.2 查询共富成果列表

- **统计年份：** 对「统计范围」中的**年份**部分进行**精确**匹配（如选择 `2026` 则匹配 `2026-01`～`2026-12`）；未选择年份时不按年份过滤。
- **分页：** 支持分页；默认 **每页 20 条**，默认首页为第一页；单页条数上限与项目列表通用规范一致（若有）。
- **排序：** 默认按 **统计范围（月份）倒序**（最近月份在前）；相同月份按 **创建时间倒序**（若有）。

**列表宜展示：** 统计范围、集体经济收入、带动就业人数、新增就业岗位、环境治理项目数、新增绿化面积、数字平台使用率、区域公共品牌数、创建时间，以及查看 / 编辑 / 删除等操作入口。

> 列表列较多时，可按 UI 设计**固定核心列**、其余在详情中展示；以产品原型为准。

---

### 5.3 修改共富成果

- **可修改项：** 统计范围及 **§5.1** 中全部指标字段（**全部字段**均可修改）。
- **保存约束：** 修改提交时须重新满足 **§5.1** 全部校验规则；**必填字段**不得为空。
- **统计范围变更：** 若修改后的统计范围与另一条记录冲突（唯一性约定下），须拒绝保存并提示。
- **说明：** 本模块无「已锁定不可改」状态；若后续引入审批流或归档只读，须单独修订本文档。

---

### 5.4 删除共富成果

- **允许删除：** 具备删除权限的用户可对单条或多条记录执行删除（是否支持批量删除与项目列表惯例一致）。
- **删除后果：** 删除后该条记录不再出现在列表与统计汇总中；**无**关联附件清理要求。
- **确认：** 删除前宜弹出确认提示，避免误删。

---

### 5.5 查看共富成果详情

- **展示内容：** 统计范围；集体经济收入（万元）；带动就业人数；新增就业岗位；环境治理项目数；新增绿化面积（亩）；文化传承人数；民族融合项目数；民族团结活动数；数字平台使用率；区域公共品牌数；品牌产品溢价率。
- **展示格式：** 比率类字段可按产品约定显示为**小数**（如 `0.85`）或**百分比**（如 `85%`），前后台须一致；金额、面积保留约定小数位。
- **审计信息：** 宜展示创建人、创建时间、最后修改人、最后修改时间（若系统有审计字段）。
- **交互：** 具备编辑权限的用户可从详情进入编辑流程（见 **§5.3**）。

---

## 6. 操作权限矩阵（汇总）

本模块无发布状态约束；在**已授权**前提下：

| 操作 | 说明 |
| --- | --- |
| 查看 | 具备查询权限即可 |
| 新增 | 具备新增权限即可 |
| 修改 | 具备修改权限即可；无记录状态限制 |
| 删除 | 具备删除权限即可；删除前确认 |

菜单与按钮级权限（查询、新增、修改、删除、导出等）按项目角色配置，具体标识在技术方案或权限配置文档中定义。

---

## 7. 错误与提示约定

- 业务与校验错误宜采用项目统一的 **`code`、`msg`、`data`** 结构呈现，便于前端统一处理（不涉及具体协议与路径设计）。
- 常见提示宜可区分，例如：
  - 必填项缺失、统计范围格式不符；
  - 数值为负、整数项含小数、比率超出 0～1；
  - 统计范围重复；
  - 删除确认取消与删除失败原因。

---

## 8. 非功能需求（建议）

| 类别 | 建议 |
| --- | --- |
| 权限 | 菜单与按钮级权限：查询、新增、修改、删除；导出（若需要）是否分角色 |
| 审计 | 新增、修改、删除记操作日志；关键指标变更可追溯 |
| 性能 | 按统计年份筛选满足后台通用体验；数据量大时考虑按年份分区或索引策略（实现阶段） |
| 汇总展示 | 若大屏需按年汇总，须约定是「取各月加总」还是「取最新月」等口径，避免与台账明细混淆 |
| 双语 | 后台字段标签与提示与项目 i18n 规范一致（汉语 + 藏文） |

---

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

| 草稿问题 | 优化处理 |
| --- | --- |
| 第 6 条缺失（序号从 5 跳到 7） | 补全删除、查看等章节编号与内容 |
| 「修改：所有均可修改」无约束说明 | 明确台账类全字段可改；补充与新增一致的校验 |
| 统计范围与查询「统计年份」关系不清 | **§2.1、§5.2** 明确：`YYYY-MM` 登记，按年份 `YYYY` 筛列表 |
| 整数 / 比率 / 金额规则分散 | **§2.2、§5.1** 分类汇总；比率限定 **0～1** |
| 新增绿化面积是否整数未写 | 定为 **≥ 0 数值**，亩可保留小数（建议 2 位） |
| 同月是否可重复登记未写 | 默认**同一范围不可重复**；允许多条须评审 |
| 第 7、8 条接口与技术栈 | 错误结构保留于 **§7**；技术栈移至技术方案文档 |
| 无流程与操作矩阵 | 增补 **§4 流程图**、**§6 操作矩阵** |
| 列表展示字段未写 | **§5.2、§5.5** 补充列表/详情展示建议 |