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

**整体进度：60%**  |  **报告日期：2026-01-20**

---

## ✅ 已完成（60%）

### 基础设施
- Spring Boot 3.1.5 单体应用架构（lingyue-starter）
- 数据库（PostgreSQL + pgvector）、缓存（Redis）、消息队列（RabbitMQ）配置完成
- 6大服务模块框架搭建完成

### 核心模块现状
- 📁 文档管理、解析、认证 → 框架完成
- 🤖 AI服务、图谱服务 → 数据层完成，RAG 功能已实现
- 🔍 **RAG 向量化存储** → ✅ 已完成
- 🏷️ **NER 实体识别服务** → ✅ 已完成并测试验证

### 新增功能（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 任务完成率：85%

| 任务 | 状态 | 说明 |
|------|------|------|
| 文件上传接口 | ✅ | 支持 PDF、Word、图片 |
| 文件类型识别 | ✅ | MIME 类型检测 |
| OCR 集成（飞浆OCR） | ✅ | Python 服务调用 |
| 文本提取（Word文档） | ✅ | Apache POI |
| TXT 文件存储 | ✅ | SSD 硬盘存储 |
| 解析任务管理 | ✅ | 异步处理、状态跟踪 |
| NER 服务集成 | ✅ | DeepSeek API 集成 |
| 实体提取接口 | ✅ | 完整实体列表输出 |
| 关系分析接口 | ✅ | 规则模式关系抽取 |
| 实体存储到图节点表 | ✅ | PostgreSQL 存储验证 |
| 图节点 CRUD 接口 | ✅ | 完整 CRUD |
| 图关系 CRUD 接口 | ✅ | 完整 CRUD |
| 图查询接口 | ✅ | 按文档、按用户查询 |

### 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️⃣ 规则"智能体"设计** | 40% | Graph Service 架构<br>规则、模板数据模型<br>RAG 问答服务<br>**NER 实体提取** | 规则 DSL 定义与解析<br>规则执行引擎<br>多层计算算法 |
| **2️⃣ 产品定位与功能逻辑** | 40% | 6大后端服务框架<br>Flutter 项目结构<br>基础组件 | 所有前端页面 UI<br>智能体集群架构<br>规则校验功能 |
| **3️⃣ 规则智能体模拟** | 45% | TextStorage（文本存储）<br>GraphNode、GraphRelation<br>**向量相似度检索**<br>**NER + 关系构建** | 规则逻辑树算法<br>单规则校验引擎<br>知识图谱构建算法 |
| **4️⃣ AI模态体型/OCR** | 65% | PaddleOCR Client<br>PDF/Word/Excel 提取<br>**DeepSeek API**<br>**Ollama Embedding** | AI多模态模型接入<br>NSDK集成<br>OCR后处理优化 |
| **5️⃣ 前端交互设计** | 15% | Flutter 项目结构<br>路由、主题配置<br>7个页面骨架 | 所有核心页面 UI<br>与后端 API 对接 |

---

## 📁 项目结构

```
backend/
├── common/                 # 公共模块
├── auth-service/           # 认证服务
├── document-service/       # 文档管理服务
├── parse-service/          # 解析服务
├── ai-service/             # AI服务
├── graph-service/          # 图谱服务（RAG、NER、图数据库）
├── notification-service/   # 通知服务
├── gateway-service/        # 网关服务
├── lingyue-starter/        # 单体应用启动器
└── sql/                    # 数据库脚本

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_flutter/
└── lib/                    # Flutter 前端（待开发）
```

---

## 🔧 技术栈确认

| 组件 | 技术选型 | 状态 |
|------|----------|------|
| 后端框架 | Spring Boot 3.1.5 | ✅ |
| 数据库 | PostgreSQL + pgvector | ✅ |
| 缓存 | Redis | ✅ |
| 消息队列 | RabbitMQ | ✅ |
| NER 模型 | DeepSeek API（内测）| ✅ |
| Embedding | Ollama nomic-embed-text | ✅ |
| OCR | PaddleOCR | ✅ |
| 图数据库 | PostgreSQL 模拟（待接入 Neo4j）| ⏳ |
| 前端 | Flutter Web | ⏳ |

---

## 📅 里程碑

- **M1（2月10日）**：第一阶段完成，核心流程跑通
  - ✅ 文件上传解析
  - ✅ RAG 向量检索
  - ✅ NER 实体提取
  - ⏳ 数据源管理（下一步）
  - ⏳ 模板基础（下一步）