湛江人社项目（zjrs-jeecgBoot）全面分析文档

分析日期：2026-06-01
项目版本：JeecgBoot 3.9.2

一、项目概述

本项目是湛江市人力资源和社会保障局的信息化管理系统，基于 JeecgBoot 3.9.2 低代码开发平台进行二次开发。项目核心定制点在于与广东省智慧人社系统的 SSO 单点登录集成和用户数据同步，业务功能页面主要通过 JeecgBoot 的 Online 低代码动态表单机制由后端配置驱动生成。

项目采用前后端分离架构：

后端：jeecg-boot/ — Spring Boot 3.5.5 + Java 17 单体应用
前端：jeecgboot-vue3/ — Vue 3 + Vite 6 + Ant Design Vue 4 + TypeScript

二、项目目录结构

zjrs-jeecgBoot/
├── jeecg-boot/                          # 后端 Java 项目
│   ├── db/                              # 数据库初始化脚本
│   │   ├── jeecgboot-mysql-5.7.sql      # MySQL 初始化脚本
│   │   ├── tables_nacos.sql             # Nacos 建表脚本
│   │   └── tables_xxl_job.sql           # XXL-Job 建表脚本
│   ├── jeecg-boot-base-core/            # 核心基础框架模块
│   ├── jeecg-module-system/             # 系统管理模块
│   │   ├── jeecg-system-api/            # 系统API接口层
│   │   │   ├── jeecg-system-local-api/  # 单体模式API（直接方法调用）
│   │   │   └── jeecg-system-cloud-api/  # 微服务模式API（Feign调用）
│   │   ├── jeecg-system-biz/            # 系统业务逻辑层
│   │   └── jeecg-system-start/          # 启动入口模块
│   ├── jeecg-boot-module/               # 业务功能模块
│   │   ├── jeecg-module-demo/           # 示例模块
│   │   ├── jeecg-module-zjrs/           # ★ 湛江人社定制模块
│   │   └── jeecg-boot-module-airag/     # AI/RAG 集成模块
│   └── jeecg-server-cloud/              # 微服务模块（可选）
│       ├── jeecg-cloud-gateway/         # Spring Cloud Gateway
│       ├── jeecg-cloud-nacos/           # Nacos 注册/配置中心
│       └── jeecg-visual/                # 监控、定时任务等
│
├── jeecgboot-vue3/                      # 前端 Vue3 项目
│   ├── src/
│   │   ├── api/                         # API 接口定义
│   │   ├── components/                  # 公共组件
│   │   │   └── jeecg/                   # JeecgBoot 专用组件
│   │   ├── views/
│   │   │   ├── sys/login/RsSSOLogin.vue # ★ 智慧人社SSO登录页
│   │   │   ├── system/                  # 系统管理页面
│   │   │   ├── super/                   # 动态扩展模块
│   │   │   │   ├── online/              # Online 低代码表单/报表
│   │   │   │   └── airag/               # AI 模块
│   │   │   ├── dashboard/               # 首页仪表盘
│   │   │   └── monitor/                 # 系统监控
│   │   ├── store/                       # Pinia 状态管理
│   │   ├── router/                      # 路由配置
│   │   ├── utils/                       # 工具类
│   │   └── hooks/                       # 组合式函数
│   └── package.json
│
├── docker-compose.yml                   # Docker 编排
└── AIWork/                              # AI 工作文档

三、技术框架详解

3.1 后端技术栈

层次	技术	版本	说明
基础框架	Spring Boot	3.5.5	使用 `jakarta` 命名空间（非 `javax`）
JDK	OpenJDK	17	同时支持 21、24、25
ORM	MyBatis-Plus	3.5.12	`BaseMapper<T>` + `ServiceImpl<M,T>`
认证授权	Apache Shiro + JWT	2.0.5 / 4.5.0	无状态认证，Redis 缓存权限
数据库	达梦 DM8	-	生产环境使用国产达梦数据库
	MySQL 8.0	-	开发环境使用 MySQL
