lingyue-zhibao/进度报告.md

📊 灵越智报 2.0 - 当前进度总结

整体进度：70% | 报告日期：2026-01-21

---

✅ 已完成（70%）

基础设施

• Spring Boot 3.1.5 单体应用架构（lingyue-starter）
• 数据库（PostgreSQL + pgvector）、缓存（Redis）、消息队列（RabbitMQ）配置完成
• 6大服务模块框架搭建完成
• 数据库重建脚本 → ✅ 完整的 rebuild_all.sh 脚本

核心模块现状

• 📁 文档管理、解析、认证 → 框架完成
• 🤖 AI服务、图谱服务 → 数据层完成，RAG 功能已实现
• 🔍 RAG 向量化存储 → ✅ 已完成
• 🏷️ NER 实体识别服务 → ✅ 已完成并测试验证
• 📄 文档结构化解析 → ✅ 已完成（图片、表格、样式）

新增功能（2026-01-21）✅ 文档结构化解析完成

• ✅ Word 文档结构化提取
  • 完整提取段落、标题、图片、表格等元素
  • 保留元素在文档中的原始顺序和位置
  • 图片自动提取并保存到独立目录
  • 支持图片尺寸、格式、描述信息提取
• ✅ DocumentElement 实体存储
  • 新增 document_elements 表存储结构化内容
  • 支持 JSONB 字段存储样式和表格数据
  • 自定义 PostgreSqlJsonbTypeHandler 处理 JSONB 类型
• ✅ 结构化解析 API
  • GET /parse/structured/{documentId} - 触发结构化解析
  • GET /parse/elements/{documentId} - 获取所有元素
  • GET /parse/elements/{documentId}/images - 获取图片列表
  • GET /parse/elements/{documentId}/tables - 获取表格列表
• ✅ 数据库脚本完善
  • 完整的数据库重建脚本 rebuild_all.sh
  • 修复 UUID/VARCHAR 类型不兼容问题
  • 统一表结构字段命名规范

新增功能（2026-01-20）✅ NER Demo 测试完成

• ✅ DeepSeek API 集成
  • 接入阿里云百炼平台 DeepSeek V3.2 实验版
  • 支持长文本分块处理（每块 2000 字符）
  • 完整的错误处理和重试机制
• ✅ 异步任务轮询模式
  • Python 端：/ner/extract/async 提交异步任务
  • Python 端：/ner/task/{task_id} 查询任务状态和进度
  • Java 端：轮询模式（每 3 秒）查询进度，实时日志反馈
  • 最大等待时间 10 分钟，失败自动回退到同步 API
• ✅ 图数据库存储验证
  • 实体成功存储到 graph_nodes 表（测试文档：188 个实体）
  • 关系成功存储到 graph_relations 表（测试文档：82 个关系）
  • 支持按文档 ID 导出 CSV/JSON 数据
• ✅ Pydantic 序列化修复
  • 修复 Python 模型 alias 序列化问题（snake_case → camelCase）
  • 确保 Java 端正确解析关系数据中的 fromEntityId、toEntityId

新增功能（2026-01-19）

• ✅ NER 服务完整实现
  • Python FastAPI NER 服务（规则模式，支持扩展 spaCy/Transformers/API）
  • Java NER 客户端（PythonNerClient）
  • NER DTO 类（NerRequest, NerResponse, EntityInfo, RelationInfo 等）
  • NER API 接口（/api/ner/extract, /api/ner/document/{id}）
• ✅ 关系抽取服务
  • 基于规则的关系抽取（位置邻近性、语义模式匹配）
  • 关系抽取 API（/api/ner/relations）
• ✅ 图数据库服务扩展
  • GraphNodeService（节点/关系 CRUD、批量操作）
  • 图数据库 API（/api/graph/nodes, /api/graph/relations）
  • 文档节点统计接口
• ✅ 解析流程集成
  • 文档解析完成事件（DocumentParsedEvent）
  • NER 自动触发监听器
  • 解析 → RAG → NER → 图数据库完整链路
  • NER 服务配置项（ner.python-service.url 等）

已完成功能（2026-01-17）

• ✅ 单体应用架构重构 - 统一到 lingyue-starter 模块
• ✅ 配置文件统一 - 全部使用 .properties 格式
• ✅ 接口测试完成 - 核心接口验证通过

已完成功能（2026-01-16）

• ✅ pgvector 向量数据库集成
• ✅ 文本分块服务（智能句子边界切分）
• ✅ Ollama Embedding 向量化服务
• ✅ RAG 核心服务（索引、检索、问答）

---

🎯 第一阶段完成情况

