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

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

## 一、概述

本文档规划「数据提取规则系统」的代码实现阶段。

**设计理念变更**（v2.0）：
- 从「规则配置驱动」改为「示例文档驱动」
- 用户上传完整报告作为模板，在文档中标记变量
- 使用模板时只需替换来源文件，自动生成新报告

### 1.1 阶段总览

| 阶段 | 名称 | 主要产出 | 预估工作量 | 状态 |
| ---- | ---- | -------- | ---------- | ---- |
| 1 | 数据模型重构 | 新表结构、实体类重构 | 中 | ✅ 已完成 |
| 2 | 模板管理 | Template 的 CRUD API | 中 | ✅ 已完成 |
| 3 | 来源文件定义 | SourceFile 的 CRUD API | 小 | ✅ 已完成 |
| 4 | 变量管理 | Variable 的 CRUD API | 中 | ✅ 已完成 |
| 5 | 内容定位服务 | 按页码/章节/元素定位 | 中 | ⏳ 待开发 |
| 6 | AI 提取服务 | AI 字段提取、总结 | 中 | ✅ 已完成 |
| 7 | 生成任务管理 | Generation 的 CRUD API | 中 | ✅ 已完成 |
| 8 | 提取执行引擎 | 变量提取核心流程 | 大 | ✅ 已完成 |
| 9 | 文档生成 | 替换变量、输出文档 | 中 | ✅ 已完成 |
| 10 | 集成与优化 | 系统集成、性能优化 | 中 | ⏳ 待开发 |

> **当前进度**: 8/10 阶段完成 (80%)
> 
> **备注**: v1.x 版本已完成的代码需要重构以适应新设计

### 1.2 阶段依赖关系图

```
第一阶段（数据模型重构）
    │
    ├─────────────────────────────────────┐
    ▼                                     ▼
第二阶段（模板管理）              第五阶段（内容定位服务）
    │                                     │
    ▼                                     │
第三阶段（来源文件定义）                  │
    │                                     │
    ▼                                     │
第四阶段（变量管理）                      │
    │                                     │
    │           第六阶段（AI提取服务）◄───┤
    │                 │                   │
    ▼                 ▼                   │
第七阶段（生成任务管理）                  │
    │                                     │
    ▼                                     │
第八阶段（提取执行引擎）◄─────────────────┘
    │
    ▼
第九阶段（文档生成）
    │
    ▼
第十阶段（集成与优化）
```

---

## 二、各阶段详细说明

### 第一阶段：数据模型重构

#### 2.1.1 目标

根据新设计重构数据模型，创建新的数据库表和实体类。

#### 2.1.2 工作内容

1. **数据库迁移**
   - 创建新表：`templates`、`source_files`、`variables`、`generations`
   - 可选：保留旧表用于数据迁移，或直接删除

2. **实体类重构**
   - `Template.java` - 模板实体（替代 Project）
   - `SourceFile.java` - 来源文件定义（替代 SourceDocument）
   - `Variable.java` - 变量（替代 ExtractRule）
   - `Generation.java` - 生成任务（新增）

3. **Repository 重构**
   - `TemplateRepository`
   - `SourceFileRepository`
   - `VariableRepository`
   - `GenerationRepository`

4. **DTO 类更新**
   - 来源配置 DTO（复用部分现有类）
   - 提取配置 DTO（复用部分现有类）
   - 位置配置 DTO（新增 `VariableLocation`）

#### 2.1.3 验收标准

- [x] 新表创建成功
- [x] 实体类与表结构对应
- [x] Repository 基本 CRUD 测试通过
- [x] JSONB 字段序列化/反序列化正常

> ✅ **已完成** (2026-01-23)
> 
> 实现概要：
> - 数据库迁移脚本：V2026_01_23_01__refactor_extract_to_template.sql
> - 新表：templates, source_files, variables, generations
> - 实体类：Template, SourceFile, Variable, Generation
> - DTO：VariableLocation, ReferenceSourceConfig
> - Repository：TemplateRepository, SourceFileRepository, VariableRepository, GenerationRepository

