novalon-manage-system/README.md

# novalon-manage-system

企业级后台管理系统

## 项目结构

```
novalon-manage-system/
├── novalon-manage-api/          # 后端 API 项目
│   ├── manage-gateway/          # API 网关服务
│   ├── manage-app/              # 主应用服务
│   ├── manage-sys/              # 系统管理模块
│   ├── manage-db/               # 数据库模块
│   ├── manage-common/           # 公共模块
│   ├── manage-audit/            # 审计模块
│   ├── manage-notify/           # 通知模块
│   └── manage-file/             # 文件管理模块
├── novalon-manage-web/          # 前端 Web 项目
├── api_integration_tests/       # API 集成测试
└── e2e-tests/                   # E2E 测试
```

## 技术栈

### 后端
- Java 21
- Spring Boot 3.5.12
- Spring Cloud Gateway
- Spring Security + JWT
- R2DBC (响应式数据库访问)
- PostgreSQL 15
- Flyway (数据库迁移)

### 前端
- Vue 3 + TypeScript
- Element Plus
- Pinia (状态管理)
- Vite (构建工具)
- Playwright (E2E 测试)

## 快速开始

### 方式一：Docker Compose（推荐）

使用 Docker Compose 可以一键启动所有服务，包括数据库、后端和前端。

#### 前置要求
- Docker 20.10+
- Docker Compose 2.0+

#### 启动步骤

1. **克隆项目**
```bash
git clone <repository-url>
cd novalon-manage-system
```

2. **启动所有服务**
```bash
docker-compose up -d
```

3. **查看服务状态**
```bash
docker-compose ps
```

4. **查看日志**
```bash
# 查看所有服务日志
docker-compose logs -f

# 查看特定服务日志
docker-compose logs -f postgres
docker-compose logs -f backend
docker-compose logs -f frontend
```

5. **访问应用**
- 前端应用: http://localhost:3001
- 后端 API: http://localhost:8084
- API 文档: http://localhost:8084/swagger-ui.html
- 健康检查: http://localhost:8084/actuator/health

#### 停止服务
```bash
docker-compose down
```

#### 清理数据（包括数据库数据）
```bash
docker-compose down -v
```

### 方式二：本地开发环境

#### 1. 环境准备要求

##### 必需软件
- **Java**: JDK 21 或更高版本
- **Maven**: 3.8+ (用于后端构建)
- **Node.js**: 18+ (用于前端构建)
- **pnpm**: 8+ (推荐) 或 npm
- **PostgreSQL**: 15+ (数据库)
- **Git**: 版本控制

##### 可选软件
- **Docker**: 用于容器化部署
- **IDE**: IntelliJ IDEA (推荐) 或 VS Code

##### 系统要求
- **操作系统**: macOS, Linux, Windows
- **内存**: 最低 4GB，推荐 8GB+
- **磁盘空间**: 最低 2GB 可用空间

#### 2. 依赖安装步骤

##### 2.1 安装 Java 和 Maven

**macOS (使用 Homebrew)**:
```bash
brew install openjdk@21
brew install maven

# 设置 JAVA_HOME
echo 'export JAVA_HOME=$(/usr/libexec/java_home -v21)' >> ~/.zshrc
echo 'export PATH=$JAVA_HOME/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

# 验证安装
java -version
mvn -version
```

**Linux (Ubuntu/Debian)**:
```bash
# 安装 OpenJDK 21
sudo apt update
sudo apt install openjdk-21-jdk

# 安装 Maven
sudo apt install maven

# 验证安装
java -version
mvn -version
```

**Windows**:
1. 下载并安装 JDK 21: https://adoptium.net/
2. 下载并安装 Maven: https://maven.apache.org/download.cgi
3. 设置环境变量:
   - `JAVA_HOME`: 指向 JDK 安装目录
   - `MAVEN_HOME`: 指向 Maven 安装目录
   - `PATH`: 添加 `%JAVA_HOME%\bin` 和 `%MAVEN_HOME%\bin`

##### 2.2 安装 Node.js 和 pnpm

