mirror of
https://github.com/stardrophere/InsightRadar.git
synced 2026-06-05 23:07:51 +08:00
109 lines
4.9 KiB
Markdown
109 lines
4.9 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## 项目简介
|
||
|
||
InsightRadar（聚势智见）是一个热点资讯聚合平台。核心流程：定时爬取微博、知乎、百度等平台热搜 → 用本地 Embedding 模型（Qwen3-Embedding-4B）做余弦相似度语义聚类 → 合并为 `UnifiedEvent`（大事件）→ 调用 DeepSeek 等大模型生成 AI 摘要与标签 → 按用户订阅关键词定时推送邮件简报。
|
||
|
||
## 开发命令
|
||
|
||
### 后端（Python / FastAPI）
|
||
|
||
```bash
|
||
cd backend
|
||
uv sync # 安装依赖
|
||
uv run python main.py # 启动开发服务器（默认 :8000）
|
||
# 或
|
||
uv run uvicorn app.main:app --reload --port 8000
|
||
```
|
||
|
||
### 前端（Vue 3 / Vite）
|
||
|
||
```bash
|
||
cd frontend
|
||
npm install
|
||
npm run dev # 开发服务器（Vite，默认 :5173，代理到后端）
|
||
npm run build # 构建产物到 dist/
|
||
npm run type-check # TypeScript 类型检查
|
||
npm run lint # oxlint + eslint 双重 lint（自动修复）
|
||
npm run format # Prettier 格式化 src/
|
||
```
|
||
|
||
### 生产部署（将前端打包集成到后端）
|
||
|
||
```bash
|
||
cd frontend && npm run build
|
||
cp -r dist/* ../backend/app/static/
|
||
```
|
||
|
||
## 架构概览
|
||
|
||
### 后端分层
|
||
|
||
```
|
||
backend/app/
|
||
├── main.py # FastAPI 入口，APScheduler 调度（抓取/摘要/推送三个定时任务）
|
||
├── database.py # SQLAlchemy engine（SQLite WAL 模式，支持 SQLALCHEMY_DATABASE_URL 切换）
|
||
├── initialize.py # 启动时幂等写入默认信息源（今日头条、微博等11个平台）
|
||
├── models/models.py # 全部 ORM 表定义（单文件）
|
||
├── api/
|
||
│ ├── router.py # 统一挂载所有子路由，前缀 /api/v1
|
||
│ └── endpoints/ # auth / events / preferences / delivery / revisions / sources / stats
|
||
├── services/
|
||
│ ├── fetcher_service.py # 爬取热搜 + Embedding 生成 + 语义聚类入库（核心）
|
||
│ ├── summary_service.py # 调用大模型生成 AI 摘要与标签
|
||
│ ├── matching_service.py # 精确 + 语义双模式匹配用户兴趣
|
||
│ └── delivery_service.py # 检查推送时间窗口并发送邮件简报
|
||
├── core/
|
||
│ ├── security.py # JWT 签发与校验
|
||
│ └── verification/ # 验证码逻辑（Redis 或 DB 双模式存储）
|
||
├── crud/ # 数据库 CRUD 操作
|
||
├── schemas/ # Pydantic 请求/响应 Schema
|
||
├── prompts/ # LLM Prompt 模板
|
||
└── static/ # 前端构建产物（生产环境）
|
||
```
|
||
|
||
### 前端分层
|
||
|
||
```
|
||
frontend/src/
|
||
├── api/ # 封装 fetch 请求（基于 config/apiBase.ts，前缀 /api/v1）
|
||
├── stores/ # Pinia 状态（auth / theme）
|
||
├── router/ # Vue Router（requiresAuth / guestOnly meta 守卫）
|
||
├── views/ # 页面：Dashboard / Search / Topics / Delivery / Revisions / Login / Register
|
||
├── layouts/ # DashboardLayout（统一侧边栏）
|
||
└── components/ # 通用组件（UnifiedEventCard 等）
|
||
```
|
||
|
||
### 关键数据模型
|
||
|
||
- `UnifiedEvent`：语义聚类后的"大事件"，含 AI 摘要、`center_embedding`（聚类中心向量）、`hot_score`
|
||
- `TrendingEvent`：各平台原始热搜，通过 `external_id`（MD5 指纹）去重，`unified_event_id` 关联大事件
|
||
- `ExtractedTopic` / `DiscussionComment`：多态设计，`target_type` 区分挂载在 EVENT / TREND / ARTICLE 下
|
||
- `DeliveryHistory`：防重推记录，唯一约束 `(user_id, target_type, target_id)`
|
||
|
||
### Embedding 模型
|
||
|
||
`fetcher_service.py` 在模块级加载 `SentenceTransformer` 全局单例（`embedder_model`）。`matching_service.py` 直接 import 复用该单例，避免重复加载。模型路径由 `EMBEDDING_MODEL_PATH` 配置，需提前将模型文件放入 `backend/data/` 目录。
|
||
|
||
## 配置
|
||
|
||
`.env` 文件放在项目根目录（或 `backend/data/`，两处均可），关键变量：
|
||
|
||
| 变量 | 说明 |
|
||
|------|------|
|
||
| `SQLALCHEMY_DATABASE_URL` | 默认 `sqlite:///./data/demo.db`，可切换 PostgreSQL |
|
||
| `EMBEDDING_MODEL_PATH` | 本地 Embedding 模型路径 |
|
||
| `AI_API_KEY` | 大模型 API Key（DeepSeek 等 OpenAI 兼容接口） |
|
||
| `SIMILARITY_THRESHOLD` | 热搜语义聚类阈值（默认 0.72） |
|
||
| `AUTH_CODE_STORE` | 验证码存储模式：`db`（无 Redis 时）或 `redis` |
|
||
| `REDIS_URL` | Redis 连接，为空时验证码自动回退到数据库 |
|
||
|
||
## 注意事项
|
||
|
||
- **后端工作目录**：必须在 `backend/` 下运行，静态文件路径 `app/static` 是相对路径
|
||
- **Embedding 模型冷启动慢**：首次加载 Qwen3-Embedding-4B 约需数十秒，是正常现象
|
||
- **前端 API 路径**：所有请求统一经 `src/config/apiBase.ts` 的 `fetchApi()` 发出，前缀 `/api/v1`，无需手动拼接
|
||
- **数据库迁移**：当前使用 `Base.metadata.create_all()` 自动建表，不使用 Alembic；修改 Model 字段后需手动处理已有数据库
|