zjrs-jeecgBoot/.docs/20260610-深度分析模块开发记录.md

深度分析模块（deepAnalysis）开发记录

开发日期：2026-06-10

一、模块概述

深度分析模块是核心业务模块之一，主要用于管理各类就业补贴/社保补贴数据的新增、编辑、列表查询、导出导入，以及对相关企业和个人发送消息通知。

模块采用 JeecgBoot 前后端分离架构：

• 后端：Spring Boot + MyBatis-Plus + AutoPoi（Excel 导入导出）+ Shiro（权限控制）
• 前端：Vue 3 + Ant Design Vue + TypeScript

---

二、后端代码结构

jeecg-boot/jeecg-boot-module/jeecg-module-zjrs/src/main/java/org/jeecg/modules/zjrs/deepAnalysis/
├── absorbDifficultSubsidy/          # 吸纳就业困难人员社保补贴（企业）
├── familyServiceAbsorbSubsidy/      # 家政服务企业吸纳就业补贴（企业）
├── familyServiceInsuranceSubsidy/   # 员工制家政服务社保补贴（企业）
├── familyServiceSubsidy/            # 家政服务企业补贴（企业）
├── flexibleEmploySubsidy/           # 灵活就业社保补贴（个人）
├── generalPostSubsidy/              # 一般性岗位补贴（企业）
├── jobInternshipSubsidy/            # 就业见习补贴（企业）
├── jobIntroductionSubsidy/          # 职业介绍补贴（企业）
├── jobSeekingSubsidy/               # 求职创业补贴（个人）
├── northRegionSubsidy/              # 粤东西北地区就业补贴（个人）
├── oneTimeAbsorbSubsidy/            # 一次性吸纳就业补贴（企业）
├── oneTimeStartupSubsidy/           # 一次性创业资助（个人）
├── povertyAlleviationSubsidy/       # 吸纳脱贫人口就业补贴（企业）
├── publicEmployServiceSubsidy/      # 公共就业服务岗位补贴（企业）
├── publicWelfarePostSubsidy/        # 公益性岗位补贴（企业）
├── ruralWelfarePostSubsidy/         # 乡村公益性岗位补贴（企业）
├── smallMicroSubsidy/               # 小微企业社保补贴（企业）
├── startupDriveEmploySubsidy/       # 创业带动就业补贴（企业）
├── startupIncubationSubsidy/        # 创业孵化补贴（企业）
├── startupRentSubsidy/              # 创业租金补贴（个人）
├── veteranAbsorbSubsidy/            # 吸纳退役军人就业补贴（企业）
└── message/                         # 公共消息模块
    ├── controller/
    │   ├── DaMessageController.java
    │   └── DaMessageTemplateController.java
    ├── entity/
    │   ├── DaMessage.java
    │   └── DaMessageTemplate.java
    ├── mapper/
    │   ├── DaMessageMapper.java
    │   └── DaMessageTemplateMapper.java
    └── service/
        ├── IDaMessageService.java / impl/DaMessageServiceImpl.java
        └── IDaMessageTemplateService.java / impl/DaMessageTemplateServiceImpl.java

2.1 每个补贴子模块的标准四层结构

每个子模块（共 21 个）均包含以下四个包：

包	文件	说明
controller/	DaXxxController.java	REST 接口，继承 JeecgController，提供 CRUD + 导出导入
entity/	DaXxx.java	MyBatis-Plus 实体，对应数据库表
mapper/	DaXxxMapper.java	MyBatis-Plus Mapper，继承 BaseMapper
service/	IDaXxxService.java + impl/DaXxxServiceImpl.java	业务接口与实现

2.2 Controller 层设计

每个 Controller 继承 JeecgController<Entity, Service>，提供以下标准 REST 接口：

接口	HTTP 方法	路径	权限标识	功能说明
分页列表查询	GET	/list	-	支持动态查询条件，返回分页数据
新增	POST	/add	deepAnalysis:xxx:add	新增一条记录
编辑	PUT/POST	/edit	deepAnalysis:xxx:edit	编辑一条记录
删除	DELETE	/delete	deepAnalysis:xxx:delete	根据 ID 删除单条记录
批量删除	DELETE	/deleteBatch	deepAnalysis:xxx:deleteBatch	批量删除多条记录
查询详情	GET	/queryById	-	根据 ID 查询单条记录
导出 Excel	GET	/exportXls	deepAnalysis:xxx:exportXls	导出数据到 Excel
导入 Excel	POST	/importExcel	deepAnalysis:xxx:importExcel	从 Excel 导入数据

