# parse-service 待完善清单

## 📋 总体状态

**完成度：约 100%**（P0、P1和P2任务全部完成）

### ✅ 已完成功能

1. **文件上传接口** ✅
   - 支持 PDF、Word、Excel、图片上传
   - 文件类型识别（MIME类型、扩展名、文件头）
   - 文件验证和存储

2. **PDF文本提取** ✅
   - 分页判断逻辑实现
   - 有文本层直接提取
   - 无文本层使用OCR（页面转图片）
   - 自动清理临时文件

3. **OCR集成** ✅
   - PaddleOCR客户端实现
   - HTTP API调用
   - 错误处理

4. **TXT文件存储** ✅
   - 文本内容写入SSD硬盘
   - 路径管理

5. **解析任务管理** ✅
   - 异步任务队列
   - 状态跟踪
   - 进度查询

---

## ❌ 待完善功能

### P0 - 高优先级（阻塞后续开发）

#### 1. Word文档文本提取 ✅ **已完成**
- **当前状态**：已实现Word文档直接文本提取
- **实现内容**：
  - ✅ 添加Apache POI依赖
  - ✅ 创建WordTextExtractionService
  - ✅ 支持.docx和.doc格式
  - ✅ 提取纯文本内容
- **文件位置**：`WordTextExtractionService.java`，已集成到`ParseService.java`
- **优先级**：P0 ✅

#### 2. OCR结果解析 ✅ **已完成**
- **当前状态**：已实现通用的JSON解析器
- **实现内容**：
  - ✅ 创建OcrResultParser使用Jackson解析JSON
  - ✅ 支持多种JSON格式（text字段、result数组、data对象等）
  - ✅ 处理数组和嵌套对象
  - ✅ 已集成到ParseService和PdfTextExtractionService
- **文件位置**：`OcrResultParser.java`
- **优先级**：P0 ✅

#### 3. 文本存储路径记录 ✅ **已完成**
- **当前状态**：已实现文本存储路径记录功能
- **实现内容**：
  - ✅ 创建GraphServiceClient（Feign Client）
  - ✅ 在graph-service中实现TextStorageController和TextStorageService
  - ✅ 记录text_storage表信息（document_id, file_path, file_size, checksum）
  - ✅ 在ParseService中调用，自动计算MD5校验和
- **文件位置**：
  - `GraphServiceClient.java`（Feign Client）
  - `graph-service/TextStorageController.java`
  - `graph-service/TextStorageService.java`
  - 已集成到`ParseService.java`
- **优先级**：P0 ✅

---

### P1 - 中优先级（重要功能）

#### 4. Excel表格提取 ✅ **已完成**
- **当前状态**：已实现Excel表格直接文本提取
- **实现内容**：
  - ✅ 使用Apache POI（已添加依赖）
  - ✅ 创建ExcelTextExtractionService
  - ✅ 支持.xlsx和.xls格式
  - ✅ 提取表格数据为文本格式（保留表格结构）
  - ✅ 支持多工作表、公式、日期等数据类型
- **文件位置**：`ExcelTextExtractionService.java`，已集成到`ParseService.java`
- **优先级**：P1 ✅

#### 5. 版面分析 ✅ **已完成**
- **当前状态**：已实现基础版面分析功能
- **实现内容**：
  - ✅ 创建LayoutAnalysisService
  - ✅ 识别文档结构（标题、段落、列表、表格行等）
  - ✅ 提取位置信息（行索引、段落索引、位置坐标等）
  - ✅ 支持PDF、Word、Excel等不同文件类型
  - ✅ 分析结果保存到解析任务选项，供后续图节点构建使用
- **文件位置**：`LayoutAnalysisService.java`，已集成到`ParseService.java`
- **优先级**：P1 ✅
- **注意**：当前为基础实现，后续可以使用更精确的版面分析库（如PDFBox的PDFLayoutTextStripper）进行增强

---

### P2 - 低优先级（优化功能）

#### 6. 异步任务处理优化 ✅ **已完成**
- **当前状态**：已实现RabbitMQ消息队列支持，同时保留线程池模式
- **实现内容**：
  - ✅ 创建RabbitMQConfig配置类
  - ✅ 创建ParseTaskMessage消息DTO
  - ✅ 创建ParseTaskMessageConsumer消息消费者
  - ✅ 更新ParseTaskExecutor支持MQ和线程池两种模式
  - ✅ 支持任务优先级
  - ✅ 支持任务重试机制（通过消息队列）
  - ✅ 支持降级处理（MQ失败时自动降级为线程池）
