doc-etl/README.md

# 文档处理系统

本系统用于处理和转换文档，支持PDF和Word文档的处理。

## 系统要求

### 必需组件

1. Python 3.8 或更高版本
2. LibreOffice（用于文档格式转换）
   - 下载地址：https://www.libreoffice.org/download/download/
   - 安装后需要将安装目录（通常是 `C:\Program Files\LibreOffice\program` 或 `C:\Program Files (x86)\LibreOffice\program`）添加到系统 PATH 环境变量
   - 如果安装后仍然报错，请尝试重启系统

3. Tesseract OCR（用于图片文字识别）
   - 下载地址：https://github.com/UB-Mannheim/tesseract/wiki
   - 安装时选择"添加到系统路径"选项

### Python 依赖

所有必需的 Python 包都列在 `requirements.txt` 文件中。使用以下命令安装：

```bash
pip install -r requirements.txt
```

## 功能特性

- 支持多种文档格式的处理：
  - PDF 文件
  - Word 文档 (.doc, .docx)
  - HTML 文件 (.html, .htm)
  - Excel 文件 (.xls, .xlsx)
- 自动提取文档中的表格和图片
- 智能清理和格式化文本内容
- 支持多种输出格式：
  - Word 文档 (.docx)
  - 纯文本文件 (.txt)
  - Markdown 文件 (.md)
- 提供 RESTful API 接口
- 高级OCR图像识别功能：
  - 独立的OCR测试Web界面
  - 多种图像预处理算法
  - 支持中文优化的OCR处理
  - 自动选择最佳OCR结果
  - 直观显示不同处理方法的效果对比
  - 可视化处理前后的图像变化

## 最近更新

### 2024年6月15日
- **移除文档中的图片标题**
  - 移除了清洗后文档中的"图1"、"图2"等图片标题
  - 保留图片在文档中的原始位置和显示
  - 简化文档结构，使文档更加简洁
  - 优化图片处理流程，确保只保留图片内容
  - 保持文本输出中的图片引用标记，但不再显示编号
  - 更接近于用户预期的输出效果

### 2024年6月14日
- **优化图片处理，保持原始位置且直接嵌入**
  - 改进图片处理逻辑，保持图片在原始文档中的相对位置
  - 不再生成外部images目录，直接将图片嵌入到清洗后的文档中
  - 智能识别原始文档中图片与文本的关联关系，确保图片插入的位置更合理
  - 直接从内存中的图片数据创建图片对象，提高处理速度
  - 简化图片说明caption格式，不再显示文件名，只保留编号信息
  - 针对无法确定原始位置的图片，统一添加到文档末尾
  - 图片处理过程更加稳定，避免因外部文件操作导致的错误
  - 提升用户体验，文档外观更加接近原始文档

### 2024年6月13日
- **修复清洗后Word文档图片丢失问题**
  - 增加了图片提取和保存功能，确保清洗后的Word文档保留原始图片
  - 使用多种方法提取文档中的图片，支持多种图片格式（PNG、JPG、GIF、BMP等）
  - 智能过滤无效和过小的图片，只保留有意义的内容
  - 自动在段落间均匀分布图片，保持文档的可读性和美观性
  - 为每张图片添加标题和编号，方便引用
  - 所有图片保存在独立的images目录，便于管理和查看
  - 在文本输出中添加图片引用标记，保持文档内容的完整性
  - 增强文档处理流程的稳定性，防止因图片处理错误导致的中断

### 2024年6月12日
- **TXT文件表格输出HTML标签**
  - 改进表格处理逻辑，使TXT文件中的表格也能以HTML标签形式输出
  - 保持与Word文档中的表格输出格式一致，提供结构化的表格内容
  - 优化TXT文件处理流程，正确保留HTML标签而不是转换为纯文本
  - 确保表格的合并单元格属性和结构信息在TXT文件中也能被完整保留
  - 保持HTML标签在TXT文件中的原始格式，不进行换行符替换
  - 改进文本合并逻辑，智能区分普通文本和HTML标签内容
  - 简化用户使用流程，无需额外操作即可获得格式一致的输出文件
  - 提高系统处理效率和文档格式统一性

### 2024年6月11日
- **同时支持HTML标签显示和HTML文件生成**
  - 优化表格处理功能，兼顾多种输出需求
  - 移除Word文档中自动添加的表格标题，保持文档结构简洁
  - Word文档中直接以HTML标签形式显示所有表格，方便查看表格结构
  - 同时生成独立的HTML文件，提供完整的表格视图，支持交互和打印
  - 在Word文档中添加蓝色超链接提示，指引用户查看对应的HTML文件
  - 改进HTML样式，增强响应式布局和打印支持
  - 优化表格HTML标签生成过程，确保标签规范性和一致性
  - 增强错误处理，即使某些表格转换失败也能保持系统稳定
  - 提升整体文档处理流程的健壮性和用户体验