**使用 nvm (推荐)**:
```bash
# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 重新加载 shell
source ~/.bashrc  # 或 source ~/.zshrc

# 安装 Node.js 18
nvm install 18
nvm use 18

# 安装 pnpm
npm install -g pnpm

# 验证安装
node -v
pnpm -v
```

**macOS (使用 Homebrew)**:
```bash
brew install node
npm install -g pnpm
```

**Windows**:
1. 下载并安装 Node.js: https://nodejs.org/
2. 安装 pnpm:
```powershell
npm install -g pnpm
```

##### 2.3 安装 PostgreSQL

**macOS (使用 Homebrew)**:
```bash
brew install postgresql@15
brew services start postgresql@15

# 创建数据库和用户
psql postgres
```

在 psql 中执行:
```sql
CREATE DATABASE manage_system;
CREATE USER novalon WITH PASSWORD 'novalon123';
GRANT ALL PRIVILEGES ON DATABASE manage_system TO novalon;
\q
```

**Linux (Ubuntu/Debian)**:
```bash
sudo apt install postgresql-15 postgresql-contrib-15
sudo systemctl start postgresql

# 创建数据库和用户
sudo -u postgres psql
```

在 psql 中执行:
```sql
CREATE DATABASE manage_system;
CREATE USER novalon WITH PASSWORD 'novalon123';
GRANT ALL PRIVILEGES ON DATABASE manage_system TO novalon;
\q
```

**Windows**:
1. 下载并安装 PostgreSQL: https://www.postgresql.org/download/windows/
2. 使用 pgAdmin 创建数据库和用户，或使用命令行工具

##### 2.4 验证环境

创建并运行环境检查脚本:
```bash
# 检查 Java
java -version
mvn -version

# 检查 Node.js
node -v
pnpm -v

# 检查 PostgreSQL
psql --version
```

#### 3. 数据库初始化

##### 3.1 配置数据库连接

后端使用 Flyway 自动管理数据库迁移，数据库表结构会在首次启动时自动创建。

**开发环境配置** (`novalon-manage-api/manage-app/src/main/resources/application-dev.yml`):
```yaml
spring:
  r2dbc:
    url: r2dbc:postgresql://localhost:55432/manage_system
    username: novalon
    password: novalon123
  flyway:
    enabled: true
```

**生产环境配置** (`novalon-manage-api/manage-app/src/main/resources/application-prod.yml`):
```yaml
spring:
  r2dbc:
    url: r2dbc:postgresql://postgres:5432/novalon_manage
    username: ${DB_USERNAME}
    password: ${DB_PASSWORD}
  flyway:
    enabled: true
```

##### 3.2 手动初始化数据库（可选）

如果需要手动初始化数据库，可以执行以下 SQL 脚本:

```bash
# 连接到数据库
psql -U novalon -d manage_system

# 执行初始化脚本
\i novalon-manage-api/manage-db/src/main/resources/db/migration/V1__Create_all_tables.sql
\i novalon-manage-api/manage-db/src/main/resources/db/migration/V2__Insert_initial_data.sql
\i novalon-manage-api/manage-db/src/main/resources/db/migration/V3__Create_indexes.sql
\i novalon-manage-api/manage-db/src/main/resources/db/migration/V4__Create_permission_tables.sql

# 退出
\q
```

##### 3.3 验证数据库连接

```bash
# 测试数据库连接
psql -U novalon -d manage_system -c "SELECT version();"

# 查看已创建的表
psql -U novalon -d manage_system -c "\dt"
```

#### 4. 后端网关服务配置说明

##### 4.1 网关服务概述

`manage-gateway` 是系统的 API 网关，负责:
- 请求路由和转发
- JWT 认证过滤
- RBAC 权限控制
- 请求重试机制
- 限流和熔断

##### 4.2 网关配置文件

