# 存储模块使用文档

## 概述

`Storage` 类提供了完整的 CRUD 操作，支持数据持久化、分类查询和全文搜索。

## 初始化

```python
from src.core.storage import Storage

# 使用默认数据目录（项目根目录下的 data 文件夹）
storage = Storage()

# 或指定自定义数据目录
storage = Storage("/path/to/data/dir")
```

## CRUD 操作

### 创建记录 (Create)

```python
# 创建新记录
record = storage.create(
    title="我的笔记",
    content="这是笔记的内容",
    category="工作",           # 可选，默认为"默认分类"
    tags=["重要", "待办"],      # 可选
    metadata={"priority": 1}   # 可选，自定义元数据
)

print(record["id"])  # 自动生成的唯一 ID
```

### 查询记录 (Read)

```python
# 根据 ID 查询单个记录
record = storage.get_by_id("20260211180219077144")
if record:
    print(record["title"], record["content"])

# 查询所有记录
all_records = storage.get_all()
for record in all_records:
    print(f"{record['title']} - {record['category']}")

# 按分类查询
work_records = storage.get_by_category("工作")

# 获取所有分类
categories = storage.get_categories()
print(f"所有分类: {categories}")
```

### 更新记录 (Update)

```python
# 更新记录（只更新提供的字段）
updated_record = storage.update(
    record_id="20260211180219077144",
    title="新的标题",           # 可选
    content="新的内容",         # 可选
    category="学习",            # 可选
    tags=["已完成"],           # 可选
    metadata={"status": "done"} # 可选，会合并到现有元数据
)

# 更新时间会自动更新
print(updated_record["updated_at"])
```

### 删除记录 (Delete)

```python
# 删除记录
success = storage.delete("20260211180219077144")
if success:
    print("删除成功")
else:
    print("记录不存在")
```

## 搜索功能

```python
# 搜索关键词（默认在标题、内容、标签中搜索）
results = storage.search("Python")

# 指定搜索字段
results = storage.search(
    "重要",
    search_in=["title", "tags"]  # 只搜索标题和标签
)

# 处理搜索结果
for record in results:
    print(f"找到: {record['title']}")
```

## 统计信息

```python
# 获取统计信息
stats = storage.get_stats()
print(f"总记录数: {stats['total_records']}")
print(f"总分类数: {stats['total_categories']}")
print("各分类统计:")
for category, count in stats['categories'].items():
    print(f"  {category}: {count}")
```

## 导入导出

```python
# 导出所有数据
data = storage.export_data()
print(f"导出 {len(data)} 条记录")

# 导入数据（覆盖模式）
storage.import_data(new_data, merge=False)

# 导入数据（合并模式）
storage.import_data(new_data, merge=True)  # 只添加不重复的记录
```

## 数据结构

每条记录包含以下字段：

```python
{
    "id": "20260211180219077144",           # 唯一 ID
    "title": "标题",                         # 标题
    "content": "内容",                       # 内容
    "category": "分类",                      # 分类
    "tags": ["标签1", "标签2"],              # 标签列表
    "metadata": {},                          # 自定义元数据
    "created_at": "2026-02-11T18:02:19.098002",  # 创建时间
    "updated_at": "2026-02-11T18:02:19.098002"   # 更新时间
}
```

## 注意事项

1. **数据持久化**: 所有数据保存在 JSON 文件中（`data/records.json`）
2. **ID 生成**: ID 基于时间戳自动生成，确保唯一性
3. **时间更新**: 更新记录时，`updated_at` 字段会自动更新
4. **元数据**: `metadata` 字段可以存储任意 JSON 兼容的数据
5. **搜索不区分大小写**: 搜索时会忽略大小写