# storage-service

**Repository Path**: bihangju/storage-service

## Basic Information

- **Project Name**: storage-service
- **Description**: 存储模块
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-14
- **Last Updated**: 2026-01-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 多形态存储服务 (Storage Service)

## 项目背景

本模块是「知识治理和RAG效果调优平台」的**多形态存储服务**，负责接收上游 Agent 解析后的文档数据，并将其持久化到合适的存储后端。

### 整体流程定位

```
┌─────────────────────────────────────────────────────────────────────────────────┐
│                           知识治理平台整体流程                                    │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                 │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐    ┌──────────────┐  │
│  │  用户上传     │───▶│  Agent解析    │───▶│ 【本模块】   │───▶│  RAG查询     │  │
│  │  各类文档     │    │  选择解析方式  │    │  多形态存储   │    │  召回服务    │  │
│  └──────────────┘    └──────────────┘    └──────────────┘    └──────────────┘  │
│                                                                                 │
└─────────────────────────────────────────────────────────────────────────────────┘
```

### 本模块职责

- 提供 FastAPI 接口，接收上游传来的 JSON 数据
- 将数据存储到合适的数据库（SeekDB 向量库、MySQL 元数据库）
- 提供查询接口供下游 RAG 引擎调用
- 提供任务状态追踪，支持异步处理和断点续传

---

## 技术架构

### 存储后端

| 组件 | 用途 | 端口 |
|------|------|------|
| **SeekDB** | 向量数据库，存储文档切片和FAQ的向量 | 2881 |
| **MySQL** | 关系数据库，存储元数据、任务状态、配置 | 3308 |

### 数据类型支持

| 数据类型 | 说明 | 存储目标 |
|----------|------|----------|
| `chunk` | 文档切片 | SeekDB 向量库 |
| `faq` | 问答对 | SeekDB 向量库 |
| `table` | 表格数据 | MySQL 结构化表 |

### Collection 命名规则

SeekDB 中的 Collection 按 `{knowledge_base_id}_{data_type}s` 命名：
- `product-kb_chunks` - 存储 chunk 类型
- `product-kb_faqs` - 存储 faq 类型

---

## 快速启动

### 前置要求

- Docker Desktop
- Docker Compose

### 启动服务

```bash
cd backend/app/storage_service

# 启动所有服务
./start.sh start

# 其他命令
./start.sh stop      # 停止服务
./start.sh restart   # 重启服务
./start.sh status    # 查看状态
./start.sh logs      # 查看日志
./start.sh rebuild   # 重新构建
```

### 服务地址

| 服务 | 地址 | 说明 |
|------|------|------|
| API 服务 | http://localhost:8001 | FastAPI 服务 |
| API 文档 | http://localhost:8001/docs | Swagger UI |
| MySQL | localhost:3308 | 元数据库 |
| SeekDB | localhost:2881 | 向量数据库 |

---

## 数据库连接信息

### MySQL（元数据库）

```
Host: localhost
Port: 3308
User: root
Password: storage123
Database: storage_service
```

### SeekDB（向量数据库）

```
Host: localhost
Port: 2881
User: root
Password: (空)
Database: storage_service
```

**注意**：SeekDB 兼容 MySQL 协议，可以用 DataGrip、Navicat 等 MySQL 客户端连接查看数据。

---

## 数据库表设计

### 1. storage_db_config（存储配置表）

存储各数据库后端的连接配置。

| 字段 | 类型 | 说明 |
|------|------|------|
| id | BIGINT | 主键 |
| config_id | VARCHAR(64) | 配置唯一标识 |
| config_name | VARCHAR(128) | 配置名称 |
| db_type | VARCHAR(32) | 数据库类型：seekdb/mysql |
| host | VARCHAR(255) | 主机地址 |
| port | INT | 端口 |
| database_name | VARCHAR(128) | 数据库名 |
| username | VARCHAR(128) | 用户名 |
| password | VARCHAR(512) | 密码（加密存储） |
| extra_config | JSON | 额外配置 |
| is_default | TINYINT | 是否默认配置 |
| status | VARCHAR(32) | 状态：active/inactive |

