171 lines
9.5 KiB
Markdown
171 lines
9.5 KiB
Markdown
# 后端运行逻辑
|
||
|
||
后端是 **Node.js Express + SQLite + WebSocket**，与 Python 爬虫共用同一数据库文件，负责提供「态势数据」API、实时推送和简单统计。
|
||
|
||
---
|
||
|
||
## 一、启动方式
|
||
|
||
```bash
|
||
npm run api # 启动 server/index.js，默认端口 3001
|
||
```
|
||
|
||
- 端口：`process.env.API_PORT || 3001`
|
||
- 数据库：`process.env.DB_PATH` 或 `server/data.db`（与爬虫共用）
|
||
|
||
---
|
||
|
||
## 二、整体架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────┐
|
||
│ server/index.js │
|
||
│ (HTTP Server + WebSocket Server) │
|
||
└─────────────────────────────────────────┘
|
||
│
|
||
┌───────────────────────────────┼───────────────────────────────┐
|
||
│ │ │
|
||
▼ ▼ ▼
|
||
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||
│ /api/* │ │ /ws │ │ 静态 dist │
|
||
│ routes.js │ │ WebSocket │ │ (生产) │
|
||
└──────┬──────┘ └──────┬──────┘ └─────────────┘
|
||
│ │
|
||
│ 读/写 │ 广播 situation + stats
|
||
▼ │
|
||
┌─────────────┐ │
|
||
│ db.js │◄─────────────────────┘
|
||
│ (SQLite) │ getSituation() / getStats()
|
||
└──────┬──────┘
|
||
│
|
||
│ 同文件 data.db
|
||
▼
|
||
┌─────────────┐
|
||
│ Python 爬虫 │ 抓取 → 去重 → AI 清洗 → 映射到库字段 → 写表 → POST /api/crawler/notify
|
||
│ situation_ │ (main.py 或 gdelt 服务；写 situation_update / news_content / combat_losses 等)
|
||
│ update 等 │
|
||
└─────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 三、核心模块
|
||
|
||
| 文件 | 作用 |
|
||
|------|------|
|
||
| **index.js** | 创建 HTTP + WebSocket 服务，挂载路由、静态资源、定时广播、爬虫通知回调 |
|
||
| **routes.js** | 所有 `/api/*` 接口：situation、db/dashboard、visit、feedback、share、stats、events、news 等 |
|
||
| **situationData.js** | `getSituation()`：从多张表聚合为前端所需的「态势」JSON（军力、基地、战损、事件脉络、GDELT 等） |
|
||
| **db.js** | SQLite 连接、建表、迁移（better-sqlite3，WAL 模式） |
|
||
| **stats.js** | `getStats()`：在看人数、累计访问、留言数、分享数 |
|
||
| **openapi.js** | Swagger/OpenAPI 文档定义 |
|
||
| **seed.js** | 初始化/重置种子数据（可单独运行 `npm run api:seed`） |
|
||
|
||
---
|
||
|
||
## 四、数据流（读）
|
||
|
||
1. **前端要「整页态势」**
|
||
- 请求 `GET /api/situation` → `routes.js` 调用 `getSituation()`
|
||
- `situationData.js` 从 db 读：`force_summary`、`power_index`、`force_asset`、`key_location`、`combat_losses`、`wall_street_trend`、`retaliation_*`、`situation_update`（最近 50 条）、`gdelt_events`、`conflict_stats` 等
|
||
- 组装成 `{ lastUpdated, usForces, iranForces, recentUpdates, conflictEvents, conflictStats, civilianCasualtiesTotal }` 返回。
|
||
|
||
2. **前端要「事件列表」**
|
||
- `GET /api/events` 返回 `conflictEvents` + `conflict_stats` + `updated_at`（同样来自 getSituation 的数据）。
|
||
|
||
3. **前端要「原始表数据」**
|
||
- `GET /api/db/dashboard` 返回多张表的 `SELECT *` 结果（含 `situation_update`），供 `/db` 调试页使用。
|
||
|
||
4. **WebSocket**
|
||
- 连接 `ws://host/ws` 时立即收到一条 `{ type: 'situation', data: getSituation(), stats: getStats() }`。
|
||
- 之后每 3 秒服务端主动广播同结构数据，前端可据此做实时刷新。
|
||
|
||
---
|
||
|
||
## 五、数据流（写）
|
||
|
||
### 5.1 爬虫侧写库链路（推荐理解顺序）
|
||
|
||
爬虫写入前端库的完整链路如下，**不是**「抓完直接写表」，而是经过去重、AI 清洗、字段映射后再落库：
|
||
|
||
1. **爬虫抓取实时数据**
|
||
- RSS 等源抓取（`scrapers/rss_scraper.fetch_all`），得到原始条目列表。
|
||
|
||
2. **数据去重**
|
||
- 抓取阶段：RSS 内按 (title, url) 去重。
|
||
- 落库前：按 `content_hash(title, summary, url)` 在 `news_content` 表中去重，仅**未出现过**的条目进入后续流程（`news_storage.save_and_dedup`）。
|
||
|
||
3. **去重后按批次推送给 AI 清洗**
|
||
- 对通过去重的每条/每批数据：
|
||
- **展示用清洗**：标题/摘要翻译、`clean_news_for_panel` 提炼为符合面板的纯文本与长度（如 summary ≤120 字），`ensure_category` / `ensure_severity` 规范为前端枚举（`cleaner_ai`）。
|
||
- **结构化提取**（可选）：`extractor_ai` / `extractor_dashscope` / `extractor_rules` 从新闻文本中抽取战损、基地状态等，输出符合 `panel_schema` 的结构。
|
||
- 得到「有效数据」：既有人读的 summary/category/severity，也有可落库的 combat_losses_delta、key_location 等。
|
||
|
||
4. **有效数据映射回前端数据库字段**
|
||
- 事件脉络：清洗后的条目写入 `situation_update`（`db_writer.write_updates`）。
|
||
- 资讯存档：去重后的新数据写入 `news_content`（已在步骤 2 完成）。
|
||
- 结构化数据：AI 提取结果通过 `db_merge.merge` 映射到前端表结构，更新 `combat_losses`、`key_location`、`retaliation_*`、`wall_street_trend` 等（与 `situationData.getSituation` 所用字段一致）。
|
||
|
||
5. **更新数据库表并通知后端**
|
||
- 上述表更新完成后，爬虫请求 **POST /api/crawler/notify**。
|
||
- 后端（index.js）更新 `situation.updated_at` 并调用 `broadcastSituation()`，前端通过 WebSocket 拿到最新态势。
|
||
|
||
实现上，**gdelt 服务**（`realtime_conflict_service`）里：先对抓取结果做翻译与清洗，再 `save_and_dedup` 去重落库 `news_content`，用去重后的新项写 `situation_update`，再按批次对这批新项做 AI 提取并 `db_merge.merge` 写战损/基地等表。
|
||
|
||
### 5.2 用户行为写入
|
||
|
||
- **POST /api/visit**：记 IP 到 `visits`，`visitor_count.total` +1，并触发一次广播。
|
||
- **POST /api/feedback**：插入 `feedback`。
|
||
- **POST /api/share**：`share_count.total` +1。
|
||
|
||
这些写操作在 `routes.js` 中通过 `db.prepare().run()` 完成。
|
||
|
||
---
|
||
|
||
## 六、API 一览
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | /api/health | 健康检查 |
|
||
| GET | /api/situation | 完整态势（供主面板） |
|
||
| GET | /api/events | 冲突事件 + 统计 |
|
||
| GET | /api/db/dashboard | 各表原始数据（供 /db 页） |
|
||
| GET | /api/news | 资讯列表（news_content 表） |
|
||
| GET | /api/stats | 在看/累计/留言/分享数 |
|
||
| POST | /api/visit | 记录访问并返回 stats |
|
||
| POST | /api/feedback | 提交留言 |
|
||
| POST | /api/share | 分享计数 +1 |
|
||
| POST | /api/crawler/notify | 爬虫通知：更新 updated_at 并广播（内部用） |
|
||
|
||
- **Swagger**：`http://localhost:3001/api-docs`
|
||
|
||
---
|
||
|
||
## 七、WebSocket 行为
|
||
|
||
- **路径**：`/ws`（与 HTTP 同端口）。
|
||
- **连接时**：服务端发送一条 `{ type: 'situation', data, stats }`。
|
||
- **定时广播**：`setInterval(broadcastSituation, 3000)` 每 3 秒向所有已连接客户端推送最新 `getSituation()` + `getStats()`。
|
||
- **爬虫通知**：POST `/api/crawler/notify` 会立即执行一次 `broadcastSituation()`，不必等 3 秒。
|
||
|
||
---
|
||
|
||
## 八、与爬虫的协作
|
||
|
||
- **共享 DB**：后端与爬虫都使用同一 `DB_PATH`（默认 `server/data.db`）。
|
||
- **爬虫写库链路**：爬虫抓取 → 去重 → AI 清洗出有效数据 → 映射到前端库字段 → 更新 `situation_update`、`news_content`、`combat_losses`、`key_location`、`gdelt_events` 等表 → 调用 POST `/api/crawler/notify` 通知后端。
|
||
- **后端角色**：只读这些表（`getSituation()` 等）并推送；不参与抓取、去重或 AI 清洗，不调度爬虫。
|
||
|
||
整体上，后端是「读库 + 聚合 + 推送」的服务；写库来自**爬虫（经过去重与 AI 清洗、字段映射后）**以及**用户行为**（访问/留言/分享）。
|
||
|
||
---
|
||
|
||
## 九、本地验证链路
|
||
|
||
1. **启动后端**：`npm run api`（默认 3001）。
|
||
2. **检查读库**：`curl -s http://localhost:3001/api/situation` 应返回含 `lastUpdated`、`recentUpdates` 的 JSON。
|
||
3. **检查写库与通知**：爬虫跑完流水线后会 POST `/api/crawler/notify`，后端会更新 `situation.updated_at` 并广播；可再请求 `/api/situation` 看 `lastUpdated` 是否更新。
|
||
4. **查原始表**：浏览器打开 `http://localhost:3001/api/db/dashboard` 或前端 `/db` 页，查看 `situation_update`、`news_content` 等表。
|
||
|
||
爬虫侧完整验证步骤见 **crawler/README.md** 的「本地验证链路」；项目根目录可执行 `./scripts/verify-pipeline.sh` 做一键检查。
|