# 数据提取规则系统 - 代码实现阶段规划

> 版本: 1.0.0
> 日期: 2026-01-22
> 作者: AI Assistant (Claude Opus 4.5)
> 关联文档: [数据提取规则系统设计.md](./数据提取规则系统设计.md)

## 一、概述

本文档规划「数据提取规则系统」的代码实现阶段，共分为 11 个阶段，按依赖关系和优先级排序。

### 1.1 阶段总览

| 阶段 | 名称 | 主要产出 | 预估工作量 |
| ---- | ---- | -------- | ---------- |
| 1 | 基础设施搭建 | extract-service 模块框架、数据库表 | 小 |
| 2 | 核心实体与 Repository | 实体类、数据访问层 | 小 |
| 3 | 项目与文档管理 | Project/SourceDocument 的 CRUD API | 中 |
| 4 | 提取规则配置 | ExtractRule 的配置与管理 API | 中 |
| 5 | 内容定位服务 | 按页码/章节/元素定位文档内容 | 中 |
| 6 | AI 提取服务 | AI 字段提取、内容总结能力 | 中 |
| 7 | 提取执行引擎 | 规则执行核心流程 | 大 |
| 8 | 批量执行与异步任务 | 批量执行、进度跟踪 | 中 |
| 9 | 结果管理与人工干预 | 结果确认、修正 API | 小 |
| 10 | 规则模板功能 | 模板保存与应用 | 小 |
| 11 | 集成与扩展 | 系统集成、文档完善 | 中 |

### 1.2 阶段依赖关系图

```
第一阶段（基础设施）
    │
    ▼
第二阶段（实体与Repository）
    │
    ├────────────────────────────────────────┐
    │                                        │
    ▼                                        ▼
第三阶段（项目与文档管理）              第五阶段（内容定位服务）
    │                                        │
    ▼                                        │
第四阶段（提取规则配置）                     │
    │                                        │
    ├──────► 第十阶段（规则模板）             │
    │                                        │
    │        第六阶段（AI提取服务）◄──────────┤
    │              │                         │
    │              ▼                         │
    └───────► 第七阶段（提取执行引擎）◄───────┘
                   │
        ┌──────────┴──────────┐
        ▼                     ▼
  第八阶段（批量执行）    第九阶段（结果管理）
        │                     │
        └──────────┬──────────┘
                   ▼
            第十一阶段（集成与扩展）
```

---

## 二、各阶段详细说明

### 第一阶段：基础设施搭建

#### 2.1.1 目标

创建新模块 `extract-service` 的基础框架，确保服务可以启动并注册到服务中心。

#### 2.1.2 工作内容

1. **创建 Maven 模块**
   - 在 `backend/` 下创建 `extract-service` 目录
   - 配置 `pom.xml`，依赖 common、mybatis-plus、nacos、openfeign 等
   - 在父 pom.xml 中添加子模块声明

2. **创建启动类**
   - `ExtractServiceApplication.java`
   - 配置 `@EnableFeignClients`、`@MapperScan` 等注解

3. **配置文件**
   - `application.properties` 或 `application.yml`
   - 配置服务端口（建议 8086）、数据库连接、Nacos 注册中心

4. **网关路由**
   - 在 `gateway-service` 的路由配置中添加 extract-service 的路由规则
   - 路径前缀：`/api/v1/extract/**`

5. **数据库表创建**
   - 执行 SQL 脚本创建 5 张核心表
   - 表名：projects、source_documents、extract_rules、extract_results、rule_templates

#### 2.1.3 验收标准

- [ ] 服务可以正常启动
- [ ] 服务注册到 Nacos 成功
- [ ] 通过网关可以访问到服务的健康检查接口
- [ ] 数据库表创建成功

#### 2.1.4 依赖关系

无外部依赖，可独立完成。

---

### 第二阶段：核心实体与 Repository 层

#### 2.2.1 目标

完成数据访问层，为上层业务逻辑提供数据操作能力。

#### 2.2.2 工作内容

