# 共同富裕成果 — 技术方案

> 依据：同目录 `共同富裕成果功能需求.md`。本模块为**月度成果台账 CRUD**，无发布/下架；本文给出库表与 HTTP 接口约定。

---

## 1. 技术架构

| 项 | 说明 |
| --- | --- |
| **后端** | RuoYi **v3.9.2**（**springboot2** 分支）：JDK 8、Spring Boot 2.x、Spring MVC、MyBatis、Druid |
| **数据库** | MySQL **5.7.39**，InnoDB，`utf8mb4` |
| **前端** | 若依 Vue2；统计范围用 **月份**选择器，提交 `YYYY-MM` |
| **代码包** | `com.ruoyi.web.modules.commonprosperity`（建议，与「共同富裕项目」同包） |

**分层**：`Controller`（校验、权限、`AjaxResult` / `TableDataInfo`）→ `Service`（字段校验、统计范围唯一性）→ `Mapper`/XML → `domain`。

**业务特征（摘要）**

- 新增 / 修改 / 删除 / 查询**无发布状态**前置。
- 列表默认按 **`stat_period` 倒序**，其次 `create_time` 倒序。
- **`stat_period`（YYYY-MM）** 在适用范围（如租户）内**唯一**；新增/修改冲突时业务失败。

---

## 2. 数据库设计

### 2.1 表 `biz_common_prosperity_achievement`（共同富裕成果）

| 字段 | 类型 | 非空 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| `id` | `bigint(20)` | Y | 自增 | 主键 |
| `stat_period` | `char(7)` | Y | — | 统计范围，`YYYY-MM` |
| `collective_economy_income` | `decimal(14,2)` | Y | — | 集体经济收入（**万元**，≥0） |
| `employment_driven_count` | `int(11)` | Y | `0` | 带动就业人数（人，≥0 整数） |
| `new_job_positions` | `int(11)` | Y | `0` | 新增就业岗位（个，≥0 整数） |
| `env_project_count` | `int(11)` | Y | `0` | 环境治理项目数（个） |
| `new_green_area` | `decimal(12,2)` | Y | — | 新增绿化面积（亩，≥0） |
| `cultural_heritage_count` | `int(11)` | Y | `0` | 文化传承人数（人） |
| `ethnic_integration_project_count` | `int(11)` | Y | `0` | 民族融合项目数（个） |
| `ethnic_unity_activity_count` | `int(11)` | Y | `0` | 民族团结活动数（个） |
| `digital_platform_usage_rate` | `decimal(8,4)` | Y | — | 数字平台使用率（0～1） |
| `regional_public_brand_count` | `int(11)` | Y | `0` | 区域公共品牌数（个） |
| `brand_premium_rate` | `decimal(8,4)` | Y | — | 品牌产品溢价率（0～1） |
| `create_by` / `create_time` / `update_by` / `update_time` | 若依惯例 | — | — | 审计 |
| `remark` | `varchar(500)` | N | NULL | 备注 |

**索引**：`PRIMARY KEY (id)`；`UNIQUE KEY uk_stat_period (stat_period)`；`KEY idx_stat_period (stat_period)`（列表排序/按年筛选）。

> 若后续多租户：将唯一约束改为 `UNIQUE (tenant_id, stat_period)`，并增加 `tenant_id` 字段。

### 2.2 DDL（MySQL 5.7）