### 2024年6月10日
- **采用HTML标签形式输出表格**
  - 改进表格处理机制，直接输出HTML标签形式的表格，而非创建Word表格
  - 精确保留所有表格结构信息，包括表头、主体和合并单元格属性
  - 自动为表格生成符合HTML规范的标签，包括class和id属性
  - 正确处理表格中的垂直和水平合并单元格，添加rowspan和colspan属性
  - 将表格标签以等宽字体显示，提高可读性和直观性
  - 优化标签生成过程，严格遵循HTML表格标准
  - 自动区分表头和数据行，使用正确的thead和tbody标签
  - 简化表格处理流程，提高效率和准确性

### 2024年6月9日
- **改进Word文档表格显示方式**
  - 修改表格处理机制，直接在Word文档中显示表格，不再需要外部HTML文件
  - 准确复制原始表格的结构、内容和合并单元格信息
  - 保留表格样式并自动设置表头格式
  - 正确处理垂直和水平合并的单元格
  - 改进表格位置控制，保持与原始文档的一致性
  - 优化表格边框和样式，提供更专业的外观
  - 简化处理流程，提高文档生成效率
  - 修复合并单元格时的潜在错误

### 2024年6月8日
- **修复Word文档打开问题并改进表格处理**
  - 解决了清洗后Word文档无法打开的关键问题
  - 优化HTML表格生成方式，确保文档处理的稳定性
  - 在Word文档中添加醒目的HTML表格文件引用提示
  - 保留表格的文本格式作为备用显示方式
  - 改进错误处理，提供更详细的诊断信息
  - 简化文档处理流程，提高代码可维护性
  - 增强HTML表格文件的样式，提供更好的打印支持
  - 改进文档处理日志，便于追踪处理过程

### 2024年6月7日
- **表格直接HTML输出功能增强**
  - 修改表格处理机制，现在所有表格都将以HTML格式输出而非文本格式
  - 彻底解决复杂表格的显示问题，包括多层表头和合并单元格
  - 自动为每个表格生成独特的HTML标识符，确保正确引用
  - 提供更美观的表格样式，包括悬停效果和自适应宽度
  - 改进表格边框和单元格间距，提升阅读体验
  - 保留单元格格式化内容（如换行符）并在HTML中正确显示
  - 针对打印场景优化表格样式，确保打印输出质量
  - 技术说明：由于Word文档格式限制，HTML表格将保存在独立的HTML文件中

### 2024年6月6日
- **增强复杂表格识别与处理能力**
  - 优化表格类型自动识别算法，通过多维度特征分析提高复杂表格的识别精度
  - 增强表格结构分析能力，支持更精确地识别垂直和水平合并单元格
  - 改进多级表头处理，提高复杂表头的识别和解析能力
  - 引入表格宽高比分析，自动识别宽表格和复杂结构表格
  - 新增单元格数一致性检查机制，提高对不规则表格的处理能力
  - 优化垂直合并单元格的内容填充算法，改进空单元格的值传播机制
  - 添加更详细的表格处理日志，便于诊断和调试复杂表格处理问题
  - 完善异常处理，提高处理复杂表格时的稳定性和鲁棒性

### 2024年6月5日
- **模块化表格处理系统升级**
  - 重构了表格处理架构，将不同类型的表格处理逻辑拆分为专门的处理器
  - 实现了针对五种特殊表格类型的专用处理器：
    - 多级表头表格处理器：处理具有复杂多级表头结构的表格
    - 合并单元格密集型表格处理器：优化处理含有大量合并单元格的表格
    - 带计算功能的表格处理器：识别并处理包含公式和计算的表格
    - 嵌套表格处理器：处理表格内嵌套的子表格结构
    - 跨页长表格处理器：正确识别和处理跨越多页的长表格
  - 优化表格识别机制，智能匹配最适合的处理器
  - 提高表格转文本的准确性和可读性
  - 保持与原有系统的兼容性，同时提高处理复杂表格的能力
  - 增强了系统对特殊表格结构的识别率和处理精度

### 2024年6月2日
- 改进Markdown表格转换功能：
  - 修复了合并单元格内容重复显示的问题
  - 修复了空单元格自动填充相邻值的问题
  - 优化表格处理逻辑，正确处理多级表头和复杂表格结构
  - 确保合并单元格的内容仅在原始单元格位置显示，被合并的单元格保持为空

