# 重点关注人员管理模块开发记录

> 开发日期：2026-06-03
> 模块路径：就业一湛通服务平台 > 信息智能匹配推送 > 重点关注人员管理
> 参考模块：视频帮办（spbb/video）

---

## 一、功能说明

重点关注人员管理模块用于管理就业困难人员、脱贫人员等需要人社部门重点关注的人员数据。以个人信息库的数据为基础，支持重点关注人员信息的查看、新增、导出、自定义标签、消息推送、岗位推送、服务跟进等功能。

### 查询字段
姓名、性别、学历、户口所在地、现居住地、年龄、人员大类标签、人员小类标签、自定义标签、就业状态

### 列表字段
姓名、性别、年龄、学历、户口所在地、现居住地、求职人员类别、联系电话、求职状态、人员大类标签、人员小类标签、自定义标签

### 人员大类标签选项
见习人员、就业困难人员、脱贫人员

---

## 二、新增文件清单

### 2.1 后端文件（6个）

| 序号 | 文件路径 | 说明 |
|------|----------|------|
| 1 | `jeecg-module-zjrs/.../focuspersonnel/entity/FocusPersonnel.java` | 实体类，对应表 focus_personnel |
| 2 | `jeecg-module-zjrs/.../focuspersonnel/mapper/FocusPersonnelMapper.java` | Mapper接口，继承BaseMapper |
| 3 | `jeecg-module-zjrs/.../focuspersonnel/mapper/xml/FocusPersonnelMapper.xml` | Mapper XML，预留自定义SQL |
| 4 | `jeecg-module-zjrs/.../focuspersonnel/service/IFocusPersonnelService.java` | Service接口，继承IService |
| 5 | `jeecg-module-zjrs/.../focuspersonnel/service/impl/FocusPersonnelServiceImpl.java` | Service实现类 |
| 6 | `jeecg-module-zjrs/.../focuspersonnel/controller/FocusPersonnelController.java` | Controller，8个接口 |

> 完整路径前缀：`jeecg-boot/jeecg-boot-module/jeecg-module-zjrs/src/main/java/org/jeecg/modules/zjrs/`

### 2.2 前端文件（5个）

| 序号 | 文件路径 | 说明 |
|------|----------|------|
| 1 | `views/focuspersonnel/FocusPersonnel.api.ts` | API接口定义 |
| 2 | `views/focuspersonnel/FocusPersonnel.data.ts` | 列表列配置和高级查询配置 |
| 3 | `views/focuspersonnel/FocusPersonnelList.vue` | 列表页面（含查询表单） |
| 4 | `views/focuspersonnel/components/FocusPersonnelForm.vue` | 表单组件（30个字段） |
| 5 | `views/focuspersonnel/components/FocusPersonnelModal.vue` | 弹窗组件（全屏模式） |

> 完整路径前缀：`jeecgboot-vue3/src/`

### 2.3 SQL脚本（2个）

| 序号 | 文件路径 | 说明 |
|------|----------|------|
| 1 | `.docs/sql/重点关注人员信息.sql` | 建表SQL（FOCUS_PERSONNEL） |
| 2 | `flyway/sql/mysql/V20260603_1__menu_insert_FocusPersonnel.sql` | 菜单权限SQL |

---

## 三、技术规范

### 3.1 后端规范

| 项目 | 值 |
|------|-----|
| 包路径 | `org.jeecg.modules.zjrs.focuspersonnel` |
| 数据库表名 | `focus_personnel` |
| API基础路径 | `/focusPersonnel` |
| 权限前缀 | `focus_personnel` |
| 实体类 | 未继承JeecgEntity，手动定义审计字段（与spbb模块一致） |
| Controller | 继承JeecgController，支持Excel导入导出 |

### 3.2 后端接口清单

| HTTP方法 | 路径 | 说明 | 权限标识 |
|----------|------|------|----------|
| GET | `/focusPersonnel/list` | 分页列表查询 | 无 |
| POST | `/focusPersonnel/add` | 添加 | `focus_personnel:add` |
| PUT/POST | `/focusPersonnel/edit` | 编辑 | `focus_personnel:edit` |
| DELETE | `/focusPersonnel/delete` | 通过id删除 | `focus_personnel:delete` |
| DELETE | `/focusPersonnel/deleteBatch` | 批量删除 | `focus_personnel:deleteBatch` |
| GET | `/focusPersonnel/queryById` | 通过id查询 | 无 |
| GET | `/focusPersonnel/exportXls` | 导出Excel | `focus_personnel:exportXls` |
| POST | `/focusPersonnel/importExcel` | 导入Excel | `focus_personnel:importExcel` |

