backend 去ai化

CLAUDE.md

@@ -0,0 +1,108 @@
+# 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 字段后需手动处理已有数据库