### 2. storage_knowledge_base（知识库表）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | BIGINT | 主键 |
| kb_id | VARCHAR(64) | 知识库唯一标识 |
| kb_name | VARCHAR(255) | 知识库名称 |
| description | TEXT | 描述 |
| status | VARCHAR(32) | 状态 |

### 3. storage_document（文档表）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | BIGINT | 主键 |
| doc_id | VARCHAR(64) | 文档唯一标识 |
| kb_id | VARCHAR(64) | 关联知识库 |
| group_id | VARCHAR(64) | 文档组ID |
| file_name | VARCHAR(512) | 文件名 |
| data_type | VARCHAR(32) | 数据类型 |
| item_count | INT | 数据项数量 |
| status | VARCHAR(32) | 状态 |
| processed_items | INT | 已处理数量（断点续传） |
| error_message | TEXT | 错误信息 |

### 4. storage_task（任务表）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | BIGINT | 主键 |
| task_id | VARCHAR(64) | 任务唯一标识 |
| kb_id | VARCHAR(64) | 关联知识库 |
| task_type | VARCHAR(32) | 任务类型 |
| status | VARCHAR(32) | 状态：pending/processing/completed/failed |
| total_documents | INT | 总文档数 |
| total_items | INT | 总数据项数 |
| completed_items | INT | 已完成数量 |

---

## API 接口详解

### 1. 数据存储接口

**POST** `/api/v1/storage/ingest`

存储文档数据到知识库。支持多文档、多类型批量存储。

#### 请求参数

```json
{
  "knowledge_base_id": "string",      // 必填，知识库ID
  "task_id": "string",                // 可选，任务ID（不传自动生成）
  "storage_config_id": "string",      // 可选，存储配置ID（不传用默认）
  "documents": [                      // 必填，文档列表
    {
      "doc_id": "string",             // 必填，文档ID
      "file_name": "string",          // 必填，文件名
      "group_id": "string",           // 可选，文档组ID
      "data_type": "chunk|faq|table", // 必填，数据类型
      "items": [...]                  // 必填，数据项列表
    }
  ]
}
```

#### items 结构 - chunk 类型

```json
{
  "item_id": "string",      // 必填，数据项ID
  "content": "string",      // 必填，文本内容
  "metadata": {             // 可选，元数据
    "page": 1,
    "section": "章节名"
  }
}
```

#### items 结构 - faq 类型

```json
{
  "item_id": "string",      // 必填，数据项ID
  "content": "string",      // 必填，问题内容
  "answer": "string",       // 必填，答案内容
  "metadata": {             // 可选，元数据
    "category": "分类"
  }
}
```

#### 响应

```json
{
  "success": true,
  "task_id": "uuid",
  "message": "Storage completed successfully",
  "total_documents": 3,
  "total_items": 10
}
```

#### curl 示例

```bash
curl -X POST 'http://localhost:8001/api/v1/storage/ingest' \
  -H 'Content-Type: application/json' \
  -d '{
    "knowledge_base_id": "product-kb",
    "documents": [
      {
        "doc_id": "doc_001",
        "file_name": "产品手册.pdf",
        "group_id": "manual",
        "data_type": "chunk",
        "items": [
          {
            "item_id": "chunk_001",
            "content": "本产品是一款智能家居控制中心，支持语音控制。",
            "metadata": {"page": 1, "section": "概述"}
          },
          {
            "item_id": "chunk_002",
            "content": "设备支持WiFi和蓝牙双模连接。",
            "metadata": {"page": 2, "section": "规格"}
          }
        ]
      },
      {
        "doc_id": "doc_002",
        "file_name": "FAQ.pdf",
        "data_type": "faq",
        "items": [
          {
            "item_id": "faq_001",
            "content": "如何连接WiFi？",
            "answer": "打开APP，进入设置，选择WiFi配置。",
            "metadata": {"category": "连接问题"}
          }
        ]
      }
    ]
  }'
```

**单行版本（避免JSON解析问题）：**

