TH01_maintenance/任务/方案/后续社区平台接入指南.md

后续社区平台接入指南

当前架构

当前 MVP 是 Python/FastAPI + SQLite：

• app/main.py：dashboard、手动同步、补跑分析、处理状态更新、后台 30 分钟增量同步。
• app/steam.py：Steam 评测、讨论区主题和回复采集器。
• app/sync.py：统一同步流程、入库去重、调用模型分析、补跑分析。
• app/openrouter.py：OpenRouter deepseek/deepseek-v4-pro 结构化分类。
• app/db.py：SQLite schema。
• app/models.py：统一原始内容对象 RawItem。
• app/cli.py：命令行入口。

统一数据流

平台采集器 -> RawItem -> raw_items -> OpenRouter -> analysis_results -> work_items -> dashboard

新平台不要直接改 dashboard 数据结构。优先让平台采集器输出 RawItem，复用现有同步和分析流程。

RawItem 字段约定

新增平台采集器至少要提供：

• source：平台标识，例如 steam_reviews、steam_discussions。
• source_item_id：稳定去重主键，必须包含平台和内容 ID。
• source_url：能跳回原始内容的链接。
• content_type：内容类型，例如 review、discussion_topic、discussion_reply。
• author_id / author_name：能取到多少填多少。
• title：帖子标题，没有则为空。
• published_at：Unix 时间戳，优先提供。
• published_at_text：平台原始时间文本。
• updated_at_source：平台原始更新时间，没有则为空。
• content：送入模型分析的正文。
• raw：平台原始字段 JSON。

新平台接入步骤

1. 验证当前事实：页面/API 是否可访问、是否需要登录态、是否有频率限制。
2. 定义内容类型和去重主键。
3. 实现平台采集器，输出 list[RawItem]。
4. 在 app/sync.py 中接入采集器，保持失败不删除旧数据。
5. 跑小样本 smoke test：抓取、去重、AI 分析、dashboard 展示。
6. 再做首轮全量策略和后续增量策略。

已知实现决策

• AI 模型：OpenRouter deepseek/deepseek-v4-pro。
• Key：.env / 环境变量 OPENROUTER_API_KEY。
• Dashboard 排序：建议回复优先，同组内按发布时间新到旧。
• 补跑分析：每批最多 20 条，按 published_at/collected_at 新到旧。
• 局域网服务：python -m uvicorn app.main:app --host 0.0.0.0 --port 8000。
• 当前无登录认证，开放到局域网有修改处理状态风险。

新平台方案必须回答

• 这个平台监控的运营目的是什么？
• 抓哪些内容类型？
• 首轮是否全量？全量边界是什么？
• 后续增量根据什么停止？
• 原始链接如何生成？
• 发布时间是否可解析？相对时间如何处理？
• 是否要抓回复/评论楼中楼？
• 是否需要登录态、cookie、API key 或浏览器自动化？
• 失败、限流和重复采集如何处理？