Controller 关键设计点：

1. 导出时字典值→标签翻译：每个 Controller 内部定义了一个静态 Map EXPORT_DICT_FIELD_MAP，声明 entity 字段名与字典编码的映射关系（如：{declareStatus → DeclarationStatus}）。导出时调用 Service 的 translateDictFields() 方法进行内存级别的字典值替换，确保导出的 Excel 中显示的是中文标签而非字典值。

2. 权限控制：增、删、改、导出、导入操作均通过 @RequiresPermissions 注解进行权限控制，权限标识格式为 deepAnalysis:table_snake_name:action。

3. 导出字段：每个 Controller 在 exportXls 方法中定制 exportFields 字符串，精确控制 Excel 的导出列及其顺序。

2.3 Entity 层设计

每个实体类使用 MyBatis-Plus 注解：

注解	说明
@TableName("da_xxx")	对应数据库表名，前缀 da_（deepAnalysis 缩写）
@TableId(type = IdType.ASSIGN_ID)	主键使用雪花算法生成
@Excel(name = "...")	Excel 导出/导入列名标注
@JsonFormat / @DateTimeFormat	日期格式化
@Schema(description = "...")	Swagger 文档说明

每个实体均包含以下公共审计字段：

• id（主键）
• recordId（省平台备案记录ID）
• createBy / createTime（创建人/创建时间）
• updateBy / updateTime（更新人/更新时间）
• sysOrgCode（所属部门）

每个实体包含的核心业务字段：

• declareStatus（申报状态，关联字典 DeclarationStatus）
• lastNotifyTime（最近通知时间，发消息后自动记录）
• dataRefluxTime（数据回流时间）

不同补贴类型的差异化业务字段举例：

补贴类型	特有字段
企业类补贴（如吸纳就业困难人员）	unitCreditCode（统一社会信用代码）、unitName（单位名称）、qualifiedCount（符合条件人数）
个人类补贴（如求职创业）	idCard（身份证号）、fullName（姓名）、contactPhone（联系方式）、subsidyAmount（补贴金额 BigDecimal）
创业租金补贴	leaseRecordNo（租赁备案号）、monthlyRent（月租金）、subsidyRatio（补贴比例）

2.4 Service 层设计

每个补贴子模块的 Service 接口除了继承 IService<Entity>（MyBatis-Plus 通用 Service），还定义了一个自定义方法：

List<DaXxx> translateDictFields(List<DaXxx> list, Map<String, String> fieldDictMap);

实现逻辑（在 ServiceImpl 中）：

1. 从 fieldDictMap 提取所有涉及的字典编码
2. 调用 IDictionaryItemService.getDictItemsBatch() 批量查询字典数据
3. 构建 Map<字典编码, Map<值, 标签>> 快速查找结构
4. 遍历导出数据，通过 switch-case 将字段的字典值替换为中文标签

消息模块的 Service 则仅继承 IService，未定义额外方法。

2.5 消息模块（message）

消息模块独立于补贴子模块，包含两张表：

实体	表名	说明
DaMessage	da_message	消息记录，关联业务模块（bizModuleName + bizId）
DaMessageTemplate	da_message_template	消息模板

DaMessage 关键字段：

• bizModuleName：所属业务模块名称（如"吸纳就业困难人员社保补贴（企业）"）
• bizId：关联业务记录 ID
• msgTitle：消息标题
• msgContent：消息内容
• sender：发送人
• sendTime：发送时间

---

三、前端代码结构

jeecgboot-vue3/src/views/deepAnalysis/
├── absorbDifficultSubsidy/          # 每个补贴子模块的标准文件结构（共21个）
│   ├── DaAbsorbDifficultSubsidyList.vue           # 列表页
│   ├── DaAbsorbDifficultSubsidy.api.ts            # API 接口定义
│   ├── DaAbsorbDifficultSubsidy.data.ts           # 表格列定义 & 高级查询配置
│   └── components/
│       ├── DaAbsorbDifficultSubsidyModal.vue       # 新增/编辑弹窗
│       ├── DaAbsorbDifficultSubsidyForm.vue        # 表单组件
│       └── DaAbsorbDifficultSubsidyDetailModal.vue # 详情弹窗
├── ... (其他20个补贴子模块，结构同上)
└── message/                         # 消息模块
    ├── api.ts                       # 消息 API（仅 add 接口）
    └── components/
        └── SendMessageModal.vue     # 发送消息弹窗（被所有补贴模块共用）

