# قراردادهای API

تمام مسیرها زیر `/api/v1` هستند. همه تاریخ‌ها و زمان‌ها در دیتابیس با
`TIMESTAMPTZ` و در API به‌صورت timestamp رشته‌ای ISO-8601 در UTC، مانند
`2026-08-09T10:30:00.000Z` نگهداری و منتقل می‌شوند. شمسی یا میلادی بودن فقط
مربوط به نمایش و تقویم رابط کاربری است.
Swagger در محیط غیر production روی `/docs` و JSON آن روی `/docs/openapi.json`
است.

- `Authorization: Bearer <token>` برای مسیرهای محافظت‌شده.
- `Accept-Language: fa|en` زبان پاسخ را مشخص می‌کند. برای سازگاری،
  `X-Language` نیز پذیرفته می‌شود، اما هدر استاندارد `Accept-Language` انتخاب
  اصلی است. API زبان نهایی را در `Content-Language` بازمی‌گرداند.
- `Idempotency-Key` برای پرداخت، انتقال، سفارش و هر command قابل‌تکرار.
- `X-Request-ID` شناسهٔ همان HTTP request و `X-Correlation-ID` شناسهٔ جریان
  سراسری است؛ در نبودشان API مقدار UUID ایجاد و در پاسخ برمی‌گرداند.
- Pagination با `page` و `pageSize` (حداکثر 100)، sorting با `sort` و `order`
  انجام می‌شود. پاسخ لیست شامل `data` و `meta` است.
- خطا شامل `statusCode`, `code`, `message`, `requestId`, `timestamp` و در صورت
  امن بودن `details` است.

کدهای وضعیت و خطا مستقل از زبان و مناسب پردازش ماشینی هستند؛ `message`های
نمایشی براساس زبان request ترجمه می‌شوند. DTOها whitelist هستند و فیلد ناشناخته رد می‌شود. SQL خاص فقط با binding
پارامترها و داخل Repository نوشته می‌شود. پس از تغییر Controller/DTO:

```bash
pnpm sdk:generate
```

OpenAPI و هر دو SDK باید همراه تغییر contract commit شوند.

## ثبت‌نام و ورود اپلیکیشن

- ثبت‌نام کاربر اپلیکیشن علاوه بر مشخصات هویتی، `username` یکتا می‌گیرد.
- `POST /api/v1/auth/login` فیلد `identifier` را می‌پذیرد؛ مقدار آن نام کاربری،
  شمارهٔ تماس یا کدملی ده‌رقمی ایران است.
- `phone` فقط به‌عنوان alias قدیمی پنل تا زمان مهاجرت Client وب پذیرفته می‌شود و
  Clientهای جدید نباید از آن برای Login استفاده کنند.
- نوع پروفایل ثبت‌نام عمومی همیشه `PERSONAL` است و از payload کاربر پذیرفته
  نمی‌شود.

## قرارداد تصویر پروفایل

- `PUT /api/v1/profile/me/avatar`: فایل multipart با نام `profileImage`؛ فقط
  JPEG، PNG یا WebP و حداکثر ۵ MiB.
- `DELETE /api/v1/profile/me/avatar`: حذف تصویر جاری کاربر.
- `GET /api/v1/profile/me`: دریافت اطلاعات قابل نمایش و ویرایش پروفایل کاربر اپلیکیشن.
- `PATCH /api/v1/profile/me`: ویرایش `firstName`، `lastName` و `username`؛ شماره تماس و کدملی از این مسیر تغییر نمی‌کنند.
- `POST /api/v1/auth/password/change`: تغییر رمز کاربر واردشده با دریافت رمز فعلی؛ پس از موفقیت همه نشست‌ها باطل می‌شوند.
- `GET /api/v1/profile/users/{userId}/avatar`: مسیر پایدار نمایش تصویر برای
  پروفایل، چت، شبکهٔ اجتماعی و پنل.

API امضای واقعی فایل را با MIME اعلام‌شده تطبیق می‌دهد. مقدار `url` در قرارداد
`ProfileImage` نسبت به origin سرویس API است و query نسخه باعث invalidation کش
پس از هر تغییر می‌شود.