### 2024年6月1日
- **修复服务端文件处理过程中的类型错误**
  - 解决文件处理后删除临时文件时出现的`'dict' object has no attribute 'strip'`错误
  - 增强了`main.py`中处理文本内容时的类型安全性，确保只对字符串类型调用字符串方法
  - 添加了对处理文件时`all_content`合并时的严格类型检查，实现对混合内容类型（字符串、字典等）的安全处理
  - 优化了临时文件和目录清理过程，增加类型检查以避免对非字符串类型执行路径操作
  - 改进临时文件删除的安全性，使用`safe_delete_file`函数确保字符串类型参数
  - 提高了文件处理后清理逻辑的健壮性，避免因类型不匹配导致的处理中断
  - 完善错误处理机制，提供更详细的日志信息，便于快速定位问题

### 2024年5月31日
- **修复表格文本提取过程中的类型错误**
  - 解决了在无效表格转换为文本时出现的`'dict' object has no attribute 'strip'`错误
  - 增强了`save_as_docx`方法中对`_extract_table_text`返回值的类型安全检查
  - 确保只有在返回值是字符串类型时才调用`strip()`方法
  - 优化了表格文本提取的错误处理流程，提高系统处理复杂表格的稳健性
  - 完善了不同表格类型的处理逻辑，确保各种特殊结构表格都能被正确处理
  - 修复了在表格无效时可能触发的类型错误，保证表格处理流程不会因类型不匹配而中断

### 2024年5月30日
- **修复文本清理过程中的类型错误**
  - 解决了在文本清理过程中出现的`'dict' object has no attribute 'strip'`错误
  - 增强了`_clean_text`方法中的类型检查，确保只对字符串类型对象调用字符串方法
  - 改进了文本文件生成逻辑，添加针对不同数据类型的处理策略
  - 优化了元数据字典的内容提取方式，确保其正文内容能够被包含在文本输出中
  - 提高了代码的健壮性，可以正确处理混合类型的内容列表
  - 完善了错误处理机制，避免因类型不匹配导致的处理中断

### 2024年5月29日
- **修复文档去重处理异常**
  - 解决了处理带元数据的文档时出现的`'dict' object has no attribute 'startswith'`错误
  - 增强了_remove_duplicates方法，使其能够正确处理字典类型的元数据结构
  - 改进了内部类型检查，区分处理字符串、字典、元组和列表等不同数据类型
  - 优化了去重机制，保证包含元数据的文档正常处理不会中断
  - 更新了相关方法的类型提示，明确方法可以处理任何类型的元素
  - 完善对特殊数据类型的保留逻辑，确保元数据不会在去重过程中丢失

### 2024年5月28日
- **增强复杂表格结构处理能力**
  - 实现多级表头表格的自动识别与处理，支持最多4级嵌套表头
  - 完善对复杂表头结构的分析，正确处理跨行跨列的表头单元格
  - 针对多级表头表格优化Markdown输出格式，保持原始表格的层次结构
  - 改进表格预处理流程，添加表格结构类型自动检测功能
  - 优化合并单元格处理逻辑，确保复杂表格数据的完整性和准确性
  - 引入表格元数据记录机制，保存表格结构特征以便后续处理
  - 完善复杂表格的调试日志，便于排查处理过程中的问题

### 2024年5月27日
- **修复表格处理异常错误**
  - 解决了处理特殊表格时出现的`'dict' object has no attribute 'strip'`类型错误
  - 增强了内容过滤函数的类型安全检查，避免对非字符串类型应用字符串方法
  - 改进了对多种数据类型（字典、元组、列表等）的兼容性处理
  - 确保在处理表格时不会因类型错误而导致文档处理中断
  - 优化了错误处理机制，提供更详细的错误信息以便于调试
  - 提高了代码的健壮性，能更好地处理各种格式和结构的输入数据

### 2024年5月26日
- **增强特殊结构表格处理能力**
  - 优化对特殊格式表格的识别能力，特别是键值对形式的表格（如账号、订单号等信息表）
  - 新增键值对表格专用渲染模式，确保所有键值对数据都被正确提取
  - 改进单元格内容提取逻辑，避免遗漏特殊格式的单元格内容
  - 引入表格结构智能分析，自动识别不同类型的表格并应用最合适的处理方法
  - 完善对"PO-Number"、"Account No."等业务类信息字段的特殊处理
  - 添加了多种关键字模式匹配，提高对各类业务表格的兼容性
  - 优化文本提取过程，确保每个文本片段都能被完整保留