根据设计文档 6.2 第一阶段：核心数据流程（2月10日前）

Week 1-2 任务完成率：95%

任务	状态	说明
文件上传接口	✅	支持 PDF、Word、图片
文件类型识别	✅	MIME 类型检测
OCR 集成（飞浆OCR）	✅	Python 服务调用
文本提取（Word文档）	✅	Apache POI
Word 结构化提取	✅	段落、图片、表格、样式
TXT 文件存储	✅	SSD 硬盘存储
图片资源提取存储	✅	自动提取并保存到独立目录
解析任务管理	✅	异步处理、状态跟踪
NER 服务集成	✅	DeepSeek API 集成
实体提取接口	✅	完整实体列表输出
关系分析接口	✅	规则模式关系抽取
实体存储到图节点表	✅	PostgreSQL 存储验证
图节点 CRUD 接口	✅	完整 CRUD
图关系 CRUD 接口	✅	完整 CRUD
图查询接口	✅	按文档、按用户查询
Neo4j 集成	✅	本地部署，双写同步

Week 3-4 任务待完成：

任务	状态	说明
数据源创建接口	⏳	下一步重点
数据源绑定节点	⏳	下一步重点
数据源查询接口	⏳	下一步重点
模板创建接口	⏳	下一步重点
占位符绑定数据源	⏳	下一步重点
模板渲染接口	⏳	下一步重点
端到端流程测试	⏳	需要完善

---

📋 下一步计划：数据源与模板基础（Week 3）

计划周期：2026-01-21 ~ 2026-01-27

目标：实现数据源管理和模板系统基础功能（设计文档 2.4 / 2.6）

1. 数据源管理（优先级最高）

根据设计文档 2.4.1：

数据源是图数据库中的节点集合，具有层次关系

实施任务：

• 数据源创建接口（DataSource 实体，节点绑定）
• 数据源绑定节点（节点 ID 数组存储，关联关系维护）
• 数据源查询接口（按类型、按文档查询）
• 数据源编辑接口（添加/移除节点）

数据源类型：

• 表格数据源：表格单元格作为独立节点
• 文本数据源：文本片段作为节点
• 图片数据源：图片作为节点

2. 模板系统基础

根据设计文档 2.6.1：

模板是对应输出的占位符结构，占位符绑定到数据源编号

实施任务：

• 模板创建接口（Template 实体，占位符解析）
• 占位符绑定数据源（placeholder_mapping JSONB 存储）
• 模板渲染接口（占位符替换，数据源值获取）
• 模板复制功能（基于已有模板复制）

3. 数据库表设计

根据现有 supplement_tables.sql，需要完善：

-- 数据源表
CREATE TABLE IF NOT EXISTS data_sources (
    id VARCHAR(32) PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    type VARCHAR(50) NOT NULL,  -- table/text/image
    document_id VARCHAR(32),
    node_ids JSONB,  -- 绑定的节点 ID 数组
    metadata JSONB,
    user_id VARCHAR(32),
    create_time TIMESTAMP,
    update_time TIMESTAMP
);

-- 模板表
CREATE TABLE IF NOT EXISTS templates (
    id VARCHAR(32) PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    content TEXT,  -- 模板内容（含占位符）
    placeholder_mapping JSONB,  -- 占位符到数据源的映射
    user_id VARCHAR(32),
    create_time TIMESTAMP,
    update_time TIMESTAMP
);

4. 接口设计

数据源 API：

• POST /api/datasource - 创建数据源
• GET /api/datasource/{id} - 获取数据源
• GET /api/datasource/document/{documentId} - 按文档查询
• PUT /api/datasource/{id}/nodes - 更新绑定节点
• DELETE /api/datasource/{id} - 删除数据源

模板 API：

• POST /api/template - 创建模板
• GET /api/template/{id} - 获取模板
• PUT /api/template/{id}/mapping - 更新占位符映射
• POST /api/template/{id}/render - 渲染模板
• POST /api/template/{id}/copy - 复制模板

---

⚠️ 关键缺失（对照技术预研表）

预研项	进度	已完成 ✅	待实现 ❌
1️⃣ 规则"智能体"设计	45%	Graph Service 架构 规则、模板数据模型 RAG 问答服务 NER 实体提取 Neo4j 图数据库	规则 DSL 定义与解析 规则执行引擎 多层计算算法
2️⃣ 产品定位与功能逻辑	45%	6大后端服务框架 前端交互原型 基础组件 结构化文档展示	所有前端页面 UI 智能体集群架构 规则校验功能
3️⃣ 规则智能体模拟	50%	TextStorage（文本存储） GraphNode、GraphRelation 向量相似度检索 NER + 关系构建 文档结构化存储	规则逻辑树算法 单规则校验引擎 知识图谱构建算法
4️⃣ AI模态体型/OCR	70%	PaddleOCR Client PDF/Word/Excel 提取 DeepSeek API Ollama Embedding Word 结构化提取	AI多模态模型接入 NSDK集成 OCR后处理优化
5️⃣ 前端交互设计	20%	前端交互原型 HTML 文档编辑预览 实体高亮展示	所有核心页面 UI 与后端 API 对接

