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

**整体进度：92%**  |  **报告日期：2026-01-25**

---

## ✅ 已完成（92%）

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

### 核心模块现状

| 模块 | 功能 | 状态 | 说明 |
|------|------|:----:|------|
| **认证服务** | 注册/登录/Token | ✅ | JWT 认证，密码修改 |
| **文档管理** | 上传/列表/删除 | ✅ | 级联删除，批量操作 |
| **文档解析** | OCR/文本提取 | ✅ | Word/PDF/图片 |
| **结构化解析** | 段落/图片/表格 | ✅ | 保留样式和顺序 |
| **RAG 向量化** | 分块/嵌入/检索 | ✅ | pgvector + Ollama |
| **NER 实体识别** | 实体/关系提取 | ✅ | DeepSeek API |
| **图数据库** | 节点/关系存储 | ✅ | PostgreSQL + Neo4j |
| **数据源管理** | CRUD/取值/聚合 | ✅ | 支持多种值类型 |
| **任务中心** | 多阶段进度跟踪 | ✅ | 6阶段流水线 |
| **模板系统** | 数据模型 | ✅ | v2.0 重构完成 |
| **模板系统** | Service/Controller | ✅ | 完整 CRUD + 状态管理 |
| **报告生成** | 变量提取/文档生成 | ✅ | 基础流程实现完成 |
| **规则系统** | 规则智能体 | ⚠️ | **数据模型已有，逻辑未实现** |
| **前端界面** | Vue Demo | ✅ | 测试用 demo 完成 |
| **前端界面** | 正式 UI | ⏳ | 基于 Vue Demo 扩展 |

### 模块完成度

```
认证服务      ████████████████████ 100%
文档管理      ████████████████████ 100%
文档解析      ████████████████████ 100%
RAG服务       ████████████████████ 100%
NER服务       ████████████████████ 100%
图数据库      ████████████████████ 100%
数据源管理    ████████████████████ 100%
任务中心      ████████████████████ 100%
模板系统      ████████████████████ 100% (完整实现)
报告生成      ████████████████░░░░  80% (基础流程)
规则系统      ████░░░░░░░░░░░░░░░░  20% (仅数据模型)
前端界面      ████████░░░░░░░░░░░░  40% (Vue Demo)
```

### 新增功能（2026-01-25）✅ 前端 Vue Demo + 服务部署

- ✅ **Vue 3 前端 Demo**（`frontend/vue-demo/`）
  - 技术栈：Vue 3 + Vite + Element Plus + Pinia
  - 登录/注册页面（对接后端认证 API）
  - 首页（统计数据从 API 获取）
  - 模板管理页面
  - 模板编辑器（变量标记、分类管理）
  - 生成任务管理
  - 路由守卫（登录验证）

- ✅ **Systemd 服务配置**（`scripts/systemd/`）
  - `lingyue-starter.service` (端口 18520)
  - `lingyue-extract.service` (端口 18521)
  - `lingyue-ner.service` (端口 18522)
  - 一键安装脚本 `install-services.sh`

- ✅ **首页统计 API**
  - `GET /api/v1/templates/stats` - 获取统计数据
  - 返回：reportCount, templateCount, variableCount, sourceFileCount

- ✅ **安全配置更新**
  - SecurityConfig 添加模板系统 API 路径许可

### 新增功能（2026-01-24）✅ 模板系统完整实现 + 原型适配

- ✅ **Service 层（6个服务）**
  - `TemplateService` - 模板 CRUD、发布、归档、复制
  - `SourceFileService` - 来源文件定义管理、重排序
  - `VariableService` - 变量管理、重排序、预览提取、**按类别分组查询**
  - `GenerationService` - 生成任务管理、执行、进度
  - `ExtractionService` - 变量提取核心逻辑
  - `DocumentGenerationService` - 文档生成、文件下载

- ✅ **Controller 层（2个控制器）**
  - `TemplateController` - 模板/来源文件/变量统一管理、**变量分组API**
  - `GenerationController` - 生成任务 CRUD 和执行