```bash
curl -X POST 'http://localhost:8001/api/v1/storage/ingest' -H 'Content-Type: application/json' -d '{"knowledge_base_id":"product-kb","documents":[{"doc_id":"doc_001","file_name":"产品手册.pdf","group_id":"manual","data_type":"chunk","items":[{"item_id":"chunk_001","content":"本产品是一款智能家居控制中心，支持语音控制。","metadata":{"page":1,"section":"概述"}},{"item_id":"chunk_002","content":"设备支持WiFi和蓝牙双模连接。","metadata":{"page":2,"section":"规格"}}]},{"doc_id":"doc_002","file_name":"FAQ.pdf","data_type":"faq","items":[{"item_id":"faq_001","content":"如何连接WiFi？","answer":"打开APP，进入设置，选择WiFi配置。","metadata":{"category":"连接问题"}}]}]}'
```

---

### 2. 向量查询接口

**POST** `/api/v1/storage/search/vector`

基于向量相似度查询文档。

#### 请求参数

```json
{
  "knowledge_base_id": "string",  // 必填，知识库ID
  "query": "string",              // 必填，查询文本
  "top_k": 10,                    // 可选，返回数量，默认10
  "data_type": "chunk|faq"        // 可选，数据类型过滤
}
```

#### 响应

```json
{
  "success": true,
  "query": "查询文本",
  "total": 5,
  "results": [
    {
      "item_id": "doc_001_chunk_001",
      "content": "文档内容...",
      "score": 0.89,
      "data_type": "chunk",
      "doc_id": "doc_001",
      "file_name": "产品手册.pdf",
      "metadata": {
        "page": 1,
        "section": "概述"
      },
      "answer": null
    }
  ]
}
```

#### curl 示例

```bash
# 查询 chunk
curl -X POST 'http://localhost:8001/api/v1/storage/search/vector' \
  -H 'Content-Type: application/json' \
  -d '{"knowledge_base_id":"product-kb","query":"如何语音控制","top_k":5,"data_type":"chunk"}'

# 查询 FAQ
curl -X POST 'http://localhost:8001/api/v1/storage/search/vector' \
  -H 'Content-Type: application/json' \
  -d '{"knowledge_base_id":"product-kb","query":"WiFi连不上","top_k":3,"data_type":"faq"}'
```

---

### 4. 查询文档切片接口

**GET** `/api/v1/storage/documents/{doc_id}/items`

查询文档的所有切片，按顺序返回，支持分页。

#### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| doc_id | string | 是 | 文档ID（路径参数） |
| page | int | 否 | 页码，从1开始，默认1 |
| page_size | int | 否 | 每页数量，默认20，最大100 |

#### 响应

```json
{
  "doc_id": "doc_001",
  "file_name": "产品手册.pdf",
  "data_type": "chunk",
  "total_items": 50,
  "page": 1,
  "page_size": 20,
  "items": [
    {
      "item_id": "chunk_001",
      "content": "这是第一个切片的内容...",
      "metadata": {"page": 1, "section": "概述"},
      "answer": null
    },
    {
      "item_id": "chunk_002",
      "content": "这是第二个切片的内容...",
      "metadata": {"page": 2, "section": "规格"},
      "answer": null
    }
  ]
}
```

#### curl 示例

```bash
# 查询第1页
curl 'http://localhost:8001/api/v1/storage/documents/doc_001/items?page=1&page_size=20'

# 查询第2页
curl 'http://localhost:8001/api/v1/storage/documents/doc_001/items?page=2&page_size=20'
```

---

### 5. 查询知识库所有文档及切片

**GET** `/api/v1/storage/knowledge-bases/{kb_id}/items`

查询知识库下所有文档，每个文档包含其切片列表。

#### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| kb_id | string | 是 | 知识库ID（路径参数） |
| include_items | bool | 否 | 是否包含切片内容，默认true |
| page | int | 否 | 页码，从1开始，默认1 |
| page_size | int | 否 | 每页文档数量，默认10，最大50 |

#### 响应

