docs(agent): 同步 RAG 当前能力文档

docs/ARCHITECTURE.md

@@ -40,6 +40,7 @@
 - 全局异常处理 `GlobalExceptionHandler`。
 - MyBatis-Plus 审计自动填充 `EntityAuditMetaObjectHandler`。
 - 附件本地存储配置 `AttachmentProperties`。
+- 文档解析抽象与 Apache Tika 解析实现。
 - 系统枚举管理能力（CRUD + 批量新增 + 管理端查询）。
 - 附件上传能力（本地磁盘 + 元数据持久化）。
 
@@ -58,6 +59,11 @@
 | SysAttachmentController | `common/controller/SysAttachmentController.java` |
 | SysEnumServiceImpl | `common/service/impl/SysEnumServiceImpl.java` |
 | SysAttachmentServiceImpl | `common/service/impl/SysAttachmentServiceImpl.java` |
+| DocumentParserFactory | `common/document/parse/DocumentParserFactory.java` |
+| TxtDocumentParser | `common/document/parse/impl/TxtDocumentParser.java` |
+| PdfDocumentParser | `common/document/parse/impl/PdfDocumentParser.java` |
+| WordDocumentParser | `common/document/parse/impl/WordDocumentParser.java` |
+| ExcelDocumentParser | `common/document/parse/impl/ExcelDocumentParser.java` |
 | CommonStatusEnum | `common/enums/CommonStatusEnum.java` |
 | EnableStatusEnum | `common/enums/EnableStatusEnum.java` |
 
@@ -80,7 +86,8 @@
 
 - 维护 RAG 知识库主数据（CRUD + 编码唯一性校验）。
 - 维护知识库文档与附件的关联关系。
-- 定义解析状态、索引状态和 RAG 相关来源常量。
+- 支持知识文档批量上传、解析入口和解析状态流转。
+- 定义切片、向量、解析状态、索引状态和 RAG 相关来源常量。
 
 关键类：
 
@@ -88,28 +95,42 @@
 |----|------|
 | RagStore | `rag/entity/RagStore.java` |
 | RagDocument | `rag/entity/RagDocument.java` |
+| RagChunk | `rag/entity/RagChunk.java` |
+| RagChunkEmbedding | `rag/entity/RagChunkEmbedding.java` |
 | RagStoreController | `rag/controller/RagStoreController.java` |
 | RagDocumentController | `rag/controller/RagDocumentController.java` |
 | RagStoreServiceImpl | `rag/service/impl/RagStoreServiceImpl.java` |
 | RagDocumentServiceImpl | `rag/service/impl/RagDocumentServiceImpl.java` |
+| RagDocumentParseServiceImpl | `rag/service/impl/RagDocumentParseServiceImpl.java` |
 | RagParseStatusEnum | `rag/enums/RagParseStatusEnum.java` |
 | RagIndexStatusEnum | `rag/enums/RagIndexStatusEnum.java` |
+| RagChunkStrategyEnum | `rag/enums/RagChunkStrategyEnum.java` |
 | RagSystemConstants | `rag/constant/RagSystemConstants.java` |
 
 接口列表：
 
 | 方法 | 路径 | 说明 |
 |------|------|------|
+| POST | `/api/rag/store/list` | 查询全部知识库 |
 | POST | `/api/rag/store/query` | 知识库条件查询 |
 | GET | `/api/rag/store/detail` | 获取知识库详情 |
+| GET | `/api/rag/store/overview` | 获取知识库总览 |
+| GET | `/api/rag/store/documentOverview` | 获取单个知识库文档概览 |
 | POST | `/api/rag/store/save` | 新增/更新知识库 |
 | POST | `/api/rag/store/delete` | 删除知识库 |
+| POST | `/api/rag/documents/list` | 查询全部知识文档 |
 | POST | `/api/rag/documents/query` | 知识文档条件查询 |
+| GET | `/api/rag/documents/detail` | 获取知识文档详情 |
+| POST | `/api/rag/documents/save` | 新增/更新知识文档 |
+| POST | `/api/rag/documents/delete` | 删除知识文档 |
+| POST | `/api/rag/documents/batchUpload` | 批量上传文档并创建 `rag_document` |
+| POST | `/api/rag/documents/parse` | 批量解析知识文档 |
 
 当前边界：
 
-- 元数据管理层已完成（知识库 CRUD、文档查询）。
-- 尚未实现"文档上传后自动建档"、"解析入库"、"切片向量化"、"检索问答"等业务流程。
+- 知识库 CRUD、文档 CRUD、批量上传、Tika 文本解析和状态流转已完成。
+- 解析结果当前只返回给调用方并更新文档状态，尚未写入 `rag_chunk`。
+- `rag_chunk`、`rag_chunk_embedding` 的结构层已就绪，尚未实现切片生成、向量化、索引任务和检索问答。
 
 ## 4. 数据模型关系
 
