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

**整体进度：80%**  |  **报告日期：2026-01-22**

---

## ✅ 已完成（80%）

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

### 核心模块现状
- 📁 **文档管理、解析、认证** → ✅ 功能完善
- 🤖 AI服务、图谱服务 → 数据层完成，RAG 功能已实现
- 🔍 **RAG 向量化存储** → ✅ 已完成
- 🏷️ **NER 实体识别服务** → ✅ 已完成并测试验证
- 📄 **文档结构化解析** → ✅ 已完成（图片、表格、样式）
- 📦 **数据源管理** → ✅ 已完成（CRUD + 取值 + 聚合）
- ⏱️ **任务中心** → ✅ 已完成（多阶段进度跟踪）

### 新增功能（2026-01-22 晚）✅ 数据提取规则系统 - 阶段一、二

- ✅ **第一阶段：基础设施搭建**
  - Maven 模块 `extract-service` 框架搭建完成
  - 启动类 `ExtractServiceApplication.java`
  - 配置文件 `application.properties`（端口 8086）
  - 健康检查接口 `/api/v1/extract/health`
  - 数据库表（5张核心表）：`extract_projects`, `extract_source_documents`, `extract_rules`, `extract_results`, `extract_rule_templates`
  - 集成配置：父 pom.xml、lingyue-starter 依赖

- ✅ **第二阶段：核心实体与 Repository 层**
  - 实体类（5个）：`Project`, `SourceDocument`, `ExtractRule`, `ExtractResult`, `RuleTemplate`
  - Repository 接口（5个）：完整 CRUD + 自定义查询方法
  - 配置 DTO 类（10个）：
    - 来源配置：`LocationConfig`, `TransformConfig`, `DocumentSourceConfig`, `SelfReferenceSourceConfig`, `FixedSourceConfig`, `ManualSourceConfig`
    - 提取配置：`DirectExtractConfig`, `AIExtractConfig`, `AISummarizeConfig`, `OcrExtractConfig`

### 新增功能（2026-01-22 下午）✅ 补充缺失接口

- ✅ **认证服务接口完善**
  - `PUT /auth/profile` - 用户信息修改（用户名、邮箱、头像）
  - `PUT /auth/password` - 密码修改（验证旧密码、新密码确认）
  
- ✅ **文档管理接口完善**
  - `PUT /api/v1/documents/{id}` - 文档更新（名称、状态、元数据）
  - `DELETE /api/v1/documents/{id}` - **级联删除增强**
    - 删除向量嵌入、文本分块、图关系、图节点
    - 删除结构化元素、解析任务、文档记录
    - 删除文本文件和图片目录
  - `POST /api/v1/documents/batch-delete` - 批量删除（返回成功/失败列表）

### 新增功能（2026-01-22 上午）✅ 一键上传全自动处理 + 数据源管理

- ✅ **一键上传全自动处理流程**
  - 上传接口：`POST /api/v1/parse/upload`（唯一入口）
  - 自动触发：RAG向量化 → 结构化解析 → NER实体提取 → 图数据库存储
  - 手动重处理 API 保留，支持单独重新生成
  
- ✅ **数据源管理系统**
  - 支持绑定 `GraphNode` 和 `DocumentElement` 两种类型
  - 支持多种值类型：text/image/table/mixed
  - 支持多种聚合方式：first/last/concat/sum/avg/list
  - 完整 CRUD + 取值 + 批量取值 API
  
- ✅ **任务中心进度跟踪**
  - 6阶段进度：upload → parse → rag → structured → ner → graph
  - 阶段权重：parse(15%) + rag(10%) + structured(15%) + ner(50%) + graph(10%)
  - 实时进度查询 API + 结果摘要展示
  
- ✅ **端到端测试脚本完善**
  - `test_upload_api.sh` 支持完整流程测试
  - 自动轮询等待 NER 完成（基于 GraphNode 数量稳定检测）
  - 支持任务中心查询、数据源操作等

### 新增功能（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 任务完成情况：

| 任务 | 状态 | 说明 |
|------|------|------|
| 数据源创建接口 | ✅ | `POST /api/v1/datasource` |
| 数据源绑定节点 | ✅ | `PUT /api/v1/datasource/{id}/refs` |
| 数据源查询接口 | ✅ | 按ID/文档/用户/类型查询 |
| 数据源取值接口 | ✅ | `GET /api/v1/datasource/{id}/value` |
| 批量取值接口 | ✅ | `POST /api/v1/datasource/batch-value` |
| 任务中心进度跟踪 | ✅ | 6阶段进度 + 结果摘要 |
| 端到端流程测试 | ✅ | 完整测试脚本 |
| 模板创建接口 | ⏳ | 下一步重点 |
| 占位符绑定数据源 | ⏳ | 下一步重点 |
| 模板渲染接口 | ⏳ | 下一步重点 |

---

## 📋 下一步计划：模板系统（Week 4）

**计划周期：2026-01-23 ~ 2026-01-27**

**目标：实现模板系统基础功能**（设计文档 2.6）

### 1. 数据源管理 ✅ 已完成

- [x] 数据源创建接口
- [x] 数据源绑定节点（支持 GraphNode + DocumentElement）
- [x] 数据源查询接口（按ID/文档/用户/类型）
- [x] 数据源取值接口（支持聚合：first/last/concat/sum/avg/list）
- [x] 数据源批量取值（用于模板渲染）

### 2. 模板系统基础（下一步重点）

根据设计文档 2.6.1：
> 模板是对应输出的占位符结构，占位符绑定到数据源编号

**实施任务：**
- [ ] 模板创建接口（Template 实体，占位符解析）
- [ ] 占位符绑定数据源（placeholder_mapping JSONB 存储）
- [ ] 模板渲染接口（占位符替换，调用数据源批量取值）
- [ ] 模板复制功能（基于已有模板复制）