```json
{
  "kb_id": "product-kb",
  "total_documents": 5,
  "page": 1,
  "page_size": 10,
  "documents": [
    {
      "doc_id": "doc_001",
      "file_name": "产品手册.pdf",
      "data_type": "chunk",
      "status": "completed",
      "item_count": 50,
      "items": [
        {
          "item_id": "chunk_001",
          "content": "切片内容...",
          "metadata": {"page": 1},
          "answer": null
        }
      ]
    },
    {
      "doc_id": "doc_002",
      "file_name": "FAQ.pdf",
      "data_type": "faq",
      "status": "completed",
      "item_count": 10,
      "items": [
        {
          "item_id": "faq_001",
          "content": "如何重置密码？",
          "metadata": {"category": "账户"},
          "answer": "点击忘记密码..."
        }
      ]
    }
  ]
}
```

#### curl 示例

```bash
# 查询所有文档及切片
curl 'http://localhost:8001/api/v1/storage/knowledge-bases/product-kb/items?include_items=true&page=1&page_size=10'

# 只查询文档列表，不包含切片
curl 'http://localhost:8001/api/v1/storage/knowledge-bases/product-kb/items?include_items=false'
```

---

### 6. 修改切片内容

**PUT** `/api/v1/storage/items/{item_id}`

修改单个切片的内容和元数据。修改后会重新生成向量。

#### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| item_id | string | 是 | 切片ID（路径参数，格式：{doc_id}_{item_id}） |

#### 请求体

```json
{
  "content": "更新后的内容",
  "metadata": {
    "page": 2,
    "updated": true,
    "update_time": "2026-01-07"
  }
}
```

#### 响应

```json
{
  "success": true,
  "item_id": "doc_001_chunk_001",
  "message": "Item updated successfully"
}
```

#### curl 示例

```bash
# 修改切片内容
curl -X PUT 'http://localhost:8001/api/v1/storage/items/doc_001_chunk_001' \
  -H 'Content-Type: application/json' \
  -d '{
    "content": "这是修改后的内容，更加准确和详细。",
    "metadata": {"page": 1, "updated": true}
  }'

# 只修改元数据
curl -X PUT 'http://localhost:8001/api/v1/storage/items/doc_001_chunk_001' \
  -H 'Content-Type: application/json' \
  -d '{
    "metadata": {"reviewed": true, "reviewer": "张三"}
  }'
```

---

### 3. 健康检查接口

**GET** `/health`

```bash
curl http://localhost:8001/health
```

响应：
```json
{
  "status": "healthy",
  "service": "storage-service"
}
```

---

### 7. 任务状态查询

**GET** `/api/v1/storage/tasks/{task_id}`

```bash
curl http://localhost:8001/api/v1/storage/tasks/your-task-id
```

响应：
```json
{
  "task_id": "uuid",
  "kb_id": "product-kb",
  "status": "completed",
  "total_documents": 3,
  "total_items": 10,
  "completed_items": 10,
  "failed_documents": 0
}
```

---

## 存储流程说明

### 1. 数据存储流程

```
请求进入
    │
    ▼
┌─────────────────────────────────┐
│ 1. 解析请求，获取 knowledge_base_id │
└─────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────┐
│ 2. 创建任务记录（MySQL）          │
└─────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────┐
│ 3. 遍历 documents                │
│    - 根据 data_type 选择 Handler │
│    - chunk → ChunkHandler       │
│    - faq → FAQHandler           │
│    - table → TableHandler       │
└─────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────┐
│ 4. Handler 处理                  │
│    - 生成 collection 名称        │
│    - 调用 get_or_create_collection │
│    - 存储数据到 SeekDB           │
└─────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────┐
│ 5. 更新任务状态（MySQL）          │
└─────────────────────────────────┘
    │
    ▼
返回结果
```

### 2. Collection 自动创建逻辑

```python
async def get_or_create_collection(name):
    # 1. 先尝试获取已存在的 collection
    try:
        collection = client.get_collection(name)
        return collection
    except:
        pass
    
    # 2. 不存在则创建新的
    collection = client.create_collection(name)
    return collection
```

---

## 目录结构