@@ -121,8 +142,10 @@
 | `sys_attachment` | 附件元数据 | 独立，被 rag_document 引用 |
 | `rag_store` | 知识库主表 | 独立 |
 | `rag_document` | 知识库文档表 | 关联 `rag_store.id` 和 `sys_attachment.id` |
+| `rag_chunk` | 知识切片表 | 关联 `rag_store.id` 和 `rag_document.id` |
+| `rag_chunk_embedding` | 切片向量表 | 关联 `rag_store.id`、`rag_document.id` 和 `rag_chunk.id` |
 
-`rag_document` 是 RAG 模块与附件模块的连接点。
+`rag_document` 是 RAG 模块与附件模块的连接点，`rag_chunk` 和 `rag_chunk_embedding` 是下一步检索链路的核心落点。
 
 ## 5. 配置与运行
 
@@ -141,15 +164,15 @@
 
 ## 7. 当前不足
 
-- RAG 尚未进入"可用链路"，只有元数据管理层。
+- RAG 尚未进入"可检索链路"，当前完成上传与解析，但未完成切片、向量化和召回。
 - Agent 运行时相关模型与服务尚未开始建设。
-- 前端部分页面（工作台、附件管理、知识文档）为占位状态。
+- 前端部分页面（工作台、附件管理、检索配置、最近任务）为占位或后续能力提示。
 - 缺少鉴权、租户、操作日志。
 
 ## 8. 建议演进方向
 
-1. 补 RAG 最小闭环：上传附件 → 建立文档 → 状态流转 → 解析占位。
+1. 补 RAG 最小检索闭环：解析文本 → 生成切片 → 生成向量 → 检索召回。
 2. 接入 Spring AI，实现最小模型调用链路。
 3. 建设 Agent 域模型：Agent、Session、Message、Tool、Task。
-4. 补齐前端占位页面的表单与联调。
-5. 衔接模型供应商、工作流编排和前端管理台。
+4. 补齐索引任务、重试、重建索引和前端任务视图。
+5. 衔接模型供应商、工作流编排和前端管理台。

docs/ROADMAP.md

@@ -1,6 +1,6 @@
 # Common Agent 开发路线图
 
-本文档基于 2026-05-21 当前分支代码整理，用来区分"已经完成""建议优先做""中期建设项"。
+本文档基于 2026-05-24 当前分支代码整理，用来区分"已经完成""建议优先做""中期建设项"。
 
 ## 已完成
 
@@ -9,6 +9,7 @@
 - Spring Boot 4.0.6 后端工程初始化。
 - PostgreSQL 数据源与多环境配置文件（dev / template）。
 - MyBatis-Plus 3.5.16、Lombok、Springdoc OpenAPI 2.8.13 已接入。
+- Apache Tika 3.2.3 已接入，用于文档文本抽取。
 - Maven Wrapper。
 
 ### 公共能力
@@ -18,6 +19,8 @@
 - `RequestResult<T>` 统一 API 返回体。
 - `GlobalExceptionHandler` 全局异常处理。
 - `AttachmentProperties` 附件本地存储配置。
+- 文档解析抽象：`DocumentParser`、`DocumentParserFactory`、`DocumentParseContext`、`DocumentParseResult`。
+- Tika 解析实现：TXT/Markdown/LOG、PDF、Word、Excel。
 - `sys_enum` 完整能力：实体、Mapper、Service、Controller、DTO 层。
   - 支持单条增删改查、批量新增、管理端条件查询（含关键词搜索）。
   - 批量新增内含重复值校验。
@@ -27,10 +30,14 @@
 ### RAG 基础能力
 
 - `rag_store`、`rag_document` 表结构与实体定义。
+- `rag_chunk`、`rag_chunk_embedding` 表结构与实体定义。
 - RAG 知识库完整 CRUD（含编码唯一性校验）。
-- 知识文档条件查询服务。
+- 知识文档完整 CRUD、条件查询、批量上传。
+- 文档解析入口：支持批量提交文档 ID，按切片策略参数发起解析，状态流转为 PARSING / PARSED / FAILED。
+- 知识库总览接口与单库文档概览接口。
 - RAG 解析状态枚举 `RagParseStatusEnum`（UPLOADED / PARSING / PARSED / FAILED）。
 - RAG 索引状态枚举 `RagIndexStatusEnum`（PENDING / INDEXING / INDEXED / FAILED）。
+- RAG 切片策略枚举 `RagChunkStrategyEnum`（FIXED_LENGTH / PARAGRAPH / HEADING / TABLE_ROW / DELIMITER / SEMANTIC）。
 - RAG 来源常量 `RagSystemConstants`。
 
 ### 前端控制台
