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）

cd backend
uv sync                            # 安装依赖
uv run python main.py              # 启动开发服务器（默认 :8000）
# 或
uv run uvicorn app.main:app --reload --port 8000

前端（Vue 3 / Vite）

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/

生产部署（将前端打包集成到后端）

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

4.9 KiB Raw Blame History Unescape Escape