docs(rag): 补全知识资产与解析设计

前端实现文档/2.知识资产与文件解析模块前端实现.md

@@ -0,0 +1,45 @@
+# 知识资产与文件解析模块前端实现
+
+## 1. 页面
+
+| 页面 | 职责 |
+|------|------|
+| `KnowledgeWorkspacePage.vue` | 展示知识库列表、配置、文档状态和发布影响 |
+| `IngestionPipelinePage.vue` | 展示上传、解析、切片、向量化和任务日志 |
+| 旧 `RagStoresPage.vue` | 保留知识库 CRUD 联调参考 |
+| 旧 `RagDocumentsPage.vue` | 保留知识文档 CRUD 联调参考 |
+
+## 2. 聚合 ViewModel
+
+知识工作台建议使用 `KnowledgeWorkspaceView`：
+
+- 当前知识库基础信息。
+- 文档健康度。
+- Embedding 模型和维度。
+- 检索配置。
+- 文档列表摘要。
+- 待处理任务。
+- 发布影响说明。
+
+文件解析管道建议使用 `IngestionRunView`：
+
+- 上传文件列表。
+- 管道阶段状态。
+- 解析文本预览。
+- 切片预览。
+- 任务日志。
+
+## 3. 接口草案
+
+- `GET /api/knowledge/workspaces/{storeId}`
+- `POST /api/knowledge/ingestion-runs`
+- `GET /api/knowledge/ingestion-runs/{runId}`
+- `POST /api/rag/documents/parse`
+- `POST /api/rag/documents/chunk`
+
+## 4. 交互状态
+
+- 解析失败显示可重试状态。
+- 索引中显示进行中状态，不允许误标为可检索。
+- 切片参数变更后提示需要重建索引。
+- Embedding 模型变更后提示会影响当前知识库向量空间。

后端实现文档/2.知识资产与文件解析模块后端实现.md

@@ -0,0 +1,39 @@
+# 知识资产与文件解析模块后端实现
+
+## 1. 当前实现落点
+
+当前实现位于 `com.bruce.rag`，包含知识库、文档、解析、切片和向量实体。
+
+## 2. Controller
+
+已落地接口继续保留：
+
+- `/api/rag/store/list`
+- `/api/rag/store/query`
+- `/api/rag/store/detail`
+- `/api/rag/store/overview`
+- `/api/rag/store/documentOverview`
+- `/api/rag/documents/query`
+- `/api/rag/documents/batchUpload`
+- `/api/rag/documents/parse`
+- `/api/rag/documents/chunk`
+
+Studio 聚合接口后续新增在知识资产模块，不替代旧接口。
+
+## 3. Service
+
+| Service | 职责 |
+|---------|------|
+| `IRagStoreService` | 知识库 CRUD、概览统计 |
+| `IRagDocumentService` | 文档 CRUD、批量上传 |
+| `IRagDocumentParseService` | 解析状态流转和解析快照 |
+| `IRagDocumentChunkService` | 根据解析快照生成切片 |
+| `IRagChunkEmbeddingService` | 向量写入和召回 |
+
+## 4. 校验规则
+
+- 知识库编码唯一。
+- 文档必须绑定存在的知识库和附件。
+- 只有解析成功的文档允许切片。
+- 向量化必须读取知识库生效模型配置。
+- 重新切片或模型变更后，索引状态必须回到待索引或索引中。

数据库设计/2.知识资产数据库设计.md

@@ -0,0 +1,37 @@
+# 知识资产数据库设计
+
+## 1. 表关系
+
+| 表 | 说明 | 关键关系 |
+|----|------|----------|
+| `rag_store` | 知识库主表 | 独立业务编码 |
+| `rag_document` | 知识文档 | 引用 `rag_store`、`sys_attachment` |
+| `rag_document_parse_result` | 解析快照 | 引用 `rag_store`、`rag_document` |
+| `rag_chunk` | 知识切片 | 引用 `rag_store`、`rag_document` |
+| `rag_chunk_embedding` | 切片向量 | 引用 `rag_store`、`rag_document`、`rag_chunk` |
+| `rag_store_model_config` | 知识库模型配置 | 引用 `rag_store`、`model_config` |
+
+## 2. 脚本清单
+
+- `script/sql/rag_store.sql`
+- `script/sql/rag_document.sql`
+- `script/sql/rag_document_parse_result.sql`
+- `script/sql/rag_chunk.sql`
+- `script/sql/rag_chunk_embedding.sql`
+- `docs/MODEL_PROVIDER_SCHEMA.sql` 中的 `rag_store_model_config`
+
+## 3. 枚举组
+
+| catalog | type | Java 枚举 |
+|---------|------|-----------|
+| `rag` | `parse_status` | `RagParseStatusEnum` |
+| `rag` | `index_status` | `RagIndexStatusEnum` |
+| `rag` | `chunk_strategy` | `RagChunkStrategyEnum` |
+
+## 4. 一致性要求
+
+- `rag_document.attachment_id` 保持唯一，避免一个附件重复建档。
+- `rag_document_parse_result.document_id` 保持唯一，表示一个文档一个当前解析快照。
+- `rag_chunk` 使用 `(document_id, chunk_index)` 保证同文档切片序号唯一。
+- `rag_chunk_embedding` 使用 `(chunk_id, embedding_model)` 防止同模型重复写入。
+- RAG 现有脚本与本文档一致，本轮不调整 `sys_enum` 格式。