### 3. 已实现的数据源 API

| 接口 | 方法 | 说明 | 状态 |
|------|------|------|------|
| `/api/v1/datasource` | POST | 创建数据源 | ✅ |
| `/api/v1/datasource/{id}` | GET | 获取数据源 | ✅ |
| `/api/v1/datasource/document/{documentId}` | GET | 按文档查询 | ✅ |
| `/api/v1/datasource/user/{userId}` | GET | 按用户查询 | ✅ |
| `/api/v1/datasource/{id}` | PUT | 更新数据源 | ✅ |
| `/api/v1/datasource/{id}/refs` | PUT | 更新绑定节点 | ✅ |
| `/api/v1/datasource/{id}` | DELETE | 删除数据源 | ✅ |
| `/api/v1/datasource/{id}/value` | GET | 获取数据源值 | ✅ |
| `/api/v1/datasource/batch-value` | POST | 批量获取值 | ✅ |

### 4. 待实现的模板 API

| 接口 | 方法 | 说明 | 状态 |
|------|------|------|------|
| `/api/v1/template` | POST | 创建模板 | ⏳ |
| `/api/v1/template/{id}` | GET | 获取模板 | ⏳ |
| `/api/v1/template/{id}/mapping` | PUT | 更新占位符映射 | ⏳ |
| `/api/v1/template/{id}/render` | POST | 渲染模板 | ⏳ |
| `/api/v1/template/{id}/copy` | POST | 复制模板 | ⏳ |

---

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

| 预研项 | 进度 | 已完成 ✅ | 待实现 ❌ |
|--------|------|-----------|-----------|
| **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 接口清单

### 认证服务（auth-service）

| 接口 | 方法 | 说明 | 状态 |
|------|------|------|------|
| `/auth/register` | POST | 用户注册 | ✅ |
| `/auth/login` | POST | 用户登录 | ✅ |
| `/auth/logout` | POST | 用户登出 | ✅ |
| `/auth/refresh` | POST | 刷新Token | ✅ |
| `/auth/me` | GET | 获取当前用户 | ✅ |
| `/auth/profile` | PUT | **更新用户资料** | ✅ |
| `/auth/password` | PUT | **修改密码** | ✅ |

### 文档管理服务（document-service）

| 接口 | 方法 | 说明 | 状态 |
|------|------|------|------|
| `/api/v1/documents` | GET | 文档列表（分页） | ✅ |
| `/api/v1/documents/{id}` | GET | 文档详情 | ✅ |
| `/api/v1/documents/{id}` | PUT | **更新文档** | ✅ |
| `/api/v1/documents/{id}` | DELETE | **级联删除** | ✅ |
| `/api/v1/documents/batch-delete` | POST | **批量删除** | ✅ |
| `/api/v1/documents/{id}/text` | GET | 获取文档文本 | ✅ |
| `/api/v1/documents/{id}/parse-status` | GET | 解析状态 | ✅ |
| `/api/v1/documents/{id}/elements` | GET | 结构化元素 | ✅ |
| `/api/v1/documents/{id}/images` | GET | 图片列表 | ✅ |
| `/api/v1/documents/{id}/tables` | GET | 表格列表 | ✅ |

### 文件上传（唯一入口）

| 接口 | 方法 | 说明 | 状态 |
|------|------|------|------|
| `/api/v1/parse/upload` | POST | **一键上传，自动触发全流程** | ✅ |

### 文档解析服务（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 | 获取图片资源 | ✅ |

### 任务中心（parse-service）

| 接口 | 方法 | 说明 | 状态 |
|------|------|------|------|
| `/api/v1/tasks/list` | GET | 获取任务列表 | ✅ |
| `/api/v1/tasks/{taskId}/detail` | GET | 获取任务详情 | ✅ |
| `/api/v1/tasks/by-document/{documentId}` | GET | 按文档ID查询任务 | ✅ |
| `/api/v1/tasks/statistics` | GET | 获取任务统计 | ✅ |

### NER 服务（ner-service）

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

### 图谱服务（graph-service）

| 接口 | 方法 | 说明 | 状态 |
|------|------|------|------|
| `/api/graph/nodes` | POST | 创建节点 | ✅ |
| `/api/graph/nodes/{nodeId}` | GET/PUT/DELETE | 节点 CRUD | ✅ |
| `/api/graph/documents/{documentId}/nodes` | GET | 按文档查询节点 | ✅ |
| `/api/graph/relations` | POST | 创建关系 | ✅ |

### 数据源服务（graph-service）

| 接口 | 方法 | 说明 | 状态 |
|------|------|------|------|
| `/api/v1/datasource` | POST | 创建数据源 | ✅ |
| `/api/v1/datasource/{id}` | GET | 获取数据源 | ✅ |
| `/api/v1/datasource/document/{documentId}` | GET | 按文档查询 | ✅ |
| `/api/v1/datasource/{id}/refs` | PUT | 更新绑定节点 | ✅ |
| `/api/v1/datasource/{id}/value` | GET | **获取数据源值** | ✅ |
| `/api/v1/datasource/batch-value` | POST | **批量获取值** | ✅ |

---

## 🗄️ 数据库表清单

| 表名 | 说明 | 状态 |
|------|------|------|
| `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` | 数据源表 | ✅（结构）|
| `extract_projects` | 提取项目表 | ✅ |
| `extract_source_documents` | 来源文档表 | ✅ |
| `extract_rules` | 提取规则表 | ✅ |
| `extract_results` | 提取结果表 | ✅ |
| `extract_rule_templates` | 规则模板表 | ✅ |