**主配置** (`novalon-manage-api/manage-gateway/src/main/resources/application.yml`):
```yaml
server:
  port: 8080

spring:
  application:
    name: manage-gateway
  cloud:
    gateway:
      routes:
        - id: manage-app
          uri: http://localhost:8084
          predicates:
            - Path=/api/**
      default-filters:
        - name: JwtAuthentication
        - name: RbacAuthorization
        - name: Retry
          args:
            retries: 3
            statuses: BAD_GATEWAY,SERVICE_UNAVAILABLE
            methods: GET,POST
            backoff:
              firstBackoff: 10ms
              maxBackoff: 50ms
              factor: 2
              basedOnPreviousValue: false

jwt:
  secret: ${JWT_SECRET:mySecretKeyForNovalonManageSystem2024}
  expiration: ${JWT_EXPIRATION:86400000}

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics
      base-path: /actuator
  endpoint:
    health:
      show-details: always
  metrics:
    tags:
      application: ${spring.application.name}

logging:
  level:
    cn.novalon.manage: DEBUG
    org.springframework.cloud.gateway: DEBUG
```

##### 4.3 网关路由配置

网关将所有 `/api/**` 路径的请求转发到 `manage-app` 服务 (端口 8084)。

**路由规则**:
- 所有以 `/api/` 开头的请求都会被转发到后端服务
- 请求会经过 JWT 认证和 RBAC 权限验证
- 失败的请求会自动重试（最多 3 次）

##### 4.4 JWT 配置

**环境变量**:
- `JWT_SECRET`: JWT 密钥（生产环境必须设置强密钥）
- `JWT_EXPIRATION`: Token 过期时间（毫秒，默认 24 小时）

**示例**:
```bash
export JWT_SECRET="your-strong-secret-key-here"
export JWT_EXPIRATION="86400000"
```

##### 4.5 网关健康检查

```bash
# 检查网关健康状态
curl http://localhost:8080/actuator/health

# 查看网关信息
curl http://localhost:8080/actuator/info

# 查看网关指标
curl http://localhost:8080/actuator/metrics
```

#### 5. 完整的项目启动步骤

##### 5.1 启动后端服务

**步骤 1: 进入后端项目目录**
```bash
cd novalon-manage-api
```

**步骤 2: 编译项目**
```bash
mvn clean install -DskipTests
```

**步骤 3: 启动网关服务**
```bash
cd manage-gateway
mvn spring-boot:run
```

网关将在 `http://localhost:8080` 启动。

**步骤 4: 启动主应用服务**
打开新的终端窗口:
```bash
cd novalon-manage-api/manage-app
mvn spring-boot:run
```

主应用将在 `http://localhost:8084` 启动。

**步骤 5: 验证后端服务**
```bash
# 检查网关健康状态
curl http://localhost:8080/actuator/health

# 检查应用健康状态
curl http://localhost:8084/actuator/health

# 访问 API 文档
open http://localhost:8084/swagger-ui.html
```

##### 5.2 启动前端服务

**步骤 1: 进入前端项目目录**
```bash
cd novalon-manage-web
```

**步骤 2: 安装依赖**
```bash
pnpm install
```

**步骤 3: 配置环境变量**

创建 `.env.local` 文件（如果不存在）:
```env
VITE_API_BASE_URL=http://localhost:8080
VITE_APP_TITLE=Novalon管理系统
```

**步骤 4: 启动开发服务器**
```bash
pnpm dev
```

前端应用将在 `http://localhost:5173` 启动。

**步骤 5: 访问应用**
在浏览器中打开: http://localhost:5173

#### 6. 不同环境的启动命令和配置差异

##### 6.1 环境配置文件

后端支持多环境配置:
- `application.yml`: 主配置文件
- `application-dev.yml`: 开发环境配置
- `application-test.yml`: 测试环境配置
- `application-prod.yml`: 生产环境配置
- `application-metrics.yml`: 监控指标配置

##### 6.2 开发环境启动

**后端**:
```bash
cd novalon-manage-api/manage-app
mvn spring-boot:run -Dspring-boot.run.profiles=dev
```

**前端**:
```bash
cd novalon-manage-web
pnpm dev
```

**特点**:
- 使用本地数据库 (localhost:55432)
- DEBUG 日志级别
- 热重载启用
- Swagger UI 可用