- ✅ **DTO（12个）**
  - 请求：CreateTemplateRequest, UpdateTemplateRequest, AddSourceFileRequest, AddVariableRequest, CreateGenerationRequest, UpdateVariableValueRequest, ReorderRequest
  - 响应：TemplateDetailResponse, TemplateListResponse, SourceFileResponse, VariableResponse, GenerationResponse, GenerationProgressResponse, VariablePreviewResponse

- ✅ **工具类**
  - `SecurityUtils` - 从 JWT 获取当前用户ID

- ✅ **原型适配 - Variable.category 字段（新增）**
  - 变量类别用于前端显示分类（与 `灵越智报_完整交互版.html` 原型对齐）
  - 类别定义：
    - `entity` - 核心实体（蓝色）：智慧园区、公司名等
    - `concept` - 概念/技术（紫色）：产业升级、智能化管理等
    - `data` - 数据/指标（绿色）：金额、面积、增长率等
    - `location` - 地点/组织（橙色）：华南地区、华南事业部等
    - `asset` - 资源模板（粉色）：图表、结论模板等
  - 新增 API：`GET /api/v1/templates/{templateId}/variables/grouped` - 按类别分组返回变量
  - 数据库迁移：`V2026_01_24_01__add_variable_category.sql`

### 新增功能（2026-01-23）✅ 模板系统 v2.0 数据模型重构

- ✅ **设计理念升级**
  - 从「规则配置驱动」改为「示例文档驱动」
  - 用户上传完整报告 → 标记变量 → 保存为模板 → 生成新报告
  
- ✅ **数据库重构**
  - 新增 `all_tables.sql` 完整数据库表结构（21张表）
  - 新增 `template_tables.sql` 模板系统专用表
  - `rebuild_all.sh` 增加 `--simple` 模式（单文件初始化）
  
- ✅ **新实体类（4个）**
  - `Template` - 报告模板（替代 Project）
  - `SourceFile` - 来源文件定义（用别名标识）
  - `Variable` - 模板变量（绑定到文档位置）
  - `Generation` - 生成任务
  
- ✅ **新 Repository（4个）**
  - `TemplateRepository`, `SourceFileRepository`, `VariableRepository`, `GenerationRepository`
  
- ✅ **新 DTO 类**
  - `VariableLocation` - 变量在文档中的位置
  - `ReferenceSourceConfig` - 引用来源配置

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

- ✅ **第一阶段：基础设施搭建**
  - Maven 模块 `extract-service` 框架搭建完成
  - 启动类 `ExtractServiceApplication.java`
  - 配置文件 `application.properties`（端口 8086）
  - 健康检查接口 `/api/v1/extract/health`
  - ~~数据库表（5张核心表）~~ → 已重构为模板系统 v2.0
  - 集成配置：父 pom.xml、lingyue-starter 依赖

- ✅ **第二阶段：核心实体与 Repository 层**（已重构为 v2.0）
  - ~~实体类（5个）：Project, SourceDocument, ExtractRule...~~ 
  - → 新实体：Template, SourceFile, Variable, Generation

### 新增功能（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阶段进度 + 结果摘要 |
| 端到端流程测试 | ✅ | 完整测试脚本 |
| 模板创建接口 | ⏳ | 下一步重点 |
| 占位符绑定数据源 | ⏳ | 下一步重点 |
| 模板渲染接口 | ⏳ | 下一步重点 |

---

## 📋 下一步计划：模板系统 v2.0（Week 4-5）

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

**目标：完成「示例文档驱动」的模板生成系统**

### 1. 数据模型重构 ✅ 已完成

- [x] 数据库表重构（templates, source_files, variables, generations）
- [x] 实体类创建（Template, SourceFile, Variable, Generation）
- [x] Repository 接口（4个）
- [x] all_tables.sql 完整表结构
- [x] rebuild_all.sh --simple 模式

### 2. 模板管理（下一步重点）

**核心用户流程：**
1. 用户上传示例报告（Word 文档）
2. 在报告中选中文本，标记为"变量"
3. 为每个变量配置数据来源（从哪个来源文件提取）
4. 保存为模板

**待实现 API：**

