# flame **Repository Path**: doublecc/flame ## Basic Information - **Project Name**: flame - **Description**: 基于 Solon + Vue 3 + Naive UI 的全栈企业级应用框架。内置权限管理、组织架构、工作流引擎和可视化设计器，支持单体与微服务双模式部署。 - **Primary Language**: Java - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 1 - **Created**: 2026-07-20 - **Last Updated**: 2026-07-20 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README
Flame Admin Logo

Flame Admin

![Java](https://img.shields.io/badge/Java-21-blue?logo=openjdk) ![Solon](https://img.shields.io/badge/Solon-4.0.3-6DB33F) ![Vue](https://img.shields.io/badge/Vue-3.5-4FC08D?logo=vue.js) ![Naive UI](https://img.shields.io/badge/Naive_UI-2.44-306BFF) ![Vite](https://img.shields.io/badge/Vite-6.4-646CFF?logo=vite) ![License](https://img.shields.io/badge/License-MIT-yellow)
--- ## 📋 项目简介 **Flame Admin** 是一个基于 **Solon + Vue 3 + Naive UI** 的全栈企业级应用开发框架，支持单体和微服务两种部署模式。它由企业级低代码平台演进而来，内置了完整的权限管理、组织架构、工作流引擎和可视化设计器等核心业务能力，开箱即用。 ### ✨ 核心特性 - **双模式部署** — 单体架构一键启动（port 10000），微服务架构（Nacos + SocketD RPC）按需拆分，同一套代码适配两种场景 - **Contract/Impl 分离** — 借鉴 DDD 的契约设计，DTO 与实现完全解耦，天然适配微服务 RPC 调用 - **可视化设计器** — 基于 Groovy 脚本引擎的动态表单/模块/数据集设计器，支持在线编写逻辑并动态生效 - **工作流引擎** — 集成 warm-flow，支持复杂审批流转（转办、委派、会签、加减签等），配合设计器实现业务驱动 - **完备的权限体系** — Sa-Token RBAC + 按钮级权限注解 + 数据权限隔离 + 多租户 SaaS 支持 - **26 个公共库模块** — 涵盖 ORM/Redis/缓存/限流/脱敏/国际化/文件存储/Excel/日志等企业级通用能力 - **字典框架** — 双层次架构（枚举字典 + 数据库字典），通过同一个 `DictItemSelector` 组件统一加载，后端 `options()` API 透明切换内存与数据库查询 - **字段翻译系统** — 自注册式声明翻译规则，序列化前自动将枚举/ID 翻译为中文名，零运行时开销 - **现代前端架构** — Vue 3 Composition API + Naive UI + UnoCSS + Pinia，组件自动导入，开发效率高 --- ## 🔧 技术栈 | 类别 | 选型 | |------|------| | 后端框架 | Solon 4.0.3 | | ORM | Mybatis-Flex 1.11.8 | | 权限认证 | Sa-Token (RBAC, 按钮级权限) | | 数据库 | MySQL（主）+ PostgreSQL（支持） | | 缓存 | Redis + Redisson | | 工作流 | warm-flow 1.8.8 | | 脚本引擎 | Groovy 4.0.24 | | 接口文档 | Knife4j (OpenAPI2) | | 微服务通信 | SocketD + Nami RPC | | 服务注册 | Nacos | | 前端框架 | Vue 3.5 + Naive UI 2.44 | | 构建工具 | Vite 6.0 | | 样式方案 | UnoCSS | | 状态管理 | Pinia | --- ## 🎯 后端架构设计亮点 | 设计 | 说明 | 详情 | |------|------|------| | **字典体系** | 双层次架构：枚举字典通过 `@DictAnno` + `DictItem` 定义，启动时自动注册到 `DictionaryUtil`，零数据库开销；数据库字典以 `std_system_dictionary` 表存储，支持三级树形结构和运行时 CRUD。前端通过统一的 `DictItemSelector` 加载，传入 `dictKey`（UUID 或编码），后端 `options()` API 先查枚举内存再查数据库表，透明切换。枚举值通过 Mybatis-Flex `DictItemTypeHandler` 自动互转（存 value 不存 ordinal），Entity 中可直接用枚举字段。 | [字典框架](./docs/Dictionary-字典框架.md) | | **字段翻译系统(Trans)** | DTO 通过 `static TransFields` 声明翻译规则（`new TransField<>(..., "dictItemNameTranslator").to("typeName")`），`TransField` 在类加载时自动注册。`TransAspect` 拦截所有 Controller 返回值，`TransUtil` 递归遍历对象图收集待翻译字段，按翻译器分组批量翻译。内置 7 个翻译器（字典枚举、组织树路径、模块名、模板详情、用户名、流程分类名、状态名）。结果写入 DTO 字段 + `@JsonAnyGetter` 展平到 JSON 顶层。翻译失败只记日志不阻断响应。 | [Trans-字段翻译框架](./docs/Trans-字段翻译框架.md) | | **统一异常处理** | `ExceptionTranslateFilter`（Solon Filter）捕获所有请求异常，按子类优先匹配 `ExceptionTranslator`，翻译为统一 `ApiResult` 响应。内置 5 个翻译器：`ServiceExceptionTranslator`（业务异常 → 500）、`NotLoginExceptionTranslator`（未登录 → 401）、`NotPermissionExceptionTranslator`（无权限 → 403）、`SmsBlendExceptionTranslator`（短信异常 → 500）和 `DefaultExceptionTranslator`（兜底 → 500）。微服务 RPC 请求直接上抛由调用方处理。 | [异常处理翻译框架](./docs/Exception-异常处理翻译框架.md) | | **Validator 契约验证** | 提供 `isTrue`/`notNull`/`notBlank`/`notEmpty`/`contains`/`fail` 等静态方法，在 Service 层进行业务校验。验证失败抛出 `ServiceException`，由异常框架统一处理。与 Controller 层 `@Validated` 互补：前者负责参数格式，后者负责业务逻辑校验。 | [异常处理翻译框架](./docs/Exception-异常处理翻译框架.md#validator-契约式验证) | | **微服务上下文传播** | 6 段过滤器链按 `FilterIndex` 排序：安全头清除 → SameToken/RequestId 加载 → 上下文生成 → 异常处理 → SameToken 校验 → 身份注入。单体模式下 ThreadLocal 直接共享；微服务模式下网关将用户信息写入请求头转发，下游提取到 ThreadLocal，RPC 调用时 `RpcClientHeaderLoadFilter` 写入 SocketD 元数据。 | [双模式架构](./docs/双模式架构-单体与微服务.md#5-上下文传递threadlocal-vs-请求头) | | **Contract/Impl 分离** | `flame-contract-*` 只放 DTO 和接口，`flame-module-*` 放实现。依赖单向（Impl → Contract），Contract 可打成轻量 jar 供 RPC 调用方依赖无需引入实现。DTO 变更不影响实体层，实体重构不影响 API 定义。 | [AGENTS.md](./AGENTS.md#contractimpl-模式) | | **BaseEntity 层次体系** | 接口混合 + 抽象类提供 10 种实体基类变体（`I`~`ICUDT`），按需组合。自引用泛型支持链式 setter。`SysOnSaveListener` 自动填充 `createTime/createUser` 和 `updateTime/updateUser`，通过 `instanceof` 判断无侵入。 | [Mybatis-Flex集成](./docs/Mybatis-Flex集成.md#baseentity实体基类体系) | | **DTO 元数据驱动** | `BaseMeta` 持有 `Map meta`，动态字段通过 default 接口方法提供类型安全 getter/setter。设计器动态表单的根基——无反射，序列化性能好。 | [AGENTS.md](./AGENTS.md#dto-元数据驱动basedtom-/-basemeta) | | **批量操作+分布式锁** | `BatchRecord` 追踪每条记录状态。流程：`CompletableFuture` 并行预加载 → Redisson `RLock` 防并发 → 验证 → MapStruct 转换 → `saveBatch()` → 事务后回调。`BatchSummary` 汇总结果，实现高并发下的安全批量 CRUD。 | [AGENTS.md](./AGENTS.md#批量操作--分布式锁模式) | | **权限系统** | `@PermAnno` + `@PermAnnoItem` 声明权限常量组，`PermUtil.register()` 启动时反射注册到全局表。`@CheckPerm` 支持 `orRoles` 回退——权限不足时降级检查角色。`@CheckLogin` 直接从 `SessionContext` 判断不走 Redis。`@CheckIgnore` 用于白名单接口。 | [Sa-Token集成与自定义](./docs/Sa-Token集成与自定义.md#权限注册系统) | | **数据脱敏** | `@Sensitive` 标注字段（手机号、身份证等），Jackson 序列化时按当前用户权限动态脱敏。数据库存原文，只序列化环节拦截，数据面零改动。 | [AGENTS.md](./AGENTS.md#数据脱敏jackson-序列化拦截) | | **操作日志** | `@Logging` 注解声明日志规则，Solon `RouterInterceptor` 拦截记录请求参数/响应/耗时/客户端信息，通过 `EventBus` 异步持久化，不阻塞主流程。 | [AGENTS.md](./AGENTS.md#操作日志aop--异步事件) | | **Groovy 脚本引擎** | `GroovyClassLoader` 编译脚本为 Class，`ActionPlugin` 提供 before/after 钩子。结果缓存在 ConcurrentMap，Redisson Topic 广播缓存失效。支持 `DesignCondition` 条件树编译为 SQL。 | [AGENTS.md](./AGENTS.md#设计器-groovy-脚本引擎) | | **雪花 ID 协调** | 各实例竞争 Redis `setIfAbsent` 分配 workerId，60 秒心跳维持租约，`@Destroy` 释放。崩溃后租约超时自动释放，避免 ID 冲突。 | [AGENTS.md](./AGENTS.md#redisson-雪花-id-协调) | --- ## 📁 项目结构 ``` flame/ # ── Maven 根项目 │ ├── flame-common/ # 26 个公共库模块 │ ├── flame-common-aom/ # 外部依赖统一版本管理 │ ├── flame-common-bom/ # common 模块 BOM │ ├── flame-common-core/ # 核心 (Solon, Jackson, 校验, BaseEntity, ApiResult) │ ├── flame-common-utils/ # 工具类 (Hutool, ip2region) │ ├── flame-common-orm/ # ORM (Mybatis-Flex, HikariCP) │ ├── flame-common-redis/ # Redis + Redisson │ ├── flame-common-thread/ # 线程池 + 本地调度 │ ├── flame-common-dict/ # 字典管理 │ ├── flame-common-i18n/ # 国际化 │ ├── flame-common-cron/ # 定时任务 │ ├── flame-common-docs/ # Knife4j 接口文档 │ ├── flame-common-context/ # 请求/登录上下文 │ ├── flame-common-security/ # 身份认证 (Sa-Token) │ ├── flame-common-web/ # Web 安全防护 │ ├── flame-common-fstore/ # 文件存储 (S3, 本地) │ ├── flame-common-social/ # 社交登录 (JustAuth) │ ├── flame-common-sms/ # 短信 (sms4j) │ ├── flame-common-sensitive/ # 数据脱敏 │ ├── flame-common-ratelimit/ # 限流 (Redisson) │ ├── flame-common-mail/ # 邮件 (Jakarta Mail) │ ├── flame-common-log/ # 操作日志 │ ├── flame-common-repeat/ # 幂等性 │ ├── flame-common-excel/ # Excel (FastExcel) │ ├── flame-common-encrypt/ # 加解密 │ ├── flame-common-realtime/ # 实时推送 (SSE/WebSocket) │ └── flame-common-event/ # 事件总线 │ ├── flame-module/ # 8 个业务模块 (4 Contract + 4 Impl) │ ├── flame-contract-auth/ # 认证 API (DTO + LoginStrategy 接口) │ ├── flame-module-auth/ # 认证实现 │ ├── flame-contract-system/ # 系统管理 API (DTO + RemoteService 接口) │ ├── flame-module-system/ # 系统管理实现 │ ├── flame-contract-design/ # 设计器 API (DTO + Model) │ ├── flame-module-design/ # 设计器实现 (Groovy 脚本引擎) │ ├── flame-contract-workflow/ # 工作流 API (DTO + Event) │ └── flame-module-workflow/ # 工作流实现 (warm-flow) │ ├── flame-cloud/ # 6 个微服务模块 │ ├── flame-cloud-basic/ # 微服务基础库 (Nacos, SocketD, Nami) │ ├── flame-cloud-service/ # 微服务公共库 │ ├── flame-service-gate/ # API 网关 (Solon Cloud Gateway) │ ├── flame-service-core/ # 核心微服务 (system + design + workflow) │ ├── flame-service-auth/ # 认证微服务 │ └── flame-service-demo/ # 演示服务 │ ├── flame-boot/ # 单体部署 (port 10000) ├── flame-support/ # 运维支撑 (预留) │ ├── flame-ui/ # ── 前端 (Vue 3 + Naive UI) │ └── src/ │ ├── api/ # 全局 API (登录, 用户, 资源) │ ├── assets/ # 静态资源 │ ├── build/ # Vite 插件 │ ├── components/ │ │ ├── common/ # 通用组件 (AppLogo, CommonPage, AppCard...) │ │ ├── standard/ # StdTable, StdModal │ │ ├── selector/ # 14 个选择器组件 │ │ ├── me/ # MeCrud, MeModal │ │ └── Process/ # 工作流组件 │ ├── composables/ # useCrud, useForm, useModal... │ ├── directives/ # v-permission, v-loading │ ├── layouts/ # empty / full / normal / simple │ ├── locales/ # 国际化 │ ├── mock/ # Mock 数据 │ ├── router/ # 基础路由 + 动态路由 │ │ └── guards/ # 路由守卫 (权限/标题/Tab) │ ├── store/ # 8 个 Pinia 模块 │ ├── styles/ # 全局样式 │ ├── utils/ # HTTP 客户端, 存储, naive 工具 │ └── views/ │ ├── app/perm/ # 角色管理 │ ├── app/orgm/ # 组织管理 (组织/用户/岗位/职称) │ ├── app/system/ # 13 个系统子模块 │ ├── app/design/ # 设计器 (模块/动作/数据集/模板) │ ├── app/workflow/ # 工作流 (定义/实例/任务) │ ├── login/ # 登录页 │ ├── home/ # 仪表盘 (ECharts) │ └── profile/ # 个人中心 │ ├── sql/ # 数据库脚本 ├── scripts/ # 工具脚本 └── docs/ # 文档与资源 ├── images/ # 图片资源 (logo 等) └── screenshots/ # 界面截图 ``` --- ## 🏗 架构 ![系统架构图](docs/images/架构图.png) ### 单体模式（默认） ``` flame-boot (port 10000) ←── flame-ui (port 3200, /api 代理) ``` ### 微服务模式 ``` flame-service-gate (port 10000) ←── flame-ui (port 3200, /api 代理) ├── flame-service-core (port 10010, system + design + workflow) ├── flame-service-auth (port 10020, 认证服务) └── flame-service-demo (port 11000, 演示服务) ``` 服务注册至 **Nacos**，服务间调用通过 **SocketD + Nami RPC**。 --- ## 🚀 快速开始 ### 环境要求 - JDK 21+ - Node.js 20+ - MySQL 8.0+ - Redis 7+ ### 后端启动 ```bash # 运行单体模式 (port 10000) mvn solon:run -pl flame-boot ``` > 首次运行前需要先执行 `mvn clean install -DskipTests` 完成全量构建，后续只需用 `solon:run` 启动。 ### 前端启动 ```bash cd flame-ui npm install npm run dev # 启动于 http://localhost:3200 ``` 开发服务器将 `/api` 代理至 `http://127.0.0.1:10000`。 ### 微服务模式 ```bash # 先启动 Nacos (默认: localhost:8848) # 分别启动（各开一个终端） mvn solon:run -pl flame-cloud/flame-service-gate mvn solon:run -pl flame-cloud/flame-service-core mvn solon:run -pl flame-cloud/flame-service-auth ``` > 首次运行前需要先执行 `mvn clean install -DskipTests` 完成全量构建，后续只需用 `solon:run` 启动。 --- ## 📦 构建命令 ### 后端 | 命令 | 说明 | |------|------| | `mvn clean install -DskipTests` | 全量构建，跳过测试 | | `mvn clean package -DskipTests` | 打包所有模块 | | `mvn test -Dtest=ClassName#methodName` | 运行单个测试 | | `mvn clean install -pl flame-module/flame-module-system` | 构建指定模块 | | `mvn clean package -DskipTests -pl flame-boot` | 打包单体应用 | | `mvn clean package -DskipTests -pl flame-cloud/flame-service-core` | 打包核心微服务 | | `mvn clean package -DskipTests -pl flame-cloud/flame-service-auth` | 打包认证微服务 | | `mvn clean package -DskipTests -pl flame-cloud/flame-service-gate` | 打包 API 网关 | | `mvn clean package -DskipTests -pl flame-cloud/flame-service-demo` | 打包演示服务 | ### 前端 | 命令 | 说明 | |------|------| | `npm run dev` | 启动开发服务器 (port 3200) | | `npm run build` | 构建生产版本 | | `npm run preview` | 预览生产构建 | | `npm run lint:fix` | ESLint 自动修复 | --- ## 📐 后端核心规范 详细规范请参阅 [AGENTS.md](./AGENTS.md#5-后端重要约束)。 | 规范 | 要点 | |------|------| | **Contract/Impl 模式** | Contract 模块仅放 DTO 和接口，Impl 模块放 Controller/Service/Entity | | **Entity 命名** | System/Auth/Workflow 用 `Std` 前缀，Design 不用前缀 | | **Entity 基类** | 继承 `BaseEntity` 变体（`I`/`IC`/`ICU`/`ICUD`/`ICD`/`IT`/`ICT`/`ICUT`/`ICDT`/`ICUDT`） | | **DTO 模式** | `CreateForm`、`ModifyForm`、`QueryForm extends BaseSearch`、`Detail extends BaseMeta` | | **Converter** | MapStruct，`Mappers.getMapper()` 模式，放在 `domain.conv` 包 | | **权限类** | `@PermAnno` 标注，`@PermAnnoItem` 定义常量，继承 `PermBase` | | **事务** | `@Transaction(org.noear.solon.data.annotation.Transaction)`，标注在方法级别 | --- ## 🎨 前端核心规范 详细规范请参阅 [AGENTS.md](./AGENTS.md#7-前端代码规范)。 - **JavaScript 仅**（不使用 TypeScript），Vue 3 `