##### 6.3 测试环境启动

**后端**:
```bash
cd novalon-manage-api/manage-app
mvn spring-boot:run -Dspring-boot.run.profiles=test
```

**前端**:
```bash
cd novalon-manage-web
pnpm dev:test
```

**特点**:
- 使用测试数据库
- INFO 日志级别
- 性能监控启用
- 测试数据可用

##### 6.4 生产环境启动

**后端**:
```bash
# 设置环境变量
export DB_USERNAME=your_prod_db_user
export DB_PASSWORD=your_prod_db_password
export JWT_SECRET=your_prod_jwt_secret

# 启动应用
cd novalon-manage-api/manage-app
mvn spring-boot:run -Dspring-boot.run.profiles=prod
```

**前端构建**:
```bash
cd novalon-manage-web
pnpm build:prod
```

**前端部署**:
```bash
# 使用 nginx 或其他静态文件服务器部署 dist 目录
pnpm preview
```

**特点**:
- 使用生产数据库
- INFO/WARN 日志级别
- 性能优化
- 安全加固
- Swagger UI 禁用

##### 6.5 Docker 环境启动

**使用 docker-compose**:
```bash
# 开发环境
docker-compose -f docker-compose.yml up -d

# 测试环境
docker-compose -f docker-compose.test.yml up -d
```

**特点**:
- 容器化部署
- 服务编排
- 健康检查
- 自动重启

#### 7. 常见启动问题的故障排除指南

##### 7.1 端口冲突问题

**症状**:
```
Port 8080 was already in use
```

**解决方案**:
```bash
# 查找占用端口的进程
lsof -i :8080  # macOS/Linux
netstat -ano | findstr :8080  # Windows

# 终止进程
kill -9 <PID>  # macOS/Linux
taskkill /PID <PID> /F  # Windows

# 或修改配置文件中的端口
# 在 application.yml 中修改 server.port
```

##### 7.2 数据库连接失败

**症状**:
```
Connection refused: localhost:55432
```

**解决方案**:
```bash
# 检查 PostgreSQL 服务状态
brew services list | grep postgresql  # macOS
systemctl status postgresql  # Linux

# 启动 PostgreSQL 服务
brew services start postgresql@15  # macOS
sudo systemctl start postgresql  # Linux

# 检查数据库连接
psql -U novalon -d manage_system -c "SELECT 1;"

# 检查防火墙设置
sudo ufw allow 5432  # Linux
```

##### 7.3 Maven 依赖下载失败

**症状**:
```
Could not resolve dependencies
```

**解决方案**:
```bash
# 清理 Maven 缓存
rm -rf ~/.m2/repository

# 使用国内镜像源
# 在 ~/.m2/settings.xml 中配置阿里云镜像
mvn clean install -U

# 检查网络连接
ping repo.maven.apache.org
```

##### 7.4 前端依赖安装失败

**症状**:
```
npm ERR! network request failed
```

**解决方案**:
```bash
# 清理缓存
pnpm store prune

# 使用国内镜像源
pnpm config set registry https://registry.npmmirror.com

# 重新安装
rm -rf node_modules
pnpm install
```

##### 7.5 JWT 认证失败

**症状**:
```
401 Unauthorized
Invalid JWT token
```

**解决方案**:
```bash
# 检查 JWT_SECRET 配置
echo $JWT_SECRET

# 确保前后端使用相同的 JWT 密钥
# 检查网关和应用的配置文件

# 重新生成 Token
# 使用登录接口获取新的 JWT Token
```

##### 7.6 Flyway 迁移失败

**症状**:
```
FlywayException: Validate failed
```

**解决方案**:
```bash
# 查看迁移历史
psql -U novalon -d manage_system -c "SELECT * FROM flyway_schema_history;"

# 修复失败的迁移
# 1. 备份数据库
# 2. 修复迁移脚本
# 3. 删除失败的迁移记录
# 4. 重新运行迁移

# 或手动修复
psql -U novalon -d manage_system
DELETE FROM flyway_schema_history WHERE success = false;
\q
```