连接池	Druid	1.2.24	支持动态多数据源
缓存	Redis	-	会话缓存、字典缓存、分布式锁
定时任务	Quartz	-	JDBC 存储，支持集群模式
JSON	FastJSON	2.0.57	阿里巴巴 JSON 框架
Excel	AutoPoi	2.0.4	Excel 导入导出
API文档	Knife4j	4.5.0	OpenAPI v3，`@Schema` 注解
文件存储	MinIO / 阿里云 OSS / 七牛	-	通过 `jeecg.uploadType` 配置切换
报表	积木报表 JimuReport	2.3.2	在线报表设计
BI大屏	积木BI JimuBI	2.3.2	仪表盘和大屏设计
AI集成	JeecgBoot AI Starter	3.9.2.1	支持 DeepSeek、通义千问、智谱等
微服务	Spring Cloud + Alibaba	2025.0.0 / 2023.0.3.3	可选，默认单体模式
数据库迁移	Flyway	7.15.0	增量 SQL 脚本管理
短信	阿里云/腾讯云 SMS	-	登录验证、密码修改
第三方登录	JustAuth	1.4.0	GitHub/企业微信/钉钉/微信
工具库	Hutool	5.8.25	通用工具类

3.2 前端技术栈

层次	技术	版本	说明
框架	Vue	3.5.22	组合式 API
构建工具	Vite	6.3.6	快速构建
UI框架	Ant Design Vue	4.2.6	企业级 UI 组件库
状态管理	Pinia	2.1.7	替代 Vuex
路由	Vue Router	4.5.1	HTML5 History 模式
语言	TypeScript	5.9.3	类型安全
HTTP	Axios	1.12.2	HTTP 请求库
表格	VXE-Table	4.13.31	高性能虚拟滚动表格
图表	ECharts	5.6.0	数据可视化
富文本	TinyMCE	6.6.2	富文本编辑器
国际化	Vue I18n	9.14.5	中英文支持
AI流程	@jeecg/aiflow	3.9.2-beta	AI 流程编排
逻辑流	LogicFlow	2.1.2	流程图绘制引擎
CSS预处理	Less	4.4.2	CSS 预处理器
微前端	Qiankun	-	可选，支持主/子应用模式
桌面端	Electron	-	可选，桌面应用打包

3.3 基础设施

服务	说明
数据库	达梦 DM8（生产）/ MySQL 8.0（开发）
Redis	192.168.0.53:6379，database 6（生产）/ 5（开发）
MinIO	对象存储（可选）
Nacos	微服务注册与配置中心（可选）

四、核心模块架构详解

4.1 jeecg-boot-base-core — 核心基础框架

这是整个平台的基石模块，提供认证、AOP切面、工具类、基础Controller等核心能力。

4.1.1 Shiro + JWT 无状态认证体系

请求流程:
  HTTP Request
    → JwtFilter (跨域处理 / 租户上下文 / @IgnoreAuth免认证判断)
      → ShiroRealm (身份认证 / 权限认证)
        → JwtUtil (Token签名HMAC256 / 验证 / 解析)
        → TokenUtils (编程式Token校验)
        → CommonAPI (查询用户/角色/权限)
          → RedisUtil (缓存用户权限信息)

关键特性：

关闭 Shiro 自带 Session，使用 Redis 缓存权限
PC端 Token 有效期 7 天，APP端 30 天
Token 自动续期机制（在线操作不掉线）
@IgnoreAuth 注解支持免认证接口
多租户校验：登录时验证租户授权状态

4.1.2 AOP 切面体系

切面	注解	功能
AutoLogAspect	`@AutoLog`	自动记录操作日志（方法名、参数、IP、耗时）
DictAspect	`@Dict`	字典值自动翻译（如 sex:1 → sex_dictText:"男"），支持 Redis 缓存
PermissionDataAspect	`@PermissionData`	数据权限控制，根据页面组件注入数据权限规则
SensitiveDataAspect	`@SensitiveEncode/Decode`	敏感数据脱敏（手机号、身份证、邮箱等）
SignatureCheckAspect	`@SignatureCheck`	接口签名校验（X-SIGN + X-TIMESTAMP）

4.1.3 通用 Controller 基类

JeecgController<T, S extends IService<T>> 提供开箱即用的能力：