1. **创建实体类**（5 个）
   - `Project.java` - 项目实体
   - `SourceDocument.java` - 来源文档实体
   - `ExtractRule.java` - 提取规则实体
   - `ExtractResult.java` - 提取结果实体
   - `RuleTemplate.java` - 规则模板实体

2. **创建 Repository 接口**（5 个）
   - 继承 `BaseMapper<T>`
   - 添加自定义查询方法（使用 `@Select` 注解或 XML）

3. **常用查询方法**

   | Repository | 方法 |
   | ---------- | ---- |
   | ProjectRepository | findByUserId, findByStatus |
   | SourceDocumentRepository | findByProjectId, findByDocumentId |
   | ExtractRuleRepository | findByProjectId, findByStatus, findByTargetFieldKey |
   | ExtractResultRepository | findByRuleId, findByProjectId, findByStatus |
   | RuleTemplateRepository | findByUserId, findPublicTemplates |

4. **创建配置 DTO 类**（约 15 个）

   来源配置类：
   - `SourceConfig.java` - 基类/接口
   - `DocumentSourceConfig.java` - 文档来源配置
   - `SelfReferenceSourceConfig.java` - 自引用来源配置
   - `FixedSourceConfig.java` - 固定内容配置
   - `ManualSourceConfig.java` - 手动输入配置
   - `LocationConfig.java` - 定位配置
   - `TransformConfig.java` - 转换配置

   提取配置类：
   - `ExtractConfigBase.java` - 基类/接口
   - `DirectExtractConfig.java` - 直接提取配置
   - `AIExtractConfig.java` - AI 提取配置
   - `AISummarizeConfig.java` - AI 总结配置
   - `OcrExtractConfig.java` - OCR 配置

5. **JSONB 序列化测试**
   - 验证配置类可以正确序列化/反序列化到数据库 JSONB 字段

#### 2.2.3 验收标准

- [ ] 所有实体类创建完成，字段与数据库表对应
- [ ] Repository 可以正常执行 CRUD 操作
- [ ] JSONB 字段读写测试通过
- [ ] 配置 DTO 类结构正确

#### 2.2.4 依赖关系

依赖第一阶段完成。

---

### 第三阶段：项目与文档管理功能

#### 2.3.1 目标

实现项目和来源文档的完整 CRUD 功能，支持用户创建项目并关联文档。

#### 2.3.2 工作内容

1. **ProjectService**
   - `create(userId, request)` - 创建项目
   - `getById(id)` - 获取项目详情
   - `listByUserId(userId, pageRequest)` - 分页查询用户的项目
   - `update(id, request)` - 更新项目
   - `delete(id)` - 删除项目（级联删除关联数据）
   - `archive(id)` - 归档项目
   - `getProjectWithDocuments(id)` - 获取项目详情（含来源文档列表）

2. **SourceDocumentService**
   - `add(projectId, request)` - 添加来源文档
   - `listByProjectId(projectId)` - 获取项目的来源文档列表
   - `update(id, request)` - 更新来源文档信息
   - `remove(id)` - 移除来源文档
   - `batchAdd(projectId, requests)` - 批量添加来源文档
   - `reorder(projectId, orders)` - 调整文档顺序

3. **Controller 层**
   - `ProjectController` - 项目管理 API
   - `SourceDocumentController` - 来源文档管理 API

4. **请求/响应 DTO**
   - `CreateProjectRequest` / `UpdateProjectRequest`
   - `AddSourceDocumentRequest` / `BatchAddSourceDocumentsRequest`
   - `ProjectDetailResponse` / `ProjectListResponse`
   - `SourceDocumentResponse`

5. **Feign Client 集成**
   - 创建 `DocumentServiceClient` 接口
   - 调用 document-service 获取文档基本信息
   - 调用 document-service 检查文档解析状态

6. **事件监听**
   - 监听 `DocumentParsedEvent` 事件
   - 更新 SourceDocument 的 metadata 中的 parseStatus

#### 2.3.3 验收标准

