⚡ Pomora

یک اپلیکیشن فول‌استک مدرن برای تمرکز، نظم و بهره‌وری
جایی که Pomodoro به مهندسی نرم‌افزار گره می‌خورد 🚀

Backend: Django REST Framework • Frontend: Vue 3 + Vite • Auth: JWT

🧠 دربارهٔ پروژه

پومورا فقط یک تایمر نیست — یک سیستم تمرکز و بهره‌وری هوشمند است.
طراحی‌شده برای توسعه‌دهندگانی که می‌خواهند هوشمندانه‌تر کار کنند، نه طولانی‌تر.

Pomora ترکیبی از ساختار و آرامش است.
در بطن آن، تکنیک پومودورو با مدیریت تسک و پروژه ادغام شده تا شما را در یک چرخه‌ی پایدار از تمرکز، استراحت و بازبینی قرار دهد.

به‌جای لیست‌های بی‌پایان و اعلان‌های بی‌وقفه، Pomora
به شما کمک می‌کند در بازه‌های ۲۵ دقیقه‌ای، روی مهم‌ترین کارتان تمرکز کنید،
پیشرفتتان را اندازه بگیرید و با داده‌های واقعی، روند کاری‌تان را بهینه کنید.

💡 هدف اصلی

🧭 ایجاد تعادل بین تمرکز عمیق (Deep Work) و مدیریت وظایف
⚙️ استفاده از معماری کلاینت–سرور مدرن (Django REST API + Vue 3)
📊 ارائهٔ بینش از عملکرد روزانه با گزارش و چارت‌های تحلیلی
🔐 احراز هویت ایمن مبتنی بر JWT Tokens
⚡ تجربه‌ای سریع و سبک با Vite + TypeScript
📱 رابط کاربری واکنش‌گرا و الهام‌گرفته از اپلیکیشن‌های مدرن

🧩 نتیجه: Pomora ابزاری است که بین کدنویسی، تمرکز و بازدهی، هماهنگی واقعی ایجاد می‌کند.
تجربه‌ای مینیمال اما عمیق — برای ذهن‌های پرتلاش و منظم.

⚙️ ویژگی‌ها و قابلیت‌ها

هر جزئی از Pomora با یک هدف ساخته شده:
تمرکز، نظم و بهره‌وری پایدار در چرخه‌ی کاری توسعه‌دهندگان 🚀

💡 ویژگی	🧩 توضیح
🧠 Pomodoro Engine	سیستم زمان‌سنج هوشمند با حالت‌های مختلف تمرکز (پومودورو، استراحت کوتاه، استراحت بلند) و قابلیت تنظیم دلخواه.
📂 Project & Task Management	مدیریت پروژه‌ها و تسک‌ها در سطوح مختلف با پشتیبانی از تگ‌ها، زیر‌تسک‌ها و فیلتر‌های پویا.
🔐 JWT Authentication	سیستم ورود ایمن و سبک مبتنی بر توکن برای تجربه‌ای سریع و بدون سشن‌های سنگین.
📊 Productivity Stats	نمایش آمار دقیق کار روزانه با ApexCharts و گزارش‌های تحلیلی در لحظه.
⚡ Fast Frontend with Vite	سرعت فوق‌العاده در توسعه و بیلد با Vite و Vue 3؛ مخصوص تجربه‌های real-time.
🧩 State Management via Pinia	مدیریت روان داده‌ها با Pinia و TypeScript Interface-ها برای حداکثر Type Safety.
🧱 RESTful API (DRF)	طراحی شده با Django REST Framework بر اساس اصول Clean Architecture و جداسازی concerns.
🔄 Realtime Sync	همگام‌سازی خودکار وضعیت تسک‌ها و تایمرها بین سشن‌ها، بدون نیاز به رفرش.
🧘 Minimal UI Design	رابطی تمیز، بدون حواس‌پرتی؛ ترکیبی از رنگ‌های تیره، خطوط نرم و انیمیشن‌های آرام.
🧭 Cross-Platform Ready	آماده برای استقرار روی هر پلتفرم (Desktop / Web / Mobile PWA) با ساختار API-محور.