| 接口 | 方法 | 说明 | 状态 |
|------|------|------|------|
| `/api/v1/templates` | POST | 创建模板 | ⏳ |
| `/api/v1/templates/{id}` | GET | 获取模板详情 | ⏳ |
| `/api/v1/templates` | GET | 模板列表 | ⏳ |
| `/api/v1/templates/{id}` | PUT | 更新模板 | ⏳ |
| `/api/v1/templates/{id}/publish` | POST | 发布模板 | ⏳ |
| `/api/v1/templates/{id}/source-files` | POST | 添加来源文件定义 | ⏳ |
| `/api/v1/templates/{id}/variables` | POST | 添加变量 | ⏳ |

### 3. 报告生成

**核心用户流程：**
1. 选择模板
2. 上传新的来源文件（按模板定义的别名）
3. 系统自动提取变量值
4. 用户确认/修改提取结果
5. 生成新报告

**待实现 API：**

| 接口 | 方法 | 说明 | 状态 |
|------|------|------|------|
| `/api/v1/generations` | POST | 创建生成任务 | ⏳ |
| `/api/v1/generations/{id}` | GET | 获取生成任务详情 | ⏳ |
| `/api/v1/generations/{id}/extract` | POST | 执行变量提取 | ⏳ |
| `/api/v1/generations/{id}/confirm` | POST | 确认提取结果 | ⏳ |
| `/api/v1/generations/{id}/generate` | POST | 生成最终报告 | ⏳ |

### 4. 已实现的数据源 API（保留）

| 接口 | 方法 | 说明 | 状态 |
|------|------|------|------|
| `/api/v1/datasource` | POST | 创建数据源 | ✅ |
| `/api/v1/datasource/{id}` | GET | 获取数据源 | ✅ |
| `/api/v1/datasource/{id}/value` | GET | 获取数据源值 | ✅ |
| `/api/v1/datasource/batch-value` | POST | 批量获取值 | ✅ |

---

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

| 预研项 | 进度 | 已完成 ✅ | 待实现 ❌ |
|--------|------|-----------|-----------|
| **1️⃣ 规则"智能体"设计** | 45% | Graph Service 架构<br>规则、模板数据模型<br>RAG 问答服务<br>**NER 实体提取**<br>**Neo4j 图数据库** | 规则 DSL 定义与解析<br>规则执行引擎<br>多层计算算法 |
| **2️⃣ 产品定位与功能逻辑** | 55% | 6大后端服务框架<br>**前端 Vue Demo**<br>基础组件<br>**结构化文档展示** | Vue 正式 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️⃣ 前端交互设计** | 40% | **前端 Vue Demo**<br>**登录/注册页面**<br>**模板管理页面**<br>文档编辑预览<br>实体高亮展示 | Vue 正式 UI 完善<br>知识图谱可视化 |

---

## 🔴 规则系统模块 - 详细欠缺分析

根据设计文档 `a_docs/灵越智报2.0程序设计详解.md` 中的规则系统设计，以下是当前实现与设计目标的对比：

### 已有基础设施

| 组件 | 状态 | 说明 |
|------|------|------|
| `rules` 表 | ✅ | 数据库表结构已定义 |
| `Rule` 实体类 | ✅ | `graph-service` 中有基础实体 |
| `ExtractRule` 实体类 | ✅ | `extract-service` 中有提取规则实体 |
| `RuleRepository` | ✅ | 仅有 Mapper 接口 |
| `RuleTemplate` 实体类 | ✅ | 规则模板实体 |
| 图节点/关系存储 | ✅ | `graph_nodes` + `graph_relations` |
| Neo4j 集成 | ✅ | 双写同步 |

### ❌ 核心欠缺功能

#### 1. 规则 Service 层（完全缺失）

```
需要实现:
- RuleService.java          # 规则 CRUD + 执行调度
- RuleExecutionService.java # 规则链执行引擎
- RuleValidationService.java # 规则校验逻辑
```

**设计要求**：
- 规则本质是 n 个节点之间的关系链（类似单链表）
- 唯一入口，唯一出口，有方向性
- 支持条件分支（拆分为多条规则）

#### 2. 规则 Controller 层（完全缺失）