### 2024年5月25日
- **优化Markdown表格格式输出**
  - 严格按照原文档中的表格格式输出Markdown表格，保留空单元格
  - 去除过度智能填充功能，避免自动填充空单元格导致的格式不一致
  - 保留完整表格结构，包括所有的空行
  - 只处理显式标记的合并单元格，不进行推断性的内容填充
  - 确保表格的每个单元格精确反映原始文档中的内容
  - 简化表格处理逻辑，提高处理速度和准确性

### 2024年5月24日
- **优化Markdown输出格式**
  - 移除Markdown输出中的文档元数据信息（如创建时间、作者、备注等）
  - 保留DOCX和TXT输出中的文档元信息，不影响其完整性
  - 重构元数据处理逻辑，使用类型标记区分不同内容类型
  - 提高代码的可维护性和扩展性
  - 优化内部数据结构，便于后续自定义输出格式
  - 改进文本处理流程，统一处理文本和结构化内容

### 2024年5月23日
- **修复PDF转Word时图片丢失的问题**
  - 增加了多种图片提取方法，确保即使在PDF转DOCX过程中丢失图片也能正确保留
  - 直接从PDF源文件提取图片，不再完全依赖转换后的DOCX文档
  - 改进图片处理流程，确保OCR结果被正确保存到最终输出
  - 增强Markdown图片处理逻辑，优化图片路径管理和文件复制过程
  - 添加详细日志和错误诊断信息，便于问题排查
  - 优化图片文件存储结构，避免图片重复处理
  - 增加图片处理失败时的备选方案，提高系统鲁棒性
  - 解决Markdown文档中图片无法显示的问题

### 2024年5月21日
- **增强复杂表格处理的安全性和稳定性**
  - 全面优化索引安全处理，解决表格解析中的索引越界问题
  - 增加表格行列索引检查机制，防止数组访问异常
  - 引入垂直合并传播机制，自动填充复杂表格中的间隔空白单元格
  - 增强多级分类表格处理，针对药品分类等特殊表格格式的优化
  - 改进空白单元格智能填充算法，分析上下文识别合并单元格模式
  - 优化错误日志记录，提供精确的错误位置信息便于问题定位
  - 统一文本和Markdown输出处理逻辑，确保不同格式输出的一致性
  - 修复多行多列复杂表格中的内容缺失问题，提高数据完整性

### 2024年5月20日
- **增强复杂表格合并单元格识别能力**
  - 改进垂直合并单元格的识别逻辑，即使未被正确标记的合并单元格也能被识别出来
  - 特别优化对药品分类等表格中常见的第一列垂直合并单元格的处理
  - 新增内容一致性检测机制，自动识别内容相同但分布在不同行的单元格
  - 添加空白单元格智能填充机制，推断可能的合并单元格内容
  - 统一文本与Markdown表格输出中对合并单元格的处理逻辑
  - 对合并单元格内容进行正确复制，确保表格展示的结构完整性
  - 提高对格式不规范表格的兼容性和处理能力

### 2024年5月19日
- **表格处理模块化重构**
  - 将表格处理相关代码抽取到独立模块`cxs_table_processor.py`
  - 实现`TableProcessor`类，封装所有表格相关的处理功能
  - 保留`TableData`类作为表格数据的标准存储结构
  - 优化代码结构，提高可维护性和扩展性
  - 改进表格处理模块与主程序的交互接口
  - 实现统一的表格处理方法调用方式
  - 便于后续对表格处理功能的单独升级和优化

### 2024-05-16
- 增强了复杂表格处理能力
  - 优化了对合并单元格表格的识别和处理
  - 降低了表格有效性的判断门槛，能够识别更多种类的表格
  - 改进了表格到Markdown的转换，添加了HTML格式输出选项
  - 完善了对垂直合并单元格的处理逻辑
  - 增强了表格内容矩阵的构建和处理
  - 优化了药品分类等复杂结构表格的识别
  - 改进了表格文本输出格式，提高可读性

### 2024-05-15
- 修复了cxs_doc_cleaner.py中的语法错误
  - 解决了处理文档元素时的try-except块和缩进结构问题
  - 改进了表格和段落处理的代码结构
  - 确保所有异常处理逻辑正确嵌套
  - 优化了错误信息输出格式

### 2024-05-12
- 修复了`Table`类初始化错误问题
  - 创建了自定义`TableData`类代替直接使用`docx.table.Table`
  - 解决了`Table.__init__() missing 2 required positional arguments: 'tbl' and 'parent'`错误
  - 重构了相关代码以适配新的类结构
  - 优化了列属性处理方式
  - 改进了单元格访问方法