---

📁 项目结构

backend/
├── common/                 # 公共模块
│   └── mybatis/            # PostgreSqlJsonbTypeHandler
├── auth-service/           # 认证服务
├── document-service/       # 文档管理服务
│   └── entity/             # Document, DocumentElement, DocumentBlock
├── parse-service/          # 解析服务
│   └── service/            # WordStructuredExtractionService
├── ai-service/             # AI服务
├── graph-service/          # 图谱服务（RAG、NER、图数据库）
│   └── neo4j/              # Neo4j 集成服务
├── notification-service/   # 通知服务
├── gateway-service/        # 网关服务
├── lingyue-starter/        # 单体应用启动器
└── sql/                    # 数据库脚本
    ├── rebuild_all.sh      # 完整重建脚本
    ├── init.sql            # 基础表
    ├── graph_tables.sql    # 图谱表
    ├── supplement_tables.sql # 补充表
    └── rag_tables_compatible.sql # RAG 表

python-services/
└── ner-service/            # NER Python 服务
    ├── app/
    │   ├── models/         # 数据模型
    │   ├── routers/        # API 路由
    │   └── services/       # 业务服务
    │       ├── ner_service.py      # NER 调度
    │       ├── deepseek_service.py # DeepSeek API
    │       └── relation_service.py # 关系抽取
    └── requirements.txt

frontend/
└── 灵越智报_完整交互版.html  # 前端交互原型

database/
└── migrations/             # 数据库迁移脚本
    └── V2026_01_21_02__add_document_elements.sql

---

🔧 技术栈确认

组件	技术选型	状态
后端框架	Spring Boot 3.1.5	✅
数据库	PostgreSQL + pgvector	✅
缓存	Redis	✅
消息队列	RabbitMQ	✅
NER 模型	DeepSeek API（内测）	✅
Embedding	Ollama nomic-embed-text	✅
OCR	PaddleOCR	✅
图数据库	PostgreSQL + Neo4j 4.4	✅
文档解析	Apache POI（Word 结构化）	✅
前端	HTML 交互原型	✅
前端框架	Flutter Web（待开发）	⏳

---

📅 里程碑

• M1（2月10日）：第一阶段完成，核心流程跑通
  • ✅ 文件上传解析
  • ✅ RAG 向量检索
  • ✅ NER 实体提取
  • ✅ 文档结构化解析（图片、表格）
  • ✅ Neo4j 图数据库集成
  • ⏳ 数据源管理（下一步）
  • ⏳ 模板基础（下一步）

---

📋 API 接口清单

文档解析服务（parse-service）

接口	方法	说明	状态
/parse/structured/{documentId}	GET	触发结构化解析	✅
/parse/elements/{documentId}	GET	获取所有结构化元素	✅
/parse/elements/{documentId}/images	GET	获取图片列表	✅
/parse/elements/{documentId}/tables	GET	获取表格列表	✅
/api/v1/files/images/{docId}/{filename}	GET	获取图片资源	✅

NER 服务（ner-service）

接口	方法	说明	状态
/api/ner/extract	POST	文本实体抽取	✅
/api/ner/document/{id}	POST	文档实体抽取	✅
/api/ner/relations	POST	关系抽取	✅

图谱服务（graph-service）

接口	方法	说明	状态
/api/v1/graph/nodes	GET/POST	节点 CRUD	✅
/api/v1/graph/relations	GET/POST	关系 CRUD	✅
/api/v1/graph/document/{id}	GET	按文档查询	✅

---

🗄️ 数据库表清单

表名	说明	状态
users	用户表	✅
documents	文档表	✅
document_elements	文档结构化元素	✅
document_blocks	文档块（TextElement）	✅
document_entities	文档实体	✅
graph_nodes	图节点	✅
graph_relations	图关系	✅
text_chunks	文本分块	✅
vector_embeddings	向量嵌入	✅
text_storage	文本存储	✅
parse_tasks	解析任务	✅
rules	规则表	✅（结构）
templates	模板表	✅（结构）
data_sources	数据源表	✅（结构）