### 3.3 前端规范

| 项目 | 值 |
|------|-----|
| 目录路径 | `views/focuspersonnel/` |
| 列表组件名 | `focusPersonnel` |
| 菜单组件路径 | `focuspersonnel/FocusPersonnelList` |
| 路由URL | `/focusPersonnel/focusPersonnelList` |

### 3.4 菜单层级

```
就业一湛通服务平台（一级菜单，ID: 178060100000001）
  └── 信息智能匹配推送（二级菜单，ID: 178060100000002）
        └── 重点关注人员管理（三级页面菜单，ID: 178060100000010）
              ├── 添加（按钮权限：focus_personnel:add）
              ├── 编辑（按钮权限：focus_personnel:edit）
              ├── 删除（按钮权限：focus_personnel:delete）
              ├── 批量删除（按钮权限：focus_personnel:deleteBatch）
              ├── 导出excel（按钮权限：focus_personnel:exportXls）
              └── 导入excel（按钮权限：focus_personnel:importExcel）
```

---

## 四、数据库表结构（FOCUS_PERSONNEL）

> 说明：仅存储重点关注人员特有字段，个人基本信息通过 `personal_id` 关联 `personal_info` 表获取，避免数据冗余。

| 字段名 | 类型 | 说明 |
|--------|------|------|
| ID | VARCHAR(36) | 主键ID |
| PERSONAL_ID | VARCHAR(36) | 关联个人信息ID（关联personal_info表） |
| MAJOR_TAG | VARCHAR(50) | 人员大类标签（见习人员/就业困难人员/脱贫人员） |
| MINOR_TAG | VARCHAR(200) | 人员小类标签 |
| CUSTOM_TAG | VARCHAR(500) | 自定义标签 |
| DATA_SOURCE | VARCHAR(50) | 数据来源 |
| CREATE_BY | VARCHAR(50) | 创建人 |
| CREATE_TIME | DATETIME | 创建时间 |
| UPDATE_BY | VARCHAR(50) | 修改人 |
| UPDATE_TIME | DATETIME | 更新时间 |
| SYS_ORG_CODE | VARCHAR(50) | 组织机构编号 |

### 4.1 关联表字段说明

`FOCUS_PERSONNEL` 不存储个人信息字段，以下字段通过 `PERSONAL_ID` 关联 `PERSONAL_INFO` 表获取：

| 字段 | 来源表 | 说明 |
|------|--------|------|
| 姓名、性别、年龄、出生日期、民族、国籍、婚姻状况 | PERSONAL_INFO | 个人基础信息 |
| 学历、毕业日期、毕业院校、专业 | PERSONAL_INFO | 教育信息 |
| 户口性质、户口所在地、现居住地、现居住地址 | PERSONAL_INFO | 地址信息 |
| 求职人员类别、联系电话、邮箱、QQ、微信 | PERSONAL_INFO | 联系方式 |
| 是否留学人才、职业技能等级、求职状态、是否接受推荐 | PERSONAL_INFO | 求职信息 |
| 政治面貌、工作经验 | PERSONAL_INFO | 其他信息 |

---

## 五、影响范围说明

本次修改为**纯新增**操作，未修改任何已有文件，不影响原有业务逻辑。

- 新增后端包：`org.jeecg.modules.zjrs.focuspersonnel`
- 新增前端目录：`views/focuspersonnel/`
- 新增SQL脚本：建表SQL和菜单权限SQL
- 新增Flyway迁移脚本：`V20260603_1__menu_insert_FocusPersonnel.sql`

---

## 六、部署说明

1. 执行建表SQL：`.docs/sql/重点关注人员信息.sql`（在目标数据库中创建FOCUS_PERSONNEL表）
2. Flyway会自动执行菜单权限SQL：`V20260603_1__menu_insert_FocusPersonnel.sql`
3. 重新编译部署后端服务
4. 重新构建部署前端服务
5. 使用admin账号登录系统，验证菜单和功能是否正常

---

