# 数据统计模块开发记录

> 创建日期：2026-06-11   
> 需求依据：《需求规格说明书》第3.11节 - 数据统计

---

## 一、模块概述

"数据统计"模块用于接收外部系统回流的数据，包含3张核心明细表及其对应的3张统计报表页面，共6个前端菜单。

### 1.1 三张核心数据表

| 序号 | 表名 | 表说明 | 实体类 |
|------|------|--------|--------|
| 1 | `stat_job_reflux` | 岗位数据回流明细表 | `StatJobReflux` |
| 2 | `stat_key_person_reflux` | 重点人群回流明细表 | `StatKeyPersonReflux` |
| 3 | `stat_worker_reflux` | 农民工流动回流明细表 | `StatWorkerReflux` |

### 1.2 六个前端页面

| 序号 | 路由路径 | 页面名称 | 功能类型 |
|------|----------|----------|----------|
| 1 | `/dataReflux/statJobReflux` | 岗位回流数据 | 明细管理 |
| 2 | `/dataReflux/statWorkerReflux` | 农民工流动回流数据 | 明细管理 |
| 3 | `/dataReflux/statKeyPersonReflux` | 重点人群回流数据 | 明细管理 |
| 4 | `/statistics/jobReflux` | 岗位归集数量统计 | 统计报表 |
| 5 | `/statistics/workerReflux` | 农民工返乡返岗统计 | 统计报表 |
| 6 | `/statistics/keyPersonReflux` | 重点人群统计 | 统计报表 |

---

## 二、后端代码结构

后端代码位于路径：`jeecg-boot/jeecg-boot-module/jeecg-module-zjrs/src/main/java/org/jeecg/modules/zjrs/dataReflux/`

每个子模块（statJobReflux / statKeyPersonReflux / statWorkerReflux）均采用统一的分层架构：

```
├── controller/          # 控制器层（REST API）
├── entity/              # 实体类 + 统计VO
├── mapper/              # MyBatis Mapper接口
│   └── xml/             # Mapper XML
└── service/             # 业务接口
    └── impl/            # 业务实现
```

### 2.1 各表实体字段说明

#### stat_job_reflux（岗位数据回流明细表）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | String | 主键（ASSIGN_ID） |
| unitCreditCode | String | 统一社会信用代码 |
| enterpriseName | String | 企业名称 |
| district | String | 所属区县 |
| jobName | String | 招聘岗位名称 |
| planHireCount | Integer | 计划招聘人数 |
| jobIndustry | String | 岗位所属行业 |
| salaryRange | String | 薪资区间 |
| educationRequire | String | 学历要求 |
| jobPublishTime | Date | 岗位发布时间 |
| jobStatus | String | 岗位状态 |
| dataRefluxTime | Date | 数据回流时间 |
| createBy/createTime/updateBy/updateTime/sysOrgCode | — | 系统标准字段 |

#### stat_key_person_reflux（重点人群回流明细表）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | String | 主键（ASSIGN_ID） |
| idCard | String | 身份证号码 |
| fullName | String | 姓名 |
| district | String | 所属区县 |
| keyPersonCategory | String | 重点人群类别 |
| confirmDate | Date | 认定日期 |
| validDate | Date | 有效日期 |
| currentEmployStatus | String | 当前就业状态 |
| dataRefluxTime | Date | 数据回流时间 |
| createBy/createTime/updateBy/updateTime/sysOrgCode | — | 系统标准字段 |

#### stat_worker_reflux（农民工流动回流明细表）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | String | 主键（ASSIGN_ID） |
| idCard | String | 身份证号码 |
| fullName | String | 姓名 |
| district | String | 所属区县 |
| ruralRegisterFlag | String | 乡村户籍标识 |
| originWorkArea | String | 原就业外出地市/省份 |
| workEndDate | Date | 外出就业结束日期 |
| localEmployDate | Date | 本地新就业登记日期 |
| personCategoryTag | String | 人员类别标签 |
| dataRefluxTime | Date | 数据回流时间 |
| createBy/createTime/updateBy/updateTime/sysOrgCode | — | 系统标准字段 |