- [ ] 可通过 API 创建项目
- [ ] 可通过 API 添加来源文档到项目
- [ ] 来源文档关联的 Document 信息可正确获取
- [ ] 文档解析完成后状态自动更新
- [ ] 项目删除时级联删除关联的来源文档和规则

#### 2.3.4 依赖关系

- 依赖第二阶段完成
- 依赖 `document-service` 提供 Feign 接口

---

### 第四阶段：提取规则配置功能

#### 2.4.1 目标

实现规则的配置与管理，支持多种来源类型和提取类型的配置。

#### 2.4.2 工作内容

1. **ExtractRuleService**
   - `create(projectId, request)` - 创建规则
   - `getById(id)` - 获取规则详情
   - `listByProjectId(projectId)` - 获取项目的规则列表（按 ruleIndex 排序）
   - `update(id, request)` - 更新规则
   - `delete(id)` - 删除规则
   - `batchCreate(projectId, requests)` - 批量创建规则
   - `duplicate(id)` - 复制规则
   - `reorder(projectId, orders)` - 调整规则顺序
   - `validateConfig(rule)` - 校验规则配置

2. **配置校验逻辑**

   | 校验项 | 说明 |
   | ------ | ---- |
   | sourceType 与 sourceConfig 匹配 | document 类型必须有 sourceDocId 和 location |
   | extractType 与 extractConfig 匹配 | ai_extract 类型必须有 targetDescription |
   | self_reference 循环引用检测 | A 引用 B，B 引用 A 的情况 |
   | 必填字段校验 | targetFieldKey、targetFieldName 不能为空 |
   | targetFieldKey 唯一性 | 同一项目内 targetFieldKey 不能重复 |

3. **依赖分析**
   - `analyzeDependencies(projectId)` - 分析规则间的依赖关系
   - 返回依赖图（哪些规则依赖哪些字段）
   - 检测循环依赖

4. **Controller 层**
   - `ExtractRuleController`

5. **请求/响应 DTO**
   - `CreateRuleRequest` / `UpdateRuleRequest`
   - `BatchCreateRulesRequest`
   - `ReorderRulesRequest`
   - `RuleDetailResponse` / `RuleListResponse`
   - `DependencyAnalysisResponse`

#### 2.4.3 验收标准

- [ ] 可通过 API 创建各种类型的规则
- [ ] 规则配置校验正确拦截无效配置
- [ ] 循环依赖可被检测
- [ ] 批量创建和排序功能正常

#### 2.4.4 依赖关系

依赖第三阶段完成。

---

### 第五阶段：内容定位服务

#### 2.5.1 目标

实现从文档中定位和提取内容的能力，支持多种定位方式。

#### 2.5.2 工作内容

1. **ContentLocatorService 接口**

   ```
   locateElements(documentId, location) -> List<DocumentElement>
   locateContent(documentId, location) -> String
   locateByPage(documentId, pageStart, pageEnd, keyword) -> List<DocumentElement>
   locateByChapter(documentId, chapterPath, chapterTitle) -> List<DocumentElement>
   locateByElementIds(documentId, elementIds) -> List<DocumentElement>
   locateExcelCell(documentId, sheetName, cellRef) -> String
   ```

2. **按页码定位实现**
   - 调用 DocumentElementService 获取文档所有元素
   - 根据元素的页码信息（需扩展 DocumentElement 添加 pageNumber 字段，或从 metadata 获取）
   - 筛选指定页码范围内的元素
   - 支持段落关键词过滤（paragraphKeyword）

3. **按章节定位实现**
   - 解析章节路径（如 `["3", "5", "3", "3"]` 表示 3.5.3.3）
   - 匹配 heading 类型元素的章节号（使用正则提取）
   - 定位到章节标题后，提取该章节下的所有内容（直到下一个同级或更高级标题）

4. **按元素ID定位实现**
   - 直接根据 elementIds 列表查询 DocumentElement
   - 适用于用户在界面上手动选择元素的场景

5. **Excel 定位实现**
   - 调用 parse-service 的 ExcelTextExtractionService
   - 支持 Sheet 名 + 单元格范围定位（如 `变电站扩建页 / A1:C10`）
   - 支持自定义格式（如 `1.5.1` 表示某种内部编号）

