ai_baijiahao/DATABASE_MIGRATION.md

# SQLite 数据库迁移说明

## 概述

系统已从 JSON 文件存储迁移到 SQLite 数据库，提供更好的性能、并发支持和数据完整性。

## 主要变更

### 1. 新增文件
- `database.py` - SQLite 数据库管理模块
- `test_database.py` - 数据库功能测试脚本
- `data/baijiahao.db` - SQLite 数据库文件（自动创建）

### 2. 修改文件
- `task_queue.py` - 使用 SQLite 替代 JSON 文件存储

### 3. 数据迁移
- 旧数据自动从 `data/task_queue.json` 迁移到数据库
- 迁移成功后会创建备份文件 `data/task_queue.json.backup`
- 原 JSON 文件保留，可安全删除

## 数据库结构

### tasks 表
```sql
CREATE TABLE tasks (
    task_id TEXT PRIMARY KEY,          -- 任务ID
    url TEXT NOT NULL,                 -- 百家号URL
    months REAL NOT NULL,              -- 获取月数
    use_proxy INTEGER NOT NULL,        -- 是否使用代理 (0/1)
    proxy_api_url TEXT,                -- 代理API地址
    username TEXT,                     -- 用户名
    status TEXT NOT NULL,              -- 任务状态
    created_at TEXT NOT NULL,          -- 创建时间
    started_at TEXT,                   -- 开始时间
    completed_at TEXT,                 -- 完成时间
    progress INTEGER DEFAULT 0,        -- 进度 (0-100)
    current_step TEXT,                 -- 当前步骤
    total_articles INTEGER DEFAULT 0,  -- 总文章数
    processed_articles INTEGER DEFAULT 0, -- 已处理文章数
    error TEXT,                        -- 错误信息
    result_file TEXT                   -- 结果文件路径
);
```

### 索引
- `idx_tasks_status` - 状态索引（加速状态查询）
- `idx_tasks_username` - 用户名索引（加速用户过滤）
- `idx_tasks_created_at` - 创建时间索引（加速时间排序）

## 优势

### 1. 性能提升
- 索引支持，查询速度更快
- 优化的 SQL 查询，减少内存占用
- 不再需要每次操作都读写整个文件

### 2. 并发安全
- 线程安全的连接管理
- 数据库级别的事务支持
- 避免文件锁冲突

### 3. 数据完整性
- 主键约束防止重复
- 事务支持确保数据一致性
- 异常回滚机制

### 4. 可扩展性
- 易于添加新字段和索引
- 支持复杂查询和统计
- 便于后续功能扩展

## 使用说明

### 测试数据库功能
```bash
python test_database.py
```

### 手动迁移数据
```python
from database import migrate_from_json

# 从 JSON 迁移到数据库
count = migrate_from_json("data/task_queue.json")
print(f"迁移了 {count} 个任务")
```

### 直接使用数据库
```python
from database import get_database

db = get_database()
with db.get_connection() as conn:
    cursor = conn.cursor()
    cursor.execute("SELECT * FROM tasks")
    tasks = cursor.fetchall()
```

## 向后兼容

- 原有 API 接口不变
- 无需修改调用代码
- 自动迁移旧数据
- 保留原 JSON 文件

## 注意事项

1. **首次启动**：系统会自动创建数据库和迁移数据
2. **备份**：迁移成功后建议备份 `data/baijiahao.db`
3. **清理**：确认迁移成功后可删除 `data/task_queue.json`
4. **性能**：大量任务时数据库性能优势明显

## 故障排除

### 数据库锁定
如果遇到 "database is locked" 错误：
- 检查是否有多个进程同时访问
- 重启应用程序
- 增加超时时间（已设置为30秒）

### 迁移失败
如果迁移失败：
- 检查 `data/task_queue.json` 格式
- 查看日志错误信息
- 手动运行 `test_database.py` 测试

### 数据丢失
- 检查 `data/task_queue.json.backup` 备份文件
- 从备份恢复后重新迁移
- 使用 SQLite 工具直接查看数据库

## 性能优化

### 已实施的优化
- 添加索引加速查询
- 使用事务批量操作
- 连接池复用连接
- Row factory 减少转换

### 未来优化方向
- 定期清理旧任务
- 数据归档机制
- 分表策略
- 查询缓存

## 相关命令

### 查看数据库
```bash
# 使用 SQLite 命令行工具
sqlite3 data/baijiahao.db

# 查看表结构
.schema tasks

# 查看所有任务
SELECT * FROM tasks;

# 统计任务数量
SELECT status, COUNT(*) FROM tasks GROUP BY status;
```

### 备份数据库
```bash
# 简单备份
cp data/baijiahao.db data/baijiahao.db.backup

# 使用 SQLite 工具备份
sqlite3 data/baijiahao.db ".backup data/baijiahao.db.backup"
```

### 恢复数据库
```bash
# 从备份恢复
cp data/baijiahao.db.backup data/baijiahao.db
```