feat(contract): 新增合同余额功能及重构文件管理
重构合同文件管理逻辑，增加错误处理和日志记录 新增ContractBalance实体、Repository和VO类 完善Voable接口文档和实现规范 更新项目架构文档和数据库设计 修复SmbFileService的连接问题 移动合同相关TabSkin类到contract包 添加合同文件重建任务的WebSocket支持
This commit is contained in:
517
DEVELOPMENT_GUIDE.md
Normal file
517
DEVELOPMENT_GUIDE.md
Normal file
@@ -0,0 +1,517 @@
|
||||
# Contract-Manager 开发环境配置指南
|
||||
|
||||
## 📋 系统要求
|
||||
|
||||
### 基础环境
|
||||
- **操作系统**: Windows 10/11, macOS, Linux
|
||||
- **Java版本**: JDK 21+
|
||||
- **Maven版本**: Maven 3.8+
|
||||
- **MySQL版本**: MySQL 8.0+
|
||||
- **Redis版本**: Redis 6.0+
|
||||
- **内存**: 最少 8GB RAM (推荐 16GB+)
|
||||
- **磁盘**: 最少 10GB 可用空间
|
||||
|
||||
### 开发工具 (推荐)
|
||||
- **IDE**: IntelliJ IDEA 2023+
|
||||
- **数据库工具**: MySQL Workbench, DataGrip
|
||||
- **缓存工具**: Redis Desktop Manager
|
||||
- **API测试**: Postman, Insomnia
|
||||
- **版本控制**: Git
|
||||
|
||||
## 🛠️ 开发工具安装
|
||||
|
||||
### 1. Java 21 安装
|
||||
|
||||
#### Windows
|
||||
1. 下载 [OpenJDK 21](https://adoptium.net/download/)
|
||||
2. 运行安装程序，选择安装路径 (如: `C:\Program Files\Java\jdk-21`)
|
||||
3. 设置环境变量:
|
||||
```bash
|
||||
# JAVA_HOME
|
||||
JAVA_HOME=C:\Program Files\Java\jdk-21
|
||||
|
||||
# PATH (添加到现有PATH末尾)
|
||||
%JAVA_HOME%\bin
|
||||
```
|
||||
|
||||
#### macOS
|
||||
```bash
|
||||
# 使用 Homebrew 安装
|
||||
brew install openjdk@21
|
||||
|
||||
# 设置环境变量 (添加到 ~/.zshrc 或 ~/.bash_profile)
|
||||
export JAVA_HOME=$(/usr/libexec/java_home -v 21)
|
||||
export PATH=$JAVA_HOME/bin:$PATH
|
||||
```
|
||||
|
||||
#### Linux (Ubuntu/Debian)
|
||||
```bash
|
||||
# 安装 OpenJDK 21
|
||||
sudo apt update
|
||||
sudo apt install openjdk-21-jdk
|
||||
|
||||
# 设置环境变量
|
||||
echo 'export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64' >> ~/.bashrc
|
||||
echo 'export PATH=$JAVA_HOME/bin:$PATH' >> ~/.bashrc
|
||||
source ~/.bashrc
|
||||
```
|
||||
|
||||
### 2. Maven 安装
|
||||
|
||||
#### Windows
|
||||
1. 下载 [Apache Maven](https://maven.apache.org/download.cgi)
|
||||
2. 解压到 `C:\Maven\apache-maven-3.9.x`
|
||||
3. 设置环境变量:
|
||||
```bash
|
||||
# MAVEN_HOME
|
||||
MAVEN_HOME=C:\Maven\apache-maven-3.9.x
|
||||
|
||||
# PATH
|
||||
%MAVEN_HOME%\bin
|
||||
```
|
||||
|
||||
#### macOS
|
||||
```bash
|
||||
# 使用 Homebrew 安装
|
||||
brew install maven
|
||||
|
||||
# 验证安装
|
||||
mvn -version
|
||||
```
|
||||
|
||||
#### Linux
|
||||
```bash
|
||||
# Ubuntu/Debian
|
||||
sudo apt install maven
|
||||
|
||||
# 验证安装
|
||||
mvn -version
|
||||
```
|
||||
|
||||
### 3. IntelliJ IDEA 配置
|
||||
|
||||
#### 插件安装 (推荐)
|
||||
- **Lombok Plugin**: 支持 Lombok 注解
|
||||
- **Maven Helper**: Maven 依赖管理
|
||||
- **Rainbow Brackets**: 括号颜色区分
|
||||
- **Database Tools**: 数据库操作支持
|
||||
|
||||
#### 项目导入
|
||||
1. 启动 IntelliJ IDEA
|
||||
2. 选择 "Open" 或 "Import Project"
|
||||
3. 选择项目根目录的 `pom.xml`
|
||||
4. 等待 Maven 导入完成
|
||||
5. 设置 JDK 为 Java 21
|
||||
|
||||
#### 代码风格配置
|
||||
1. File → Settings → Editor → Code Style → Java
|
||||
2. 导入项目提供的代码风格配置 (如存在)
|
||||
3. 设置自动格式化规则
|
||||
|
||||
## 📁 项目配置
|
||||
|
||||
### 1. 环境变量配置
|
||||
|
||||
创建项目根目录下的 `.env` 文件:
|
||||
```bash
|
||||
# 数据库配置
|
||||
DB_HOST=localhost
|
||||
DB_PORT=3306
|
||||
DB_USERNAME=contract_manager
|
||||
DB_PASSWORD=your_password
|
||||
DB_DATABASE=contract_manager
|
||||
|
||||
# Redis 配置
|
||||
REDIS_HOST=localhost
|
||||
REDIS_PORT=6379
|
||||
REDIS_PASSWORD=
|
||||
|
||||
# 服务端口配置
|
||||
SERVER_PORT=8080
|
||||
CLIENT_PORT=8081
|
||||
|
||||
# 文件存储配置
|
||||
FILE_BASE_PATH=C:/contract_files
|
||||
|
||||
# 云服务 API 密钥 (如有)
|
||||
CLOUD_RK_API_KEY=your_rk_api_key
|
||||
CLOUD_TYC_API_KEY=your_tyc_api_key
|
||||
CLOUD_U8_API_KEY=your_u8_api_key
|
||||
|
||||
# 日志配置
|
||||
LOG_LEVEL=INFO
|
||||
LOG_PATH=./logs
|
||||
|
||||
# 开发环境配置
|
||||
SPRING_PROFILES_ACTIVE=dev
|
||||
```
|
||||
|
||||
### 2. 数据库配置
|
||||
|
||||
#### MySQL 安装与配置
|
||||
```bash
|
||||
# Ubuntu/Debian
|
||||
sudo apt install mysql-server
|
||||
|
||||
# 启动 MySQL 服务
|
||||
sudo systemctl start mysql
|
||||
sudo systemctl enable mysql
|
||||
|
||||
# 安全配置
|
||||
sudo mysql_secure_installation
|
||||
```
|
||||
|
||||
#### 创建数据库和用户
|
||||
```sql
|
||||
-- 登录 MySQL
|
||||
mysql -u root -p
|
||||
|
||||
-- 创建数据库
|
||||
CREATE DATABASE contract_manager CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
|
||||
|
||||
-- 创建用户
|
||||
CREATE USER 'contract_manager'@'localhost' IDENTIFIED BY 'your_password';
|
||||
|
||||
-- 授权
|
||||
GRANT ALL PRIVILEGES ON contract_manager.* TO 'contract_manager'@'localhost';
|
||||
FLUSH PRIVILEGES;
|
||||
```
|
||||
|
||||
#### 数据初始化
|
||||
```bash
|
||||
# 导入数据库结构
|
||||
mysql -u contract_manager -p contract_manager < docs/db/structs.sql
|
||||
|
||||
# 导入初始数据 (如需要)
|
||||
mysql -u contract_manager -p contract_manager < docs/db/initial_data.sql
|
||||
```
|
||||
|
||||
### 3. Redis 配置
|
||||
|
||||
#### Redis 安装
|
||||
```bash
|
||||
# Ubuntu/Debian
|
||||
sudo apt install redis-server
|
||||
|
||||
# 启动 Redis
|
||||
sudo systemctl start redis-server
|
||||
sudo systemctl enable redis-server
|
||||
|
||||
# 测试连接
|
||||
redis-cli ping
|
||||
# 应该返回: PONG
|
||||
```
|
||||
|
||||
#### Redis 配置优化 (开发环境)
|
||||
```bash
|
||||
# 编辑 Redis 配置文件
|
||||
sudo nano /etc/redis/redis.conf
|
||||
|
||||
# 推荐配置 (开发环境)
|
||||
maxmemory 256mb
|
||||
maxmemory-policy allkeys-lru
|
||||
save 900 1
|
||||
save 300 10
|
||||
save 60 10000
|
||||
```
|
||||
|
||||
## 🚀 项目运行
|
||||
|
||||
### 1. 项目构建
|
||||
```bash
|
||||
# 克隆项目 (如使用 Git)
|
||||
git clone <project-url>
|
||||
cd Contract-Manager
|
||||
|
||||
# 清理并编译
|
||||
mvn clean compile
|
||||
|
||||
# 运行测试
|
||||
mvn test
|
||||
|
||||
# 打包 (生产环境)
|
||||
mvn clean package -DskipTests
|
||||
```
|
||||
|
||||
### 2. 启动服务
|
||||
|
||||
#### 方式一: 分模块启动
|
||||
```bash
|
||||
# 启动服务端
|
||||
cd server
|
||||
mvn spring-boot:run
|
||||
|
||||
# 新终端窗口 - 启动客户端
|
||||
cd client
|
||||
mvn jfx:run
|
||||
```
|
||||
|
||||
#### 方式二: Maven 工具启动
|
||||
```bash
|
||||
# 启动服务端
|
||||
mvn spring-boot:run -pl server
|
||||
|
||||
# 新终端窗口 - 启动客户端
|
||||
mvn jfx:run -pl client
|
||||
```
|
||||
|
||||
#### 方式三: IDE 启动
|
||||
1. **服务端**: 运行 `com.ecep.contract.ContractApplication`
|
||||
2. **客户端**: 运行客户端的启动类
|
||||
|
||||
### 3. 访问应用
|
||||
- **服务端**: http://localhost:8080
|
||||
- **客户端**: 运行 JavaFX 应用后打开界面
|
||||
- **API 文档**: http://localhost:8080/swagger-ui.html
|
||||
|
||||
## 📝 开发流程
|
||||
|
||||
### 1. 日常开发
|
||||
```bash
|
||||
# 获取最新代码
|
||||
git pull origin main
|
||||
|
||||
# 创建功能分支
|
||||
git checkout -b feature/your-feature-name
|
||||
|
||||
# 开发功能...
|
||||
|
||||
# 提交代码
|
||||
git add .
|
||||
git commit -m "feat: add new feature description"
|
||||
|
||||
# 推送分支
|
||||
git push origin feature/your-feature-name
|
||||
|
||||
# 创建 Pull Request
|
||||
```
|
||||
|
||||
### 2. 代码质量检查
|
||||
```bash
|
||||
# 代码检查
|
||||
mvn checkstyle:check
|
||||
|
||||
# 静态分析
|
||||
mvn spotbugs:check
|
||||
|
||||
# 测试覆盖率
|
||||
mvn jacoco:report
|
||||
```
|
||||
|
||||
### 3. 数据库迁移
|
||||
```bash
|
||||
# 执行数据库脚本
|
||||
mysql -u contract_manager -p contract_manager < docs/db/your_migration.sql
|
||||
|
||||
# 或使用 Flyway (如已配置)
|
||||
mvn flyway:migrate
|
||||
```
|
||||
|
||||
## 🔧 IDE 配置
|
||||
|
||||
### IntelliJ IDEA 配置
|
||||
|
||||
#### 代码样式
|
||||
```xml
|
||||
<!-- 设置 UTF-8 编码 -->
|
||||
File → Settings → Editor → File Encodings → Global Encoding: UTF-8
|
||||
|
||||
<!-- 设置 JDK -->
|
||||
File → Project Structure → Project → SDK: 21
|
||||
```
|
||||
|
||||
#### Maven 配置
|
||||
```xml
|
||||
<!-- 设置本地仓库路径 -->
|
||||
File → Settings → Build → Maven → User Settings File: settings.xml
|
||||
|
||||
<!-- 设置 Maven HOME -->
|
||||
File → Settings → Build → Maven → Maven home directory: /path/to/maven
|
||||
```
|
||||
|
||||
#### 插件配置
|
||||
```xml
|
||||
<!-- Lombok 插件 -->
|
||||
Settings → Build → Compiler → Annotation Processors → Enable annotation processing
|
||||
|
||||
<!-- 代码格式化 -->
|
||||
Settings → Tools → External Tools → 配置格式化命令
|
||||
```
|
||||
|
||||
### Git 配置
|
||||
```bash
|
||||
# 设置用户信息
|
||||
git config --global user.name "Your Name"
|
||||
git config --global user.email "your.email@example.com"
|
||||
|
||||
# 设置默认分支
|
||||
git config --global init.defaultBranch main
|
||||
|
||||
# 启用自动换行转换
|
||||
git config --global core.autocrlf true
|
||||
```
|
||||
|
||||
## 🔍 常见问题
|
||||
|
||||
### 1. 编译错误
|
||||
|
||||
#### Java 版本不匹配
|
||||
```bash
|
||||
# 检查 Java 版本
|
||||
java -version
|
||||
|
||||
# 设置正确的 JAVA_HOME
|
||||
echo $JAVA_HOME
|
||||
```
|
||||
|
||||
#### 依赖下载失败
|
||||
```bash
|
||||
# 清理 Maven 仓库
|
||||
mvn dependency:purge-local-repository
|
||||
|
||||
# 强制更新依赖
|
||||
mvn clean install -U
|
||||
```
|
||||
|
||||
### 2. 数据库连接问题
|
||||
|
||||
#### 连接被拒绝
|
||||
```bash
|
||||
# 检查 MySQL 服务状态
|
||||
sudo systemctl status mysql
|
||||
|
||||
# 检查端口占用
|
||||
netstat -an | grep 3306
|
||||
```
|
||||
|
||||
#### 权限问题
|
||||
```sql
|
||||
-- 检查用户权限
|
||||
SHOW GRANTS FOR 'contract_manager'@'localhost';
|
||||
|
||||
-- 重新授权
|
||||
GRANT ALL PRIVILEGES ON contract_manager.* TO 'contract_manager'@'localhost';
|
||||
FLUSH PRIVILEGES;
|
||||
```
|
||||
|
||||
### 3. Redis 连接问题
|
||||
|
||||
#### Redis 服务未启动
|
||||
```bash
|
||||
# 启动 Redis
|
||||
sudo systemctl start redis-server
|
||||
|
||||
# 检查 Redis 状态
|
||||
sudo systemctl status redis-server
|
||||
```
|
||||
|
||||
#### 端口占用
|
||||
```bash
|
||||
# 检查 Redis 端口
|
||||
netstat -an | grep 6379
|
||||
|
||||
# 重启 Redis
|
||||
sudo systemctl restart redis-server
|
||||
```
|
||||
|
||||
### 4. 客户端启动问题
|
||||
|
||||
#### JavaFX 版本不匹配
|
||||
```xml
|
||||
<!-- 检查 pom.xml 中的 JavaFX 版本 -->
|
||||
<properties>
|
||||
<maven.compiler.release>21</maven.compiler.release>
|
||||
<javafx.version>21</javafx.version>
|
||||
</properties>
|
||||
```
|
||||
|
||||
#### 依赖冲突
|
||||
```bash
|
||||
# 清理客户端模块
|
||||
cd client
|
||||
mvn clean
|
||||
|
||||
# 重新导入依赖
|
||||
mvn dependency:tree
|
||||
```
|
||||
|
||||
## 📚 有用的命令
|
||||
|
||||
### Maven 命令
|
||||
```bash
|
||||
# 清理项目
|
||||
mvn clean
|
||||
|
||||
# 编译
|
||||
mvn compile
|
||||
|
||||
# 打包
|
||||
mvn package
|
||||
|
||||
# 运行测试
|
||||
mvn test
|
||||
|
||||
# 运行特定测试
|
||||
mvn test -Dtest=CompanyServiceTest
|
||||
|
||||
# 跳过后测试打包
|
||||
mvn package -DskipTests
|
||||
|
||||
# 查看依赖树
|
||||
mvn dependency:tree
|
||||
|
||||
# 依赖分析
|
||||
mvn dependency:analyze
|
||||
```
|
||||
|
||||
### 数据库操作
|
||||
```bash
|
||||
# 连接到数据库
|
||||
mysql -u contract_manager -p
|
||||
|
||||
# 备份数据库
|
||||
mysqldump -u contract_manager -p contract_manager > backup.sql
|
||||
|
||||
# 恢复数据库
|
||||
mysql -u contract_manager -p contract_manager < backup.sql
|
||||
|
||||
# 查看表结构
|
||||
SHOW TABLES;
|
||||
DESCRIBE table_name;
|
||||
```
|
||||
|
||||
### Redis 操作
|
||||
```bash
|
||||
# 连接 Redis
|
||||
redis-cli
|
||||
|
||||
# 查看所有键
|
||||
KEYS *
|
||||
|
||||
# 清空数据库
|
||||
FLUSHDB
|
||||
|
||||
# 监控命令
|
||||
redis-cli monitor
|
||||
```
|
||||
|
||||
## 🎯 性能优化建议
|
||||
|
||||
### 开发环境优化
|
||||
1. **使用 SSD 硬盘**: 加快构建和部署速度
|
||||
2. **增加内存**: 至少 8GB RAM，推荐 16GB+
|
||||
3. **关闭不必要程序**: 释放系统资源
|
||||
|
||||
### IDE 优化
|
||||
1. **启用编译缓存**: Settings → Build → Compiler → Use build cache
|
||||
2. **配置启动内存**: -Xmx4g -Xms2g
|
||||
3. **禁用不必要的插件**: 减少启动时间
|
||||
|
||||
### 数据库优化
|
||||
1. **连接池配置**: 调整 HikariCP 连接池参数
|
||||
2. **索引优化**: 为常用查询字段添加索引
|
||||
3. **查询优化**: 避免 N+1 查询问题
|
||||
|
||||
---
|
||||
|
||||
*本指南涵盖了 Contract-Manager 项目的完整开发环境配置。如有问题，请参考故障排除部分或联系项目维护者。*
|
||||
Reference in New Issue
Block a user