6. **内容拼接**
   - 将定位到的多个元素内容拼接为完整文本
   - 保留基本格式（段落分隔、表格文本等）

7. **Feign Client**
   - 创建 `DocumentElementServiceClient`
   - 创建 `ParseServiceClient`（用于 Excel 解析）

#### 2.5.3 验收标准

- [ ] 按页码定位可正确提取内容
- [ ] 按章节定位可正确识别章节范围
- [ ] Excel 单元格定位可正确提取数据
- [ ] 多元素内容拼接正确

#### 2.5.4 依赖关系

- 依赖第二阶段完成
- 依赖 `document-service` 的 DocumentElementService
- 依赖 `parse-service` 的 Excel 解析能力

---

### 第六阶段：AI 提取服务

#### 2.6.1 目标

封装 AI 提取和总结功能，提供结构化的 AI 调用接口。

#### 2.6.2 工作内容

1. **AIExtractService 接口**

   ```
   extract(content, config) -> AIExtractResult
   summarize(content, config, context) -> AISummarizeResult
   ```

2. **AI 字段提取实现**
   - 根据 `AIExtractConfig` 构建 Prompt
   - Prompt 模板包含：提取目标、字段类型、预期格式、示例
   - 调用 `DeepSeekClient.complete()` 执行
   - 解析返回结果，提取值
   - 评估置信度（可选，基于返回内容的匹配度）

3. **AI 内容总结实现**
   - 根据 `AISummarizeConfig` 构建 Prompt
   - Prompt 模板包含：总结要求、关注维度、规则、风格、字数限制
   - 支持传入上下文字段值（contextFieldKeys 引用的已提取值）
   - 调用 `DeepSeekClient.complete()` 执行

4. **Prompt 模板管理**

   字段提取 Prompt 模板：
   ```
   你是一个专业的文档信息提取助手。请从以下文档内容中提取指定的信息。
   
   ## 提取目标
   {targetDescription}
   
   ## 字段类型
   {fieldType}
   
   ## 预期格式
   {expectedFormat}
   
   ## 示例
   {examples}
   
   ## 文档内容
   {content}
   
   ## 输出要求
   请直接输出提取的值，不要包含任何解释。
   ```

   内容总结 Prompt 模板：
   ```
   你是一个专业的工程报告撰写助手。请对以下内容进行总结/提炼。
   
   ## 总结要求
   {summarizePrompt}
   
   ## 关注维度
   {focusPoints}
   
   ## 总结规则
   {rules}
   
   ## 输出风格
   {style}
   
   ## 字数限制
   {maxLength} 字以内
   
   ## 原文内容
   {content}
   ```

5. **错误处理与重试**
   - AI 调用超时重试（最多 3 次）
   - 返回结果为空时的处理
   - Token 超限时的内容截断策略

6. **结果数据结构**
   - `AIExtractResult`: value, confidence, reasoning
   - `AISummarizeResult`: summary, keyPoints

#### 2.6.3 验收标准

- [ ] AI 字段提取可正确提取工程名称、日期等字段
- [ ] AI 内容总结可生成符合要求的总结
- [ ] Prompt 模板参数替换正确
- [ ] 错误处理和重试机制正常

#### 2.6.4 依赖关系

- 依赖 `ai-service` 的 DeepSeekClient
- 可与第五阶段并行开发

---

### 第七阶段：提取执行引擎

#### 2.7.1 目标

实现规则执行的核心流程，是整个系统的核心模块。

#### 2.7.2 工作内容

1. **Executor 策略模式**

   ```
   interface ExtractExecutor {
       boolean supports(String extractType);
       ExtractResult execute(ExtractRule rule, String sourceContent);
   }
   ```

   实现类：
   - `DirectExtractExecutor` - 直接提取
   - `AIExtractExecutor` - AI 字段提取
   - `AISummarizeExecutor` - AI 总结提炼
   - `OcrExtractExecutor` - OCR 识别（可选，后续实现）

