# DeepSeek Chat 开发文档 ## 1. 项目概述 ### 1.1 项目简介 DeepSeek Chat 是一个基于 DeepSeek API 的智能聊天应用，提供了用户认证、聊天对话、日程管理和待办事项等功能。该应用采用模块化设计，便于扩展和维护，同时提供了友好的用户界面。 ### 1.2 主要功能 - **用户认证**：支持用户注册、登录和会话管理 - **智能聊天**：与 DeepSeek API 集成，提供智能对话功能 - **聊天历史**：支持保存和管理聊天历史记录 - **日程管理**：创建、编辑、删除和查询日程安排 - **待办事项**：创建、标记完成和删除待办事项 - **日志管理**：记录系统操作和用户行为日志 ### 1.3 技术栈 - **编程语言**：Python 3.9+ - **GUI框架**：Tkinter + CustomTkinter - **API集成**：DeepSeek API - **数据存储**：JSON文件 - **打包工具**：PyInstaller ## 2. 系统架构 ### 2.1 整体架构设计 DeepSeek Chat 采用模块化分层架构，主要分为以下几个层次： 1. **用户界面层**：负责与用户交互，包括登录界面、聊天界面、日程管理界面等 2. **业务逻辑层**：处理核心业务逻辑，如用户认证、聊天管理、日程管理等 3. **数据访问层**：负责数据的存储和检索，使用JSON文件作为数据存储格式 4. **外部服务层**：与外部API交互，主要是DeepSeek API ### 2.2 模块划分 | 模块名称 | 主要职责 | 文件位置 | |---------|---------|---------| | 认证模块 | 用户注册、登录和会话管理 | auth/ | | 聊天模块 | 聊天功能实现和API交互 | chat/ | | 对话管理 | 聊天历史记录管理 | conversation/ | | 日程管理 | 日程安排的创建、编辑和查询 | schedule/ | | 待办事项 | 待办任务的管理 | todo/ | | 用户界面 | 应用程序的UI组件 | ui/ | | 日志管理 | 系统日志的记录和查看 | logger/ | | 配置管理 | 应用程序配置 | config/ | ### 2.3 核心组件关系 ``` ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ 用户界面层 │────▶│ 业务逻辑层 │────▶│ 数据访问层 │ └─────────────┘ └──────┬──────┘ └─────────────┘ │ ▼ ┌─────────────┐ ┌─────────────┐ │ 外部服务层 │◀────│ 配置管理 │ └─────────────┘ └─────────────┘ ``` ### 2.4 数据流图 1. **用户登录流程**： - 用户输入用户名和密码 - 认证模块验证用户信息 - 生成会话ID并保存到会话文件 - 返回登录结果给用户界面 2. **聊天消息流程**： - 用户在聊天界面输入消息 - 聊天模块处理消息 - 调用DeepSeek API获取回复 - 保存聊天记录到JSON文件 - 更新聊天界面显示 3. **日程管理流程**： - 用户在日程界面创建日程 - 日程管理模块处理日程数据 - 保存日程到JSON文件 - 更新日程界面显示 ## 3. 功能模块详细设计 ### 3.1 用户认证模块 (auth) #### 3.1.1 模块概述 用户认证模块负责用户的注册、登录和会话管理，确保只有授权用户可以访问应用程序的功能。 #### 3.1.2 主要功能 - 用户注册：创建新用户账户 - 用户登录：验证用户身份并创建会话 - 会话管理：维护用户会话状态 - 密码验证：确保密码安全 #### 3.1.3 核心类和方法 **UserAuth 类** (auth/user_auth.py) - `register_user(username, password)`: 注册新用户 - `login_user(username, password)`: 用户登录 - `validate_session(session_id)`: 验证会话有效性 - `logout_user(session_id)`: 用户登出 **UserAuthUI 类** (auth/user_auth_ui.py) - `show_login_window()`: 显示登录窗口 - `show_register_window()`: 显示注册窗口 - `on_login()`: 处理登录事件 - `on_register()`: 处理注册事件 #### 3.1.4 数据结构 ```json // 用户数据结构 { "username": "string", "password": "string", // 加密存储 "created_at": "timestamp" } // 会话数据结构 { "session_id": "string", "username": "string", "created_at": "timestamp", "last_active": "timestamp" } ``` ### 3.2 聊天模块 (chat) #### 3.2.1 模块概述 聊天模块负责实现与DeepSeek API的交互，处理用户消息并获取AI回复。 #### 3.2.2 主要功能 - 发送消息到DeepSeek API - 处理API响应 - 管理聊天上下文 - 支持流式响应 #### 3.2.3 核心类和方法 **ChatManager 类** (chat/chat_manager.py) - `send_message(message, username)`: 发送消息并获取回复 - `_get_ai_response(message, history)`: 调用DeepSeek API获取AI回复 - `update_chat_display(message, is_user)`: 更新聊天界面显示 **DeepSeekAPI 类** (chat/deepseek_api.py) - `generate_response(message, history)`: 调用DeepSeek API生成响应 - `_build_request_body(message, history)`: 构建API请求体 - `_handle_stream_response(response)`: 处理流式响应 ### 3.3 对话管理模块 (conversation) #### 3.3.1 模块概述 对话管理模块负责保存和管理用户的聊天历史记录。 #### 3.3.2 主要功能 - 保存聊天历史 - 加载聊天历史 - 清除聊天历史 - 管理多个对话 #### 3.3.3 核心类和方法 **ConversationManager 类** (conversation/conversation_manager.py) - `save_message(username, message, is_user)`: 保存消息到历史记录 - `load_history(username)`: 加载用户的聊天历史 - `clear_history(username)`: 清除用户的聊天历史 - `get_conversation_list(username)`: 获取用户的对话列表 ### 3.4 日程管理模块 (schedule) #### 3.4.1 模块概述 日程管理模块允许用户创建、编辑、删除和查询日程安排。 #### 3.4.2 主要功能 - 创建新日程 - 更新日程信息 - 删除日程 - 按日期查询日程 #### 3.4.3 核心类和方法 **ScheduleManager 类** (schedule/schedule_manager.py) - `create_schedule(username, date, title, description, start_time, end_time)`: 创建新日程 - `update_schedule(username, schedule_id, date, title, description, start_time, end_time)`: 更新日程 - `delete_schedule(username, schedule_id)`: 删除日程 - `get_schedules_by_date(username, date)`: 按日期查询日程 ### 3.5 待办事项模块 (todo) #### 3.5.1 模块概述 待办事项模块允许用户创建、标记完成和删除待办任务。 #### 3.5.2 主要功能 - 创建新待办事项 - 标记待办事项为已完成 - 删除待办事项 - 获取待处理的待办事项 #### 3.5.3 核心类和方法 **TodoManager 类** (todo/todo_manager.py) - `create_todo(username, title, description, due_date)`: 创建新待办事项 - `complete_todo(username, todo_id)`: 标记待办事项为已完成 - `delete_todo(username, todo_id)`: 删除待办事项 - `get_pending_todos(username)`: 获取待处理的待办事项 ### 3.6 用户界面模块 (ui) #### 3.6.1 模块概述 用户界面模块负责应用程序的所有UI组件和交互逻辑，提供友好的用户体验。 #### 3.6.2 主要功能 - 聊天界面 - 登录/注册界面 - 日程管理界面 - 待办事项界面 - 日志查看界面 #### 3.6.3 核心类和方法 **DeepSeekChatUI 类** (ui/chat_ui.py) - `__init__(root)`: 初始化聊天界面 - `setup_ui()`: 设置UI组件 - `setup_events()`: 绑定事件处理 - `on_send_message()`: 处理发送消息事件 **UIComponents 类** (ui/ui_components.py) - `create_button()`: 创建按钮组件 - `create_entry()`: 创建输入框组件 - `create_label()`: 创建标签组件 - `create_frame()`: 创建框架组件 ### 3.7 日志管理模块 (logger) #### 3.7.1 模块概述 日志管理模块负责记录系统操作和用户行为日志，便于调试和监控。 #### 3.7.2 主要功能 - 记录不同级别的日志 - 保存日志到文件 - 查看和过滤日志 #### 3.7.3 核心类和方法 **LoggerManager 类** (logger/logger_manager.py) - `log(level, message, username)`: 记录日志 - `show_logs()`: 显示日志查看窗口 - `save_logs()`: 保存日志到文件 - `load_logs()`: 加载日志 ### 3.8 配置管理模块 (config) #### 3.8.1 模块概述 配置管理模块负责管理应用程序的配置参数，如API密钥、路径设置等。 #### 3.8.2 主要功能 - 加载配置文件 - 获取配置参数 - 更新配置参数 #### 3.8.3 核心类和方法 **Config 类** (config/config.py) - `load_config()`: 加载配置文件 - `get_config(key)`: 获取配置参数 - `set_config(key, value)`: 设置配置参数 ## 4. 技术栈详细说明 ### 4.1 Python 3.9+ #### 4.1.1 安装 ```bash # 使用conda安装 conda create -n deepseek_chat python=3.9 conda activate deepseek_chat # 使用pip安装依赖 pip install -r requirements.txt ``` ### 4.2 Tkinter + CustomTkinter #### 4.2.1 概述 Tkinter是Python标准库中的GUI工具包，CustomTkinter是一个第三方库，提供了现代化的UI组件。 #### 4.2.2 安装 ```bash pip install customtkinter ``` #### 4.2.3 主要组件 - CTk: 主窗口组件 - CTkFrame: 框架组件 - CTkButton: 按钮组件 - CTkEntry: 输入框组件 - CTkTextbox: 文本框组件 - CTkLabel: 标签组件 ### 4.3 DeepSeek API #### 4.3.1 概述 DeepSeek API提供智能对话功能，支持多轮对话和上下文管理。 #### 4.3.2 配置 在config/config.py文件中设置API密钥： ```python class Config: API_KEY = "your_api_key_here" API_URL = "https://api.deepseek.com/v1/chat/completions" ``` ### 4.4 JSON数据存储 #### 4.4.1 概述 应用程序使用JSON文件作为数据存储格式，便于读取和修改。 #### 4.4.2 数据文件位置 - 用户数据: data/users/users.json - 会话数据: data/sessions/sessions.json - 聊天历史: data/chat_history/ - 日程数据: data/schedule/ - 待办数据: data/todo/ - 日志数据: data/app_logs.json ### 4.5 PyInstaller #### 4.5.1 概述 PyInstaller用于将Python应用程序打包为可执行文件(.exe)。 #### 4.5.2 安装 ```bash pip install pyinstaller ``` #### 4.5.3 打包命令 ```bash pyinstaller -F -w -i assets/app_icon.ico -p . core/main.py ``` ## 5. 开发环境搭建 ### 5.1 系统要求 - **操作系统**: Windows 10/11, macOS 10.15+, Linux (Ubuntu 18.04+) - **Python版本**: 3.9或更高版本 - **内存**: 至少4GB RAM - **磁盘空间**: 至少10GB可用空间 ### 5.2 安装步骤 #### 5.2.1 克隆或下载项目 ```bash # 克隆项目（如果使用Git） git clone cd deepseek_chat # 或直接下载并解压项目文件 ``` #### 5.2.2 创建虚拟环境 **使用Python内置venv** ```bash # Windows python -m venv venv source venv/Scripts/activate # macOS/Linux python3 -m venv venv source venv/bin/activate ``` **使用conda** ```bash conda create -n deepseek_chat python=3.9 conda activate deepseek_chat ``` #### 5.2.3 安装依赖 ```bash # 安装主要依赖 pip install -r requirements.txt # 安装开发依赖（如果有） pip install -r requirements-dev.txt ``` #### 5.2.4 配置API密钥 1. 访问DeepSeek官网获取API密钥 2. 打开`config/config.py`文件 3. 将`API_KEY`字段替换为您的实际API密钥 ```python class Config: API_KEY = "your_actual_api_key_here" API_URL = "https://api.deepseek.com/v1/chat/completions" ``` #### 5.2.5 测试运行 ```bash # 运行主程序 python core/main.py ``` 如果一切正常，您应该会看到DeepSeek Chat应用程序的登录窗口。 ### 5.3 开发工具推荐 - **IDE**: PyCharm Community Edition 或 Visual Studio Code - **代码版本控制**: Git - **调试工具**: PyCharm调试器或VS Code调试器 - **UI设计工具**: Tkinter Designer (可选) ### 5.4 常见问题解决 #### 5.4.1 模块导入错误 如果遇到模块导入错误，确保： 1. 虚拟环境已激活 2. 所有依赖都已正确安装 3. 项目根目录在Python路径中 可以通过以下命令添加项目根目录到Python路径： ```bash # Windows set PYTHONPATH=%PYTHONPATH%;. # macOS/Linux export PYTHONPATH=$PYTHONPATH:. ``` #### 5.4.2 API连接错误 如果无法连接到DeepSeek API，检查： 1. API密钥是否正确 2. 网络连接是否正常 3. 防火墙设置是否允许应用程序访问网络 ## 6. 代码结构 ### 6.1 项目目录结构 ``` deepseek_chat/ ├── __pycache__/ # Python编译缓存 ├── assets/ # 静态资源文件 │ ├── app_icon.ico # 应用图标 │ └── images/ # 图片资源 ├── auth/ # 用户认证模块 │ ├── __init__.py │ ├── user_auth.py # 用户认证逻辑 │ └── user_auth_ui.py # 认证界面 ├── chat/ # 聊天功能模块 │ ├── __init__.py │ ├── chat_manager.py # 聊天管理 │ └── deepseek_api.py # DeepSeek API接口 ├── config/ # 配置管理模块 │ ├── __init__.py │ └── config.py # 配置参数 ├── conversation/ # 对话管理模块 │ ├── __init__.py │ └── conversation_manager.py # 对话历史管理 ├── core/ # 核心模块 │ ├── __init__.py │ └── main.py # 应用入口 ├── data/ # 数据存储目录 │ ├── chat_history/ # 聊天历史数据 │ ├── schedule/ # 日程数据 │ ├── sessions/ # 会话数据 │ ├── todo/ # 待办事项数据 │ └── users/ # 用户数据 ├── logger/ # 日志管理模块 │ ├── __init__.py │ └── logger_manager.py # 日志管理 ├── schedule/ # 日程管理模块 │ ├── __init__.py │ └── schedule_manager.py # 日程管理 ├── todo/ # 待办事项模块 │ ├── __init__.py │ └── todo_manager.py # 待办事项管理 ├── ui/ # 用户界面模块 │ ├── __init__.py │ ├── chat_ui.py # 聊天界面 │ └── ui_components.py # UI组件 ├── chat_history.json # 聊天历史数据文件 ├── developer_documentation.md # 开发文档 ├── readme.txt # 项目说明 └── requirements.txt # 依赖列表 ``` ### 6.2 模块依赖关系 ``` ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ User Interface│ │ Business Logic │ │ Data Layer │ │ (ui/) │─────>│ (auth/, chat/, │─────>│ (data/) │ │ │ │ schedule/, todo/)│ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │ │ ▼ ▼ ▼ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Core Module │ │ API & Service │ │ Configuration │ │ (core/) │<─────│ (chat/deepseek_api.py)│ (config/) │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │ └────────────────────────┘ │ ▼ ┌─────────────────┐ │ Logger │ │ (logger/) │ └─────────────────┘ ``` ### 6.3 核心模块说明 #### 6.3.1 main.py (应用入口) 位置: `core/main.py` 应用程序的入口点，负责： - 初始化应用程序 - 设置UI主题 - 加载配置 - 启动主循环 ```python # 核心流程 1. 初始化配置 2. 初始化日志管理器 3. 创建主窗口 4. 设置UI组件 5. 启动Tkinter主循环 ``` #### 6.3.2 config.py (配置管理) 位置: `config/config.py` 管理应用程序的所有配置参数，包括： - API密钥和URL - 数据存储路径 - UI主题设置 - 日志级别 #### 6.3.3 logger_manager.py (日志管理) 位置: `logger/logger_manager.py` 负责记录系统日志，支持： - 不同级别的日志记录（INFO, DEBUG, ERROR） - 日志文件存储 - 日志查看界面 ### 6.4 代码规范 #### 6.4.1 命名规范 - **模块名**: 小写字母，使用下划线分隔（如：`chat_manager.py`） - **类名**: 驼峰命名法（如：`ChatManager`） - **函数名**: 小写字母，使用下划线分隔（如：`send_message`） - **变量名**: 小写字母，使用下划线分隔（如：`session_id`） - **常量名**: 大写字母，使用下划线分隔（如：`API_KEY`） #### 6.4.2 注释规范 - **文件头**: 包含模块说明、作者、创建日期等信息 - **类和函数**: 使用文档字符串（docstring）说明功能、参数、返回值 - **关键代码行**: 添加行内注释说明复杂逻辑 #### 6.4.3 代码组织 - 每个模块负责单一功能 - 避免过长的函数（建议不超过50行） - 使用面向对象编程思想 - 遵循DRY（Don't Repeat Yourself）原则 ## 7. API参考 ### 7.1 DeepSeek API接口 #### 7.1.1 接口概述 DeepSeek API提供了智能对话功能，应用程序通过该接口与DeepSeek的AI模型进行交互。 #### 7.1.2 接口地址 ``` POST https://api.deepseek.com/v1/chat/completions ``` #### 7.1.3 请求参数 | 参数名 | 类型 | 必填 | 描述 | |--------|------|------|------| | model | string | 是 | 要使用的模型名称，例如 "deepseek-chat" | | messages | array | 是 | 对话历史消息数组 | | temperature | float | 否 | 生成文本的随机性，范围0-2，默认0.7 | | top_p | float | 否 | 核采样参数，范围0-1，默认1.0 | | max_tokens | integer | 否 | 生成的最大token数，默认1024 | | stream | boolean | 否 | 是否使用流式响应，默认false | #### 7.1.4 请求示例 ```json { "model": "deepseek-chat", "messages": [ { "role": "system", "content": "You are a helpful assistant named DeepSeek." }, { "role": "user", "content": "Hello, how can I help you today?" } ], "temperature": 0.7, "stream": true } ``` #### 7.1.5 响应参数 | 参数名 | 类型 | 描述 | |--------|------|------| | id | string | 响应ID | | object | string | 对象类型，通常是 "chat.completion" | | created | integer | 响应创建时间戳 | | model | string | 使用的模型名称 | | choices | array | 生成的回复选项数组 | | usage | object | API使用情况统计 | #### 7.1.6 响应示例 ```json { "id": "chatcmpl-123", "object": "chat.completion", "created": 1677652288, "model": "deepseek-chat", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "Hello! How can I assist you today?" }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 12, "completion_tokens": 7, "total_tokens": 19 } } ``` #### 7.1.7 流式响应 当`stream`参数设置为`true`时，API会以SSE（Server-Sent Events）格式返回流式响应： ``` data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"deepseek-chat","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]} data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"deepseek-chat","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]} data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"deepseek-chat","choices":[{"index":0,"delta":{"content":"! How can I assist you today?"},"finish_reason":null}]} data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"deepseek-chat","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]} data: [DONE] ``` ### 7.2 内部API接口 #### 7.2.1 用户认证接口 (auth/user_auth.py) ##### 7.2.1.1 register_user ```python def register_user(self, username: str, password: str) -> bool: """ 注册新用户 参数: username: 用户名 password: 密码 返回: bool: 注册成功返回True，失败返回False """ ``` ##### 7.2.1.2 login_user ```python def login_user(self, username: str, password: str) -> str or None: """ 用户登录 参数: username: 用户名 password: 密码 返回: str or None: 登录成功返回session_id，失败返回None """ ``` ##### 7.2.1.3 validate_session ```python def validate_session(self, session_id: str) -> bool: """ 验证会话有效性 参数: session_id: 会话ID 返回: bool: 会话有效返回True，无效返回False """ ``` #### 7.2.2 聊天管理接口 (chat/chat_manager.py) ##### 7.2.2.1 send_message ```python def send_message(self, message: str, username: str) -> None: """ 发送消息并获取AI回复 参数: message: 用户输入的消息 username: 用户名 返回: None """ ``` #### 7.2.3 日程管理接口 (schedule/schedule_manager.py) ##### 7.2.3.1 create_schedule ```python def create_schedule(self, username: str, date: str, title: str, description: str, start_time: str, end_time: str) -> dict: """ 创建新日程 参数: username: 用户名 date: 日期 (YYYY-MM-DD) title: 日程标题 description: 日程描述 start_time: 开始时间 (HH:MM) end_time: 结束时间 (HH:MM) 返回: dict: 创建的日程信息 """ ``` ##### 7.2.3.2 get_schedules_by_date ```python def get_schedules_by_date(self, username: str, date: str) -> list: """ 按日期获取日程 参数: username: 用户名 date: 日期 (YYYY-MM-DD) 返回: list: 日程列表 """ ``` #### 7.2.4 待办事项接口 (todo/todo_manager.py) ##### 7.2.4.1 create_todo ```python def create_todo(self, username: str, title: str, description: str, due_date: str) -> dict: """ 创建新待办事项 参数: username: 用户名 title: 待办事项标题 description: 待办事项描述 due_date: 截止日期 (YYYY-MM-DD) 返回: dict: 创建的待办事项信息 """ ``` ##### 7.2.4.2 get_pending_todos ```python def get_pending_todos(self, username: str) -> list: """ 获取待处理的待办事项 参数: username: 用户名 返回: list: 待处理的待办事项列表 """ ``` ### 7.3 API错误处理 #### 7.3.1 常见错误码 | 错误码 | 描述 | 解决方法 | |--------|------|----------| | 400 | 请求参数错误 | 检查请求参数格式是否正确 | | 401 | 未授权 | 检查API密钥是否正确 | | 403 | 禁止访问 | 检查API密钥权限是否足够 | | 404 | 接口不存在 | 检查API接口地址是否正确 | | 429 | 请求频率过高 | 减少请求频率或联系DeepSeek增加配额 | | 500 | 服务器内部错误 | 稍后重试或联系DeepSeek技术支持 | | 503 | 服务不可用 | 稍后重试或检查DeepSeek服务状态 | #### 7.3.2 错误处理示例 ```python try: # 调用API response = deepseek_api.generate_response(message, history) except APIError as e: if e.code == 401: print("API密钥错误，请检查配置") elif e.code == 429: print("请求频率过高，请稍后重试") else: print(f"API调用错误: {e.message}") ``` ## 8. 测试说明 ### 8.1 测试策略 #### 8.1.1 测试类型 - **单元测试**: 测试单个函数或方法的功能 - **集成测试**: 测试模块之间的交互 - **系统测试**: 测试整个应用程序的功能 - **UI测试**: 测试用户界面的交互和响应 #### 8.1.2 测试工具 - **单元测试框架**: pytest - **UI测试工具**: pytest-tkinter (可选) - **API测试工具**: requests ### 8.2 单元测试 #### 8.2.1 测试目录结构 ``` tests/ ├── __init__.py ├── test_auth.py # 测试用户认证模块 ├── test_chat.py # 测试聊天模块 ├── test_schedule.py # 测试日程管理模块 ├── test_todo.py # 测试待办事项模块 └── test_config.py # 测试配置管理模块 ``` #### 8.2.2 测试示例 **测试用户认证模块示例** ```python import pytest from auth.user_auth import UserAuth class TestUserAuth: def setup_method(self): self.auth = UserAuth() # 创建测试用户 self.auth.register_user("test_user", "test_password") def teardown_method(self): # 清理测试数据 self.auth._users.pop("test_user", None) def test_register_user(self): """测试用户注册功能""" result = self.auth.register_user("new_user", "new_password") assert result is True assert "new_user" in self.auth._users def test_login_user(self): """测试用户登录功能""" session_id = self.auth.login_user("test_user", "test_password") assert session_id is not None assert len(session_id) > 0 def test_login_invalid_password(self): """测试使用无效密码登录""" session_id = self.auth.login_user("test_user", "wrong_password") assert session_id is None ``` **测试聊天模块示例** ```python import pytest from unittest.mock import MagicMock from chat.chat_manager import ChatManager class TestChatManager: def setup_method(self): self.chat_manager = ChatManager() # 模拟DeepSeekAPI self.chat_manager._api = MagicMock() self.chat_manager._api.generate_response.return_value = "Test response" def test_send_message(self): """测试发送消息功能""" self.chat_manager.send_message("Hello", "test_user") # 验证API调用 self.chat_manager._api.generate_response.assert_called_once() # 验证消息是否添加到历史记录 assert len(self.chat_manager._chat_history) > 0 ``` ### 8.3 集成测试 #### 8.3.1 测试场景 - 测试用户从登录到发送消息的完整流程 - 测试创建日程并查询日程的流程 - 测试创建待办事项并标记完成的流程 #### 8.3.2 测试示例 ```python import pytest from auth.user_auth import UserAuth from chat.chat_manager import ChatManager class TestIntegration: def setup_method(self): self.auth = UserAuth() self.chat_manager = ChatManager() # 创建测试用户 self.auth.register_user("integration_test", "password") def teardown_method(self): # 清理测试数据 self.auth._users.pop("integration_test", None) def test_login_and_chat_flow(self): """测试登录和聊天的完整流程""" # 登录 session_id = self.auth.login_user("integration_test", "password") assert session_id is not None # 发送消息 self.chat_manager.send_message("Hello", "integration_test") # 验证聊天历史记录 assert len(self.chat_manager._chat_history) > 0 ``` ### 8.4 系统测试 #### 8.4.1 测试场景 - 启动应用程序并验证登录窗口显示 - 测试登录功能 - 测试聊天功能 - 测试日程管理功能 - 测试待办事项功能 - 测试日志查看功能 #### 8.4.2 测试执行 系统测试通常通过手动操作进行，按照以下步骤执行： 1. 启动应用程序：`python core/main.py` 2. 验证登录窗口是否正常显示 3. 测试注册新用户 4. 测试使用新用户登录 5. 测试发送消息并获取AI回复 6. 测试创建、编辑和删除日程 7. 测试创建、标记完成和删除待办事项 8. 测试查看日志 9. 测试退出登录 ### 8.5 测试报告 #### 8.5.1 测试结果记录 测试完成后，应记录测试结果，包括： - 测试日期和时间 - 测试环境 - 测试用例执行情况 - 通过/失败的测试数量 - 发现的问题和缺陷 #### 8.5.2 测试报告示例 ``` DeepSeek Chat 应用程序测试报告 测试日期: 2023-12-01 测试环境: Windows 11, Python 3.9 测试用例总数: 50 通过测试数: 48 失败测试数: 2 通过率: 96% 失败测试用例: 1. test_schedule_overlap (schedule/test_schedule.py) - 描述: 测试创建重叠日程时的错误处理 - 原因: 未实现重叠日程检测功能 2. test_todo_due_date_validation (todo/test_todo.py) - 描述: 测试待办事项截止日期验证 - 原因: 日期格式验证逻辑错误 建议改进: 1. 实现重叠日程检测功能 2. 修复日期格式验证逻辑 ``` ### 8.6 性能测试 #### 8.6.1 测试目标 - 测试应用程序的响应时间 - 测试API调用的延迟 - 测试应用程序在长时间运行下的稳定性 #### 8.6.2 性能指标 - 登录响应时间: < 1秒 - 消息发送和接收响应时间: < 5秒 - 日程和待办事项操作响应时间: < 2秒 - 应用程序内存占用: < 200MB #### 8.6.3 性能测试示例 ```python import time from auth.user_auth import UserAuth # 测试登录响应时间 auth = UserAuth() auth.register_user("performance_test", "password") start_time = time.time() session_id = auth.login_user("performance_test", "password") end_time = time.time() response_time = end_time - start_time print(f"登录响应时间: {response_time:.2f}秒") # 验证性能指标 assert response_time < 1.0, f"登录响应时间过长: {response_time:.2f}秒" ``` ### 8.7 安全测试 #### 8.7.1 测试目标 - 测试密码安全性 - 测试会话管理安全性 - 测试数据存储安全性 #### 8.7.2 安全测试示例 ```python from auth.user_auth import UserAuth # 测试密码是否加密存储 auth = UserAuth() auth.register_user("security_test", "plain_password") # 获取存储的用户数据 user_data = auth._users.get("security_test") # 验证密码是否不是明文存储 assert user_data["password"] != "plain_password", "密码未加密存储" assert len(user_data["password"]) > 20, "密码加密强度不足" ``` ## 9. 部署说明 ### 9.1 部署方式 #### 9.1.1 本地开发环境部署 这是最基本的部署方式，用于开发和测试： ```bash # 1. 克隆或下载项目 cd deepseek_chat # 2. 创建并激活虚拟环境 python -m venv venv source venv/Scripts/activate # Windows source venv/bin/activate # macOS/Linux # 3. 安装依赖 pip install -r requirements.txt # 4. 配置API密钥 # 编辑 config/config.py 文件，设置API_KEY # 5. 运行应用程序 python core/main.py ``` #### 9.1.2 打包部署 使用PyInstaller将应用程序打包为可执行文件，便于在没有Python环境的机器上运行： ```bash # 1. 安装PyInstaller pip install pyinstaller # 2. 打包应用程序 pyinstaller -F -w -i assets/app_icon.ico -p . core/main.py # 3. 查找生成的可执行文件 # Windows: dist/main.exe # macOS: dist/main.app # Linux: dist/main ``` **PyInstaller参数说明**： - `-F`: 生成单个可执行文件 - `-w`: 不显示控制台窗口（仅GUI应用） - `-i`: 指定应用程序图标 - `-p`: 添加Python路径 #### 9.1.3 批量部署 对于需要在多台机器上部署的情况，可以使用以下步骤： 1. 完成打包步骤，生成可执行文件 2. 创建部署脚本（如batch文件或shell脚本） 3. 配置网络共享或使用部署工具分发应用 ### 9.2 系统要求 | 组件 | 最低要求 | 推荐配置 | |------|----------|----------| | 操作系统 | Windows 10, macOS 10.15, Linux Ubuntu 18.04 | Windows 11, macOS 12, Linux Ubuntu 20.04 | | CPU | Intel Core i3 或等效处理器 | Intel Core i5 或更高 | | 内存 | 4 GB RAM | 8 GB RAM | | 存储空间 | 500 MB 可用空间 | 1 GB 可用空间 | | 网络 | 稳定的互联网连接 | 高速互联网连接 | ### 9.3 配置管理 #### 9.3.1 配置文件 应用程序的配置信息存储在 `config/config.py` 文件中： ```python class Config: # API配置 API_KEY = "your_api_key_here" API_URL = "https://api.deepseek.com/v1/chat/completions" # 数据存储路径 DATA_PATH = "data/" USERS_PATH = DATA_PATH + "users/users.json" SESSIONS_PATH = DATA_PATH + "sessions/sessions.json" CHAT_HISTORY_PATH = DATA_PATH + "chat_history/" SCHEDULE_PATH = DATA_PATH + "schedule/" TODO_PATH = DATA_PATH + "todo/" LOGS_PATH = DATA_PATH + "app_logs.json" # UI配置 THEME = "dark-blue" SCREEN_WIDTH = 1200 SCREEN_HEIGHT = 800 # 日志配置 LOG_LEVEL = "INFO" ``` #### 9.3.2 环境变量 可以通过环境变量覆盖配置文件中的设置： ```bash # Windows set DEEPSEEK_API_KEY=your_api_key_here python core/main.py # macOS/Linux export DEEPSEEK_API_KEY=your_api_key_here python core/main.py ``` ### 9.4 数据备份与恢复 #### 9.4.1 数据备份 应用程序的数据存储在 `data/` 目录中，备份该目录即可： ```bash # Windows xcopy /s /e data backup_data # macOS/Linux cp -r data backup_data ``` #### 9.4.2 数据恢复 将备份的数据目录恢复到应用程序目录： ```bash # Windows xcopy /s /e backup_data data # macOS/Linux cp -r backup_data/* data/ ``` ### 9.5 常见部署问题 #### 9.5.1 打包后无法运行 **问题**：使用PyInstaller打包后，应用程序无法运行。 **解决方法**： 1. 检查是否包含了所有依赖项 2. 确保API密钥配置正确 3. 检查数据目录是否存在且可写 4. 尝试在命令行中运行可执行文件，查看错误信息 ```bash # Windows dist/main.exe # macOS/Linux ./dist/main ``` #### 9.5.2 API连接错误 **问题**：应用程序运行时显示API连接错误。 **解决方法**： 1. 检查网络连接是否正常 2. 验证API密钥是否正确 3. 检查防火墙设置是否允许应用程序访问网络 4. 确认DeepSeek API服务是否正常 #### 9.5.3 数据存储错误 **问题**：应用程序无法保存或加载数据。 **解决方法**： 1. 检查数据目录是否存在 2. 确认应用程序对数据目录有读写权限 3. 检查数据文件是否被其他程序锁定 ### 9.6 更新部署 当应用程序有新版本时，按照以下步骤更新部署： 1. 备份当前版本的数据 2. 下载或克隆新版本代码 3. 安装新版本的依赖 4. 恢复数据备份 5. 重新打包应用程序（如果使用打包部署） 6. 测试新版本功能 ## 10. 扩展指南 ### 10.1 扩展架构 DeepSeek Chat应用程序采用模块化设计，便于扩展。主要扩展点包括： - **功能模块扩展**：添加新的功能模块 - **UI组件扩展**：自定义用户界面组件 - **API集成扩展**：集成其他AI服务或API - **数据存储扩展**：使用不同的数据存储方式 ### 10.2 添加新功能模块 #### 10.2.1 模块结构 遵循现有的模块结构创建新功能模块： ``` new_module/ ├── __init__.py ├── new_module_manager.py # 业务逻辑 └── new_module_ui.py # UI组件（可选） ``` #### 10.2.2 模块实现示例 **业务逻辑模块** (`new_module/new_module_manager.py`) ```python class NewModuleManager: def __init__(self): self.data = [] # 初始化模块 def add_item(self, username, item_data): """ 添加新项 参数: username: 用户名 item_data: 项数据 返回: dict: 添加的项信息 """ # 实现添加逻辑 item = { "id": "unique_id", "username": username, "data": item_data, "created_at": "timestamp" } self.data.append(item) return item def get_items(self, username): """ 获取用户的所有项 参数: username: 用户名 返回: list: 项列表 """ # 实现获取逻辑 return [item for item in self.data if item["username"] == username] ``` **UI模块** (`new_module/new_module_ui.py`) ```python import customtkinter as ctk from new_module.new_module_manager import NewModuleManager class NewModuleUI: def __init__(self, parent, username): self.parent = parent self.username = username self.manager = NewModuleManager() self.frame = None def show(self): """显示新模块界面""" if self.frame: self.frame.destroy() self.frame = ctk.CTkFrame(self.parent) self.frame.pack(fill="both", expand=True, padx=20, pady=20) # 创建UI组件 title_label = ctk.CTkLabel(self.frame, text="新功能模块", font=ctk.CTkFont(size=20, weight="bold")) title_label.pack(pady=10) # 添加其他UI组件和事件处理 ``` #### 10.2.3 集成到主应用 在 `ui/chat_ui.py` 中集成新模块： ```python # 导入新模块 from new_module.new_module_ui import NewModuleUI class DeepSeekChatUI: def __init__(self, root): # 现有初始化代码 self.new_module_ui = None def setup_ui(self): # 现有UI设置代码 self._create_new_module_button() def _create_new_module_button(self): """创建新模块按钮""" new_module_btn = ctk.CTkButton( self.sidebar_frame, text="新功能", command=self.show_new_module ) new_module_btn.pack(pady=10, padx=20, fill="x") def show_new_module(self): """显示新模块界面""" if self.new_module_ui is None: self.new_module_ui = NewModuleUI(self.content_frame, self.username) # 隐藏其他模块界面 self._hide_all_content_frames() # 显示新模块界面 self.new_module_ui.show() self.current_module = "new_module" ``` ### 10.3 自定义UI主题 #### 10.3.1 主题配置 在 `config/config.py` 中设置UI主题： ```python class Config: # UI配置 THEME = "dark-blue" # 可选: "blue", "dark-blue", "green" SCREEN_WIDTH = 1200 SCREEN_HEIGHT = 800 ``` #### 10.3.2 自定义颜色 在 `ui/chat_ui.py` 中自定义颜色： ```python class DeepSeekChatUI: def __init__(self, root): # 设置主题 ctk.set_appearance_mode("dark") # "light", "dark", "system" ctk.set_default_color_theme("dark-blue") # 自定义颜色 self.custom_colors = { "primary": "#3B82F6", "secondary": "#10B981", "accent": "#F59E0B" } ``` #### 10.3.3 自定义组件 创建自定义UI组件： ```python class CustomButton(ctk.CTkButton): def __init__(self, parent, **kwargs): super().__init__(parent, **kwargs) self.configure( font=ctk.CTkFont(size=14, weight="bold"), corner_radius=8, hover_color="#2563EB" ) class CustomEntry(ctk.CTkEntry): def __init__(self, parent, **kwargs): super().__init__(parent, **kwargs) self.configure( font=ctk.CTkFont(size=14), corner_radius=8, border_width=2 ) ``` ### 10.4 集成其他AI服务 #### 10.4.1 API客户端实现 创建新的API客户端类： ```python # new_api/new_api_client.py import requests class NewAPIClient: def __init__(self, api_key): self.api_key = api_key self.api_url = "https://api.new-service.com/v1/endpoint" def generate_response(self, message, history): """ 调用新AI服务API 参数: message: 用户消息 history: 对话历史 返回: str: AI回复 """ headers = { "Authorization": f"Bearer {self.api_key}", "Content-Type": "application/json" } payload = { "message": message, "history": history, "model": "new-service-model" } response = requests.post(self.api_url, json=payload, headers=headers) response.raise_for_status() return response.json()["response"] ``` #### 10.4.2 集成到聊天模块 在 `chat/chat_manager.py` 中集成新API： ```python from new_api.new_api_client import NewAPIClient class ChatManager: def __init__(self): self.deepseek_api = DeepSeekAPI(config.Config.API_KEY) self.new_api = NewAPIClient(config.Config.NEW_API_KEY) self.current_api = "deepseek" def switch_api(self, api_name): """切换AI服务API""" if api_name in ["deepseek", "new_api"]: self.current_api = api_name return True return False def _get_ai_response(self, message, history): """获取AI回复""" if self.current_api == "deepseek": return self.deepseek_api.generate_response(message, history) else: return self.new_api.generate_response(message, history) ``` ### 10.5 数据存储扩展 #### 10.5.1 使用SQL数据库 创建数据库适配器类： ```python # data/database_adapter.py import sqlite3 class DatabaseAdapter: def __init__(self, db_path="data/app.db"): self.db_path = db_path self._init_database() def _init_database(self): """初始化数据库""" with sqlite3.connect(self.db_path) as conn: cursor = conn.cursor() # 创建用户表 cursor.execute(""" CREATE TABLE IF NOT EXISTS users ( username TEXT PRIMARY KEY, password TEXT NOT NULL, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ) """) # 创建其他表 conn.commit() def save_user(self, username, password): """保存用户信息""" with sqlite3.connect(self.db_path) as conn: cursor = conn.cursor() cursor.execute( "INSERT OR REPLACE INTO users (username, password) VALUES (?, ?)", (username, password) ) conn.commit() def get_user(self, username): """获取用户信息""" with sqlite3.connect(self.db_path) as conn: cursor = conn.cursor() cursor.execute("SELECT * FROM users WHERE username = ?", (username,)) return cursor.fetchone() ``` #### 10.5.2 集成到现有模块 在认证模块中使用数据库适配器： ```python # auth/user_auth.py from data.database_adapter import DatabaseAdapter class UserAuth: def __init__(self): self.db = DatabaseAdapter() def register_user(self, username, password): """注册新用户""" hashed_password = self._hash_password(password) self.db.save_user(username, hashed_password) return True def login_user(self, username, password): """用户登录""" user = self.db.get_user(username) if user and self._verify_password(password, user[1]): return self._create_session(username) return None ``` ### 10.6 最佳实践 #### 10.6.1 代码组织 - 遵循现有的模块结构 - 使用面向对象编程 - 保持代码简洁，遵循单一职责原则 - 添加适当的注释和文档 #### 10.6.2 性能优化 - 避免不必要的API调用 - 使用缓存减少重复计算 - 优化UI响应性能 - 适当使用异步编程 #### 10.6.3 安全性 - 不要在代码中硬编码API密钥 - 使用环境变量或配置文件管理敏感信息 - 对用户密码进行加密存储 - 验证用户输入，防止注入攻击 #### 10.6.4 测试 - 为新功能编写单元测试 - 测试与现有功能的集成 - 进行性能测试和安全测试 - 编写测试文档 #### 10.6.5 文档 - 更新开发文档 - 为新功能添加使用说明 - 记录API接口和参数 - 提供示例代码 ### 10.7 常见扩展场景 #### 10.7.1 添加文件上传功能 1. 创建文件上传UI组件 2. 实现文件上传逻辑 3. 集成到聊天模块，支持发送文件 4. 处理文件内容，生成适当的AI提示 #### 10.7.2 添加语音输入功能 1. 使用SpeechRecognition库实现语音识别 2. 创建语音输入按钮 3. 将语音转换为文本，发送到AI服务 #### 10.7.3 添加多语言支持 1. 创建语言配置文件 2. 实现文本翻译功能 3. 添加语言切换UI 4. 确保所有UI文本可翻译 #### 10.7.4 添加插件系统 1. 设计插件接口 2. 创建插件加载机制 3. 实现插件管理UI 4. 提供插件开发文档