上传文件至「/」

2026-03-23 15:30:38 +08:00
commit f13ecb3bba
5 changed files with 1448 additions and 0 deletions
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -0,0 +1,490 @@
+# 会会虚拟用户 AI 互动系统 - 架构设计文档
+
+## 一、系统架构
+
+### 1.1 整体架构图
+
+```
+┌─────────────────────────────────────────────────────┐
+│                    用户层                            │
+│              (浏览器 / 移动端)                        │
+└──────────────────┬──────────────────────────────────┘
+                   │
+                   │ HTTP/HTTPS
+                   │
+┌──────────────────▼──────────────────────────────────┐
+│                  Nginx                              │
+│            (反向代理 / 静态资源)                      │
+└──────────────────┬──────────────────────────────────┘
+                   │
+         ┌─────────┴─────────┐
+         │                   │
+┌────────▼────────┐  ┌──────▼────────┐
+│  Frontend       │  │   Backend      │
+│  Vue3 +         │  │   FastAPI      │
+│  Element Plus   │  │   Python       │
+│  (端口：80)     │  │   (端口：8000) │
+└─────────────────┘  └──────┬────────┘
+                            │
+              ┌─────────────┼─────────────┐
+              │             │             │
+       ┌──────▼──────┐ ┌───▼────┐ ┌─────▼─────┐
+       │   MySQL     │ │ Redis  │ │  定时任务 │
+       │   数据库    │ │ (可选) │ │  调度器   │
+       └─────────────┘ └────────┘ └───────────┘
+                            │
+              ┌─────────────┼─────────────┐
+              │             │             │
+       ┌──────▼──────┐ ┌───▼────┐ ┌─────▼─────┐
+       │  会会 API   │ │ AI 模型 │ │  文件存储 │
+       │  接口服务   │ │ 服务   │ │  ( uploads)│
+       └─────────────┘ └────────┘ └───────────┘
+```
+
+### 1.2 技术栈选型
+
+| 层级 | 技术 | 说明 |
+|------|------|------|
+| **前端** | Vue 3 | 渐进式 JavaScript 框架 |
+| | Element Plus | UI 组件库 |
+| | Pinia | 状态管理 |
+| | Vue Router | 路由管理 |
+| | ECharts | 数据可视化 |
+| **后端** | Python 3.11 | 编程语言 |
+| | FastAPI | 高性能 Web 框架 |
+| | SQLAlchemy | ORM 框架 |
+| | Pydantic | 数据验证 |
+| | APScheduler | 定时任务调度 |
+| **数据库** | MySQL 8.0 | 关系型数据库 |
+| **AI 对接** | OpenAI SDK | GPT 系列模型 |
+| | Zhipu SDK | 智谱 AI 模型 |
+| **部署** | Docker | 容器化 |
+| | Docker Compose | 编排工具 |
+| | Nginx | Web 服务器 |
+
+## 二、模块设计
+
+### 2.1 后端模块划分
+
+```
+backend/app/
+├── main.py                 # 应用入口
+├── core/                   # 核心配置
+│   ├── config.py          # 系统配置
+│   └── __init__.py
+├── models/                 # 数据库模型
+│   ├── base.py            # 数据库基础
+│   ├── virtual_user.py    # 虚拟用户模型
+│   ├── interaction.py     # 互动记录模型
+│   ├── token_usage.py     # Token 使用模型
+│   ├── system_config.py   # 系统配置模型
+│   ├── ai_model.py        # AI 模型配置模型
+│   └── news_cache.py      # 新闻缓存模型
+├── schemas/                # Pydantic Schema
+│   ├── virtual_user.py    # 虚拟用户 Schema
+│   ├── interaction.py     # 互动 Schema
+│   ├── dashboard.py       # 控制台 Schema
+│   ├── ai_model.py        # AI 模型 Schema
+│   └── system_config.py   # 系统配置 Schema
+├── services/               # 业务服务
+│   ├── huihui_api.py      # 会会接口服务
+│   ├── ai_service.py      # AI 服务
+│   ├── virtual_user_service.py  # 虚拟用户服务
+│   ├── interaction_service.py   # 互动服务
+│   ├── token_service.py         # Token 统计服务
+│   └── scheduler_service.py     # 定时任务服务
+├── api/                    # API 路由
+│   ├── router.py          # 路由注册
+│   ├── virtual_user.py    # 虚拟用户 API
+│   ├── interaction.py     # 互动 API
+│   ├── ai_model.py        # AI 模型 API
+│   ├── dashboard.py       # 控制台 API
+│   └── system_config.py   # 系统配置 API
+└── utils/                  # 工具函数
+```
+
+### 2.2 前端模块划分
+
+```
+frontend/src/
+├── main.js                # 应用入口
+├── App.vue                # 根组件
+├── router/                # 路由配置
+│   └── index.js
+├── api/                   # API 接口
+│   ├── request.js         # Axios 封装
+│   └── index.js           # API 定义
+├── views/                 # 页面组件
+│   ├── Dashboard.vue      # 控制台
+│   ├── VirtualUsers.vue   # 虚拟用户管理
+│   ├── Interactions.vue   # 互动记录
+│   ├── AIModels.vue       # AI 模型配置
+│   └── Settings.vue       # 系统设置
+├── components/            # 公共组件
+├── stores/                # Pinia 状态管理
+└── utils/                 # 工具函数
+```
+
+## 三、数据库设计
+
+### 3.1 ER 图
+
+```
+┌─────────────────┐       ┌──────────────────┐
+│ virtual_users   │       │ ai_model_configs │
+│─────────────────│       │──────────────────│
+│ id (PK)         │       │ id (PK)          │
+│ username        │       │ model_name       │
+│ password        │       │ provider         │
+│ nickname        │       │ api_key          │
+│ avatar_url      │       │ is_default       │
+│ writing_style   │       │ is_active        │
+│ activity_level  │       └──────────────────┘
+│ status          │
+│ session_token   │       ┌──────────────────┐
+│ total_interactions│     │ system_configs   │
+│ today_comments  │       │──────────────────│
+│ today_replies   │       │ id (PK)          │
+└────────┬────────┘       │ config_key       │
+         │                │ config_value     │
+         │ 1              │ config_type      │
+         │                └──────────────────┘
+         │ N
+┌────────▼────────┐       ┌──────────────────┐
+│interaction_records│      │ token_usages     │
+│─────────────────│       │──────────────────│
+│ id (PK)         │       │ id (PK)          │
+│ virtual_user_id │(FK)   │ virtual_user_id  │
+│ news_id         │       │ interaction_id   │
+│ news_title      │       │ tokens_used      │
+│ interaction_type│       │ ai_model         │
+│ content         │       │ action_type      │
+│ status          │       │ usage_date       │
+│ retry_count     │       └──────────────────┘
+│ tokens_used     │
+│ ai_model_used   │       ┌──────────────────┐
+└─────────────────┘       │ news_cache       │
+                          │──────────────────│
+                          │ id (PK)          │
+                          │ news_id          │
+                          │ title            │
+                          │ content          │
+                          │ category         │
+                          │ cache_date       │
+                          └──────────────────┘
+```
+
+### 3.2 核心表结构
+
+#### virtual_users (虚拟用户表)
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | INT | 主键 |
+| username | VARCHAR(100) | 用户名（唯一） |
+| password | VARCHAR(200) | 密码（加密） |
+| nickname | VARCHAR(100) | 昵称 |
+| avatar_url | VARCHAR(500) | 头像 URL |
+| writing_style | VARCHAR(50) | 写作风格 |
+| activity_level | ENUM | 活跃度（low/medium/high） |
+| persona_description | TEXT | AI 生成的人格描述 |
+| status | ENUM | 状态（active/disabled） |
+| is_logged_in | BOOLEAN | 是否已登录 |
+| session_token | VARCHAR(500) | 会话 Token |
+| total_interactions | INT | 总互动次数 |
+| today_comments | INT | 今日评论数 |
+| today_replies | INT | 今日回复数 |
+| created_at | DATETIME | 创建时间 |
+| updated_at | DATETIME | 更新时间 |
+
+#### interaction_records (互动记录表)
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | INT | 主键 |
+| virtual_user_id | INT | 虚拟用户 ID（外键） |
+| news_id | VARCHAR(100) | 新闻 ID |
+| news_title | VARCHAR(500) | 新闻标题 |
+| interaction_type | ENUM | 类型（comment/reply/like/favorite/share） |
+| content | TEXT | 互动内容 |
+| target_comment_id | VARCHAR(100) | 目标评论 ID（回复时） |
+| status | ENUM | 状态（pending/success/failed） |
+| retry_count | INT | 重试次数 |
+| error_message | TEXT | 错误信息 |
+| tokens_used | INT | 消耗 Token 数 |
+| execution_time | DATETIME | 执行时间 |
+
+## 四、核心流程设计
+
+### 4.1 虚拟用户生成流程
+
+```
+开始
+  │
+  ▼
+接收生成请求
+(count, styles, levels)
+  │
+  ▼
+循环 count 次
+  │
+  ├─► 生成唯一用户名
+  ├─► 随机生成昵称
+  ├─► 生成随机密码
+  ├─► 选择写作风格
+  ├─► 选择活跃度级别
+  ├─► 调用 AI 生成人格描述
+  ├─► 生成头像 URL
+  ├─► 保存到数据库
+  │
+  ▼
+返回生成的用户列表
+  │
+  ▼
+结束
+```
+
+### 4.2 自动互动执行流程
+
+```
+定时任务触发
+  │
+  ▼
+检查活动时间段
+  │
+  ├─否─► 跳过本次执行
+  │
+是
+  │
+  ▼
+获取活跃虚拟用户列表
+  │
+  ▼
+随机选择一个用户
+  │
+  ▼
+检查用户活跃度概率
+  │
+  ├─不通过─► 跳过
+  │
+通过
+  │
+  ▼
+检查今日限额
+  │
+  ├─超出─► 跳过
+  │
+未超出
+  │
+  ▼
+随机选择新闻
+  │
+  ▼
+确定互动类型
+(点赞/收藏/转发/评论/回复)
+  │
+  ▼
+如果是评论/回复
+  │
+  ├─► 调用 AI 生成内容
+  ├─► 记录 Token 消耗
+  │
+  ▼
+调用会会接口执行互动
+  │
+  ▼
+记录互动结果
+  │
+  ▼
+更新用户统计
+  │
+  ▼
+结束
+```
+
+### 4.3 AI 内容生成流程
+
+```
+接收生成请求
+(新闻内容，写作风格，人格)
+  │
+  ▼
+构建提示词 Prompt
+  │
+  ▼
+获取默认 AI 模型配置
+  │
+  ▼
+根据 provider 选择 SDK
+  │
+  ├─► OpenAI: 调用 GPT API
+  ├─► Zhipu: 调用 GLM API
+  ├─► Baidu: 调用文心 API
+  └─► Aliyun: 调用通义 API
+  │
+  ▼
+接收 AI 响应
+  │
+  ▼
+解析内容和 Token 数
+  │
+  ▼
+记录 Token 使用
+  │
+  ▼
+返回生成结果
+  │
+  ▼
+结束
+```
+
+## 五、API 设计规范
+
+### 5.1 RESTful API 规范
+
+所有 API 遵循 RESTful 设计风格：
+
+```
+GET    /api/v1/resource          # 获取资源列表
+GET    /api/v1/resource/{id}     # 获取单个资源
+POST   /api/v1/resource          # 创建资源
+PUT    /api/v1/resource/{id}     # 更新资源
+DELETE /api/v1/resource/{id}     # 删除资源
+POST   /api/v1/resource/action   # 资源操作
+```
+
+### 5.2 统一响应格式
+
+成功响应：
+```json
+{
+  "data": { ... },
+  "message": "success"
+}
+```
+
+列表响应：
+```json
+{
+  "total": 100,
+  "items": [ ... ]
+}
+```
+
+错误响应：
+```json
+{
+  "detail": "错误信息",
+  "status_code": 400
+}
+```
+
+### 5.3 分页参数
+
+```
+GET /api/v1/virtual-users?page=1&page_size=20
+```
+
+响应：
+```json
+{
+  "total": 100,
+  "items": [...],
+  "page": 1,
+  "page_size": 20
+}
+```
+
+## 六、安全设计
+
+### 6.1 认证授权
+
+- JWT Token 认证
+- Token 有效期 7 天
+- 支持刷新 Token
+
+### 6.2 数据安全
+
+- 密码加密存储（bcrypt）
+- API Key 加密存储
+- SQL 注入防护（ORM 参数化）
+- XSS 防护（前端输入过滤）
+
+### 6.3 限流策略
+
+- API 请求限流
+- Token 消耗限额
+- 单用户互动频次限制
+
+## 七、性能优化
+
+### 7.1 数据库优化
+
+- 索引优化（username, status, execution_time）
+- 分页查询
+- 批量操作
+
+### 7.2 缓存策略
+
+- 新闻数据缓存
+- 系统配置缓存
+- 字典数据缓存
+
+### 7.3 并发控制
+
+- 数据库连接池（20-60）
+- 异步 IO（FastAPI + asyncio）
+- 定时任务并发控制
+
+## 八、扩展性设计
+
+### 8.1 插件化 AI 模型
+
+支持通过配置添加新的 AI 模型提供商，无需修改代码。
+
+### 8.2 可配置的互动策略
+
+所有互动参数可通过系统配置调整：
+- 互动概率
+- 活跃度分级
+- 时间段控制
+
+### 8.3 模块化设计
+
+各功能模块独立，易于扩展新功能：
+- 新增互动类型
+- 新增数据源
+- 新增统计维度
+
+## 九、监控与日志
+
+### 9.1 日志系统
+
+- 应用日志（INFO/WARNING/ERROR）
+- 访问日志
+- 慢查询日志
+- 日志轮转（保留 30 天）
+
+### 9.2 健康检查
+
+```bash
+GET /health
+```
+
+响应：
+```json
+{
+  "status": "healthy",
+  "scheduler_running": true
+}
+```
+
+### 9.3 指标监控
+
+- API 响应时间
+- 数据库查询性能
+- AI 调用成功率
+- Token 消耗速率
+
+---
+
+**文档版本**: v1.0  
+**更新日期**: 2026-03-23