CN_Gather/tools/report-generator/README.md

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接口方式

# 简单占位符替换
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方式

// 注入服务
@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)

ProcessOptions options = ProcessOptions.builder()
    .enablePlaceholder(true)      // 启用占位符替换
    .enableBookmark(true)         // 启用书签处理
    .enableDynamicTable(true)     // 启用动态表格
    .enableAutoPage(true)         // 启用自动分页
    .placeholderPattern("${}")    // 占位符格式
    .build();

模板源配置 (TemplateSource)

// 文件路径方式
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. 资源管理: 自动资源清理和释放