contract-manager/ARCHITECTURE.md

# Contract-Manager 技术架构文档

## 📋 项目概述

Contract-Manager 是一个基于 Spring Boot 后端 + JavaFX 客户端的企业合同管理系统，采用模块化设计，支持多业务域的企业级应用开发。

## 🏗️ 技术栈

### 服务端 (Server Module)
- **基础框架**: Spring Boot 3.3.7
- **Java 版本**: Java 21
- **数据库访问**: Spring Data JPA 3.3.7
- **数据库**: MySQL 8.0.33
- **缓存**: Redis
- **构建工具**: Maven 3.x
- **开发工具**: Lombok 1.18.32
- **文档处理**: Apache POI 5.2.5, PDFBox 3.0.1
- **云服务集成**: 支持第三方云服务API集成

### 客户端 (Client Module)
- **UI框架**: JavaFX 21
- **Java 版本**: Java 21
- **UI组件库**: ControlsFX 11.1.2
- **开发工具**: Lombok 1.18.32
- **缓存**: Caffeine 3.1.8
- **通信**: WebSocket 与服务端通信
- **界面**: FXML 格式界面文件

### 公共模块 (Common Module)
- **Java 版本**: Java 21
- **开发工具**: Lombok 1.18.32
- **共享内容**: 常量定义、实体模型、视图对象、通用工具类

## 🏛️ 架构设计

### 整体架构图
```mermaid
graph TB
    subgraph "客户端层 (Client Layer)"
        A[JavaFX UI] --> B[FXML 界面]
        A --> C[Controller 控制器]
        A --> D[ViewModel 视图模型]
        A --> E[Service 层]
    end
    
    subgraph "业务层 (Business Layer)"
        C --> F[Controller API]
        E --> G[Service 业务逻辑]
        G --> H[Repository 数据访问]
    end
    
    subgraph "数据层 (Data Layer)"
        H --> I[JPA Repository]
        I --> J[MySQL 数据库]
    end
    
    subgraph "缓存层 (Cache Layer)"
        G --> K[Redis 缓存]
        E --> L[Caffeine 缓存]
    end
    
    subgraph "公共层 (Common Layer)"
        M[Entity 实体模型]
        N[VO 视图对象]
        O[Constants 常量]
        P[Utils 工具类]
    end
    
    H --> M
    G --> N
    M --> O
    G --> P
    
    subgraph "外部服务 (External Services)"
        Q[云服务 API]
        R[第三方集成]
    end
    
    G --> Q
    G --> R
```

### 模块架构说明

#### 1. 客户端模块 (client/)
```
src/main/java/com/ecep/contract/
├── controller/          # JavaFX 控制器
│   ├── CompanyController.java
│   ├── ContractController.java
│   └── ...
├── service/             # 客户端服务层
│   ├── CompanyService.java
│   └── ...
├── task/                # 任务处理类
├── vm/                  # 视图模型 (ViewModel)
├── converter/           # 类型转换器
├── serializer/          # 序列化类
└── util/                # 工具类
```

#### 2. 服务端模块 (server/)
```
src/main/java/com/ecep/contract/
├── api/                 # API 接口定义
├── config/              # Spring 配置类
├── controller/          # Web 控制器
├── ds/                  # 数据访问层 (按业务域组织)
│   ├── company/         # 公司相关业务
│   │   ├── model/       # 实体类
│   │   ├── repository/  # 数据访问接口
│   │   ├── service/     # 业务逻辑服务
│   │   ├── tasker/      # 任务处理器
│   │   └── controller/  # 控制器
│   ├── contract/        # 合同相关业务
│   ├── customer/        # 客户相关业务
│   ├── project/         # 项目相关业务
│   └── vendor/          # 供应商相关业务
├── service/             # 通用服务和任务处理器
├── handler/             # WebSocket 处理器
├── ui/                  # UI 相关组件
└── util/                # 工具类
```

#### 3. 公共模块 (common/)
```
src/main/java/ecep/contract/
├── constant/            # 常量类 (按业务域组织)
├── model/               # 实体类 (按业务域组织)
├── vo/                  # 视图对象 (按业务域组织)
└── util/                # 工具类
```

## 🎯 核心设计模式

### 1. 分层架构模式
- **表示层**: JavaFX UI + FXML
- **业务逻辑层**: Service + Task + Controller
- **数据访问层**: Repository + Entity
- **基础设施层**: 配置、缓存、工具类

