feat: 实现CutThenThink P0阶段核心功能
项目初始化 - 创建完整项目结构(src/, data/, docs/, examples/, tests/) - 配置requirements.txt依赖 - 创建.gitignore P0基础框架 - 数据库模型:Record模型,6种分类类型 - 配置管理:YAML配置,支持AI/OCR/云存储/UI配置 - OCR模块:PaddleOCR本地识别,支持云端扩展 - AI模块:支持OpenAI/Claude/通义/Ollama,6种分类 - 存储模块:完整CRUD,搜索,统计,导入导出 - 主窗口框架:侧边栏导航,米白配色方案 - 图片处理:截图/剪贴板/文件选择/图片预览 - 处理流程整合:OCR→AI→存储串联,Markdown展示,剪贴板复制 - 分类浏览:卡片网格展示,分类筛选,搜索,详情查看 技术栈 - PyQt6 + SQLAlchemy + PaddleOCR + OpenAI/Claude SDK - 共47个Python文件,4000+行代码 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
151
docs/storage_usage.md
Normal file
151
docs/storage_usage.md
Normal file
@@ -0,0 +1,151 @@
|
||||
# 存储模块使用文档
|
||||
|
||||
## 概述
|
||||
|
||||
`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. **搜索不区分大小写**: 搜索时会忽略大小写
|
||||
Reference in New Issue
Block a user