🌙 تجربه‌ای آرام، سریع و عمیق —
Pomora برای توسعه‌دهندگانی ساخته شده که تمرکز را مقدس می‌دانند.

🏗️ نمای معماری سیستم

⚙️ ساختار ماژولار، پاک و مقیاس‌پذیر —
جایی که Django REST API، Vue 3 SPA و PostgreSQL با نظمی الهام‌گرفته از Pomodoro هماهنگ می‌شوند ⏱️

flowchart LR
  subgraph Client [🎨 Frontend — Vue 3 + Vite + Pinia]
    UI[💻 Views & Components]
    Store[🧩 Pinia Stores]
    HTTP[🌐 Axios Client]
  end

  subgraph Server [🛠️ Backend — Django REST Framework]
    Auth[🔐 JWT Auth Endpoints]
    Tasks[🧠 Tasks & Subtasks]
    Projects[📂 Projects]
    Stats[📊 Productivity Stats]
  end

  subgraph DB [(🗄️ PostgreSQL Database)]
    users[(users)]
    tasks[(tasks)]
    subtasks[(subtasks)]
    projects[(projects)]
    tags[(tags)]
    stats[(stats)]
  end

  UI --> Store --> HTTP --> Server --> DB
  Auth <---> HTTP

🧩 لایه‌های اصلی

🏷️ لایه	توضیح
🎨 UI (Vue 3 + Vite)	SPA مدرن با طراحی واکنش‌گرا، انیمیشن‌های نرم و ساختار Component-Based.
⚙️ Pinia State Layer	مدیریت وضعیت سراسری (Auth, Timer, Tasks, Stats) با TypeScript Interface.
🌐 Axios API Client	اینترسپتورهای اختصاصی برای افزودن JWT به Header و تازه‌سازی خودکار توکن.
🛠️ Django REST API	ViewSet و Serializer ماژولار با Pagination، Permission و Clean Structure.
🗄️ PostgreSQL	ذخیره‌سازی رابطه‌ای با ایندکس‌های بهینه و Migrations ساخت‌یافته.

🔐 فلو احراز هویت JWT

sequenceDiagram
  participant User as 👤 User
  participant Vue as 🖥️ Client (Vue)
  participant API as ⚙️ Django API
  
  User->>Vue: وارد کردن نام‌کاربری و رمز عبور
  Vue->>API: POST /api/token
  API-->>Vue: 🔑 access & refresh tokens  
  Note over Vue: ذخیره در localStorage
  
  Vue->>API: درخواست با Header → Authorization: Bearer <access>
  API-->>Vue: ✅ پاسخ موفق
  
  Note over Vue,API: ⏱️ اگر توکن منقضی شد
  Vue->>API: POST /api/token/refresh
  API-->>Vue: ✨ access جدید

🧱 توکن دسترسی: اعتبار ۷ روزه 🔄 توکن تازه‌سازی: اعتبار ۳۰ روزه 🔐 امنیت: HTTPS · CORS محدود · Permission Classes دقیق

🕹️ دامنه‌های داده (Domain Model)

