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 类

定义了支持的分类常量：

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

3. DatabaseManager 类

数据库连接管理器，负责：

• 创建数据库引擎
• 管理会话工厂
• 初始化表结构

4. 便捷函数

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

使用示例

初始化数据库

from src.models import init_database

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

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

创建记录

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()

查询记录

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()

更新记录

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()

删除记录

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()

转换为字典

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）：

python3 tests/test_database.py