#### 2.1.4 处理现有代码

现有代码处理方案：
- `Project` → 重构为 `Template`
- `SourceDocument` → 重构为 `SourceFile`
- `ExtractRule` → 重构为 `Variable`
- `ProjectService` → 重构为 `TemplateService`
- 配置 DTO 类大部分可复用

---

### 第二阶段：模板管理

#### 2.2.1 目标

实现模板的完整 CRUD 功能。

#### 2.2.2 工作内容

1. **TemplateService**
   - `create(userId, request)` - 创建模板
   - `getById(id)` - 获取模板详情
   - `listByUserId(userId, pageRequest)` - 分页查询
   - `update(id, request)` - 更新模板
   - `delete(id)` - 删除模板（级联删除）
   - `publish(id)` - 发布模板
   - `duplicate(id)` - 复制模板
   - `getTemplateWithDetails(id)` - 获取完整详情（含来源文件和变量）

2. **请求/响应 DTO**
   - `CreateTemplateRequest`
   - `UpdateTemplateRequest`
   - `TemplateDetailResponse`
   - `TemplateListResponse`

3. **TemplateController**
   - RESTful API 实现

#### 2.2.3 验收标准

- [x] 可创建模板并关联示例报告
- [x] 可查询、更新、删除模板
- [x] 发布/归档状态切换正常
- [x] 复制模板功能正常

> ✅ **已完成** (2026-01-23)
> 
> 实现概要：
> - TemplateService: create, getById, getTemplateDetail, listByUserId, update, delete, publish, archive, duplicate
> - TemplateController: 完整 RESTful API
> - DTO: CreateTemplateRequest, UpdateTemplateRequest, TemplateDetailResponse, TemplateListResponse

---

### 第三阶段：来源文件定义

#### 2.3.1 目标

实现来源文件定义的管理功能。

#### 2.3.2 工作内容

1. **SourceFileService**
   - `add(templateId, request)` - 添加来源文件定义
   - `listByTemplateId(templateId)` - 获取列表
   - `update(id, request)` - 更新定义
   - `remove(id)` - 删除定义
   - `reorder(templateId, orders)` - 调整顺序

2. **请求/响应 DTO**
   - `AddSourceFileRequest`
   - `UpdateSourceFileRequest`
   - `SourceFileResponse`

3. **SourceFileController**
   - RESTful API 实现

#### 2.3.3 验收标准

- [x] 可添加来源文件定义（自定义别名）
- [x] 别名在模板内唯一
- [x] 可设置文件类型、是否必须等属性
- [x] 可调整显示顺序

> ✅ **已完成** (2026-01-23)
> 
> 实现概要：
> - SourceFileService: add, batchAdd, getById, listByTemplateId, update, delete, forceDelete
> - 集成到 TemplateController（/api/v1/templates/{templateId}/source-files）
> - DTO: AddSourceFileRequest, SourceFileResponse

---

### 第四阶段：变量管理

#### 2.4.1 目标

实现变量的创建和管理功能。

#### 2.4.2 工作内容

1. **VariableService**
   - `create(templateId, request)` - 创建变量
   - `getById(id)` - 获取变量详情
   - `listByTemplateId(templateId)` - 获取列表
   - `update(id, request)` - 更新变量
   - `delete(id)` - 删除变量
   - `validateConfig(variable)` - 校验配置
   - `checkReferenceLoop(variable)` - 检查引用循环

2. **变量位置 DTO**
   ```java
   @Data
   public class VariableLocation {
       private String elementId;      // DocumentElement ID
       private String type;           // text | table_cell | paragraph
       private Integer startOffset;   // 文本起始位置
       private Integer endOffset;     // 文本结束位置
       private Integer rowIndex;      // 表格行
       private Integer colIndex;      // 表格列
   }
   ```

