songqq/contract-manager
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects 1 Releases 1 Wiki Activity

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

Browse Source 
删除旧的package.json文件
添加天眼查下载信用报告文档
添加项目文档总览、架构设计、API文档、开发指南和数据库设计文档
This commit is contained in:
宋其青
2025-11-26 16:10:01 +08:00
parent a784438e97
commit f0e85c5a18
8 changed files with 0 additions and 1934 deletions
Download Patch File Download Diff File Expand all files Collapse all files

546
docs/API_DOCUMENTATION.md Normal file
View File

@@ -0,0 +1,546 @@
# Contract-Manager API 接口文档
## 📖 概览
Contract-Manager 系统提供了完整的 RESTful API 接口，用于合同管理系统的各项业务操作。本文档详细描述了所有可用的 API 接口、请求参数、响应格式和错误处理。
### API 基础信息
- **基础URL**: `http://localhost:8080`
- **协议**: HTTP/HTTPS
- **数据格式**: JSON
- **认证方式**: Spring Security Session + JWT
- **字符编码**: UTF-8
### 通用响应格式
```json
{
"success": true|false,
"data": {...},
"message": "提示信息",
"error": "错误信息"
}
```
### 状态码说明
- `200`: 成功
- `400`: 请求参数错误
- `401`: 未认证
- `403`: 权限不足
- `404`: 资源不存在
- `500`: 服务器内部错误
---
## 🔐 认证接口
### 用户登录 - POST /api/login
用户登录接口，支持用户名密码登录和客户端认证两种方式。
**请求参数**:
```json
{
"type": "client|web", // 登录类型：client=客户端认证，web=用户名密码登录
"username": "用户名", // 用户名
"password": "密码", // 密码（web模式需要）
"sign": { // 客户端认证信息（client模式需要）
"MAC地址": "IP地址"
}
}
```
**响应数据**:
```json
{
"success": true,
"employeeId": 1,
"sessionId": "session_id",
"username": "admin",
"roles": ["ROLE_ADMIN"],
"message": "登录成功"
}
```
**错误响应**:
```json
{
"success": false,
"error": "用户名或密码错误"
}
```
---
## 👥 用户管理接口
### 员工信息 - GET /employee/findById
根据ID获取员工信息。
**请求参数**:
- `id` (Integer): 员工ID
**响应数据**:
```json
{
"success": true,
"data": {
"id": 1,
"name": "张三",
"account": "admin",
"email": "admin@example.com"
}
}
```
### 员工列表 - GET /employee/list
分页获取员工列表。
**请求参数**:
- `page` (Integer, 默认0): 页码
- `size` (Integer, 默认10): 每页大小
- `searchText` (String, 可选): 搜索关键词
**响应数据**:
```json
{
"content": [
{
"id": 1,
"name": "张三",
"account": "admin"
}
],
"totalElements": 10,
"totalPages": 1,
"size": 10,
"number": 0
}
```
### 保存员工信息 - POST /employee/save
保存或更新员工信息。
**请求参数**:
```json
{
"id": 1,
"name": "张三",
"account": "admin",
"email": "admin@example.com"
}
```
### 删除员工 - GET /employee/delete
删除指定ID的员工。
**请求参数**:
- `id` (Integer): 员工ID
### 获取当前用户信息 - GET /employee/currentUser
获取当前登录用户的信息。
**响应数据**:
```json
{
"success": true,
"employeeId": 1,
"sessionId": "session_id"
}
```
---
## 🏢 公司管理接口
### 公司信息 - GET /company/findById
根据ID获取公司信息。
**请求参数**:
- `id` (Integer): 公司ID
**响应数据**:
```json
{
"success": true,
"data": {
"id": 1,
"name": "示例公司",
"address": "北京市朝阳区",
"phone": "010-12345678"
}
}
```
### 公司列表 - GET /company/list
分页获取公司列表。
**请求参数**:
- `page` (Integer, 默认0): 页码
- `size` (Integer, 默认10): 每页大小
**响应数据**:
```json
{
"content": [
{
"id": 1,
"name": "示例公司",
"address": "北京市朝阳区"
}
],
"totalElements": 10,
"totalPages": 1,
"size": 10,
"number": 0
}
```
### 保存公司信息 - GET /company/save
保存或更新公司信息。
**请求参数**:
```json
{
"id": 1,
"name": "示例公司",
"address": "北京市朝阳区",
"phone": "010-12345678"
}
```
### 删除公司 - GET /company/delete
删除指定ID的公司。
**请求参数**:
- `id` (Integer): 公司ID
---
## 🏦 银行管理接口
### 银行信息 - GET /bank/findById
根据ID获取银行信息。
**请求参数**:
- `id` (Integer): 银行ID
### 银行列表 - GET /bank/list
分页获取银行列表。
**请求参数**:
- `page` (Integer, 默认0): 页码
- `size` (Integer, 默认10): 每页大小
### 保存银行信息 - POST /bank/save
保存或更新银行信息。
**请求参数**:
```json
{
"id": 1,
"name": "中国银行",
"code": "BOC"
}
```
### 删除银行 - GET /bank/delete
删除指定ID的银行。
**请求参数**:
- `id` (Integer): 银行ID
---
## 🔑 角色管理接口
### 角色信息 - GET /employee/role/findById
根据ID获取角色信息。
**请求参数**:
- `id` (Integer): 角色ID
### 角色列表 - GET /employee/role/list
分页获取角色列表，非系统管理员无法查看系统管理员角色。
**请求参数**:
- `page` (Integer, 默认0): 页码
- `size` (Integer, 默认10): 每页大小
- `searchText` (String, 可选): 搜索关键词
### 保存角色信息 - GET /employee/role/save
保存角色信息，**仅系统管理员可操作**。
### 删除角色 - GET /employee/role/delete
删除指定ID的角色，**仅系统管理员可操作**。
**请求参数**:
- `id` (Integer): 角色ID
**注意**: 不能删除系统管理员角色。
### 获取角色权限 - GET /employee/role/getFunctionsByRoleId
根据角色ID获取该角色的权限功能列表。
**请求参数**:
- `roleId` (Integer): 角色ID
---
## ☁️ 云服务接口
### 天眼查服务 - /cloudTyc
天眼查第三方数据服务接口。
#### 获取天眼查信息 - GET /cloudTyc/findById
#### 天眼查列表 - GET /cloudTyc/list
#### 保存天眼查信息 - GET /cloudTyc/save
#### 删除天眼查信息 - GET /cloudTyc/delete
### 企查查服务 - /cloudRk
企查查第三方数据服务接口。
#### 获取企查查信息 - GET /cloudRk/findById
#### 企查查列表 - GET /cloudRk/list
#### 保存企查查信息 - GET /cloudRk/save
#### 删除企查查信息 - GET /cloudRk/delete
### 用友云服务 - /cloudYu
用友云第三方数据服务接口。
#### 获取用友云信息 - GET /cloudYu/findById
#### 用友云列表 - GET /cloudYu/list
#### 保存用友云信息 - GET /cloudYu/save
#### 删除用友云信息 - GET /cloudYu/delete
---
## 📊 其他接口
### 系统首页 - GET /index
获取系统首页信息。
**响应数据**:
```json
{
"success": true,
"data": {
"systemInfo": "Contract Manager System",
"version": "1.0.0"
}
}
```
### WebSocket 连接 - GET /websocket
建立WebSocket连接，用于实时通信。
**连接地址**: `ws://localhost:8080/websocket`
---
## 🔒 权限说明
### 角色权限
- **ROLE_ADMIN**: 系统管理员，拥有所有权限
- **普通用户**: 只能查看和操作非系统管理员级别的数据
### 权限控制
- 删除角色操作仅限系统管理员
- 系统管理员角色不可删除
- 非系统管理员无法查看系统管理员角色信息
---
## 🚨 错误处理
### 常见错误码
#### 400 - 请求参数错误
```json
{
"success": false,
"error": "请求参数不正确"
}
```
#### 401 - 未认证
```json
{
"success": false,
"error": "请先登录"
}
```
#### 403 - 权限不足
```json
{
"success": false,
"error": "无权限执行此操作"
}
```
#### 404 - 资源不存在
```json
{
"success": false,
"error": "资源不存在"
}
```
### 认证错误
- 客户端认证模式下，需要提供正确的MAC地址和IP地址映射
- 用户名密码模式下，需要提供正确的用户名和密码
### 业务错误
- 系统管理员角色不可删除
- 用户未绑定认证信息无法登录
- 认证信息错误登录失败
---
## 📝 使用示例
### JavaScript/Ajax 调用示例
```javascript
// 用户登录
$.ajax({
url: '/api/login',
type: 'POST',
contentType: 'application/json',
data: JSON.stringify({
type: 'web',
username: 'admin',
password: 'password123'
}),
success: function(response) {
if (response.success) {
console.log('登录成功', response);
// 保存sessionId等认证信息
sessionStorage.setItem('sessionId', response.sessionId);
}
}
});
// 获取公司列表
$.ajax({
url: '/company/list',
type: 'GET',
data: {
page: 0,
size: 10
},
success: function(response) {
console.log('公司列表', response);
}
});
// 保存公司信息
$.ajax({
url: '/company/save',
type: 'GET',
data: {
id: 1,
name: '新公司名称',
address: '新地址'
},
success: function(response) {
console.log('保存成功', response);
}
});
```
### curl 调用示例
```bash
# 用户登录
curl -X POST http://localhost:8080/api/login \
-H "Content-Type: application/json" \
-d '{
"type": "web",
"username": "admin",
"password": "password123"
}'
# 获取公司列表
curl "http://localhost:8080/company/list?page=0&size=10"
# 获取员工信息
curl "http://localhost:8080/employee/findById?id=1"
```
---
## 🔧 SDK 使用指南
### 添加依赖
```xml
<dependency>
<groupId>com.ecep.contract</groupId>
<artifactId>contract-client</artifactId>
<version>1.0.0</version>
</dependency>
```
### 初始化客户端
```java
ContractClient client = new ContractClient("http://localhost:8080");
client.setSessionId(sessionId); // 设置认证session
```
### 调用API
```java
// 获取公司列表
Page<CompanyVo> companies = client.company().list(0, 10);
// 保存公司信息
CompanyVo company = new CompanyVo();
company.setName("新公司");
CompanyVo saved = client.company().save(company);
```
---
## 📈 版本历史
| 版本 | 日期 | 变更说明 |
|------|------|----------|
| v1.0.0 | 2024-01-01 | 初始版本，包含基础CRUD操作 |
| v1.1.0 | 2024-02-01 | 新增角色权限管理接口 |
| v1.2.0 | 2024-03-01 | 新增云服务集成接口 |
---
## 📞 技术支持
如有技术问题，请联系：
- **技术支持邮箱**: support@contractmanager.com
- **开发团队**: Contract Manager Development Team
- **文档版本**: v1.2.0
- **最后更新**: 2024-03-01
---
*本文档详细描述了 Contract-Manager 系统的所有 API 接口。请在使用前仔细阅读相关说明，确保正确调用接口。*

