# 工具

**Repository Path**: tranquility-behind-the-waves/tool

## Basic Information

- **Project Name**: 工具
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-16
- **Last Updated**: 2025-10-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 项目说明文档

## 项目简介

这是一个基于 Spring Boot 的多功能 Web 应用系统，主要提供以下两大核心功能：

1. **PDF拼版工具** - 可视化PDF页面编辑与拼接
2. **公式计算系统** - 可视化拖拽式数学公式设计与计算

---

## 技术栈

### 后端
- **Spring Boot 3.5.6** - Web应用框架
- **Java 17** - 编程语言
- **Apache PDFBox 3.0.5** - PDF处理库
- **Aviator 5.4.3** - 表达式引擎
- **Lombok** - 简化Java代码

### 前端
- 原生 **HTML5 + CSS3 + JavaScript**
- 响应式设计，支持移动端访问

### 服务端口
- 默认端口：**9999**

---

## 功能一：PDF拼版工具

### 功能概述

PDF拼版工具是一个强大的可视化PDF编辑系统，允许用户上传多个PDF文件，通过拖拽、缩放、旋转、裁切等操作，将多个PDF页面拼接成一个新的PDF文档。

### 界面展示

![PDF拼版工具界面](img/pdf.png)

### 功能特点

✅ **多文件上传** - 支持同时上传多个PDF文件  
✅ **页面预览** - 自动生成页面缩略图  
✅ **可视化编辑** - 拖拽式画布操作  
✅ **灵活布局** - 自定义页面尺寸（支持A3、A4、A5等预设）  
✅ **精确控制** - 支持毫米级精度的位置、缩放、旋转调整  
✅ **页面裁切** - 支持四边距离裁切和矩形区域裁切  
✅ **重叠模式** - 可选择允许或禁止页面元素重叠  
✅ **实时预览** - 画布实时显示最终效果  
✅ **批量处理** - 一次性配置多页PDF拼版  

### 使用方法

#### 1. 访问页面
打开浏览器访问：`http://localhost:9999/pdf/index.html`

#### 2. 上传PDF文件
- 点击"选择文件"按钮或拖拽PDF文件到上传区域
- 系统自动解析PDF页面并生成缩略图

#### 3. 设计PDF布局
- 点击"添加页面"创建目标PDF页面
- 设置页面尺寸（可选择A3、A4、A5预设或自定义）
- 从左侧拖拽源PDF页面到画布中

#### 4. 调整页面元素
- **位置调整**：拖拽元素到目标位置
- **缩放**：调整元素的X/Y缩放比例
- **旋转**：设置旋转角度（0-360度）
- **裁切**：设置裁切区域和边距

#### 5. 生成PDF
- 点击"生成并下载PDF"按钮
- 系统自动生成拼版后的PDF文件并下载

### API接口说明

#### 1. 上传PDF文件
```http
POST /api/pdf/upload
Content-Type: multipart/form-data

参数:
- file: PDF文件（支持多文件）

响应:
{
  "success": true,
  "message": "文件上传成功",
  "data": [
    {
      "fileId": "uuid",
      "fileName": "原文件名.pdf",
      "pageIndex": 0,
      "widthMm": 210,
      "heightMm": 297,
      "rotation": 0,
      "thumbnailBase64": "base64编码的缩略图"
    }
  ]
}
```

#### 2. 拼接PDF
```http
POST /api/pdf/merge
Content-Type: application/json

请求体:
{
  "outputFileName": "输出文件名",
  "targetPages": [
    {
      "widthMm": 210,
      "heightMm": 297,
      "sourcePages": [
        {
          "sourceFileId": "文件ID",
          "sourcePageIndex": 0,
          "transform": {
            "offsetX": 0,
            "offsetY": 0,
            "scaleX": 1.0,
            "scaleY": 1.0,
            "rotation": 0,
            "cropTop": 0,
            "cropBottom": 0,
            "cropLeft": 0,
            "cropRight": 0
          }
        }
      ]
    }
  ]
}

响应:
返回生成的PDF文件（二进制流）
```

#### 3. 清理缓存
```http
DELETE /api/pdf/cache/{fileId}  # 清理指定文件缓存
DELETE /api/pdf/cache           # 清理所有缓存

响应:
{
  "success": true,
  "message": "缓存清理成功"
}
```

### 核心技术实现

- **坐标系转换**：自动处理前端坐标系（左上角原点）与PDF坐标系（左下角原点）的转换
- **图形变换**：使用变换矩阵实现平移、缩放、旋转的复合操作
- **裁切处理**：支持基于四边距离的裁切和矩形区域裁切
- **内存管理**：使用ConcurrentHashMap缓存PDF文档，支持主动清理

---

## 功能二：公式计算系统

### 功能概述

公式计算系统是一个可视化的数学表达式设计与计算平台。用户可以通过拖拽式流程图界面设计复杂的数学公式，系统自动编译为可执行的表达式，并支持保存、加载、管理公式库。