## 七、问题修复记录

### 7.1 子菜单不显示问题 - 汇总修复

**问题描述：** "信息智能匹配推送"一级菜单可显示，但"重点关注人员管理"二级子菜单在侧边栏不显示。

**根因分析（多个问题叠加）：**

**问题①：component不是LAYOUT**
- 前端 `routeHelper.ts` 中 `transformObjToRoute` 方法（第147行）对非 `LAYOUT` 组件会执行 `route.children = [cloneDeep(route)]`，覆盖原有的子菜单数据
- 修复：一级菜单component改为 `LAYOUT`

**问题②：always_show=1导致子菜单不渲染**
- 前端 `compUtils.ts` 中 `checkChildrenHidden` 函数（第389行）当 `alwaysShow=true` 时返回 `false`
- 导致 `BasicSubMenuItem.vue` 中 `menuHasChildren` 返回 `false`
- 菜单项被渲染为叶子节点 `BasicMenuItem` 而非子菜单 `SubMenu`
- 修复：`always_show` 改为 `0`

**问题③：子菜单缺少redirect**
- 一级菜单作为聚合路由没有redirect，导航到父路径时内容区为空
- 修复：添加 `redirect = '/focusPersonnel/focusPersonnelList'`

**相关代码（compUtils.ts 第389-398行）：**
```typescript
export function checkChildrenHidden(menuTreeItem){
  let alwaysShow = menuTreeItem.alwaysShow;
  if(alwaysShow){
    return false;  // ← 导致子菜单不可见！
  }
  return menuTreeItem.children?.find((item) => item.hideMenu == false) != null;
}
```

**相关代码（BasicSubMenuItem.vue 第41-48行）：**
```typescript
function menuHasChildren(menuTreeItem): boolean {
    return (
      !menuTreeItem.meta?.hideChildrenInMenu &&
      Reflect.has(menuTreeItem, 'children') &&
      !!menuTreeItem.children &&
      menuTreeItem.children.length > 0
      && checkChildrenHidden(menuTreeItem)  // ← 返回false，menuHasChildren=false
    );
  }
```

**最终SQL关键字段值：**

| 字段 | 一级菜单（id:002） | 二级菜单（id:010） |
|------|-------------------|-------------------|
| component | `LAYOUT` | `focuspersonnel/FocusPersonnelList` |
| menu_type | `0`（一级菜单） | `1`（子菜单） |
| is_leaf | `0`（有子菜单） | `1`（叶子节点） |
| always_show | `0` | `0` |
| redirect | `/focusPersonnel/focusPersonnelList` | `NULL` |
| parent_id | `''`（空=顶级） | `178060100000002` |
| icon | `ant-design:connect-outlined` | `NULL` |
| sort_no | `2.00` | `1.00` |

**涉及文件：**
- `V20260603_1__menu_insert_FocusPersonnel.sql` — 最终完整版本，包含所有正确配置
- `.docs/sql/重点关注人员管理-手动修复.sql` — 手动清理重插脚本

**最终验证通过后：**
1. 在数据库中执行手动清理SQL（清除脏数据）
2. 重新启动后端服务（Flyway会自动执行V1脚本）
3. 重新登录系统
4. 侧边栏应显示：信息智能匹配推送（可展开▶）> 重点关注人员管理

---

## 八、字典实现

### 8.1 人员大类标签字典（focus_major_tag）

将"人员大类标签"字段改为数据字典实现，方便后续灵活调整标签选项。

**字典编码：** `focus_major_tag`

**字典项：**
| 显示文本 | 存储值 | 排序 |
|---------|--------|------|
| 就业困难人员 | 就业困难人员 | 1 |
| 脱贫人员 | 脱贫人员 | 2 |

**涉及文件：**
1. `FocusPersonnel.java` — 添加 `@Dict(dicCode = "focus_major_tag")` 注解
2. `FocusPersonnelForm.vue` — `<a-select>` 改为 `<j-dict-select-tag dict-code="focus_major_tag" />`
3. `FocusPersonnelList.vue` — 查询条件同理改为字典控件
4. `FocusPersonnel.data.ts` — 列定义添加 `dictCode: 'focus_major_tag'`
5. `.docs/sql/重点关注人员字典.sql` — 字典SQL脚本

**执行字典SQL后再重新编译后端即可生效。**