Strona główna Odkrywaj Pomoc
Zaloguj się
hewensong
/
lingyue-zhibao
1
0
Forkuj 0
Pliki Problemy 0 Oczekujące zmiany 0 Wiki
Drzewo: 4454793beb
Gałęzie Tagi
lingyue-zhibao
/
docs
/
design
/
数据提取规则系统-实现阶段规划.md

数据提取规则系统-实现阶段规划.md 16 KB
Historia Czysty

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

版本: 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 集成与优化 系统集成、性能优化 中 ⏳ 待开发

当前进度: 1/10 阶段完成 (10%)

备注: 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 验收标准

  • 新表创建成功
  • 实体类与表结构对应
  • 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 工作内容

  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 验收标准

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

第三阶段：来源文件定义

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 验收标准

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

第四阶段：变量管理

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

    @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 验收标准

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

第五阶段：内容定位服务

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 验收标准

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

第七阶段：生成任务管理

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 验收标准

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

第八阶段：提取执行引擎

2.8.1 目标

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

2.8.2 工作内容

  1. 变量执行器策略模式

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

实现类：

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

  1. 执行服务

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

  2. 依赖排序

    • 分析 reference 类型变量的依赖
    • 拓扑排序确定执行顺序

  3. 进度跟踪

    • Redis 存储执行进度
    • 提供进度查询接口

2.8.3 验收标准

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

第九阶段：文档生成

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 验收标准

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

第十阶段：集成与优化

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

文档结束