# دلدل — فرانت PWA اپ دیتینگ (Next.js + Basis Design System)

فرانت موبایل‌محور و PWA برای بک‌اند Go/Gin/GORM که قبلاً ساختیم، با همون
Basis Design System (نسخه‌ی شاد و گرد Atlas): قرمز پرانرژی، گوشه‌های گرد،
سایه‌های نرم، فونت Vazirmatn + Baloo 2.

## ویژگی‌ها

- ورود با شماره موبایل + کد OTP (بدون پسورد)
- ۸ مرحله‌ی آنبوردینگ دقیقاً مطابق API بک‌اند (با state machine که جلوی پرش
  از مرحله رو می‌گیره، ولی اجازه‌ی برگشت و ویرایش می‌ده)
- صفحه‌ی پروفایل کامل با دکمه‌ی ویرایش روی هر بخش (برمی‌گرده به همون مرحله‌ی
  آنبوردینگ، چون بک‌اند بعد از تکمیل کامل اجازه‌ی ویرایش هر مرحله رو می‌ده)
- شبیه‌سازی یک اپ سه‌تبه (کشف/پروفایل/تنظیمات) — تب «کشف» چون بک‌اند فعلاً
  matching نداره، حالت «به‌زودی» نشون می‌ده
- PWA کامل: قابل نصب روی گوشی (`manifest.webmanifest` + service worker +
  آیکون)، تمام صفحات موبایل‌فرست و محدود به عرض یک گوشی

## ✅ تست شده

قبل از تحویل، کل مسیر کاربر (درخواست OTP → تایید → ۸ مرحله‌ی آنبوردینگ →
پروفایل نهایی → رفرش توکن) با یک اسکریپت Node که دقیقاً همون درخواست‌های
`src/lib/api.ts` رو می‌فرسته، روی یک نمونه‌ی واقعی از بک‌اند گو اجرا و با
موفقیت پاس شد — شامل تست‌های منفی (OTP اشتباه، انتخاب ناقص علاقه‌مندی).
یعنی قرارداد بین این فرانت و بک‌اندی که قبلاً تحویل گرفتی، تضمین‌شده هم‌خونه.

## راه‌اندازی

### ۱) تنظیم آدرس بک‌اند

```bash
cp .env.local.example .env.local
```

و `NEXT_PUBLIC_API_URL` رو به آدرس واقعی بک‌اندت تغییر بده (پیش‌فرض
`http://localhost:8080/api/v1`).

### ۲) نصب و اجرا

```bash
npm install
npm run dev
```

`http://localhost:3000` رو باز کن. برای تست موبایل واقعی، از ابزار
device-toolbar مرورگر استفاده کن یا با آی‌پی لوکال شبکه از گوشی وصل شو.

### ۳) نصب به‌عنوان PWA

- **اندروید/کروم:** منوی مرورگر → «Add to Home screen»
- **iOS/Safari:** دکمه‌ی Share → «Add to Home Screen»

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

## ساختار پروژه

```
src/
├── app/
│   ├── layout.tsx              ← فونت، متادیتای PWA، AuthProvider
│   ├── page.tsx                ← ریدایرکت اولیه بر اساس وضعیت کاربر
│   ├── login/page.tsx          ← ورود با شماره موبایل
│   ├── verify/page.tsx         ← تایید کد OTP
│   ├── onboarding/
│   │   ├── [slug]/page.tsx     ← صفحه‌ی داینامیک هر ۸ مرحله
│   │   └── done/page.tsx       ← صفحه‌ی تبریک پایان آنبوردینگ
│   └── (main)/                 ← اپ اصلی بعد از آنبوردینگ (با BottomNav)
│       ├── layout.tsx
│       ├── home/page.tsx       ← کشف (placeholder "به‌زودی")
│       ├── profile/page.tsx    ← پروفایل کامل + دکمه‌ی ویرایش هر بخش
│       └── settings/page.tsx   ← خروج از حساب + آیتم‌های "به‌زودی"
├── components/
│   ├── ui/                     ← کامپوننت‌های پایه‌ی دیزاین‌سیستم
│   ├── onboarding/              ← wrapper و ۸ کامپوننت هر مرحله
│   └── BottomNav.tsx
└── lib/
    ├── api.ts                  ← کلاینت تایپ‌شده‌ی کامل API (منطبق با بک‌اند گو)
    ├── auth-context.tsx        ← مدیریت وضعیت ورود/کاربر/آنبوردینگ
    ├── token-store.ts          ← ذخیره‌ی توکن‌ها در localStorage
    ├── onboarding-steps.ts     ← ترتیب و متادیتای ۸ مرحله
    └── hooks.ts                ← useRequireAuth، فرمت خطا
```

## نکات فنی مهم

- **رفرش خودکار توکن:** اگه access token منقضی بشه، `api.ts` خودکار با
  refresh token یه توکن جدید می‌گیره و درخواست رو یک‌بار دوباره می‌فرسته؛
  کاربر چیزی حس نمی‌کنه.
- **گارد مراحل آنبوردینگ:** هر صفحه‌ی مرحله چک می‌کنه که کاربر اجازه‌ی
  دیدن اون مرحله رو داره یا نه (بر اساس `current_step` از بک‌اند)؛ اگه
  بخواد از روی مرحله بپره، خودکار به مرحله‌ی درست برمی‌گرده.
- **فونت self-hosted:** مثل دیزاین‌سیستم قبلی، فونت‌ها از `@fontsource-variable`
  میان (نه `next/font/google`) تا هیچ‌وقت به گوگل وصل نشه.
- **CORS:** بک‌اند گو از قبل CORS باز داره، پس این فرانت روی هر پورت/دامنه‌ای
  بدون تنظیم اضافه بهش وصل می‌شه.

## محدودیت شناخته‌شده

تب «کشف» (matching/کشف افراد) و بخش چت هنوز در بک‌اند پیاده نشدن، پس فقط
یک EmptyState با برچسب «به‌زودی» نشون داده می‌شه. هر وقت اون endpoint ها
رو ساختی، فقط کافیه `src/app/(main)/home/page.tsx` رو با فراخوانی API واقعی
جایگزین کنی.