# Chat-Room 聊天室项目


>~~也许这段话是这个项目中唯一一段是人类写的话~~
>
> 本项目原意是为了学习socket, 完成了核心代码 (也就是 `server.py` 与 `client.py` 的部分代码) 后, 就尝试使用 Augment 来充实这个项目, 和它高强度对线快两周后这个项目就从 1k 行左右的mini💩变成了现在的💩山. 
>
> 使用 Augment 的初衷是为了体验一下稍微正经点的项目是如何一步步充实的. 目前来讲, 也许体验到了一点.
> AI真的太强

> **🎓 一个专为编程学习设计的完整Socket网络编程教学项目**

Chat-Room不仅是一个功能完整的实时聊天室系统，更是一个精心设计的**渐进式学习平台**。通过从零开始构建聊天室，您将掌握Python网络编程、数据库设计、用户界面开发、AI集成等现代软件开发的核心技能。

## 🌟 项目特色

### 📚 完整的学习文档系统
- **17个章节**：从Python基础到高级项目实践的完整学习路径
- **77个详细文档**：每个知识点都有深入讲解和代码示例
- **渐进式设计**：适合编程初学者，循序渐进掌握复杂概念
- **实战导向**：所有理论都结合Chat-Room项目进行实践

### 🎯 三种学习路径
- **🚀 快速入门**（4-6周）：适合有编程基础的学习者
- **📚 完整学习**（3-4个月）：适合编程初学者的系统化学习
- **🎨 项目驱动**（6-8周）：适合喜欢边做边学的实践者

### 💡 现代化技术栈
- **网络编程**：Socket TCP/IP通信、多线程并发处理
- **数据库技术**：SQLite数据库设计、ORM模式应用
- **用户界面**：Textual TUI框架、现代化命令行界面
- **AI集成**：智谱AI GLM-4-Flash API集成
- **软件工程**：模块化设计、测试驱动开发、CI/CD部署

## 📖 项目简介

Chat-Room是一个功能完整的聊天室应用，采用客户端-服务器架构，使用Socket进行网络通信，SQLite作为数据存储，Textual库构建现代化TUI界面。项目严格遵循模块化设计原则，代码结构清晰，注释详细，易于学习和扩展。

## ✨ 主要功能特性

- **实时聊天**：基于Socket的即时消息传输，支持多用户群聊
- **用户系统**：完整的用户注册、登录、会话管理
- **聊天组管理**：创建、加入、进入聊天组，支持公频聊天
- **文件传输**：安全的文件上传下载，支持多种文件类型
- **AI智能助手**：集成智谱AI GLM-4-Flash，支持群聊@AI和私聊对话
- **管理员系统**：完整的管理员功能，支持用户/群组管理、禁言等操作
- **现代化TUI**：基于Textual的美观命令行界面，支持多主题

## 🎓 学习文档系统

Chat-Room项目的核心价值在于其完整的学习文档系统：

- **📚 [完整学习路径](docs/learning-v02/README.md)**：17个章节、77个详细文档
- **📖 [学习文档索引](docs/learning-v02/index.md)**：章节目录和学习指南
- **🎯 三种学习路径**：快速入门、完整学习、项目驱动
- **🔧 实战导向**：所有理论都结合实际项目进行实践

## 🏗️ 项目架构

### 📁 核心目录结构

```
Chat-Room/
├── docs/learning-v02/       # 📚 学习文档系统（项目核心价值）
├── client/                  # 🖥️ 客户端模块：TUI界面、Socket通信、命令处理
├── server/                  # 🖧 服务器模块：Socket服务器、业务逻辑、数据库操作
├── shared/                  # 🔗 共享模块：通信协议、消息格式、工具函数
├── config/                  # ⚙️ 配置文件：服务器配置、客户端配置、模板示例
├── test/                    # 🧪 测试代码：单元测试、集成测试、测试工具
├── demo/                    # 🎬 演示代码：功能演示、使用示例
├── tools/                   # 🔧 开发工具：构建脚本、部署工具
├── logs/                    # 📋 日志目录：运行日志、错误日志
└── archive/                 # 📦 归档文件：临时文件、调试脚本
```