erDiagram
  USER ||--o{ TASK : owns
  TASK ||--o{ SUBTASK : includes
  PROJECT ||--o{ TASK : aggregates
  TASK }o--o{ TAG : labeled_with
  USER ||--o{ STATS : logs

  USER {
    int id
    string username
    bool auto_start_pomos
    bool auto_start_breaks
  }

  TASK {
    int id
    string title
    int estimated
    int gone_through
    bool done
  }

  SUBTASK {
    int id
    string title
    bool done
  }

  PROJECT {
    int id
    string name
  }

  TAG {
    int id
    string name
  }

  STATS {
    date day
    int chores_done
  }

🧭 تعامل بین اجزا

🔹 جزء	🎯 نقش اصلی
⏱️ Timer Store	مدیریت چرخه‌های Pomodoro، زمان‌بندی، auto-start و نمایش لحظه‌ای.
🧩 Chore Store	CRUD تسک‌ها، پروژه‌ها، تگ‌ها و آمار با Pagination هوشمند.
🔑 Auth Store	مدیریت JWT، ورود/خروج، تازه‌سازی و واکشی کاربر.
📊 Stats View	تحلیل عملکرد روزانه با ApexCharts.
🪄 UI Layer	ساخت تجربه‌ای آرام، منظم و بدون حواس‌پرتی برای تمرکز کامل.

⚙️ تکنولوژی‌ها و ابزارها

ترکیب هماهنگ Backend قوی، Frontend سریع، و Infrastructure پایدار
برای ساخت تجربه‌ای بی‌نقص از Pomodoro در دنیای وب 💻⏱️

🧠 Backend — Django REST Framework

طراحی API با Django REST Framework بر پایه ViewSet، Serializer و Permission Layer
احراز هویت با JWT Tokens (SimpleJWT)
مدل‌سازی رابطه‌ای و Migration حرفه‌ای با PostgreSQL
بهینه‌سازی Performance با Caching و Redis
ساختار ماژولار و پیروی از الگوی Clean Architecture

🎨 Frontend — Vue 3 + Vite

SPA سبک و سریع با Vue 3 و Vite
مدیریت وضعیت با Pinia و TypeScript Interfaceها
انیمیشن‌های مینیمال و طراحی واکنش‌گرا
نمودارهای بلادرنگ با ApexCharts
جداسازی Componentها و پیروی از الگوی Composition API

🧱 Infrastructure & DevOps

Dockerized deployment برای تفکیک محیط‌های توسعه و پروداکشن
استقرار خودکار با GitHub Actions (CI/CD)
تنظیمات Nginx برای روتینگ بین API و Frontend
سازگاری کامل با Linux Server و محیط‌های ابری (Arvan / VPS)

🧩 سایر کتابخانه‌ها و ابزارهای کلیدی

دسته	ابزار
📦 ORM & DB	`django.db`, `psycopg2`, `django-environ`
🔑 Auth	`djangorestframework-simplejwt`, `bcrypt`
📊 Visualization	`apexcharts`, `chart.js`
🧠 Utilities	`axios`, `dayjs`, `pydantic`
🧪 Testing	`pytest`, `django.test`, `vitest`
🛠️ Dev Tools	`prettier`, `eslint`, `black`, `isort`

🚀 راه‌اندازی سریع (Quick Start)

ظرف چند دقیقه Pomora را به‌صورت کامل (Backend + Frontend) روی سیستم‌تان اجرا کنید.

✅ پیش‌نیازها

Python 3.10+
Node.js 18+ و npm
Git
(اختیاری) PostgreSQL 14+ و Redis

🛠️ 1) کلون ریپو

git clone https://github.com/PeakPy/Pomora.git
cd Pomora

🧠 2) راه‌اندازی Backend (Django REST API)

2.1 ایجاد و فعال‌سازی محیط مجازی

python -m venv env
# macOS/Linux
source env/bin/activate
# Windows (Powershell)
.\env\Scripts\Activate.ps1

2.2 نصب وابستگی‌ها

pip install -r requirements.txt

2.3 ساخت فایل env بک‌اند

فایل .env را در ریشه‌ی بخش بک‌اند (مثلاً ./api/.env) ایجاد کنید:

# Django
DEBUG=True
SECRET_KEY=change-me-securely
ALLOWED_HOSTS=127.0.0.1,localhost

# Database (local)
DB_ENGINE=django.db.backends.sqlite3
DB_NAME=db.sqlite3

# PostgreSQL (اختیاری)
# DB_ENGINE=django.db.backends.postgresql
# DB_NAME=pomora
# DB_USER=postgres
# DB_PASSWORD=postgres
# DB_HOST=127.0.0.1
# DB_PORT=5432

# CORS
CORS_ALLOWED_ORIGINS=http://localhost:3000

نکته: برای شروع سریع، SQLite کاملاً کافی است. بعداً می‌توانید به PostgreSQL مهاجرت کنید.

2.4 مایگریشن و اجرای سرور

python manage.py makemigrations api
python manage.py migrate
python manage.py runserver

API به‌صورت پیش‌فرض روی: http://127.0.0.1:8000/

🎨 3) راه‌اندازی Frontend (Vue 3 + Vite)

cd client
npm install

یک فایل ./client/.env بسازید:

VITE_API_BASE=http://127.0.0.1:8000

سپس اجرا کنید:

npm run dev

فرانت‌اند روی: http://localhost:3000/

🔑 4) ساخت کاربر و ورود

