# اپلیکیشن دوستیابی — بک‌اند Go (Gin + GORM + PostgreSQL)

یک بک‌اند تمیز و لایه‌بندی‌شده برای یک اپ دوستیابی با:
- احراز هویت فقط با شماره موبایل + کد OTP (بدون پسورد)
- فرآیند آنبوردینگ مرحله‌به‌مرحله (۸ مرحله) برای تکمیل پروفایل
- سیستم عمومی «دسته + گزینه» که کاملاً از طریق API ادمین قابل مدیریت است
  (بدون نیاز به تغییر کد برای اضافه/حذف گزینه‌های هر لیست)
- سوالات پروفایل (Q&A) که ادمین تعریف می‌کند و کاربر ۳ تای آن را انتخاب می‌کند

## ساختار پروژه (لایه‌بندی تمیز)

```
dating-app/
├── cmd/api/main.go              # نقطه ورود، wiring همه‌چیز
├── internal/
│   ├── config/                  # خواندن تنظیمات از .env
│   ├── database/                # اتصال دیتابیس، migrate، seed
│   ├── models/                  # مدل‌های GORM
│   ├── dto/                     # ساختار request/response ها
│   ├── repository/              # لایه دسترسی به داده (فقط query)
│   ├── service/                 # منطق تجاری (validation، state machine و...)
│   ├── handler/                 # هندلرهای HTTP (gin.Context)
│   ├── middleware/               # auth، admin، cors
│   └── router/                  # تعریف روت‌ها
├── go.mod / go.sum
└── .env.example
```

لایه‌بندی مشابه الگوی selector/service که در پروژه‌ی جنگویی قبلی‌تون بود:
`repository` = selector (فقط query خام)، `service` = منطق و اعتبارسنجی،
`handler` = فقط ترجمه‌ی HTTP request/response.

## اجرا

### ۱) پیش‌نیاز: PostgreSQL

```bash
createdb dating_app
```

### ۲) تنظیمات

```bash
cp .env.example .env
# مقادیر رو مطابق محیط خودت ویرایش کن (خصوصاً JWT_*_SECRET و OTP_HASH_SECRET در پروداکشن)
```

`ADMIN_BOOTSTRAP_PHONE` رو به شماره‌ی موبایل خودت تنظیم کن؛ در اولین اجرای برنامه
یک کاربر ادمین با اون شماره ساخته می‌شه (یا اگه از قبل وجود داشت، ادمین می‌شه).
بعدش با همون شماره از مسیر عادی OTP وارد شو تا توکن ادمین بگیری.

### ۳) اجرا

```bash
go run ./cmd/api
```

سرور روی `http://localhost:8080` بالا میاد. مسیر `/health` برای healthcheck هست.

## اتصال گیت‌وی پیامک واقعی

فعلاً `service.MockOTPSender` استفاده می‌شه که کد OTP رو به‌جای ارسال واقعی توی
لاگ چاپ می‌کنه (`internal/service/otp_sender.go`). برای وصل کردن یک گیت‌وی واقعی:

```go
type KavenegarOTPSender struct{ apiKey string }

func (s *KavenegarOTPSender) Send(phone, otp string) bool {
    // درخواست HTTP به گیت‌وی، صبر برای پاسخ، و true/false واقعی برگردون.
    // این تابع باید SYNC باشه (نتیجه‌ی واقعی رو برگردونه)، وگرنه کاربر حتی
    // در صورت شکست واقعی ارسال، پیام موفقیت می‌گیره.
}
```

و در `cmd/api/main.go` خط `otpSender := service.NewMockOTPSender(...)` رو با
`otpSender := &KavenegarOTPSender{apiKey: cfg.KavenegarAPIKey}` عوض کن. بقیه‌ی
کد (`AuthService` و...) نیازی به تغییر نداره چون فقط با اینترفیس `OTPSender` کار می‌کنه.

## فرآیند آنبوردینگ

۹ مرحله‌ی ثابت که باید به‌ترتیب طی بشن (نمی‌شه از روی مرحله پرید، ولی مراحل
قبلی هر وقت بخوای قابل ویرایش‌اند؛ بعد از تکمیل کامل هم همه‌ی مراحل آزادانه
قابل ویرایش می‌شن — حتی توی همون بازه‌ای که کاربر منتظر تایید ادمینه):

