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

版本: 2.0.0 日期: 2026-01-23 作者: AI Assistant (Claude Opus 4.5) 关联文档: 数据提取规则系统设计.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 工作内容

数据库迁移
- 创建新表：templates、source_files、variables、generations
- 可选：保留旧表用于数据迁移，或直接删除
实体类重构
- Template.java - 模板实体（替代 Project）
- SourceFile.java - 来源文件定义（替代 SourceDocument）
- Variable.java - 变量（替代 ExtractRule）
- Generation.java - 生成任务（新增）
Repository 重构
- TemplateRepository
- SourceFileRepository
- VariableRepository
- GenerationRepository
DTO 类更新
- 来源配置 DTO（复用部分现有类）
- 提取配置 DTO（复用部分现有类）
- 位置配置 DTO（新增 VariableLocation）

2.1.3 验收标准

新表创建成功
实体类与表结构对应
Repository 基本 CRUD 测试通过
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 工作内容

TemplateService
- create(userId, request) - 创建模板
- getById(id) - 获取模板详情
- listByUserId(userId, pageRequest) - 分页查询
- update(id, request) - 更新模板
- delete(id) - 删除模板（级联删除）
- publish(id) - 发布模板
- duplicate(id) - 复制模板
- getTemplateWithDetails(id) - 获取完整详情（含来源文件和变量）
请求/响应 DTO
- CreateTemplateRequest
- UpdateTemplateRequest
- TemplateDetailResponse
- TemplateListResponse
TemplateController
- RESTful API 实现

2.2.3 验收标准

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

✅ 已完成 (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 工作内容

SourceFileService
- add(templateId, request) - 添加来源文件定义
- listByTemplateId(templateId) - 获取列表
- update(id, request) - 更新定义
- remove(id) - 删除定义
- reorder(templateId, orders) - 调整顺序
请求/响应 DTO
- AddSourceFileRequest
- UpdateSourceFileRequest
- SourceFileResponse
SourceFileController
- RESTful API 实现

2.3.3 验收标准

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

✅ 已完成 (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 工作内容

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

变量位置 DTO

@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;      // 表格列
}

请求/响应 DTO
- CreateVariableRequest
- UpdateVariableRequest
- VariableDetailResponse
VariableController
- RESTful API 实现

2.4.3 验收标准

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

✅ 已完成 (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 工作内容

ContentLocatorService
- locateByPage(documentId, pageStart, pageEnd, keyword) - 按页码定位
- locateByChapter(documentId, chapterPath) - 按章节定位
- locateByElement(documentId, elementIds) - 按元素ID定位
- locateExcelCell(documentId, sheetName, cellRef) - Excel单元格定位
- getContent(documentId, location) - 获取定位到的内容
与 document-service 集成
- 调用 DocumentElementService 获取元素
- 解析章节结构

2.5.3 验收标准

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

第六阶段：AI 提取服务

2.6.1 目标

封装 AI 提取和总结功能。

2.6.2 工作内容

AIExtractService
- extract(content, config) - AI 字段提取
- summarize(content, config) - AI 内容总结
- buildPrompt(config) - 构建 Prompt
Prompt 模板管理
- 字段提取 Prompt
- 内容总结 Prompt
结果数据结构
- AIExtractResult: value, confidence
- AISummarizeResult: summary

2.6.3 验收标准

AI 提取功能正常
AI 总结功能正常
Prompt 参数替换正确

✅ 已完成 (2026-01-24)

实现概要：

ExtractionService: extractByAI(), summarizeByAI(), callAIService()

支持调用 ai-service 的 DeepSeek API

Prompt 模板构建: buildExtractionPrompt(), buildSummarizePrompt()

第七阶段：生成任务管理

2.7.1 目标

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

2.7.2 工作内容

GenerationService
- create(request) - 创建生成任务
- getById(id) - 获取任务详情
- listByUserId(userId, pageRequest) - 分页查询
- updateVariableValue(generationId, varName, value) - 修改变量值
- delete(id) - 删除任务
来源文件映射验证
- 检查是否所有必须的来源文件都已上传
- 验证文件类型是否符合定义
请求/响应 DTO
- CreateGenerationRequest
- GenerationDetailResponse
- UpdateVariableValueRequest
GenerationController
- RESTful API 实现

2.7.3 验收标准

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

✅ 已完成 (2026-01-24)

实现概要：

GenerationService: create, getById, getDetail, listByUserId, delete

GenerationController: 完整 RESTful API

DTO: CreateGenerationRequest, GenerationResponse, UpdateVariableValueRequest

第八阶段：提取执行引擎

2.8.1 目标

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

2.8.2 工作内容

变量执行器策略模式

interface VariableExtractor {
   boolean supports(String sourceType, String extractType);
   ExtractedValue extract(Variable variable, Generation generation);
}

实现类：

DocumentDirectExtractor - 文档直接提取
DocumentAIExtractor - 文档AI提取
DocumentAISummarizer - 文档AI总结
ManualValueExtractor - 手动输入（返回待填写状态）
ReferenceValueExtractor - 引用其他变量
FixedValueExtractor - 固定值

执行服务
- ExecutionService.execute(generationId) - 执行所有变量提取
- ExecutionService.executeVariable(generationId, varName) - 执行单个变量
- ExecutionService.preview(generationId, varName) - 预览提取结果
依赖排序
- 分析 reference 类型变量的依赖
- 拓扑排序确定执行顺序
进度跟踪
- Redis 存储执行进度
- 提供进度查询接口

2.8.3 验收标准

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

✅ 已完成 (2026-01-24)

实现概要：

ExtractionService: executeExtraction(), processReferenceVariables()

支持 4 种来源类型: document, manual, reference, fixed

支持 3 种提取类型: direct, ai_extract, ai_summarize

异步执行 + 进度跟踪

预览接口: previewExtract()

第九阶段：文档生成

2.9.1 目标

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

2.9.2 工作内容

DocumentGeneratorService
- generate(generationId) - 生成文档
- replaceVariables(document, variableValues) - 替换变量
- saveOutput(generationId, document) - 保存输出文档
变量替换逻辑
- 根据 Variable.location 定位文档位置
- 替换对应的文本/表格单元格内容
- 保持原有格式
文档输出
- 生成 Word 文档（.docx）
- 存储到文件系统
- 记录 output_document_id

2.9.3 验收标准

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

✅ 已完成 (2026-01-24)

实现概要：

DocumentGenerationService: generateDocument(), getOutputFileResource()

生成文本报告（基础版，TODO: Word 格式）

文件下载: ResponseEntity
下载信息接口: getDownloadInfo()

第十阶段：集成与优化

2.10.1 目标

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

2.10.2 工作内容

错误处理

定义错误码

统一异常处理

友好的错误提示

日志完善

变量执行日志

AI 调用日志

性能优化

批量查询优化

AI 调用缓存

API 文档

SpringDoc/Swagger 配置

接口注释完善

测试

单元测试

集成测试

完整流程测试

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
文档结束

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

现有文件	处理方式
`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/*`	大部分复用，部分调整

数据提取规则系统-实现阶段规划.md 18 KB Historique Raw