### 2.2 Controller API 接口

每个Controller继承自 `JeecgController<T, IService<T>>`，提供以下标准接口：

| 接口 | HTTP方法 | 路径 | 说明 |
|------|----------|------|------|
| 分页查询 | GET | `/list` | 支持QueryGenerator动态查询条件 |
| 主键查询 | GET | `/queryById` | 通过id查询单条记录 |
| 新增 | POST | `/add` | 新增记录 |
| 编辑 | PUT/POST | `/edit` | 更新记录 |
| 删除 | DELETE | `/delete` | 通过id删除 |
| 批量删除 | DELETE | `/deleteBatch` | 逗号分隔id批量删除 |
| 导出Excel | GET/POST | `/exportXls` | 导出明细数据到Excel |
| 导入Excel | POST | `/importExcel` | 从Excel导入数据 |
| 统计查询 | GET | `/statistics/queryByMonth` | 按月统计查询（传入year参数） |
| 统计导出 | GET/POST | `/statistics/exportXls` | 导出统计报表到Excel |

### 2.3 统计SQL逻辑

三个MyBatis XML中的统计SQL均按 **年份** 进行筛选，按 **月份 + 区县**（+ 类别）维度进行 GROUP BY 聚合：

- **岗位统计**：`DATE_FORMAT(t.DATA_REFLUX_TIME, '%Y-%m')` + `DISTRICT`，统计归集总数、本期新增、本期失效
- **重点人群统计**：`DATE_FORMAT(t.DATA_REFLUX_TIME, '%Y-%m')` + `DISTRICT` + `KEY_PERSON_CATEGORY`，统计总人数、已失效人数、未就业人数
- **农民工统计**：`DATE_FORMAT(t.DATA_REFLUX_TIME, '%Y-%m')` + `DISTRICT` + `PERSON_CATEGORY_TAG`，统计返乡总人数、新就业登记人数

### 2.4 Service层

- 每个Service接口均扩展 `IService<T>`，继承MyBatis-Plus基础CRUD能力
- 每个ServiceImpl均扩展 `ServiceImpl<Mapper, Entity>`，实现 `ITranslateDictFieldService` 接口
- `translateDictFields` 方法用于导出时将字典值翻译为中文标签（当前3表暂无字典字段需要翻译，直接返回原列表）
- `queryStatisticsByYear` 方法委托给对应的Mapper执行统计SQL

---

## 三、前端代码结构

### 3.1 明细管理页面（dataReflux目录）

每个表的明细页面包含6个文件，结构一致：

| 文件 | 说明 |
|------|------|
| `StatXxxReflux.api.ts` | API接口定义（list/save/edit/delete/exportXls/importExcel/queryById） |
| `StatXxxReflux.data.ts` | 表格列定义（columns）+ 高级查询字段定义（superQuerySchema） |
| `StatXxxRefluxList.vue` | 列表主页面（查询区域 + BasicTable + 导出按钮 + 详情弹窗） |
| `components/StatXxxRefluxDetailModal.vue` | 详情弹窗组件（使用a-descriptions展示字段） |
| `components/StatXxxRefluxForm.vue` | 表单组件（新增/编辑） |
| `components/StatXxxRefluxModal.vue` | 弹窗容器组件（包裹Form） |

#### 关键技术点：

1. **查询区域**：默认可见3个查询条件，高级搜索通过 `superQuerySchema` 支持更多字段
2. **操作栏**：每行显示"查看"按钮，点击打开详情弹窗
3. **详情弹窗**：通过 `queryById` 接口获取完整数据，使用 `a-descriptions` 展示
4. **导出**：通过 `useListPage` hook 统一的 `onExportXls` 方法
5. **日期选择器**：表单中的日期字段使用 `a-date-picker`，格式为 `YYYY-MM-DD`