- 添加了`test_big_file.py`工具
  - 专门用于从大型复杂Word文档中提取表格
  - 支持自动识别文档中的所有表格
  - 实现了更强大的表格内容提取逻辑
  - 可以处理合并单元格和复杂结构
  - 生成格式友好的表格文本输出

### 2024-05-02
- 修复文档中图片OCR无法识别的问题
  - 添加pytesseract显式导入，确保OCR组件可用
  - 优化Tesseract OCR路径自动检测和配置流程
  - 增加pytesseract版本检测机制，确保OCR组件正常工作
  - 改进OCR处理流程，添加直接调用pytesseract模式，不再完全依赖pdf_processor
  - 添加多重OCR尝试策略，提高图片文字识别成功率
  - 增强OCR错误处理和日志记录，便于问题诊断
  - 简化单图片OCR处理逻辑，增加文本预览功能
  - 修复PdfProcessor类中缺少_is_valid_image方法的问题，解决图片验证失败的错误

### 2024-01-20
- 修复文档中图片OCR识别问题
  - 解决了从Word文档中提取的图片无法被OCR识别的问题
  - 增加了Tesseract OCR路径自动检测和配置功能
  - 添加了独立的图片OCR测试工具，方便排查问题
  - 优化了图像提取和OCR处理流程，提高识别成功率
  - 增强了图像预处理算法，改进对不同格式图片的支持
  - 新增fix_tesseract_path.py脚本，提供一键修复和测试功能

### 2024-01-19
- 修复Word文档图像提取和OCR功能
  - 修复了Word文档处理流程中图像提取功能未被正确调用的问题
  - 增强了调试日志系统，提供更详细的图像提取和OCR处理信息
  - 优化了文档处理流程，确保图像OCR结果被正确保存和展示
  - 添加了更多统计信息，包括图像提取数量和OCR识别成功率
  - 改进了不同文件格式的处理逻辑，确保最大兼容性
  - 增强了错误处理能力，提高了系统的鲁棒性和稳定性

### 2024-01-18
- 增强了DOCX文档中图像的提取与OCR识别能力
  - 实现了三种不同的图像提取方法，确保各种格式的Word文档中的图像都能被正确提取
  - 为图像提取和OCR处理添加了全面的调试日志，记录每个步骤的处理结果
  - 增加了原始图像和处理后图像的保存功能，便于分析OCR失败的原因
  - 优化了图像过滤机制，自动识别并排除无效的小图像和非图像文件
  - 引入中文优化的二次识别机制，提高中文图像的文字识别率
  - 添加了详细的处理统计信息，包括成功识别率和处理时间
  - 改进了错误处理和异常报告，提高系统稳定性
- 增加了中文OCR专用图像优化模块 `_optimize_for_chinese.py`
  - 提供9种针对中文文本的图像处理方法，适用于不同场景
  - 支持图像倾斜校正，提高不规则拍摄图像的识别率
  - 针对中文笔画特点优化的形态学处理算法
  - 提供一体化的中文OCR预处理流程
  - 自动判断最佳处理方法，优化OCR结果

### 2024-01-17
- 新增OCR测试Web界面，便于快速测试图像文字识别效果
  - 开发了独立的OCR API服务，支持多种图像处理模式
  - 引入自动选择最佳OCR结果的机制，通过对比不同处理方法的结果选择最优方案
  - 可视化展示图像处理细节和实时预览效果
  - 简化OCR测试流程，支持拖放上传图像并一键处理
  - 提供快速启动脚本，自动检查环境和依赖
  - 优化调试文件存储和显示，方便问题分析

### 2024-01-16
- 大幅增强了OCR图像识别能力，提高了复杂图像的文字识别率
  - 引入了9种新的图像预处理方法，并自动进行组合尝试
  - 新增图像纠偏和倾斜校正，提高对歪斜文本的识别能力
  - 增加针对中文处理的专项优化
  - 增加超高DPI处理，提高小字体和复杂字符的识别率
  - 引入基于PSM模式的多方案OCR处理，自动选择最佳结果
  - 改进OCR结果评估机制，综合考虑文本长度和置信度
  - 增加图像处理调试功能，自动保存处理前后的图像用于分析
  - 优化OCR结果报表，提供各种处理方法的对比和详细统计

### 2024-01-15
- 增强了OCR功能
  - 改进了PDF处理器中的OCR文本识别功能
  - 增强了Tesseract OCR路径检测
  - 添加了OCR识别重试机制

### 2024-01-14
- 优化文档图片OCR识别功能，大幅提升Word文档内图片文本识别率
- 增强图片处理逻辑，添加文件类型验证，防止非图片文件误处理
- 增加OCR失败重试机制，提高文本识别成功率
- 添加更多调试信息，帮助排查图片处理问题
- 改进Markdown输出中图片显示方式，正确标识无法识别文本的图片