2. **DirectExtractExecutor 实现**
   - 根据 `DirectExtractConfig` 处理内容
   - trimWhitespace - 去除首尾空白
   - removeLineBreaks - 移除换行符
   - mergeSpaces - 合并连续空格
   - 直接返回处理后的文本

3. **AIExtractExecutor 实现**
   - 调用 AIExtractService.extract()
   - 将 AIExtractResult 转换为 ExtractResult

4. **AISummarizeExecutor 实现**
   - 获取上下文字段值（contextFieldKeys）
   - 调用 AIExtractService.summarize()
   - 将 AISummarizeResult 转换为 ExtractResult

5. **ExtractExecuteService 核心流程**

   ```
   executeRule(ruleId):
       1. 获取规则配置 ExtractRule
       2. 根据 sourceType 获取来源内容
          - document: 调用 ContentLocatorService
          - self_reference: 查询已提取的字段值
          - fixed: 返回 fixedContent
          - manual: 返回 defaultValue 或标记为待填写
       3. 选择对应的 Executor 执行提取
       4. 创建 ExtractResult 记录
          - 保存提取值
          - 保存来源追溯信息（sourceContent, sourceLocation）
       5. 更新 ExtractRule 的 status 和 extracted_value
       6. 返回结果
   ```

6. **self_reference 处理**
   - 查询引用字段的已提取值
   - 如果引用字段未提取，返回错误或标记依赖
   - 支持多字段组合（combineTemplate）
   - 支持值转换（transform）

7. **来源追溯信息**

   ```json
   {
     "documentId": "doc_001",
     "documentAlias": "可研批复",
     "locationType": "page",
     "pageStart": 1,
     "pageEnd": 2,
     "elementIds": ["elem_001", "elem_002"],
     "textPreview": "本项目建设必要性主要体现在..."
   }
   ```

8. **状态管理**
   - pending → extracting → extracted/error
   - 更新 ExtractRule.status
   - 更新 ExtractRule.extracted_value
   - 错误时保存 error_message

#### 2.7.3 验收标准

- [ ] DirectExtractExecutor 可正确直接提取内容
- [ ] AIExtractExecutor 可正确调用 AI 提取
- [ ] AISummarizeExecutor 可正确调用 AI 总结
- [ ] self_reference 类型可正确引用已提取值
- [ ] 来源追溯信息完整保存
- [ ] 状态更新正确

#### 2.7.4 依赖关系

- 依赖第五阶段（ContentLocatorService）
- 依赖第六阶段（AIExtractService）
- 这是系统的核心阶段

---

### 第八阶段：批量执行与异步任务

#### 2.8.1 目标

支持批量执行规则和后台异步任务，提供进度跟踪能力。

#### 2.8.2 工作内容

1. **规则依赖排序**
   - 分析 self_reference 的依赖关系
   - 构建依赖图（DAG）
   - 拓扑排序确定执行顺序
   - 识别可并行执行的规则组（同一层级无依赖的规则）

2. **批量执行实现**
   
   ```
   executeRules(ruleIds):
       1. 获取所有规则
       2. 依赖排序
       3. 按顺序执行（或并行执行同层级规则）
       4. 返回所有结果
   
   executeProject(projectId):
       1. 获取项目所有规则
       2. 调用 executeRules
   ```

3. **异步执行实现**
   - 使用 `@Async` 或线程池执行
   - 或使用 RabbitMQ 消息队列（复用 parse-service 的模式）
   - 返回任务 ID

4. **进度跟踪**
   - 使用 Redis 存储执行进度
   - 数据结构：`extract_task:{taskId}` -> `{total, completed, failed, currentRule, status}`
   - 提供 SSE 或轮询接口查询进度

5. **Controller 层**
   - `ExtractExecuteController`
   - POST `/projects/{projectId}/execute` - 执行项目
   - POST `/rules/{ruleId}/execute` - 执行单条
   - POST `/rules/batch-execute` - 批量执行
   - POST `/rules/{ruleId}/preview` - 预览
   - POST `/rules/{ruleId}/retry` - 重试
   - GET `/tasks/{taskId}/progress` - 获取进度