##### 7.7 内存不足错误

**症状**:
```
Java heap space
OutOfMemoryError
```

**解决方案**:
```bash
# 增加 JVM 内存
export MAVEN_OPTS="-Xmx2g -Xms1g"

# 或在 pom.xml 中配置
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-surefire-plugin</artifactId>
  <configuration>
    <argLine>-Xmx2g</argLine>
  </configuration>
</plugin>
```

##### 7.8 CORS 跨域问题

**症状**:
```
Access to XMLHttpRequest blocked by CORS policy
```

**解决方案**:
```bash
# 检查网关 CORS 配置
# 在 application.yml 中添加:
spring:
  cloud:
    gateway:
      globalcors:
        cors-configurations:
          '[/**]':
            allowedOrigins: "http://localhost:5173"
            allowedMethods:
              - GET
              - POST
              - PUT
              - DELETE
              - OPTIONS
            allowedHeaders: "*"
            allowCredentials: true
```

##### 7.9 日志查看和调试

**查看应用日志**:
```bash
# 后端日志
tail -f novalon-manage-api/manage-app/logs/application.log

# 网关日志
tail -f novalon-manage-api/manage-gateway/logs/application.log

# Docker 日志
docker-compose logs -f backend
docker-compose logs -f gateway
```

**启用 DEBUG 日志**:
```yaml
# 在 application.yml 中设置
logging:
  level:
    root: DEBUG
    cn.novalon.manage: DEBUG
    org.springframework: DEBUG
```

#### 8. 启动成功后的验证方法

##### 8.1 后端服务验证

**健康检查**:
```bash
# 网关健康检查
curl http://localhost:8080/actuator/health

# 应用健康检查
curl http://localhost:8084/actuator/health

# 预期输出:
# {"status":"UP"}
```

**API 文档访问**:
```bash
# 在浏览器中打开
open http://localhost:8084/swagger-ui.html

# 或使用 curl
curl http://localhost:8084/swagger-ui.html
```

**数据库连接验证**:
```bash
# 检查数据库表是否创建成功
psql -U novalon -d manage_system -c "\dt"

# 预期输出应包含以下表:
# users, roles, menus, sys_dict_type, sys_dict_data, etc.
```

**API 端点测试**:
```bash
# 测试登录接口
curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'

# 预期输出:
# {"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}
```

##### 8.2 前端应用验证

**应用访问**:
```bash
# 在浏览器中打开
open http://localhost:5173
```

**功能验证清单**:
- [ ] 登录页面正常显示
- [ ] 能够成功登录（使用默认账号 admin/admin123）
- [ ] 主页面正常加载
- [ ] 菜单导航正常工作
- [ ] 用户管理功能可用
- [ ] 角色管理功能可用
- [ ] 系统配置功能可用

**浏览器控制台检查**:
```javascript
// 打开浏览器开发者工具 (F12)
// 检查 Console 标签页，确保没有错误信息
// 检查 Network 标签页，确认 API 请求正常
```

##### 8.3 集成测试验证

**运行 API 集成测试**:
```bash
cd api_integration_tests
pip install -r requirements.txt
pytest tests/ -v
```

**运行 E2E 测试**:
```bash
cd novalon-manage-web
pnpm test:e2e
```

##### 8.4 性能验证

**后端性能测试**:
```bash
# 使用 k6 进行性能测试
cd novalon-manage-api/manage-sys/src/test/k6
k6 run performance-test.js
```

**前端性能测试**:
```bash
cd novalon-manage-web
pnpm test:perf
```

##### 8.5 监控和日志

**查看应用指标**:
```bash
# 查看应用指标
curl http://localhost:8084/actuator/metrics

# 查看特定指标
curl http://localhost:8084/actuator/metrics/jvm.memory.used
```

**查看日志**:
```bash
# 查看应用日志
tail -f novalon-manage-api/manage-app/logs/application.log

# 查看错误日志
grep ERROR novalon-manage-api/manage-app/logs/application.log
```