### 2024-01-13
- 添加openpyxl依赖库，修复Excel文件处理的依赖问题
- 更新requirements.txt文件，确保Excel文件可以正确读取
- 优化Excel文件处理逻辑，解决处理大型Excel文件时卡住的问题
- 增加直接处理Excel文件选项，不必转换为Word格式
- 限制处理的Excel行数，提高大型文件处理效率
- 改进临时文件处理机制，增加文件删除重试功能
- 优化Excel文件句柄管理，确保文件资源及时释放

### 2024-01-12
- 优化Markdown文档输出格式，使其更接近原文排版
- 改进复杂表格的Markdown转换，提高可读性
- 修复图片无法在Markdown中正确显示的问题
- 增强文档结构识别，自动识别标题层级

### 2024-01-11
- 修复缺少uuid库导入的问题
- 改进图片目录创建逻辑
- 优化文件路径处理机制

### 2024-01-10
- 新增支持 HTML 文件处理
- 新增支持 Excel 文件处理
- 优化文件格式处理逻辑
- 改进错误处理机制

### 2024-01-09
- 新增 Markdown 格式输出支持
- 优化文件处理逻辑
- 改进错误处理

### 2024年6月3日
- 优化表格数据处理逻辑：
  - 重构format_group_to_text函数，采用更通用的处理方式
  - 移除对特定字段名的依赖，提高代码灵活性
  - 自动清理和格式化字段名中的特殊字符
  - 统一的文本格式化逻辑，适应不同数据结构
  - 改进键值对处理方式，支持更多数据格式
  - 自动清理"表格无有效数据"等无效提示信息
  - 优化文本拼接逻辑，确保输出格式的一致性

## 安装说明

1. 克隆项目代码
2. 安装依赖：
   ```bash
   pip install -r requirements.txt
   ```
3. 配置环境变量（可选）：
   - OLLAMA_HOST：Ollama 服务器地址
   - TESSERACT_CMD：Tesseract OCR 可执行文件路径

## 使用说明

### 文件上传
- 支持的文件格式：
  - PDF (.pdf)
  - Word (.doc, .docx)
  - HTML (.html, .htm)
  - Excel (.xls, .xlsx)

### API 接口
- 文件上传：POST `/api/upload`
- 文件下载：GET `/api/download/{filename}`

### 输出格式
- Word 文档：`response_文件名_output.docx`
- 纯文本文件：`response_文件名_output.txt`
- Markdown 文件：`response_文件名_output.md`

### OCR图像识别测试
使用OCR测试功能可以快速测试图像文字识别效果，无需处理完整文档。

#### 快速启动方法
1. 运行项目根目录下的启动脚本：
   ```bash
   python start_ocr_test.py
   ```
   脚本会自动：
   - 检查必要依赖是否安装
   - 验证Tesseract OCR配置
   - 启动OCR API服务
   - 在浏览器中打开测试界面

2. 如果自动打开浏览器失败，请手动访问：
   ```
   http://localhost:8001/static/ocr_test.html
   ```

#### 使用方法
1. 在测试界面上传图片文件（支持拖放上传）
2. 选择识别语言（默认为中文+英文）
3. 选择处理模式：
   - **自动模式**：自动尝试最佳处理方法
   - **标准模式**：使用基本OCR处理，速度最快
   - **中文优化**：专为中文文本优化的处理方法
   - **高级模式**：使用多种图像处理方法，并比较结果

4. 点击"执行OCR"按钮开始处理
5. 查看处理结果：
   - **识别文本**：显示识别出的文本内容
   - **处理详情**：显示不同处理方法的结果对比
   - **处理图像**：显示处理前后的图像效果

#### 处理模式说明
- **自动模式**：适合大多数图像，自动选择最佳处理方法
- **标准模式**：适合清晰、对比度高的图像，处理速度最快
- **中文优化**：适合包含中文的图像，特别是小字体或模糊的中文文本
- **高级模式**：适合复杂图像，会尝试多种处理方法并选择最佳结果，处理时间较长

## 注意事项
1. Excel 文件处理时会将每个工作表转换为单独的章节
2. HTML 文件会保留基本的文本格式和表格结构
3. 所有临时文件会保存在 `temp` 目录下

## 开发说明