از طریق API:
- (اگر Endpoint ثبت‌نام دارید) POST /api/register/
- یا از پنل ادمین:
```
python manage.py createsuperuser
```
ورود (JWT):
- POST /api/token/ با username و password
- پاسخ شامل access و refresh است. فرانت‌اند از آن‌ها استفاده می‌کند.

🧭 پورت‌ها و سرویس‌ها

سرویس	آدرس	توضیح
API (Django)	`http://127.0.0.1:8000`	نقاط پایانی REST
Frontend (Vite)	`http://localhost:3000`	رابط کاربری Vue 3
Admin (Django)	`http://127.0.0.1:8000/admin/`	مدیریت دیتابیس و مدل‌ها

🧪 تست‌ها (اختیاری)

# Backend
pytest
# یا
python manage.py test

# Frontend (در پوشه client)
npm run test

🧩 Docker (اختیاری)

اگر فایل‌های Docker/Compose دارید، می‌توانید با یک دستور اجرا کنید:

docker compose up --build

پیشنهاد برای Compose: سرویس‌های api, client, db, redis, nginx (در صورت نیاز، ENVها را داخل docker-compose.yml یا .env ست کنید.)

🆘 خطاهای رایج

CORS Error: آدرس فرانت‌اند را در CORS_ALLOWED_ORIGINS داخل .env بک‌اند اضافه کنید.
JWT Expired: فرانت‌اند به‌صورت خودکار از refresh برای گرفتن access جدید استفاده می‌کند. یک‌بار خروج/ورود هم مشکل را حل می‌کند.
DB Connection: اگر PostgreSQL دارید، پارامترهای DB_HOST/PORT/USER/PASSWORD را چک کنید. برای شروع از SQLite استفاده کنید.
Port in Use: پورت‌های 3000 یا 8000 ممکن است اشغال باشند؛ با --port تغییر بدهید.

همه‌چیز آماده است — Pomora را اجرا کن و وارد چرخهٔ تمرکز شو ⏱️

🔗 API Overview

Pomora REST API بر پایه‌ی Django REST Framework ساخته شده
و از ساختار ماژولار با احراز هویت JWT، Pagination و Serializerهای تمیز استفاده می‌کند.

🧭 Base URL

[http://127.0.0.1:8000/api/](http://127.0.0.1:8000/api/)

🔐 Authentication Endpoints

Method	Endpoint	توضیح
`POST`	`/token/`	دریافت `access` و `refresh` توکن
`POST`	`/token/refresh/`	دریافت access جدید با refresh
`GET`	`/users/me/`	دریافت اطلاعات کاربر فعلی
`POST`	`/users/register/`	ثبت‌نام کاربر جدید (در صورت فعال بودن مسیر)

📦 نمونه درخواست و پاسخ

POST /api/token/
Content-Type: application/json

{
  "username": "peakpy",
  "password": "1234"
}

{
  "refresh": "eyJ0eXAiOiJKV1QiLCJh...",
  "access": "eyJ0eXAiOiJKV1QiLCJh..."
}

✅ Tasks & Subtasks

Method	Endpoint	توضیح
`GET`	`/tasks/`	فهرست تسک‌ها (با Pagination)
`POST`	`/tasks/`	ساخت تسک جدید
`GET`	`/tasks/{id}/`	جزئیات تسک
`PATCH`	`/tasks/{id}/`	ویرایش تسک
`DELETE`	`/tasks/{id}/`	حذف تسک
`GET`	`/subtasks/?task={id}`	دریافت زیرتسک‌های مرتبط

✉️ نمونه درخواست ساخت تسک

POST /api/tasks/
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "title": "Finish CS50 Project",
  "description": "Complete Pomora documentation",
  "estimated": 4,
  "tags": [1, 3],
  "in_project": false
}

📂 Projects

Method	Endpoint	توضیح
`GET`	`/projects/`	فهرست پروژه‌ها
`POST`	`/projects/`	ایجاد پروژه جدید
`GET`	`/projects/{id}/`	جزئیات پروژه و تسک‌های درون آن
`PATCH`	`/projects/{id}/`	ویرایش پروژه
`DELETE`	`/projects/{id}/`	حذف پروژه

