# 帝国幻想乡~TOHOTOPIA 社区监控 MVP

本项目第一阶段接入 Steam 评测与 Steam 讨论区，定时抓取社区内容，使用 OpenRouter 模型分类，并在本地 dashboard 中展示处理状态。

## 当前状态

- 产品：《帝国幻想乡~TOHOTOPIA》
- Steam AppID：`3774440`
- 当前已接入：Steam 评测、Steam 讨论区主题、Steam 讨论区回复
- 已实现待登录验证：Twitter/X 账号帖子与帖子回复采集
- 当前模型：OpenRouter `deepseek/deepseek-v4-pro`
- 当前数据库：SQLite，默认 `data/tohotopia_monitor.sqlite3`
- 当前服务：FastAPI + 内联 dashboard
- 当前刷新：后台每 30 分钟增量同步
- 当前排序：建议回复优先；同组内按发布时间新到旧
- 当前局域网服务：监听 `0.0.0.0:8000`

已验证数据状态：

- 本机 smoke test 已抓取 384 条 Steam 内容。
- 2026-05-01 之后的 209 条内容已全部完成 AI 分析。
- Steam 讨论区中文时间文本已解析并回填，支持新到旧排序。

## 本机运行

```powershell
python -m venv .venv
.\.venv\Scripts\pip install -r requirements.txt
Copy-Item .env.example .env
# 编辑 .env，填入 OPENROUTER_API_KEY
.\.venv\Scripts\python -m app.cli sync --full
.\.venv\Scripts\uvicorn app.main:app --host 0.0.0.0 --port 8000
```

打开：

```text
http://127.0.0.1:8000
```

局域网其他设备访问：

```text
http://本机局域网IP:8000
```

当前 MVP 没有登录认证。开放到局域网后，同一局域网内能访问该地址的人都可以查看 dashboard、触发同步和修改处理状态。

## 关键配置

- `OPENROUTER_API_KEY`：OpenRouter Key。
- `APP_ID`：Steam AppID，默认 `3774440`。
- `SYNC_INTERVAL_MINUTES`：自动刷新间隔，默认 30 分钟。
- `TWITTER_ENABLED`：是否启用 Twitter/X 采集，默认 `false`，需要先登录 X.com。
- `TWITTER_USERNAME`：目标账号，默认 `Tohotopia`。
- `TWITTER_BROWSER_PROVIDER`：社媒采集浏览器来源，默认 `existing`，复用 `social-media-scraper` 的 CDP Chrome profile。
- `TWITTER_FULL_MAX_NO_NEW` / `TWITTER_INCREMENTAL_MAX_NO_NEW`：账号时间线滚动停止阈值。
- `TWITTER_THREAD_MAX_NO_NEW`：单帖回复滚动停止阈值。
- `TWITTER_FULL_REPLY_POST_LIMIT`：全量同步时抓取回复的帖子数上限，`0` 表示不限制。
- `TWITTER_INCREMENTAL_REPLY_PARENT_LIMIT`：增量同步时回查最近多少条已入库 Twitter 主帖的回复。
- `DISCUSSION_FULL_SCAN_MAX_PAGES`：首轮讨论区全量安全页数上限。
- `DISCUSSION_INCREMENTAL_MAX_PAGES`：增量刷新最多扫描页数。

## 分析补跑

Dashboard 里的“补跑分析”会在后台启动，每批最多处理 20 条，点击后页面会立即返回。刷新页面查看“已分析 / 待补跑”计数变化；如果仍有待补跑，可以继续点击。

如果启动服务后才修改 `.env`，需要重启 uvicorn 才能让后台自动同步线程读取新配置。页面按钮会在每次请求时重新读取 `.env`。

也可以用 CLI 定向补跑，例如只补 2026-05-01 之后的内容：

```powershell
python -m app.cli analyze-pending --since 2026-05-01 --limit 20
```

## Twitter/X 采集前提

Twitter/X 采集复用本机已有 `social-media-scraper` skill，通过 CDP Chrome profile 拦截结构化接口。首次使用需要先登录：

```powershell
python "$env:USERPROFILE\.codex\skills\social-media-scraper\scraper.py" --keep-browser-open https://x.com
```

在弹出的 Chrome 窗口登录 X.com 后，启用 `.env` 中的 `TWITTER_ENABLED=true`，再运行：

```powershell
python -m app.cli sync --platform twitter --full
```

如果未登录，系统会把本轮同步记为 partial 并在最近同步里显示错误，不会删除旧数据。

## 新社区平台扩展入口

后续接入其它社区平台时，优先复用现有三层数据模型：

- `raw_items`：原始内容和来源追溯信息
- `analysis_results`：OpenRouter 模型分析结果
- `work_items`：制作人/处理人状态、备注和处理记录

每个新平台建议单独实现采集器，输出与 `app.models.RawItem` 兼容的数据，不要让 dashboard 直接依赖平台私有字段。

新增平台最少需要明确：

- 来源平台和内容类型
- 稳定去重主键
- 原始链接生成方式
- 作者标识和发布时间解析
- 首轮全量与后续增量策略
- 是否需要登录态、cookie、API key 或浏览器自动化
- 失败重试和限流策略

当前 Steam 采集器参考：

- `app/steam.py`
- `app/sync.py`
- `app/openrouter.py`