### 目录结构
```
doc-etl/
├── cxs/
│   ├── static/         # 前端文件
│   │   └── ocr_test.html  # OCR测试界面
│   ├── main.py         # 主程序
│   ├── cxs_doc_cleaner.py  # 文档处理核心
│   ├── cxs_table_processor.py  # 表格处理模块
│   ├── cxs_pdf_cleaner.py  # PDF处理模块
│   ├── _optimize_for_chinese.py  # 中文OCR优化模块
│   └── ocr_api.py      # OCR API服务
├── temp/
│   ├── uploads/        # 上传文件
│   ├── outputs/        # 输出文件
│   ├── images/         # 临时图片
│   └── debug/          # OCR处理调试图像
├── start_ocr_test.py   # OCR测试启动脚本
└── requirements.txt    # 依赖清单
```

### 开发环境
- Python 3.8+
- 依赖详见 requirements.txt

## 图像OCR问题排查

### 问题: 文档中图片OCR无法识别

如果您遇到文档处理时图片OCR识别失败的问题，很可能是因为Tesseract OCR工具的路径配置不正确。系统在初始化时会尝试自动查找Tesseract，但如果系统环境变量中没有正确配置，OCR功能可能无法正常工作。

### 解决方案

我们提供了一个修复脚本`fix_tesseract_path.py`，它可以:

1. 自动查找系统中已安装的Tesseract OCR
2. 正确设置Tesseract路径
3. 处理您的文档并启用图片OCR功能

使用方法:

```bash
# 直接处理指定文档
python fix_tesseract_path.py --file 您的文档.docx

# 指定Tesseract路径
python fix_tesseract_path.py --file 您的文档.docx --tesseract "C:\Program Files\Tesseract-OCR\tesseract.exe"

# 交互式模式
python fix_tesseract_path.py
```

### 注意事项