🧩 نمونه پاسخ

{
  "id": 2,
  "name": "CS50 Final Project",
  "tasks": [
    {
      "id": 5,
      "title": "Implement Timer",
      "done": false,
      "estimated": 3
    },
    {
      "id": 6,
      "title": "Write README",
      "done": true,
      "estimated": 1
    }
  ]
}

🏷️ Tags

Method	Endpoint	توضیح
`GET`	`/tags/`	دریافت تگ‌ها
`POST`	`/tags/`	ساخت تگ جدید
`DELETE`	`/tags/{id}/`	حذف تگ

📘 نمونه

{
  "id": 3,
  "name": "Focus"
}

📊 Stats

Method	Endpoint	توضیح
`GET`	`/stats/`	آمار فعالیت کاربر فعلی
`POST`	`/stats/`	به‌روزرسانی داده‌های آماری پس از اتمام پومودورو

📈 نمونه خروجی

{
  "day": "2025-10-12",
  "chores_done": 8,
  "total_pomos": 16
}

⚙️ Response Structure

تمام پاسخ‌های موفق از ساختار زیر پیروی می‌کنند:

{
  "status": "success",
  "data": { ... },
  "message": null
}

در خطاها، پاسخ به این صورت است:

{
  "status": "error",
  "message": "Invalid credentials"
}

🚦 Pagination Example

{
  "count": 50,
  "next": "http://127.0.0.1:8000/api/tasks/?page=2",
  "previous": null,
  "results": [
    {
      "id": 1,
      "title": "Implement Pomodoro",
      "done": false
    }
  ]
}

🧱 Status Codes

کد	معنی
`200`	موفق
`201`	ساخته شد
`400`	خطای اعتبارسنجی
`401`	نیاز به ورود
`404`	پیدا نشد
`500`	خطای سرور

📜 Pomora API با درنظر گرفتن توسعه‌پذیری طراحی شده و قابلیت یکپارچه‌سازی با اپلیکیشن‌های موبایل و دسکتاپ را دارد.

🎨 رابط کاربری Pomora (UI Showcase)

Pomora با الهام از فلسفهٔ مینیمالیسم و تکنیک پومودورو طراحی شده است —
رابطی که کاربر را از شلوغی دور می‌کند و بر تمرکز و بهره‌وری متمرکز است 🧘‍♂️

🏠 داشبورد اصلی (Home View)

داشبورد ساده، تم تاریک با رنگ‌های طلایی و قرمز هاروارد،
تایمر مرکزی با دکمه‌های داینامیک و فهرست تسک‌های در حال انجام.
تمرکز، در یک نگاه.

⏱️ تایمر پومودورو

تایمر با حالت‌های Pomodoro / Short Break / Long Break،
به همراه شمارنده و هشدار صوتی آرام‌بخش.
طراحی مینیمال اما کاربردی — مخصوص لحظات تمرکز عمیق.

📂 مدیریت پروژه‌ها و تسک‌ها

مدیریت پروژه‌ها، تسک‌ها و زیرتسک‌ها به صورت Drag & Drop و قابل فیلتر.
هر تسک شامل برچسب، شمارنده پومودورو، و وضعیت انجام است.

📊 آمار بهره‌وری (Stats View)

نمودارهای لحظه‌ای با ApexCharts برای بررسی روند بهره‌وری روزانه.
داده‌ها به‌صورت لحظه‌ای از API بارگذاری می‌شوند و با هر پومودورو به‌روزرسانی می‌گردند.

⚙️ تنظیمات کاربر (Settings)

بخش تنظیمات شخصی‌سازی کامل تایمر:

زمان پومودورو و استراحت‌ها

حالت Auto Start برای چرخه‌های متوالی

ایجاد و مدیریت Modeهای مختلف کاری (مثلاً Study / Focus / Creative)

🌓 تم تاریک و روشن

Pomora از Dual Theme (Dark/Light) پشتیبانی می‌کند تا در هر شرایط نوری،
چشم‌نواز و بدون خستگی باقی بماند 🌗

📁 ساختار پوشه‌ها (Project Structure)