6. **预览功能**
   - 执行提取但不保存结果
   - 返回预览内容和来源信息

7. **重试功能**
   - 清除旧的提取结果
   - 重新执行规则

#### 2.8.3 验收标准

- [ ] 依赖排序正确
- [ ] 批量执行按正确顺序执行
- [ ] 异步执行可正常工作
- [ ] 进度可实时查询
- [ ] 预览和重试功能正常

#### 2.8.4 依赖关系

依赖第七阶段完成。

---

### 第九阶段：结果管理与人工干预

#### 2.9.1 目标

支持结果查看、确认、修正等人工干预操作。

#### 2.9.2 工作内容

1. **ExtractResultService**
   - `listByProjectId(projectId)` - 获取项目所有结果
   - `listByRuleId(ruleId)` - 获取规则的结果历史
   - `getById(id)` - 获取结果详情
   - `confirm(id, userId)` - 确认结果
   - `reject(id, userId, reason)` - 拒绝结果
   - `modify(id, modifiedValue, userId)` - 修正结果
   - `batchConfirm(projectId, userId)` - 批量确认所有待确认结果

2. **状态流转**
   ```
   extracted ──► confirmed（确认）
            ──► rejected（拒绝）
            ──► modified（修正）
   ```

3. **Controller 层**
   - `ExtractResultController`
   - GET `/projects/{projectId}/results` - 项目结果列表
   - GET `/rules/{ruleId}/results` - 规则结果历史
   - POST `/results/{id}/confirm` - 确认
   - POST `/results/{id}/reject` - 拒绝
   - PUT `/results/{id}/modify` - 修正
   - POST `/projects/{projectId}/results/confirm-all` - 批量确认

4. **响应 DTO**
   - `ExtractResultResponse` - 包含来源追溯信息
   - `ResultListResponse` - 结果列表（含统计）

5. **统计信息**
   - 项目结果统计：总数、已确认、待确认、已拒绝
   - 提取成功率统计

#### 2.9.3 验收标准

- [ ] 结果查询 API 正常
- [ ] 确认/拒绝/修正操作正常
- [ ] 批量确认功能正常
- [ ] 来源追溯信息可正确展示
- [ ] 统计信息正确

#### 2.9.4 依赖关系

依赖第七阶段完成。

---

### 第十阶段：规则模板功能

#### 2.10.1 目标

支持规则配置的保存和复用，提高配置效率。

#### 2.10.2 工作内容

1. **RuleTemplateService**
   - `create(userId, request)` - 创建模板
   - `getById(id)` - 获取模板详情
   - `listByUserId(userId)` - 用户的模板列表
   - `listPublic()` - 公开模板列表
   - `delete(id)` - 删除模板
   - `saveFromProject(projectId, name, description)` - 从项目保存为模板
   - `applyToProject(templateId, projectId)` - 应用模板到项目

2. **保存为模板**
   - 快照项目当前的所有规则配置
   - 移除项目特定信息（projectId、sourceDocId）
   - 保存 documentAlias 作为文档匹配依据

3. **应用模板**
   - 根据 documentAlias 匹配项目中的来源文档
   - 创建规则副本，绑定到匹配的来源文档
   - 未匹配的规则标记为需要手动配置

4. **Controller 层**
   - `RuleTemplateController`
   - POST `/templates` - 创建模板
   - GET `/templates` - 模板列表
   - GET `/templates/{id}` - 模板详情
   - DELETE `/templates/{id}` - 删除模板
   - POST `/templates/{id}/apply` - 应用模板
   - POST `/projects/{projectId}/save-as-template` - 保存为模板

5. **模板分享**
   - 支持设置模板为公开/私有
   - 公开模板所有用户可见

#### 2.10.3 验收标准

- [ ] 可将项目规则保存为模板
- [ ] 可将模板应用到新项目
- [ ] 模板应用时文档匹配正确
- [ ] 公开/私有模板功能正常

#### 2.10.4 依赖关系

依赖第四阶段完成，可与后续阶段并行开发。

---

### 第十一阶段：集成与扩展