##### 8.6 完整验证脚本

创建验证脚本 `verify-setup.sh`:
```bash
#!/bin/bash

echo "=== Novalon 管理系统启动验证 ==="

# 1. 检查后端服务
echo "1. 检查网关服务..."
if curl -s http://localhost:8080/actuator/health | grep -q "UP"; then
  echo "✓ 网关服务正常"
else
  echo "✗ 网关服务异常"
  exit 1
fi

echo "2. 检查应用服务..."
if curl -s http://localhost:8084/actuator/health | grep -q "UP"; then
  echo "✓ 应用服务正常"
else
  echo "✗ 应用服务异常"
  exit 1
fi

# 3. 检查数据库
echo "3. 检查数据库连接..."
if psql -U novalon -d manage_system -c "SELECT 1;" > /dev/null 2>&1; then
  echo "✓ 数据库连接正常"
else
  echo "✗ 数据库连接失败"
  exit 1
fi

# 4. 检查前端服务
echo "4. 检查前端服务..."
if curl -s http://localhost:5173 > /dev/null 2>&1; then
  echo "✓ 前端服务正常"
else
  echo "✗ 前端服务异常"
  exit 1
fi

echo "=== 所有服务验证通过 ==="
```

运行验证脚本:
```bash
chmod +x verify-setup.sh
./verify-setup.sh
```

## 功能模块

### 已完成功能

- ✅ 用户管理 - 完整的用户CRUD操作、角色分配、状态管理
- ✅ 角色管理 - 角色定义、权限配置、菜单关联
- ✅ 菜单管理 - 菜单树结构、路由配置、权限控制
- ✅ 权限管理 - 权限定义、角色授权、API权限控制
- ✅ 操作日志 - 登录日志、异常日志、操作记录
- ✅ 字典管理 - 字典类型管理、字典数据管理、数据字典
- ✅ 系统配置 - 系统参数配置、配置管理、缓存刷新
- ✅ 审计中心 - 审计日志、操作审计、安全审计
- ✅ 通知中心 - 通知公告、用户消息、消息推送
- ✅ 文件管理 - 文件上传、文件下载、文件预览
- ✅ WebSocket消息推送 - 实时通知、消息推送、在线状态

### 核心特性

- **响应式编程**: 基于Spring WebFlux的异步非阻塞架构
- **JWT认证**: 无状态Token认证，支持Token刷新
- **权限控制**: 基于角色的访问控制(RBAC)
- **实时通信**: WebSocket支持实时消息推送
- **文件预览**: 支持图片、PDF、文本文件的在线预览
- **逻辑删除**: 支持数据的软删除和恢复
- **审计日志**: 完整的操作审计和安全审计

## 开发指南

### 后端开发

```bash
cd novalon-manage-api
mvn clean install
mvn spring-boot:run
```

### 前端开发

```bash
cd novalon-manage-web
pnpm install
pnpm dev
```

### 测试

```bash
# 后端单元测试
cd novalon-manage-api
mvn test

# 前端单元测试
cd novalon-manage-web
pnpm test

# E2E 测试
cd novalon-manage-web
pnpm test:e2e

# API 集成测试
cd api_integration_tests
pytest tests/
```

## 部署

### Docker 部署

```bash
# 构建镜像
docker-compose build

# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f
```

### 生产环境部署

详见部署文档 [DEPLOYMENT.md](./docs/DEPLOYMENT.md)

## 故障排除

### 常见问题

1. **端口冲突**: 修改 `application.yml` 中的端口配置
2. **数据库连接失败**: 检查 PostgreSQL 服务状态和连接配置
3. **JWT 认证失败**: 确认前后端使用相同的 JWT 密钥
4. **CORS 跨域问题**: 配置网关的 CORS 设置

详细故障排除指南请参考 [TROUBLESHOOTING.md](./docs/TROUBLESHOOTING.md)

## 贡献指南

欢迎贡献代码！请阅读 [CONTRIBUTING.md](./docs/CONTRIBUTING.md) 了解详细信息。

## License

MIT