exportXls() — Excel 导出
exportXlsSheet() — 多 Sheet 导出
exportXlsForBigData() — 大数据量导出
importExcel() — Excel 导入

4.1.4 查询生成器

QueryGenerator.initQueryWrapper(entity, request.getParameterMap()) 根据前端请求参数自动构建 MyBatis-Plus 的 QueryWrapper，支持：

模糊查询（LIKE）
范围查询（BETWEEN）
高级查询（IN、NOT IN 等）
排序
数据权限 SQL 注入

4.1.5 MyBatis 增强

公共字段自动填充：MybatisInterceptor 自动注入 createBy/createTime/updateBy/updateTime/sysOrgCode
多租户 SQL 注入：MybatisPlusSaasConfig 自动在 SQL 中追加租户条件
动态表名：@DynamicTable 注解 + DynamicTableAspect 实现运行时表名切换
动态数据源：DynamicDBUtil 支持运行时切换数据源

4.2 jeecg-module-system — 系统管理模块

提供完整的后台管理功能，采用标准的 Controller → Service → Mapper 三层架构。

4.2.1 核心业务实体关系

用户(SysUser)
  ├── 用户-角色(SysUserRole) ───── 角色(SysRole)
  │                                   ├── 角色-权限(SysRolePermission) ── 菜单权限(SysPermission)
  │                                   │                                     ├── 数据权限规则(SysPermissionDataRule)
  │                                   │                                     └── 类型: 一级菜单/子菜单/按钮权限
  │                                   └── 角色首页(SysRoleIndex)
  ├── 用户-部门(SysUserDepart) ─── 部门(SysDepart)
  │                                   ├── 部门权限(SysDepartPermission) ── 菜单权限
  │                                   ├── 部门角色(SysDepartRole)
  │                                   │    ├── 部门角色-权限(SysDepartRolePermission)
  │                                   │    └── 部门角色-用户(SysDepartRoleUser)
  │                                   └── 树形结构(parentId)
  ├── 用户-租户(SysUserTenant) ─── 租户(SysTenant)
  │                                   └── 租户套餐(SysTenantPack) ── 套餐用户(SysTenantPackUser)
  ├── 用户-岗位(SysUserPosition)
  └── 用户组(SysUgroup) ── 用户组用户(SysUgroupUser)

字典(SysDict)
  └── 字典项(SysDictItem) ── 通过 dictId 关联

4.2.2 功能模块清单

模块	Controller	路由	核心功能
用户管理	SysUserController	`/sys/user`	CRUD、密码管理、冻结/解冻、多租户隔离、Excel导入导出
角色管理	SysRoleController	`/sys/role`	CRUD、权限分配、角色首页配置、admin角色保护
菜单权限	SysPermissionController	`/sys/permission`	树形菜单管理、权限编码、数据权限规则、按钮级权限
字典管理	SysDictController	`/sys/dict`	字典主子表管理、表字典、Redis缓存、多租户隔离
部门管理	SysDepartController	`/sys/sysDepart`	树形组织架构、部门权限、部门角色、级联删除
租户管理	SysTenantController	-	SaaS多租户、租户套餐包、用户-租户关联
登录认证	LoginController	`/sys`	账号密码登录、手机验证码登录、二维码登录
第三方登录	ThirdLoginController	-	GitHub/企业微信/钉钉/微信登录
系统公告	SysAnnouncementController	`/sys/annountCement`	公告发布与管理
日志管理	SysLogController	-	操作日志、数据日志
文件管理	CommonController	-	通用文件上传下载
数据源	SysDataSourceController	-	多数据源管理
网关路由	SysGatewayRouteController	-	微服务网关路由配置
编码规则	SysFillRuleController / SysCheckRuleController	-	填充规则、校验规则

4.3 jeecg-module-zjrs — 湛江人社定制模块 ★

这是本项目的核心定制模块，实现与广东省智慧人社系统的 SSO 单点登录集成和用户数据同步。

4.3.1 模块结构

