docs: describe websocket chatroom project

README.md

@@ -0,0 +1,154 @@
+# چت‌روم ساده با WebSocket
+
+این پروژه برای درس **مهندسی اینترنت** آماده شده است و هدف اصلی آن نمایش یک نمونه ساده از برنامه‌نویسی **Socket / WebSocket** در قالب یک چت‌روم تحت وب است. در این برنامه چند کاربر می‌توانند با مرورگر وارد یک اتاق مشترک شوند و پیام‌ها را به صورت هم‌زمان دریافت کنند. رابط کاربری فارسی است و از فونت وزیرمتن استفاده می‌کند.
+
+## اعضای گروه
+
+- علیرضا خسروی
+- مرتضی خان‌بابائی
+- امیرحسین خلیلی
+
+## هدف پروژه
+
+هدف پروژه، تمرکز روی نحوه کار WebSocket است. برخلاف ارتباط معمول HTTP که در آن مرورگر درخواست می‌فرستد و سرور پاسخ می‌دهد، در WebSocket یک ارتباط پایدار بین مرورگر و سرور باز می‌ماند. به همین دلیل سرور می‌تواند پیام جدید را همان لحظه برای همه کاربران حاضر در اتاق ارسال کند.
+
+## امکانات
+
+- اتصال کاربران به سرور با WebSocket
+- پشتیبانی از چند اتاق گفتگو
+- ارسال پیام به همه کاربران حاضر در همان اتاق
+- نمایش پیام‌های ورود و خروج کاربران
+- نمایش فهرست کاربران آنلاین هر اتاق
+- رابط کاربری فارسی، راست‌به‌چپ و ساده
+- مسیر کمکی `/api/rooms` برای مشاهده اتاق‌های فعال
+- مسیر `/health` برای بررسی روشن بودن سرور
+
+## تکنولوژی‌های استفاده‌شده
+
+- Python
+- FastAPI
+- WebSocket
+- Uvicorn
+- HTML
+- CSS
+- JavaScript
+
+## ساختار پروژه
+
+```text
+chatroom_completed/
+├── app/
+│   ├── main.py
+│   ├── static/
+│   │   ├── index.html
+│   │   ├── style.css
+│   │   ├── app.js
+│   │   └── Vazirmatn[wght].woff2
+│   └── websocket/
+│       ├── chat.py
+│       └── manager.py
+├── requirements.txt
+└── README.md
+```
+
+## توضیح فایل‌های اصلی
+
+فایل `app/main.py`
+
+نقطه شروع برنامه FastAPI است. در این فایل فایل‌های استاتیک فرانت‌اند سرو می‌شوند، مسیر WebSocket به برنامه اضافه می‌شود و چند مسیر ساده مثل `/` و `/health` تعریف شده‌اند.
+
+فایل `app/websocket/chat.py`
+
+مسیر اصلی WebSocket در این فایل قرار دارد:
+
+```text
+ws://localhost:8000/ws/{room_id}/{client_id}
+```
+
+این فایل اتصال کاربر را می‌پذیرد، پیام‌های دریافتی را می‌خواند و پیام‌ها را برای کاربران همان اتاق پخش می‌کند.
+
+فایل `app/websocket/manager.py`
+
+این فایل اتصال‌های فعال را نگه می‌دارد. هر اتاق یک لیست از کاربران متصل دارد. وظایف اصلی آن شامل اتصال کاربر، قطع اتصال، ارسال پیام و گرفتن فهرست کاربران آنلاین است.
+
+فایل `app/static/app.js`
+
+کد JavaScript مرورگر است. این فایل یک شیء `WebSocket` می‌سازد، پیام‌ها را به سرور می‌فرستد و پیام‌های برگشتی سرور را در صفحه نمایش می‌دهد.
+
+## روش اجرا
+
+ابتدا وابستگی‌ها را نصب کنید:
+
+```bash
+python -m venv .venv
+```
+
+در ویندوز PowerShell:
+
+```powershell
+.\.venv\Scripts\activate
+```
+
+در Linux یا macOS:
+
+```bash
+source .venv/bin/activate
+```
+
+سپس:
+
+```bash
+pip install -r requirements.txt
+uvicorn app.main:app --reload
+```
+
+بعد از اجرا، این آدرس را در مرورگر باز کنید:
+
+```text
+http://localhost:8000
+```
+
+اگر پورت `8000` روی سیستم شما اشغال بود، می‌توانید برنامه را روی پورت دیگری اجرا کنید:
+
+```bash
+uvicorn app.main:app --reload --port 8010
+```
+
+## روش آزمایش
+
+1. آدرس `http://localhost:8000` را در دو تب مرورگر باز کنید.
+2. در هر تب یک نام متفاوت وارد کنید.
+3. در هر دو تب نام اتاق یکسان باشد، مثلا `عمومی`.
+4. دکمه اتصال را بزنید.
+5. از یک تب پیام بفرستید و دریافت هم‌زمان آن را در تب دیگر مشاهده کنید.
+
+## نمونه آدرس WebSocket
+
+```text
+ws://localhost:8000/ws/عمومی/علی
+```
+
+اگر پروژه روی HTTPS اجرا شود، مرورگر به جای `ws` از `wss` استفاده می‌کند.
+
+## روند کار WebSocket در این پروژه
+
+1. کاربر در صفحه HTML نام و اتاق را وارد می‌کند.
+2. فایل `app.js` یک اتصال WebSocket به سرور باز می‌کند.
+3. سرور در `chat.py` اتصال را قبول می‌کند.
+4. فایل `manager.py` کاربر را به لیست کاربران همان اتاق اضافه می‌کند.
+5. وقتی کاربر پیامی می‌فرستد، سرور پیام را دریافت می‌کند.
+6. سرور همان پیام را برای همه اتصال‌های فعال در همان اتاق ارسال می‌کند.
+7. مرورگر پیام جدید را بدون Refresh شدن صفحه نمایش می‌دهد.
+
+## نکته آموزشی
+
+این پروژه عمدا ساده نگه داشته شده است. در آن ثبت‌نام، پایگاه داده، ذخیره تاریخچه پیام‌ها و احراز هویت پیاده‌سازی نشده‌اند، چون هدف اصلی پروژه نمایش ارتباط زنده با WebSocket است.
+
+## پیشنهادهای توسعه
+
+- ذخیره پیام‌ها در SQLite یا PostgreSQL
+- اضافه کردن صفحه ورود کاربران
+- نمایش وضعیت تایپ کردن
+- ارسال پیام خصوصی
+- محدود کردن نام اتاق‌ها و نام کاربران
+- اضافه کردن Dockerfile برای اجرای ساده‌تر