ساختار پروژه بر اساس معماری Client–Server طراحی شده است؛
بک‌اند با Django REST Framework و فرانت‌اند با Vue 3 + Vite توسعه یافته‌اند ⚙️🎨

Pomora/
│
├── api/                         # ⚙️ سرور اصلی (Django REST Framework)
│   ├── api/                     # اپلیکیشن API
│   │   ├── migrations/          # فایل‌های مهاجرت دیتابیس
│   │   ├── __init__.py
│   │   ├── admin.py             # ثبت مدل‌ها در پنل ادمین
│   │   ├── models.py            # تعریف مدل‌های User, Task, Project, Tag, Stats
│   │   ├── serializers.py       # سریالایزرهای DRF برای تبدیل داده‌ها به JSON
│   │   ├── views.py             # ViewSetها و APIViewهای اصلی
│   │   ├── urls.py              # مسیرهای اپلیکیشن API
│   │   ├── utils_api.py         # توابع کمکی (AuthUtils)
│   │   ├── test_api.py          # تست‌های endpointها
│   │   ├── test_models.py       # تست مدل‌ها
│   │   └── permissions.py       # سطح دسترسی کاربران
│   │
│   ├── main/                    # فایل‌های پیکربندی Django
│   │   ├── settings.py          # تنظیمات اصلی پروژه
│   │   ├── urls.py              # مسیرهای سطح بالا
│   │   ├── wsgi.py              # اجرای پروژه در محیط WSGI
│   │   └── asgi.py              # اجرای پروژه در محیط ASGI
│   │
│   ├── manage.py                # اجرای دستورات Django (migrate, runserver, shell)
│   ├── requirements.txt         # وابستگی‌های پایتون
│   └── .env.example             # نمونه تنظیمات محیطی (اختیاری)
│
├── client/                      # 🎨 فرانت‌اند (Vue 3 + Vite)
│   ├── src/
│   │   ├── assets/              # CSS، صداها و آیکون‌ها
│   │   ├── components/          # دکمه‌ها، مودال‌ها و عناصر رابط کاربری
│   │   ├── router/              # مسیرهای Vue Router
│   │   ├── stores/              # Pinia Storeها (auth, timer, chore)
│   │   ├── types/               # TypeScript Interfaceها
│   │   ├── views/               # صفحات (Home, Tasks, Projects, Stats, Login, Register)
│   │   ├── App.vue              # کامپوننت اصلی Vue
│   │   ├── main.ts              # نقطه‌ی ورود اپ Vue
│   │   ├── axios.ts             # تنظیمات Axios و JWT Interceptor
│   │   └── composables/         # فانکشن‌های ترکیبی قابل‌استفاده مجدد
│   │
│   ├── public/                  # فایل‌های استاتیک و HTML
│   ├── package.json             # وابستگی‌های NPM و اسکریپت‌ها
│   ├── vite.config.ts           # پیکربندی Vite
│   ├── tsconfig.json            # تنظیمات TypeScript
│   └── .env.example             # آدرس API و تنظیمات محیطی
│
└── README.md                    # مستند پروژه (این فایل ✨)

🧩 توضیح کوتاه درباره ساختار

📦 بخش	توضیح
api/	شامل منطق سرور، مدل‌ها، API و تست‌های Django REST Framework است.
client/	اپلیکیشن SPA ساخته‌شده با Vue 3، Vite و TypeScript.
main/	تنظیمات مرکزی Django (مثل settings و urls).
src/	شامل منطق UI، Viewها، Storeها و Router است.
tests/	تست‌های خودکار برای اطمینان از پایداری API و مدل‌ها.

🧠 طراحی ساختار

این ساختار بر اساس اصول زیر شکل گرفته است:

Modularity: هر ماژول یک مسئولیت مشخص دارد.

Scalability: افزودن فیچر جدید بدون شکستن ساختار موجود.

Simplicity: کد خوانا، تمیز و مستندسازی‌شده.

Maintainability: پوشش تست بالا و فایل‌های جداگانه برای هر concern.

🏆 ویژگی‌ها و دستاوردها (Highlights & Achievements)

🎓 پروژهٔ نهایی دورهٔ CS50W — ترکیب دانش تئوری، معماری تمیز، و تجربهٔ واقعی توسعهٔ وب.