```sql
CREATE TABLE `biz_common_prosperity_achievement` (
  `id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT '主键',
  `stat_period` char(7) NOT NULL COMMENT '统计范围YYYY-MM',
  `collective_economy_income` decimal(14,2) NOT NULL COMMENT '集体经济收入(万元)',
  `employment_driven_count` int(11) NOT NULL DEFAULT '0' COMMENT '带动就业人数',
  `new_job_positions` int(11) NOT NULL DEFAULT '0' COMMENT '新增就业岗位',
  `env_project_count` int(11) NOT NULL DEFAULT '0' COMMENT '环境治理项目数',
  `new_green_area` decimal(12,2) NOT NULL COMMENT '新增绿化面积(亩)',
  `cultural_heritage_count` int(11) NOT NULL DEFAULT '0' COMMENT '文化传承人数',
  `ethnic_integration_project_count` int(11) NOT NULL DEFAULT '0' COMMENT '民族融合项目数',
  `ethnic_unity_activity_count` int(11) NOT NULL DEFAULT '0' COMMENT '民族团结活动数',
  `digital_platform_usage_rate` decimal(8,4) NOT NULL COMMENT '数字平台使用率0-1',
  `regional_public_brand_count` int(11) NOT NULL DEFAULT '0' COMMENT '区域公共品牌数',
  `brand_premium_rate` decimal(8,4) NOT NULL COMMENT '品牌产品溢价率0-1',
  `create_by` varchar(64) DEFAULT '' COMMENT '创建者',
  `create_time` datetime DEFAULT NULL COMMENT '创建时间',
  `update_by` varchar(64) DEFAULT '' COMMENT '更新者',
  `update_time` datetime DEFAULT NULL COMMENT '更新时间',
  `remark` varchar(500) DEFAULT NULL COMMENT '备注',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_stat_period` (`stat_period`),
  KEY `idx_stat_period` (`stat_period`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='共同富裕成果';
```

### 2.3 字段与需求对照

| 需求名称 | 库字段 | API 驼峰 |
| --- | --- | --- |
| 统计范围 | `stat_period` | `statPeriod` |
| 集体经济收入 | `collective_economy_income` | `collectiveEconomyIncome` |
| 带动就业人数 | `employment_driven_count` | `employmentDrivenCount` |
| 新增就业岗位 | `new_job_positions` | `newJobPositions` |
| 环境治理项目数 | `env_project_count` | `envProjectCount` |
| 新增绿化面积 | `new_green_area` | `newGreenArea` |
| 文化传承人数 | `cultural_heritage_count` | `culturalHeritageCount` |
| 民族融合项目数 | `ethnic_integration_project_count` | `ethnicIntegrationProjectCount` |
| 民族团结活动数 | `ethnic_unity_activity_count` | `ethnicUnityActivityCount` |
| 数字平台使用率 | `digital_platform_usage_rate` | `digitalPlatformUsageRate` |
| 区域公共品牌数 | `regional_public_brand_count` | `regionalPublicBrandCount` |
| 品牌产品溢价率 | `brand_premium_rate` | `brandPremiumRate` |

---

## 3. 接口设计

**统一响应**：`AjaxResult`（`code` / `msg` / `data`）或分页 `TableDataInfo`（`rows`、`total`）。

**权限标识（示例）**：`commonProsperity:achievement:list|query|add|edit|remove|export`

**Base Path（示例）**：`/commonProsperity/achievement`

| # | 说明 | Method | URI | 权限 | 要点 |
| --- | --- | --- | --- | --- | --- |
| 3.1 | 分页列表 | GET | `/commonProsperity/achievement/list` | `commonProsperity:achievement:list` | Query **3.1.1**；排序 `stat_period DESC, create_time DESC, id DESC` |
| 3.2 | 详情 | GET | `/commonProsperity/achievement/{id}` | `commonProsperity:achievement:query` | 全字段 |
| 3.3 | 新增 | POST | `/commonProsperity/achievement` | `commonProsperity:achievement:add` | Body **3.3.1**；校验 `stat_period` 唯一 |
| 3.4 | 修改 | PUT | `/commonProsperity/achievement` | `commonProsperity:achievement:edit` | Body 含 `id`；改 `statPeriod` 时排除自身后查重 |
| 3.5 | 删除 | DELETE | `/commonProsperity/achievement/{ids}` | `commonProsperity:achievement:remove` | 支持逗号分隔批量 id |
| 3.6 | 导出（可选） | POST | `/commonProsperity/achievement/export` | `commonProsperity:achievement:export` | 与列表同筛选条件 |

