Frontend/AUTH_API.md

# Authentication & Account API Documentation

## فهرست مطالب

- [مکانیزم احراز هویت](#مکانیزم-احراز-هویت)
- [فرمت کلی پاسخ‌ها](#فرمت-کلی-پاسخها)
- [مدل کاربر](#مدل-کاربر)
- [Auth Endpoints](#auth-endpoints)
  - [ثبت‌نام](#1-ثبت‌نام)
  - [ورود با رمز عبور](#2-ورود-با-رمز-عبور)
  - [درخواست OTP](#3-درخواست-otp)
  - [تأیید OTP](#4-تأیید-otp)
  - [رفرش توکن](#5-رفرش-توکن)
- [Account Endpoints](#account-endpoints)
  - [آپدیت پروفایل](#1-آپدیت-پروفایل)
- [احراز هویت در درخواست‌ها](#احراز-هویت-در-درخواستها)
- [کدهای خطا](#کدهای-خطا)

---

## مکانیزم احراز هویت

پروژه از **JWT (JSON Web Token)** با کتابخانه `djangorestframework-simplejwt` استفاده می‌کند.

- هر بار که کاربر ثبت‌نام یا لاگین موفق انجام می‌دهد، دو توکن دریافت می‌کند:
  - **`access`** — توکن کوتاه‌مدت برای احراز هویت درخواست‌ها
  - **`refresh`** — توکن بلندمدت برای گرفتن `access` جدید
- برای اندپوینت‌هایی که نیاز به احراز هویت دارند، باید توکن `access` را در هدر `Authorization` ارسال کنید:

```
Authorization: Bearer <access_token>
```

- Backend احراز هویت: `MultiFieldBackend` — کاربر می‌تواند با `username`، `email` یا `phone_number` لاگین کند.

---

## فرمت کلی پاسخ‌ها

همه پاسخ‌ها از یک ساختار یکسان پیروی می‌کنند:

```json
{
  "code": 200,
  "msg": "success",
  "data": { ... }
}
```

| فیلد    | نوع     | توضیح                                       |
|---------|---------|---------------------------------------------|
| `code`  | integer | کد وضعیت (مشابه HTTP status)                |
| `msg`   | string  | پیام وضعیت (`"success"` یا متن خطا)         |
| `data`  | object  | داده‌های برگشتی (در صورت وجود)              |
| `token` | object  | توکن‌های JWT (فقط در پاسخ‌های auth)         |

---

## مدل کاربر

شیء `AuthUser` که در پاسخ‌های احراز هویت و پروفایل برگردانده می‌شود:

```json
{
  "id": 1,
  "username": "john_doe",
  "email": "john@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "phone_number": "09121234567"
}
```

---

## Auth Endpoints

Base URL: `/api/auth/`

---

### 1. ثبت‌نام

**`POST /api/auth/register/`**

ساخت حساب کاربری جدید با نام کاربری، ایمیل، شماره موبایل و رمز عبور.

#### Request Body

```json
{
  "username": "john_doe",
  "email": "john@example.com",
  "phone_number": "09121234567",
  "password": "securepass123",
  "first_name": "John",
  "last_name": "Doe"
}
```

| فیلد           | نوع    | الزامی | توضیح                         |
|----------------|--------|--------|-------------------------------|
| `username`     | string | ✅      | حداکثر ۱۵۰ کاراکتر، یکتا     |
| `email`        | string | ✅      | فرمت ایمیل، یکتا              |
| `phone_number` | string | ✅      | حداکثر ۳۲ کاراکتر، یکتا      |
| `password`     | string | ✅      | حداقل ۸ کاراکتر              |
| `first_name`   | string | ❌      | حداکثر ۱۵۰ کاراکتر           |
| `last_name`    | string | ❌      | حداکثر ۱۵۰ کاراکتر           |

#### Response موفق — `201 Created`

```json
{
  "code": 201,
  "msg": "success",
  "data": {
    "id": 1,
    "username": "john_doe",
    "email": "john@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone_number": "09121234567"
  },
  "token": {
    "access": "<access_token>",
    "refresh": "<refresh_token>"
  }
}
```

#### Response خطا — `400 Bad Request`

```json
{
  "code": 400,
  "msg": "A user with this username already exists."
}
```

پیام‌های خطای احتمالی:
- `"A user with this username already exists."`
- `"A user with this email already exists."`
- `"A user with this phone number already exists."`
- `"A user with these credentials already exists."`

---

### 2. ورود با رمز عبور

**`POST /api/auth/login/`**

ورود با استفاده از `username`، `email` یا `phone_number` به همراه رمز عبور.

#### Request Body

```json
{
  "identifier": "john_doe",
  "password": "securepass123"
}
```

| فیلد         | نوع    | الزامی | توضیح                                               |
|--------------|--------|--------|-----------------------------------------------------|
| `identifier` | string | ✅      | می‌تواند `username`، `email` یا `phone_number` باشد |
| `password`   | string | ✅      | رمز عبور کاربر                                     |

#### Response موفق — `200 OK`

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "id": 1,
    "username": "john_doe",
    "email": "john@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone_number": "09121234567"
  },
  "token": {
    "access": "<access_token>",
    "refresh": "<refresh_token>"
  }
}
```

#### Response خطا — `401 Unauthorized`

```json
{
  "code": 401,
  "msg": "Invalid credentials."
}
```

---

### 3. درخواست OTP

**`POST /api/auth/request-otp/`**

> ⚠️ این endpoint در حال حاضر در `urls.py` کامنت شده است (غیرفعال).

ارسال کد یکبار مصرف (OTP) به شماره موبایل از طریق SMS.ir.

#### Request Body

```json
{
  "phone_number": "09121234567"
}
```

| فیلد           | نوع    | الزامی | توضیح               |
|----------------|--------|--------|---------------------|
| `phone_number` | string | ✅      | حداکثر ۳۲ کاراکتر  |

#### Response موفق — `200 OK`

```json
{
  "code": 200,
  "msg": "success",
  "token": "<otp_token>"
}
```

| فیلد          | توضیح                                                        |
|---------------|--------------------------------------------------------------|
| `token`       | توکن امضاشده که باید در مرحله verify-otp ارسال شود          |
| `sms_warning` | (اختیاری) در صورت شکست ارسال پیامک ظاهر می‌شود             |
| `debug_otp`   | (اختیاری) فقط در حالت `DEBUG=True` — کد OTP در پاسخ می‌آید |

> کد OTP مدت اعتبار **۳۰۰ ثانیه (۵ دقیقه)** دارد.

---

### 4. تأیید OTP

**`POST /api/auth/verify-otp/`**

> ⚠️ این endpoint در حال حاضر در `urls.py` کامنت شده است (غیرفعال).

تأیید کد OTP دریافت‌شده و ورود/ثبت‌نام خودکار کاربر.

#### Request Body

```json
{
  "token": "<otp_token>",
  "otp_code": "123456"
}
```

| فیلد       | نوع    | الزامی | توضیح                                     |
|------------|--------|--------|-------------------------------------------|
| `token`    | string | ✅      | توکن دریافت‌شده از مرحله request-otp      |
| `otp_code` | string | ✅      | کد ۶ رقمی ارسال‌شده به موبایل            |

#### Response موفق — `200 OK`

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "id": 1,
    "username": "09121234567",
    "email": "09121234567@otp.local",
    "first_name": "",
    "last_name": "",
    "phone_number": "09121234567"
  },
  "token": {
    "access": "<access_token>",
    "refresh": "<refresh_token>"
  }
}
```

> اگر کاربر با این شماره موبایل قبلاً ثبت‌نام نکرده باشد، حساب جدید به‌صورت خودکار ساخته می‌شود.

#### Response خطا — `400 Bad Request`

```json
{
  "code": 400,
  "msg": "Token is invalid or expired."
}
```

یا:

```json
{
  "code": 400,
  "msg": "OTP code is invalid or expired."
}
```

---

### 5. رفرش توکن

**`POST /api/auth/token/refresh/`**

دریافت `access` token جدید با استفاده از `refresh` token.

> این endpoint توسط `djangorestframework-simplejwt` به‌صورت پیش‌فرض فراهم می‌شود.

#### Request Body

```json
{
  "refresh": "<refresh_token>"
}
```

#### Response موفق — `200 OK`

```json
{
  "access": "<new_access_token>"
}
```

---

## Account Endpoints

Base URL: `/api/account/`

---

### 1. آپدیت پروفایل

**`PATCH /api/account/profile/`**

> 🔒 نیاز به احراز هویت دارد — هدر `Authorization: Bearer <access_token>` الزامی است.

ویرایش اطلاعات پروفایل کاربر لاگین‌شده.

#### Request Body

همه فیلدها اختیاری هستند (partial update):

```json
{
  "first_name": "علی",
  "last_name": "احمدی",
  "email": "new_email@example.com"
}
```

| فیلد         | نوع    | الزامی | توضیح               |
|--------------|--------|--------|---------------------|
| `first_name` | string | ❌      | حداکثر ۱۵۰ کاراکتر |
| `last_name`  | string | ❌      | حداکثر ۱۵۰ کاراکتر |
| `email`      | string | ❌      | فرمت ایمیل معتبر    |

#### Response موفق — `200 OK`

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "id": 1,
    "username": "john_doe",
    "email": "new_email@example.com",
    "first_name": "علی",
    "last_name": "احمدی",
    "phone_number": "09121234567"
  }
}
```

#### Response خطا — `401 Unauthorized`

در صورت نبود یا منقضی بودن توکن:

```json
{
  "detail": "Authentication credentials were not provided."
}
```

---

## احراز هویت در درخواست‌ها

برای اندپوینت‌هایی که نیاز به احراز هویت دارند (مانند `PATCH /api/account/profile/`)، توکن `access` را در هدر HTTP ارسال کنید:

```
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

### چرخه عمر توکن

```
[ثبت‌نام / لاگین]
       ↓
دریافت access + refresh
       ↓
ارسال درخواست‌ها با access
       ↓
منقضی شدن access (401)
       ↓
ارسال refresh به POST /api/auth/token/refresh/
       ↓
دریافت access جدید
```

---

## کدهای خطا

| HTTP Status | code | معنا                                          |
|-------------|------|-----------------------------------------------|
| 201         | 201  | ثبت‌نام موفق                                  |
| 200         | 200  | عملیات موفق                                   |
| 400         | 400  | داده‌های نامعتبر یا OTP/توکن اشتباه           |
| 401         | 401  | احراز هویت ناموفق (رمز اشتباه یا بدون توکن)  |

> پاسخ‌های خطای اعتبارسنجی serializer (مانند فیلد اجباری) با فرمت استاندارد DRF برگردانده می‌شوند:
> ```json
> {
>   "field_name": ["This field is required."]
> }
> ```