# 📊 灵越智报 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`，需要完善：

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