```
需要实现的 API:
POST   /api/v1/rules                    # 创建规则
GET    /api/v1/rules/{id}               # 获取规则详情
GET    /api/v1/rules                    # 规则列表
PUT    /api/v1/rules/{id}               # 更新规则
DELETE /api/v1/rules/{id}               # 删除规则
POST   /api/v1/rules/{id}/validate      # 校验规则
POST   /api/v1/rules/{id}/execute       # 执行规则
GET    /api/v1/rules/{id}/trace         # 获取执行轨迹
```

#### 3. 规则执行引擎（完全缺失）

**设计要求**（来自设计文档 2.5 章节）：

| 关系类型 | 说明 | 实现状态 |
|----------|------|----------|
| 依赖关系（DEP） | 数据获取依赖，不涉及计算 | ❌ |
| 计算关系 | 加减乘除、取并集、取交集 | ❌ |
| AI能力调用 | 调用AI进行文本生成、总结 | ❌ |

**核心类设计**：

```java
// 规则执行器接口
interface RuleExecutor {
    Object execute(RuleContext context);
}

// 规则动作类型（设计文档提到约 20-200 类）
enum RuleActionType {
    DEP_FETCH,      // 依赖获取
    CALC_ADD,       // 加法
    CALC_SUB,       // 减法
    CALC_MUL,       // 乘法
    CALC_DIV,       // 除法
    CALC_UNION,     // 取并集
    CALC_INTERSECT, // 取交集
    AI_GENERATE,    // AI 生成
    AI_SUMMARIZE,   // AI 总结
    AI_EXTRACT,     // AI 提取
    // ...
}
```

#### 4. 规则 DSL 定义与解析（完全缺失）

**设计要求**：
- 规则用 DSL（领域特定语言）描述
- 支持 AI 对话生成规则
- 输出固定格式的规则描述

```
示例 DSL 格式（待设计）:
RULE "计算总价"
  INPUT @产品单价, @产品数量
  ACTION CALC_MUL(@产品单价, @产品数量)
  OUTPUT @总价
END
```

#### 5. 规则智能体（完全缺失）

**设计要求**（来自设计文档 2.5.5 章节）：

| 能力 | 说明 | 实现状态 |
|------|------|----------|
| 规则逻辑校验 | 验证规则链完整性、检查循环依赖 | ❌ |
| 规则关联分析 | 分析规则之间的依赖关系 | ❌ |
| 要素查询 | 根据规则查询相关节点 | ❌ |
| 上下文生成 | 将图关系转换为 AI 可理解的格式 | ❌ |

#### 6. AI 记忆库构建（完全缺失）

**设计要求**：
- 输入+输出模式记录
- 规则逻辑上下文保存
- 自动发现规则关联

### 📋 规则系统实现优先级

| 优先级 | 功能 | 预计工作量 |
|--------|------|------------|
| P0 | RuleService CRUD | 2天 |
| P0 | RuleController API | 1天 |
| P1 | 规则执行引擎（基础动作） | 3天 |
| P1 | 规则校验（入口→出口路径） | 2天 |
| P2 | 规则 DSL 解析器 | 3天 |
| P2 | AI 对话生成规则 | 2天 |
| P3 | 规则智能体上下文构建 | 3天 |
| P3 | AI 记忆库 | 2天 |

**总计：约 18 人天**

### 与模板系统的关系

当前模板系统（v2.0）采用的是「示例文档驱动」的设计：
- 用户上传示例报告 → 标记变量 → 配置提取规则 → 生成新报告

规则系统与模板系统的区别：
- **模板系统**：侧重于「变量提取」和「文档生成」，规则相对简单
- **规则系统**：侧重于「复杂计算链」和「多节点关联」，支持 AI 调用

两者可以协同工作：
- 模板变量的 `extract_type` 可以调用规则系统
- 规则系统的输出可以作为模板变量的数据来源

---

## 📁 项目结构