3. **请求/响应 DTO**
   - `CreateVariableRequest`
   - `UpdateVariableRequest`
   - `VariableDetailResponse`

4. **VariableController**
   - RESTful API 实现

#### 2.4.3 验收标准

- [x] 可创建各种来源类型的变量
- [x] 变量名在模板内唯一
- [x] 配置校验正确
- [x] 引用类型变量的循环引用检测正常

> ✅ **已完成** (2026-01-23)
> 
> 实现概要：
> - VariableService: add, batchAdd, getById, getByName, listByTemplateId, update, delete, forceDelete
> - 支持按来源文件、来源类型、分组过滤
> - 引用变量检测: findReferencingVariables
> - 集成到 TemplateController（/api/v1/templates/{templateId}/variables）
> - DTO: AddVariableRequest, VariableResponse

---

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

#### 2.5.1 目标

实现从文档中定位内容的能力。

#### 2.5.2 工作内容

1. **ContentLocatorService**
   - `locateByPage(documentId, pageStart, pageEnd, keyword)` - 按页码定位
   - `locateByChapter(documentId, chapterPath)` - 按章节定位
   - `locateByElement(documentId, elementIds)` - 按元素ID定位
   - `locateExcelCell(documentId, sheetName, cellRef)` - Excel单元格定位
   - `getContent(documentId, location)` - 获取定位到的内容

2. **与 document-service 集成**
   - 调用 DocumentElementService 获取元素
   - 解析章节结构

#### 2.5.3 验收标准

- [ ] 按页码定位正确
- [ ] 按章节定位正确
- [ ] Excel 定位正确
- [ ] 内容拼接正确

---

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

#### 2.6.1 目标

封装 AI 提取和总结功能。

#### 2.6.2 工作内容

1. **AIExtractService**
   - `extract(content, config)` - AI 字段提取
   - `summarize(content, config)` - AI 内容总结
   - `buildPrompt(config)` - 构建 Prompt

2. **Prompt 模板管理**
   - 字段提取 Prompt
   - 内容总结 Prompt

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

#### 2.6.3 验收标准

- [x] AI 提取功能正常
- [x] AI 总结功能正常
- [x] Prompt 参数替换正确

> ✅ **已完成** (2026-01-24)
> 
> 实现概要：
> - ExtractionService: extractByAI(), summarizeByAI(), callAIService()
> - 支持调用 ai-service 的 DeepSeek API
> - Prompt 模板构建: buildExtractionPrompt(), buildSummarizePrompt()

---

### 第七阶段：生成任务管理

#### 2.7.1 目标

实现生成任务的管理功能。

#### 2.7.2 工作内容

1. **GenerationService**
   - `create(request)` - 创建生成任务
   - `getById(id)` - 获取任务详情
   - `listByUserId(userId, pageRequest)` - 分页查询
   - `updateVariableValue(generationId, varName, value)` - 修改变量值
   - `delete(id)` - 删除任务

2. **来源文件映射验证**
   - 检查是否所有必须的来源文件都已上传
   - 验证文件类型是否符合定义

3. **请求/响应 DTO**
   - `CreateGenerationRequest`
   - `GenerationDetailResponse`
   - `UpdateVariableValueRequest`

4. **GenerationController**
   - RESTful API 实现

#### 2.7.3 验收标准

- [x] 可创建生成任务并绑定来源文件
- [x] 来源文件映射验证正确
- [x] 可查询任务详情和变量值

> ✅ **已完成** (2026-01-24)
> 
> 实现概要：
> - GenerationService: create, getById, getDetail, listByUserId, delete
> - GenerationController: 完整 RESTful API
> - DTO: CreateGenerationRequest, GenerationResponse, UpdateVariableValueRequest

---

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

#### 2.8.1 目标

实现变量提取的核心执行流程。

#### 2.8.2 工作内容

