# راهنمای فارسی Swagger پروژه

این پروژه حالا یک مستندات Swagger/OpenAPI داخلی دارد که از APIهای فعلی کد تولید شده است.

## مسیرها

- رابط Swagger UI: `/swagger`
- خروجی خام OpenAPI JSON: `/api/openapi`

## کاربرد هر مسیر

- `/swagger` برای مشاهده، جستجو و تست Endpointها در مرورگر است.
- `/api/openapi` برای اتصال ابزارهای دیگر مثل Postman Import، Redoc، یا CI/CD مناسب است.

## نحوه استفاده

1. پروژه را اجرا کنید.
2. در مرورگر به `/swagger` بروید.
3. از روی Tagها Endpoint مورد نظر را باز کنید.
4. در صورت نیاز روی `Try it out` بزنید و ورودی را پر کنید.
5. برای Endpointهای نیازمند احراز هویت، بهتر است ابتدا در همان مرورگر داخل برنامه لاگین کرده باشید.

## احراز هویت

این پروژه از `NextAuth` با Session Cookie استفاده می‌کند.

- بیشتر APIهای کاربری با Session کار می‌کنند.
- APIهای ادمین علاوه بر Session، نقش `ADMIN` هم می‌خواهند.
- در Swagger نیازی به Bearer Token نیست، چون درخواست‌ها روی همان Origin اجرا می‌شوند و Cookie مرورگر قابل استفاده است.

## دسته‌بندی Endpointها

- `Auth`: ثبت‌نام، Session و مسیرهای پایه NextAuth
- `User`: پروفایل و تست Session
- `Team`: ساخت و مدیریت تیم فانتزی
- `Players`: دریافت و مدیریت بازیکنان
- `Countries`: دریافت و مدیریت کشورها
- `Matches`: بازی‌ها، آمار، رویدادها و محاسبه امتیاز
- `Rounds` و `Gameweeks`: مدیریت بازه‌های مسابقات
- `Quiz`: کوئیز روزانه، نتایج و قرعه‌کشی
- `Golden Cards`: کارت‌های طلایی
- `Payment`: ساخت و تایید پرداخت
- `Upload`: آپلود عکس بازیکن

## نکات مهم

- مسیر `/api/payment/verify` پاسخ JSON نمی‌دهد و کاربر را Redirect می‌کند.
- مسیر `/api/upload/player-image` از `multipart/form-data` استفاده می‌کند.
- برخی مسیرها مثل `POST /api/admin/matches/{id}/calc-points` از داده‌های ثبت‌شده قبلی استفاده می‌کنند و بدنه ورودی ندارند.
- مستندات بر اساس Routeهای فعلی پروژه نوشته شده؛ اگر API جدید اضافه شود باید `lib/openapi.ts` هم به‌روزرسانی شود.

## نگهداری مستندات

فایل اصلی مستندات:

- `lib/openapi.ts`

Routeهای خروجی:

- `app/api/openapi/route.ts`
- `app/swagger/route.ts`

اگر API جدیدی اضافه کردید:

1. مسیر جدید را در `paths` اضافه کنید.
2. در صورت نیاز Schema مشترک را در `components.schemas` تعریف کنید.
3. اگر Endpoint نیازمند Session است، از Security فعلی استفاده کنید.