```
backend/app/storage_service/
├── main.py                 # FastAPI 应用入口
├── Dockerfile              # Docker 构建文件
├── docker-compose.yml      # Docker Compose 配置
├── start.sh                # 启动脚本
├── core/
│   ├── config.py           # 配置管理
│   └── database.py         # 数据库连接
├── models/                 # SQLAlchemy 模型
│   ├── db_config.py
│   ├── knowledge_base.py
│   ├── document.py
│   └── task.py
├── schemas/                # Pydantic 模型
│   ├── ingest.py
│   ├── search.py
│   └── enums.py
├── routers/                # API 路由
│   ├── ingest.py
│   ├── search.py
│   └── config.py
├── services/               # 业务逻辑
│   ├── ingest_service.py
│   └── config_service.py
├── handlers/               # 数据类型处理器
│   ├── base.py
│   ├── chunk_handler.py
│   ├── faq_handler.py
│   └── handler_factory.py
└── connectors/             # 数据库连接器
    ├── base.py
    ├── seekdb_connector.py
    ├── mysql_connector.py
    └── connector_manager.py
```

---

## 扩展指南

### 添加新的数据类型

1. 在 `schemas/enums.py` 添加新的 DataType
2. 创建新的 Handler（继承 BaseHandler）
3. 在 `handlers/handler_factory.py` 注册新 Handler

### 添加新的存储后端

1. 创建新的 Connector（继承 BaseConnector）
2. 在 `connectors/connector_manager.py` 注册
3. 在 `schemas/enums.py` 添加新的 DBType

---

## 常见问题

### Q: 服务启动后连接 MySQL 失败？

A: MySQL 容器启动需要时间，等待几秒后重启 storage-service：
```bash
./start.sh restart
```

### Q: 如何查看 SeekDB 中的数据？

A: 用 MySQL 客户端连接 localhost:2881，SeekDB 兼容 MySQL 协议。

### Q: 如何清空所有数据重新开始？

A: 
```bash
./start.sh stop
docker volume rm storage_service_mysql_data storage_service_seekdb_data
./start.sh start
```

---

## 版本信息

- 版本：1.0.0
- Python：3.11
- FastAPI：0.109.0
- SeekDB：latest
- MySQL：8.0

---

## 完整测试案例

以下是一个完整的端到端测试流程，包含复杂场景的 curl 命令。

### 1. 健康检查

```bash
curl http://localhost:8001/health
```

**预期返回：**
```json
{"status":"healthy","service":"storage-service"}
```

---

### 2. 存储数据 - 复杂场景（多文档、多类型）