1. **变量执行器策略模式**
   ```java
   interface VariableExtractor {
       boolean supports(String sourceType, String extractType);
       ExtractedValue extract(Variable variable, Generation generation);
   }
   ```
   
   实现类：
   - `DocumentDirectExtractor` - 文档直接提取
   - `DocumentAIExtractor` - 文档AI提取
   - `DocumentAISummarizer` - 文档AI总结
   - `ManualValueExtractor` - 手动输入（返回待填写状态）
   - `ReferenceValueExtractor` - 引用其他变量
   - `FixedValueExtractor` - 固定值

2. **执行服务**
   - `ExecutionService.execute(generationId)` - 执行所有变量提取
   - `ExecutionService.executeVariable(generationId, varName)` - 执行单个变量
   - `ExecutionService.preview(generationId, varName)` - 预览提取结果

3. **依赖排序**
   - 分析 reference 类型变量的依赖
   - 拓扑排序确定执行顺序

4. **进度跟踪**
   - Redis 存储执行进度
   - 提供进度查询接口

#### 2.8.3 验收标准

- [x] 各类型变量提取正确
- [x] 依赖排序正确
- [x] 进度跟踪正常
- [x] 预览功能正常

> ✅ **已完成** (2026-01-24)
> 
> 实现概要：
> - ExtractionService: executeExtraction(), processReferenceVariables()
> - 支持 4 种来源类型: document, manual, reference, fixed
> - 支持 3 种提取类型: direct, ai_extract, ai_summarize
> - 异步执行 + 进度跟踪
> - 预览接口: previewExtract()

---

### 第九阶段：文档生成

#### 2.9.1 目标

将提取的变量值替换到模板文档中，生成新文档。

#### 2.9.2 工作内容

1. **DocumentGeneratorService**
   - `generate(generationId)` - 生成文档
   - `replaceVariables(document, variableValues)` - 替换变量
   - `saveOutput(generationId, document)` - 保存输出文档

2. **变量替换逻辑**
   - 根据 Variable.location 定位文档位置
   - 替换对应的文本/表格单元格内容
   - 保持原有格式

3. **文档输出**
   - 生成 Word 文档（.docx）
   - 存储到文件系统
   - 记录 output_document_id

#### 2.9.3 验收标准

- [x] 变量替换正确
- [x] 输出文档格式正确
- [x] 文件存储和下载正常

> ✅ **已完成** (2026-01-24)
> 
> 实现概要：
> - DocumentGenerationService: generateDocument(), getOutputFileResource()
> - 生成文本报告（基础版，TODO: Word 格式）
> - 文件下载: ResponseEntity<Resource>
> - 下载信息接口: getDownloadInfo()

---

### 第十阶段：集成与优化

#### 2.10.1 目标

完善系统集成、错误处理和性能优化。

#### 2.10.2 工作内容

1. **错误处理**
   - 定义错误码
   - 统一异常处理
   - 友好的错误提示

2. **日志完善**
   - 变量执行日志
   - AI 调用日志

3. **性能优化**
   - 批量查询优化
   - AI 调用缓存

4. **API 文档**
   - SpringDoc/Swagger 配置
   - 接口注释完善

5. **测试**
   - 单元测试
   - 集成测试
   - 完整流程测试

#### 2.10.3 验收标准

- [ ] 错误处理完善
- [ ] 日志记录完整
- [ ] API 文档可访问
- [ ] 核心测试通过

---

## 三、开发优先级建议

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

目标：跑通「创建模板 → 标记变量 → 生成报告」的完整流程。

```
第一阶段 → 第二阶段 → 第三阶段 → 第四阶段 → 
第五阶段 → 第七阶段 → 第八阶段（仅 direct 提取）→ 第九阶段
```

MVP 功能：
- 可创建模板并添加来源文件定义
- 可创建变量（仅支持 document + direct 类型）
- 可创建生成任务并上传来源文件
- 可执行提取并生成文档

### 3.2 第二优先级

