# *多人聊天室*中枢通讯模块设计
- chatrooms

*---来自某人的综合设计---*

[English version](README_EN.md)
[Русская версия](README_RU.md)

## 设计思想
1. 目的：快速构建消息通讯
2. 作用：搭建模拟“群聊”的通讯架构
3. 实际：将群聊逻辑做成极简通信模块，使得只需要构造类就可以完成通信

- 注：后续可能会继续跟进以适应更多情况

## 模块使用（快速上手）

### 安装

```bash
# 从 PyPI 安装
pip install fastchatrooms

# 或从源码安装
pip install -e .

# 安装测试依赖
pip install fastchatrooms[test]
```

### 基本使用

#### 1. 初始化聊天室

```python
from fastchatrooms import ChatRoom

# 创建聊天室
chatroom = ChatRoom('Test Room')
```

#### 2. 添加用户

```python
# 添加用户
chatroom.add('user1', 'User 1')
chatroom.add('user2', 'User 2')

# 获取所有用户
users = chatroom.participants()
print(f"Current users: {[user.name for user in users]}")
```

#### 3. 发送消息

```python
# 广播消息（发送给所有人）
chatroom.send('user1', 'Hello everyone!')

# 私聊消息（发送给特定用户）
chatroom.send_to('user1', 'Hello private!', 'user2')
```

#### 4. 获取历史消息

```python
# 获取最近的消息
messages = chatroom.history(limit=10)
for msg in messages:
    print(f"{msg.sender_name}: {msg.content}")

# 获取特定用户的消息
user_messages = chatroom.history_by_sender('user1', limit=5)

# 获取消息总数
message_count = chatroom.history_count()
print(f"Total messages: {message_count}")
```

#### 5. 删除消息

```python
# 删除单条消息
chatroom.delete_message('message_id')

# 删除特定用户的所有消息
deleted_count = chatroom.delete_user_messages('user1')
print(f"Deleted {deleted_count} messages from user1")

# 清空所有消息
chatroom.clear_history()
```

#### 6. 事件回调

```python
# 消息回调
def on_message(msg):
    print(f"New message: {msg.sender_name}: {msg.content}")

chatroom.on_message(on_message)

# 加入回调
def on_join(user):
    print(f"User joined: {user.name}")

chatroom.on_join(on_join)

# 离开回调
def on_leave(user):
    print(f"User left: {user.name}")

chatroom.on_leave(on_leave)
```

#### 7. 清空所有数据

```python
# 清空所有数据库文件
chatroom.clear_all()
```

#### 8. 停止聊天室

```python
# 停止聊天室，关闭数据库连接
chatroom.stop()
```

## 技术栈设计
- 实现语言：Python (version:3.13)
- 初步设计数据库：SQLite
- 测试框架：pytest
- 许可证：MIT License

## 模块结构和组分
1. 核心部分架构
```
fastchatrooms/
├── store/
│   ├── __init__.py       # 导出
│   ├── base.py           # 存储抽象基类
│   └── sqlitestore.py    # SQLite 实现
├── __init__.py       # 导出主要类
├── message.py        # Message 类
├── user.py           # User 类
└── chatroom.py       # ChatRoom 核心类
```
2. 总架构
fastchatrooms/
├── fastchatrooms/
│   ├── __init__.py
│   ├── chatroom.py
│   ├── message.py
│   ├── user.py
│   └── store/
│       ├── __init__.py
│       ├── base.py
│       └── sqlitestore.py
├── test/
│   ├── __init__.py
│   ├── test_chatroom.py
│   └── test_clear_all.py
├── setup.py
├── setup.cfg
├── pyproject.toml
├── README.md
├── LICENSE
└── requirements.txt


## 其他信息
- 仓库：`https://github.com/ComplicatedWinds/fastchatrooms.git`
- 设计：`B.H.C.`
- 初步包装日期：`2026年3月18日`