```bash
curl -X POST 'http://localhost:8001/api/v1/storage/ingest' \
  -H 'Content-Type: application/json' \
  -d '{
    "knowledge_base_id": "product-kb-2024",
    "documents": [
      {
        "doc_id": "manual_v1",
        "file_name": "产品使用手册V1.0.pdf",
        "group_id": "manuals",
        "data_type": "chunk",
        "items": [
          {"item_id": "ch_001", "content": "第一章：产品概述。本产品是一款智能家居控制中心，支持语音控制、手机APP远程操控。", "metadata": {"page": 1, "chapter": "概述"}},
          {"item_id": "ch_002", "content": "第二章：安装指南。请将设备放置在WiFi信号良好的位置，避免金属遮挡。", "metadata": {"page": 5, "chapter": "安装"}},
          {"item_id": "ch_003", "content": "第三章：功能说明。设备支持定时开关、场景联动、语音唤醒等功能。", "metadata": {"page": 10, "chapter": "功能"}},
          {"item_id": "ch_004", "content": "第四章：故障排除。如设备无法连接，请检查WiFi密码是否正确，或尝试重启路由器。", "metadata": {"page": 15, "chapter": "故障排除"}},
          {"item_id": "ch_005", "content": "第五章：技术规格。工作电压：DC 5V，功耗：≤5W，工作温度：0-40℃。", "metadata": {"page": 20, "chapter": "规格"}}
        ]
      },
      {
        "doc_id": "faq_v1",
        "file_name": "常见问题解答.pdf",
        "group_id": "support",
        "data_type": "faq",
        "items": [
          {"item_id": "faq_001", "content": "设备无法连接WiFi怎么办？", "answer": "1. 确认WiFi密码正确；2. 检查路由器是否支持2.4GHz；3. 重启设备和路由器；4. 将设备靠近路由器重试。", "metadata": {"category": "连接问题", "priority": "high"}},
          {"item_id": "faq_002", "content": "如何重置设备到出厂设置？", "answer": "长按设备背面的RESET按钮10秒，听到提示音后松开，设备将自动重启并恢复出厂设置。", "metadata": {"category": "设备操作", "priority": "medium"}},
          {"item_id": "faq_003", "content": "语音控制不灵敏怎么办？", "answer": "1. 确保环境噪音较低；2. 说话时面向设备；3. 使用标准普通话；4. 检查麦克风是否被遮挡。", "metadata": {"category": "语音问题", "priority": "high"}},
          {"item_id": "faq_004", "content": "APP无法登录怎么办？", "answer": "1. 检查网络连接；2. 确认账号密码正确；3. 尝试使用验证码登录；4. 更新APP到最新版本。", "metadata": {"category": "APP问题", "priority": "medium"}}
        ]
      },
      {
        "doc_id": "spec_v1",
        "file_name": "技术规格书.pdf",
        "group_id": "technical",
        "data_type": "chunk",
        "items": [
          {"item_id": "spec_001", "content": "处理器：ARM Cortex-A53 四核 1.5GHz，内存：512MB DDR3，存储：4GB eMMC。", "metadata": {"section": "硬件规格"}},
          {"item_id": "spec_002", "content": "无线连接：WiFi 802.11 b/g/n 2.4GHz，蓝牙5.0 BLE，Zigbee 3.0。", "metadata": {"section": "无线规格"}},
          {"item_id": "spec_003", "content": "音频：双麦克风阵列，支持5米远场拾音，3W扬声器。", "metadata": {"section": "音频规格"}}
        ]
      }
    ]
  }'
```

**预期返回：**
```json
{
  "success": true,
  "task_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "message": "Storage completed successfully",
  "total_documents": 3,
  "total_items": 12
}
```

---

### 3. 向量查询 - chunk 类型

```bash
curl -X POST 'http://localhost:8001/api/v1/storage/search/vector' \
  -H 'Content-Type: application/json' \
  -d '{"knowledge_base_id": "product-kb-2024", "query": "设备无法连接WiFi", "top_k": 5, "data_type": "chunk"}'
```

**预期返回：**
```json
{
  "success": true,
  "query": "设备无法连接WiFi",
  "total": 5,
  "results": [
    {
      "item_id": "manual_v1_ch_004",
      "content": "第四章：故障排除。如设备无法连接，请检查WiFi密码是否正确，或尝试重启路由器。",
      "score": 0.85,
      "data_type": "chunk",
      "doc_id": "manual_v1",
      "file_name": "产品使用手册V1.0.pdf",
      "metadata": {"page": 15, "chapter": "故障排除"},
      "answer": null
    }
  ]
}
```

---

### 4. 向量查询 - faq 类型

```bash
curl -X POST 'http://localhost:8001/api/v1/storage/search/vector' \
  -H 'Content-Type: application/json' \
  -d '{"knowledge_base_id": "product-kb-2024", "query": "语音控制不好用", "top_k": 3, "data_type": "faq"}'
```

**预期返回：**
```json
{
  "success": true,
  "query": "语音控制不好用",
  "total": 3,
  "results": [
    {
      "item_id": "faq_v1_faq_003",
      "content": "语音控制不灵敏怎么办？",
      "score": 0.92,
      "data_type": "faq",
      "doc_id": "faq_v1",
      "file_name": "常见问题解答.pdf",
      "metadata": {"category": "语音问题", "priority": "high"},
      "answer": "1. 确保环境噪音较低；2. 说话时面向设备；3. 使用标准普通话；4. 检查麦克风是否被遮挡。"
    }
  ]
}
```

---

### 5. 查询文档的所有切片（分页）

```bash
# 第1页，每页2条
curl 'http://localhost:8001/api/v1/storage/documents/manual_v1/items?page=1&page_size=2'
```

