ChouJuGEO/docs/guides/STORAGE_GUIDE.md

数据持久化方案对比

为什么不能用 IndexedDB？

IndexedDB 是浏览器 API，只能在 JavaScript 前端使用。
Streamlit 是 Python 后端应用，运行在服务器端，无法使用 IndexedDB。

---

方案对比

方案1：SQLite（⭐ 推荐）

优点：

• ✅ Python 内置支持（sqlite3），无需安装额外依赖
• ✅ 单文件数据库，易于备份和迁移
• ✅ 查询性能好，支持复杂查询
• ✅ 支持事务，数据安全
• ✅ 支持 SQL 查询，灵活强大
• ✅ 适合 MVP 到生产环境的平滑升级

缺点：

• ⚠️ 需要学习基本的 SQL（但很简单）
• ⚠️ 多进程写入需要处理锁（Streamlit 单进程，无此问题）

代码复杂度： ⭐⭐（非常简单）

适用场景： MVP 和生产环境都适用

---

方案2：JSON 文件

优点：

• ✅ 最简单，无需学习 SQL
• ✅ 人类可读，易于调试
• ✅ 无需数据库知识

缺点：

• ❌ 查询性能差（需要加载整个文件）
• ❌ 数据量大时很慢
• ❌ 并发写入可能丢失数据
• ❌ 不支持复杂查询

代码复杂度： ⭐（极简单）

适用场景： 仅适合数据量很小（<1000条）的 MVP

---

推荐方案：SQLite

为什么推荐 SQLite？

1. 其实很简单：只需要几行代码

   import sqlite3
   conn = sqlite3.connect('data.db')
   cursor = conn.cursor()
   cursor.execute("INSERT INTO table VALUES (?)", (value,))
   conn.commit()
   conn.close()
   

2. 性能好：即使数据量增长到几万条，依然很快

3. 功能强大：支持统计、查询、分析，为后续功能扩展打好基础

4. 零依赖：Python 内置，无需安装任何包

---

快速开始

1. 使用已封装好的 DataStorage 类

我已经为你创建了 modules/data_storage.py，提供了统一的接口：

from data_storage import DataStorage

# 初始化（SQLite方式）
storage = DataStorage(storage_type="sqlite", db_path="geo_data.db")

# 保存关键词
storage.save_keywords(["关键词1", "关键词2"], "品牌名")

# 获取关键词
keywords = storage.get_keywords("品牌名")

# 保存文章
storage.save_article("关键词", "平台", "内容", "文件名", "品牌名")

# 获取统计数据
stats = storage.get_stats("品牌名")

2. 最小改动集成

在 modules/geo_tool.py 中，只需要在关键位置添加几行保存代码：

# 文件顶部
from data_storage import DataStorage
storage = DataStorage(storage_type="sqlite", db_path="geo_data.db")

# 关键词生成后（约第533行）
if cleaned:
    st.session_state.keywords = cleaned
    storage.save_keywords(cleaned, brand)  # 新增这一行
    st.success(f"生成完成（{len(cleaned)} 条）")

# 内容生成后（约第714行）
st.session_state.generated_contents = contents
storage.save_article(keyword, plat, content, filename, brand)  # 在循环中添加

# 优化后（约第838行）
st.session_state.optimized_article = optimized_article
storage.save_optimization(
    original_article, optimized_article, changes, target_platform, brand
)  # 新增

# 验证后（约第932行）
st.session_state.verify_combined = combined
storage.save_verify_results(all_results)  # 新增

3. 添加历史记录查看功能（可选）

可以新增一个 Tab 来查看历史数据：

tab5 = st.tabs([..., "5 历史记录"])

with tab5:
    st.header("历史记录")
    
    # 统计数据
    stats = storage.get_stats(brand)
    col1, col2, col3, col4 = st.columns(4)
    col1.metric("关键词", stats["keywords_count"])
    col2.metric("文章", stats["articles_count"])
    col3.metric("优化", stats["optimizations_count"])
    col4.metric("验证", stats["verify_results_count"])
    
    # 历史文章列表
    articles = storage.get_articles(brand=brand)
    if articles:
        df = pd.DataFrame(articles)
        st.dataframe(df[["keyword", "platform", "created_at"]])

---

数据库文件位置

• SQLite 文件：geo_data.db（项目根目录）
• JSON 文件：data/ 目录（如果使用 JSON 方式）

建议： 将 geo_data.db 添加到 .gitignore，避免提交到版本控制。

---

性能对比（参考）

数据量	SQLite	JSON文件
100条	<10ms	<10ms
1000条	<50ms	~100ms
10000条	~200ms	~5秒
100000条	~1秒	很慢

---

总结

对于 MVP 版本，强烈推荐使用 SQLite：

1. ✅ 简单：使用封装好的 DataStorage 类，只需几行代码
2. ✅ 高效：性能好，支持未来扩展
3. ✅ 可靠：数据安全，支持事务
4. ✅ 零依赖：Python 内置，无需安装

如果数据量真的非常小（<100条），可以考虑 JSON 文件。

---

下一步

1. 查看 modules/data_storage.py 了解实现细节
2. 查看 modules/storage_example.py 了解使用方法
3. 在 modules/geo_tool.py 中集成（参考上面的最小改动示例）

需要我帮你直接集成到 modules/geo_tool.py 吗？