#### 2.11.1 目标

完善系统集成、错误处理、日志和文档。

#### 2.11.2 工作内容

1. **与 DataSourceService 集成**
   - 提供将提取结果注册为数据源的功能
   - `registerAsDataSource(resultId, userId)` -> DataSource
   - 支持批量注册项目所有结果
   - 用于后续报告生成使用

2. **错误处理完善**
   - 定义错误码枚举 `ExtractErrorCode`
   - 统一异常类 `ExtractException`
   - 全局异常处理器

   | 错误码 | 说明 |
   | ------ | ---- |
   | EXTRACT_001 | 项目不存在 |
   | EXTRACT_002 | 来源文档不存在 |
   | EXTRACT_003 | 规则配置无效 |
   | EXTRACT_004 | 文档未解析完成 |
   | EXTRACT_005 | 内容定位失败 |
   | EXTRACT_006 | AI 提取失败 |
   | EXTRACT_007 | 引用的字段未提取 |
   | EXTRACT_008 | 循环引用 |

3. **日志完善**
   - 规则执行日志（开始、结束、耗时）
   - AI 调用日志（Prompt、Token 使用）
   - 错误日志（详细错误信息）

4. **API 文档**
   - 配置 SpringDoc/Swagger
   - 完善接口注释和示例
   - 生成 OpenAPI 文档

5. **性能优化**
   - 批量查询优化
   - AI 调用缓存（相同内容+配置的缓存）
   - 内容定位结果缓存

6. **单元测试**
   - Service 层单元测试
   - Executor 单元测试
   - 配置校验测试

7. **集成测试**
   - 完整流程测试（创建项目→配置规则→执行→确认）
   - 边界条件测试

#### 2.11.3 验收标准

- [ ] 提取结果可注册为数据源
- [ ] 错误处理统一规范
- [ ] 日志记录完整
- [ ] API 文档可访问
- [ ] 核心测试通过

#### 2.11.4 依赖关系

依赖前面所有阶段完成。

---

## 三、开发优先级建议

### 3.1 MVP（最小可行产品）路径

目标：跑通「创建项目 → 添加文档 → 配置规则 → 直接提取 → 查看结果」的完整流程。

```
第一阶段 → 第二阶段 → 第三阶段 → 第四阶段 → 第五阶段 → 
第七阶段（仅 DirectExtractExecutor）→ 第九阶段
```

预计产出：
- 可创建项目和添加文档
- 可配置直接提取规则
- 可执行直接提取并查看结果
- 不含 AI 能力

### 3.2 第二优先级

目标：添加 AI 提取能力

```
第六阶段 + 第七阶段完善（AIExtractExecutor、AISummarizeExecutor）
```

预计产出：
- AI 字段提取能力
- AI 内容总结能力

### 3.3 第三优先级

目标：提升效率和体验

```
第八阶段（批量执行、异步任务）+ 第十阶段（规则模板）
```

预计产出：
- 批量执行项目规则
- 异步执行和进度跟踪
- 规则模板复用

### 3.4 最后完善

目标：系统完善

```
第十一阶段（集成与扩展）
```

预计产出：
- 与数据源集成
- 完善的错误处理和日志
- API 文档和测试

---

## 四、风险与注意事项

### 4.1 技术风险

| 风险 | 影响 | 缓解措施 |
| ---- | ---- | -------- |
| AI 提取准确率不稳定 | 提取结果需要大量人工修正 | 优化 Prompt、提供人工修正功能 |
| 文档解析不完整 | 章节定位失败 | 增强解析能力、支持手动选择元素 |
| 大文档性能问题 | 执行超时 | 分批处理、异步执行 |

### 4.2 依赖风险

| 依赖 | 风险 | 缓解措施 |
| ---- | ---- | -------- |
| document-service | 接口变更 | 定义清晰的 Feign 接口契约 |
| DeepSeekClient | API 不稳定 | 重试机制、降级方案 |
| parse-service | Excel 解析能力不足 | 按需扩展解析能力 |

### 4.3 注意事项

