diff --git a/产品需求说明书.md b/产品需求说明书.md new file mode 100644 index 0000000..34a8546 --- /dev/null +++ b/产品需求说明书.md @@ -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：微信客户端接口 + - Flask：Web 框架 + - MySQL Connector：数据库连接 + - Redis：缓存服务 + - Requests：HTTP 客户端 + - 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.0：XML 处理 +- openai>1.0.0：OpenAI API 接口 +- pandas~=2.2.3：数据处理 +- pyyaml~=6.0.2：YAML 配置文件处理 +- requests~=2.32.3：HTTP 请求 +- schedule~=1.2.2：定时任务 +- wcferry==39.2.*：微信客户端接口 +- redis~=5.2.1：Redis 缓存 +- PyMySQL~=1.1.1：MySQL 数据库连接 +- Flask~=3.1.0：Web 框架 +- mysql-connector-python~=9.2.0：MySQL 连接器 +- 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 项目的需求规格，为开发团队提供了明确的开发指导。随着项目的进展，本文档可能会进行更新和补充。 \ No newline at end of file