Initial commit: 百家号文章采集系统

DATABASE_MIGRATION.md

@@ -0,0 +1,177 @@
+# 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
+```