目标：添加 AI 提取能力

```
第六阶段 + 第八阶段完善（AI 提取器）
```

### 3.3 第三优先级

目标：完善用户体验

```
第十阶段（集成与优化）
```

---

## 四、风险与注意事项

### 4.1 技术风险

| 风险 | 影响 | 缓解措施 |
| ---- | ---- | -------- |
| 变量位置偏移 | 文档修改后变量位置不准确 | 使用 Element ID 定位，而非绝对偏移 |
| AI 提取不稳定 | 提取结果需人工修正 | 提供预览和修改功能 |
| 大文档性能 | 解析和替换耗时 | 异步处理、进度显示 |

### 4.2 现有代码处理

| 现有文件 | 处理方式 |
| -------- | -------- |
| `entity/Project.java` | 重构为 `Template.java` |
| `entity/SourceDocument.java` | 重构为 `SourceFile.java` |
| `entity/ExtractRule.java` | 重构为 `Variable.java` |
| `entity/ExtractResult.java` | 删除，结果存储在 Generation.variable_values |
| `entity/RuleTemplate.java` | 删除，模板功能合并到 Template |
| `service/ProjectService.java` | 重构为 `TemplateService.java` |
| `service/SourceDocumentService.java` | 重构为 `SourceFileService.java` |
| `dto/config/*` | 大部分复用，部分调整 |

---

## 五、附录：新模块结构

```
backend/extract-service/
├── pom.xml
└── src/main/java/com/lingyue/extract/
    ├── ExtractServiceApplication.java
    ├── config/
    │   └── ExtractConfig.java
    ├── controller/
    │   ├── TemplateController.java
    │   ├── SourceFileController.java
    │   ├── VariableController.java
    │   └── GenerationController.java
    ├── dto/
    │   ├── request/
    │   │   ├── CreateTemplateRequest.java
    │   │   ├── UpdateTemplateRequest.java
    │   │   ├── AddSourceFileRequest.java
    │   │   ├── CreateVariableRequest.java
    │   │   ├── UpdateVariableRequest.java
    │   │   ├── CreateGenerationRequest.java
    │   │   └── UpdateVariableValueRequest.java
    │   ├── response/
    │   │   ├── TemplateDetailResponse.java
    │   │   ├── TemplateListResponse.java
    │   │   ├── SourceFileResponse.java
    │   │   ├── VariableDetailResponse.java
    │   │   ├── GenerationDetailResponse.java
    │   │   └── ExecuteProgressResponse.java
    │   └── config/
    │       ├── VariableLocation.java
    │       ├── SourceConfig.java
    │       ├── DocumentSourceConfig.java
    │       ├── ManualSourceConfig.java
    │       ├── ReferenceSourceConfig.java
    │       ├── FixedSourceConfig.java
    │       ├── ExtractConfig.java
    │       ├── DirectExtractConfig.java
    │       ├── AIExtractConfig.java
    │       └── AISummarizeConfig.java
    ├── entity/
    │   ├── Template.java
    │   ├── SourceFile.java
    │   ├── Variable.java
    │   └── Generation.java
    ├── repository/
    │   ├── TemplateRepository.java
    │   ├── SourceFileRepository.java
    │   ├── VariableRepository.java
    │   └── GenerationRepository.java
    ├── service/
    │   ├── TemplateService.java
    │   ├── SourceFileService.java
    │   ├── VariableService.java
    │   ├── GenerationService.java
    │   ├── ExecutionService.java
    │   ├── ContentLocatorService.java
    │   ├── AIExtractService.java
    │   └── DocumentGeneratorService.java
    └── extractor/
        ├── VariableExtractor.java
        ├── DocumentDirectExtractor.java
        ├── DocumentAIExtractor.java
        ├── DocumentAISummarizer.java
        ├── ManualValueExtractor.java
        ├── ReferenceValueExtractor.java
        └── FixedValueExtractor.java
```

---

> 文档结束