| # | مرحله | Endpoint |
|---|-------|----------|
| ۱ | جنسیت، اسم، تاریخ تولد | `POST /onboarding/basic-info` |
| ۲ | عکس‌ها (حداقل ۱ عکس؛ خودِ آپلود از `/profile/photos`) | `POST /onboarding/photos` |
| ۳ | قد و وزن | `POST /onboarding/body-info` |
| ۴ | ۳ سوال از پیش‌تعریف‌شده + پاسخ | `POST /onboarding/profile-questions` |
| ۵ | سطح تحصیلات + رشته | `POST /onboarding/education` |
| ۶ | کارهایی که انجام می‌دهد (چندتایی) | `POST /onboarding/occupations` |
| ۷ | ۳ چیز مهم در رابطه | `POST /onboarding/relationship-importance` |
| ۸ | ۵ علاقه‌مندی | `POST /onboarding/interests` |
| ۹ | دنبال چی می‌گردی | `POST /onboarding/looking-for` |

وضعیت فعلی: `GET /onboarding/status`

اگه کاربر قبلاً رد شده باشه و بعد از onboarded شدن هرکدوم از مراحل رو دوباره
بزنه (حتی مرحله‌ی عکس‌ها)، `approval_status` خودکار به `pending` برمی‌گرده تا
ادمین دوباره بررسی کنه.

### بعد از تکمیل آنبوردینگ: تایید ادمین

به محض تکمیل مرحله‌ی ۸، `approval_status` کاربر روی `pending` قرار می‌گیرد.
کاربر تا وقتی ادمین تاییدش نکنه (`approved`) اجازه‌ی ورود به صفحه‌ی دوستیابی
رو نداره (این بخش در فاز بعدی پیاده می‌شه). اپ باید بعد از `is_onboarded=true`،
مقدار `approval_status` رو از `GET /onboarding/status` یا `GET /profile/me`
بخونه و بر اساسش یکی از این صفحات رو نشون بده:

| `approval_status` | صفحه‌ی مناسب در اپ |
|---|---|
| `pending`  | «در انتظار تایید ادمین» |
| `approved` | ورود به صفحه‌ی دوستیابی |
| `rejected` | نمایش `rejection_reason` + امکان ویرایش پروفایل |

اگر کاربر رد شده باشه و بعداً هر کدوم از مراحل آنبوردینگ رو ویرایش کنه،
`approval_status` خودکار به `pending` برمی‌گرده تا ادمین دوباره بررسی کنه.

گزینه‌های هر مرحله (که از پنل ادمین مدیریت می‌شن):
`GET /onboarding/options/:category` با یکی از این category ها:
`education_level`, `field_of_study`, `occupation`,
`important_in_relationship`, `interest`, `looking_for`

سوالات قابل‌انتخاب برای مرحله‌ی ۳: `GET /onboarding/profile-questions`

### چرا این معماری؟

به‌جای این‌که برای هر لیست (تحصیلات، علاقه‌مندی، اهداف رابطه و...) یک جدول
جدا بسازیم، یک سیستم عمومی «دسته (Category) + گزینه (Option)» ساختیم.
هر Category یک `min_select`/`max_select` داره (مثلاً علاقه‌مندی‌ها دقیقاً ۵
تا، تحصیلات دقیقاً ۱ تا، فعالیت‌ها بدون سقف). این یعنی:
- ادمین می‌تونه از طریق API هر وقت خواست گزینه اضافه/ویرایش/غیرفعال کنه،
  بدون نیاز به دیپلوی کد جدید.
- اضافه کردن یک دسته‌ی جدید در آینده فقط یک `INSERT` توی جدول `categories`
  می‌خواد، نه migration جدید.

## دوستیابی (Discovery)، مچ و پیام‌رسانی

بعد از این‌که کاربر تایید شد (`approval_status=approved`) وارد این بخش می‌شه.
تشخیص جنسیت مقابل فعلاً **ساده و هترو-پیش‌فرض** هست (زن↔مرد)؛ سیستم هنوز
فیلد جداگانه‌ای برای «ترجیح جنسیتی/گرایش» نداره.

فاصله از روی `latitude`/`longitude` کاربر (که هیچ‌وقت خام برنمی‌گرده، فقط
فاصله‌ی محاسبه‌شده) با فرمول haversine حساب و به نزدیک‌ترین کیلومتر گرد
می‌شه — یعنی از همون ابتدا تقریبیه، نه GPS دقیق.