1. 确保已安装Tesseract OCR，如未安装，请从[官方GitHub](https://github.com/UB-Mannheim/tesseract/wiki)下载并安装
2. 安装时选择中文语言包，以支持中文OCR识别
3. 建议将Tesseract添加到系统PATH环境变量中，或在配置文件中明确指定路径

### 手动设置Tesseract路径

如果您希望永久解决这个问题，可以:

1. 将Tesseract安装目录(通常是`C:\Program Files\Tesseract-OCR`)添加到系统PATH环境变量
2. 设置环境变量`TESSERACT_CMD`为Tesseract可执行文件的完整路径

# 文档表格处理工具

本工具提供了强大的表格数据处理功能,可以处理文档中的各种类型表格。

## 主要功能

### 1. 表格数据处理
- 表格数据验证和清理
- 表格结构规范化
- 表格数据增强
- 表格布局优化

### 2. 数据转换和分析
- 表格转换为字典格式
- 表格内容分析
  - 基本统计信息
  - 列数据分析
  - 数据模式检测
  - 结构特征分析
  - 内容质量评估
- 重复值检测
- 值分布分析
- 列相关性分析
- 数据一致性检查
- 潜在问题检测

### 3. 格式转换
- 转换为CSV格式
- 转换为Excel格式
- 转换为Markdown格式
- 转换为HTML格式

### 4. 高级功能
- 多级表头处理
- 合并单元格处理
- 键值对表格处理
- 数据类型自动识别
- 表格结构优化

## 使用示例

```python
from cxs.cxs_table_processor import TableProcessor

# 创建处理器实例
processor = TableProcessor()

# 处理表格数据
table_data = {
    'rows': [...],
    'header_rows': 1
}

# 数据转换
dict_data = processor._convert_table_to_dict(table_data)

# 内容分析
analysis = processor._analyze_table_content(table_data)

# 检测数据模式
patterns = processor._detect_table_patterns(table_data)

# 导出为不同格式
csv_data = processor._convert_table_to_csv(table_data)
excel_data = processor._convert_table_to_excel(table_data)
```

## 数据转换能力

支持以下数据转换:

1. 表格 -> 字典
   - 支持键值对表格
   - 支持普通表格结构
   - 支持多级表头

2. 表格 -> CSV
   - 自动处理表头
   - 处理合并单元格
   - 支持自定义分隔符

3. 表格 -> Excel
   - 保留表格结构
   - 处理合并单元格
   - 自动调整列宽
   - 设置表头样式

4. 表格 -> Markdown/HTML
   - 格式化输出
   - 保持表格结构
   - 支持样式设置

## 开发要求

- Python 3.7+
- 依赖包:
  - openpyxl
  - pandas
  - numpy

## 安装说明

```bash
pip install -r requirements.txt
```

## 更新日志

### v1.0.0
- 初始版本发布
- 基本的表格处理功能

### v1.1.0
- 添加数据验证和清理功能
- 增加表格结构规范化

### v1.2.0
- 添加数据转换功能
- 支持多种输出格式

### v1.3.0
- 添加内容分析功能
- 增加数据模式检测
- 优化表格处理性能

### 2024-03-xx
- 优化了表格处理器的稳定性和错误处理
  - 增加了严格的索引检查和边界处理
  - 改进了单元格和行级别的错误处理机制
  - 增强了对大型表格和复杂表头的支持
  - 优化了表格规范化处理
  - 提高了处理不规则表格的兼容性
  - 改进了内存使用效率

## 注意事项

1. 大文件处理
   - 建议分批处理大型表格
   - 注意内存使用

2. 数据验证
   - 建议在处理前进行数据验证
   - 检查表格结构完整性

3. 错误处理
   - 所有方法都包含错误处理
   - 详细的错误信息输出

## 贡献指南

1. Fork 项目
2. 创建特性分支
3. 提交变更
4. 发起 Pull Request

## 许可证

MIT License

## 更新日志

### 2024-03-21
- 修复了文本分段工具的命令行参数问题
- 现在支持使用相对路径处理文件
- 新增txt格式输出支持，默认输出格式改为txt
- 优化了段落分隔显示，使用空行分隔各段落
- 全新的智能语义分段功能：
  - 支持基于章节标题的主要分段
  - 支持基于语义转折词的次要分段
  - 智能识别特殊段落（如摘要、引言等）
  - 自动合并过短段落，保持语义完整性
  - 优化的中文标点符号处理
- 添加token长度控制：
  - 确保每个段落不超过512个token
  - 智能估算中英文混合文本的token数量
  - 对超长句子进行智能拆分
  - 在保持语义完整性的同时控制token数量
- 优化表格内容处理：
  - 自动移除表格标记（如"表格1开始"、"表格1结束"）
  - 智能分割长表格内容，确保每段不超过token限制
  - 保持表格行的语义完整性
  - 使用逗号和分号作为表格内容的分割点
  - 优化表格段落的可读性

## 使用方法

### 文本分段工具

基本用法（输出txt格式）：
```bash
python text_paragraph_splitter.py sample_continuous_text.txt
```

指定输出文件：
```bash
python text_paragraph_splitter.py sample_continuous_text.txt -o output.txt
```

输出JSON格式：
```bash
python text_paragraph_splitter.py sample_continuous_text.txt -f json -o output.json
```

参数说明：
- input_file：输入文件路径，例如：sample_continuous_text.txt
- --output/-o：输出文件路径，默认为当前目录下的 paragraphs.txt
- --format/-f：输出格式，支持txt和json，默认为txt

分段规则说明：
1. Token长度控制：
   - 每个段落严格控制在512个token以内
   - 中文字符按1.5个token计算
   - 英文单词按1个token计算
   - 标点符号按1个token计算
   - 超长句子会按逗号智能拆分

2. 表格处理：
   - 自动识别并移除表格标记
   - 按行处理表格内容
   - 智能合并短行，不超过token限制
   - 对超长行进行分割处理
   - 保持表格内容的语义连贯性

3. 主要分段标记：
   - 章节标题（如"第一章"、"第1节"等）
   - 序号标记（如"一、"、"1."、"（1）"等）
   - 罗马数字标记（如"I."、"II."等）

4. 次要分段标记：
   - 语义转折词（如"然而"、"但是"、"因此"等）
   - 总结性词语（如"总的来说"、"综上所述"等）
   - 举例词语（如"例如"、"比如"等）

5. 特殊段落：
   - 自动识别摘要、引言、结论等特殊段落
   - 保持这些段落的独立性

6. 智能合并：
   - 合并过短的段落（小于50字）
   - 确保合并后不超过token限制
   - 保持标题等特殊标记的独立性
   - 确保段落语义的完整性

### 2024-03-xx
- 重写了表格处理逻辑，增强了对复杂表格的处理能力
  - 使用@dataclass重新设计了表格数据结构（Cell、Row、Table类）
  - 支持多级表头和合并单元格的识别
  - 自动识别表格类型（标准表格、键值对、矩阵等）
  - 支持特殊格式（货币、百分比、日期等）的识别和转换
  - 增加了表格处理的错误处理和容错机制
  - 优化了表格输出格式，支持Markdown、HTML和字典格式
  - 添加了表格处理的调试信息输出
  - 更新了导入路径，使用新的table_processor模块

### 2024年3月
- 优化表格处理逻辑：
  - 修复复杂表头和矩阵类型表格的索引越界问题
  - 增强表格行和单元格的错误处理机制
  - 改进表头结构分析，支持多级表头识别
  - 优化矩阵类型表格的检测算法
  - 增加数字单元格识别功能
  - 完善表格转文本的格式化处理
  - 增加边界检查和异常处理机制
  - 优化内存使用和处理效率