- **文件位置**：
  - `RabbitMQConfig.java` - RabbitMQ配置
  - `ParseTaskMessage.java` - 消息DTO
  - `ParseTaskMessageConsumer.java` - 消息消费者
  - `ParseTaskExecutor.java` - 已更新支持MQ模式
- **配置**：通过`parse.task.use-mq`配置项控制是否使用MQ（默认false）
- **优先级**：P2 ✅

#### 7. 错误处理和重试机制 ✅ **已完成**
- **当前状态**：已实现完整的错误处理和重试机制
- **实现内容**：
  - ✅ 创建RetryUtil重试工具类（支持指数退避）
  - ✅ 创建ErrorCategory错误分类枚举
  - ✅ OCR调用失败自动重试（最多3次，指数退避）
  - ✅ 文件处理异常重试
  - ✅ 详细的错误日志（包含错误分类、是否可重试等信息）
  - ✅ 错误分类和处理策略（网络错误、超时错误、文件错误等）
  - ✅ 错误信息保存到任务选项
- **文件位置**：
  - `RetryUtil.java` - 重试工具类
  - `ErrorCategory.java` - 错误分类枚举
  - `PaddleOcrClient.java` - 已集成重试机制
  - `ParseService.java` - 已集成错误分类和详细日志
- **优先级**：P2 ✅

#### 8. 性能优化 ✅ **已完成**
- **当前状态**：已实现大文件分块处理，内存优化
- **实现内容**：
  - ✅ 创建FileChunkProcessor大文件分块处理工具
  - ✅ 大文件分块写入（超过50MB自动分块）
  - ✅ 内存优化（避免大文件一次性加载到内存）
  - ✅ 单线程处理（符合GPU线性处理约束）
  - ✅ 文件大小检测和优化策略
- **文件位置**：
  - `FileChunkProcessor.java` - 大文件分块处理工具
  - `ParseService.java` - 已集成分块写入
- **配置**：通过`performance.large-file-threshold`和`performance.chunk-size`配置
- **优先级**：P2 ✅

---

## 📝 代码中的TODO标记

### ParseService.java
1. ✅ ~~第128行~~：调用 graph-service 或 document-service 记录 text_storage 信息 - **已完成**
2. ✅ ~~第218行~~：根据实际返回结构提取文字内容（OCR结果解析） - **已完成**
3. ✅ ~~第222行~~：实现版面分析 - **已完成**
4. ✅ ~~第223行~~：实现异步任务处理（MQ / 线程池等） - **已完成**

### PdfTextExtractionService.java
1. ✅ ~~第185行~~：根据实际OCR服务返回的JSON结构解析 - **已完成**

---

## 🔧 需要添加的依赖

### 已添加
- ✅ Apache PDFBox 3.0.1
- ✅ Apache POI 5.2.5（Word/Excel处理）
  - ✅ poi（核心库）
  - ✅ poi-ooxml（.docx, .xlsx）
  - ✅ poi-scratchpad（.doc, .xls）

---

## 📊 功能覆盖情况

| 文件类型 | 处理方式 | 状态 |
|---------|---------|------|
| PDF | 分页判断（文本层/OCR） | ✅ 已完成 |
| Word (.docx) | 直接文本提取 | ✅ 已完成 |
| Word (.doc) | 直接文本提取 | ✅ 已完成 |
| Excel (.xlsx) | 直接表格提取 | ✅ 已完成 |
| Excel (.xls) | 直接表格提取 | ✅ 已完成 |
| 图片 (JPG/PNG/GIF) | OCR | ✅ 已完成 |

---

## 🎯 下一步行动计划

### ✅ 已完成（P0）
1. ✅ **Word文档文本提取**
   - ✅ 添加Apache POI依赖
   - ✅ 实现WordTextExtractionService
   - ✅ 集成到ParseService

2. ✅ **OCR结果解析完善**
   - ✅ 创建OcrResultParser使用Jackson解析JSON
   - ✅ 支持多种JSON格式
   - ✅ 提取文本内容
   - ✅ 集成到ParseService和PdfTextExtractionService

3. ✅ **文本存储路径记录**
   - ✅ 创建GraphServiceClient（Feign Client）
   - ✅ 在graph-service中实现TextStorageController和TextStorageService
   - ✅ 在ParseService中调用，自动计算MD5校验和

