Files

songqq f0e85c5a18 docs: 添加项目文档和架构设计文件

删除旧的package.json文件
添加天眼查下载信用报告文档
添加项目文档总览、架构设计、API文档、开发指南和数据库设计文档

2025-11-26 16:10:01 +08:00

8.0 KiB

Raw Permalink Blame History

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
共享内容: 常量定义、实体模型、视图对象、通用工具类

🏛️ 架构设计

整体架构图

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 实现三个核心接口：

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 项目的整体技术架构和设计理念，为项目开发、部署和维护提供指导。

8.0 KiB Raw Permalink Blame History