# 深度分析模块（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），还定义了一个自定义方法：

```java
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 个消息模块，模块结构高度统一

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