### ✅ 已完成（P1）
4. ✅ **Excel表格提取**
   - ✅ 创建ExcelTextExtractionService
   - ✅ 支持.xlsx和.xls格式
   - ✅ 提取表格数据为文本格式
   - ✅ 集成到ParseService

5. ✅ **版面分析**
   - ✅ 创建LayoutAnalysisService
   - ✅ 识别文档结构（标题、段落、表格等）
   - ✅ 提取位置信息
   - ✅ 集成到ParseService，结果保存到任务选项

### ✅ 已完成（P2）
6. ✅ **异步任务优化（MQ）**
   - ✅ 创建RabbitMQ配置和消息队列
   - ✅ 支持MQ和线程池两种模式
   - ✅ 支持任务优先级和重试
   - ✅ 支持降级处理

7. ✅ **错误处理和重试机制**
   - ✅ 创建RetryUtil和ErrorCategory
   - ✅ OCR调用自动重试
   - ✅ 详细错误日志和分类
   - ✅ 错误信息保存到任务

8. ✅ **性能优化**
   - ✅ 大文件分块处理
   - ✅ 内存优化
   - ✅ 文件大小检测

---

## 📌 注意事项

1. ✅ **OCR服务返回格式**：已实现通用的JSON解析器，支持多种常见格式
2. ✅ **Feign Client**：已创建GraphServiceClient，graph-service已提供接口
3. **性能考虑**：PDF处理可能消耗大量内存，大文件需要优化
4. **GPU资源限制**：当前单线程处理符合GPU线性处理约束，优化时需注意
5. **MD5校验和**：文本存储记录时会自动计算文件MD5，用于文件完整性校验

---

**最后更新**：2026-01-14

---

## ✅ 本次更新（2026-01-14 - P1任务完成）

### 已完成的功能

1. **Word文档文本提取** ✅
   - 创建了`WordTextExtractionService`
   - 支持.docx和.doc格式
   - 已集成到ParseService

2. **OCR结果解析** ✅
   - 创建了`OcrResultParser`使用Jackson解析JSON
   - 支持多种JSON格式（text字段、result数组、data对象等）
   - 已集成到ParseService和PdfTextExtractionService

3. **文本存储路径记录** ✅
   - 创建了`GraphServiceClient`（Feign Client）
   - 在graph-service中实现了`TextStorageController`和`TextStorageService`
   - 自动计算MD5校验和
   - 已集成到ParseService

### 新增文件

- `parse-service/src/main/java/com/lingyue/parse/service/WordTextExtractionService.java`
- `parse-service/src/main/java/com/lingyue/parse/service/OcrResultParser.java`
- `parse-service/src/main/java/com/lingyue/parse/client/GraphServiceClient.java`
- `graph-service/src/main/java/com/lingyue/graph/service/TextStorageService.java`
- `graph-service/src/main/java/com/lingyue/graph/controller/TextStorageController.java`
- `parse-service/src/main/java/com/lingyue/parse/service/ExcelTextExtractionService.java`（P1）
- `parse-service/src/main/java/com/lingyue/parse/service/LayoutAnalysisService.java`（P1）
- `parse-service/src/main/java/com/lingyue/parse/util/RetryUtil.java`（P2）
- `parse-service/src/main/java/com/lingyue/parse/util/ErrorCategory.java`（P2）
- `parse-service/src/main/java/com/lingyue/parse/util/FileChunkProcessor.java`（P2）
- `parse-service/src/main/java/com/lingyue/parse/config/RabbitMQConfig.java`（P2）
- `parse-service/src/main/java/com/lingyue/parse/dto/ParseTaskMessage.java`（P2）
- `parse-service/src/main/java/com/lingyue/parse/service/ParseTaskMessageConsumer.java`（P2）

### 更新的文件

- `backend/pom.xml` - 添加POI依赖版本管理
- `parse-service/pom.xml` - 添加POI依赖
- `parse-service/src/main/java/com/lingyue/parse/service/ParseService.java` - 集成所有新功能（Word提取、Excel提取、版面分析、文本存储记录、错误处理）
- `parse-service/src/main/java/com/lingyue/parse/service/PdfTextExtractionService.java` - 使用OcrResultParser
- `parse-service/src/main/java/com/lingyue/parse/service/PaddleOcrClient.java` - 集成重试机制
- `parse-service/src/main/java/com/lingyue/parse/service/ParseTaskExecutor.java` - 支持MQ和线程池两种模式
- `parse-service/src/main/resources/application.yml` - 添加MQ和性能配置