说明书上传

This commit is contained in:
liuwei
2025-03-13 16:47:16 +08:00
parent c897c40370
commit a559dcaaf0

853
产品需求说明书.md Normal file
View File

@@ -0,0 +1,853 @@
# WeChatRobot 项目需求规格说明书
## 文档信息
| 文档名称 | WeChatRobot 项目需求规格说明书 |
| :------ | :--------------------------- |
| 版本号 | V1.0 |
| 状态 | 初稿 |
| 创建日期 | 2024年5月 |
## 目录
1. [项目概述](#1-项目概述)
1. [项目背景](#11-项目背景)
2. [项目目标](#12-项目目标)
3. [适用范围](#13-适用范围)
2. [系统架构](#2-系统架构)
1. [总体架构](#21-总体架构)
2. [核心组件](#22-核心组件)
3. [技术栈](#23-技术栈)
4. [系统依赖](#24-系统依赖)
3. [功能需求](#3-功能需求)
1. [基础功能](#31-基础功能)
2. [特色功能](#32-特色功能)
3. [管理功能](#33-管理功能)
4. [命令系统](#4-命令系统)
1. [通用命令](#41-通用命令)
2. [游戏任务命令](#42-游戏任务命令)
3. [积分交易命令](#43-积分交易命令)
4. [管理命令](#44-管理命令)
5. [数据模型](#5-数据模型)
1. [数据库设计](#51-数据库设计)
2. [缓存设计](#52-缓存设计)
6. [非功能需求](#6-非功能需求)
1. [性能需求](#61-性能需求)
2. [安全需求](#62-安全需求)
3. [可扩展性](#63-可扩展性)
4. [可靠性](#64-可靠性)
7. [部署要求](#7-部署要求)
1. [环境依赖](#71-环境依赖)
2. [第三方服务](#72-第三方服务)
3. [部署流程](#73-部署流程)
8. [未来扩展计划](#8-未来扩展计划)
9. [附录](#9-附录)
1. [术语表](#91-术语表)
2. [参考文档](#92-参考文档)
## 1. 项目概述
### 1.1 项目背景
随着微信在社交和工作场景中的广泛应用用户对于微信自动化管理、智能回复、群聊管理等需求日益增长。WeChatRobot 项目旨在满足这些需求,提供一个功能丰富、易于扩展的微信机器人解决方案,帮助用户提高沟通效率、增强群聊体验、实现自动化管理。
### 1.2 项目目标
1. 开发一个基于 Python 的微信机器人系统,实现微信消息的自动化处理
2. 提供丰富的功能模块包括但不限于AI 对话、群聊管理、游戏任务、积分系统等
3. 支持多种 AI 模型接入,提供智能对话能力
4. 实现群聊内容的自动化总结和分析
5. 提供用户友好的管理界面,便于配置和监控
6. 设计可扩展的架构,便于后续功能扩展
### 1.3 适用范围
本系统适用于以下场景:
- 个人用户:提升微信使用体验,自动化处理日常消息
- 群组管理员:辅助管理微信群,提高群聊活跃度
- 企业用户:用于客户服务、内部沟通自动化等场景
- 开发者:作为微信自动化的基础框架,进行二次开发
## 2. 系统架构
### 2.1 总体架构
WeChatRobot 采用模块化设计,主要由以下几个部分组成:
- 核心引擎:负责与微信客户端交互,处理消息收发
- 功能模块:提供各种具体功能的实现
- 数据存储:管理系统数据和状态
- 管理界面:提供配置和监控功能
系统架构图如下:
```
+------------------+ +------------------+ +------------------+
| | | | | |
| 微信客户端 |<--->| WeChatRobot |<--->| 数据存储 |
| (wcferry) | | 核心引擎 | | (MySQL/Redis) |
| | | | | |
+------------------+ +--------+---------+ +------------------+
|
|
+--------v---------+
| |
| 功能模块 |
| |
+--------+---------+
|
|
+--------v---------+
| |
| Web管理界面 |
| (Flask) |
| |
+------------------+
```
### 2.2 核心组件
1. **主程序模块**
- 负责系统初始化和启动
- 协调各功能模块的工作
- 处理系统级事件
2. **机器人核心**
- 与微信客户端交互
- 消息分发与处理
- 命令解析与执行
3. **功能模块**
- AI 对话模块:集成多种 AI 模型
- 群聊管理模块:处理群成员变动、自动欢迎等
- 游戏任务模块:实现百科问答游戏
- 积分系统模块:管理用户积分和交易
- 签到模块:实现每日签到功能
- 消息总结模块:自动总结群聊内容
4. **数据存储层**
- MySQL 数据库:存储持久化数据
- Redis 缓存:存储临时数据和状态
5. **Web 界面**
- 基于 Flask 的管理界面
- 提供配置和监控功能
### 2.3 技术栈
1. **编程语言**
- Python 3.x
2. **框架与库**
- wcferry微信客户端接口
- FlaskWeb 框架
- MySQL Connector数据库连接
- Redis缓存服务
- RequestsHTTP 客户端
- Schedule定时任务
- Pandas数据处理
- Jupyter Client代码执行
3. **AI 接口**
- OpenAI API
- 豆包 API (Doubao)
- TigerBot API
- 智谱 API (ZhipuAI)
- Google Generative AI
4. **前端技术**
- HTML/CSS/JavaScript
- Bootstrap可选
### 2.4 系统依赖
详细的系统依赖列表(基于 requirements.txt
- chinese_calendar~=1.10.0:中国节假日判断
- lxml~=5.3.0XML 处理
- openai>1.0.0OpenAI API 接口
- pandas~=2.2.3:数据处理
- pyyaml~=6.0.2YAML 配置文件处理
- requests~=2.32.3HTTP 请求
- schedule~=1.2.2:定时任务
- wcferry==39.2.*:微信客户端接口
- redis~=5.2.1Redis 缓存
- PyMySQL~=1.1.1MySQL 数据库连接
- Flask~=3.1.0Web 框架
- mysql-connector-python~=9.2.0MySQL 连接器
- pytz~=2025.1:时区处理
- 其他辅助库(详见 requirements.txt
## 3. 功能需求
### 3.1 基础功能
#### 3.1.1 消息处理
**功能描述**
系统能够接收、处理和响应各类微信消息,包括个人消息和群聊消息。
**详细需求**
1. **消息接收**
- 接收文本消息、图片消息、视频消息、语音消息等多种类型
- 支持群聊和私聊消息的区分处理
2. **消息存储**
- 将消息存储到数据库中,包含以下信息:
- 消息ID
- 群ID如适用
- 发送者ID
- 消息内容
- 消息类型
- 时间戳
- 附件URL如适用
- 消息XML如适用
- 缩略图(如适用)
3. **消息过滤**
- 过滤无效或垃圾消息
- 支持关键词过滤
- 支持特定消息类型的过滤
4. **消息响应**
- 根据预设规则自动响应特定消息
- 支持命令触发的响应
- 支持AI模型生成的智能响应
#### 3.1.2 群聊管理
**功能描述**
系统能够监控和管理微信群聊,包括成员变动、自动欢迎等功能。
**详细需求**
1. **成员变动监控**
- 检测群成员加入和退出事件
- 记录成员变动历史
- 提供成员变动通知
2. **自动欢迎**
- 当新成员加入群聊时,自动发送欢迎消息
- 支持自定义欢迎消息模板
- 支持群组特定的欢迎设置
3. **群聊邀请管理**
- 支持通过命令添加群聊
- 管理群聊邀请关系
- 提供群聊列表查询功能
4. **群成员信息管理**
- 缓存群成员信息
- 提供群成员信息查询功能
- 支持群成员昵称与ID的映射
#### 3.1.3 AI 对话
**功能描述**
系统集成多种AI模型提供智能对话能力。
**详细需求**
1. **多模型支持**
- 支持豆包(Doubao)模型
- 支持TigerBot模型
- 支持ChatGLM模型
- 支持OpenAI模型
- 支持其他可扩展的AI模型
2. **上下文对话**
- 维护对话历史
- 支持上下文相关的回复
- 限制对话历史长度避免token过多
3. **自定义系统提示词**
- 支持为不同AI模型设置系统提示词
- 支持根据不同场景切换提示词
4. **对话统计**
- 记录token使用情况
- 提供对话性能统计
- 支持对话质量评估
### 3.2 特色功能
#### 3.2.1 群聊总结
**功能描述**
系统能够自动总结群聊内容,识别热门话题和活跃成员。
**详细需求**
1. **内容总结**
- 定期(如每日)总结群聊内容
- 提取关键话题和重要信息
- 生成结构化的总结报告
2. **话题识别**
- 自动识别群聊中的热门话题
- 对话题进行分类和评分
- 提供话题参与度分析
3. **成员活跃度分析**
- 识别最活跃的群成员
- 统计成员发言频率和质量
- 生成"今日MVP"等趣味性内容
4. **总结展示**
- 以轻松幽默的风格展示总结
- 融入网络流行语和Emoji
- 提供数据概览、话题概览、贡献者识别等内容
#### 3.2.2 游戏任务系统
**功能描述**
系统提供百科问答游戏功能,支持任务分配、答案验证和积分奖励。
**详细需求**
1. **任务管理**
- 支持随机分配任务
- 维护任务状态(待完成、已完成)
- 提供任务查询功能
2. **答案验证**
- 验证用户提交的答案
- 支持部分正确的评分
- 提供答案反馈和提示
3. **积分系统**
- 根据答案正确性奖励积分
- 支持积分扣除(如答错扣分)
- 维护用户积分余额
4. **排行榜**
- 提供群内用户积分排行
- 支持定期(如每周)排行榜更新
- 展示排行榜前N名用户
#### 3.2.3 积分交易系统
**功能描述**
系统支持用户间的积分转账和交易功能。
**详细需求**
1. **积分转账**
- 支持用户间积分转移
- 验证转账合法性(如余额检查)
- 记录转账历史
2. **积分查询**
- 提供用户积分余额查询
- 支持积分历史记录查询
- 展示积分来源和去向
3. **积分奖惩**
- 支持管理员奖励或扣除用户积分
- 提供积分奖惩理由记录
- 支持批量积分操作
#### 3.2.4 签到系统
**功能描述**
系统提供每日签到功能,支持签到统计和奖励机制。
**详细需求**
1. **每日签到**
- 支持用户每日签到
- 限制每日签到次数(每人每天一次)
- 自动重置每日签到计数
2. **签到奖励**
- 签到成功后给予积分奖励
- 支持连续签到额外奖励
- 支持特殊日期(如节假日)额外奖励
3. **签到统计**
- 记录用户签到历史
- 统计连续签到天数
- 提供签到排行榜
4. **时区支持**
- 根据配置的时区判断日期变更
- 支持不同地区用户的签到需求
#### 3.2.5 定时提醒
**功能描述**
系统能够根据预设规则发送定时提醒消息。
**详细需求**
1. **工作报告提醒**
- 支持日报、周报、月报提醒
- 自动识别工作日和非工作日
- 在适当时间发送提醒消息
2. **自定义提醒**
- 支持用户设置自定义提醒
- 提供提醒时间和内容的配置
- 支持重复提醒设置
3. **节假日识别**
- 集成中国节假日日历
- 在节假日发送特定消息
- 支持节假日前的工作安排提醒
### 3.3 管理功能
#### 3.3.1 Web 管理界面
**功能描述**
系统提供基于 Web 的管理界面,便于配置和监控。
**详细需求**
1. **消息管理**
- 查看历史消息记录
- 支持消息搜索和过滤
- 提供消息统计和分析
2. **群组配置**
- 管理群组列表
- 配置群组特定的功能设置
- 监控群组活跃度
3. **功能开关**
- 提供全局功能开关
- 支持群组级别的功能开关
- 记录功能状态变更历史
4. **系统监控**
- 监控系统运行状态
- 提供资源使用情况统计
- 支持异常情况告警
#### 3.3.2 权限管理
**功能描述**
系统提供多级权限管理,控制不同用户对功能的访问权限。
**详细需求**
1. **权限级别**
- 系统管理员:拥有所有权限
- 群组管理员:拥有特定群组的管理权限
- 普通用户:拥有基本功能使用权限
2. **功能权限**
- 控制特定功能的使用权限
- 支持按群组设置功能权限
- 提供权限变更审计
3. **用户管理**
- 管理用户账号和权限
- 支持用户封禁和解封
- 记录用户操作日志
## 4. 命令系统
### 4.1 通用命令
**功能描述**
系统提供一系列通用命令,用于基本功能的触发和控制。
**详细需求**
1. **帮助命令**
- `/help`:显示帮助信息
- `/menu`:显示功能菜单
2. **功能开关命令**
- 启用/禁用特定功能的命令
- 查询功能状态的命令
3. **系统信息命令**
- 查询系统状态
- 查询版本信息
### 4.2 游戏任务命令
**功能描述**
系统提供一系列命令,用于游戏任务系统的操作。
**详细命令列表**
1. `/s`:加入游戏(可选)
- 功能:显式加入游戏系统
- 响应:确认加入的消息
2. `/ts`:查看活跃任务
- 功能:显示当前活跃的任务列表
- 响应:活跃任务的详细信息
3. `/l`:列出未完成任务
- 功能:显示所有未完成的任务
- 响应:未完成任务的列表
4. `/a [任务ID] [答案]`:提交答案
- 功能:提交特定任务的答案
- 参数任务ID和答案内容
- 响应:答案验证结果和积分变更
5. `/r`:查看排行榜
- 功能:显示积分排行榜
- 响应:排行榜信息
6. `/ag`:手动添加群聊(可选)
- 功能:将当前群聊添加到游戏系统
- 响应:添加结果确认
7. `/t`:获取新任务
- 功能:获取一个随机任务
- 响应:新任务的详细信息
- 限制仅在特定时间段9:00-22:59可用
### 4.3 积分交易命令
**功能描述**
系统提供积分交易相关的命令,支持用户间的积分转移。
**详细命令列表**
1. `积分转账 积分数 @用户`:转账积分
- 功能:将指定数量的积分转给目标用户
- 参数:积分数量和目标用户
- 响应:转账结果确认
2. 命令别名:
- `积分交易`
- `积分赠送`
- `积分转移`
- `转账积分`
- `赠送积分`
- `转移积分`
- `送积分`
- `积分送人`
- `送人积分`
- `积分赠予`
- `赠予`
### 4.4 管理命令
**功能描述**
系统提供一系列管理命令,用于系统配置和管理。
**详细命令列表**
1. **群组管理命令**
- 添加/删除群组
- 配置群组特定设置
2. **功能配置命令**
- 启用/禁用特定功能
- 配置功能参数
3. **用户管理命令**
- 添加/删除用户
- 设置用户权限
## 5. 数据模型
### 5.1 数据库设计
**功能描述**
系统使用 MySQL 数据库存储持久化数据。
**主要数据表**
1. **消息表messages**
- 字段:
- id消息ID
- group_id群ID
- timestamp时间戳
- sender发送者ID
- content消息内容
- message_type消息类型
- attachment_url附件URL
- message_id微信消息ID
- message_xml消息XML
- message_thumb消息缩略图
2. **用户表t_encyclopedia_players**
- 字段:
- player_id用户ID
- group_id群ID
- player_name用户名称
- points积分
- join_time加入时间
3. **任务表t_encyclopedia_active_tasks**
- 字段:
- active_task_id任务ID
- group_id群ID
- question问题
- answer答案
- score分数
- holder_id持有者ID
- status状态pending/completed
4. **任务历史表t_encyclopedia_task_history**
- 字段:
- id记录ID
- group_id群ID
- active_task_id任务ID
- player_id用户ID
- answer提交的答案
- is_correct是否正确
- points_earned获得的积分
5. **签到表**
- 字段:
- id记录ID
- user_id用户ID
- group_id群ID
- sign_time签到时间
- continuous_days连续签到天数
### 5.2 缓存设计
**功能描述**
系统使用 Redis 缓存存储临时数据和状态。
**主要缓存数据**
1. **群成员信息**
- 键格式:`group:group_members:{group_id}`
- 值类型哈希表wxid -> nickname
- 用途:缓存群成员信息,避免频繁查询
2. **群成员数量**
- 键格式:`group:group_member_count:{group_id}`
- 值类型:字符串(数字)
- 用途:记录群成员数量
3. **签到记录**
- 键格式:`group:sign_in:{group_id}:{user_id}`
- 值类型:字符串(时间戳)
- 用途:记录用户签到状态
4. **最后总结时间**
- 键格式:`{group_id}:summary_time`
- 值类型:字符串(时间戳)
- 用途:记录群聊最后总结的时间
5. **对话历史**
- 内存缓存非Redis
- 结构字典wxid -> 消息列表)
- 用途维护AI对话的上下文
## 6. 非功能需求
### 6.1 性能需求
**功能描述**
系统需要满足一定的性能要求,确保良好的用户体验。
**详细需求**
1. **响应时间**
- 普通命令响应时间不超过1秒
- AI生成内容响应时间不超过10秒
- 数据库查询响应时间不超过2秒
2. **并发处理**
- 支持多个群组同时活跃
- 支持多用户并发请求
- 避免资源竞争和死锁
3. **资源使用**
- CPU使用率平均不超过50%
- 内存使用合理,避免内存泄漏
- 数据库连接池管理,避免连接耗尽
### 6.2 安全需求
**功能描述**
系统需要确保数据安全和用户隐私保护。
**详细需求**
1. **数据安全**
- 敏感配置信息加密存储
- API密钥安全管理
- 数据库访问权限控制
2. **用户隐私**
- 遵循最小权限原则收集用户信息
- 不存储不必要的敏感信息
- 提供隐私政策说明
3. **防滥用措施**
- 命令频率限制
- 异常行为检测
- 防止恶意使用系统资源
### 6.3 可扩展性
**功能描述**
系统设计需要考虑未来的扩展需求。
**详细需求**
1. **模块化设计**
- 功能模块之间低耦合
- 提供清晰的接口定义
- 支持插件式扩展
2. **配置灵活性**
- 支持通过配置文件调整系统行为
- 避免硬编码配置项
- 支持运行时配置更新
3. **AI模型扩展**
- 支持新AI模型的便捷接入
- 统一的AI接口抽象
- 模型切换不影响系统稳定性
### 6.4 可靠性
**功能描述**
系统需要具备良好的可靠性和稳定性。
**详细需求**
1. **错误处理**
- 全面的异常捕获和处理
- 避免单点故障导致系统崩溃
- 提供友好的错误提示
2. **日志系统**
- 详细的操作日志记录
- 错误日志分级管理
- 支持日志查询和分析
3. **自动恢复**
- 系统异常时自动重试
- 关键服务自动重启
- 数据一致性保障
## 7. 部署要求
### 7.1 环境依赖
**功能描述**
系统运行需要特定的环境依赖。
**详细需求**
1. **操作系统**
- Windows 10/11推荐
- 支持其他操作系统(可选)
2. **Python环境**
- Python 3.8+
- 虚拟环境管理(推荐)
3. **数据库环境**
- MySQL 5.7+
- Redis 5.0+
4. **网络环境**
- 稳定的互联网连接
- 支持HTTPS请求
### 7.2 第三方服务
**功能描述**
系统依赖一些第三方服务和API。
**详细需求**
1. **AI服务**
- 豆包API访问权限
- TigerBot API访问权限
- OpenAI API访问权限可选
- 其他AI服务提供商的API
2. **微信接口**
- wcferry库及其依赖
- 微信PC客户端
3. **其他服务**
- 中国节假日数据服务
- 时区服务
### 7.3 部署流程
**功能描述**
系统部署需要遵循特定的流程。
**详细需求**
1. **环境准备**
- 安装 Python 3.8+
- 安装 MySQL 和 Redis
- 配置虚拟环境
2. **代码部署**
- 克隆或下载代码仓库
- 安装依赖包:`pip install -r requirements.txt`
- 配置系统参数
3. **数据库初始化**
- 创建 MySQL 数据库和表结构
- 初始化 Redis 缓存
- 导入基础数据(如有)
4. **配置文件设置**
- 复制 `config.yaml.template``config.yaml`
- 设置 AI 模型 API 密钥
- 配置数据库连接参数
- 设置其他系统参数
5. **启动系统**
- 启动微信客户端
- 运行主程序:`python main.py`
- 验证系统功能
## 8. 未来扩展计划
**功能描述**
系统计划在未来版本中实现的功能和改进。
**详细计划**
1. **功能扩展**
- 更多游戏类型支持
- 语音识别和处理
- 图像识别和处理
- 多语言支持
2. **性能优化**
- 消息处理流程优化
- 数据库查询优化
- 缓存策略改进
3. **用户体验提升**
- 移动端管理界面
- 更丰富的数据可视化
- 个性化配置选项
4. **AI能力增强**
- 更多AI模型集成
- 多模态内容生成
- 自定义模型训练
5. **生态系统建设**
- 插件系统
- 开发者文档
- 社区贡献机制
## 9. 附录
### 9.1 术语表
| 术语 | 描述 |
| ---- | ---- |
| wcferry | 微信客户端接口库,用于与微信进行交互 |
| AI模型 | 人工智能模型如豆包、TigerBot等用于生成智能回复 |
| 积分系统 | 用户在系统中获取和使用的虚拟货币系统 |
| 任务系统 | 百科问答游戏的核心功能模块 |
| Redis | 内存数据库,用于缓存临时数据 |
| MySQL | 关系型数据库,用于存储持久化数据 |
| Flask | Python Web框架用于构建管理界面 |
| Token | AI模型处理文本的计量单位 |
### 9.2 参考文档
1. Python 官方文档https://docs.python.org/
2. Flask 文档https://flask.palletsprojects.com/
3. MySQL 文档https://dev.mysql.com/doc/
4. Redis 文档https://redis.io/documentation
5. wcferry 文档参考项目GitHub页面
6. 各AI模型API文档参考各服务提供商官方文档
---
本文档详细描述了 WeChatRobot 项目的需求规格,为开发团队提供了明确的开发指导。随着项目的进展,本文档可能会进行更新和补充。