# JustQQbot **Repository Path**: muchuan114514/just-qqbot ## Basic Information - **Project Name**: JustQQbot - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2025-09-26 - **Last Updated**: 2026-01-14 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # VoxMind 言智 - QQ 群舆情智能分析平台

![License](https://img.shields.io/badge/license-MIT-blue.svg) ![Python](https://img.shields.io/badge/python-3.10+-green.svg) ![Node](https://img.shields.io/badge/node-18+-green.svg) ![FastAPI](https://img.shields.io/badge/FastAPI-0.109+-blue.svg) ![React](https://img.shields.io/badge/React-18.2+-blue.svg) **VoxMind 言智 - AI 驱动的 QQ 群舆情智能分析平台** 基于 FastAPI + React 的专业舆情监测与分析系统实时监控 | AI 话题分析 | 3D 关系图谱 | 深度学习情感分析 | 智能预警 | 专业报表导出 [快速开始](#快速开始) | [功能特性](#功能特性) | [文档](#文档) | [部署指南](#部署指南)

--- ## 功能特性 ### 核心功能 #### 1. 实时消息监控 - **多群组监控**: 同时监控多个 QQ 群消息 - **多账号支持**: 支持多个 QQ 号数据隔离与独立展示 - **消息队列处理**: 异步批处理，每秒处理 10+ 条消息 - **WebSocket 实时推送**: 新消息实时显示，延迟 < 1秒 - **消息持久化**: 自动保存到数据库，支持历史查询 #### 2. AI 智能分析 - **AI 话题聚类**: 基于大语言模型的智能话题发现与分析 - 自动识别群组热门话题 - AI 生成话题摘要和标签 - 支持自定义分析时间范围和消息数量 - 定时任务：每 10 分钟自动分析最活跃的 10 个群组 - **深度学习情感分析**: - LSTM 神经网络模型训练与推理 - 混合算法：规则引擎 + SnowNLP + LSTM - 三维情感分类：积极、中性、消极 + 置信度评分 - 情感词库：内置中文情感词典，支持扩展 - 上下文理解：识别否定词、程度词，提高准确率 #### 3. 关键词提取 - **双算法融合**: TF-IDF (40%) + TextRank (60%) - **智能过滤**: 150+ 停用词，词性过滤（名词/动词/形容词） - **词云可视化**: - 动态交互式词云图 - 螺旋布局算法，防重叠 - 权重映射：字体大小 18px-56px - 悬停高亮 + 详情卡片 - **趋势追踪**: 关键词热度变化分析 #### 4. 3D 用户群组关系图谱 - **3D 力导向图**: 使用 ForceGraph3D 和 Three.js 渲染 - **节点类型**: - 群组节点：紫色球体，大小反映成员数量 - 用户节点：蓝色球体，大小反映活跃度 - **关系可视化**: - 连线强度表示互动频率 - 实时 WebSocket 更新 - 交互式操作：旋转、缩放、聚焦 - **性能优化**: - 仅显示活跃节点 - 自适应渲染 - 数据缓存（30s 过期） #### 5. 预警系统 - **多种规则类型**: - 敏感词检测（关键词/正则） - 负面情绪预警（时间窗口统计） - 异常活跃预警（消息量突增） - **智能冷却**: 60分钟冷却期，避免重复触发 - **实时通知**: - WebSocket 推送预警信息 - Toast 弹窗通知（AlertToast 组件） - 预警历史记录 - **规则模板**: 预置常用规则模板，快速启用 #### 6. 用户画像分析 - **基础信息**: 用户ID、昵称、总消息数、活跃时长 - **活动热力图**: 24小时 × 7天活跃度可视化 - **情感雷达图**: 多维度情感倾向分析 - **话题云**: 用户关注的话题分布 - **社交关系**: 用户互动关系网络 - **消息时间线**: 用户历史消息浏览 #### 7. 数据分析与报表 - **多维统计**: 消息量、用户活跃度、情感分布 - **趋势分析**: 7/15/30 天情感趋势曲线 - **群组对比**: 各群组情感对比分析 - **用户排行**: 活跃度榜单（日/周/月） - **报表导出**: Excel 和 PDF 专业版式导出（支持周报/月报） - **报告中心**: 历史报告管理、对比分析、批量导出 - **系统配置**: 灵活的系统参数配置管理 ### UI 设计 - **现代化界面**: Apple 风格，毛玻璃效果 - **响应式布局**: 完美适配桌面/平板/手机 - **实时仪表板**: 关键指标一目了然 - **3D 可视化**: 立体关系图谱，交互丰富 - **数据可视化**: Echarts + Recharts 双图表库，交互丰富 - **动态背景**: 彩球碰撞动画背景（可配置） ## 技术栈 ### 后端 - **框架**: FastAPI + SQLAlchemy (异步) - **数据库**: SQLite / PostgreSQL - **NLP**: jieba, SnowNLP - **深度学习**: PyTorch (LSTM 模型) - **AI**: 大语言模型集成（OpenAI API 兼容） - **QQ 接口**: LLOneBot - **任务调度**: APScheduler - **缓存**: Redis (可选) ### 前端 - **框架**: React 18 + TypeScript - **构建工具**: Vite - **UI 组件**: shadcn/ui (Radix UI) - **样式**: Tailwind CSS - **状态管理**: Zustand + TanStack Query - **图表**: Recharts + Echarts - **3D 可视化**: - ForceGraph3D (力导向图) - Three.js (3D 渲染) - Echarts WordCloud (词云) - **图论**: Graphology + Sigma.js - **实时通信**: WebSocket ## 项目结构 ``` PythonQQBot/ ├── backend/ # 后端代码（FastAPI） │ ├── app/ │ │ ├── api/v1/ # API 路由和端点 │ │ │ ├── endpoints/ # 各模块 API │ │ │ │ ├── messages.py # 消息管理 │ │ │ │ ├── groups.py # 群组管理 │ │ │ │ ├── users.py # 用户管理 │ │ │ │ ├── sentiment.py # 情感分析 │ │ │ │ ├── keywords.py # 关键词 │ │ │ │ ├── topics.py # 话题分析 │ │ │ │ ├── alerts.py # 预警系统 │ │ │ │ ├── reports.py # 报表导出 │ │ │ │ ├── statistics.py # 统计数据 │ │ │ │ ├── settings.py # 系统配置 │ │ │ │ ├── system.py # 系统管理 │ │ │ │ └── websocket.py # WebSocket │ │ │ └── router.py # 路由汇总 │ │ ├── core/ # 核心功能 │ │ │ ├── nlp/ # NLP算法 │ │ │ │ ├── sentiment_analyzer.py # 情感分析（SnowNLP + LSTM） │ │ │ │ ├── keyword_extractor.py # 关键词提取（TF-IDF + TextRank） │ │ │ │ ├── ai_topic_clusterer.py # AI 话题分析与聚类 │ │ │ │ ├── sarcasm_detector.py # 讽刺检测 │ │ │ │ ├── text_preprocessor.py # 文本预处理 │ │ │ │ └── stopwords.txt # 停用词库 │ │ │ ├── ai/ # AI 模块 │ │ │ │ └── llm_service.py # LLM 服务 │ │ │ ├── cache/ # 缓存管理 │ │ │ ├── alert/ # 预警引擎 │ │ │ ├── queue/ # 消息队列处理 │ │ │ ├── llonebot/ # LLOneBot集成 │ │ │ ├── scheduler/ # 定时任务 │ │ │ ├── tasks/ # 后台任务 │ │ │ │ └── group_sync.py # 群组同步 │ │ │ ├── report/ # 报表生成 │ │ │ │ ├── excel_export.py # Excel 报表导出 │ │ │ │ └── pdf_export.py # PDF 报表导出（专业版式） │ │ │ └── formatters/ # 数据格式化 │ │ ├── db/ # 数据库配置和会话管理 │ │ ├── models/ # SQLAlchemy 数据模型 │ │ ├── repositories/ # 数据访问层（Repository Pattern） │ │ ├── services/ # 业务逻辑层（Service Layer） │ │ ├── schemas/ # Pydantic 数据模式 │ │ └── main.py # FastAPI 应用入口 │ ├── LSTM/ # LSTM 情感分析模型 │ │ └── main.py # 模型训练脚本 │ ├── tests/ # 单元测试 │ ├── data/ # SQLite 数据库文件 │ ├── logs/ # 日志文件 │ ├── run.py # 开发服务器启动脚本 │ ├── init_db.py # 数据库初始化脚本 │ ├── init_system_config.py # 系统配置初始化 │ ├── init_alert_rules.py # 预警规则初始化 │ ├── requirements.txt # Python 依赖 │ ├── .env.example # 环境变量示例 │ └── README.md # 后端文档 │ ├── frontend/ # 前端代码（React + TypeScript） │ ├── src/ │ │ ├── api/ # API 客户端封装 │ │ │ └── endpoints.ts # API 端点定义 │ │ ├── components/ # React 组件 │ │ │ ├── layout/ # 布局组件 │ │ │ │ ├── MainLayout.tsx # 主布局 │ │ │ │ ├── Sidebar.tsx # 侧边栏 │ │ │ │ ├── Header.tsx # 顶部导航 │ │ │ │ └── AnimatedBalls.tsx # 动画背景 │ │ │ ├── ui/ # shadcn/ui 基础组件 │ │ │ ├── WordCloud.tsx # 词云组件 │ │ │ ├── SentimentTrendChart.tsx # 情感趋势图 │ │ │ ├── UserGroupNetwork.tsx # 3D 关系图谱 │ │ │ ├── AlertToast.tsx # 预警通知 │ │ │ └── WebSocketIndicator.tsx # WebSocket 状态 │ │ ├── pages/ # 页面组件（13个主要页面） │ │ │ ├── Dashboard.tsx # 仪表盘 │ │ │ ├── Messages.tsx # 消息列表 │ │ │ ├── Groups.tsx # 群组管理 │ │ │ ├── Keywords.tsx # 关键词分析 │ │ │ ├── SentimentAnalysis.tsx # 情感分析 │ │ │ ├── TopicSquare.tsx # 话题广场（AI 话题分析） │ │ │ ├── UserRanking.tsx # 用户排行 │ │ │ ├── UserProfile/ # 用户画像 │ │ │ │ ├── index.tsx │ │ │ │ └── components/ # 用户画像子组件 │ │ │ ├── AlertCenter.tsx # 预警中心 │ │ │ ├── AlertRules.tsx # 预警规则管理 │ │ │ ├── ReportCenter.tsx # 报告中心（历史报告） │ │ │ └── Settings.tsx # 系统设置 │ │ ├── hooks/ # 自定义 React Hooks │ │ ├── stores/ # Zustand 状态管理 │ │ │ └── websocketStore.ts # WebSocket 状态 │ │ ├── services/ # 服务层 │ │ ├── types/ # TypeScript 类型定义 │ │ └── styles/ # 样式和设计令牌 │ ├── package.json # Node.js 依赖 │ ├── vite.config.ts # Vite 构建配置 │ ├── tailwind.config.js # Tailwind CSS 配置 │ └── tsconfig.json # TypeScript 配置 │ ├── LLOneBot-win-x64-ffmpeg/ # LLOneBot 程序（QQ机器人） │ ├── start_all.bat # Windows 一键启动脚本 ├── stop_all.bat # Windows 一键停止脚本 └── README.md # 本文件（项目总览） ``` ## 架构设计 ### 后端架构（分层架构） ``` ┌─────────────────────────────────────────────────┐ │ API Layer (FastAPI Routes) │ │ HTTP请求处理 / WebSocket / 文档 │ └────────────────────┬────────────────────────────┘ │ ┌────────────────────▼────────────────────────────┐ │ Service Layer (业务逻辑层) │ │ MessageService | SentimentService │ │ KeywordService | StatisticsService │ │ + 缓存管理 + 业务规则 │ └────────────────────┬────────────────────────────┘ │ ┌────────────────────▼────────────────────────────┐ │ Repository Layer (数据访问层) │ │ MessageRepository | SentimentRepository │ │ KeywordRepository | GroupUserRepository │ │ 封装所有数据库操作 │ └────────────────────┬────────────────────────────┘ │ ┌────────────────────▼────────────────────────────┐ │ Model Layer (SQLAlchemy ORM) │ │ 数据库表定义 + 关系映射（12+个模型） │ └─────────────────────────────────────────────────┘ ``` ### 前端架构 - **状态管理**: Zustand（轻量级）+ TanStack Query（服务端状态） - **路由**: React Router v6 - **组件库**: shadcn/ui（基于 Radix UI） - **样式**: Tailwind CSS（原子化 CSS） - **图表**: Recharts + Echarts（双图表库） - **3D 渲染**: Three.js + ForceGraph3D - **实时通信**: WebSocket + 自动重连 ## 快速开始 ### 环境要求 - **Python 3.10+** （推荐 3.10 或 3.11） - **Node.js 18+** （推荐 LTS 版本） - **QQ 客户端 + LLOneBot** （用于接收QQ消息） - **（可选）OpenAI API Key** （用于 AI 话题分析） ### 一键启动（推荐）适用于 Windows 用户，已安装所有依赖的情况： ```bash # 启动所有服务（后端 + 前端） start_all.bat # 停止所有服务 stop_all.bat ``` ### 完整安装步骤 #### 1. 克隆项目 ```bash git clone https://gitee.com/muchuan114514/just-qqbot.git cd just-qqbot ``` #### 2. 后端配置 ```bash # 进入后端目录 cd backend # 创建虚拟环境（推荐） python -m venv venv # 激活虚拟环境 # Windows: venv\Scripts\activate # Linux/Mac: # source venv/bin/activate # 安装依赖 pip install -r requirements.txt # 复制环境变量配置文件 copy .env.example .env # Linux/Mac: cp .env.example .env # 编辑 .env 文件，配置数据库和 LLOneBot 连接信息 notepad .env # 或使用你喜欢的编辑器 ``` **重要配置项**（`.env` 文件）： ```bash # 应用配置 APP_NAME=QQ群数据分析系统 APP_VERSION=2.0.0 DEBUG=True HOST=0.0.0.0 PORT=8000 # 数据库配置（SQLite 更简单，无需额外安装） DATABASE_URL=sqlite+aiosqlite:///./data/qqbot.db # 生产环境可使用 PostgreSQL # DATABASE_URL=postgresql+asyncpg://user:password@localhost/dbname # LLOneBot 配置 LLONEBOT_HTTP_URL=http://127.0.0.1:3000 LLONEBOT_WS_URL=ws://127.0.0.1:3001 LLONEBOT_ACCESS_TOKEN= # AI 配置（可选，用于 AI 话题分析） AI_ENABLED=False AI_API_KEY=your_api_key_here AI_BASE_URL=https://api.openai.com/v1 AI_MODEL=gpt-3.5-turbo AI_MAX_TOKENS=2000 AI_TEMPERATURE=0.7 AI_TIMEOUT=120 # NLP 配置 SENTIMENT_THRESHOLD=0.3 # 情感分值阈值 KEYWORD_MIN_FREQ=2 # 关键词最低出现次数 MAX_KEYWORDS=50 # 最大关键词数量 # Redis 配置（可选，用于缓存） REDIS_ENABLED=False REDIS_URL=redis://localhost:6379/0 # CORS 配置 CORS_ORIGINS=["http://localhost:5173","http://127.0.0.1:5173"] # 日志配置 LOG_LEVEL=INFO LOG_FILE=logs/app.log ``` #### 3. 初始化数据库 ```bash # 在 backend 目录下运行 python init_db.py python init_system_config.py python init_alert_rules.py ``` #### 4. 前端配置 ```bash # 进入前端目录 cd ../frontend # 安装依赖（首次运行必须执行） npm install # 或使用 pnpm/yarn # pnpm install # yarn install # 如果 npm install 很慢，可以使用国内镜像 npm install --registry=https://registry.npmmirror.com ``` #### 5. 配置 LLOneBot 1. 下载 LLOneBot：https://github.com/LLOneBot/LLOneBot/releases 2. 解压到项目的 `LLOneBot-win-x64-ffmpeg/` 目录 3. 运行 QQ 客户端，LLOneBot 会自动注入 4. 打开 LLOneBot 设置面板，配置： - HTTP 服务端口：`3000` - WebSocket 服务端口：`3001` - 消息上报地址：`http://localhost:8000/api/v1/onebot/message` #### 6. 启动服务 ##### 方式一：一键启动（Windows） ```bash # 回到项目根目录 cd .. start_all.bat ``` ##### 方式二：手动启动 **启动后端**： ```bash cd backend python run.py # 或使用 uvicorn # uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload ``` **启动前端**： ```bash # 新开一个终端 cd frontend npm run dev ``` #### 7. 访问系统 - **前端界面**: http://localhost:5173 - **后端 API**: http://localhost:8000 - **API 文档**: http://localhost:8000/api/docs （Swagger UI） - **健康检查**: http://localhost:8000/health - **WebSocket**: ws://localhost:8000/api/v1/ws ## 核心功能详解 ### 1. AI 话题分析系统集成了大语言模型，支持智能话题发现和分析： - **自动分析**: 定时任务每 10 分钟分析最活跃的 10 个群组 - **手动分析**: 在话题广场页面选择群组和时间范围进行分析 - **AI 能力**: - 话题识别与分类 - 主题摘要生成 - 话题标签提取 - 置信度评分 - **配置**: 在 `.env` 中启用 `AI_ENABLED=True` 并配置 API Key ### 2. 3D 用户群组关系图谱实时可视化用户与群组的关系网络： - **3D 力导向布局**: 自动计算节点位置，关系紧密的节点聚集 - **实时更新**: WebSocket 推送新消息时自动更新图谱 - **交互操作**: - 鼠标拖拽旋转视角 - 滚轮缩放 - 点击节点聚焦 - 悬停显示详情 - **性能优化**: - 仅渲染最近 7 天活跃的用户和群组 - 低活跃度节点过滤 - 帧率自适应 ### 3. 用户画像系统深度分析用户行为特征： - **基础信息**: 总消息数、活跃天数、首次/最后发言时间 - **活动热力图**: 24小时 × 7天活跃度分布 - **情感雷达图**: 积极、中性、消极情感倾向 - **话题云**: 用户最常讨论的话题标签 - **社交关系**: 与其他用户的互动关系网络 - **消息时间线**: 按时间排序的历史消息 ### 4. 情感分析多模型融合的情感分析： - **SnowNLP**: 基于朴素贝叶斯的中文情感分析 - **LSTM 模型**: 深度学习模型，支持自定义训练 - **规则引擎**: 情感词典匹配，处理否定词和程度词 - **实时分析**: 消息接收后立即进行情感分析 - **趋势追踪**: 7/15/30 天情感趋势可视化 ### 5. 预警系统智能预警，及时发现异常： - **敏感词预警**: 关键词或正则表达式匹配 - **情感预警**: 负面情感消息频率超过阈值 - **活跃度预警**: 消息量突增检测 - **实时通知**: Toast 弹窗 + WebSocket 推送 - **规则管理**: Web 界面配置预警规则 - **冷却机制**: 避免重复触发 ## 常见问题（FAQ） ### Q1: 前端启动失败 **问题**：`npm run dev` 报错，提示找不到模块 **解决**：确保已执行 `npm install` 安装依赖 ```bash cd frontend npm install # 必须先安装依赖！ npm run dev ``` ### Q2: 后端启动失败 **问题**：`ModuleNotFoundError: No module named 'xxx'` **解决**：检查是否已安装所有 Python 依赖 ```bash cd backend pip install -r requirements.txt ``` **问题**：数据库连接失败 **解决**：检查 `.env` 文件中的 `DATABASE_URL` 配置 ### Q3: LLOneBot 连接失败 **问题**：无法接收 QQ 消息 **解决**： 1. 确认 QQ 客户端已登录 2. 确认 LLOneBot 已正确注入 3. 检查 LLOneBot 配置中的端口是否与 `.env` 一致 4. 检查消息上报地址是否配置为 `http://localhost:8000/api/v1/onebot/message` 5. 查看后端日志 `backend/logs/app.log` 排查错误 ### Q4: AI 话题分析不工作 **问题**：话题分析没有结果或报错 **解决**： 1. 检查 `.env` 中 `AI_ENABLED=True` 2. 确认 `AI_API_KEY` 已正确配置 3. 检查 `AI_BASE_URL` 是否可访问 4. 查看后端日志确认 API 调用状态 5. 确保有足够的消息数据（至少 20 条） ### Q5: 3D 关系图谱加载缓慢 **问题**：关系图谱加载时间长或卡顿 **解决**： 1. 数据量过大，系统会自动过滤低活跃度节点 2. 调整查询时间范围（默认 7 天） 3. 浏览器硬件加速是否开启 4. 建议使用 Chrome 或 Edge 浏览器 ### Q6: 关键词提取效果不理想 **问题**：提取的关键词不准确 **解决**： 1. 调整 `KEYWORD_MIN_FREQ`（最低出现频率） 2. 增加消息样本量（至少 100 条消息） 3. 编辑停用词列表 `backend/app/core/nlp/stopwords.py` 4. 查看文档：关键词提取优化指南 ### Q7: 如何切换到 PostgreSQL？ **解决**： 1. 安装 asyncpg：`pip install asyncpg` 2. 修改 `.env` 中的 `DATABASE_URL`： ```ini DATABASE_URL=postgresql+asyncpg://user:password@localhost/dbname ``` 3. 重新运行 `python init_db.py` 初始化数据库 ### Q8: 生产环境部署建议？ **建议**： 1. 使用 PostgreSQL 替代 SQLite 2. 启用 Redis 缓存 3. 使用 Nginx 反向代理 4. 使用 Gunicorn + Uvicorn Workers 运行后端 5. 前端构建后部署静态文件（`npm run build`） 6. 使用 Supervisor 或 systemd 管理进程 7. 配置 HTTPS 证书 8. 设置日志轮转 9. 配置数据库备份 ## 路线图（Roadmap） ### 已完成 - [x] 基础消息采集与存储 - [x] 关键词提取与优化（TF-IDF + TextRank） - [x] 情感分析（SnowNLP + LSTM 深度学习） - [x] AI 驱动的话题分析与聚类 - [x] 讽刺检测（NLP 模块） - [x] 用户活跃度统计 - [x] 用户画像系统 - [x] 3D 用户群组关系图谱 - [x] 预警系统（多维度规则引擎） - [x] 实时 WebSocket 推送 - [x] 前端完整界面（13+ 页面） - [x] 多 QQ 号支持 - [x] 系统配置管理 - [x] 报表导出（Excel + PDF 专业版式） - [x] 报告中心（历史报告管理） ### 进行中 - [ ] 移动端适配优化 - [ ] Docker 一键部署 ### 计划中 - [ ] 机器人自动回复（基于规则/AI） - [ ] 多平台支持（微信、Telegram） - [ ] 数据备份与恢复 - [ ] 更多 AI 功能（摘要生成、智能问答） - [ ] 用户权限管理 - [ ] 多语言支持 ## 技术栈详情 ### 后端技术 | 技术 | 版本 | 说明 | |------|------|------| | Python | 3.10+ | 编程语言 | | FastAPI | 0.109+ | 高性能异步 Web 框架 | | SQLAlchemy | 2.0+ | ORM（异步模式） | | aiosqlite | 最新 | SQLite 异步驱动 | | Pydantic | 2.5+ | 数据验证和序列化 | | jieba | 0.42+ | 中文分词 | | snownlp | 0.12+ | 中文情感分析 | | PyTorch | 最新 | 深度学习框架（LSTM） | | APScheduler | 3.10+ | 定时任务调度 | | WebSockets | 12.0+ | 实时通信 | | Redis | 5.0+ | 缓存（可选） | | httpx | 0.26+ | 异步 HTTP 客户端 | ### 前端技术 | 技术 | 版本 | 说明 | |------|------|------| | React | 18.2+ | UI 库 | | TypeScript | 5.3+ | 类型系统 | | Vite | 5.0+ | 构建工具 | | Tailwind CSS | 3.4+ | 原子化 CSS | | shadcn/ui | 最新 | 组件库 | | Radix UI | 最新 | 无样式组件基础 | | TanStack Query | 5.17+ | 服务端状态管理 | | Zustand | 5.0+ | 客户端状态管理 | | React Router | 6.21+ | 路由管理 | | Recharts | 3.2+ | React 图表库 | | Echarts | 5.4+ | 通用图表库 | | ForceGraph3D | 1.79+ | 3D 力导向图 | | Three.js | 0.181+ | 3D 渲染引擎 | | Graphology | 0.26+ | 图论库 | | Sigma.js | 3.0+ | 图可视化 | | Lucide React | 最新 | 图标库 | ### 数据库设计 **核心表结构**（14 个表）： - `messages`: 消息记录（主表） - `groups`: 群组信息 - `users`: 用户信息 - `keywords`: 关键词提取结果 - `message_keywords`: 消息-关键词关联表（多对多） - `sentiments`: 情感分析结果 - `topics`: 话题聚类结果 - `message_topics`: 消息-话题关联表（多对多） - `user_activities`: 用户活跃度统计 - `alerts`: 预警记录 - `alert_rules`: 预警规则配置 - `reports`: 报告记录（历史报告存储） - `system_configs`: 系统配置 - (附加索引和关系映射表) ## 开发说明 ### 后端开发 #### 添加新 API 端点 1. 在 `app/models/` 创建数据模型 2. 在 `app/repositories/` 创建 Repository 3. 在 `app/services/` 创建 Service 4. 在 `app/api/v1/endpoints/` 创建 API 端点 5. 在 `app/api/v1/router.py` 注册路由 #### 运行测试 ```bash cd backend pytest tests/ # 运行所有测试 pytest tests/test_services.py # 运行特定测试 pytest -v --cov=app # 带覆盖率报告 ``` ### 前端开发 #### 添加新页面 1. 在 `src/types/` 定义类型 2. 在 `src/api/endpoints.ts` 添加 API 调用 3. 在 `src/pages/` 创建页面组件 4. 在 `src/App.tsx` 添加路由 #### 代码规范 - **组件命名**: PascalCase - **函数命名**: camelCase - **样式**: 仅使用 Tailwind CSS - **类型**: 所有 Props 和状态必须有类型定义 - **Hooks**: 自定义 Hooks 以 `use` 开头 ## 贡献指南欢迎提交 Issue 和 Pull Request！ ### 提交规范使用 [Conventional Commits](https://www.conventionalcommits.org/) 格式： - `feat`: 新功能 - `fix`: 修复 Bug - `docs`: 文档更新 - `style`: 代码格式 - `refactor`: 重构 - `test`: 测试相关 - `chore`: 构建/工具链相关示例：`feat: add AI topic analysis` ## License MIT License - 详见 [LICENSE](LICENSE) 文件 ## 致谢感谢以下开源项目： - [FastAPI](https://fastapi.tiangolo.com/) - 现代 Python Web 框架 - [React](https://react.dev/) - 用户界面库 - [shadcn/ui](https://ui.shadcn.com/) - 精美的 UI 组件 - [Tailwind CSS](https://tailwindcss.com/) - 实用优先的 CSS 框架 - [jieba](https://github.com/fxsjy/jieba) - 中文分词 - [SnowNLP](https://github.com/isnowfy/snownlp) - 中文情感分析 - [PyTorch](https://pytorch.org/) - 深度学习框架 - [LLOneBot](https://github.com/LLOneBot/LLOneBot) - QQ Bot 接口 - [Three.js](https://threejs.org/) - 3D 渲染库 - [ForceGraph3D](https://github.com/vasturiano/3d-force-graph) - 3D 力导向图 - [Echarts](https://echarts.apache.org/) - 数据可视化图表库 - [ReportLab](https://www.reportlab.com/) - PDF 生成库 ## 联系方式 - **Email**: 954811360@qq.com - **Gitee**: [@muchuan114514](https://gitee.com/muchuan114514) - **项目主页**: [Gitee](https://gitee.com/muchuan114514/python-qq-bot) | [GitHub](https://github.com/muchuan114514/PythonQQBot) ---

**VoxMind 言智 | Made with ❤️ by R0LL & TwindT** AI 驱动的舆情智能分析平台 | 版本 2.0 如果这个项目对你有帮助，请给个 ⭐ Star 支持一下！