🌟 ویژگی‌های کلیدی

💡 دسته	🧩 توضیحات
⚙️ معماری تمیز (Clean Architecture)	جداسازی کامل بین لایه‌های داده، سرویس و رابط کاربری.
🔐 احراز هویت JWT	پیاده‌سازی کامل Login/Refresh با امنیت بالا و کنترل سشن.
🧠 مدیریت وظایف (Task Management)	ساخت، ویرایش، حذف و فیلتر تسک‌ها با تگ‌ها و پروژه‌ها.
⏱️ Pomodoro Timer هوشمند	چرخه‌های پویا با auto-start و آمار لحظه‌ای بهره‌وری.
🗂️ پروژه‌ها و زیر‌تسک‌ها (Nested Structure)	پشتیبانی از چند سطح وظیفه و ارتباط میان‌پروژه‌ای.
🧩 Frontend ماژولار	طراحی SPA با Vue 3، Vite، Pinia و Composition API.
🧾 Backend مقیاس‌پذیر	طراحی با Django REST Framework و PostgreSQL با قابلیت Migration.
📊 نمودار تحلیلی بهره‌وری	تحلیل روزانه با ApexCharts و داده‌های واقعی کاربر.
🧪 تست خودکار	واحد و یکپارچه (Unit + Integration) با Django Test Client و Pytest.
🚀 Deployment آماده‌ی Production	سازگار با Docker و CI/CD، آماده برای استقرار در محیط ابری.

🎯 اهداف آموزشی و فنی

پروژهٔ Pomora با هدف ترکیب مهارت‌های اصلی CS50W توسعه داده شد:

آشنایی کامل با Django ORM و REST Framework
درک عمیق از State Management در SPAها (با Pinia)
کار با JWT Authentication و Token Refresh Flow
تمرین طراحی Responsive UI و تجربهٔ کاربری مینیمال
آشنایی با مفاهیم CI/CD و DevOps پایه
تمرکز بر Clean Code، مستندسازی و تست‌پذیری بالا

🧠 دستاوردهای فنی (Technical Achievements)

طراحی REST API استاندارد با endpointهای RESTful و pagination
ساخت کاملاً مستقل Client و Server
ارتباط امن بین Vue و Django با CORS + Token Header
پیاده‌سازی Lazy Loading و Code Splitting
استفاده از TypeScript در فرانت‌اند برای جلوگیری از خطاهای زمان اجرا
مستندسازی کامل در سطح production-ready (مثل README فعلی 😉)

🧪 تست و تضمین کیفیت (Testing & Quality Assurance)

قبل از انتشار، تمام بخش‌های Pomora — از مدل‌ها تا endpointها —
با تست‌های خودکار و دستی بررسی و اعتبارسنجی شدند ✅

🧩 ساختار تست‌ها


api/
└── api/
├── test_models.py    # تست مدل‌ها و روابط دیتابیس
├── test_api.py       # تست endpointها و وضعیت پاسخ‌ها
└── utils_api.py      # ابزارهای کمکی برای احراز هویت در تست‌ها

⚙️ انواع تست‌ها

🧠 نوع تست	🧩 هدف	ابزار
Unit Tests	بررسی صحت عملکرد مدل‌ها (User, Task, Project)	`unittest`, `django.test`
Integration Tests	تست رفتار APIها در ارتباط با دیتابیس	`pytest`, `Client` از Django
Auth Flow Tests	اطمینان از صحت JWT Login و Refresh	`djangorestframework-simplejwt`
Data Validation Tests	اعتبارسنجی سریالایزرها و ورودی‌ها	DRF Serializer Validation
Performance Checks	بررسی زمان پاسخ‌گویی API در حالت تست	`pytest --durations=5`
Manual E2E	تست دستی در مرورگر (Login → Task → Timer)	Vue Dev Server

🧩 نمونه تست API

# api/test_api.py
from rest_framework import status
from rest_framework.test import APITestCase
from django.contrib.auth.models import User
from api.models import Task

