پلتفرم چندکلینیکی BeautyClinic یک SaaS برای مدیریت کلینیک‌های زیبایی است که احراز هویت مبتنی بر OTP (کاوه‌نگار)، طرح رایگان/پولی، پرداخت BitPay و داشبورد وب (Next.js) را در قالب یک مونو ریپو ارائه می‌کند. این سند راه‌اندازی سریع، متغیرهای محیطی و جریان‌های کلیدی MVP را پوشش می‌دهد.

• Python 3.12، Django 5، Django REST Framework و SimpleJWT برای API و صدور توکن.
• PostgreSQL برای داده اصلی و Redis برای کش/Rate Limit OTP.
• Celery اختیاری برای صف‌بندی ارسال OTP و وبهوک‌ها.
• Kavenegar برای ارسال کد یک‌بارمصرف و BitPay برای پرداخت اشتراک.

• Next.js (App Router) با TypeScript، TailwindCSS و React Query برای مدیریت داده.
• Zod و React Hook Form برای اعتبارسنجی فرم‌های احراز هویت و عملیات کلینیک.
• ذخیره توکن دسترسی در HttpOnly cookie یا حافظه به همراه Refresh cookie.

• Docker Compose برای اجرای PostgreSQL، Redis، Backend و Frontend.
• پیکربندی CORS محدود به مبدأ فرانت‌اند و ثبت لاگ برای OTP و وبهوک پرداخت.

beauty-platform/
├─ README.md
├─ AGENTS.md
├─ docker-compose.yml
├─ .env.example
├─ backend/
│  ├─ Dockerfile
│  ├─ requirements.txt
│  └─ app/ (Django apps: accounts، clinics، patients، services، appointments، billing)
└─ frontend/
   └─ Dockerfile

1. کپی کردن فایل‌های نمونه پیکربندی:

   cp .env.example .env
   cp backend/.env.example backend/.env
   cp frontend/.env.example frontend/.env

2. ساخت و اجرای سرویس‌ها:

   docker compose up --build

3. دسترسی‌ها پس از بالا آمدن کانتینرها:
   • Backend: http://localhost:${BACKEND_PORT:-8000}
   • Frontend: http://localhost:${FRONTEND_PORT:-3000}
   • PostgreSQL: پورت ${POSTGRES_PORT:-5432} با نام سرویس postgres
   • Redis: پورت ${REDIS_PORT:-6379} با نام سرویس redis

1. نصب پیش‌نیازها و فعال‌سازی محیط مجازی:

   cd backend
   python -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt

2. تنظیم متغیرها و مهاجرت پایگاه داده:

   cp .env.example .env
   python app/manage.py migrate

3. اجرای سرور توسعه:

   python app/manage.py runserver 0.0.0.0:8000

1. نصب وابستگی‌ها:

   cd frontend
   npm install

2. تنظیم متغیرهای محیطی و اجرای توسعه:

   cp .env.example .env
   npm run dev

• احراز هویت OTP (کاوه‌نگار): ارسال کد ۶ رقمی با تمپلیت‌های ورود و بازیابی، نگهداری هش OTP و محدودیت نرخ ارسال (۳ بار در ۱۰ دقیقه). پس از تایید، کاربر و کلینیک اولیه ایجاد می‌شود.
• مدیریت کلینیک و نقش‌ها: کاربران با نقش OWNER و STAFF (و امکان DOCTOR) در یک پایگاه داده مشترک نگهداری می‌شوند و تمامی کوئری‌ها بر اساس clinic_id محدود می‌شوند.
• رزرو و پرونده: بیمار، خدمت، نوبت و Procedure با وضعیت‌های SCHEDULED/CHECKED_IN/DONE/CANCELED/NO_SHOW و نسبت‌دهی به کاربر ایجادکننده ذخیره می‌شود.
• پرداخت و اشتراک: پلن FREE/Paid با BitPay مدیریت می‌شود. ایجاد Checkout از Backend انجام می‌شود، فعال‌سازی پلن تنها پس از وبهوک موفق BitPay صورت می‌گیرد و وضعیت اشتراک در /app/billing نمایش داده می‌شود.

• اجرای تست‌های Backend (پس از نصب وابستگی‌ها):

  cd backend
  source .venv/bin/activate
  python app/manage.py test

• اجرای Lint/تست‌های Frontend (در صورت فعال بودن اسکریپت‌ها):

  cd frontend
  npm test

• مقادیر محرمانه (کلیدها و توکن‌ها) را فقط در فایل‌های .env نگه دارید و در کنترل نسخه قرار ندهید.
• دسترسی CORS را به دامنه‌های مورد اعتماد محدود کنید و طول عمر توکن‌ها را مطابق نیاز محیط تولید کاهش دهید.
• لاگ OTP و پرداخت را بدون ثبت کد خام یا داده کارت نگه‌داری کنید و وبهوک BitPay را با BITPAY_WEBHOOK_SECRET اعتبارسنجی نمایید.