# chat

**Repository Path**: F2T/chat

## Basic Information

- **Project Name**: chat
- **Description**: 基于 H5 的综合实时通讯平台
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-27
- **Last Updated**: 2026-08-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# H5 实时聊天室（一期 / 二期 / 三期）

基于 H5 的综合实时通讯平台，一期为单房间匿名聊天，二期升级为注册用户多房间持久化平台，三期进一步升级为具备社交关系的综合 IM（语音/通话/好友私聊/文件/引用/管理/搜索/通知）。技术方案见 `chat.md`（一期）、`聊天室二期需求功能点.md`（二期）、`聊天室三期需求功能点.md`（三期），规格与设计见 `specs/`。

## 功能特性

### 一期（已交付）
- 昵称 2~12 字符在线唯一、随机头像、进出广播；文本+emoji、回车/Shift+Enter、自动滚动；在线列表与心跳重连

### 二期（已交付）
- 账户体系（昵称全局唯一、bcrypt、JWT 7 天、头像 2MB）、多房间（大厅、创建/列表/解散、单房间约束）、持久化（50+20 分页）、图片 5MB、敏感词 `***`、撤回 2 分钟、@在线高亮、PWA

### 三期（本次升级）
- **语音消息**：MediaRecorder 录制 ≤60s、webm/ogg/mp3 ≤5MB、`voice` 类型气泡播放
- **音视频通话**：1对1 WebRTC P2P、WS 信令 SDP/ICE、语音/视频模式、来电提醒/接听/挂断与时长
- **好友与私聊**：搜索/申请/同意/拒绝、好友列表在线状态、私聊会话唯一（user1<user2）、历史分页与未读计数、已读标记
- **文件传输**：通用文件 ≤20MB、白名单校验、`/static/files/` 卡片下载
- **消息引用/回复**：长按引用、`reply_to` 落库、摘要展示、点击定位
- **房间管理增强**：房主设管理员、管理员禁言（时长）与踢人、禁言拦截与剩余提示
- **消息搜索**：房间内关键词 LIKE/pg_trgm、高亮与跳转、时间范围筛选
- **桌面通知**：Notification API + Service Worker、后台/离线私聊/@通知、未读聚合、开关设置

## 技术栈

- **前端**：Vue 3.4 + TS 5 + Vite 5 + Router/Pinia/Axios + Workbox + WebRTC/MediaRecorder/Notification
- **后端**：Python 3.8+ (建议 3.12) + FastAPI + Uvicorn + Pydantic 2 + SQLAlchemy 2 + Alembic + python-jose/bcrypt + python-multipart，本地 `uploads/{avatars|images|voices|files}` 可切换 OSS/S3
- **通信**：RESTful `/api/v1` + WebSocket JSON + WebRTC P2P（信令经 WS）
- **存储**：SQLite（开发）/ PostgreSQL（生产 via `DATABASE_URL`）
- **测试**：后端 pytest 61 项 + 前端 Vitest 32 项，真实 DB/WS 集成

## 目录结构

```
.
├── backend/
│   ├── main.py              # 挂载 REST + WS + /static
│   ├── models.py            # ORM (User/Room/Message/SensitiveWord/Friendship/Conversation/PrivateMessage/RoomMember)
│   ├── routers/             # auth/rooms/messages/admin/upload/friends/conversations
│   ├── ws.py                # WS (一期兼容 + 二期房间 + 三期信令/私聊/管理)
│   ├── uploads/{avatars|images|voices|files}
│   └── tests/
├── frontend/
│   ├── src/views/           # Login/Register/Chat/Profile/Friends/PrivateChat/Call
│   ├── src/components/      # VoiceRecorder/VoiceMessage/FileCard/ReplyPreview/SearchBar/RoomMembers/...
│   ├── src/stores/          # user/room/chat/friends/conversations
│   ├── src/utils/           # websocket/webrtc/notification
│   └── tests/unit + e2e
├── specs/
│   ├── 001-h5-chatroom/
│   ├── 002-h5-chatroom-phase2/
│   └── 003-h5-chatroom-phase3/
└── docker-compose.yml
```

## 快速启动

### 1. 后端
```bash
cd backend
pip install -r requirements.txt
alembic upgrade head  # 或由 init_db 自动创建表与默认“大厅”
uvicorn main:app --reload --host 0.0.0.0 --port 8000
# http://localhost:8000/health  ws://localhost:8000/ws?token=<JWT>
```

### 2. 前端
```bash
cd frontend
pnpm install
pnpm dev  # http://localhost:5173
```

流程：注册→登录→大厅→创建/加入房间→好友申请/私聊→语音/文件/引用→搜索/通话/通知。需 HTTPS 以支持 WebRTC 与 Service Worker。

### 3. Docker
```bash
docker-compose up --build  # 需 Nginx client_max_body_size 25m
```

## 常用命令

```bash
cd backend; pytest -v          # 61 项
cd frontend; pnpm test         # 32 项
pnpm run build                 # 含 PWA sw.js
```

## 契约与文档

- 一期：`specs/001-h5-chatroom/`
- 二期：`specs/002-h5-chatroom-phase2/`
- 三期：`specs/003-h5-chatroom-phase3/`（含 `rest-api.md` + `websocket-protocol.md` + `quickstart.md`）