#### 查询条件（各表默认可见）：

| 表 | 查询条件1 | 查询条件2 | 查询条件3 |
|----|-----------|-----------|-----------|
| 岗位 | 企业名称 | 岗位名称 | 所属区县 |
| 重点人群 | 姓名 | 身份证号码 | 所属区县 |
| 农民工 | 姓名 | 身份证号码 | 所属区县 |

### 3.2 统计报表页面（statistics目录）

每个表的统计页面包含3个文件，结构一致：

| 文件 | 说明 |
|------|------|
| `XxxStatistics.api.ts` | API定义（statisticsList + statisticsExportXls） |
| `XxxStatistics.data.ts` | 统计表格列定义 + 单元格合并逻辑 |
| `XxxStatisticsList.vue` | 统计列表页面（年份选择 + BasicTable + 导出按钮） |

#### 关键技术点：

1. **年份选择器**：使用 `a-date-picker picker="year"`，默认值为当前年份
2. **单元格合并**：通过 `afterFetch` 钩子计算同月份行的 `_rowSpanMap`，在 `customCell` 中实现同月份的多行合并展示
3. **分页**：统计报表关闭分页（`pagination: false`），一次性展示全年数据
4. **操作栏**：统计报表隐藏操作栏（`showActionColumn: false`）

#### 统计报表列定义：

**岗位归集数量统计报表**：

| 列 | 是否合并 |
|----|----------|
| 序号 | 按月合并 |
| 统计月份 | 按月合并 |
| 所属区县 | 不合并 |
| 归集岗位总数 | 不合并 |
| 本期新增岗位数 | 不合并 |
| 本期失效下架岗位数 | 不合并 |

**重点人群统计报表**：

| 列 | 是否合并 |
|----|----------|
| 序号 | 按月合并 |
| 统计月份 | 按月合并 |
| 所属区县 | 不合并 |
| 重点人群类别 | 不合并 |
| 本期本类别总人数 | 不合并 |
| 本期本类别已失效总人数 | 不合并 |
| 本期本类别未就业总人数 | 不合并 |

**农民工返乡返岗统计报表**：

| 列 | 是否合并 |
|----|----------|
| 序号 | 按月合并 |
| 统计月份 | 按月合并 |
| 所属区县 | 不合并 |
| 人员类别 | 不合并 |
| 本期返乡总人数 | 不合并 |
| 本期新就业登记总人数 | 不合并 |

---

## 四、权限与菜单配置

权限菜单SQL文件位于：  
`jeecg-boot/jeecg-module-system/jeecg-system-start/src/main/resources/flyway/sql/mysql/V20260611_1__menu_dataReflux.sql`

### 4.1 菜单结构

所有主菜单的父级菜单ID为 `2064888275729645570`。

#### 明细管理菜单（3个主菜单，每个含7个子权限）：

| 菜单ID | 菜单名称 | 排序 |
|--------|----------|------|
| 178061200000101 | 岗位回流数据 | 1 |
| 178061200000201 | 农民工流动回流数据 | 2 |
| 178061200000301 | 重点人群回流数据 | 3 |

每个主菜单下包含：添加、编辑、删除、批量删除、导出excel、导入excel 共6个按钮级权限。

#### 统计报表菜单（3个主菜单，每个含2个子权限）：

| 菜单ID | 菜单名称 | 排序 |
|--------|----------|------|
| 178061200000401 | 岗位归集数量统计 | 4 |
| 178061200000501 | 农民工返乡返岗统计 | 5 |
| 178061200000601 | 重点人群统计 | 6 |

每个统计菜单下包含：查询、导出excel 共2个按钮级权限。

### 4.2 权限命名规范