3.1 List.vue —— 列表页

列表页是每个补贴模块的主页面，功能包括：

功能区域	说明
查询区域	支持按所属区县、单位名称（企业类）/ 所属县区（个人类）、申报状态等条件查询
表格区域	使用 Jeecg 封装的 BasicTable 组件，支持分页、列宽拖拽
操作栏	每条记录提供"查看"和"发送消息"两个操作按钮
字典翻译	通过 bodyCell 插槽，使用 getDictText() 方法展示字典的中文标签
导出功能	使用 onExportXls 方法导出 Excel
详情弹窗	点击查看时打开 DaXxxDetailModal
发送消息弹窗	点击发送消息时打开 SendMessageModal（公共组件）

发送消息逻辑流程：

1. 用户在列表页点击"发送消息"
2. 打开 SendMessageModal，自动传入 bizModuleName（当前模块名称）和 bizId（记录ID）
3. 用户在弹窗中填写消息标题、内容，发送人自动取当前登录用户姓名，发送时间自动取当前时间
4. 点击发送后，调用消息模块的 add API 保存到 da_message 表
5. 回调更新：发送成功后，前端自动调用当前模块的 saveOrUpdate API，将该业务记录的 lastNotifyTime 更新为当前时间

3.2 api.ts —— API 接口定义

每个补贴子模块的 API 文件定义统一的接口枚举和请求方法：

方法	接口路径	功能
list()	/deepAnalysis/daXxx/list	分页列表查询
saveOrUpdate()	/deepAnalysis/daXxx/add 或 /edit	新增或编辑（根据是否传入 id 判断）
deleteOne()	/deepAnalysis/daXxx/delete	删除单条
batchDelete()	/deepAnalysis/daXxx/deleteBatch	批量删除（带确认弹窗）
queryById()	/deepAnalysis/daXxx/queryById	通过 ID 查询详情
getExportUrl	/deepAnalysis/daXxx/exportXls	导出 Excel URL
getImportUrl	/deepAnalysis/daXxx/importExcel	导入 Excel URL

3.3 data.ts —— 数据配置

定义两个核心配置：

1. columns（表格列配置）：指定表格每列的标题、对齐方式、宽度、数据字段名
2. superQuerySchema（高级查询配置）：每个字段的查询类型（text/number/date）、排序

3.4 Modal.vue —— 新增/编辑弹窗

• 全屏弹窗（:fullscreen="true"）
• 包含确认/取消按钮
• 内部调用 DaXxxForm.vue 表单组件
• 通过 defineExpose 暴露 add()、edit() 方法

3.5 Form.vue —— 表单组件

• 使用 Ant Design Vue 的 a-form 组件
• 通过 useForm 进行表单校验
• 新增和编辑复用同一个表单，根据是否传入 id 区分
• 提交前进行表单验证，失败时自动滚动到第一个错误字段

3.6 DetailModal.vue —— 详情弹窗

• 宽度 1000px 的弹窗
• 使用 a-descriptions 组件以两列布局展示详情
• 通过 queryById API 获取完整数据
• 字典字段（如申报状态）通过 getDictText() 展示中文标签

3.7 SendMessageModal.vue —— 发送消息弹窗（公共组件）

• 位于 message/components/ 下，被所有补贴列表页复用
• 表单字段：消息标题、消息内容、发送人（禁用，自动填充）、发送时间（禁用，自动填充）
• 发送人自动取 userStore.userInfo.realname
• 发送成功后通过 emit('success') 通知父组件更新 lastNotifyTime

---

四、涉及的主要文件清单

后端文件（Java）

