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

开发日期：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

六、部署说明

执行建表SQL：.docs/sql/重点关注人员信息.sql（在目标数据库中创建FOCUS_PERSONNEL表）
Flyway会自动执行菜单权限SQL：V20260603_1__menu_insert_FocusPersonnel.sql
重新编译部署后端服务
重新构建部署前端服务
使用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行）：

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行）：

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 — 手动清理重插脚本

最终验证通过后：

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

八、字典实现

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

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

字典编码： focus_major_tag

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

涉及文件：

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

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

九、视图实现（替代Mapper XML中的JOIN查询）

9.1 背景

列表查询原在 FocusPersonnelMapper.xml 中使用 LEFT JOIN personal_info 关联查询个人信息字段。为简化SQL、提高可维护性，改用数据库视图封装关联逻辑。

9.2 视图定义

视图名： v_focus_personnel_list

视图SQL文件： .docs/sql/重点关注人员视图.sql

CREATE VIEW v_focus_personnel_list AS
SELECT
    fp.id,
    fp.personal_id,
    fp.major_tag,
    fp.minor_tag,
    fp.custom_tag,
    pi.full_name,
    pi.gender,
    TIMESTAMPDIFF(YEAR, pi.birth_date, CURDATE()) AS age,
    pi.education,
    pi.household_location,
    pi.current_residence,
    pi.job_seeker_category,
    pi.contact_phone,
    pi.job_search_status,
    fp.create_time
FROM focus_personnel fp
LEFT JOIN personal_info pi ON fp.personal_id = pi.id;

9.3 修改内容

文件	修改说明
`FocusPersonnelMapper.xml`	原 `SELECT ... FROM focus_personnel fp LEFT JOIN personal_info pi ...` 改为 `SELECT * FROM v_focus_personnel_list`
`.docs/sql/重点关注人员视图.sql`	新增，视图创建SQL

9.4 部署说明

执行视图SQL前需要确保 focus_personnel 和 personal_info 表已存在。建议先执行 重点关注人员信息.sql 建表，再执行本视图SQL。视图只需在数据库中执行一次，后续查询均通过视图进行。

9.5 涉及文件清单

.docs/sql/重点关注人员视图.sql — 新增，视图创建SQL
FocusPersonnelMapper.xml — 修改，SELECT * FROM v_focus_personnel_list

十、前端查询区下拉框修复

10.1 问题说明

查询条件中的"学历"和"求职状态"字段原为普通文本输入框（<a-input>），使用不便且容易输入不匹配的值。根据现有数据存储情况（personal_info表中性别、学历、求职状态均直接存储文本值），将这两个字段改为下拉选择框。

10.2 修改内容

1. FocusPersonnelList.vue — 学历查询条件

原为 <a-input> 普通文本输入框，改为 <a-select> 下拉选择框，选项包括：博士研究生、硕士研究生、大学本科、大学专科、中专、高中、初中及以下。

2. FocusPersonnelList.vue — 求职状态查询条件

原为 <a-input> 普通文本输入框，改为 <a-select> 下拉选择框，选项包括：正在求职、暂不求职、已就业、已入职。

10.3 修改原则

性别（原已为 <a-select> 硬编码"男性"/"女性"）保持不变
人员大类标签（原已为 j-dict-select-tag dict-code="focus_major_tag"）保持不变
由于 personal_info 表中这些字段存储的是文本值（非字典编码值），使用 <a-select> 硬编码选项与数据匹配
高级查询配置（superQuerySchema）中这些字段保持 view='text'，因无对应系统字典

10.4 涉及文件清单

FocusPersonnelList.vue — 学历和求职状态查询条件从 <a-input> 改为 <a-select>

十一、j-dict-select-tag 组件未渲染问题

11.1 问题说明

前端页面中"人员大类标签"的下拉框 <j-dict-select-tag dict-code="focus_major_tag" /> 空白无选项。

11.2 根因分析

j-dict-select-tag 组件没有全局注册，需要在每个使用它的页面中显式 import。而 FocusPersonnelList.vue 和 FocusPersonnelForm.vue 的 <script setup> 中均缺少 import 语句，导致组件未注册、未渲染，下拉框为空。

对比成功页面（views/system/examples/demo/index.vue）使用方式：

// 必须显式 import
import JDictSelectTag from '/@/components/Form/src/jeecg/components/JDictSelectTag.vue';

11.3 修改内容

文件	修改说明
`FocusPersonnelList.vue`	脚本区添加 `import JDictSelectTag`
`FocusPersonnelForm.vue`	脚本区添加 `import JDictSelectTag`

11.4 涉及文件清单

FocusPersonnelList.vue — 添加组件导入
FocusPersonnelForm.vue — 添加组件导入

260603-重点关注人员管理模块开发记录.md 15 KB History Raw