### 界面展示

![公式计算系统界面](img/公式.png)

### 功能特点

✅ **可视化设计** - 拖拽式流程图界面，无需编写代码  
✅ **丰富的运算符** - 支持加减乘除、取整、最大最小值等  
✅ **参数化输入** - 自定义输入参数及默认值  
✅ **常量支持** - 提供数字、字符串、布尔常量节点，无需定义参数即可使用  
✅ **条件判断** - 支持比较运算、逻辑运算、三目运算、if-elsif-else分支  
✅ **实时计算** - 即时验证公式正确性  
✅ **公式管理** - 保存、加载、删除公式  
✅ **公式库** - 统一管理所有已保存的公式  
✅ **表达式缓存** - 提升计算性能  
✅ **错误提示** - 友好的错误信息提示  

### 使用方法

#### 1. 访问公式管理页面
打开浏览器访问：`http://localhost:9999/aviator/index.html`

#### 2. 创建新公式
- 点击"新建公式"按钮
- 进入可视化编辑器页面

#### 3. 设计公式（编辑器页面）
- **定义参数**：设置输入参数名称、类型、默认值
- **拖拽节点**：从工具栏拖拽运算节点到画布
  - 🔢 **常量值**：拖拽常量节点（数字/字符串/布尔），无需定义参数即可使用
    - 数字常量：用于数值比较，如判断结果是否大于 0
    - 字符串常量：用于文本比较，如判断颜色是否等于 '红'
    - 布尔常量：用于逻辑判断，可选 true 或 false
- **连接节点**：连接输入和输出端口构建计算流程
- **设置属性**：为每个节点配置属性（如运算符类型、常量值等）
- **生成表达式**：系统自动生成计算表达式

#### 4. 测试公式
- 在测试面板输入参数值
- 点击"计算"按钮查看结果
- 验证公式是否正确

#### 5. 保存公式
- 填写公式名称和描述
- 点击"保存"按钮
- 公式自动保存到本地JSON文件

#### 6. 管理公式
- 返回公式管理页面查看所有已保存的公式
- 支持编辑、删除操作
- 按更新时间倒序显示

### API接口说明

#### 1. 计算公式
```http
POST /api/formula/calculate
Content-Type: application/json

请求体:
{
  "expression": "a + b * 2",
  "inputs": {
    "a": 10,
    "b": 5
  }
}

响应:
{
  "success": true,
  "message": "计算成功",
  "data": {
    "success": true,
    "outputs": {
      "result": 20
    },
    "executionTime": 5
  }
}
```

#### 2. 保存公式
```http
POST /api/formula/save
Content-Type: application/json

请求体:
{
  "name": "公式名称",
  "description": "公式描述",
  "expression": "a + b * 2",
  "parameters": {
    "a": {
      "id": "a",
      "name": "参数A",
      "type": "number",
      "defaultValue": 0
    }
  },
  "nodes": [...],
  "connections": [...]
}

响应:
{
  "success": true,
  "message": "公式保存成功: 公式名称"
}
```

#### 3. 获取公式列表
```http
GET /api/formula/list

响应:
{
  "success": true,
  "message": "获取成功",
  "data": [
    {
      "name": "公式名称",
      "description": "公式描述",
      "expression": "a + b * 2",
      "createTime": 1697468400000,
      "updateTime": 1697468400000,
      "parameters": {...},
      "nodes": [...],
      "connections": [...]
    }
  ]
}
```

#### 4. 加载指定公式
```http
GET /api/formula/load/{formulaName}

响应:
{
  "success": true,
  "message": "加载成功",
  "data": {
    "name": "公式名称",
    "description": "公式描述",
    "expression": "a + b * 2",
    ...
  }
}
```

#### 5. 删除公式
```http
DELETE /api/formula/delete/{formulaName}

响应:
{
  "success": true,
  "message": "公式删除成功: 公式名称"
}
```

### 核心技术实现

- **表达式引擎**：基于 Aviator 5.4.3，支持复杂的数学表达式计算
- **表达式缓存**：使用 ConcurrentHashMap 缓存编译后的表达式，提升性能
- **文件存储**：公式保存为JSON格式，存储在 `./formulas` 目录
- **文件名处理**：自动清理非法字符，支持中文文件名
- **异常处理**：完善的错误捕获和友好的错误提示

### 使用示例

#### 示例1：字符串常量比较
**场景**：判断颜色参数是否等于"红"

1. 定义参数：创建字符串参数 `颜色`，默认值为 "红"
2. 拖拽节点：
   - 输入参数节点：颜色
   - 字符串常量节点：设置值为 "红"
   - 比较运算节点：选择 "等于" (==)
   - 输出结果节点
3. 连接节点：颜色 → 比较运算 ← 常量"红" → 输出结果
4. 生成表达式：`(颜色 == '红')`
5. 测试：输入颜色="红"，结果为 `true`