```
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 集成服务
├── extract-service/        # 模板系统服务（v2.0）
│   ├── entity/             # Template, SourceFile, Variable, Generation
│   ├── repository/         # 4个 Repository
│   └── dto/config/         # VariableLocation, ReferenceSourceConfig
├── notification-service/   # 通知服务
├── gateway-service/        # 网关服务
├── lingyue-starter/        # 单体应用启动器
└── sql/                    # 数据库脚本
    ├── rebuild_all.sh      # 完整重建脚本（支持 --simple）
    ├── all_tables.sql      # 完整表结构（21张表）
    ├── template_tables.sql # 模板系统表（v2.0）
    ├── 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  # 前端交互原型（HTML 版）
└── vue-demo/                 # Vue 3 前端 Demo（可作为正式前端参考）
    ├── src/
    │   ├── api/              # API 封装（axios）
    │   │   └── index.js      # templateApi, authApi, generationApi 等
    │   ├── assets/
    │   │   └── main.scss     # 全局样式（变量高亮颜色等）
    │   ├── router/
    │   │   └── index.js      # 路由配置 + 登录守卫
    │   ├── stores/
    │   │   └── template.js   # Pinia 状态管理
    │   └── views/
    │       ├── Login.vue           # 登录页
    │       ├── Register.vue        # 注册页
    │       ├── Home.vue            # 首页（统计卡片）
    │       ├── Templates.vue       # 模板列表
    │       ├── TemplateDetail.vue  # 模板详情
    │       ├── Editor.vue          # 模板编辑器（变量标记）
    │       ├── Generations.vue     # 生成任务列表
    │       └── GenerationDetail.vue # 生成任务详情
    ├── vite.config.js        # Vite 配置（API 代理）
    └── package.json          # 依赖配置

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 交互原型 | ✅ |
| 前端 Demo | **Vue 3 + Element Plus** | ✅ |
| 前端框架 | **Vue 3 + Element Plus** | ✅ |

---

## 🖥️ 前端开发参考（Vue Demo）

前端使用 **Vue 3**，`frontend/vue-demo/` 为基础框架，可直接扩展为正式版本：

### 技术栈
- **Vue 3** + Composition API
- **Vite** 构建工具
- **Element Plus** UI 组件库
- **Pinia** 状态管理
- **Vue Router** 路由（含登录守卫）
- **Axios** HTTP 客户端
- **Sass** 样式预处理

### 已实现功能
| 页面 | 功能 | 文件 |
|------|------|------|
| 登录页 | 用户名/邮箱+密码登录、记住我 | `Login.vue` |
| 注册页 | 用户名/邮箱/密码注册、表单验证 | `Register.vue` |
| 首页 | 统计卡片（从API获取）、推荐模板 | `Home.vue` |
| 模板列表 | 搜索筛选、创建/编辑/删除模板 | `Templates.vue` |
| 模板详情 | 模板信息、变量列表、来源文件 | `TemplateDetail.vue` |
| 编辑器 | 变量标记、分类管理、右键菜单 | `Editor.vue` |
| 生成任务列表 | 任务状态、执行/确认/下载 | `Generations.vue` |
| 生成任务详情 | 变量提取结果、编辑确认 | `GenerationDetail.vue` |

### API 封装
```javascript
// 模板 API
templateApi.list(page, size)
templateApi.getById(id)
templateApi.create(data)
templateApi.update(id, data)
templateApi.delete(id)
templateApi.publish(id)
templateApi.getStats()

// 认证 API
authApi.login({ usernameOrEmail, password })
authApi.register({ username, email, password, confirmPassword })
authApi.logout()
authApi.getCurrentUser()

// 变量 API
variableApi.list(templateId)
variableApi.listGrouped(templateId)
variableApi.add(templateId, data)

// 生成任务 API
generationApi.list()
generationApi.create(data)
generationApi.execute(id)
generationApi.confirm(id)
```

### 启动方式
```bash
cd frontend/vue-demo
yarn install
yarn dev