@@ -38,7 +45,9 @@
 - Vue 3 + TypeScript + Vite + Element Plus + Pinia + Vue Router 工程。
 - `AdminLayout.vue` 管理后台布局（侧边栏菜单 + 主内容区）。
 - 系统枚举管理页：完整 CRUD + 批量新增对话框 + 关键词搜索 + 响应式布局。
-- 知识库管理页：完整 CRUD + 概览卡片 + 双栏详情 + 编辑对话框。
+- 知识库管理页：完整 CRUD + 概览卡片 + 双栏详情 + 编辑对话框 + 批量上传入口。
+- 知识文档管理页：条件查询 + 批量上传 + 批量解析入口 + 编辑/启停用/删除。
+- RAG 文档批量上传组件：支持锁定知识库或选择知识库上传。
 - API 层：Axios 封装 + Long 类型安全解析 + 统一错误拦截。
 - 单元测试：Vitest + @vue/test-utils，覆盖路由、布局、页面和 API。
 
@@ -49,24 +58,24 @@
 
 ## 短期优先级
 
-建议优先完成下面几项，把 RAG 元数据管理层升级为可用的业务闭环：
+建议优先完成下面几项，把 RAG 上传解析链路升级为可检索链路：
 
-1. 知识库文档上传接口：上传文件后自动创建 `rag_document` 记录。
-2. 文档解析任务入口与状态流转。
-3. 向量化任务入口与状态流转。
-4. 知识库文档新增、详情、启停用、重试等管理接口。
-5. 前端附件管理页面联调。
-6. 前端知识文档页面联调。
+1. 切片生成服务：把解析服务拿到的 `DocumentParseResult.text` 改造成可持久化的 `rag_chunk` 记录。
+2. 按 `RagChunkStrategyEnum` 先落地 `FIXED_LENGTH` 和 `DELIMITER`，再扩展段落/标题/表格/语义切片。
+3. 索引任务入口：把文档或知识库的 `indexStatus` 推进为真实状态流转。
+4. 接入 Spring AI Embedding 模型，生成并保存 `rag_chunk_embedding`。
+5. 补齐重建索引、失败重试、最近任务接口。
+6. 前端接入检索配置、最近任务和重建索引动作。
 
 ## RAG 最小闭环
 
-在基础规范层补齐后，当前 RAG 元数据层已完成，下一步建设业务闭环：
+当前上传与解析入口已完成，下一步建设最小检索闭环：
 
-1. 附件上传后自动创建 `rag_document` 记录。
-2. 建立文档解析任务入口（占位解析器）。
-3. 解析状态、索引状态按流程流转。
-4. 接入占位向量化接口。
-5. 提供知识库文档管理完整接口（新增、详情、启停用、重试、删除）。
+1. 批量上传文件，自动创建 `sys_attachment` 与 `rag_document`。
+2. 调用解析入口，使用 Tika 抽取文本并更新 `parseStatus`。
+3. 根据切片策略生成 `rag_chunk`。
+4. 调用 Embedding 模型生成向量并写入 `rag_chunk_embedding`。
+5. 提供检索接口，按 query 向量召回切片并返回引用元数据。
 
 ## Agent 核心能力
 
@@ -98,6 +107,8 @@ RAG 数据链路稳定后，再进入 Agent 主线：
 - 上传接口返回模型：`SysAttachmentResponse`。
 - 枚举查询接口规范：POST `/api/sys-enum/queryForManagement`。
 - RAG 文档状态字段：`parseStatus` + `indexStatus` + `enabled`。
+- RAG 文档批量上传接口：POST `/api/rag/documents/batchUpload`。
+- RAG 文档解析接口：POST `/api/rag/documents/parse`，当前同步解析并返回解析元数据。
 - 大整数 ID 通过 `@JsonSerialize(ToStringSerializer.class)` 输出为字符串。
 
 ## 里程碑
@@ -109,9 +120,9 @@ RAG 数据链路稳定后，再进入 Agent 主线：
 
 ### 里程碑 2：RAG 可演示
 
-- 实现知识库文档上传、建档、状态流转。
-- 预留解析和索引任务接口。
-- 前端知识库页面完整联调。
+- 已完成知识库文档上传、建档、解析状态流转。
+- 下一步完成切片持久化、向量化和检索接口。
+- 前端知识库与知识文档页面已接入当前接口，索引任务和检索配置待接入。
 
 ### 里程碑 3：Agent 最小运行时
 
@@ -119,4 +130,4 @@ RAG 数据链路稳定后，再进入 Agent 主线：
 
 ### 里程碑 4：平台管理化
 
-- 补齐前端占位页面联调与后台配置能力，形成完整平台雏形。
+- 补齐前端占位页面联调与后台配置能力，形成完整平台雏形。