### 🎯 模块说明

- **docs/learning-v02/**：完整的学习文档系统，包含17个章节的渐进式教程
- **client/**：客户端应用，基于Textual的现代化TUI界面，处理用户交互和服务器通信
- **server/**：服务器端应用，处理Socket连接、用户管理、消息路由、数据存储
- **shared/**：客户端和服务器共享的代码，包括通信协议、消息格式、常量定义
- **config/**：配置文件管理，支持YAML格式配置，包含服务器和客户端的所有可配置参数
- **test/**：完整的测试套件，包括单元测试、集成测试、功能测试和性能测试

## 🚀 快速开始

### 📚 学习路径（推荐）

如果您想系统学习网络编程，建议从学习文档开始：

- **🎓 [开始学习之旅](docs/learning-v02/README.md)**：完整的17章节学习路径
- **📖 [学习文档索引](docs/learning-v02/index.md)**：章节目录和学习指南
- **🎯 选择学习路径**：快速入门（4-6周）、完整学习（3-4个月）、项目驱动（6-8周）

### 💻 直接运行项目

如果您想直接体验Chat-Room功能：

#### 环境要求
- Python 3.8+、conda环境、100MB存储空间

#### 快速启动
```bash
# 1. 克隆项目
git clone <repository-url> && cd Chat-Room

# 2. 激活环境并安装依赖
conda activate chatroom
pip install -r requirements.txt

# 3. 启动服务器
python -m server.main

# 4. 启动客户端（新终端）
python -m client.main

# 5. 注册并开始聊天
# 未登录> /signin
# 未登录> /login
```

详细安装和配置说明请参考：[环境搭建指南](docs/learning-v02/00-overview/environment-setup.md)

#### 🌐 远程服务器部署

如果需要部署到远程服务器供多人使用：

```bash
# 1. 修改客户端配置（指向远程服务器）
# 编辑 config/client_config.yaml
connection:
  default_host: your-server-ip  # 修改为服务器IP地址
  default_port: 8888

# 2. 修改服务器配置（允许外部连接）
# 编辑 config/server_config.yaml
server:
  host: 0.0.0.0  # 重要：必须设置为0.0.0.0才能接受外部连接
  port: 8888

# 3. 在服务器上启动服务
nohup python -m server.main > server.log 2>&1 &

# 4. 开放防火墙端口
sudo ufw allow 8888
```

详细部署指南请参考：[服务器部署指南](docs/server_deployment_guide.md)

## 📚 相关文档

- **🎓 [学习指南](docs/learning-v02/README.md)**：完整的学习路径和教程
- **🎮 [使用指南](docs/learning-v02/00-overview/README.md)**：项目使用和功能介绍
- **🔧 [开发指南](docs/learning-v02/02-development-environment/README.md)**：开发环境配置和贡献指南
- **🧪 [测试指南](docs/learning-v02/15-testing-quality/README.md)**：测试框架和质量保证

## 🤝 贡献与支持

### 贡献方式
- **📖 改进文档**：修正错误、补充说明、优化结构
- **🔧 代码贡献**：修复bug、添加功能、性能优化
- **🧪 测试用例**：添加测试、提高覆盖率
- **🌐 翻译工作**：将文档翻译成其他语言

### 开发原则
- **教学导向**：代码的首要目标是帮助学习者理解概念
- **初学者友好**：优先考虑代码的可读性和理解性
- **文档同步**：代码变更必须同步更新相关学习文档

详细贡献指南请参考：[开发指南](docs/learning-v02/02-development-environment/README.md)

## 📄 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件

## 🙏 致谢

感谢以下开源项目的支持：
- [Textual](https://github.com/Textualize/textual) - 现代化TUI框架
- [智谱AI](https://open.bigmodel.cn/) - AI对话能力支持
- [SQLite](https://www.sqlite.org/) - 轻量级数据库
- [Python](https://www.python.org/) - 强大的编程语言

---

**最后更新**: 2025年1月17日

如有问题或建议，欢迎提交Issue或参与项目贡献！