#### 示例2：数字常量比较
**场景**：判断结果是否大于0

1. 定义参数：创建数字参数 `结果`，默认值为 5
2. 拖拽节点：
   - 输入参数节点：结果
   - 数字常量节点：设置值为 0
   - 比较运算节点：选择 "大于" (>)
   - 输出结果节点
3. 连接节点：结果 → 比较运算 ← 常量 0 → 输出结果
4. 生成表达式：`(结果 > 0)`
5. 测试：输入结果=5，结果为 `true`

### 公式存储位置

公式以JSON格式存储在项目根目录的 `formulas` 文件夹中：
```
demo/
├── formulas/
│   ├── 公式名称1.json
│   ├── 公式名称2.json
│   ├── 常量测试.json        # 字符串常量示例
│   ├── 数字常量测试.json    # 数字常量示例
│   └── ...
```

---

## 快速开始

### 环境要求
- **JDK 17+**
- **Maven 3.6+**
- **现代浏览器**（Chrome、Firefox、Edge等）

### 启动步骤

#### 1. 克隆或下载项目
```bash
cd demo
```

#### 2. 编译项目
```bash
mvn clean package
```

#### 3. 运行项目
```bash
java -jar target/demo-0.0.1-SNAPSHOT.jar
```

或者直接运行主类：
```bash
mvn spring-boot:run
```

#### 4. 访问应用

启动成功后，访问以下地址：

- **首页**：http://localhost:9999/
- **PDF拼版工具**：http://localhost:9999/pdf/index.html
- **公式计算系统**：http://localhost:9999/aviator/index.html

---

## 配置说明

### application.yml

```yaml
server:
  port: 9999  # 服务端口

spring:
  servlet:
    multipart:
      max-file-size: 1000MB      # 最大文件上传大小
      max-request-size: 1000MB   # 最大请求大小
```

### 公式存储路径

默认公式存储路径为 `./formulas`，可通过配置修改：
```yaml
formula:
  storage:
    path: ./formulas  # 公式存储目录
```

---

## 项目结构

```
demo/
├── src/main/java/com/example/
│   ├── pdfSplice/              # PDF拼版模块
│   │   ├── controller/         # 控制器
│   │   │   └── PdfController.java
│   │   ├── service/            # 服务层
│   │   │   └── PdfService.java
│   │   └── model/              # 数据模型
│   │       ├── PdfMergeRequest.java
│   │       ├── PdfPageInfo.java
│   │       ├── TargetPageConfig.java
│   │       ├── MergePageConfig.java
│   │       └── PageTransform.java
│   │
│   ├── aviatorCount/           # 公式计算模块
│   │   ├── controller/         # 控制器
│   │   │   └── FormulaController.java
│   │   ├── service/            # 服务层
│   │   │   └── DynamicFormulaCalculator.java
│   │   └── model/              # 数据模型
│   │       ├── CalculateRequest.java
│   │       ├── FormulaResult.java
│   │       └── SavedFormula.java
│   │
│   └── DemoApplication.java    # 应用入口
│
├── src/main/resources/
│   ├── static/                 # 静态资源
│   │   ├── pdf/               # PDF拼版前端
│   │   │   ├── index.html
│   │   │   ├── css/
│   │   │   └── js/
│   │   └── aviator/           # 公式计算前端
│   │       ├── index.html
│   │       ├── edit.html
│   │       ├── css/
│   │       └── js/
│   └── application.yml         # 配置文件
│
├── formulas/                   # 公式存储目录
├── img/                        # 文档图片
│   ├── pdf.png                # PDF拼版工具截图
│   └── 公式.png               # 公式计算系统截图
├── pom.xml                     # Maven配置
└── README.md                   # 说明文档
```

---

## 注意事项

### PDF拼版工具
1. 上传的PDF文件缓存在内存中，长时间运行建议定期清理缓存
2. 大文件处理可能需要较长时间，请耐心等待
3. 确保浏览器支持现代JavaScript特性
4. 坐标单位统一使用毫米（mm）

### 公式计算系统
1. 公式以JSON格式存储在本地文件系统
2. 公式名称支持中文，但会自动清理特殊字符
3. 表达式遵循Aviator语法规则
4. 计算结果会缓存，提升性能

---

## 常见问题

### 1. 端口被占用
如果9999端口被占用，请修改 `application.yml` 中的端口配置。

### 2. 文件上传失败
检查文件大小是否超过1000MB限制，可在配置文件中调整。

### 3. 公式保存失败
确保 `formulas` 目录存在且有写入权限。

### 4. PDF生成失败
检查浏览器控制台是否有错误信息，确认所有源PDF文件已正确上传。

---

## 技术支持

如有问题或建议，请联系开发团队。

---

## 许可证

本项目仅供学习和内部使用。

---

**祝使用愉快！** 🎉