jeecg-module-zjrs/
└── src/main/java/org/jeecg/modules/zjrs/sso/
    ├── config/
    │   └── ZjrsConfig.java              # SSO 配置（读取 zjrs.sso.* 配置项）
    ├── controller/
    │   └── LoginSSOController.java      # SSO 登录控制器
    ├── entity/
    │   └── VRsUsers.java                # 外部视图 V_RS_USERS 实体映射
    ├── job/
    │   └── UserInfoJob.java             # 定时同步任务（每天凌晨2点）
    ├── mapper/
    │   ├── VRsUsersMapper.java          # 视图数据访问接口
    │   └── xml/VRsUsersMapper.xml       # MyBatis XML 映射
    └── service/
        ├── ILoginSSOService.java        # SSO 登录服务接口
        ├── IVRsUsersService.java        # 用户数据服务接口
        └── impl/
            ├── LoginSSOServiceImpl.java  # SSO 登录服务实现
            └── VRsUsersServiceImpl.java  # 用户同步服务实现

4.3.2 SSO 单点登录流程

1. 外部系统（智慧人社）携带 usertoken 跳转到前端 /rs-sso-login
2. 前端 RsSSOLogin.vue 提取 URL 中的 usertoken 参数
3. 调用后端 POST /zjrs/login/ssoLoginByToken 接口
4. 后端 LoginSSOServiceImpl.ssoLoginByToken 处理：
   a. 通过 usertoken 在 V_RS_USERS 视图中查询用户信息
   b. 若未找到用户 → 抛出异常"未找到用户信息"
   c. 用 loginid 在本地 SysUser 表中查询
   d. 若本地不存在 → 自动调用 syncUserToLocal 同步创建
   e. 校验用户是否有效（checkUserIsEffective）
   f. 生成 JWT Token，存入 Redis
   g. 处理并发登录限制（单点登录踢人逻辑）
   h. 设置登录租户信息
   i. 查询用户所属部门，处理多部门情况
   j. 返回完整登录信息（token、userInfo、departs、multi_depart）
5. 前端保存 token 和用户信息，重定向到目标页面

4.3.3 用户数据同步逻辑

数据流向：V_RS_USERS 视图 → VRsUsersMapper → VRsUsersServiceImpl → SysUser 表

同步规则：

从 V_RS_USERS 视图提取 loginid、sguserid、contactphone、opername
在本地 SysUser 表中按 loginid 查询
若用户已存在 → 更新 id、phone、realname、password
若用户不存在 → 新建 SysUser，设置 username、realname、phone、password、status=1、delFlag=0
密码统一使用配置项 zjrs.sso.userPwd（默认加密值 cb362cfeefbf3d8d）

定时同步任务：UserInfoJob 使用 @Scheduled(cron = "0 0 2 * * ?") 每天凌晨 2:00 自动执行全量同步。

4.3.4 并发登录控制

根据 jeecgBaseConfig.firewall.isConcurrent 配置：

允许并发：同一用户可在多设备同时在线
禁止并发：同一用户在新设备登录时，旧 Token 被删除，旧登录被踢下线
区分 PC 端、APP 端、PHONE 端的不同 Token 前缀

4.3.5 VRsUsers 视图字段

字段名	数据库列名	类型	说明
loginid	LOGINID	String	登录ID（主键）
opername	OPERNAME	String	操作员姓名
contactphone	CONTACTPHONE	String	联系电话
sguserid	SGUSERID	String	用户唯一标识ID

4.4 jeecg-boot-module-airag — AI/RAG 集成模块

集成 AI 能力，支持多种 AI 模型和服务：

AI 能力	提供商	模型
AI 对话	DeepSeek	deepseek-chat
AI 文生图	通义千问	wan2.2-t2i-flash
AI 图生图	通义千问	wan2.5-i2i-preview
AI 语音	智谱	glm-tts
AI 视频	智谱	-
AI 向量嵌入	通义千问	text-embedding-v1
AI RAG	PostgreSQL pgvector	本地向量库

五、前端架构详解

5.1 启动引导流程

createApp → createRouter → setupStore(Pinia)
  → i18n → initAppConfigStore → registerPackages(@jeecg/online)
  → registerGlobComp → SSO login → registerSuper(动态模块发现)
  → setupRouter → guards → directives → error handler
  → registerThirdComp(vxe-table, emoji, dayjs)
  → setupElectron → router.isReady() → mount

5.2 权限与路由