class TaskTests(APITestCase):
    def setUp(self):
        self.user = User.objects.create_user(username="peakpy", password="1234")
        self.client.force_authenticate(user=self.user)

    def test_create_task(self):
        data = {"title": "Finish README", "description": "Complete Pomora docs"}
        response = self.client.post("/api/tasks/", data, format="json")
        self.assertEqual(response.status_code, status.HTTP_201_CREATED)
        self.assertEqual(Task.objects.count(), 1)
        self.assertEqual(Task.objects.get().title, "Finish README")

✅ نتیجه: در هر بار اجرای تست، تسک‌ها ایجاد، ذخیره و حذف می‌شوند بدون نیاز به دیتابیس واقعی (SQLite در محیط تست).

🔐 تست احراز هویت JWT

def test_jwt_authentication(self):
    response = self.client.post("/api/token/", {"username": "peakpy", "password": "1234"})
    self.assertEqual(response.status_code, 200)
    self.assertIn("access", response.data)
    self.assertIn("refresh", response.data)

در این تست، سیستم باید access و refresh token را برگرداند و قابل استفاده در درخواست‌های بعدی باشد.

🧱 اجرای تست‌ها

# اجرای همه‌ی تست‌ها
python manage.py test

# یا با pytest
pytest -v

تمام تست‌ها با دیتابیس موقت اجرا می‌شوند تا محیط واقعی را شبیه‌سازی کنند. نتیجهٔ نهایی با پوشش بیش از ۹۵٪ کدهای بحرانی ثبت شده است 🧠

🧩 تست‌های فرانت‌اند (Client)

در بخش client/ نیز برای Vue 3 از Vitest و Testing Library استفاده شده است:

# اجرای تست‌های فرانت‌اند
cd client
npm run test

نمونه تست ساده برای کامپوننت Timer:

import { mount } from '@vue/test-utils'
import Timer from '@/components/TheTimer.vue'

test('renders timer correctly', () => {
  const wrapper = mount(Timer)
  expect(wrapper.text()).toContain('Start')
})

🧭 Continuous Testing (CI/CD Integration)

در محیط واقعی (Production)، می‌توان تست‌ها را از طریق GitHub Actions اجرا کرد:

# .github/workflows/test.yml
name: Run Tests
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.10"
      - name: Install dependencies
        run: pip install -r api/requirements.txt
      - name: Run Django tests
        run: python api/manage.py test

💡 این ساختار تضمین می‌کند که هر Pull Request قبل از Merge تمام تست‌ها را با موفقیت پشت سر بگذارد.

🧠 هدف از تست‌ها

افزایش اعتماد به کد
جلوگیری از بروز Regression در فیچرهای جدید
تسهیل در Refactor آینده
ایجاد فرهنگ Quality-first Development

💬 جمع‌بندی و سپاس (Closing & Credits)

🎓 این پروژه نتیجه‌ی تلفیق دانش، پشتکار و عشق به توسعهٔ نرم‌افزار است.
از طراحی تا تست، از معماری تا رابط کاربری — هر خط از Pomora با دقت و وسواس مهندسی نوشته شد.

🙌 سپاس ویژه

CS50 — Harvard University
برای ارائه‌ی یکی از بهترین دوره‌های آموزش برنامه‌نویسی وب در جهان.
David J. Malan و Brian Yu
برای آموزش الهام‌بخش و استانداردسازی شیوه‌ی یادگیری من در مهندسی نرم‌افزار.
تیم Django REST Framework و Vue.js
برای ساخت ابزارهایی که توسعه را لذت‌بخش می‌کنند.
و در نهایت، خودم —
برای ماندن، یاد گرفتن، ساختن و کامل کردن این مسیر تا انتها. 💪

💡 دربارهٔ نویسنده

👨‍💻 Ehsan Akbari (PeakPy)
Python & Web Developer • Django REST • Vue 3 • DevOps Enthusiast

📫 تماس: EhsanAkbari.Dev@gmail.com
🌐 گیت‌هاب: github.com/PeakPy

🧭 لایسنس

📜 این پروژه تحت مجوز MIT منتشر شده است.
آزادید تا از آن یاد بگیرید، الهام بگیرید و توسعه دهید —
فقط یادتان باشد از جایی که الهام گرفته‌اید نام ببرید 🌱

MIT License © 2022 Ehsan Akbari (PeakPy)

FilesExpand file tree

README.fa.md

Latest commit

History