#### 3.1.1 列表 Query 参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `pageNum` / `pageSize` | int | N | 默认 `1` / `20` |
| `statYear` | int / string | N | 统计年份，如 `2026`；匹配 `stat_period` 以该年开头（`2026-01`～`2026-12`）；空则不过滤 |

**按年筛选（SQL 示例）**：`stat_period LIKE CONCAT(#{statYear}, '-%')` 或 `LEFT(stat_period, 4) = #{statYear}`。

#### 3.3.1 新增 / 修改 Body（JSON，驼峰）

| 字段 | 必填 | 说明 |
| --- | --- | --- |
| `id` | 修改 Y | 主键 |
| `statPeriod` | Y | `YYYY-MM`，正则 `^\d{4}-(0[1-9]|1[0-2])$` |
| `collectiveEconomyIncome` | Y | ≥0，最多 2 位小数 |
| `employmentDrivenCount` | Y | ≥0 整数 |
| `newJobPositions` | Y | ≥0 整数 |
| `envProjectCount` | Y | ≥0 整数 |
| `newGreenArea` | Y | ≥0，最多 2 位小数 |
| `culturalHeritageCount` | Y | ≥0 整数 |
| `ethnicIntegrationProjectCount` | Y | ≥0 整数 |
| `ethnicUnityActivityCount` | Y | ≥0 整数 |
| `digitalPlatformUsageRate` | Y | ≥0 且 ≤1 |
| `regionalPublicBrandCount` | Y | ≥0 整数 |
| `brandPremiumRate` | Y | ≥0 且 ≤1 |
| `remark` | N | 备注 |

**列表行字段（示例）**：`id`、`statPeriod`、`collectiveEconomyIncome`、`employmentDrivenCount`、`newJobPositions`、`envProjectCount`、`newGreenArea`、`digitalPlatformUsageRate`、`regionalPublicBrandCount`、`createTime`。

### 3.4 服务端校验（摘要）

| 项 | 规则 |
| --- | --- |
| `statPeriod` | 非空；格式 `YYYY-MM`；唯一（新增 / 修改排除当前 id） |
| 金额、面积 | ≥0；小数位与库表一致 |
| 整数项 | ≥0；无小数部分 |
| 比率项 | `digitalPlatformUsageRate`、`brandPremiumRate` ∈ [0, 1] |
| 删除 | 无状态限制；物理删或逻辑删按项目惯例 |

---

## 4. 菜单与权限 SQL（示例）

| 类型 | 名称 | 权限标识 |
| --- | --- | --- |
| 目录 | 共同富裕 | — |
| 菜单 | 共同富裕成果 | `commonProsperity:achievement:list` |
| 按钮 | 查询 | `commonProsperity:achievement:query` |
| 按钮 | 新增 | `commonProsperity:achievement:add` |
| 按钮 | 修改 | `commonProsperity:achievement:edit` |
| 按钮 | 删除 | `commonProsperity:achievement:remove` |
| 按钮 | 导出 | `commonProsperity:achievement:export` |

组件路径建议：`commonProsperity/achievement/index`；API 文件 `ruoyi-ui/src/api/commonProsperity/achievement.js`。

---

## 5. 交付清单

- [ ] `biz_common_prosperity_achievement` DDL、菜单权限 SQL（`sql/biz_common_prosperity_achievement.sql`）
- [ ] `BizCommonProsperityAchievement` Domain / Mapper / Service / Controller
- [ ] 前端：按 `statYear` 筛选、月份选择 `statPeriod`、比率 0～1 校验
- [ ] 用例：同月重复、比率越界、整数含小数、按年筛选、CRUD

---

## 6. 修订记录

| 版本 | 说明 |
| --- | --- |
| 1.0 | 初稿：对齐功能需求；单表台账；`stat_period` 唯一；Base Path `/commonProsperity/achievement` |