265
docs/ARCHITECTURE.md Normal file
View File

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

646
docs/DATABASE_DESIGN.md Normal file
View File

@@ -0,0 +1,646 @@
# Contract-Manager 数据库设计文档
## 📊 概览
Contract-Manager 系统采用 MySQL 8.0+ 作为主数据库，设计遵循第三范式（3NF），支持高并发访问和数据一致性。本文档详细描述了数据库设计架构、表结构、关系设计和维护策略。
### 数据库基本信息
- **数据库类型**: MySQL 8.0+
- **数据库名称**: supplier_ms
- **字符集**: utf8mb4
- **排序规则**: utf8mb4_unicode_ci
- **存储引擎**: InnoDB（支持事务和外键约束）
---
## 🏗️ 数据库架构设计
### 核心业务域
#### 1. 用户权限管理域
- **员工管理**: EMPLOYEE, EMPLOYEE_ROLE, EMPLOYEE_AUTH_BIND
- **角色管理**: EMPLOYEE_ROLE, FUNCTION
- **登录历史**: EMPLOYEE_LOGIN_HISTORY
- **权限功能**: FUNCTION
#### 2. 企业管理域
- **公司信息**: COMPANY, COMPANY_FILE_TYPE_LOCAL
- **银行信息**: BANK
- **供应商管理**: COMPANY_VENDOR_ENTITY, VENDOR_TYPE_LOCAL
- **客户管理**: CUSTOMER, CUSTOMER_FILE_TYPE_LOCAL
#### 3. 合同管理域
- **合同基础**: CONTRACT, CONTRACT_FILE_TYPE_LOCAL
- **合同发票**: CONTRACT_INVOICE
- **销售订单**: CONTRACT_SALES_ORDER
- **合同余额**: CONTRACT_BALANCE
#### 4. 项目管理域
- **项目信息**: PROJECT, PROJECT_FILE_TYPE_LOCAL
- **项目资金计划**: PROJECT_FUND_PLAN_TABLE
- **库存管理**: INVENTORY
#### 5. 基础数据域
- **单位管理**: UNIT
- **云服务数据**: CLOUD_TYC, CLOUD_RK, CLOUD_YU
---
## 📋 核心表结构设计
### 1. 用户权限相关表
#### EMPLOYEE (员工表)
```sql
CREATE TABLE EMPLOYEE (
ID INT AUTO_INCREMENT PRIMARY KEY,
NAME VARCHAR(255) NOT NULL COMMENT '员工姓名',
ACCOUNT VARCHAR(255) UNIQUE NOT NULL COMMENT '登录账号',
PASSWORD VARCHAR(255) NOT NULL COMMENT '密码哈希',
EMAIL VARCHAR(255) COMMENT '邮箱',
PHONE VARCHAR(50) COMMENT '电话',
IS_ACTIVE BOOLEAN DEFAULT TRUE COMMENT '是否激活',
CREATE_TIME DATETIME DEFAULT CURRENT_TIMESTAMP,
UPDATE_TIME DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
CONSTRAINT uq_employee_account UNIQUE KEY (ACCOUNT)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
```
#### EMPLOYEE_ROLE (员工角色表)
```sql
CREATE TABLE EMPLOYEE_ROLE (
ID INT AUTO_INCREMENT PRIMARY KEY,
ROLE_NAME VARCHAR(255) NOT NULL COMMENT '角色名称',
DESCRIPTION TEXT COMMENT '角色描述',
SYSTEM_ADMINISTRATOR BOOLEAN DEFAULT FALSE COMMENT '是否系统管理员',
IS_ACTIVE BOOLEAN DEFAULT TRUE COMMENT '是否激活',
CREATE_TIME DATETIME DEFAULT CURRENT_TIMESTAMP,
UPDATE_TIME DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
```
#### EMPLOYEE_AUTH_BIND (员工认证绑定表)
```sql
CREATE TABLE EMPLOYEE_AUTH_BIND (
ID INT AUTO_INCREMENT PRIMARY KEY,
EMPLOYEE_ID INT NOT NULL COMMENT '员工ID',
MAC VARCHAR(255) NOT NULL COMMENT 'MAC地址',
IP VARCHAR(255) NOT NULL COMMENT 'IP地址',
BIND_TIME DATETIME DEFAULT CURRENT_TIMESTAMP,
CONSTRAINT fk_employee_auth_bind_employee FOREIGN KEY (EMPLOYEE_ID) REFERENCES EMPLOYEE(ID)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
```
### 2. 企业管理相关表
#### COMPANY (公司表)
```sql
CREATE TABLE COMPANY (
ID INT AUTO_INCREMENT PRIMARY KEY,
NAME VARCHAR(255) NOT NULL COMMENT '公司名称',
ADDRESS TEXT COMMENT '地址',
PHONE VARCHAR(50) COMMENT '电话',
EMAIL VARCHAR(255) COMMENT '邮箱',
LEGAL_PERSON VARCHAR(255) COMMENT '法人代表',
BUSINESS_LICENSE VARCHAR(255) COMMENT '营业执照号',
IS_VENDOR BOOLEAN DEFAULT FALSE COMMENT '是否供应商',
IS_CUSTOMER BOOLEAN DEFAULT FALSE COMMENT '是否客户',
CREATE_TIME DATETIME DEFAULT CURRENT_TIMESTAMP,
UPDATE_TIME DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
```
#### VENDOR_TYPE_LOCAL (供应商类型本地化表)
```sql
CREATE TABLE VENDOR_TYPE_LOCAL (
ID INT AUTO_INCREMENT PRIMARY KEY,
TYPE VARCHAR(255) NOT NULL COMMENT '枚举类型',
LANG VARCHAR(255) NOT NULL COMMENT '语言',
VALUE VARCHAR(255) NOT NULL COMMENT '本地化值',
CONSTRAINT pk_vendor_type_local PRIMARY KEY (ID),
CONSTRAINT uq_vendor_type_local UNIQUE KEY (TYPE, LANG)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
```
### 3. 合同管理相关表
#### CONTRACT (合同表)
```sql
CREATE TABLE CONTRACT (
ID INT AUTO_INCREMENT PRIMARY KEY,
CODE VARCHAR(100) UNIQUE NOT NULL COMMENT '合同编号',
NAME VARCHAR(500) NOT NULL COMMENT '合同名称',
CUSTOMER_ID INT COMMENT '客户ID',
VENDOR_ID INT COMMENT '供应商ID',
PROJECT_ID INT COMMENT '项目ID',
SIGN_DATE DATE COMMENT '签订日期',
START_DATE DATE COMMENT '开始日期',
END_DATE DATE COMMENT '结束日期',
AMOUNT DECIMAL(15,2) COMMENT '合同金额',
STATUS VARCHAR(50) DEFAULT 'ACTIVE' COMMENT '合同状态',
CREATE_TIME DATETIME DEFAULT CURRENT_TIMESTAMP,
UPDATE_TIME DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
CONSTRAINT fk_contract_customer FOREIGN KEY (CUSTOMER_ID) REFERENCES COMPANY(ID),
CONSTRAINT fk_contract_vendor FOREIGN KEY (VENDOR_ID) REFERENCES COMPANY(ID),
CONSTRAINT fk_contract_project FOREIGN KEY (PROJECT_ID) REFERENCES PROJECT(ID)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
```
#### CONTRACT_INVOICE (合同发票关联表)
```sql
CREATE TABLE CONTRACT_INVOICE (
ID INT AUTO_INCREMENT PRIMARY KEY,
CODE VARCHAR(50) COMMENT '发票编号',
NAME VARCHAR(200) COMMENT '发票名称',
CONTRACT_ID INT NOT NULL COMMENT '合同ID',
INVOICE_ID INT COMMENT '发票ID',
AMOUNT DECIMAL(15,2) COMMENT '发票金额',
SETUP_PERSON_ID INT COMMENT '创建人ID',
SETUP_DATE DATE COMMENT '创建日期',
UPDATE_PERSON_ID INT COMMENT '更新人ID',
UPDATE_DATE DATE COMMENT '更新日期',
REMARK VARCHAR(500) COMMENT '备注',
CONSTRAINT fk_contract_invoice_contract FOREIGN KEY (CONTRACT_ID) REFERENCES CONTRACT(ID) ON DELETE CASCADE,
CONSTRAINT fk_contract_invoice_invoice FOREIGN KEY (INVOICE_ID) REFERENCES INVOICE(ID) ON DELETE SET NULL,
CONSTRAINT fk_contract_invoice_setup_person FOREIGN KEY (SETUP_PERSON_ID) REFERENCES EMPLOYEE(ID) ON DELETE SET NULL,
CONSTRAINT fk_contract_invoice_update_person FOREIGN KEY (UPDATE_PERSON_ID) REFERENCES EMPLOYEE(ID) ON DELETE SET NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
```
### 4. 文件类型本地化表
#### COMPANY_FILE_TYPE_LOCAL (公司文件类型本地化表)
```sql
CREATE TABLE COMPANY_FILE_TYPE_LOCAL (
ID INT AUTO_INCREMENT PRIMARY KEY,
TYPE VARCHAR(255) NOT NULL COMMENT '枚举类型',
LANG VARCHAR(255) NOT NULL COMMENT '语言',
VALUE VARCHAR(255) NOT NULL COMMENT '本地化值',
CONSTRAINT pk_company_file_type_local PRIMARY KEY (ID),
CONSTRAINT uq_company_file_type_local UNIQUE KEY (TYPE, LANG)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
```
#### CONTRACT_FILE_TYPE_LOCAL (合同文件类型本地化表)
```sql
CREATE TABLE CONTRACT_FILE_TYPE_LOCAL (
ID INT AUTO_INCREMENT PRIMARY KEY,
TYPE VARCHAR(255) NOT NULL COMMENT '枚举类型',
LANG VARCHAR(255) NOT NULL COMMENT '语言',
VALUE VARCHAR(255) NOT NULL COMMENT '本地化值',
SUGGEST_FILE_NAME VARCHAR(255) COMMENT '建议的文件名',
DESCRIPTION VARCHAR(255) COMMENT '描述',
CONSTRAINT pk_contract_file_type_local PRIMARY KEY (ID),
CONSTRAINT uq_contract_file_type_local UNIQUE KEY (TYPE, LANG)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
```
---
## 🔗 数据库关系设计
### 1. 核心实体关系图
```mermaid
erDiagram
EMPLOYEE ||--o{ EMPLOYEE_AUTH_BIND : has
EMPLOYEE ||--o{ EMPLOYEE_LOGIN_HISTORY : creates
EMPLOYEE }o--|| EMPLOYEE_ROLE : belongs
COMPANY ||--o{ CONTRACT : creates
COMPANY ||--o{ PROJECT : has
COMPANY ||--o{ COMPANY_VENDOR_ENTITY : is_vendor
COMPANY ||--o{ COMPANY_VENDOR_ENTITY : is_customer
CONTRACT ||--o{ CONTRACT_INVOICE : contains
CONTRACT ||--o{ CONTRACT_SALES_ORDER : has
CONTRACT ||--o{ CONTRACT_BALANCE : has
PROJECT ||--o{ PROJECT_FUND_PLAN_TABLE : has
PROJECT ||--o{ INVENTORY : manages
VENDOR_TYPE_LOCAL }o--|| COMPANY_VENDOR_ENTITY : types
FILE_TYPE_LOCAL }o--o| COMPANY : documents
FILE_TYPE_LOCAL }o--o| CONTRACT : documents
```
### 2. 外键约束设计
#### 核心外键关系
```sql
-- 员工与角色关联
ALTER TABLE EMPLOYEE
ADD CONSTRAINT fk_employee_role
FOREIGN KEY (ROLE_ID) REFERENCES EMPLOYEE_ROLE(ID);
-- 合同与客户供应商关联
ALTER TABLE CONTRACT
ADD CONSTRAINT fk_contract_customer
FOREIGN KEY (CUSTOMER_ID) REFERENCES COMPANY(ID);
-- 合同发票关联
ALTER TABLE CONTRACT_INVOICE
ADD CONSTRAINT fk_contract_invoice_contract
FOREIGN KEY (CONTRACT_ID) REFERENCES CONTRACT(ID) ON DELETE CASCADE;
```
### 3. 索引设计策略
#### 主要索引
```sql
-- 单列索引
CREATE INDEX idx_employee_account ON EMPLOYEE(ACCOUNT);
CREATE INDEX idx_contract_code ON CONTRACT(CODE);
CREATE INDEX idx_company_name ON COMPANY(NAME);
-- 复合索引
CREATE INDEX idx_contract_customer_status ON CONTRACT(CUSTOMER_ID, STATUS);
CREATE INDEX idx_invoice_date_amount ON INVOICE(INVOICE_DATE, AMOUNT);
-- 外键索引
CREATE INDEX idx_contract_invoice_contract_id ON CONTRACT_INVOICE(CONTRACT_ID);
CREATE INDEX idx_employee_auth_bind_employee ON EMPLOYEE_AUTH_BIND(EMPLOYEE_ID);
```
---
## 🎯 本地化设计
### 1. 多语言支持
#### 本地化表设计原则
- **统一结构**: 所有本地化表使用相同的结构
- **语言键**: 使用LANG字段标识语言（zh_CN, en_US）
- **类型分类**: 使用TYPE字段进行分类管理
- **唯一约束**: (TYPE, LANG)组合唯一
#### 本地化表示例
```sql
-- 合同文件类型本地化
TYPE: 'CONTRACT_CERTIFICATE', LANG: 'zh_CN', VALUE: '资质证书'
TYPE: 'CONTRACT_CERTIFICATE', LANG: 'en_US', VALUE: 'Certificate'
-- 供应商类型本地化
TYPE: 'VENDOR_PRIMARY', LANG: 'zh_CN', VALUE: '主要供应商'
TYPE: 'VENDOR_PRIMARY', LANG: 'en_US', VALUE: 'Primary Vendor'
```
### 2. 数据维护策略
#### 本地化数据初始化
```sql
-- 初始化供应商类型本地化数据
INSERT INTO VENDOR_TYPE_LOCAL (TYPE, LANG, VALUE) VALUES
('VENDOR_PRIMARY', 'zh_CN', '主要供应商'),
('VENDOR_PRIMARY', 'en_US', 'Primary Vendor'),
('VENDOR_SECONDARY', 'zh_CN', '次要供应商'),
('VENDOR_SECONDARY', 'en_US', 'Secondary Vendor');
-- 初始化合同文件类型本地化数据
INSERT INTO CONTRACT_FILE_TYPE_LOCAL (TYPE, LANG, VALUE, SUGGEST_FILE_NAME, DESCRIPTION) VALUES
('CONTRACT_MAIN', 'zh_CN', '主合同', 'main_contract.pdf', '主要合同文件'),
('CONTRACT_MAIN', 'en_US', 'Main Contract', 'main_contract.pdf', 'Main contract document'),
('CONTRACT_CERTIFICATE', 'zh_CN', '资质证书', 'certificate.pdf', '相关资质证书'),
('CONTRACT_CERTIFICATE', 'en_US', 'Certificate', 'certificate.pdf', 'Related certificates');
```
---
## 🔧 数据库脚本管理
### 1. 脚本文件组织
```
docs/db/
├── structs.sql # 数据库结构脚本
├── initial_data.sql # 初始数据脚本
├── CompanyFileTypeLocal.sql # 公司文件类型本地化
├── ContractFileTypeLocal.sql # 合同文件类型本地化
├── CustomerFileTypeLocal.sql # 客户文件类型本地化
├── ProjectFileTypeLocal.sql # 项目文件类型本地化
├── VendorFileTypeLocal.sql # 供应商文件类型本地化
├── VendorTypeLocal.sql # 供应商类型本地化
├── Unit.sql # 单位基础数据
├── CompanyVendor.sql # 公司供应商关联表
├── Contract_INVOICE.sql # 合同发票关联表
├── Contract_SALES_ORDER.sql # 合同销售订单表
├── Contract_BALANCE.sql # 合同余额表
├── Inverntory.sql # 库存表
├── project_fund_plan_table.sql # 项目资金计划表
├── add_function_columns.sql # 功能扩展列脚本
├── temp.sql # 临时脚本
└── temp_u8.sql # 临时U8脚本
```
### 2. 脚本执行顺序
#### 环境初始化脚本执行顺序
```bash
# 1. 创建数据库和基础表结构
mysql -u root -p < structs.sql
# 2. 初始化基础数据
mysql -u root -p < initial_data.sql
# 3. 初始化本地化数据
mysql -u root -p < CompanyFileTypeLocal.sql
mysql -u root -p < ContractFileTypeLocal.sql
mysql -u root -p < CustomerFileTypeLocal.sql
mysql -u root -p < ProjectFileTypeLocal.sql
mysql -u root -p < VendorFileTypeLocal.sql
mysql -u root -p < VendorTypeLocal.sql
# 4. 初始化基础字典数据
mysql -u root -p < Unit.sql
# 5. 业务表数据
mysql -u root -p < Contract_INVOICE.sql
mysql -u root -p < Contract_SALES_ORDER.sql
mysql -u root -p < Contract_BALANCE.sql
mysql -u root -p < Inverntory.sql
mysql -u root -p < project_fund_plan_table.sql
# 6. 数据关联和约束
mysql -u root -p < CompanyVendor.sql
# 7. 功能扩展（如需要）
mysql -u root -p < add_function_columns.sql
```
### 3. 版本控制策略
#### 数据库版本管理
- **结构版本**: 通过版本号管理数据库结构变更
- **数据迁移**: 使用迁移脚本管理数据变更
- **回滚策略**: 保持完整的回滚脚本
#### 迁移脚本模板
```sql
-- 版本: v1.0.1
-- 描述: 添加员工激活状态字段
-- 日期: 2024-01-15
-- 前置检查
SELECT 'Starting migration v1.0.1' as status;
-- 添加字段
ALTER TABLE EMPLOYEE
ADD COLUMN IS_ACTIVE BOOLEAN DEFAULT TRUE COMMENT '是否激活';
-- 更新现有数据
UPDATE EMPLOYEE SET IS_ACTIVE = TRUE WHERE IS_ACTIVE IS NULL;
-- 验证
SELECT COUNT(*) as total_employees FROM EMPLOYEE;
SELECT 'Migration v1.0.1 completed' as status;
```
---
## 📊 性能优化策略
### 1. 索引优化
#### 查询模式分析
- **高频查询**: 员工登录（ACCOUNT字段）
- **分页查询**: 合同列表（STATUS, CREATE_TIME）
- **关联查询**: 合同客户信息（CUSTOMER_ID）
- **搜索查询**: 公司名称模糊搜索（NAME字段）
#### 索引配置建议
```sql
-- 高频查询索引
CREATE INDEX idx_employee_account_active ON EMPLOYEE(ACCOUNT, IS_ACTIVE);
CREATE INDEX idx_contract_status_date ON CONTRACT(STATUS, CREATE_TIME DESC);
-- 搜索优化索引
CREATE INDEX idx_company_name_prefix ON COMPANY(NAME(20));
-- 关联查询索引
CREATE INDEX idx_contract_customer_status ON CONTRACT(CUSTOMER_ID, STATUS);
-- 统计查询索引
CREATE INDEX idx_invoice_date_amount ON INVOICE(INVOICE_DATE, AMOUNT);
```
### 2. 分区策略
#### 时间分区设计
```sql
-- 登录历史表时间分区（月度分区）
ALTER TABLE EMPLOYEE_LOGIN_HISTORY
PARTITION BY RANGE (YEAR(LOGIN_TIME)*100 + MONTH(LOGIN_TIME)) (
PARTITION p202401 VALUES LESS THAN (202402),
PARTITION p202402 VALUES LESS THAN (202403),
PARTITION p202403 VALUES LESS THAN (202404),
-- ... 更多分区
PARTITION p_max VALUES LESS THAN MAXVALUE
);
```
### 3. 缓存策略
#### Redis缓存配置
```yaml
# 缓存配置
spring:
cache:
type: redis
redis:
timeout: 2000ms
lettuce:
pool:
max-active: 8
max-idle: 8
min-idle: 0
max-wait: -1ms
# 缓存策略
cache:
# 员工信息缓存（5分钟）
employee:
timeout: 300
# 公司信息缓存（10分钟）
company:
timeout: 600
# 合同信息缓存（2分钟）
contract:
timeout: 120
```
---
## 🔒 安全与权限
### 1. 数据权限控制
#### 行级安全
```sql
-- 基于角色的数据访问控制
CREATE VIEW contract_view AS
SELECT c.* FROM CONTRACT c
WHERE
CASE
WHEN EXISTS (SELECT 1 FROM EMPLOYEE e JOIN EMPLOYEE_ROLE er ON e.ROLE_ID = er.ID
WHERE e.ID = CURRENT_USER_ID() AND er.SYSTEM_ADMINISTRATOR = TRUE)
THEN TRUE
ELSE c.CREATOR_ID = CURRENT_USER_ID()
END;
```
#### 敏感字段加密
```sql
-- 员工密码加密存储
ALTER TABLE EMPLOYEE
MODIFY COLUMN PASSWORD VARCHAR(255) NOT NULL COMMENT 'BCrypt加密密码';
-- 敏感信息脱敏
CREATE VIEW employee_safe_view AS
SELECT
ID, NAME, ACCOUNT,
SUBSTRING(EMAIL, 1, 2) || '****' || SUBSTRING(EMAIL, INSTR(EMAIL, '@')) as EMAIL_MASKED,
PHONE_MASKED
FROM EMPLOYEE;
```
### 2. 数据备份策略
#### 备份配置
```bash
#!/bin/bash
# 数据库备份脚本
DB_NAME="supplier_ms"
BACKUP_DIR="/backup/mysql"
DATE=$(date +%Y%m%d_%H%M%S)
# 全量备份
mysqldump -u backup_user -p$BACKUP_PASSWORD \
--single-transaction \
--routines \
--triggers \
$DB_NAME > $BACKUP_DIR/${DB_NAME}_full_$DATE.sql
# 增量备份（二进制日志）
mysql -u root -p$ROOT_PASSWORD -e "FLUSH LOGS;"
cp /var/lib/mysql/mysql-bin.* $BACKUP_DIR/incremental_$DATE/
# 清理旧备份（保留30天）
find $BACKUP_DIR -name "${DB_NAME}_*.sql" -mtime +30 -delete
```
---
## 📈 监控与维护
### 1. 性能监控
#### 关键指标
- **连接数**: 当前连接数和最大连接数
- **查询性能**: 慢查询日志和执行时间分布
- **缓存命中率**: Redis缓存命中率
- **锁等待**: 表锁和行锁等待情况
#### 监控查询
```sql
-- 查看当前连接数
SHOW STATUS LIKE 'Threads_connected';
SHOW STATUS LIKE 'Max_used_connections';
-- 查看慢查询
SELECT * FROM mysql.slow_log
ORDER BY start_time DESC LIMIT 10;
-- 查看表大小
SELECT
table_name,
ROUND(((data_length + index_length) / 1024 / 1024), 2) AS 'Size (MB)'
FROM information_schema.tables
WHERE table_schema = 'supplier_ms'
ORDER BY (data_length + index_length) DESC;
```
### 2. 维护任务
#### 定期维护任务
```sql
-- 优化表（每周执行）
OPTIMIZE TABLE EMPLOYEE, COMPANY, CONTRACT, PROJECT;
-- 分析表统计信息（每日执行）
ANALYZE TABLE EMPLOYEE, COMPANY, CONTRACT;
-- 检查表完整性（每日执行）
CHECK TABLE EMPLOYEE, COMPANY, CONTRACT;
-- 清理历史数据（每月执行）
DELETE FROM EMPLOYEE_LOGIN_HISTORY
WHERE LOGIN_TIME < DATE_SUB(NOW(), INTERVAL 1 YEAR);
```
---
## 🚀 扩展设计
### 1. 分库分表策略
#### 水平分片设计
```sql
-- 按年份分表的合同表
CONTRACT_2024, CONTRACT_2025, CONTRACT_2026
-- 分片键选择
CREATE TABLE CONTRACT (
ID BIGINT AUTO_INCREMENT PRIMARY KEY,
YEAR int NOT NULL COMMENT '年份',
CONTRACT_CODE varchar(100) NOT NULL,
-- 其他字段...
INDEX idx_year_contract_code (YEAR, CONTRACT_CODE)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
-- 分片路由规则
function getContractTable(year) {
return "CONTRACT_" + year;
}
```
### 2. 数据归档策略
#### 历史数据归档
```sql
-- 创建归档表
CREATE TABLE CONTRACT_ARCHIVE LIKE CONTRACT;
-- 归档5年前的数据
INSERT INTO CONTRACT_ARCHIVE
SELECT * FROM CONTRACT
WHERE CREATE_TIME < DATE_SUB(NOW(), INTERVAL 5 YEAR);
-- 删除已归档数据
DELETE FROM CONTRACT
WHERE CREATE_TIME < DATE_SUB(NOW(), INTERVAL 5 YEAR);
```
---
## 📚 文档维护
### 1. 文档更新机制
- **表结构变更**: 同步更新文档
- **关系变更**: 更新ER图和关系说明
- **性能优化**: 记录优化历史和效果
- **安全更新**: 记录权限变更和风险控制
### 2. 版本管理
- **文档版本**: v1.0.0, v1.1.0, v1.2.0
- **变更记录**: 详细记录每次变更内容
- **影响评估**: 分析变更对系统的影响
---
*本文档详细描述了 Contract-Manager 系统的数据库设计和维护策略。请在数据库结构变更时同步更新本文档，确保文档与实际系统保持一致。*
**文档版本**: v1.2.0
**最后更新**: 2024-03-01
**维护团队**: Contract Manager Development Team

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

