# XuanChen-Monolithic **Repository Path**: doutoo/xuanchen-monolithic ## Basic Information - **Project Name**: XuanChen-Monolithic - **Description**: 一套基于 SpringBoot3/SpringBoot4、Vue3 及 UniApp 技术栈构建的单体式前后端分离企业级管理系统。 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 7 - **Created**: 2026-11-12 - **Last Updated**: 2026-11-12 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # XuanChen（萱晨）管理系统介绍 ## 一、项目概述 XuanChen 是一套**前后端分离的企业级中后台开发平台（脚手架）**，除权限管理、组织架构、数据字典、通知推送、系统监控、代码生成等通用底座能力外，还内置了一批开箱即用的业务模块：**审批流程（自研 BPM 引擎）、文件中心（在线预览）、协同 Office 文档、报表中心、数据可视化大屏、接口服务（API 编排与开放分发）、AI 助手与知识库（RAG）**，可直接作为业务系统的底座进行二次开发。 数据库脚本 `Documents/xuanchen-monolithic.sql` 共包含 54 张业务表，主数据表统一采用模块化前缀（`sys_` 系统账号、`md_` 主数据、`bpm_` 审批流、`file_` 文件、`online_` 在线文档、`rpt_` 报表、`vis_` 大屏、`api_` 接口、`gen_` 代码生成、`log_` 日志）。 仓库内**并存两套后端实现**，业务模块划分与接口契约基本一致、共用同一套前端，区别在于基础框架选型： | | 后端实现 | 基础框架 | |---|---|---| | 旧版 | `BackEnd/xuanchen-springboot3` | Spring Boot 3 + Java 17 + Shiro | | 新版（当前主线） | `BackEnd/xuanchen-springboot4` | Spring Boot 4 + Java 25 + Spring Security | - **前端工程**：`FrontEnd/xuanchen-vue3`，基于 **Vue 3 + Vite 8 + TypeScript** 的单页应用（SPA），两套后端通用 - **手机端**：`APP/xuanchen-uniapp`，UniApp 工程 - **数据与中间件**：MySQL 8.0、Redis、MinIO 对象存储（文件中心）、PostgreSQL + pgvector（AI 知识库，可选） - **通信方式**：HTTP/JSON（REST 风格）+ WebSocket（通知 / 审批任务 / 催办 / 抄送实时推送） 整体链路： ``` 浏览器 Vue3 SPA ──/api──▶ Vite Dev Proxy / Nginx ──▶ Spring Boot 多模块应用（3 或 4） ├── MySQL 8（持久化） ├── Redis（会话/限流/缓存/分片上传） ├── MinIO（文件对象存储） └── WebSocket /ws（通知与审批实时推送） ``` ## 二、软件架构 ``` * 环境：JDK17+（新版主线为 JDK25） * 手机端：uniapp * 后端： * SpringBoot3版本：SpringBoot3、Mybatis Plus、Shiro、Druid、fesod-sheet、LangChain4j * SpringBoot4版本：SpringBoot4、Mybatis Plus、Spring Security、Druid、fesod-sheet、LangChain4j * 前端：Vue3、Ant Design Vue、vue-router、pinia、axios、dayjs、echarts、quill、bpmn-js * 中间件：MySQL8、Redis、MinIO、ONLYOFFICE DocumentServer（在线文档协同，可选）、Ollama（AI 推理，可选） * 即时通讯：WebSocket ``` ## 三、软件功能 > 菜单分组与页面名称以实际运行系统为准（见[第八节系统功能截图](#八系统功能截图)）。 ``` |--登录 / 注册 / 忘记密码（滑块验证码、邮箱验证码、强制改密） |--首页（欢迎语 / 未读公告 / 我的待办 / 今日登录 / 快捷入口） |--顶部 | |--通知提醒（WebSocket 实时推送） | |--多页签工作区 | |--头像 | | |--用户中心 | | |--修改密码 | | |--清除缓存 | | |--退出登录 | |--AI 助手（右下角悬浮对话） |--基础数据 | |--人员管理（人员档案、导入导出、部门/岗位分配） | |--部门管理（树形、部门负责人） | |--岗位管理 |--系统管理 | |--账号管理（登录凭证、角色分配） | |--角色管理（分配菜单 / 用户） | |--菜单管理 | |--字典管理 | |--参数配置 | |--数据源配置 |--系统监控 | |--在线用户（强制下线） | |--性能监控（CPU / 内存 / JVM / 磁盘） | |--缓存监控（Redis） | |--登录日志 / 操作日志 / 接口日志 / 代码生成日志 |--文件中心 | |--我的文件（文件夹、上传/秒传/分片续传、在线预览：图片/文本/CAD/Office） | |--回收站 / 配额管理 / 文件分享 / 协同编辑 |--流程审批 | |--在线表单（动态表单设计） | |--流程配置（bpmn-js 可视化设计器） | |--发起申请 / 待我审批 / 我的申请 / 我已审批 |--在线文档 | |--协同文档（在线 Word / Excel / PPT 多人共编） | |--思维导图 / 流程图 |--报表管理（模板设计 / 报表列表 / 报表查看） |--接口服务（接口管理 / 采集数据 / 接口日志 / 对外分发） |--数据大屏（大屏设计 / 大屏展示） |--待办事项（审批任务与通知统一待办） |--通知公告（发布通知 / 通知管理 / 通知列表） |--代码生成器（项目预设 / 代码生成 / 生成日志） |--AI 知识库（知识库管理 / 检索测试） |--回收站（各业务模块通用：还原 / 彻底删除） ``` ## 四、目录结构 ``` |--APP 手机端 | |--xuanchen-uniapp uniapp版本（首页/系统/监控/通知/大屏/用户） |--BackEnd 后端（两套实现，模块划分一致） | |--xuanchen-springboot3 SpringBoot3版本 | |--xuanchen-springboot4 SpringBoot4版本 | | |--xuanchen-boot 启动入口 | | |--xuanchen-auth 认证、授权 | | |--xuanchen-common 通用模块（返回体/全局异常/AOP/Excel/WebSocket/工具） | | |--xuanchen-system 系统模块（账号、角色、菜单、字典、参数、通知、待办） | | |--xuanchen-masterdata 主数据模块（部门、人员、岗位及人员-部门/岗位关系） | | |--xuanchen-monitor 监控模块（服务器/缓存/在线用户/登录日志/操作日志/接口日志/生成日志） | | |--xuanchen-filemanage 文件中心（文件/文件夹/分享/配额/回收站/在线Office协同） | | |--xuanchen-businessprocess 审批流程（自研BPM引擎 + bpmn-js设计器） | | |--xuanchen-online 在线协同文档（在线Word/Excel/PPT、绘图、思维导图） | | |--xuanchen-report 报表中心（数据源/数据集/报表/模板） | | |--xuanchen-visualization 数据可视化大屏 | | |--xuanchen-api 接口服务（API编排/调度/日志/对外分发） | | |--xuanchen-ai AI助手与知识库（LangChain4j + Ollama + pgvector） | | |--xuanchen-generator 代码生成器 |--FrontEnd 前端 | |--xuanchen-vue3 vue3版本 | | |--assets 资源 | | |--components 组件（XC通用组件 + 审批流组件） | | |--hooks 钩子（useList / useDragSort / useStatusToggle） | | |--layout 布局 | | |--router 路由 | | |--stores 状态管理（auth/menu/tabs/websocket/collapsed） | | |--utils 工具 | | |--views 视图 | | | |--system 系统管理 | | | |--masterdata 主数据管理（部门/人员/岗位） | | | |--monitor 系统监控 | | | |--generator 开发工具 | | | |--businessprocess 审批流程 | | | |--filemanage 文件中心 | | | |--online 协同文档 | | | |--report 报表中心 | | | |--visualization 可视化大屏 | | | |--api 接口服务 | | | |--ai AI助手 | | | |--auth 登录注册 / error 错误页 |--Documents 文档 | |--xuanchen-monolithic.sql 数据库脚本（54 张表全量 dump） | |--docker-compose.yml 本地中间件编排 | |--系统截图/ 53 张系统功能截图（见第八节） | |--前端目录结构说明.md / 知识库说明.md 专题文档 ``` ## 五、后端工程（两套实现的公共描述） 两套后端均为 Maven 多模块工程，父工程 `xuanchen-parent` 按职责拆分为 **14 个模块**，模块划分与接口契约保持一致，同一套 Vue3 前端可直接切换对接： | 模块 | 职责 | |---|---| | **xuanchen-boot** | 启动入口，聚合各业务模块、提供主类与 `application.yml` | | **xuanchen-common** | 公共基座：统一返回体 `Result`、全局异常 `GlobalExceptionHandler` + `BusinessException`、MyBatis-Plus 配置、AOP 切面（字典翻译/操作日志）、WebSocket 服务端、fesod Excel 导入导出、Redis/IP/密码等工具 | | **xuanchen-auth** | 认证授权：登录登出、注册、滑块验证码、邮箱验证码找回密码、JWT 过滤器（sb3 为 Shiro Realm，sb4 为 Spring Security 过滤链） | | **xuanchen-system** | 核心业务：账号 `sys_account`、角色、菜单、字典、参数、通知、待办 `sys_todo`、首页看板；单向依赖 masterdata 完成账号绑定人员的存在性校验 | | **xuanchen-masterdata** | 主数据：部门 `md_dept`（部门负责人）、人员 `md_person`（档案/导入导出/回收站）、岗位 `md_post`、人员—部门 `md_person_dept` 与人员—岗位 `md_person_post` 关系；对外 REST 为 `/masterdata/dept`、`/masterdata/person`、`/masterdata/post`、`/masterdata/persondept`、`/masterdata/personpost`（权限标识仍为 `system:*`） | | **xuanchen-monitor** | 服务器、Redis 缓存、在线用户（强制下线）、登录日志、操作日志、接口日志、代码生成日志 | | **xuanchen-filemanage** | 文件中心：文件/文件夹、MD5 秒传、分片上传（Redis 管理分块，TTL 24h）、文件分享、配额、回收站、类型白名单/魔数校验；存储抽象 `StorageService`（本地 / MinIO 双实现）；ONLYOFFICE 在线 Office 协同（JWT 回调鉴权、协作者权限） | | **xuanchen-businessprocess** | 审批流程：**自研 BPM 引擎**（非 Flowable）+ 前端 bpmn-js 设计器；BPMN2.0 XML 解析（JDK DOM，零第三方依赖）+ `xc` 扩展命名空间；多 token 推进（并行网关分叉/汇聚、token 状态 JSON 持久化、行锁保证并发正确）、或签/会签、SpEL 条件表达式、审批人规则（用户/角色/自选/部门负责人/直属上级 N 级/表单字段）、转办/驳回/催办/抄送/委托，任务同步待办并经 WebSocket 实时推送 | | **xuanchen-online** | 在线协同文档：在线 Word/Excel/PPT（POI 生成空白文档落库文件中心，编辑复用 ONLYOFFICE），协作者表 `file_collaborator`（可编辑/只读）；在线绘图、思维导图 | | **xuanchen-report** | 报表中心：多数据源（口令 AES 加密入库）、数据集（`SqlGuard` 仅允许单条 SELECT 防注入）、报表模板与报表设计/查看 | | **xuanchen-visualization** | 数据可视化大屏：大屏 `vis_screen`、数据集 `vis_dataset`（SQL 只许单条 SELECT，max-rows=2000），前端全屏设计器与展示页 | | **xuanchen-api** | 接口服务：API 定义/编排引擎（步骤定义 `StepDef` + 模板求值 `TemplateEval`）、模拟数据 `api_data`、定时调度、调用日志 `api_log`，对外公开分发入口 `/open/api/{apiCode}`（匿名放行） | | **xuanchen-ai** | AI 助手与知识库：LangChain4j + Ollama 对话模型，pgvector 向量库 + Apache Tika 文档解析实现知识库 RAG 检索问答 | | **xuanchen-generator** | 代码生成器：多数据源管理（口令 AES-GCM 加密入库、接口返回掩码）、表/字段 UI 配置、Freemarker 模板一键生成前后端 CRUD 代码（含 `CREATE TABLE IF NOT EXISTS` 建表 DDL） | ### 5.1 核心技术栈（两版共有） - **MyBatis-Plus**：单表 CRUD、分页插件、逻辑删除（`@TableLogic`）；复杂 SQL 走同名 Mapper XML - **Druid**：数据源连接池（两版统一） - **fesod-sheet**：EasyExcel 进入 Apache 孵化后的继任者，支撑各模块 Excel 导入导出（流式读取监听器） - **MySQL 8 + Redis**：雪花算法字符串主键；Redis 承载会话、登录失败计数、限流（Lua 脚本原子固定窗口）、分片上传块、在线用户等；`RedisUtil.scanKeys` 统一 SCAN，禁用 KEYS - **WebSocket**：通知公告、审批任务/催办/抄送实时推送（事务提交后再推送） - **oshi-core**：服务器 CPU、内存、JVM、磁盘指标采集 - **Freemarker**：代码生成器模板引擎 - **java-jwt、Lombok**：无状态令牌与样板代码精简 ### 5.2 两套后端的主要差异对照 | 维度 | xuanchen-springboot3 | xuanchen-springboot4 | |---|---|---| | 框架 / JDK | Spring Boot 3 / Java 17 | Spring Boot 4 / Java 25 | | 安全框架 | Apache Shiro（`ShiroFilterFactoryBean` + `JwtFilter`/`ShiroRealm`） | Spring Security（`JwtAuthenticationFilter` + `@PreAuthorize` 方法级鉴权） | | WebSocket | JSR-356 原生 `@ServerEndpoint` | Spring WebSocket + 握手鉴权 | | Web starter | `spring-boot-starter-web` | `spring-boot-starter-webmvc` | | 业务模块与前端 | 与新版一致，共用同一套 Vue3 前端 | 当前开发与修复主线 | > 认证令牌约定（两版一致）：前端请求头 `XC-ACCESS-TOKEN` 携带 JWT 访问令牌；Redis 存储会话；刷新令牌经 httpOnly Cookie `XC-REFRESH-TOKEN` 下发。踢人/改密等会话失效场景会同步清理刷新令牌、WebSocket 连接与在线会话，关闭码 1000=正常重连、1008=会话终止。 ### 5.3 后端工程实践 - 统一返回结构 `Result` 与 `GlobalExceptionHandler` 全局兜底，业务异常用 `BusinessException` 携带业务码（两版均已具备） - 多表写操作统一 `@Transactional(rollbackFor = Exception.class)` - 标志位取值（启用/停用、正常/已删除）统一收敛到 `CommonConst` 常量，禁止裸字面量 - JSON 统一 Jackson 3（`tools.jackson.*`），注解兼容 `com.fasterxml.jackson.annotation.*` - 敏感配置（数据库口令、MinIO、邮件、AI 模型地址等）一律环境变量注入，仓库内不内置真实口令 - 回收站逻辑：列表数据逻辑删除入站，支持还原（自定义 SQL，规避 `@TableLogic` 过滤）与彻底物理删除（级联清理关系表） ## 六、前端工程 xuanchen-vue3（两套后端通用） ### 6.1 技术栈与工程化 - **Vue 3**（3.5+）：全面采用 `