# 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 字段后需手动处理已有数据库