# 后续社区平台接入指南

## 当前架构

当前 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`：命令行入口。

## 统一数据流

```text
平台采集器 -> 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 或浏览器自动化？
- 失败、限流和重复采集如何处理？