权限模式：BACK — 路由和菜单从后端 API 动态获取
动态路由：运行时在 src/store/modules/permission.ts 中添加
静态路由：登录页、OAuth2登录、Token登录、异常页、AI首页
超级模块发现：registerSuper.ts 使用 import.meta.glob('./**/register.ts') 自动发现并注册模块

5.3 状态管理（Pinia）

Store	ID	职责
user	app-user	认证Token、用户信息、角色、租户、字典
permission	app-permission	动态路由、权限编码、后端菜单
app	app	项目配置、主题、布局设置
locale	app-locale	国际化语言
multipleTab	app-multiple-tab	标签页状态

5.4 API 层

自定义 Axios 封装：src/utils/http/axios/
所有请求通过 MD5 签名（signMd5Utils）
租户模式下自动注入租户 ID Header
统一响应格式：{ code, result, message, success }，code === 200 为成功

5.5 湛江人社 SSO 前端实现

核心文件：

src/views/sys/login/RsSSOLogin.vue — SSO 登录页面，路由 /rs-sso-login
src/views/system/loginmini/SSOLogin.vue — Mini 版 SSO 登录页面
src/api/sys/user.ts — API 定义 rsSsoLogin = '/zjrs/login/ssoLoginByToken'

路由注册（src/router/routes/index.ts）：

export const RsSSOLoginRoute = {
  path: '/rs-sso-login',
  name: 'RsSSOLoginRoute',
  component: () => import('/@/views/sys/login/RsSSOLogin.vue'),
  meta: { title: '智慧人社SSO登录', ignoreAuth: true },
};

5.6 动态模块（super/）

通过 registerSuper.ts 的 import.meta.glob 自动发现机制，实现模块即插即用：

模块	功能
`super/online/`	Online 低代码表单/报表，支持30+种控件、多种列表模式（默认/ERP/Tab/树形）
`super/airag/`	AI 模块，包含 AI 应用、聊天、知识库、模型管理、提示词、MCP工具、海报、换装、视频、语音、写作、OCR 等

六、数据库架构

6.1 数据库选型

环境	数据库	连接信息
开发	MySQL 8.0	192.168.0.77:3306/jeecg-boot2
生产	达梦 DM8	192.168.0.56:5236，Schema: ZJRS_JEECG_BOOT

当前激活的 Profile 为 dm8（见 application.yml 中 spring.profiles.active: dm8）。

6.2 支持的数据库

MySQL、PostgreSQL、Oracle 11g+、SQL Server 2017+、MariaDB、DM8（达梦）、KingBase ES（人大金仓），通过 application-{dbtype}.yml Profile 切换。

6.3 核心数据表

表名	说明
sys_user	用户表
sys_role	角色表
sys_permission	菜单权限表
sys_user_role	用户角色关联表
sys_role_permission	角色权限关联表
sys_depart	部门表
sys_user_depart	用户部门关联表
sys_dict	字典主表
sys_dict_item	字典项表
sys_tenant	租户表
sys_user_tenant	用户租户关联表
sys_log	操作日志表
sys_data_log	数据日志表
sys_announcement	系统公告表
QRTZ_*	Quartz 定时任务表
V_RS_USERS	★ 外部视图（智慧人社用户数据源）

七、业务实现逻辑总结

7.1 整体业务架构

┌─────────────────────────────────────────────────────────────┐
│                    广东省智慧人社系统                          │
│                    (外部系统)                                │
└──────────────────────┬──────────────────────────────────────┘
                       │ usertoken (SSO)
                       ▼
┌─────────────────────────────────────────────────────────────┐
│              湛江人社管理系统 (zjrs-jeecgBoot)                │
│                                                             │
│  ┌─────────────┐   ┌──────────────┐   ┌─────────────────┐  │
│  │ SSO 登录模块 │   │ 用户同步模块  │   │ Online 低代码    │  │
│  │ (zjrs/sso)  │   │ (定时任务)    │   │ (动态表单/报表)  │  │
│  └──────┬──────┘   └──────┬───────┘   └────────┬────────┘  │
│         │                 │                     │           │
│         ▼                 ▼                     ▼           │
│  ┌─────────────────────────────────────────────────────┐   │
│  │              系统管理模块 (jeecg-module-system)       │   │
│  │  用户/角色/权限/部门/字典/租户/日志/公告/文件...      │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │              核心基础框架 (jeecg-boot-base-core)      │   │
│  │  Shiro+JWT / AOP切面 / 查询生成器 / 工具类...        │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  │
│  │ 达梦 DM8  │  │  Redis   │  │  MinIO   │  │ AI 服务   │  │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘  │
└─────────────────────────────────────────────────────────────┘

