# rocks

**Repository Path**: smartunity/rocks

## Basic Information

- **Project Name**: rocks
- **Description**: Spring Boot 4 + PostgreSQL + Flowable 的可拆分 Starter 平台：DB/缓存/日志/监控/JWT/RBAC/工作流，前后端分离，Docker 开箱即用。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-23
- **Last Updated**: 2026-06-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Rocks Platform

Rocks 是一套**前后端分离**的企业级 Java 开发底座：后端以 Spring Boot Starter 按需组合（Core / Auth / Flow），前端为 Vue 3 管理端模板。本仓库包含完整 Demo（RBAC + 请假审批流程），业务示例与底座源码分离，便于二次开发或仅引入 Starter 构建新项目。

---

## 特性

- **模块化 Starter**：`rocks-spring-boot-starter`（核心）、`-auth`、`-flow` 按需引入
- **核心能力**：MyBatis-Plus、多 Schema 租户、Caffeine/Redis 缓存、操作日志（`@RockLog`）、JVM/缓存/DB 监控
- **权限体系**：JWT + Spring Security，用户 / 角色 / 菜单 RBAC
- **工作流**：Flowable 封装，流程部署、任务中心、BPMN 设计
- **开箱 Demo**：Docker 一键启动（PostgreSQL + Redis + 后端 + 前端）
- **演示业务**：请假审批（`rocks-samples-leave`，不随 Starter 发布）

---

## 技术栈

| 层级 | 技术 |
|------|------|
| 后端 | Java 21、Spring Boot 4.0、MyBatis-Plus、Flowable |
| 数据 | PostgreSQL 16、Redis |
| 前端 | Vue 3、Vite、Element Plus、Pinia、BPMN.js |
| 构建 | Maven 多模块、Docker Compose |

---

## 快速开始（Docker）

**前置条件**：Docker Desktop、端口 **15433 / 16379 / 8924 / 8925** 未被占用。

```bash
# 项目根目录
docker compose up -d --build
```

首次构建需下载 Maven 依赖，约 5–15 分钟。

| 地址 | 说明 |
|------|------|
| http://localhost:8924 | 前端 |
| http://localhost:8925/swagger-ui | API 文档 |
| http://localhost:8925/actuator/health | 健康检查 |

**默认账号**（密码均为 `123456`）：

| 用户名 | 用途 |
|--------|------|
| admin | 超级管理员 / 主管审批 |
| user | 普通用户 / 请假发起人 |
| manager | 总经理审批（>3 天） |
| hr | 人事备案 |

**演示路径**：`user` 发起请假 → `admin` 任务中心审批 →（可选）`manager` → `hr` → 系统监控查看操作日志与 JVM 监控。

更多细节见 [doc/QUICKSTART.md](doc/QUICKSTART.md)。

```bash
# 查看后端日志
docker compose logs -f backend

# 停止
docker compose down

# 停止并重建数据库
docker compose down -v
```

---

## 本地开发

**后端**（需本地 PostgreSQL，默认 `localhost:15432`）：

```powershell
.\start-backend.ps1
```

**前端**：

```bash
cd rocks-ui
npm install
npm run dev
```

**集成测试**：

```bash
mvn test -pl rocks-flow,rocks-log,rocks-auth -am
```

**Starter 组合验证**（Testcontainers，需 Docker + JDK 21）：

```powershell
.\scripts\verify-starters.ps1
```

详见 [rocks-starter-verify/README.md](rocks-starter-verify/README.md)。

---

## 仓库结构

| 模块 | 说明 |
|------|------|
| `rocks-spring-boot-starter` | 核心 Starter（DB、缓存、日志、监控） |
| `rocks-spring-boot-starter-auth` | 认证与 RBAC |
| `rocks-spring-boot-starter-flow` | 工作流 |
| `rocks-starter` | 全家桶（core + auth + flow，Demo 兼容） |
| `rocks-dependencies` | BOM，统一依赖版本 |
| `rocks-app` | 演示后端应用 |
| `rocks-ui` | 演示前端 |
| `rocks-samples-leave` | 请假 Demo 业务（不发布为 Maven 制品） |
| `rocks-starter-verify` | Starter 组合集成测试 |
| `doc/` | 快速启动、SQL 脚本、架构与发布规划 |

数据库初始化脚本位于 `doc/sql/`（Demo 数据在 `doc/sql/demo/`），说明见 [doc/sql/README.md](doc/sql/README.md)。

---

## 在新项目中使用 Starter

### 从源码构建（当前推荐）

```bash
# 项目根目录
mvn clean install -DskipTests
```

在新项目 `pom.xml` 中引入 BOM 与所需 Starter：

```xml
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.rocks</groupId>
      <artifactId>rocks-dependencies</artifactId>
      <version>1.0.0-SNAPSHOT</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <!-- 核心 -->
  <dependency>
    <groupId>com.rocks</groupId>
    <artifactId>rocks-spring-boot-starter</artifactId>
  </dependency>
  <!-- 按需：auth / flow -->
  <!--
  <dependency>
    <groupId>com.rocks</groupId>
    <artifactId>rocks-spring-boot-starter-auth</artifactId>
  </dependency>
  <dependency>
    <groupId>com.rocks</groupId>
    <artifactId>rocks-spring-boot-starter-flow</artifactId>
  </dependency>
  -->
</dependencies>
```

执行 `doc/sql/` 下主库脚本（不含 `demo/` 目录则为纯底座环境）。

### 推荐组合

| 场景 | 后端依赖 |
|------|----------|
| 纯 API + 日志 + 监控 | `rocks-spring-boot-starter` |
| 管理后台（用户/角色/菜单） | core + `rocks-spring-boot-starter-auth` |
| 审批 / 任务中心 | core + auth + `rocks-spring-boot-starter-flow` |
| 本仓库 Demo | `rocks-starter` + `rocks-samples-leave` |

> 引入 flow 时需配置 `rocks.flow.enabled=true`。生产环境建议使用 **core + auth + flow**，不要单独 core + flow（流程 API 无 JWT 保护）。

完整发布规划与 Starter 边界见 [doc/Rocks_starter-minimal-publish.md](doc/Rocks_starter-minimal-publish.md)。

---

## 环境要求

| 工具 | 版本 |
|------|------|
| JDK | 21 |
| Maven | 3.9+ |
| Node.js | 18+（前端开发） |
| Docker | 24+（Demo / 集成测试） |

---

## 文档

- [快速启动（Docker）](doc/QUICKSTART.md)
- [SQL 初始化说明](doc/sql/README.md)
- [Starter 发布与模块规划](doc/Rocks_starter-minimal-publish.md)
- [Starter 组合验证](rocks-starter-verify/README.md)

---

## 版本

当前版本：`1.0.0-SNAPSHOT`（v1.0-standalone：Starter 已拆分，Docker Demo 可用）

---

## License

本项目采用 [Apache License 2.0](LICENSE) 开源协议。