### 2. 领域驱动设计 (DDD)
项目采用领域驱动设计，按业务域组织代码：
- **Company (公司域)**: 公司信息、联系人、文件管理
- **Contract (合同域)**: 合同管理、目录分类、文件处理
- **Customer (客户域)**: 客户关系、分类管理
- **Project (项目域)**: 项目管理、文件跟踪
- **Vendor (供应商域)**: 供应商管理、评价体系

### 3. 接口分离原则
服务端 Service 实现三个核心接口：
```java
public interface IEntityService<T> {
    T save(T entity);
    void delete(T entity);
    T getById(Integer id);
    Page<T> findAll(Specification<T> spec, Pageable pageable);
}

public interface QueryService<Vo> {
    Vo findById(Integer id);
    Page<Vo> findAll(JsonNode paramsNode, Pageable pageable);
}

public interface VoableService<M, Vo> {
    void updateByVo(M model, Vo vo);
}
```

### 4. 缓存策略模式
- **多级缓存**: Caffeine (客户端) + Redis (服务端)
- **缓存键设计**: 按查询类型设计唯一键
- **缓存清理**: 数据修改时清理相关缓存

## 🔗 模块间通信

### 1. 客户端-服务端通信
- **协议**: HTTP REST API + WebSocket
- **数据格式**: JSON
- **序列化**: 统一使用 VO 对象进行数据传输

### 2. 服务端内部通信
- **依赖注入**: Spring IoC 容器管理
- **服务调用**: 延迟加载 (@Lazy) 避免循环依赖
- **事务管理**: @Transactional 确保数据一致性

### 3. 数据流转
```
Entity (数据库) ↔ Repository ↔ Service ↔ VO ↔ JSON ↔ Client
```

## 🛡️ 安全与性能

### 1. 安全设计
- **API 认证**: 基于 JWT 的身份认证机制
- **权限控制**: 基于角色的访问控制 (RBAC)
- **数据验证**: 输入参数校验和 SQL 注入防护

### 2. 性能优化
- **延迟加载**: @Lazy 避免循环依赖
- **缓存策略**: 多级缓存减少数据库访问
- **分页查询**: 大数据集分页处理
- **批量操作**: 批量保存和更新

### 3. 监控与日志
- **应用监控**: Spring Boot Actuator
- **日志管理**: SLF4J + Logback
- **性能监控**: 缓存命中率、响应时间

## 📦 依赖管理

### Maven 模块结构
```
parent
├── client       # 客户端模块
├── common       # 公共模块
└── server       # 服务端模块
```

### 关键依赖说明
- **Spring Boot Starter**: 快速集成 Spring 生态
- **Spring Data JPA**: 简化数据访问层开发
- **Lombok**: 减少样板代码
- **Caffeine**: 高性能本地缓存
- **JavaFX**: 现代化桌面应用 UI

## 🚀 开发规范

### 1. 命名规范
- **类名**: 驼峰命名法，以业务含义命名
- **接口名**: 以 I 开头 + 业务描述
- **控制器**: 以 Controller 结尾
- **服务类**: 以 Service 结尾
- **仓储接口**: 以 Repository 结尾

### 2. 编码规范
- **注解使用**: 合理使用 Spring、Lombok 等注解
- **异常处理**: 统一异常处理机制
- **单元测试**: 核心业务逻辑必须有测试覆盖
- **代码注释**: 关键逻辑和复杂业务需要 JavaDoc

### 3. 配置管理
- **环境配置**: 多环境配置 (dev, test, prod)
- **敏感信息**: 使用 .env 文件管理 API 密钥等
- **配置分离**: 业务配置与框架配置分离

## 📊 扩展性设计

### 1. 模块化设计
- **业务域分离**: 不同业务域独立开发和部署
- **接口标准化**: 统一的 Service 接口设计
- **组件复用**: 基础组件可在多个业务域复用

### 2. 水平扩展
- **无状态设计**: Service 层无状态设计支持集群部署
- **缓存分离**: Redis 支持分布式缓存
- **数据库分离**: 支持读写分离和分库分表

### 3. 垂直扩展
- **微服务拆分**: 按业务域可拆分为微服务
- **插件化**: 支持新业务域的快速集成

---

*本文档反映了 Contract-Manager 项目的整体技术架构和设计理念，为项目开发、部署和维护提供指导。*