# 连接远程服务器
API_SERVER=http://47.101.133.94:18520 yarn dev
```

### 变量类别配色（与后端 Variable.category 对应）
```scss
.entity   { background: rgba(24, 144, 255, 0.15); }  // 蓝色 - 核心实体
.concept  { background: rgba(114, 46, 209, 0.15); }  // 紫色 - 概念/技术
.data     { background: rgba(82, 196, 26, 0.15); }   // 绿色 - 数据/指标
.location { background: rgba(250, 173, 20, 0.15); }  // 橙色 - 地点/组织
.asset    { background: rgba(235, 47, 150, 0.15); }  // 粉色 - 资源模板
```

---

## 📅 里程碑

- **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 | **批量获取值** | ✅ |

### 模板系统（extract-service）

| 接口 | 方法 | 说明 | 状态 |
|------|------|------|------|
| `/api/v1/templates` | POST | 创建模板 | ✅ |
| `/api/v1/templates/{id}` | GET | 获取模板详情 | ✅ |
| `/api/v1/templates` | GET | 模板列表 | ✅ |
| `/api/v1/templates/{id}` | PUT | 更新模板 | ✅ |
| `/api/v1/templates/{id}` | DELETE | 删除模板 | ✅ |
| `/api/v1/templates/{id}/publish` | POST | 发布模板 | ✅ |
| `/api/v1/templates/{id}/archive` | POST | 归档模板 | ✅ |
| `/api/v1/templates/{id}/duplicate` | POST | 复制模板 | ✅ |
| `/api/v1/templates/{id}/source-files` | POST | 添加来源文件定义 | ✅ |
| `/api/v1/templates/{id}/source-files` | GET | 获取来源文件列表 | ✅ |
| `/api/v1/templates/{id}/variables` | POST | 添加变量 | ✅ |
| `/api/v1/templates/{id}/variables` | GET | 获取变量列表 | ✅ |
| `/api/v1/templates/{id}/variables/grouped` | GET | **变量按类别分组** | ✅ |
| `/api/v1/templates/variables/{id}/preview` | POST | 预览提取结果 | ✅ |

### 生成任务（extract-service）

| 接口 | 方法 | 说明 | 状态 |
|------|------|------|------|
| `/api/v1/generations` | POST | 创建生成任务 | ✅ |
| `/api/v1/generations/{id}` | GET | 获取任务详情 | ✅ |
| `/api/v1/generations` | GET | 获取任务列表 | ✅ |
| `/api/v1/generations/{id}/execute` | POST | 执行变量提取 | ✅ |
| `/api/v1/generations/{id}/progress` | GET | 获取执行进度 | ✅ |
| `/api/v1/generations/{id}/variables/{varName}` | PUT | 修改变量值 | ✅ |
| `/api/v1/generations/{id}/confirm` | POST | 确认并生成文档 | ✅ |
| `/api/v1/generations/{id}/download` | GET | 下载生成文档 | ✅ |

---

## 🗄️ 数据库表清单（21张）

### 基础模块
| 表名 | 说明 | 状态 |
|------|------|------|
| `users` | 用户表 | ✅ |
| `documents` | 文档表 | ✅ |
| `elements` | 要素表 | ✅ |
| `annotations` | 批注表 | ✅ |
| `graphs` | 关系网络表 | ✅ |
| `parse_tasks` | 解析任务（多阶段进度）| ✅ |
| `sessions` | 会话表 | ✅ |

### 图谱模块
| 表名 | 说明 | 状态 |
|------|------|------|
| `graph_nodes` | 图节点（NER实体）| ✅ |
| `graph_relations` | 图关系 | ✅ |

### 补充模块
| 表名 | 说明 | 状态 |
|------|------|------|
| `rules` | 规则表 | ✅ |
| `data_sources` | 数据源表 | ✅ |
| `text_storage` | 文本存储 | ✅ |

### RAG 模块
| 表名 | 说明 | 状态 |
|------|------|------|
| `text_chunks` | 文本分块 | ✅ |
| `vector_embeddings` | 向量嵌入（pgvector）| ✅ |

### 文档结构化模块
| 表名 | 说明 | 状态 |
|------|------|------|
| `document_blocks` | 文档块（TextElement）| ✅ |
| `document_entities` | 文档实体标注 | ✅ |
| `document_elements` | 文档结构化元素 | ✅ |

### 模板系统 v2.0（新增）
| 表名 | 说明 | 状态 |
|------|------|------|
| `templates` | 报告模板 | ✅ |
| `source_files` | 来源文件定义 | ✅ |
| `variables` | 模板变量 | ✅ |
| `generations` | 生成任务 | ✅ |