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

共同富裕成果 — 技术方案

依据：同目录 共同富裕成果功能需求.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）

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]
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