contract-manager/docs/DEVELOPMENT_GUIDE.md

# 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 项目的完整开发环境配置。如有问题，请参考故障排除部分或联系项目维护者。*