# forge-admin
**Repository Path**: open-hj/forge-admin
## Basic Information
- **Project Name**: forge-admin
- **Description**: 企业级后台管理解决方案，前后端分离架构设计。基于 Spring Boot 3.2 构建，使用 MyBatis Plus 简化数 据操作；前端采用 Vue 3 + TypeScript + Element Plus 技术栈。 内置完整的权限管理模块，支持用户、角色、菜单、部门的层级管理，并实现细粒度的数据权限控制。 集成 Quartz 定时任务调度、操作日志审计等企业级功能。提供项目模板化工具。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 3
- **Created**: 2026-06-07
- **Last Updated**: 2026-10-04
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# forge-admin
**开箱即用的企业级后台管理系统 · Spring Boot 3.4 + Vue 3 + TypeScript**
RBAC 权限 · B2B SaaS 多租户 · 工作流审批 · 可视化大屏 · AI 对话 · 打印模板 · 等保二级
[](https://github.com/wlddhj/forge-admin/stargazers)
[](https://github.com/wlddhj/forge-admin/network)
[](https://github.com/wlddhj/forge-admin/issues)
[](./LICENSE)
**Github 镜像**：[github.com/wlddhj/forge-admin](https://github.com/wlddhj/forge-admin)
**Gitee 镜像**：[gitee.com/open-hj/forge-admin](https://gitee.com/open-hj/forge-admin)
**在线演示**：
## 核心亮点
| 能力 | 说明 |
|------|------|
| RBAC + 数据权限 | 用户/角色/菜单/部门/岗位五级管理，数据权限支持全部/本部门/本部门及以下/仅本人等多种范围 |
| B2B SaaS 多租户 | SQL 级自动隔离（TenantLineInnerInterceptor）、套餐化菜单分配、平台超管代管，配置开关一键回归单租户 |
| 工作流审批 | 基于 FlowLong 的可视化流程设计器，支持驳回/委派/转办/退回/加签/抄送等完整审批操作 |
| 可视化大屏 | goView 拖拽编辑器 + SQL/HTTP 双数据源 + AST 级 SQL 安全层（SELECT-only/表列白名单/强制 LIMIT/熔断/SSRF 防护） |
| AI 能力 | Spring AI 直连 DeepSeek/Qwen/GLM/ERNIE，SSE 流式对话、Tika 文档解析、智能摘要，模型配置表驱动 |
| 打印模板 | 基于 hiprint 的拖拽式模板设计器，浏览器原生打印预览，按编号跨租户调用 |
| 等保二级合规 | 密码策略/失败锁定/单点登录/AES-256-GCM 字段加密/XSS 过滤/审计脱敏（GB/T 22239-2019） |
| OAuth2 + 社交登录 | Spring Authorization Server 授权服务器，JustAuth 集成微信、钉钉扫码登录 |
| 10 套 UI 主题 | 预设套餐 + 调色板/布局/风格三维度独立切换 + 自定义主色 + 明暗双模式，无刷新切换 |
| 微信小程序 | 独立 `/app-api` 端点与 `app_user` 用户体系，微信授权登录一键注册 |
| 工程化 | pnpm monorepo、业务模块脚手架（创建/删除）、项目模板化工具、Docker 容器化部署 |
## 系统架构
```mermaid
graph TB
subgraph client["客户端"]
direction LR
Web["forge-web
管理端 SPA
Vue 3 + TS + Element Plus"]
Mini["forge-miniapp
微信小程序
uni-app"]
Screen["forge-screen
goView 大屏编辑器
iframe 嵌入管理端"]
end
subgraph gateway["接入层（双端点）"]
direction LR
AdminAPI["/admin-api · JWT + RBAC
sys_user 用户体系"]
AppAPI["/app-api · 微信授权登录
app_user 独立用户体系"]
end
subgraph biz["业务模块（api + biz 分离）"]
direction LR
System["system
RBAC · 多租户 · 定时任务"]
Workflow["workflow
FlowLong 审批流"]
AI["ai
Spring AI 多模型"]
ScreenBiz["screen
大屏 · SQL 安全层"]
end
subgraph framework["框架层 forge-framework（6 Starter）"]
direction LR
FSecurity["security
JWT · OAuth2 · JustAuth"]
FTenant["tenant
SQL 级租户隔离"]
FMybatis["mybatis
数据权限 · 字段加密"]
FWeb["web
限流 · XSS · 审计日志"]
FRedis["redis
缓存 · 租户前缀"]
FCommon["common
注解 · 响应 · 工具"]
end
subgraph storage["存储与中间件"]
direction LR
MySQL[("MySQL 8
业务数据")]
Redis[("Redis 6
缓存 · 限流 · 熔断")]
end
LLM["LLM 上游
DeepSeek · Qwen · GLM · ERNIE"]
Web --> AdminAPI
Mini --> AppAPI
Screen -.iframe 嵌入.- Web
AdminAPI --> biz
AppAPI --> biz
biz --> MySQL
System & ScreenBiz --> Redis
AI --> LLM
biz -.构建于.- framework
classDef clientStyle fill:#E8F1FD,stroke:#4A90D9
classDef gatewayStyle fill:#FFF3E0,stroke:#E8A23D
classDef bizStyle fill:#E8F5E9,stroke:#66A36B
classDef frameworkStyle fill:#F3E5F5,stroke:#9C6BB5
classDef storageStyle fill:#FBE9E7,stroke:#D87566
classDef externalStyle fill:#ECEFF1,stroke:#90A4AE
class Web,Mini,Screen clientStyle
class AdminAPI,AppAPI gatewayStyle
class System,Workflow,AI,ScreenBiz bizStyle
class FSecurity,FTenant,FMybatis,FWeb,FRedis,FCommon frameworkStyle
class MySQL,Redis storageStyle
class LLM externalStyle
```
## 项目简介
forge-admin 是一款现代化的企业级后台管理解决方案，采用前后端分离架构：后端基于 Spring Boot 3.4 构建，多模块 Maven 结构 + MyBatis Plus + JWT 无状态认证；前端基于 Vue 3 + TypeScript + Element Plus + vxe-table，内置多套 UI 主题切换系统与品牌信息动态配置（Logo、项目名称、登录页文案），管理后台修改后全局生效，无需重新构建。支持 Docker 容器化部署，并提供项目模板化工具，可快速基于此项目创建新的管理系统。
## 项目截图
### 登录页面
### 仪表盘
### 用户管理
### 角色管理
### 菜单管理
### 定时任务
## 功能清单
### 系统管理
| 功能 | 说明 |
|------|------|
| 用户管理 | 用户增删改查、状态控制、密码重置、部门关联、岗位分配 |
| 角色管理 | 角色增删改查、菜单权限分配、数据权限设置 |
| 菜单管理 | 菜单增删改查、路由配置、权限标识、图标设置 |
| 部门管理 | 部门树形结构、增删改查、负责人设置 |
| 岗位管理 | 岗位增删改查、状态控制 |
| 字典管理 | 字典类型和数据管理、缓存刷新 |
| 参数配置 | 系统参数增删改查、缓存刷新 |
| 品牌设置 | 项目 Logo（上传）、项目名称、登录页主/副标题运行时配置，登录页/侧边栏/顶栏/移动端菜单/标签页标题/favicon 全局生效，未配置时回退默认值 |
| 文件配置 | 文件存储配置（本地/OSS） |
| 通知公告 | 公告增删改查、发布状态管理 |
| 在线用户 | 查看在线用户、强制下线 |
| 租户管理 | 租户 CRUD（仅平台超管可见），创建时自动生成租户管理员账号 + 强密码 + 首次登录强制改密 |
| 套餐管理 | 租户套餐（菜单包）维护，支持差异化菜单分配（待接入运行时菜单过滤） |
| 租户切换 | 平台超管通过 `X-Tenant-Id` 切换操作租户上下文，前端头部下拉切换 |
### 监控中心
| 功能 | 说明 |
|------|------|
| 登录日志 | 登录记录查询、状态统计 |
| 操作日志 | 操作记录查询、审计追踪 |
| 定时任务 | 任务增删改查、执行控制、日志查看 |
| 服务监控 | 服务器状态、JVM 信息、Redis 监控 |
### 流程管理
| 功能 | 说明 |
|------|------|
| 模型管理 | 流程模型设计（FlowLong可视化设计器）、模型部署、版本管理 |
| 审批流程 | 已部署流程查看、启用/停用、版本切换 |
| 表单管理 | 表单设计（可视化拖拽）、表单配置 |
| 流程分类 | 分类树形结构、增删改查 |
| 流程实例 | 实例查询、详情查看、取消流程 |
| 待办任务 | 待办列表、审批操作（通过/驳回/委派/转办/退回/加签） |
| 已办任务 | 已办列表、审批记录查看 |
| 抄送列表 | 抄送记录查看 |
| 表达式管理 | 流程表达式增删改查 |
| 监听器管理 | 流程监听器增删改查 |
### AI 功能
| 功能 | 说明 |
|------|------|
| AI 文档管理 | 文档上传、智能摘要生成、对话问答 |
| 多模型对话 | 基于 Spring AI 直连 DeepSeek、Qwen、GLM、ERNIE 等 OpenAI 兼容模型，模型配置表驱动 |
| 文档解析 | PDF、DOCX、TXT 文档解析 |
| 流式响应 | SSE 实时流式输出 |
### 大屏管理
| 功能 | 说明 |
|------|------|
| 大屏列表 | 大屏 CRUD、按 code 访问、发布、复制、版本管理 |
| 大屏编辑器 | 基于 goView 拖拽式编辑器（iframe 嵌入），支持柱/线/饼/地图/散点等图表库 |
| 大屏渲染 | 公开访问 / 登录访问、主题切换、字段映射与自动保存草稿 |
| 数据源管理 | SQL / HTTP 两种类型，启用/禁用、缓存时长配置；敏感配置不返回列表 |
| SQL 白名单 | 表/列级白名单维护，三级风险等级（公开/内部/敏感） |
| 大屏安全 | SQL AST 校验 + 列级白名单 + HTTP SSRF 防护 + 数据源熔断器 |
### 打印管理
| 功能 | 说明 |
|------|------|
| 打印模板管理 | 模板 CRUD、按编号唯一（跨租户共享）、版本号、状态控制 |
| 模板设计器 | 基于 hiprint 的拖拽式设计器（拖元素/绑定字段/纸张/缩放/旋转/清空/导出 JSON） |
| 打印预览 | 浏览器原生打印预览（el-dialog 弹窗 + jQuery html 兼容多种返回类型） |
| 按编号调用 | 业务方通过 `GET /admin-api/system/print-template/code/{code}` 取模板 JSON 后调用打印 |
| 打印 Demo | `/demo/hiprint` 提供按编号调用打印的示例页 |
### 移动端（小程序）
| 功能 | 说明 |
|------|------|
| 微信授权登录 | 一键授权、自动注册 |
| 个人中心 | 信息编辑、头像修改、手机绑定 |
| 账号注销 | 用户账号注销 |
### 系统工具
| 功能 | 说明 |
|------|------|
| 项目模板化 | 基于模板创建新项目 |
| 模块管理 | 创建/删除业务模块 |
| API 文档 | springdoc 在线文档（Swagger UI） |
### 主题系统
| 功能 | 说明 |
|------|------|
| 预设套餐 | 10 套精心搭配的视觉套餐（默认/极客紫/商务器/酷暗黑/日暮橙/琥珀琉璃/海洋青/薄荷青/青碧岛/青碧紧凑），每套含配色 + 布局 + 风格组合 |
| 明暗双模式 | 每个套餐都支持 light/dark 双版本，独立切换不互相影响 |
| 高级设置 | 三维度独立切换：调色板（蓝/紫/绿/红/橙/青/碧/自定义）、布局（侧栏/顶栏）、风格（扁平/玻璃/卡片/紧凑） |
| 系统默认主题 | 管理后台「品牌设置」可配置默认主题（三维度 + 明暗模式），跟随用户每次进入自动应用，手动调整后固定为个人选择 |
| 自定义色板 | 输入 HEX 主色，运行时自动派生 EP 颜色阶梯（light-3/5/7/9 + dark-2），实时预览 |
| 响应式布局 | 移动端始终为侧栏布局（顶栏在小屏自动回落），保证小屏可用性 |
| 错误降级 | localStorage 损坏、未知套餐 ID、不支持 backdrop-filter 等场景均静默降级 |
| 跨版本兼容 | 老 localStorage 数据自动迁移（preset → 三维度派生），用户无感知升级 |
| 设置持久化 | localStorage 持久化（key 为 `forge_admin-page-config`），不引入后端依赖 |
## 特性
- **权限管理**：完整的 RBAC 权限系统，支持用户、角色、菜单、部门管理
- **数据权限**：支持部门数据权限隔离（5 种范围类型）
- **多租户**：B2B SaaS 多租户隔离（MyBatis Plus `TenantLineInnerInterceptor` + SQL 自动注入 + 缓存 key 前缀），可配置开关 `forge.tenant.enable`
- **OAuth2 授权服务器**：基于 Spring Authorization Server，支持授权码、客户端凭证等标准 OAuth2/OIDC 协议
- **第三方登录**：支持微信、钉钉扫码登录，基于 JustAuth 实现
- **工作流引擎**：集成 FlowLong 国产工作流引擎，支持流程设计、审批管理、待办任务、流程实例监控
- **可视化大屏**：基于 goView 的拖拽式大屏编辑器、多数据源配置、列级 SQL 白名单、SSRF 防护、数据源熔断
- **字典管理**：灵活的数据字典配置，支持缓存刷新
- **定时任务**：基于 Quartz 的定时任务管理和日志
- **文件存储**：支持本地存储，可扩展 OSS 等
- **AI 功能**：基于 Spring AI 原生实现（Java 直连上游模型），支持多模型对话、文档解析、智能摘要
- **API 文档**：springdoc-openapi 原生 Swagger UI
- **移动端支持**：独立的 `/app-api` 端点，支持微信小程序授权登录
- **强大表格**：vxe-table 提供列自定义、导出、打印等功能
- **打印模板**：基于 vue-plugin-hiprint 的拖拽式模板设计器，支持纸张/缩放/旋转、浏览器原生打印预览、按编号调用打印，模板跨租户共享
- **多套 UI 主题**：10 套预设套餐 + 7 色调色板/布局/风格三维度独立切换 + 自定义主色 + 明暗双模式 + 系统默认主题配置，CSS 变量两阶桥接（业务变量 → Element Plus/vxe-table）实现无刷新切换
- **等保二级合规**：符合 GB/T 22239-2019 二级等保要求的安全改造
- **密码安全**：复杂度校验（8-32位、大小写+数字+特殊字符）、历史校验（5条不可重复）、90天有效期、首次登录强制改密、BCrypt 强度=12
- **登录安全**：失败锁定（5次→15分钟）、图形验证码、单点登录（踢掉旧会话+refreshToken 同步失效）
- **数据加密**：AES-256-GCM 敏感字段加密（phone/email）、jasypt 配置文件加密
- **应用安全**：XSS 过滤器、安全响应头（CSP/HSTS/X-Frame-Options 等）、文件上传校验（扩展名+Magic Number）
- **审计安全**：操作日志敏感字段自动脱敏（密码/手机号/邮箱/身份证）
- **大屏模块安全**：
- **SQL 三道闸门**：AST 静态规则（SELECT-only / 禁 UNION/SET / 禁危险函数 / 禁系统表 / 必须 LIMIT）+ 表/列白名单（列级 fail-closed）+ 运行时 LIMIT/OFFSET 实参上限
- **HTTP SSRF 防护**：`forge.security.screen.allowed-hosts` host 白名单、5s 连接/读取超时、1MB 响应体上限、可选强制 HTTPS
- **数据源熔断器**：基于 Redis 滑动窗口，1 分钟内失败 10 次触发 30 秒熔断
- **访问控制**：大屏支持公开访问（免登录）和登录访问，敏感 `config` 字段不在列表接口返回
## 技术栈
### 后端
- Java 21
- Spring Boot 3.4.11
- Spring AI 1.1.8（LLM 对话/文档解析/摘要）
- MyBatis Plus 3.5.17
- MySQL 8.0+
- Redis 6.0+
- JWT 认证
- MyBatis Plus TenantLineInnerInterceptor（多租户）
- Spring Authorization Server (OAuth2/OIDC)
- JustAuth（第三方登录）
- springdoc-openapi 2.8（Swagger UI）
- Quartz 定时任务
- FlowLong 1.2.5（国产工作流引擎）
- JSqlParser 4.9（SQL 解析与 AST 校验）
- jasypt-spring-boot-starter（配置文件加密）
- AES-256-GCM + BCrypt（数据加密与密码哈希）
### 前端
- Vue 3.4
- TypeScript 5.3
- Element Plus 2.4
- vxe-table 4.9（强大表格组件）
- vxe-pc-ui 4.6
- Pinia 2.1
- Vite 5.0
- vue-plugin-hiprint 0.0.58-fix（打印模板设计器）+ jQuery（hiprint 依赖）+ lodash-es + min-dash
### 大屏编辑器
- goView 1.3.2（基于 VChart 的拖拽式大屏编辑器）
- VChart 2.0（图表渲染引擎）
- 通过 iframe 嵌入到 forge-web，组件编辑、自动保存草稿
### 移动端（小程序）
- uni-app + Vue 3
- 微信小程序授权登录
- Pinia 状态管理
- 独立的 app_user 用户表
### AI 能力（Java 原生）
- Spring AI 1.1.8（OpenAI 兼容协议直连上游）
- 多模型支持：DeepSeek、Qwen（通义）、GLM（智谱）、ERNIE（百度千帆 v2）
- 文档解析：Apache Tika（PDF、DOCX、TXT）
- SSE 流式响应（模型实例按 ai_model_config 表配置指纹缓存）
## 快速开始
### 环境要求
- JDK 21+
- Node.js 18+（推荐 22.9.0）
- pnpm 9+（lockfile 为 9.0 格式，推荐 11.x）
- MySQL 8.0+
- Redis 6.0+
- 微信开发者工具（小程序开发）
### 安装
1. **克隆项目**
```bash
git clone
cd forge-admin
```
2. **创建数据库**
```bash
mysql -u root -p -e "CREATE DATABASE IF NOT EXISTS forge_admin DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci"
mysql -u root -p forge_admin < sql/init.sql
mysql -u root -p forge_admin < sql/init-ai.sql
mysql -u root -p forge_admin < sql/init-app.sql
mysql -u root -p forge_admin < sql/init-screen.sql
mysql -u root -p forge_admin < sql/init-workflow.sql
```
3. **启动后端**
```bash
cd apps/forge-server
mvn spring-boot:run -pl forge-server
```
后端服务运行在 http://localhost:8181
4. **启动前端**
```bash
cd apps/forge-web
pnpm install
pnpm dev
```
前端服务运行在 http://localhost:3003
5. **启动大屏编辑器**（可选）
```bash
cd apps/forge-screen
pnpm install
pnpm dev
```
大屏编辑器运行在 http://localhost:8001，通过 iframe 嵌入到 forge-web 的"大屏管理 → 编辑器"页面。
6. **启动小程序**（可选）
```bash
cd apps/forge-miniapp
pnpm install
pnpm dev:mp-weixin
```
小程序开发工具导入 `dist/dev/mp-weixin` 目录
7. **访问系统**
- 前端地址：http://localhost:3003
- 大屏编辑器：http://localhost:8001
- API 文档：http://localhost:8181/swagger-ui/index.html
- 默认账号：`admin` / `password`（启用多租户时登录页需输入租户标识，默认 `default`）
- OAuth2 使用文档：[docs-base/guide/oauth2-guide.md](docs-base/guide/oauth2-guide.md)
## 开发命令
### 前端（在 `apps/forge-web` 目录下）
```bash
pnpm install # 安装依赖
pnpm dev # 启动开发服务器（端口 3003）
pnpm build # 生产构建（含类型检查）
pnpm preview # 预览生产构建
pnpm lint # 运行 ESLint
pnpm test # 运行 vitest 单元测试
```
### 大屏编辑器（在 `apps/forge-screen` 目录下）
```bash
pnpm install # 安装依赖
pnpm dev # 启动开发服务器（端口 8001）
pnpm build # 生产构建
pnpm lint # 运行 ESLint
```
### 小程序（在 `apps/forge-miniapp` 目录下）
```bash
pnpm install # 安装依赖
pnpm dev:mp-weixin # 微信小程序开发模式
pnpm build:mp-weixin # 微信小程序生产构建
```
### 后端（在 `apps/forge-server` 目录下）
```bash
mvn spring-boot:run -pl forge-server # 启动开发服务器
mvn clean compile # 仅编译
mvn clean package -DskipTests # 打包 JAR（跳过测试）
mvn test # 运行所有测试
mvn test -Dtest=ClassName -pl # 运行指定模块的单个测试类
```
## 目录结构
```
forge-admin/
├── apps/
│ ├── forge-server/ # 后端（多模块 Maven 项目）
│ │ ├── pom.xml # 根聚合 POM
│ │ ├── forge-dependencies/ # BOM 版本管理
│ │ ├── forge-framework/ # 框架层
│ │ │ ├── forge-common/ # 公共模块（注解、异常、响应、工具类）
│ │ │ ├── forge-spring-boot-starter-mybatis/ # MyBatis + 数据权限
│ │ │ ├── forge-spring-boot-starter-redis/ # Redis 配置
│ │ │ ├── forge-spring-boot-starter-security/ # JWT + OAuth2
│ │ │ ├── forge-spring-boot-starter-tenant/ # 多租户（SQL 自动注入 + 过滤器 + AOP）
│ │ │ └── forge-spring-boot-starter-web/ # Web + WebSocket
│ │ ├── forge-module-system/ # 系统模块
│ │ │ ├── forge-module-system-api/ # API 接口 + 实体 + DTO
│ │ │ └── forge-module-system-biz/ # 业务实现（含 auth、quartz）
│ │ ├── forge-module-workflow/ # 工作流模块
│ │ │ ├── forge-module-workflow-api/
│ │ │ └── forge-module-workflow-biz/
│ │ ├── forge-module-ai/ # AI 模块
│ │ │ ├── forge-module-ai-api/
│ │ │ └── forge-module-ai-biz/
│ │ ├── forge-module-screen/ # 大屏模块
│ │ │ ├── forge-module-screen-api/ # 实体 + DTO + 枚举
│ │ │ └── forge-module-screen-biz/ # Controller/Service/Mapper + safety/executor/cache/fault
│ │ └── forge-server/ # Spring Boot 启动入口
│ │
│ ├── forge-web/ # 前端应用
│ │ ├── src/
│ │ │ ├── api/ # API 接口定义
│ │ │ ├── components/ # 公共组件（含 components/hiprint 打印组件）
│ │ │ ├── composables/ # 组合式函数（useTableHeight、useTableSeq 等）
│ │ │ ├── layouts/ # 布局组件（BasicLayout 分发器 + LayoutSidebar + LayoutTop）
│ │ │ ├── plugins/ # vxe-table 全局配置
│ │ │ ├── router/ # 路由配置（动态路由）
│ │ │ ├── stores/ # Pinia 状态管理
│ │ │ ├── styles/ # 样式文件
│ │ │ ├── themes/ # 主题系统（套餐注册表 + 调色板 + 风格 + 运行时颜色派生）
│ │ │ ├── types/ # TypeScript 类型定义
│ │ │ ├── utils/ # 工具函数（含 utils/hiprint 打印工具）
│ │ │ └── views/ # 页面组件（含 views/screen 大屏管理、views/system/print 打印模板）
│ │ │ ├── screen/ # 大屏管理页面
│ │ │ │ ├── index/ # 大屏列表
│ │ │ │ ├── editor/ # 编辑器入口（iframe 嵌入 goView）
│ │ │ │ ├── preview/ # 大屏预览
│ │ │ │ ├── render/ # 公开/登录大屏渲染
│ │ │ │ ├── data-source/ # 数据源管理
│ │ │ │ └── sql-whitelist/ # SQL 白名单管理
│ │ │ ├── system/print/ # 打印模板管理（列表 + 表单 + design/ 设计器）
│ │ │ └── demo/hiprint/ # 打印调用示例页
│ │ └── package.json
│ │
│ ├── forge-screen/ # 大屏编辑器（goView，独立 SPA）
│ │ ├── src/
│ │ │ ├── api/forge/ # 与 forge-admin 通信的 API
│ │ │ ├── store/ # Pinia stores（chartEditStore，自动保存草稿）
│ │ │ ├── hooks/ # useSync、useChartDataFetch
│ │ │ ├── packages/ # 图表组件库（Bars/Lines/Pies/Maps/...）
│ │ │ └── views/chart/ # 图表编辑视图
│ │ └── package.json
│ │
│ └── forge-miniapp/ # 小程序应用
│ ├── src/
│ │ ├── api/ # API 接口定义
│ │ ├── pages/ # 页面组件
│ │ │ ├── login/ # 登录页
│ │ │ └── profile/ # 个人中心
│ │ ├── stores/ # Pinia 状态管理
│ │ ├── static/ # 静态资源（logo、头像）
│ │ └── composables/ # 组合式函数
│ └── package.json
│
├── docker/ # Docker 配置
├── scripts/ # 项目初始化脚本
├── sql/ # 数据库脚本
└── .template/ # 模板配置
```
## 架构要点
### 后端多模块架构
后端采用 16 模块的 Maven 多项目结构，各模块职责清晰：
```
forge-dependencies → BOM 版本管理
forge-framework (6模块) → 框架层，可独立版本管理（含多租户 starter）
forge-module-system (2) → 系统模块，api/biz 分离
forge-module-workflow (2) → 工作流模块，api/biz 分离（基于 FlowLong）
forge-module-ai (2) → AI 模块，api/biz 分离
forge-module-screen (2) → 大屏模块，api/biz 分离（含 SQL 安全层）
forge-server → Spring Boot 启动入口
```
每个业务模块遵循分层结构：`controller/admin/` + `controller/app/` → `service/` → `mapper/`，实体和 DTO 放在 `api` 子模块供跨模块引用。
**双端点架构：**
- `/admin-api/**` — 后台管理端点，使用 `sys_user` 表 + `@PreAuthorize` 权限控制
- `/app-api/**` — 移动端端点，使用独立的 `app_user` 表 + 微信授权登录
框架通过 `WebMvcConfigurer.configurePathMatch()` 根据 Controller 包名（`controller.admin` / `controller.app`）自动注入路径前缀，Controller 代码无需手动指定前缀。
**模块依赖关系：**
- `forge-server` ← `system-biz`、`workflow-biz`、`ai-biz`、`screen-biz`
- `workflow-biz` ← `workflow-api`、`system-api`、`starters`、`flowlong`
- `ai-biz` ← `ai-api`、`system-api`、`starters`、`spring-ai`（直连 LLM 上游）
- `system-biz` ← `system-api`、`starters`、`quartz`
- `screen-biz` ← `screen-api`、`system-api`、`starters`
**横切关注点：**
- `@OperationLog` — 基于 AOP 的审计日志
- `@DataPermission` — SQL 级数据范围过滤
- `@RateLimiter` — 基于 Redis 令牌桶的限流
- `@Cacheable/@CacheEvict` — Redis 缓存
### 大屏模块分层
`forge-module-screen-biz` 是少数按子包组织的模块，关键子包：
- `safety/` — SQL 安全三道闸门：`SqlSafetyValidator`（AST 规则：SELECT-only、禁 UNION/SET、禁危险函数、必须 LIMIT）、`SqlSafetyGuard`（编排器）、`WhitelistService`（表/列级白名单校验，列级 fail-closed）
- `executor/` — 数据源执行器：`SqlDataSourceExecutor`（动态 SQL + 参数绑定 + @DataPermission）、`HttpDataSourceExecutor`（SSRF 防护：`ScreenProperties.allowedHosts`）
- `cache/` — Redis 缓存（key = `dataSourceId + paramsJson`）
- `fault/` — 熔断器：基于 Redis 滑动窗口统计失败次数，达阈值拒绝请求
数据源表 `sys_screen_data_source.config` 含 SQL 原文/HTTP URL 等敏感信息。列表接口通过 `qw.select()` 排除 `config` 字段（详见 `SysScreenDataSourceServiceImpl.page`），详情接口正常返回以支持编辑回显。
**大屏安全 API：**
- `POST /admin-api/screen/data-source/{id}/execute` — 执行数据源（内部走 SQL 三道闸门 + 熔断器）
- `GET /admin-api/screen/code/{code}` — 按 code 加载大屏（运行时使用，`permitAll`，支持公开大屏）
- `PUT /admin-api/screen/publish/{code}` — 发布大屏（草稿覆盖到正式 config）
### 前端表格组件（vxe-table）
所有列表页面统一使用 vxe-table，提供：
- 列自定义（显示/隐藏、排序、固定）
- 数据导出（CSV、HTML、XML、TXT）
- 打印功能
- 虚拟滚动（大数据量优化）
- 树形表格（菜单、部门）
**表格命名约定：** `sys{Module}Table`（如 `sysUserTable`、`sysRoleTable`）
### 大屏编辑器集成
goView 编辑器是独立的前端 SPA（`apps/forge-screen`），通过 iframe 嵌入到 `apps/forge-web/src/views/screen/editor/` 和 `preview/`：
- 编辑：用户在 goView 中拖拽组件、绑定 forge 数据源 → 自动保存草稿到后端 `config_draft`
- 渲染：访问 `/screen/render/{code}` → 加载正式 `config` → 渲染图表
- 数据源绑定：编辑器内 `executeDataSource(id, params)` 走 SQL 三道闸门 + 熔断器
### 动态路由
后端返回菜单树 → 转换为 Vue Router 配置 → 通过 `import.meta.glob` 解析组件 → `router.addRoute()` 添加路由。
### AI 能力架构
AI 能力全部在 Java 端实现（Spring AI 直连上游模型，无独立 AI 服务进程）：
- **LlmClient / SpringAiLlmClient** — LLM 门面：非流式对话 + SSE 流式（`{"content":"…"}` 增量帧 + `[DONE]` 结束帧）
- **OpenAiChatModelFactory** — 按 `ai_model_config` 表编程式构建/缓存模型实例（配置变更指纹失效重建）
- **TikaDocumentParser / DocumentSummarizer** — 文档解析（PDF/DOCX/TXT）与三风格摘要
- **ModelHealthProbe** — 模型可用性探测（max_tokens=1 探测，密钥无效自动置不可用）
四家 provider（DeepSeek/Qwen/GLM/ERNIE）统一走 OpenAI 兼容协议，端点与密钥在「系统管理 → AI 模型配置」维护。
**API 端点：** `/admin-api/ai/chat/**`、`/admin-api/ai/document/**`、`/admin-api/ai/model/**`
### 打印模板架构
系统基于 `vue-plugin-hiprint` 实现拖拽式打印模板设计与浏览器原生打印：
- **后端**（`forge-module-system`）：`SysPrintTemplate` 实体 + DTO + Mapper + Service + Controller，提供 6 个 REST 端点（list/get/getByCode/create/update/delete）
- **前端**（`apps/forge-web`）：
- `components/hiprint/` — 复用组件（`preview.vue` 预览弹窗、`print-view.vue` 调用打印）
- `utils/hiprint/` — 工具（`template-helper.js` 模板工厂、`modal.js` 弹窗辅助）
- `views/system/print/` — 列表页 + 表单弹窗 + `design/` 设计器
- `views/demo/hiprint/` — 按编号调用打印的示例页
- **数据表 `sys_print_template`**：跨租户共享表（在 `ignore-tables` 白名单），`template_code` 全表唯一，`contents` 字段存 hiprint JSON
- **依赖**：`vue-plugin-hiprint@0.0.58-fix`、`jquery`（hiprint 内部依赖，main.ts 全局暴露 `window.$`）、`lodash-es`、`min-dash`
**关键流程：**
1. 列表 → 新增模板（填编号/名称）→ 路由跳转 `/system/print/design?id=N` 进入设计器
2. 设计器内拖拽元素、绑定字段、设置纸张/缩放 → 保存（`PUT /admin-api/system/print-template`，contents 携带 JSON）
3. 业务方调用：`GET /admin-api/system/print-template/code/{code}` 取模板 JSON → 用 `print-view.vue` 触发浏览器打印
### 权限控制
- **后端**：`@PreAuthorize("hasAuthority('system:user:list')")`
- **前端模板**：`v-permission="'system:user:add'"`
- **前端脚本**：`hasPermission('system:user:add')`
## 基于模板创建新项目
```bash
pnpm run init <项目名称> "<项目描述>" <包名>
# 示例：pnpm run init my-admin "我的管理系统" com.mycompany
```
自动扫描所有模块的 Java 源码目录，重命名包名、更新配置文件、前端标题和数据库名。详见 [docs-base/template-guide.md](docs-base/template-guide.md)。
## 模块管理
### 创建新模块
```bash
node scripts/create-module.js <模块名称> "<模块描述>"
# 示例：node scripts/create-module.js order "订单管理模块"
```
自动创建模块目录结构、pom.xml、基础类模板。
### 删除模块
```bash
./scripts/remove-module.sh <模块名称>
# 示例：./scripts/remove-module.sh workflow
```
自动从 pom.xml 移除模块引用、删除依赖关系、清理迁移脚本和模块目录。
## Docker 部署
### 全新安装
```bash
cp .env.example .env # 填写必填密钥（MySQL/Redis/JWT/AES，参考文件内注释）
docker compose up -d
```
MySQL（utf8mb4）、Redis、backend、frontend 四服务编排，健康检查依赖链自动拉起。**MySQL 首次启动时自动按序执行 `sql/` 下的初始化脚本**（建表 + 菜单/种子数据），无需手工导入；增量迁移脚本位于 `apps/forge-server/**/db/migration/`（项目未引入 Flyway，需按版本号手工执行）。
访问：http://localhost（前端）、http://localhost/swagger-ui/index.html（API 文档，生产可按等保要求在 nginx.conf 移除该代理）
### 升级
```bash
# 1. 备份数据库（数据卷不会被重建，备份仅为升级兜底）
docker exec forge-admin-mysql sh -c 'mysqldump -uroot -p"$MYSQL_ROOT_PASSWORD" --databases $MYSQL_DATABASE' > backup-$(date +%Y%m%d%H%M).sql
# 2. 拉取最新代码并重建镜像（backend 的 POM 分层缓存使增量构建较快）
git pull
docker compose build
# 3. 重建容器（mysql-data/redis-data 数据卷自动保留，初始化脚本不会重复执行）
docker compose up -d
# 4. 执行本次新增的增量迁移（项目未引入 Flyway，需按版本号顺序手工执行）
# 对比升级前后的 db/migration/ 目录，逐个执行新出现的脚本：
mysql -h 127.0.0.1 -P ${MYSQL_EXPOSE_PORT:-3306} -u root -p forge_admin \
< apps/forge-server/forge-server/src/main/resources/db/migration/V2026xxxx__xxx.sql
```
说明：
- 升级只会重建前后端容器；`docker compose down` 不带 `-v` 不会删除数据卷，**切勿在升级场景使用 `down -v`**（会清空数据库）
- `.env` 中已配置的密钥与端口在升级后保持生效，新增配置项以 `.env.example` 为准按需补充
- 升级后可用 `docker compose ps` 确认四服务健康，`docker logs -f forge-admin-backend` 观察启动日志
## 配置说明
### 后端配置（application.yml）
| 配置项 | 默认值 |
|--------|--------|
| 服务端口 | 8181 |
| 数据库 | localhost:3306/forge_admin |
| Redis | localhost:6379 |
| JWT 密钥 | （生产环境请修改） |
### 前端环境变量
| 变量 | 开发环境 | 生产环境 |
|------|----------|----------|
| 后台 API 地址 | http://localhost:8181/admin-api | /admin-api |
| 移动端 API 地址 | http://localhost:8181/app-api | /app-api |
| 大屏编辑器地址 | http://localhost:8001 | /screen-app |
### 等保安全配置（application.yml）
| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `forge.security.captcha.enabled` | true | 是否启用验证码 |
| `forge.security.captcha.length` | 4 | 验证码长度 |
| `forge.security.password.min-length` | 8 | 密码最小长度 |
| `forge.security.password.max-length` | 32 | 密码最大长度 |
| `forge.security.password.expire-days` | 90 | 密码有效期（天） |
| `forge.security.password.history-size` | 5 | 密码历史校验条数 |
| `forge.security.password.bcrypt-strength` | 12 | BCrypt 强度 |
| `forge.security.password.aes-key` | （必须配置） | AES-256 加密密钥 |
| `forge.security.login.max-fail-count` | 5 | 登录失败锁定阈值 |
| `forge.security.login.lock-minutes` | 15 | 锁定时长（分钟） |
| `forge.security.login.single-session` | true | 单点登录模式 |
| `forge.security.upload.max-size` | 10485760 | 文件上传大小限制（字节） |
**生产环境必填环境变量：**
| 变量 | 用途 |
|------|------|
| `APP_AES_KEY` | AES-256 加密密钥（32字节） |
| `JWT_SECRET` | JWT 签名密钥（≥256位） |
| `JASYPT_PASSWORD` | jasypt 配置解密密钥 |
### 大屏安全配置（application.yml）
| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `forge.security.screen.allowed-hosts` | localhost / 127.0.0.1 / forge-server | HTTP 数据源 host 白名单（SSRF 防护） |
| `forge.security.screen.http-timeout-ms` | 5000 | HTTP 连接 + 读取超时（毫秒） |
| `forge.security.screen.http-max-body-bytes` | 1048576 | HTTP 响应体最大字节（1MB） |
| `forge.security.screen.require-https` | false | 是否强制 HTTPS（生产环境建议 true） |
### 多租户配置（application.yml）
| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `forge.tenant.enable` | true | 是否启用多租户（false 时所有多租户能力关闭，回归单租户） |
| `forge.tenant.header` | X-Tenant-Id | 租户标识请求头名 |
| `forge.tenant.ignore-urls` | 登录/验证码/WebSocket 等 | 不需要 X-Tenant-Id 的 URL 白名单 |
| `forge.tenant.ignore-tables` | sys_menu / sys_role / sys_dict_* 等 | 跨租户共享表，不注入 tenant_id |
| `forge.tenant.ignore-caches` | dictData / sysConfig / menu / dept | 跨租户共享缓存，key 不加 tenantId 前缀 |
**多租户角色：**
| 角色 code | 角色 | 说明 |
|-----------|------|------|
| `SUPER_ADMIN` (id=1) | 平台超管（admin） | `account_type=2`，跨租户，可通过 `X-Tenant-Id` 切换操作租户 |
| `TENANT_ADMIN` (id=3) | 租户管理员 | 创建租户时自动生成，仅管本租户 |
| `USER` (id=2) | 普通用户 | 单租户内的普通成员 |
**多租户部署：**
- 全新初始化：直接执行 `sql/init.sql`（已集成多租户结构）
### 大屏模块
大屏模块提供两种使用方式：**全新初始化**使用 `sql/init-screen.sql`；**已有数据库增量更新**按版本号顺序手动执行模块的 `db/migration/` 脚本。
#### 全新初始化（`sql/init-screen.sql`）
`sql/init-screen.sql` 整合了模块 6 个增量脚本的全部内容（4 张表 + 7 条 SQL 白名单 + 19 条菜单/权限 + 4 条测试数据源），使用 `DROP TABLE IF EXISTS + CREATE TABLE` 模式可重复执行，仅用于一次性建库。脚本中已将 `V202607080` 的 `ALTER TABLE` 合并到 `sys_screen` 的建表语句，无需后续 `ALTER` 步骤。
```bash
mysql -u root -p forge_admin < sql/init.sql
mysql -u root -p forge_admin < sql/init-screen.sql
```
#### 增量脚本（参考）
`sql/init-screen.sql` 与模块下的增量脚本**互斥使用**。如需逐版本演进，可手动执行下列脚本（文件位于 `apps/forge-server/forge-module-screen/forge-module-screen-biz/src/main/resources/db/migration/`，命名遵循 `V{YYYYMMDD}{seq}__.sql`）：
| 增量脚本 | 说明 |
|---------|------|
| `V202607041__create_screen_tables.sql` | 创建大屏主体、数据源、SQL 白名单 3 张表，并初始化白名单数据 |
| `V202607042__insert_screen_menu_permissions.sql` | 大屏管理目录、菜单与按钮权限种子数据 |
| `V202607080__add_screen_public_fields.sql` | 大屏主体增加 `is_public` / `access_type` 字段 |
| `V202607081__add_screen_role_table.sql` | 大屏角色授权表（access_type=1 时使用） |
| `V202607090__seed_test_data_sources.sql` | 测试数据源种子数据 |
| `V202607091__add_sql_whitelist_menu.sql` | SQL 白名单菜单与按钮权限种子数据 |
### 打印模板
`sys_print_template` 表在多租户 `ignore-tables` 白名单中（跨租户共享），不注入 tenant_id。
全新初始化使用 `sql/init.sql`（已集成 sys_print_template 表 + 菜单种子）。
详见 [docs-base/guide/print-template-guide.md](docs-base/guide/print-template-guide.md)。
## 相关文档
### 流程模块(`docs-base/modules/workflow/`)
按阅读顺序排列,新接手流程模块从 `01` 开始:
| 文档 | 目标读者 | 用途 |
|------|----------|------|
| [01.workflow-usage.md](docs-base/modules/workflow/01.workflow-usage.md) | 流程管理员 / 配置人员 / 最终用户 | 流程管理菜单、完整配置流程、候选人策略、触发器任务、待办/已办、状态码 |
| [02.condition-node-guide.md](docs-base/modules/workflow/02.condition-node-guide.md) | 流程设计者 / 后端开发 | 条件节点(type=3 / type=4)实际行为、触发条件使用时机、SpEL 求值、兜底机制 |
| [03.trigger-bean-guide.md](docs-base/modules/workflow/03.trigger-bean-guide.md) | 后端开发 | 自定义 `@FlowLongTrigger` Bean、`AbstractFlowLongTrigger` 抽象基类、4 种业务模式、反射调用 |
### 其他文档
| 文档 | 用途 |
|------|------|
| [docs-base/guide/oauth2-guide.md](docs-base/guide/oauth2-guide.md) | OAuth2 授权服务器使用(第三方应用接入本系统做用户认证) |
| [docs-base/template-guide.md](docs-base/template-guide.md) | 基于本项目创建新管理系统(项目模板化) |
| [docs-base/guide/deployment-guide.md](docs-base/guide/deployment-guide.md) | 服务部署(环境变量配置、Docker Compose、镜像构建与容器运行) |
| [docs-base/guide/data-permission-guide.md](docs-base/guide/data-permission-guide.md) | 数据权限(部门级 / 本人级)使用说明 |
| [docs-base/development/database-design-specification.md](docs-base/development/database-design-specification.md) | 数据库设计规范(字段命名、索引、关联关系) |
| [docs-base/development/module-development.md](docs-base/development/module-development.md) | 新建业务模块的开发规范 |
| [docs-base/guide/print-template-guide.md](docs-base/guide/print-template-guide.md) | 打印模板使用指南（hiprint 设计器/调用打印/多租户行为/常见问题） |
## 许可证
MIT License