设计文档/2.知识资产与文件解析模块设计.md

@@ -0,0 +1,44 @@
+# 知识资产与文件解析模块设计
+
+## 1. 领域模型
+
+| 对象 | 职责 |
+|------|------|
+| 知识库 | 聚合文档、模型配置、检索配置和索引版本 |
+| 知识文档 | 关联附件，维护解析和索引状态 |
+| 解析快照 | 保存文本抽取结果，作为切片输入 |
+| 知识切片 | 保存切片内容、序号、元数据和启用状态 |
+| 切片向量 | 保存 Embedding 向量、模型名和维度 |
+| 知识库模型配置 | 固定知识库 Embedding 模型和切片配置 |
+
+## 2. 状态流转
+
+文档解析状态：
+
+`UPLOADED -> PARSING -> PARSED`，失败时进入 `FAILED`。
+
+文档索引状态：
+
+`PENDING -> INDEXING -> INDEXED`，失败时进入 `FAILED`。
+
+切片策略继续使用整型枚举值，例如 `1` 表示固定长度，`5` 表示按分隔符。
+
+## 3. 数据流
+
+```mermaid
+flowchart LR
+    Upload["上传文件"] --> Attachment["sys_attachment"]
+    Attachment --> Document["rag_document"]
+    Document --> Parse["rag_document_parse_result"]
+    Parse --> Chunk["rag_chunk"]
+    Chunk --> Embedding["rag_chunk_embedding"]
+    Embedding --> Retrieval["检索召回"]
+```
+
+## 4. 设计约束
+
+- `rag_document` 只引用附件和知识库，不存储大段解析文本。
+- 解析快照按文档唯一，重新解析时更新快照。
+- `rag_chunk_embedding` 必须记录模型和维度，防止向量空间混用。
+- 知识库模型配置由模型与路由模块维护，但知识资产模块负责消费。
+- 检索配置要面向 Workflow 和 Agent 复用，不绑定某一个页面。

需求分析/2.知识资产与文件解析模块需求.md

@@ -0,0 +1,36 @@
+# 知识资产与文件解析模块需求
+
+## 1. 模块目标
+
+知识资产与文件解析模块负责把外部文件变成可检索知识资产，覆盖知识库维护、文件上传、文本解析、切片、向量化和索引状态管理。
+
+## 2. 核心场景
+
+1. 知识维护者创建知识库并批量上传文档。
+2. 系统保存附件元数据并创建 `rag_document`。
+3. 文档解析管道抽取文本并保存解析快照。
+4. 用户选择切片策略生成 `rag_chunk`。
+5. 系统调用 Embedding 模型写入 `rag_chunk_embedding`。
+6. 知识库达到可检索状态后供 Workflow 和 Agent 调用。
+
+## 3. 功能需求
+
+- 知识库支持新增、编辑、删除、查询和概览统计。
+- 文档支持上传、解析、解析失败重试、切片和索引状态查看。
+- 解析结果必须落到 `rag_document_parse_result`，切片不能直接依赖原始附件。
+- 同一文档重新切片时，必须替换旧切片并推动索引重建。
+- 知识库必须绑定稳定的 Embedding 模型和向量维度。
+- 前端需要展示文档健康度、解析失败数、待向量化任务数和发布影响。
+
+## 4. 验收标准
+
+- 能从知识库视角看到文档数量、解析状态、索引状态和切片数量。
+- 能从文件解析管道看到上传、解析、切片、向量化、可检索的阶段。
+- 枚举值与现有 `RagParseStatusEnum`、`RagIndexStatusEnum`、`RagChunkStrategyEnum` 一致。
+
+## 5. 关联资料
+
+- 表：`rag_store`、`rag_document`、`rag_document_parse_result`、`rag_chunk`、`rag_chunk_embedding`、`rag_store_model_config`
+- 枚举：`rag/parse_status`、`rag/index_status`、`rag/chunk_strategy`
+- 脚本：`script/sql/rag_store.sql`、`script/sql/rag_document.sql`、`script/sql/rag_document_parse_result.sql`、`script/sql/rag_chunk.sql`、`script/sql/rag_chunk_embedding.sql`
+- 前端原型：`KnowledgeWorkspacePage.vue`、`IngestionPipelinePage.vue`