mobiniqow
cba4bc30da
git-subtree-dir: web git-subtree-mainline:75a0ba593dgit-subtree-split:8f624e7416
104 lines
6.1 KiB
Markdown
104 lines
6.1 KiB
Markdown
# دلدل — فرانت 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 واقعی
|
|
جایگزین کنی.
|