**预期返回：**
```json
{
  "doc_id": "manual_v1",
  "file_name": "产品使用手册V1.0.pdf",
  "data_type": "chunk",
  "total_items": 5,
  "page": 1,
  "page_size": 2,
  "items": [
    {"item_id": "ch_001", "content": "第一章：产品概述...", "metadata": {...}, "answer": null},
    {"item_id": "ch_002", "content": "第二章：安装指南...", "metadata": {...}, "answer": null}
  ]
}
```

```bash
# 第2页
curl 'http://localhost:8001/api/v1/storage/documents/manual_v1/items?page=2&page_size=2'
```

```bash
# 查询FAQ文档
curl 'http://localhost:8001/api/v1/storage/documents/faq_v1/items?page=1&page_size=10'
```

---

### 6. 查询知识库所有文档及切片

```bash
# 包含切片内容
curl 'http://localhost:8001/api/v1/storage/knowledge-bases/product-kb-2024/items?include_items=true&page=1&page_size=10'
```

**预期返回：**
```json
{
  "kb_id": "product-kb-2024",
  "total_documents": 3,
  "page": 1,
  "page_size": 10,
  "documents": [
    {
      "doc_id": "manual_v1",
      "file_name": "产品使用手册V1.0.pdf",
      "data_type": "chunk",
      "status": "completed",
      "item_count": 5,
      "items": [...]
    },
    {
      "doc_id": "faq_v1",
      "file_name": "常见问题解答.pdf",
      "data_type": "faq",
      "status": "completed",
      "item_count": 4,
      "items": [...]
    },
    {
      "doc_id": "spec_v1",
      "file_name": "技术规格书.pdf",
      "data_type": "chunk",
      "status": "completed",
      "item_count": 3,
      "items": [...]
    }
  ]
}
```

```bash
# 只查文档列表，不包含切片
curl 'http://localhost:8001/api/v1/storage/knowledge-bases/product-kb-2024/items?include_items=false'
```

---

### 7. 修改切片内容

```bash
# 修改 manual_v1 的第一个切片
curl -X PUT 'http://localhost:8001/api/v1/storage/items/manual_v1_ch_001' \
  -H 'Content-Type: application/json' \
  -d '{
    "content": "第一章：产品概述（已更新）。本产品是新一代智能家居控制中心，支持语音控制、手机APP远程操控、智能场景联动。",
    "metadata": {"page": 1, "chapter": "概述", "updated": true, "update_time": "2024-01-14"}
  }'
```

**预期返回：**
```json
{
  "success": true,
  "item_id": "manual_v1_ch_001",
  "message": "Item updated successfully"
}
```

```bash
# 验证修改结果
curl 'http://localhost:8001/api/v1/storage/documents/manual_v1/items?page=1&page_size=1'
```

---

### 8. 删除单个文档

```bash
curl -X DELETE 'http://localhost:8001/api/v1/storage/documents/spec_v1'
```

**预期返回：**
```json
{
  "success": true,
  "message": "Document deleted successfully",
  "doc_id": "spec_v1"
}
```

---

### 9. 查询任务状态

```bash
# 替换为实际的 task_id（从存储接口返回值获取）
curl 'http://localhost:8001/api/v1/storage/tasks/{task_id}'
```

**预期返回：**
```json
{
  "task_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "kb_id": "product-kb-2024",
  "status": "completed",
  "total_documents": 3,
  "total_items": 12,
  "completed_items": 12,
  "failed_documents": 0
}
```

---

### 10. 删除整个知识库

```bash
curl -X DELETE 'http://localhost:8001/api/v1/storage/knowledge-bases/product-kb-2024'
```

**预期返回：**
```json
{
  "success": true,
  "message": "Knowledge base deleted successfully",
  "kb_id": "product-kb-2024"
}
```

---

### 测试顺序建议

1. 健康检查 → 确认服务正常
2. 存储数据 → 创建知识库和文档
3. 向量查询 → 测试检索功能
4. 查询切片 → 测试分页功能
5. 修改切片 → 测试更新功能
6. 删除文档 → 测试单文档删除
7. 删除知识库 → 测试整体清理