```
GET    /profile/photos                       (داخل /profile/me برمی‌گرده، endpoint جدا نداره)
POST   /profile/photos                       آپلود عکس   multipart/form-data، فیلد "photo" (jpg/png/webp، حداکثر ۵ مگابایت، حداکثر ۶ عکس)
DELETE /profile/photos/:id                   حذف عکس
PATCH  /profile/location                     body: {latitude, longitude}

GET    /discover?max_distance_km=&min_age=&max_age=   لیست پیشنهادها (نزدیک‌ترین اول)
GET    /discover/:id                         پروفایل کامل یک کاندید
POST   /discover/:id/swipe                   body: {action: "like"|"pass"|"superlike"}
                                              اگه طرف مقابل هم قبلاً لایک کرده باشه، مچ ساخته می‌شه

GET    /matches                              لیست مچ‌ها (با آخرین پیام هرکدوم)
GET    /matches/:id/messages                 پیام‌های یک گفتگو
POST   /matches/:id/messages                 body: {text}
```

فایل‌های آپلودشده روی دیسک محلی سرور (`./uploads/photos`) ذخیره و از مسیر
`/uploads/...` سرو می‌شن (پیاده‌سازی `service.PhotoStorage`؛ برای پروداکشن
با یک object storage واقعی جایگزینش کن، دقیقاً مثل الگوی `OTPSender`).
پیام‌رسانی فعلاً polling-based هست، نه realtime/websocket.

## API پنل ادمین

احراز هویت ادمین از همون مسیر OTP هست؛ فقط باید `is_admin=true` روی
کاربر ست شده باشه (یا با `ADMIN_BOOTSTRAP_PHONE`، یا مستقیم توی دیتابیس).
همه‌ی مسیرهای زیر نیاز به هدر `Authorization: Bearer <access_token>` یک
کاربر ادمین دارن.

```
GET    /admin/users/pending                  لیست کاربران آنبوردشده و منتظر بررسی (قدیمی‌ترین اول)
GET    /admin/users/:id                      پروفایل کامل یک کاربر برای بررسی
POST   /admin/users/:id/approve              تایید کاربر
POST   /admin/users/:id/reject               رد کاربر    body: {reason}

GET    /admin/categories/:key                دریافت تنظیمات یک دسته
PATCH  /admin/categories/:key                ویرایش min_select/max_select/title

GET    /admin/categories/:key/options        لیست همه گزینه‌های یک دسته (فعال/غیرفعال)
POST   /admin/categories/:key/options        ساخت گزینه جدید      body: {title, sort_order}
PATCH  /admin/options/:id                    ویرایش گزینه          body: {title?, sort_order?, is_active?}
DELETE /admin/options/:id                    حذف گزینه

GET    /admin/profile-questions              لیست همه سوالات (فعال/غیرفعال)
POST   /admin/profile-questions              ساخت سوال جدید        body: {text, sort_order}
PATCH  /admin/profile-questions/:id          ویرایش سوال           body: {text?, sort_order?, is_active?}
DELETE /admin/profile-questions/:id          حذف سوال
```

## خلاصه‌ی کامل API

### احراز هویت (عمومی)
```
POST /api/v1/auth/request-otp     body: {phone}
POST /api/v1/auth/verify-otp      body: {phone, otp}   -> access/refresh token
POST /api/v1/auth/token/refresh   body: {refresh_token} -> access/refresh جدید
```

### پروفایل
```
GET /api/v1/profile/me   (نیاز به توکن) — پروفایل کامل + همه‌ی انتخاب‌ها/پاسخ‌ها
```

همه‌ی پاسخ‌ها با این ساختار برمی‌گردن:
```json
{ "success": true, "message": "...", "data": { ... } }
{ "success": false, "message": "...", "errors": { ... } }
```

## نکاتی که از پروژه‌ی جنگویی قبلی‌تون رعایت شده

- ارسال OTP **sync** انجام می‌شه (نه توی یک goroutine بی‌خیال از نتیجه)،
  چون قبلاً دیدیم نسخه‌ی async باعث می‌شد کاربر با اینکه ارسال واقعاً شکست
  خورده، پیام موفقیت بگیره.
- اگه ارسال پیامک واقعاً شکست بخوره، OTP ذخیره‌شده پاک می‌شه تا کاربر
  فوراً بتونه دوباره تلاش کنه (وگرنه تا پایان OTP_EXPIRY_SECONDS با خطای
  «کد قبلی هنوز معتبره» قفل می‌مونه).
- OTP هیچ‌وقت خام ذخیره نمی‌شه؛ با HMAC-SHA256 هش می‌شه.
- کد OTP فقط وقتی `APP_ENV != production` باشه توی لاگ چاپ می‌شه.