# reglow-admin（Java版本）

**Repository Path**: reglow-ai/reglow-admin-java

## Basic Information

- **Project Name**: reglow-admin（Java版本）
- **Description**: Java版本，使用AI工具，重塑面向企业的生产级后台管理系统，后端基础库未抽离，前端组件库未抽离。不依赖reglow-library和reglow-design，适合单项目使用独立使用。
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-24
- **Last Updated**: 2026-10-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ReglowAdmin - 通用后台管理系统 (Java)

> 基于 Spring Boot 3.3 的企业级通用后台管理系统（Java 版），与 Node.js / Python / Rust 版四语言同构。
> 内嵌 **reglow 基础库 0.14.2**（34 个 L2 同构模块 + 1 个 Java 侧 `seed` 初始化模块），
> 前端为 **@reglow/design 0.8.3 + @reglow/reui 0.6.8**。

## 项目构成

| 目录              | 说明                                                                                         |
| ----------------- | -------------------------------------------------------------------------------------------- |
| `backend-java/`   | Spring Boot 3.3 多模块后端                                                                   |
| `frontend-admin/` | Vue 3 + Vite 管理端前端（[reglow-design](https://gitee.com/reglow-ai/reglow-design) 子模块） |

## 前端子模块（Git Submodule）

`frontend-admin/` 是 reglow-design 的 Git 子模块（版本锁定，由 gitee 仓库管理，无需手动同步副本）。

**克隆项目时需一并拉取子模块**：

```bash
git clone --recurse-submodules git@gitee.com:reglow-ai/reglow-admin-java.git
# 或已克隆后执行：
git submodule update --init --recursive
```

**前端更新**（reglow-design 发版后同步最新）：

```bash
git submodule update --remote --merge frontend-admin
git add frontend-admin && git commit -m "chore: 同步 reglow-design 最新" && git push
```

## 技术栈

| 技术                             | 版本  | 说明                  |
| -------------------------------- | ----- | --------------------- |
| Java                             | 21    | 编程语言              |
| Spring Boot                      | 3.3.5 | 应用框架              |
| Spring Data JPA + Hibernate      | -     | ORM 数据访问          |
| Spring Security + JJWT           | 0.12  | 认证授权              |
| Redis（Lettuce + commons-pool2） | -     | 缓存 / 会话（可降级） |
| Flyway                           | -     | 数据库迁移            |
| SpringDoc OpenAPI                | 2.6   | API 文档              |
| MinIO                            | 8.5   | 对象存储              |
| MapStruct                        | 1.6   | 对象映射              |
| Lombok                           | 1.18  | 简化样板代码          |
| MySQL Connector                  | 9.0   | 数据库驱动（生产）    |
| SQLite（xerial）                 | -     | 本地开发默认数据库    |

## 架构设计

### 五层架构

```
Controller → DTO → Service → Repository → Entity
  路由层     验证层   业务层     数据层      模型层
```

> 路由职责由 `@RestController` + `@RequestMapping` 注解承担，`@ComponentScan` 启动时自动扫描注册。

### Maven 多模块

```
backend-java/
├── reglow-core/      # 核心框架层（缓存 / 安全 / Redis / 存储 / 支付 / 短信 / 邮件等抽象）
├── reglow-common/    # 公共组件层（异常 / 响应 / 工具 / 中间件）
├── reglow-modules/   # 业务模块层（34 个通用模块 + seed 初始化器）
├── demo-modules/     # 管理端业务示例模块（默认仅保留包声明）
└── reglow-server/    # 应用启动层（Spring Boot 主类 + 环境配置）
```

### 基础模块（34 个 L2 同构模块）

| 分类         | 模块                                                                            |
| ------------ | ------------------------------------------------------------------------------- |
| 系统与权限   | auth / employee / role / menu / dept / post / dict / config / log               |
| 内容与素材   | article / photo / video / material / agreement / notice / message               |
| 商业化与平台 | payment / billing / tenant / principal / principal_member / open_api / workflow |
| AI 与数据    | ai / ai_usage / skill / studio / analytics / dashboard                          |
| 其他         | user / region / wechat / customer_service / security                            |

> 另有 Java 侧 `seed`（`DataInitializer`，L3 独有）负责建库后的基础数据播种，不计入 34 个共同模块。
> 模块面由 `reglow-library/contract/modules.json` 统一登记，四语言保持同构。

### 统一响应格式

成功码为 `code=0`、`success=true`、字段 snake_case，与共享前端 `@reglow/design` 契约一致：

```json
{ "code": 0, "success": true, "msg": "操作成功", "data": { ... } }
```

分页响应：

```json
{ "code": 0, "success": true, "msg": "操作成功", "data": { "items": [...], "total": 100, "page": 1, "size": 20 } }
```

### 多端点分离

| 端点             | 路径                   | 状态      |
| ---------------- | ---------------------- | --------- |
| 管理后台 API     | `/admin/api/v1/`       | ✅ 已实现 |
| 客户端 API       | `/api/v1/`             | ✅ 已实现 |
| 健康检查         | `/actuator/health`     | ✅ 已实现 |
| Prometheus 指标  | `/actuator/prometheus` | ✅ 已实现 |
| 静态文件（上传） | `/uploads/`            | ✅ 已实现 |

## 更新 reglow 库（重要注意事项）

本项目以「库模式」内嵌 reglow 基础库源码，与 [reglow-library](https://gitee.com/reglow-ai/reglow-library) 的 `reglow-java` 保持同步。升级时从 reglow-library 拷贝对应模块的 `src` 代码覆盖即可。

**与 Node.js / Python / Rust 版的差异**：这三版的库代码是独立的自包含 `reglow/` 目录（管理端代码全部在目录之外），可直接整目录覆盖；而 **Java 版不能整目录覆盖**——库的 4 个 Maven 模块（`reglow-common/core/modules/server`）与管理端的业务模块 `demo-modules` 平级混排在同一个 `backend-java` 结构中，部分管理端定制文件就位于库模块目录内部，覆盖会丢失。

以下**管理端定制文件必须保留**，不得被库版本覆盖：

| 文件                                                | 原因（覆盖后的后果）                                                              |
| --------------------------------------------------- | --------------------------------------------------------------------------------- |
| 根 `pom.xml`                                        | 含 `<module>demo-modules</module>`，覆盖后业务模块脱离构建                        |
| `reglow-server/pom.xml`                             | 含 `demo-modules` 依赖，覆盖后服务端不再依赖业务代码                              |
| `reglow-server/.../ReglowApplication.java`          | `scanBasePackages` 含 `com.demo.modules`，覆盖后业务 Controller 不被扫描注册      |
| `reglow-server/src/main/resources/application*.yml` | 管理端定制（默认 SQLite / 生产 MySQL / SpringDoc / Scalar），覆盖后回退库默认配置 |
| `demo-modules/`                                     | 业务示例模块，仅存在于管理端                                                      |

### 升级步骤

```bash
# 1) 从 reglow-library 拷贝库代码（仅 src，覆盖同名文件、新增库新文件）
robocopy reglow-library/reglow-java/reglow-common/src  backend-java/reglow-common/src  /E /IS /IT
robocopy reglow-library/reglow-java/reglow-core/src    backend-java/reglow-core/src    /E /IS /IT
robocopy reglow-library/reglow-java/reglow-modules/src backend-java/reglow-modules/src /E /IS /IT
robocopy reglow-library/reglow-java/reglow-server/src/main/java \
        backend-java/reglow-server/src/main/java /E /IS /IT /XF ReglowApplication.java

# 2) 同步父 POM 与各模块版本号（reglow-java 父 POM 版本 → backend-java/pom.xml）
#    当前版本：0.14.2

# 3) 同步数据库脚本参考
copy reglow-library/reglow-java/db/schema.sql backend-java/db/schema.sql

# 4) 确认保留：根 pom.xml、reglow-server/pom.xml、ReglowApplication.java、application*.yml、demo-modules/

# 5) 构建验证
cd backend-java && mvn clean install -DskipTests
```

> 提示：若业务模块 `demo-modules` 弃用、或不再需要管理端环境定制，可改为整目录覆盖，但请确认上述文件确实不需要。

## 核心特性

- **五层架构**：Controller → DTO → Service → Repository → Entity，职责清晰、不可越界
- **JWT 双 Token**：Access Token（默认 120 分钟）+ Refresh Token（默认 7 天），`SessionManager` 管理设备级会话
- **多级缓存**：Redis（分布式）+ 内存（本地降级），支持 TTL、主动失效
- **Redis 熔断器**：Redis 不可用时自动切换内存降级，30 秒后自动探测恢复
- **数据权限**：`DataScopeProvider` 支持 ALL / DEPT / SELF / CUSTOM 级别
- **多租户部署模式**：`DEPLOY_MODE=single_tenant | saas_multi_tenant`，JWT claim → `X-Tenant-Id`，fail-closed + 启动自检
- **对象存储抽象**：`StorageProvider` 统一接口，支持本地 / S3（MinIO、OSS、COS）
- **短信 / 支付多 Provider**：统一抽象接口，支持 Mock 模式；支付含退款 / 分账 / 关单闭环
- **智能客服**：知识库问答、转人工排队（坐席容量 FIFO、`queue_update` 推送）与 SDK 模板
- **可观测性**：Actuator 暴露 health / metrics / prometheus，集成 Prometheus + Grafana

## 快速开始

### 前置条件

| 组件   | 版本要求 | 说明                           |
| ------ | -------- | ------------------------------ |
| JDK    | 21+      | 必需                           |
| Maven  | 3.9+     | 必需                           |
| SQLite | -        | 默认数据库（零依赖，开箱即用） |
| MySQL  | 8.0+     | 可选，`DB_DRIVER=mysql` 切换   |
| Redis  | 7+       | 可选，不可用时自动降级内存实现 |

### 1. 配置环境变量

```bash
cd backend-java
# 参考 .env.example 设置环境变量（Spring 通过环境变量读取；容器部署时由 env 注入）
# 本地开发可全部使用默认值：SQLite + 内存降级 Redis
```

### 2. 构建项目

```bash
mvn clean install -DskipTests
```

### 3. 启动服务

```bash
cd backend-java
mvn spring-boot:run -pl reglow-server
# 或指定环境
mvn spring-boot:run -pl reglow-server -Dspring-boot.run.profiles=dev
```

### 4. 访问服务

| 服务          | 地址                                      |
| ------------- | ----------------------------------------- |
| Swagger UI    | http://localhost:8080/api/docs/swagger    |
| API Docs      | http://localhost:8080/api/docs            |
| Scalar 调试台 | http://localhost:8080/scalar              |
| 健康检查      | http://localhost:8080/actuator/health     |
| Prometheus    | http://localhost:8080/actuator/prometheus |

### 5. 默认账号

| 角色       | 用户名    | 密码     |
| ---------- | --------- | -------- |
| 超级管理员 | rootadmin | admin123 |
| 演示账号   | demo      | demo123  |

### 6. 前端启动

```bash
cd frontend-admin
npm install
npm run dev
```

默认访问 http://localhost:5178。Vite 代理默认指向 `http://127.0.0.1:8000`，Java 后端为 8080，请在 `frontend-admin/vite.config.ts` 中调整代理目标。

## 开发脚本

```bash
# 开发环境启动
mvn spring-boot:run -pl reglow-server -Dspring-boot.run.profiles=dev

# 生产环境打包
mvn clean package -pl reglow-server -DskipTests
java -jar reglow-server/target/reglow-server-0.14.2.jar --spring.profiles.active=prod
```

## 当前状态

- ✅ `reglow-core`：核心框架层已实现（缓存 / 安全 / Redis / 存储 / 支付 / 短信 / 邮件 / 限流 / 可观测性）
- ✅ `reglow-common`：公共组件层已实现（统一响应 / 错误码 / 全局异常 / 日志 / 租户 / TraceId）
- ✅ `reglow-modules`：业务模块层已实现 34 个通用模块（对齐 `contract/modules.json` 与共享前端契约）
- ✅ `reglow-server`：应用启动层已就绪，通用路由已自动注册
- ✅ `seed`：启动时幂等播种菜单、角色、部门、字典、默认账号等基础数据

## 关联项目

| 项目                                                        | 说明                           |
| ----------------------------------------------------------- | ------------------------------ |
| [reglow-library/reglow-java](../reglow-library/reglow-java) | reglow Java 基础库（拷贝来源） |
| [reglow-admin-python](../reglow-admin-python)               | Python 版后台                  |
| [reglow-admin-nodejs](../reglow-admin-nodejs)               | Node.js 版后台                 |
| [reglow-admin-rust](../reglow-admin-rust)                   | Rust 版后台                    |
| [reglow-design](https://gitee.com/reglow-ai/reglow-design)  | 共享管理端前端基座             |

## 许可证

Apache License 2.0