Document 功能设计与实现

功能概述

在现有的 file 模块基础上，扩展实现 Document 的完整 CRUD（创建、读取、更新、删除）功能，支持对文档的增删改查操作，与 Chroma 向量数据库集成，为 RAG 系统提供文档管理能力。

设计目标

1. 实现 Document 的增删改查功能
2. 与 Chroma 向量数据库深度集成
3. 支持文档元数据管理
4. 与现有 file 模块无缝集成
5. 支持多租户环境下的文档隔离

技术方案

1. 服务架构

DocumentService
├── ChromaClient (外部依赖)
├── DocumentRepository (数据持久化)
├── DocumentController (API 接口)
└── FileService (文档解析)

2. 核心功能

2.1 创建 Document (ADD)

• 接收上传的文件
• 解析文件内容（使用现有 FileService）
• 将文档内容存储到 Chroma 向量数据库
• 在本地数据库记录文档元数据
• 支持批量上传

2.2 查询 Document (QUERY)

• 支持基于文本内容的相似性搜索
• 支持基于元数据的过滤查询
• 支持分页和排序
• 支持高亮显示匹配内容

2.3 删除 Document (DELETE)

• 根据 ID 删除指定文档
• 同时从 Chroma 和本地数据库中删除
• 支持批量删除
• 支持软删除和硬删除两种模式

3. 数据模型

3.1 Document 实体

interface Document {
  id: string;              // 唯一标识
  title: string;           // 文档标题
  content: string;         // 文档内容
  tenantId: string;        // 租户 ID
  collectionId: string;    // 所属 Collection ID
  filename: string;        // 原始文件名
  filetype: string;        // 文件类型 (markdown, text等)
  wordCount: number;       // 字数统计
  charCount: number;       // 字符数统计
  createdAt: Date;         // 创建时间
  updatedAt: Date;         // 更新时间
  status: 'active' | 'deleted'; // 状态
  chromaDocumentId: string;     // Chroma 中的实际 ID
  metadata?: Record<string, any>; // 元数据
  tags?: string[];         // 标签
}

4. API 接口设计

4.1 上传并创建 Document

POST /api/v1/documents
Content-Type: multipart/form-data

Form Data:
- file: 文件内容
- collectionId: 所属 Collection ID
- title: 文档标题（可选）
- tags: 标签（可选，JSON数组）
- metadata: 元数据（可选，JSON对象）

Response:
{
  "id": "uuid",
  "title": "文档标题",
  "filename": "example.md",
  "filetype": "markdown",
  "wordCount": 1234,
  "charCount": 5678,
  "chromaDocumentId": "chroma_uuid",
  "createdAt": "2026-11-14T10:00:00Z",
  ...
}

4.2 查询 Documents 列表

GET /api/v1/documents?collectionId=uuid&page=1&pageSize=10&tags=tag1,tag2

Response:
{
  "list": [...],
  "total": 100,
  "page": 1,
  "pageSize": 10
}

4.3 搜索 Documents 内容

POST /api/v1/documents/search
Content-Type: application/json

{
  "query": "搜索关键词",
  "collectionId": "uuid",
  "limit": 10,
  "filters": {
    "tags": ["tag1", "tag2"],
    "source": "manual.pdf"
  }
}

Response:
{
  "results": [
    {
      "id": "uuid",
      "title": "文档标题",
      "content": "匹配的文档内容片段...",
      "score": 0.85,
      "metadata": { ... }
    }
  ]
}

4.4 获取 Document 详情

GET /api/v1/documents/{id}

Response:
{
  "id": "uuid",
  "title": "文档标题",
  "content": "完整文档内容",
  "filename": "example.md",
  ...
}

4.5 更新 Document

PUT /api/v1/documents/{id}
Content-Type: application/json

{
  "title": "新标题",
  "tags": ["newTag1", "newTag2"],
  "metadata": { "updated": "value" }
}

4.6 删除 Document

DELETE /api/v1/documents/{id}

4.7 批量删除 Documents

DELETE /api/v1/documents
Content-Type: application/json

{
  "ids": ["id1", "id2", "id3"]
}

5. 与现有模块的集成

5.1 复用 FileService

• 使用现有的 方法解析上传文件
• 支持相同的文件类型（.md 等）
• 复用现有的日志和错误处理机制

5.2 与 CollectionService 集成

• Document 必须关联到特定的 Collection
• 创建 Document 时需要指定 Collection ID
• 删除 Collection 时需要处理关联的 Documents

6. 错误处理

• 文件类型不支持
• 文件内容无法解析
• Chroma 服务不可用
• 权限不足
• 数据库操作失败
• Document ID 不存在

7. 安全考虑

• 所有操作需通过 JWT 验证
• 实施多租户数据隔离
• 对敏感操作记录审计日志
• 实现操作频率限制
• 文件内容安全检查

实现计划

第一阶段：基础功能实现（1天）

• 创建 Document 实体和服务
• 实现文档上传和解析功能
• 实现本地数据库存储

第二阶段：Chroma 集成（1天）

• 集成 Chroma 向量数据库
• 实现文档内容的向量化存储
• 实现基础搜索功能

第三阶段：查询和更新功能（1天）

• 实现 Document 查询功能
• 实现 Document 更新功能
• 添加分页和过滤支持

第四阶段：高级功能和优化（1天）

• 实现批量操作
• 添加元数据过滤支持
• 实现缓存机制

第五阶段：集成和测试（1天）

• 与现有 file 模块集成
• 编写单元测试和接口测试
• 进行集成测试

验收标准

1. 能够成功上传、查询、更新、删除 Document
2. 与 Chroma 数据库操作保持同步
3. 支持多租户数据隔离
4. 提供完整的 API 文档
5. 通过所有单元测试和集成测试
6. 性能满足设计要求（查询响应时间 < 500ms）