| 权限类型 | 格式 |
|----------|------|
| 明细-添加 | `dataReflux:stat_{table}_reflux:add` |
| 明细-编辑 | `dataReflux:stat_{table}_reflux:edit` |
| 明细-删除 | `dataReflux:stat_{table}_reflux:delete` |
| 明细-批量删除 | `dataReflux:stat_{table}_reflux:deleteBatch` |
| 明细-导出 | `dataReflux:stat_{table}_reflux:exportXls` |
| 明细-导入 | `dataReflux:stat_{table}_reflux:importExcel` |
| 统计-查询 | `dataReflux:stat_{table}_reflux:statisticsQuery` |
| 统计-导出 | `dataReflux:stat_{table}_reflux:statisticsExportXls` |

其中 `{table}` 为 `job` / `worker` / `key_person`。

### 4.3 角色授权

所有菜单和权限均已授权给 admin 角色（role_id: `f6817f48af4fb3af11b9e8bf182f618b`）。

---

## 五、涉及文件清单

### 5.1 后端文件（21个）

```
jeecg-boot/jeecg-boot-module/jeecg-module-zjrs/src/main/java/org/jeecg/modules/zjrs/dataReflux/
├── statJobReflux/
│   ├── controller/StatJobRefluxController.java        # 岗位回流控制器（CRUD + 统计 + Excel导入导出）
│   ├── entity/StatJobReflux.java                      # 岗位回流实体（11个业务字段）
│   ├── entity/StatJobRefluxStatisticsVo.java          # 岗位统计报表VO（5个统计字段）
│   ├── mapper/StatJobRefluxMapper.java                # Mapper接口（统计查询方法）
│   ├── mapper/xml/StatJobRefluxMapper.xml             # 统计SQL（按月+区县分组聚合）
│   ├── service/IStatJobRefluxService.java             # 服务接口
│   └── service/impl/StatJobRefluxServiceImpl.java     # 服务实现
├── statKeyPersonReflux/
│   ├── controller/StatKeyPersonRefluxController.java  # 重点人群回流控制器
│   ├── entity/StatKeyPersonReflux.java                # 重点人群回流实体（8个业务字段）
│   ├── entity/StatKeyPersonRefluxStatisticsVo.java    # 重点人群统计报表VO（6个统计字段）
│   ├── mapper/StatKeyPersonRefluxMapper.java          # Mapper接口
│   ├── mapper/xml/StatKeyPersonRefluxMapper.xml       # 统计SQL（按月+区县+类别分组）
│   ├── service/IStatKeyPersonRefluxService.java       # 服务接口
│   └── service/impl/StatKeyPersonRefluxServiceImpl.java # 服务实现
└── statWorkerReflux/
    ├── controller/StatWorkerRefluxController.java     # 农民工回流控制器
    ├── entity/StatWorkerReflux.java                   # 农民工回流实体（9个业务字段）
    ├── entity/StatWorkerRefluxStatisticsVo.java       # 农民工统计报表VO（5个统计字段）
    ├── mapper/StatWorkerRefluxMapper.java             # Mapper接口
    ├── mapper/xml/StatWorkerRefluxMapper.xml          # 统计SQL（按月+区县+人员类别分组）
    ├── service/IStatWorkerRefluxService.java          # 服务接口
    └── service/impl/StatWorkerRefluxServiceImpl.java  # 服务实现
```

### 5.2 前端文件（27个）

