cutThenThink/docs/database_usage.md

# 数据库模型使用说明

## 概述

数据库模型位于 `src/models/database.py`，使用 SQLAlchemy ORM 实现。

## 主要组件

### 1. Record 模型

数据库表结构，包含以下字段：

| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | Integer | 主键，自增 |
| image_path | String(512) | 图片路径，唯一索引 |
| ocr_text | Text | OCR识别结果 |
| category | String(20) | 分类类型 |
| ai_result | Text | AI生成的Markdown |
| tags | JSON | 标签列表 |
| notes | Text | 用户备注 |
| created_at | DateTime | 创建时间 |
| updated_at | DateTime | 更新时间 |

### 2. RecordCategory 类

定义了支持的分类常量：

```python
RecordCategory.TODO   # 待办事项
RecordCategory.NOTE   # 笔记
RecordCategory.IDEA   # 灵感
RecordCategory.REF    # 参考资料
RecordCategory.FUNNY  # 搞笑文案
RecordCategory.TEXT   # 纯文本
```

### 3. DatabaseManager 类

数据库连接管理器，负责：
- 创建数据库引擎
- 管理会话工厂
- 初始化表结构

### 4. 便捷函数

- `init_database(db_path)`: 初始化数据库
- `get_db()`: 获取数据库会话

## 使用示例

### 初始化数据库

```python
from src.models import init_database

# 使用默认路径
db_manager = init_database()

# 指定自定义路径
db_manager = init_database("sqlite:////path/to/database.db")
```

### 创建记录

```python
from src.models import get_db, Record, RecordCategory

session = get_db()

# 创建新记录
record = Record(
    image_path="/path/to/image.png",
    ocr_text="识别的文本",
    category=RecordCategory.NOTE,
    ai_result="# AI内容",
    tags=["标签1", "标签2"],
    notes="用户备注"
)

session.add(record)
session.commit()
print(f"新记录ID: {record.id}")
session.close()
```

### 查询记录

```python
from src.models import get_db, Record, RecordCategory

session = get_db()

# 查询所有记录
all_records = session.query(Record).all()

# 按分类查询
notes = session.query(Record).filter_by(category=RecordCategory.NOTE).all()

# 按ID查询
record = session.query(Record).filter_by(id=1).first()

# 模糊搜索
results = session.query(Record).filter(
    Record.ocr_text.contains("关键词")
).all()

session.close()
```

### 更新记录

```python
from src.models import get_db, Record

session = get_db()
record = session.query(Record).filter_by(id=1).first()

# 更新字段
record.notes = "新的备注"
record.ai_result = "# 更新后的AI内容"

# 使用标签方法
record.add_tag("新标签")
record.update_tags(["标签A", "标签B"])

session.commit()
session.close()
```

### 删除记录

```python
from src.models import get_db, Record

session = get_db()
record = session.query(Record).filter_by(id=1).first()

session.delete(record)
session.commit()
session.close()
```

### 转换为字典

```python
from src.models import get_db, Record

session = get_db()
record = session.query(Record).first()

# 转换为字典格式
data = record.to_dict()
print(data)
# {'id': 1, 'image_path': '/path/to/image.png', ...}

session.close()
```

## 注意事项

1. **会话管理**: 使用完session后记得关闭，或使用上下文管理器
2. **时间戳**: `created_at` 和 `updated_at` 自动管理
3. **分类验证**: 使用 `RecordCategory.is_valid(category)` 验证分类
4. **JSON字段**: tags 字段是JSON类型，存储为列表

## 数据库文件位置

默认数据库文件路径：
```
/home/congsh/CodeSpace/ClaudeSpace/CutThenThink/data/cutnthink.db
```

## 测试

运行测试脚本验证数据库功能（需要先安装SQLAlchemy）：

```bash
python3 tests/test_database.py
```