新增工具模块，并添加了子模块-报告工具生成模块

2025-09-01 11:06:00 +08:00
parent 3951b71fff
commit 0977a77eed
22 changed files with 3486 additions and 0 deletions
--- a/tools/report-generator/README.md
+++ b/tools/report-generator/README.md
@@ -0,0 +1,126 @@
+# Report Generator 报告生成工具
+
+通用的文档模板处理和报告生成工具，支持Word文档的动态内容生成。
+
+## 功能特性
+
+### 1. 基础功能
+- ✅ 占位符替换 (`${key}` 格式)
+- ✅ Word文档处理 (基于Apache POI)
+- ✅ 模板文件管理
+- ✅ 多种输入输出方式 (文件路径、流、字节数组)
+
+### 2. 高级功能
+- ✅ 书签定位插入 (基于docx4j)
+- ✅ 动态表格生成
+- ✅ 文档合并
+- ✅ 样式管理 (字体、颜色、对齐)
+- ✅ 自动分页控制
+- ✅ 深拷贝支持
+
+### 3. 扩展功能
+- 🔄 自定义处理器插件化
+- 🔄 复杂表达式支持
+- 🔄 模板验证
+- 🔄 缓存优化
+
+## 架构设计
+
+```
+report-generator/
+├── controller/              # HTTP接口层
+├── service/                # 业务逻辑层
+├── engine/                 # 模板引擎核心
+│   ├── DocumentProcessor   # 文档处理器接口
+│   ├── WordEngine         # Word处理引擎
+│   ├── PlaceholderEngine  # 占位符处理引擎
+│   └── BookmarkEngine     # 书签处理引擎
+├── model/                  # 数据模型
+│   ├── TemplateRequest    # 处理请求模型
+│   ├── TemplateSource     # 模板源定义
+│   └── ProcessResult      # 处理结果
+├── util/                   # 工具类
+└── exception/             # 异常处理
+```
+
+## 使用示例
+
+### 1. HTTP接口方式
+
+```bash
+# 简单占位符替换
+POST /api/report/process
+Content-Type: multipart/form-data
+
+{
+    "templateFile": <template.docx>,
+    "data": {
+        "name": "张三",
+        "date": "2024-01-01",
+        "amount": "1000.00"
+    },
+    "outputFileName": "report.docx"
+}
+```
+
+### 2. Java API方式
+
+```java
+// 注入服务
+@Autowired
+private ReportGeneratorService reportService;
+
+// 创建请求
+TemplateRequest request = TemplateRequest.builder()
+    .templatePath("template.docx")
+    .data(Map.of("name", "张三", "date", "2024-01-01"))
+    .outputPath("result.docx")
+    .options(ProcessOptions.builder()
+        .enablePlaceholder(true)
+        .enableBookmark(true)
+        .build())
+    .build();
+
+// 处理模板
+ProcessResult result = reportService.processTemplate(request);
+```
+
+## 配置说明
+
+### 处理选项 (ProcessOptions)
+```java
+ProcessOptions options = ProcessOptions.builder()
+    .enablePlaceholder(true)      // 启用占位符替换
+    .enableBookmark(true)         // 启用书签处理
+    .enableDynamicTable(true)     // 启用动态表格
+    .enableAutoPage(true)         // 启用自动分页
+    .placeholderPattern("${}")    // 占位符格式
+    .build();
+```
+
+### 模板源配置 (TemplateSource)
+```java
+// 文件路径方式
+TemplateSource.fromFile("path/to/template.docx")
+
+// 输入流方式  
+TemplateSource.fromStream(inputStream)
+
+// 字节数组方式
+TemplateSource.fromBytes(byteArray)
+```
+
+## 技术栈
+
+- **Apache POI**: Word文档基础操作
+- **docx4j**: 高级Word文档处理
+- **Spring Boot**: 框架支持
+- **Hutool**: 工具库
+- **Jackson**: JSON处理
+
+## 性能优化
+
+1. **模板缓存**: 常用模板缓存减少IO
+2. **流式处理**: 大文件流式处理避免内存溢出
+3. **异步处理**: 支持异步批量处理
+4. **资源管理**: 自动资源清理和释放