# LearnMail

**Repository Path**: aymwoo/learn-mail

## Basic Information

- **Project Name**: LearnMail
- **Description**: 学生学习邮箱演示
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2025-12-15
- **Last Updated**: 2025-12-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 邮箱演示系统 📧

[![Python](https://img.shields.io/badge/Python-3.8+-blue.svg)](https://python.org)
[![Flask](https://img.shields.io/badge/Flask-2.3+-green.svg)](https://flask.palletsprojects.com)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Status](https://img.shields.io/badge/Status-Active-success.svg)]()

> 当前稳定版本：`v1.0`（标签）。详细更新说明见 `CHANGELOG.md`。

## 🎯 项目概述

**邮箱演示系统**是一个专为教学环境设计的轻量级邮件服务器系统，基于Python Flask框架开发。系统提供完整的邮件收发功能，支持用户注册、登录、邮件管理等核心功能，是学习Web开发和邮件系统原理的理想平台。

### ✨ 核心特点

- 🚀 **开箱即用**: 一键部署，无需复杂配置
- 🎓 **教学友好**: 专为教学环境优化，界面简洁直观
- 🔒 **安全可靠**: 完善的用户认证和权限管理机制
- 📱 **响应式设计**: 支持PC、平板、手机等多种设备
- 🛠️ **易于维护**: 详细的文档和管理工具
- 💡 **轻量级**: 基于SQLite数据库，无需额外数据库服务

### 🎯 适用场景

- **计算机网络课程**: 演示邮件系统工作原理
- **Web开发教学**: 展示前后端分离架构
- **Python编程实践**: Flask框架应用示例
- **系统管理培训**: 用户和权限管理实践
- **小型团队协作**: 内网邮件通信工具

## 🚀 快速开始

### 📋 系统要求

- **操作系统**: Windows 10/11, macOS 10.14+, Ubuntu 18.04+
- **Python版本**: Python 3.8 或更高版本
- **内存要求**: 最少 512MB RAM
- **存储空间**: 最少 100MB 可用空间
- **网络要求**: 支持HTTP访问（默认端口5000）

### ⚡ 一键部署

```bash
# 1. 克隆项目
git clone <repository-url>
cd 邮箱演示

# 2. 安装依赖
pip install -r requirements.txt

# 3. 启动系统
python run.py

# 4. 访问系统
# 浏览器打开: http://localhost:5000
```

### 👤 默认账户

**管理员账户**:
- 用户名: `admin`
- 密码: `admin123`
- 邮箱: `admin@mailserver.local`

**教师账户**:
- 用户名: `teacher`
- 密码: `123456`
- 邮箱: `teacher@wxxx.com`
- 角色: `admin`

**测试账户**:
- 用户名: `test`
- 密码: `123456`
- 邮箱: `test@wxxx.com`

**学生账户示例**:
- 用户名: `cyw`
- 密码: `123456`
- 邮箱: `cyw@wxxx.com`

### 📚 详细文档

- 📖 **[部署指南](docs/DEPLOYMENT.md)** - 详细的安装和配置说明
- 👨‍🎓 **[用户手册](docs/USER_MANUAL.md)** - 学生用户使用指南
- 👨‍💼 **[管理员指南](docs/ADMIN_GUIDE.md)** - 管理员操作手册
- 🔧 **[API文档](http://localhost:5000/api/doc)** - 系统启动后可访问

### 🎨 系统架构

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   前端界面      │    │   Flask应用     │    │   SQLite数据库  │
│                 │    │                 │    │                 │
│ • Bootstrap UI  │◄──►│ • 路由控制      │◄──►│ • 用户数据      │
│ • 响应式设计    │    │ • 业务逻辑      │    │ • 邮件数据      │
│ • JavaScript    │    │ • API接口       │    │ • 会话数据      │
└─────────────────┘    └─────────────────┘    └─────────────────┘
```

## ⭐ 功能特性

### 👨‍🎓 学生用户功能
- 📝 **用户注册**: 快速注册个人账号，支持邮箱验证
- 🔐 **安全登录**: 基于Session的身份验证机制
- 📧 **发送邮件**: 支持发送文本邮件给系统内其他用户
- 📬 **接收邮件**: 实时查看收到的邮件列表和未读提醒
- 🔍 **邮件详情**: 查看邮件完整内容，支持已读/未读状态
- 🗂️ **邮件管理**: 删除不需要的邮件，保持收件箱整洁
- 👤 **个人设置**: 修改个人信息和密码

### 👨‍💼 管理员功能
- 👥 **用户管理**: 查看、编辑、禁用/启用用户账号
- 🔑 **权限管理**: 设置用户角色（学生/管理员）
- 🔄 **密码重置**: 为用户重置密码到默认值
- 📊 **邮件监控**: 查看系统内所有邮件收发情况
- 📈 **系统统计**: 用户数量、邮件数量、活跃度等统计
- 🛠️ **系统维护**: 数据清理、备份管理等维护功能
- 📋 **操作日志**: 记录重要的管理操作

## 🔧 技术架构

### 🛠️ 后端技术栈
- **Web框架**: Flask 2.3+ - 轻量级Python Web框架
- **数据库**: SQLite - 轻量级，无需额外配置
- **ORM**: SQLAlchemy - Python SQL工具包和对象关系映射
- **身份验证**: Flask-Login + JWT - 安全的用户认证
- **密码加密**: Werkzeug Security - 密码哈希和验证
- **API文档**: Flask-RESTX (Swagger UI) - 自动生成API文档

### 🎨 前端技术栈
- **基础技术**: HTML5 + CSS3 + JavaScript ES6+
- **UI框架**: Bootstrap 5 - 响应式设计框架
- **HTTP客户端**: Fetch API - 现代异步请求处理
- **模板引擎**: Jinja2 - Python模板引擎
- **图标库**: Bootstrap Icons - 丰富的图标资源

## 📁 项目结构

```
邮箱演示/
├── 📁 app/                    # 应用核心代码
│   ├── 📁 admin/              # 管理员功能模块
│   │   ├── __init__.py
│   │   └── routes.py          # 管理员路由
│   ├── 📁 auth/               # 用户认证模块
│   │   ├── __init__.py
│   │   └── routes.py          # 认证路由
│   ├── 📁 main/               # 主要功能模块
│   │   ├── __init__.py
│   │   └── routes.py          # 主路由
│   ├── 📁 templates/          # HTML模板
│   │   ├── 📁 admin/          # 管理员模板
│   │   ├── 📁 auth/           # 认证模板
│   │   ├── 📁 main/           # 主模板
│   │   └── base.html          # 基础模板
│   ├── 📁 static/             # 静态资源
│   │   ├── 📁 css/            # 样式文件
│   │   ├── 📁 js/             # JavaScript文件
│   │   └── 📁 images/         # 图片资源
│   ├── __init__.py            # Flask应用工厂
│   ├── models.py              # 数据库模型
│   └── utils.py               # 工具函数
├── 📁 docs/                   # 项目文档
│   ├── DEPLOYMENT.md          # 部署指南
│   ├── USER_MANUAL.md         # 用户手册
│   └── ADMIN_GUIDE.md         # 管理员指南
├── 📁 instance/               # 实例配置
├── 📄 config.py               # 配置文件
├── 📄 run.py                  # 启动脚本
├── 📄 requirements.txt        # 依赖包列表
└── 📄 README.md               # 项目说明
```

## 🗄️ 数据库设计

### 用户表 (users)
| 字段 | 类型 | 说明 |
|------|------|------|
| id | Integer | 主键，自增 |
| username | String(80) | 用户名，唯一 |
| email | String(120) | 邮箱地址，唯一 |
| real_name | String(100) | 真实姓名 |
| class_name | String(50) | 班级信息 |
| password_hash | String(255) | 加密密码 |
| role | String(20) | 用户角色 (student/admin) |
| is_active | Boolean | 账号状态 |
| created_at | DateTime | 创建时间 |
| last_login | DateTime | 最后登录时间 |

### 邮件表 (emails)
| 字段 | 类型 | 说明 |
|------|------|------|
| id | Integer | 主键，自增 |
| sender_id | Integer | 发送者ID，外键 |
| recipient_id | Integer | 接收者ID，外键 |
| subject | String(200) | 邮件主题 |
| content | Text | 邮件内容 |
| sent_at | DateTime | 发送时间 |
| is_read | Boolean | 是否已读 |
| is_deleted_by_sender | Boolean | 发送者是否删除 |
| is_deleted_by_recipient | Boolean | 接收者是否删除 |

## 🚀 安装部署

> 💡 **提示**: 详细的部署说明请参考 [部署指南](docs/DEPLOYMENT.md)

### 📋 环境要求
- **Python**: 3.8 或更高版本
- **操作系统**: Windows 10/11, macOS 10.14+, Ubuntu 18.04+
- **内存**: 最少 512MB RAM
- **存储**: 最少 100MB 可用空间

### ⚡ 快速部署

```bash
# 1️⃣ 克隆项目
git clone <项目地址>
cd 邮箱演示

# 2️⃣ 创建虚拟环境 (推荐)
python -m venv venv
# Windows
venv\Scripts\activate
# macOS/Linux
source venv/bin/activate

# 3️⃣ 安装依赖
pip install -r requirements.txt

# 4️⃣ 启动系统
python run.py

# 5️⃣ 访问系统
# 浏览器打开: http://localhost:5000
```

### 🌐 网络配置

#### 教师机配置
1. **启动服务**: 确保服务运行在 `0.0.0.0:5000`
2. **防火墙设置**: 开放5000端口或关闭防火墙
3. **获取IP地址**: 
   - Windows: `ipconfig`
   - macOS/Linux: `ifconfig`

#### 学生机访问
- **访问地址**: `http://教师机IP:5000`
- **支持浏览器**: Chrome, Firefox, Safari, Edge
- **移动设备**: 支持手机和平板访问

## 🔒 安全特性

### 🛡️ 数据安全
- **密码加密**: 使用 Werkzeug 进行密码哈希
- **SQL注入防护**: SQLAlchemy ORM 自动防护
- **XSS防护**: Jinja2 模板自动转义
- **CSRF保护**: Flask-WTF 提供跨站请求伪造保护

### 🔐 身份验证
- **会话管理**: Flask-Login 安全会话管理
- **权限控制**: 基于角色的访问控制 (RBAC)
- **自动登出**: 会话超时自动登出机制
## 📖 使用说明

> 💡 **提示**: 详细的使用说明请参考相关文档
> - 👨‍🎓 [用户手册](docs/USER_MANUAL.md) - 学生用户完整指南
> - 👨‍💼 [管理员指南](docs/ADMIN_GUIDE.md) - 管理员操作手册

### 👨‍🎓 学生操作流程
1. **访问系统**: 浏览器打开教师提供的服务器地址
2. **注册账号**: 点击"注册"创建个人账号
3. **登录系统**: 使用用户名和密码登录
4. **查看邮件**: 在收件箱查看接收到的邮件
5. **发送邮件**: 点击"写邮件"发送新邮件给其他用户
6. **邮件管理**: 查看邮件详情、标记已读、删除邮件

### 👨‍💼 教师管理流程
1. **管理员登录**: 使用管理员账号登录系统
2. **用户管理**: 查看用户列表、管理用户权限
3. **邮件监控**: 监控系统内所有邮件收发情况
4. **系统统计**: 查看用户活跃度和邮件统计
5. **系统维护**: 执行数据清理和系统维护操作

## 🚀 扩展功能

### 💡 可选增强功能
- 📎 **邮件附件**: 支持文件附件上传和下载
- 📁 **邮件分类**: 邮件标签和分类管理
- 🔍 **搜索功能**: 全文搜索邮件内容
- 📊 **统计报表**: 详细的使用统计和分析
- 🔔 **实时通知**: 新邮件实时提醒
- 📱 **移动适配**: 优化移动设备体验
- 🌐 **多语言**: 支持多语言界面
- 🎨 **主题定制**: 可定制的界面主题

### ⚙️ 高级配置
- **存储限制**: 设置邮件和用户存储配额
- **注册审核**: 管理员审核新用户注册
- **批量导入**: 批量导入用户数据
- **数据备份**: 自动数据备份和恢复
- **日志记录**: 详细的操作日志记录
- **性能监控**: 系统性能监控和优化

## 🔧 故障排除

### ❓ 常见问题

#### 🌐 网络连接问题
**问题**: 无法访问服务器
**解决方案**:
- ✅ 检查防火墙设置，开放5000端口
- ✅ 确认教师机IP地址正确
- ✅ 验证Python服务是否正常启动
- ✅ 检查网络连接是否正常

#### 🔐 登录问题
**问题**: 用户无法登录
**解决方案**:
- ✅ 检查用户名和密码是否正确
- ✅ 确认用户账号是否被禁用
- ✅ 清除浏览器缓存和Cookie
- ✅ 尝试重置密码（管理员操作）

#### 📧 邮件问题
**问题**: 邮件发送失败
**解决方案**:
- ✅ 确认收件人用户名存在
- ✅ 检查邮件内容长度是否超限
- ✅ 验证发送者权限是否正常
- ✅ 查看系统错误日志

### 📞 技术支持
如遇到其他问题，请：
1. 查看系统日志文件 (`logs/` 目录)
2. 参考详细文档和FAQ
3. 联系系统管理员或开发团队

## 📄 许可证

本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件

## 🤝 贡献指南

欢迎贡献代码和建议！请遵循以下步骤：

1. **Fork** 本项目
2. **创建** 功能分支 (`git checkout -b feature/AmazingFeature`)
3. **提交** 更改 (`git commit -m 'Add some AmazingFeature'`)
4. **推送** 到分支 (`git push origin feature/AmazingFeature`)
5. **创建** Pull Request

## 📊 更新日志

### v1.0.0 (2024-01-01)
- ✨ 初始版本发布
- ✅ 完整的邮件收发功能
- ✅ 用户注册和认证系统
- ✅ 管理员面板和用户管理
- ✅ 响应式Web界面
- ✅ 完整的文档和部署指南

---

## 🎯 项目状态

![GitHub last commit](https://img.shields.io/github/last-commit/username/repository)
![GitHub issues](https://img.shields.io/github/issues/username/repository)
![GitHub stars](https://img.shields.io/github/stars/username/repository)

**开发状态**: ✅ 稳定版本  
**维护状态**: 🔄 积极维护  
**文档状态**: 📚 完整文档  

---

<div align="center">

**感谢使用邮箱演示系统！** 🎉

如果这个项目对您有帮助，请给我们一个 ⭐ Star！

[📖 文档](docs/) | [🐛 报告问题](issues) | [💡 功能建议](issues) | [🤝 贡献代码](pulls)

</div>
   - 查看服务器日志

3. **邮件发送失败**
   - 检查收件人是否存在
   - 验证网络连接
   - 查看错误提示信息

### 日志查看
- 应用日志：`logs/app.log`
- 错误日志：`logs/error.log`
- 访问日志：`logs/access.log`

## 技术支持

### 开发环境
- 开发工具：VS Code / PyCharm
- 调试模式：`python run.py --debug`
- 测试命令：`python -m pytest`

### 性能优化
- 数据库索引优化
- 静态资源缓存
- 分页查询实现
- 异步任务处理

## 许可证

本项目采用MIT许可证，详见LICENSE文件。

## 更新日志

### v1.0.0 (2024-01-XX)
- 初始版本发布
- 基础邮件收发功能
- 用户权限管理
- 管理员面板

---

**注意**: 本系统仅用于教学演示，不建议在生产环境中使用。如需商业用途，请进行相应的安全加固和性能优化。