```
jeecgboot-vue3/src/views/

dataReflux/
├── statJobReflux/
│   ├── StatJobReflux.api.ts                           # 岗位回流API定义（8个接口）
│   ├── StatJobReflux.data.ts                          # 岗位表格列定义（11列） + 高级查询（11字段）
│   ├── StatJobRefluxList.vue                          # 岗位回流列表页（企业名称/岗位名称/区县查询）
│   └── components/
│       ├── StatJobRefluxDetailModal.vue               # 岗位详情弹窗
│       ├── StatJobRefluxForm.vue                      # 岗位表单（11个业务字段输入）
│       └── StatJobRefluxModal.vue                     # 岗位弹窗容器
├── statKeyPersonReflux/
│   ├── StatKeyPersonReflux.api.ts                     # 重点人群回流API定义
│   ├── StatKeyPersonReflux.data.ts                    # 重点人群表格列定义（8列） + 高级查询（8字段）
│   ├── StatKeyPersonRefluxList.vue                    # 重点人群列表页（姓名/身份证/区县查询）
│   └── components/
│       ├── StatKeyPersonRefluxDetailModal.vue         # 重点人群详情弹窗
│       ├── StatKeyPersonRefluxForm.vue                # 重点人群表单（8个业务字段输入）
│       └── StatKeyPersonRefluxModal.vue               # 重点人群弹窗容器
└── statWorkerReflux/
    ├── StatWorkerReflux.api.ts                        # 农民工回流API定义
    ├── StatWorkerReflux.data.ts                       # 农民工表格列定义（9列） + 高级查询（9字段）
    ├── StatWorkerRefluxList.vue                       # 农民工列表页（姓名/身份证/区县查询）
    └── components/
        ├── StatWorkerRefluxDetailModal.vue            # 农民工详情弹窗
        ├── StatWorkerRefluxForm.vue                   # 农民工表单（9个业务字段输入）
        └── StatWorkerRefluxModal.vue                  # 农民工弹窗容器

statistics/
├── jobReflux/
│   ├── JobRefluxStatistics.api.ts                     # 岗位统计API（查询+导出）
│   ├── JobRefluxStatistics.data.ts                    # 岗位统计表格列定义（6列，含单元格合并）
│   └── JobRefluxStatisticsList.vue                    # 岗位统计页面（年份选择 + 无分页 + 月份合并）
├── keyPersonReflux/
│   ├── KeyPersonRefluxStatistics.api.ts               # 重点人群统计API
│   ├── KeyPersonRefluxStatistics.data.ts              # 重点人群统计表格列定义（7列，含单元格合并）
│   └── KeyPersonRefluxStatisticsList.vue              # 重点人群统计页面
└── workerReflux/
    ├── WorkerRefluxStatistics.api.ts                  # 农民工统计API
    ├── WorkerRefluxStatistics.data.ts                 # 农民工统计表格列定义（6列，含单元格合并）
    └── WorkerRefluxStatisticsList.vue                 # 农民工统计页面
```

### 5.3 SQL文件（1个）

```
jeecg-boot/jeecg-module-system/jeecg-system-start/src/main/resources/flyway/sql/mysql/
└── V20260611_1__menu_dataReflux.sql                   # 菜单权限SQL（6个主菜单 + 37个子权限 + 角色授权）
```

---

## 六、技术要点总结

| 要点 | 说明 |
|------|------|
| 框架 | Spring Boot + MyBatis-Plus + JeecgBoot |
| ORM | MyBatis-Plus（基础CRUD自动生成）+ MyBatis XML（统计SQL手写） |
| 前端 | Vue 3 + TypeScript + Ant Design Vue + JeecgBoot Vue3封装组件 |
| 权限 | Apache Shiro注解 + sys_permission表存储菜单/按钮权限 |
| 导入导出 | AutoPoi（JeecgEntityExcelView） |
| 数据库迁移 | Flyway（SQL脚本命名规范：V{YYYYMMDD}_{序号}__描述.sql） |
| 统计维度 | 年份筛选 + 月份/区县/类别多维度聚合 |
| 前端合并 | 通过 `afterFetch` 计算 `_rowSpanMap` + `customCell` 实现同月单元格合并 |
| JSON格式化 | 后端日期字段统一 `GMT+8`、`yyyy-MM-dd` 格式 |
| Excel导出 | 明细导出 - 可选择导出字段列表；统计导出 - 固定导出字段 |