113
docs/PROJECT_DOCUMENTATION.md Normal file
View File

@@ -0,0 +1,113 @@
# Contract-Manager 项目文档
## 📁 文档结构总览
```
Contract-Manager/
├── 📄 README.md # 项目总体介绍
├── 📄 PROJECT_DOCUMENTATION.md # 本文档 - 项目文档总览
├── 📄 DEVELOPMENT_GUIDE.md # 开发指南
├── 📄 API_DOCUMENTATION.md # API接口文档
├── 📄 DEPLOYMENT_GUIDE.md # 部署指南
├── 📄 DATABASE_SCHEMA.md # 数据库设计文档
│
├── 📁 .trae/rules/ # 技术规则和规范文档
│ ├── 📄 server_service_rules.md # 服务器端Service开发规范
│ ├── 📄 server_repository_rules.md # 服务器端Repository开发规范
│ ├── 📄 client_service_rules.md # 客户端Service开发规范
│ ├── 📄 client_controller_rules.md # 客户端Controller开发规范
│ ├── 📄 vo_rules.md # VO对象规范
│ ├── 📄 entity_rules.md # 实体对象规范
│ └── 📄 ...其他规则文档
│
├── 📁 docs/ # 项目文档目录
│ ├── 📁 analysis/ # 技术分析报告
│ ├── 📁 task/ # 任务相关文档
│ ├── 📁 db/ # 数据库脚本和设计
│ ├── 📁 model/ # 数据模型说明
│ └── 📁 cloud/ # 云服务集成文档
│
├── 📁 server/ # 服务器端代码
└── 📁 client/ # 客户端代码
```
## 📚 核心文档说明
### 1. 技术规则文档 (.trae/rules/)
技术规则文档是项目的核心开发规范，定义了代码编写、设计模式、架构原则等：
- **server_service_rules.md** - 服务器端Service层开发规范
- **server_repository_rules.md** - 数据访问层开发规范
- **client_service_rules.md** - 客户端Service层开发规范
- **client_controller_rules.md** - 客户端控制器开发规范
- **vo_rules.md** - 视图对象(VO)设计和实现规范
- **entity_rules.md** - 实体对象设计和实现规范
### 2. 项目文档 (docs/)
项目文档包含具体的技术实现、任务分析和业务说明：
- **analysis/** - 包含技术架构分析、性能优化、代码审查报告
- **task/** - 包含具体的开发任务文档和执行记录
- **db/** - 数据库表结构、脚本和迁移文件
- **model/** - 数据模型说明和业务规则
### 3. 待完善文档 (需要新建)
#### 核心项目文档
- **README.md** - 项目简介、快速开始指南
- **DEVELOPMENT_GUIDE.md** - 开发环境搭建、开发流程指南
- **API_DOCUMENTATION.md** - REST API接口完整文档
- **DEPLOYMENT_GUIDE.md** - 项目部署、运维指南
- **DATABASE_SCHEMA.md** - 数据库架构和表关系图
#### 用户指南
- **USER_MANUAL.md** - 最终用户使用手册
- **UI_COMPONENT_GUIDE.md** - 客户端界面组件说明
## 🎯 文档更新目标
### 高优先级 (Core Documentation)
1. **项目架构文档** - 技术栈、模块划分、架构设计
2. **开发指南** - 环境配置、开发流程、代码规范
3. **API文档** - 完整的接口定义和示例
### 中优先级 (Functional Documentation)
1. **数据库文档** - 表结构、关系图、数据字典
2. **部署运维** - 安装配置、监控、日志管理
3. **业务功能** - 功能说明、使用流程
### 低优先级 (User Documentation)
1. **用户手册** - UI使用指南、常见问题
2. **开发进阶** - 性能优化、高级特性
3. **集成指南** - 第三方服务集成
## 📋 文档质量标准
### 内容要求
- **完整性** - 覆盖项目各个方面的完整信息
- **准确性** - 信息准确、代码示例可运行
- **时效性** - 定期更新，保持与代码同步
- **可读性** - 结构清晰、语言简洁
### 格式规范
- **统一格式** - 使用Markdown格式，保持一致的样式
- **目录结构** - 清晰的章节组织和目录导航
- **代码示例** - 提供可执行的代码示例和配置
- **图表说明** - 使用图表辅助说明复杂概念
## 🚀 更新计划
1. **第一阶段** - 核心文档完善 (高优先级)
2. **第二阶段** - 功能文档补充 (中优先级)
3. **第三阶段** - 用户指南和最佳实践 (低优先级)
## 📞 文档维护
- **责任分工** - 各模块开发者负责对应文档的维护
- **更新频率** - 代码变更时同步更新相关文档
- **审核机制** - 重要文档变更需要技术负责人审核
- **版本控制** - 文档版本与代码版本保持同步
---
*本文档将持续更新以反映项目的最新状态和最佳实践。*

0
docs/天眼查下载信用报告.md Normal file
View File