文件路径（相对于 jeecg-boot/jeecg-boot-module/jeecg-module-zjrs/src/main/java/org/jeecg/modules/zjrs/）	操作说明
deepAnalysis/absorbDifficultSubsidy/controller/DaAbsorbDifficultSubsidyController.java	吸纳就业困难人员社保补贴 Controller
deepAnalysis/absorbDifficultSubsidy/entity/DaAbsorbDifficultSubsidy.java	对应数据库表 da_absorb_difficult_subsidy 的实体
deepAnalysis/absorbDifficultSubsidy/mapper/DaAbsorbDifficultSubsidyMapper.java	MyBatis-Plus Mapper
deepAnalysis/absorbDifficultSubsidy/service/IDaAbsorbDifficultSubsidyService.java	Service 接口，定义字典翻译方法
deepAnalysis/absorbDifficultSubsidy/service/impl/DaAbsorbDifficultSubsidyServiceImpl.java	Service 实现，含字典值→标签翻译逻辑
deepAnalysis/familyServiceAbsorbSubsidy/*	家政服务企业吸纳就业补贴（结构同上）
deepAnalysis/familyServiceInsuranceSubsidy/*	员工制家政服务社保补贴（结构同上）
deepAnalysis/familyServiceSubsidy/*	家政服务企业补贴（结构同上）
deepAnalysis/flexibleEmploySubsidy/*	灵活就业社保补贴（结构同上）
deepAnalysis/generalPostSubsidy/*	一般性岗位补贴（结构同上）
deepAnalysis/jobInternshipSubsidy/*	就业见习补贴（结构同上）
deepAnalysis/jobIntroductionSubsidy/*	职业介绍补贴（结构同上）
deepAnalysis/jobSeekingSubsidy/*	求职创业补贴（结构同上）
deepAnalysis/northRegionSubsidy/*	粤东西北地区就业补贴（结构同上）
deepAnalysis/oneTimeAbsorbSubsidy/*	一次性吸纳就业补贴（结构同上）
deepAnalysis/oneTimeStartupSubsidy/*	一次性创业资助（结构同上）
deepAnalysis/povertyAlleviationSubsidy/*	吸纳脱贫人口就业补贴（结构同上）
deepAnalysis/publicEmployServiceSubsidy/*	公共就业服务岗位补贴（结构同上）
deepAnalysis/publicWelfarePostSubsidy/*	公益性岗位补贴（结构同上）
deepAnalysis/ruralWelfarePostSubsidy/*	乡村公益性岗位补贴（结构同上）
deepAnalysis/smallMicroSubsidy/*	小微企业社保补贴（结构同上）
deepAnalysis/startupDriveEmploySubsidy/*	创业带动就业补贴（结构同上）
deepAnalysis/startupIncubationSubsidy/*	创业孵化补贴（结构同上）
deepAnalysis/startupRentSubsidy/*	创业租金补贴（结构同上）
deepAnalysis/veteranAbsorbSubsidy/*	吸纳退役军人就业补贴（结构同上）
deepAnalysis/message/controller/DaMessageController.java	公共消息表 Controller（CRUD + Excel）
deepAnalysis/message/controller/DaMessageTemplateController.java	消息模版表 Controller（CRUD + Excel + 权限控制）
deepAnalysis/message/entity/DaMessage.java	对应数据库表 da_message 的实体
deepAnalysis/message/entity/DaMessageTemplate.java	对应数据库表 da_message_template 的实体
deepAnalysis/message/mapper/DaMessageMapper.java	消息表 Mapper
deepAnalysis/message/mapper/DaMessageTemplateMapper.java	消息模版表 Mapper
deepAnalysis/message/service/IDaMessageService.java	消息 Service 接口
deepAnalysis/message/service/IDaMessageTemplateService.java	消息模版 Service 接口
deepAnalysis/message/service/impl/DaMessageServiceImpl.java	消息 Service 实现
deepAnalysis/message/service/impl/DaMessageTemplateServiceImpl.java	消息模版 Service 实现

前端文件（Vue3 + TypeScript）

文件路径（相对于 jeecgboot-vue3/src/views/）	操作说明
deepAnalysis/absorbDifficultSubsidy/DaAbsorbDifficultSubsidyList.vue	列表页：查询、表格、详情弹窗、发送消息入口
deepAnalysis/absorbDifficultSubsidy/DaAbsorbDifficultSubsidy.api.ts	API 接口定义
deepAnalysis/absorbDifficultSubsidy/DaAbsorbDifficultSubsidy.data.ts	表格列定义 + 高级查询配置
deepAnalysis/absorbDifficultSubsidy/components/DaAbsorbDifficultSubsidyModal.vue	新增/编辑弹窗
deepAnalysis/absorbDifficultSubsidy/components/DaAbsorbDifficultSubsidyForm.vue	表单组件
deepAnalysis/absorbDifficultSubsidy/components/DaAbsorbDifficultSubsidyDetailModal.vue	详情弹窗
deepAnalysis/familyServiceAbsorbSubsidy/*	家政服务企业吸纳就业补贴（结构同上）
deepAnalysis/familyServiceInsuranceSubsidy/*	员工制家政服务社保补贴（结构同上）
deepAnalysis/familyServiceSubsidy/*	家政服务企业补贴（结构同上）
deepAnalysis/flexibleEmploySubsidy/*	灵活就业社保补贴（结构同上）
deepAnalysis/generalPostSubsidy/*	一般性岗位补贴（结构同上）
deepAnalysis/jobInternshipSubsidy/*	就业见习补贴（结构同上）
deepAnalysis/jobIntroductionSubsidy/*	职业介绍补贴（结构同上）
deepAnalysis/jobSeekingSubsidy/*	求职创业补贴（结构同上）
deepAnalysis/northRegionSubsidy/*	粤东西北地区就业补贴（结构同上）
deepAnalysis/oneTimeAbsorbSubsidy/*	一次性吸纳就业补贴（结构同上）
deepAnalysis/oneTimeStartupSubsidy/*	一次性创业资助（结构同上）
deepAnalysis/povertyAlleviationSubsidy/*	吸纳脱贫人口就业补贴（结构同上）
deepAnalysis/publicEmployServiceSubsidy/*	公共就业服务岗位补贴（结构同上）
deepAnalysis/publicWelfarePostSubsidy/*	公益性岗位补贴（结构同上）
deepAnalysis/ruralWelfarePostSubsidy/*	乡村公益性岗位补贴（结构同上）
deepAnalysis/smallMicroSubsidy/*	小微企业社保补贴（结构同上）
deepAnalysis/startupDriveEmploySubsidy/*	创业带动就业补贴（结构同上）
deepAnalysis/startupIncubationSubsidy/*	创业孵化补贴（结构同上）
deepAnalysis/startupRentSubsidy/*	创业租金补贴（结构同上）
deepAnalysis/veteranAbsorbSubsidy/*	吸纳退役军人就业补贴（结构同上）
deepAnalysis/message/api.ts	消息模块 API（含 addMessage 接口）
deepAnalysis/message/components/SendMessageModal.vue	公共发送消息弹窗，被所有补贴列表页引用

---

五、数据库表汇总

序号	表名	说明	类型
1	da_absorb_difficult_subsidy	吸纳就业困难人员社保补贴	企业
2	da_family_service_absorb_subsidy	家政服务企业吸纳就业补贴	企业
3	da_family_service_insurance_subsidy	员工制家政服务社保补贴	企业
4	da_family_service_subsidy	家政服务企业补贴	企业
5	da_flexible_employ_subsidy	灵活就业社保补贴	个人
6	da_general_post_subsidy	一般性岗位补贴	企业
7	da_job_internship_subsidy	就业见习补贴	企业
8	da_job_introduction_subsidy	职业介绍补贴	企业
9	da_job_seeking_subsidy	求职创业补贴	个人
10	da_north_region_subsidy	粤东西北地区就业补贴	个人
11	da_one_time_absorb_subsidy	一次性吸纳就业补贴	企业
12	da_one_time_startup_subsidy	一次性创业资助	个人
13	da_poverty_alleviation_subsidy	吸纳脱贫人口就业补贴	企业
14	da_public_employ_service_subsidy	公共就业服务岗位补贴	企业
15	da_public_welfare_post_subsidy	公益性岗位补贴	企业
16	da_rural_welfare_post_subsidy	乡村公益性岗位补贴	企业
17	da_small_micro_subsidy	小微企业社保补贴	企业
18	da_startup_drive_employ_subsidy	创业带动就业补贴	企业
19	da_startup_incubation_subsidy	创业孵化补贴	企业
20	da_startup_rent_subsidy	创业租金补贴	个人
21	da_veteran_absorb_subsidy	吸纳退役军人就业补贴	企业
22	da_message	公共消息表	公共
23	da_message_template	消息模版表	公共

---

六、关键技术要点

6.1 字典翻译机制

所有补贴实体中的"申报状态"字段存储的是字典值（code），前端列表和详情展示时通过 getDictText('DeclarationStatus', value) 获取中文标签。导出 Excel 时，通过 Service 层 translateDictFields() 方法进行内存级别的批量翻译。

6.2 发送消息并更新通知时间的联动

发送消息功能实现了跨模块联动：

1. 消息发送到 da_message 表（记录业务模块名和业务 ID）
2. 发送成功后回调更新对应补贴记录的 lastNotifyTime 字段

6.3 权限控制

所有 CUD 操作和导入导出均通过 Shiro 的 @RequiresPermissions 进行权限控制，权限标识遵循格式：deepAnalysis:snake_table_name:action

6.4 共 21 个补贴模块 + 1 个消息模块，模块结构高度统一

所有补贴模块采用完全一致的代码模板和架构设计，保证了代码的可维护性和一致性。如需新增补贴类型，只需按模板生成对应的后端四层代码和前端六文件即可。