1. **数据库事务**
   - 规则执行时使用事务，失败时回滚
   - 批量操作注意事务边界

2. **并发控制**
   - 同一规则不能同时执行
   - 使用 Redis 分布式锁

3. **数据清理**
   - 项目删除时级联清理所有数据
   - 定期清理已归档项目的提取结果

4. **安全性**
   - 校验用户对项目的访问权限
   - 敏感信息不记录到日志

---

## 五、附录：文件清单预览

### 5.1 extract-service 模块结构

```
backend/extract-service/
├── pom.xml
└── src/main/java/com/lingyue/extract/
    ├── ExtractServiceApplication.java
    ├── config/
    │   ├── ExtractConfig.java
    │   └── FeignConfig.java
    ├── controller/
    │   ├── ProjectController.java
    │   ├── SourceDocumentController.java
    │   ├── ExtractRuleController.java
    │   ├── ExtractExecuteController.java
    │   ├── ExtractResultController.java
    │   └── RuleTemplateController.java
    ├── dto/
    │   ├── request/
    │   │   ├── CreateProjectRequest.java
    │   │   ├── UpdateProjectRequest.java
    │   │   ├── AddSourceDocumentRequest.java
    │   │   ├── CreateRuleRequest.java
    │   │   ├── UpdateRuleRequest.java
    │   │   ├── BatchCreateRulesRequest.java
    │   │   ├── ExecuteRulesRequest.java
    │   │   ├── ConfirmResultRequest.java
    │   │   ├── ModifyResultRequest.java
    │   │   └── SaveAsTemplateRequest.java
    │   ├── response/
    │   │   ├── ProjectDetailResponse.java
    │   │   ├── ProjectListResponse.java
    │   │   ├── SourceDocumentResponse.java
    │   │   ├── RuleDetailResponse.java
    │   │   ├── RuleListResponse.java
    │   │   ├── ExtractResultResponse.java
    │   │   ├── ResultListResponse.java
    │   │   ├── ExecuteProgressResponse.java
    │   │   ├── PreviewResponse.java
    │   │   └── TemplateDetailResponse.java
    │   └── config/
    │       ├── SourceConfig.java
    │       ├── DocumentSourceConfig.java
    │       ├── SelfReferenceSourceConfig.java
    │       ├── FixedSourceConfig.java
    │       ├── ManualSourceConfig.java
    │       ├── LocationConfig.java
    │       ├── TransformConfig.java
    │       ├── ExtractConfigBase.java
    │       ├── DirectExtractConfig.java
    │       ├── AIExtractConfig.java
    │       ├── AISummarizeConfig.java
    │       └── OcrExtractConfig.java
    ├── entity/
    │   ├── Project.java
    │   ├── SourceDocument.java
    │   ├── ExtractRule.java
    │   ├── ExtractResult.java
    │   └── RuleTemplate.java
    ├── repository/
    │   ├── ProjectRepository.java
    │   ├── SourceDocumentRepository.java
    │   ├── ExtractRuleRepository.java
    │   ├── ExtractResultRepository.java
    │   └── RuleTemplateRepository.java
    ├── service/
    │   ├── ProjectService.java
    │   ├── SourceDocumentService.java
    │   ├── ExtractRuleService.java
    │   ├── ExtractExecuteService.java
    │   ├── ExtractResultService.java
    │   ├── ContentLocatorService.java
    │   ├── AIExtractService.java
    │   └── RuleTemplateService.java
    ├── executor/
    │   ├── ExtractExecutor.java
    │   ├── DirectExtractExecutor.java
    │   ├── AIExtractExecutor.java
    │   ├── AISummarizeExecutor.java
    │   └── OcrExtractExecutor.java
    ├── client/
    │   ├── DocumentServiceClient.java
    │   ├── DocumentElementServiceClient.java
    │   └── ParseServiceClient.java
    ├── exception/
    │   ├── ExtractException.java
    │   ├── ExtractErrorCode.java
    │   └── ExtractExceptionHandler.java
    └── listener/
        └── DocumentParsedEventListener.java
```

---

> 文档结束