7.2 核心业务流程

SSO 单点登录：外部智慧人社系统通过 URL 传递 usertoken，本系统验证后自动登录或创建本地用户
用户数据同步：每天凌晨2点定时从 V_RS_USERS 视图同步用户数据到本地 SysUser 表
权限管理：基于 RBAC 模型（用户→角色→权限），支持菜单级、按钮级、数据级权限控制
低代码开发：业务功能通过 Online 动态表单配置生成，无需编写前端代码
多租户隔离：SaaS 模式下通过 tenantId 实现数据隔离

7.3 湛江人社定制范围

定制点	位置	说明
SSO 登录后端	`jeecg-module-zjrs`	与智慧人社系统的 SSO 集成
SSO 登录前端	`RsSSOLogin.vue` / `SSOLogin.vue`	SSO 登录页面
SSO API 定义	`src/api/sys/user.ts`	`rsSsoLogin` 接口
SSO 路由	`src/router/routes/index.ts`	`/rs-sso-login` 路由
用户同步任务	`UserInfoJob.java`	每日凌晨2点同步
数据库视图	`V_RS_USERS`	外部用户数据源
达梦数据库适配	`application-dm8.yml`	国产数据库生产配置
SSO 配置	`zjrs.sso.userPwd`	SSO 用户默认密码

八、部署架构

8.1 单体模式（默认）

Nginx → [Vue3 静态资源]
      → [Spring Boot :8080 /jeecg-boot]
           → [达梦 DM8 :5236]
           → [Redis :6379]

8.2 微服务模式（可选，通过 `-P SpringCloud` 激活）

Nginx → [Vue3 静态资源]
      → [Spring Cloud Gateway :9999]
           → [jeecg-system-cloud-start] → [Nacos :8848]
           → [jeecg-demo-cloud-start]   → [Sentinel :9000]
                                        → [XXL-Job :9080]
                                        → [Monitor :9111]

8.3 Docker 部署

docker-compose.yml 包含：MySQL (13306)、Redis、PostgreSQL+pgvector、MongoDB、应用容器 (8080)。

九、代码规范

9.1 后端代码规范

包结构：org.jeecg.modules.<module-name>.{controller,entity,mapper,mapper.xml,service,service.impl,vo}
命名规范：实体 Sys 前缀、Controller 继承 JeecgController、Service 接口 I<Entity>Service
API 响应：统一使用 Result<T> 封装，Result.OK(data) / Result.error(msg)
修改痕迹：必须用 update-begin/update-end 注释包裹，格式 //update-begin---author:xxx ---date:YYYY-MM-DD for:说明

9.2 前端代码规范

路径别名：/@/ → src/，/#/ → types/
Prettier：150字符宽度、单引号、2空格缩进
ESLint：Vue3 + TypeScript 推荐 + Prettier
提交规范：Conventional Commits（feat/fix/perf/docs/refactor 等）
性能优化：非关键模块使用动态 import() 懒加载

十、关键配置文件索引

文件	位置	说明
根 POM	`jeecg-boot/pom.xml`	Maven 父项目配置、依赖管理
应用配置	`jeecg-system-start/src/main/resources/application.yml`	Profile 选择（当前: dm8）
开发环境	`application-dev.yml`	MySQL + Redis 开发配置
生产环境	`application-dm8.yml`	达梦 DM8 生产配置
前端配置	`jeecgboot-vue3/package.json`	前端依赖和脚本
环境变量	`jeecgboot-vue3/.env`	前端基础配置
开发代理	`jeecgboot-vue3/.env.development`	代理到 localhost:8080
Docker	`docker-compose.yml`	容器编排配置

260601-项目结构与技术框架分析.md 26 KB История Исходник