# مستند منطق API ریوو (Rievo API)

این فایل منطق کسب‌وکار و قوانین درخواست‌های API پروژه را به زبان فارسی توضیح می‌دهد.

- **پایه آدرس:** `/api/...`
- **احراز هویت:** Laravel Sanctum — هدر `Authorization: Bearer {token}`
- **قالب پاسخ استاندارد (`ApiResponse`):**

```json
{
  "success": true,
  "message": "پیام فارسی",
  "data": {},
  "errors": null,
  "meta": {},
  "next": null
}
```

در خطای اعتبارسنجی (معمولاً `422`):

```json
{
  "success": false,
  "message": "اطلاعات وارد شده نامعتبر است.",
  "errors": {
    "field": ["پیام خطا"]
  }
}
```

---

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

1. [نقش‌ها و دسترسی‌ها](#۱-نقشها-و-دسترسیها)
2. [احراز هویت و پروفایل](#۲-احراز-هویت-و-پروفایل)
3. [داشبورد کاربر](#۳-داشبورد-کاربر)
4. [آپلود فایل](#۴-آپلود-فایل)
5. [صفحه اصلی و محتوای عمومی](#۵-صفحه-اصلی-و-محتوای-عمومی)
6. [محصولات، تولیدکننده و خدمات‌دهنده](#۶-محصولات-تولیدکننده-و-خدماتدهنده)
7. [سفارش، پرداخت و کیف پول](#۷-سفارش-پرداخت-و-کیف-پول)
8. [فاکتورها](#۸-فاکتورها)
9. [پروژه‌ها](#۹-پروژهها)
10. [قرارداد پروژه (امضای OTP)](#۱۰-قرارداد-پروژه-امضای-otp)
11. [تکمیل پروژه](#۱۱-تکمیل-پروژه)
12. [پیشنهادات و درخواست پروژه](#۱۲-پیشنهادات-و-درخواست-پروژه)
13. [گزارش‌ها (رشد، سلامت، جیره)](#۱۳-گزارشها-رشد-سلامت-جیره)
14. [بلاگ و مقالات](#۱۴-بلاگ-و-مقالات)
15. [پشتیبانی، بحث‌ها و اعلان‌ها](#۱۵-پشتیبانی-بحثها-و-اعلانها)
16. [ماشین وضعیت‌های مهم](#۱۶-ماشین-وضعیتهای-مهم)

---

## ۱. نقش‌ها و دسترسی‌ها

| نقش | توضیح |
|-----|--------|
| `admin` | مدیر سیستم — دسترسی کامل به پروژه‌ها، تأیید فاکتور/گزارش، تکمیل پروژه |
| `employer` | کارفرما — مالک پروژه، سفارش، کیف پول |
| `producer` | تولیدکننده — پروفایل فروشنده، پروژه‌های مرتبط |
| `expert` | خدمات‌دهنده — پروفایل خدمات |
| `user` | کاربر پایه |
| `writer` | نویسنده محتوا (عمدتاً پنل ادمین) |

**نکته:** مدیریت کاربران در پنل Filament است؛ فرانت‌اند از APIهای `/api/user` و `/api/users-dashboard` استفاده می‌کند.

---

## ۲. احراز هویت و پروفایل

### ارسال OTP
- `POST /api/otp`
- بدون توکن
- ورودی: `cellphone` (فرمت `09xxxxxxxxx`)
- محدودیت نرخ ارسال بر اساس موبایل یا IP
- فقط `expire_at` برمی‌گردد (کد در پاسخ نیست)

### ورود با رمز یا OTP
- `POST /api/authenticate`
- بدون توکن
- رمز **یا** OTP الزامی است (`required_without`)
- اگر کاربر وجود نداشته باشد → ساخت خودکار با نقش کارفرما
- کاربر مسدود → `403`
- OTP نامعتبر → `409`
- موفقیت: توکن Sanctum + آبجکت کاربر

### ورود با ایمیل/موبایل و رمز
- `POST /api/login/{refreshToken?}`
- بدون توکن
- به‌روزرسانی `last_online_at`

### ثبت‌نام
- `POST /api/register` — نیاز به OTP معتبر؛ موبایل تکراری → `409`
- `POST /api/register/employer` — ثبت‌نام کارفرما با رمز؛ نقش‌های `employer` + `user`

### فراموشی رمز
- `POST /api/forget-password`
- تأیید OTP سپس تنظیم `newPassword`

### خروج
- `POST /api/logout` — نیاز به توکن؛ حذف همه توکن‌های کاربر

### پروفایل فعلی
- `GET /api/user` — نیاز به توکن
- شامل نقش‌ها، `producer` / `expert`، استان و شهر

### ویرایش پروفایل
- `PUT|PATCH /api/user` (ترجیحی — بدون spoof شناسه)
- `PUT|PATCH /api/users/{id}` — فقط خود کاربر یا ادمین

| فیلد UI | کلید API | قوانین |
|---------|----------|--------|
| تصویر کاربری | `avatar` | مسیر یا URL پس از آپلود |
| نام / نام خانوادگی | `first_name`, `last_name` | اجباری، حداکثر ۱۰۰ |
| نام کاربری | `name` | اجباری، یکتا (ستون `username`) |
| موبایل | `cellphone` | اجباری، یکتا، `09xxxxxxxxx` |
| کد ملی | `national_code` | اختیاری، ۱۰ رقم، یکتا |
| ایمیل | `email` | اختیاری، یکتا |
| تلفن ثابت | `phone` | اختیاری |
| تاریخ تولد | `dob` | `Y-m-d`، قبل از امروز |
| آدرس | `address` | اختیاری |
| رمز فعلی / جدید | `current_password`, `password`, `password_confirmation` | فقط هنگام تغییر رمز؛ حداقل ۸ کاراکتر |

فیلدهای خالی رمز به‌معنای «بدون تغییر رمز» هستند.

---

## ۳. داشبورد کاربر

- `GET /api/users-dashboard` — نیاز به توکن

### خروجی `data`

| کلید | توضیح |
|------|--------|
| `user` | پروفایل فشرده + `producer` / `expert` (id، status، admin_reason) |
| `stats` | آمار پروژه‌ها و کیف پول |
| `alerts` | هشدارها (سفارش در انتظار، نیاز به ویرایش پروفایل) |
| `notification_settings` | تنظیمات اعلان (ایمیل، تأیید/لغو سفارش) |
| `profile_cta` | فراخوان تکمیل پروفایل تولیدکننده/خدمات‌دهنده |

### آمار (`stats`)

| فیلد | منطق |
|------|------|
| `active_projects_count` | وضعیت‌های `active`, `approved`, `unsigned`, `waiting` |
| `completed_projects_count` | وضعیت `completed` |
| `total_investment` | جمع `budget` پروژه‌های کاربر |
| `wallet_balance` | موجودی کیف پول |
| `unread_notifications` | اعلان‌های خوانده‌نشده |

پروژه‌های کاربر: `user_id` یا `created_by` یا `producer_id` مرتبط.

---

## ۴. آپلود فایل

- `POST /api/uploads` — نیاز به توکن
- `multipart/form-data` با فیلد `file` یا `files[]` (حداکثر ۱۰ فایل)
- حداکثر حجم: ۱۲ مگابایت
- فرمت‌ها: jpg, jpeg, png, gif, webp, pdf, doc, docx, xls, xlsx, zip
- مسیر ذخیره: `{userId}/{Y}/{m}/`
- پاسخ: URL در `data` (و مسیر نسبی در `meta.paths`)

**جریان آواتار:** آپلود → گرفتن URL → ارسال در `PUT /api/user` با کلید `avatar`.

---

## ۵. صفحه اصلی و محتوای عمومی

| متد | مسیر | توضیح |
|-----|------|--------|
| GET | `/api/home` | داده تجمیعی لندینگ |
| GET | `/api/settings` | تنظیمات عمومی |
| GET | `/api/menus` | منوها |
| GET | `/api/faqs` | سوالات متداول تأییدشده |
| GET | `/api/services` | خدمات |
| POST | `/api/newsletters` | عضویت خبرنامه |
| POST | `/api/contacts` | فرم تماس |

`/api/home` شامل: تنظیمات ایندکس، آمار، ویژگی‌ها، دسته‌ها، محصولات ویژه، دامداران برتر، پیش‌نمایش بلاگ، FAQ.

---

## ۶. محصولات، تولیدکننده و خدمات‌دهنده

### محصولات
| متد | مسیر | احراز هویت |
|-----|------|------------|
| GET | `/api/products`, `/api/products/{id}` | خیر |
| POST/PUT/DELETE | همان‌ها | بله |

لیست عمومی فقط `status=active` و `is_active=true`.

### تولیدکننده (`producers`)
- ایجاد پروفایل → وضعیت `pending` + نقش `producer`
- لیست عمومی معمولاً فقط `approved`
- وضعیت‌ها: `pending`, `approved`, `rejected`, `needs_edit`, `blocked`

### خدمات‌دهنده (`experts`)
- مشابه تولیدکننده با وضعیت‌های مشابه
- نقش `expert`

### نژاد و دسته
- خواندن عمومی؛ نوشتن با توکن

---

## ۷. سفارش، پرداخت و کیف پول

### سفارش
- `GET/POST /api/orders` و CRUD تک‌سفارش — نیاز به توکن
- سبد: `items[]`, آدرس، `payable` (باید با جمع سرور برابر باشد)، `payment_method`: `wallet` یا درگاه
- هر قلم سفارش جدا با `group_id` مشترک؛ وضعیت اولیه `pending`
- کیف پول: کسر فوری؛ درگاه: آدرس پرداخت در `next`

### پرداخت
- ایجاد/لیست با توکن؛ تأیید درگاه عمومی:
  - `GET /api/payments/{payment}/verify`
  - `ANY /api/pay/verify/{payment}` → ریدایرکت فرانت

### کیف پول (`/api/wallet`)
| مسیر | منطق |
|------|------|
| `GET /` | خلاصه موجودی |
| `GET transactions` | گردش حساب |
| `POST deposit` | شارژ از درگاه (وضعیت در انتظار) |
| `GET/POST withdrawals` | درخواست برداشت — نیاز کارت فعال یا شبا؛ موجودی قفل می‌شود |
| `bank-cards` | CRUD کارت بانکی + تنظیم پیش‌فرض |

---

## ۸. فاکتورها

همه مسیرهای فاکتور نیاز به توکن دارند.

### چرخه وضعیت
`draft` → `pending` → (`approved` / `unpaid`) → `paid`  
همچنین: `rejected`, `needs_edit`

| اکشن | مسیر | نقش |
|------|------|-----|
| ثبت | `POST /api/invoices` | کاربر مجاز |
| ارسال برای بررسی | `POST .../submit` | صاحب فاکتور |
| تأیید | `POST .../approve` | ادمین |
| رد | `POST .../reject` | ادمین (+ دلیل) |
| نیاز به ویرایش | `POST .../needs-edit` | ادمین (+ دلیل) |
| پرداخت | `POST .../pay` | صاحب — فقط `unpaid`/`approved` |

ویرایش فقط در `draft` / `needs_edit` / `rejected` (غیر ادمین).

---

## ۹. پروژه‌ها

### دسترسی به پروژه
کاربر مجاز است اگر:
- ادمین باشد، یا
- `user_id` / `created_by` او باشد (کارفرما)، یا
- کاربرِ تولیدکننده مرتبط باشد، یا
- روی پروژه سفارش داشته باشد.

### CRUD و پنل‌ها
| متد | مسیر | توضیح |
|-----|------|--------|
| GET | `/api/projects` | لیست (توکن) |
| POST | `/api/projects` | ایجاد |
| GET | `/api/projects/{id}` | جزئیات |
| GET | `/api/projects/by-code/{code}` | عمومی با کد |
| GET | `/api/projects/overview` | نمای کلی |
| GET | `/api/projects/history` | تاریخچه |
| GET | `/api/projects/{id}/hub` | هاب پروژه |
| GET | `.../finance`, `growth`, `health`, `ration`, `gallery`, `documents`, `transactions` | زیرصفحات |
| POST | `.../comments`, `.../ratings` | نظر و امتیاز |
| PATCH | `.../sale-registration` | ثبت فروش |

### ایجاد پروژه
- پیش‌نویس (`is_draft`) → وضعیت `pending`
- غیر پیش‌نویس → `unsigned` (آماده امضای قرارداد)
- پیش‌فرض: `sale_registration_enabled = true`

### نمودار سود پروژه

| متد | مسیر | توضیح |
|-----|------|--------|
| GET | `/api/projects` / `history` / `{id}` | هر پروژه شامل `chart_points` |
| GET | `/api/projects/{id}/profit-chart` | فقط سری سود همان پروژه |
| GET | `/api/projects/overview` | شامل `profit_series` و `loss_series` |
| GET | `/api/projects/overview/profit-chart` | فقط سری پورتفوی |

**منطق محاسبه**
1. اگر فاکتورهای موفق (`paid` / `approved`) وجود داشته باشد → سود تجمعی ماهانه از (درآمد − هزینه)
2. در غیر این صورت → رشد خطی `estimated_profit` از `start_date` تا `end_date` یا امروز (حداکثر ۲۴ ماه)
3. `label` = شماره ماه جلالی صفرپر (`01` … `12`)، `date` = اول ماه میلادی ISO، `value` = تومان (عدد)

نمونه `chart_points` روی پروژه:

```json
{
  "chart_points": [
    { "label": "05", "value": 1000000, "date": "2025-08-01" },
    { "label": "06", "value": 2000000, "date": "2025-09-01" },
    { "label": "07", "value": 3000000, "date": "2025-10-01" }
  ]
}
```

نمونه overview / overview profit-chart:

```json
{
  "total_profit": 45000000,
  "profit_percent": 12.5,
  "profit_series": [
    { "label": "05", "value": 2000000, "date": "2025-08-01" },
    { "label": "06", "value": 4500000, "date": "2025-09-01" }
  ],
  "loss_series": [
    { "label": "05", "value": 500000, "date": "2025-08-01" },
    { "label": "06", "value": 900000, "date": "2025-09-01" }
  ],
  "tooltip": { "value": 4500000, "date": "2025-09-01" }
}
```

- `profit_series`: تجمعی درآمد (فاکتور) + برآورد پروژه‌های بدون فاکتور
- `loss_series`: تجمعی هزینه از فاکتورهای expense (در صورت نبود فاکتور → صفر)
- `tooltip`: آخرین نقطه `profit_series`

---

## ۱۰. قرارداد پروژه (امضای OTP)

همه با توکن و دسترسی پروژه:

| متد | مسیر | توضیح |
|-----|------|--------|
| GET | `/api/projects/{project}/contract` | متن قرارداد + وضعیت امضاها |
| POST | `.../contract/send-code` | ارسال کد OTP به موبایل |
| POST | `.../contract/confirm` | تأیید با `{ "code": "..." }` |

### قوانین امضا
1. طرفین: **کارفرما** (`project.user_id`) و **تولیدکننده** (کاربرِ `producer`)
2. نیاز به `contract_text` و شماره موبایل
3. اعتبار کد: **۱۰ دقیقه**
4. نقش ادمین:
   - اگر طرفی امضا نکرده باشد، ادمین می‌تواند به‌جای او امضا کند (اولویت با طرف ناقص)
   - تأیید ادمین می‌تواند پروژه را از `unsigned` / `pending` / `waiting` به **`active`** ببرد
5. فقط تولیدکننده امضا کرده → وضعیت `waiting` (منتظر کارفرما)
6. هر دو طرف امضا کرده‌اند → وضعیت `active` + اعلان به تولیدکننده

### جریان پیشنهادی فرانت
1. نمایش قرارداد (`GET .../contract`)
2. درخواست کد (`POST .../send-code`)
3. وارد کردن کد و تأیید (`POST .../confirm`)
4. خواندن `project_status` / آبجکت `project` از پاسخ

---

## ۱۱. تکمیل پروژه

| متد | مسیر | نقش |
|-----|------|-----|
| GET | `/api/projects/completable` | ادمین |
| GET | `.../completion` | طرفین مجاز |
| POST | `.../completion/start` | ادمین → پروژه `waiting` |
| POST | `.../completion/confirm` | کارفرما/تولیدکننده (ادمین می‌تواند `as=producer\|employer`) |
| POST | `.../completion/finalize` | ادمین → `completed` |

اگر وضعیت `arbitration` باشد، تکمیل مسدود است.  
لیست قابل‌تکمیل: تاریخ پایان گذشته یا فاکتور پرداخت‌شده.

---

## ۱۲. پیشنهادات و درخواست پروژه

### پیشنهادات (`/api/offers`)
- نیاز به توکن
- ایجاد با وضعیت `pending`
- قابل اتصال به `project_id` یا `product_id`
- قابل مشاهده برای صاحب، گیرنده (`offer_to`) یا ادمین

### درخواست پروژه تولیدکننده (`/api/project-requests`)
- لیست/ایجاد/نمایش
- `PATCH .../status` تغییر وضعیت
- `POST .../message` پیام روی درخواست
- ایجاد فقط توسط تولیدکننده (یا ادمین)

---

## ۱۳. گزارش‌ها (رشد، سلامت، جیره)

### چرخه مشترک گردش‌کار
`draft` → `submit` → `pending` → ادمین: `approved` / `rejected` / `needs_edit`  
(برای رد و نیاز به ویرایش، دلیل الزامی است)

| نوع | پیشوند API |
|-----|------------|
| رشد | `/api/growth-reports` |
| سلامت | `/api/health-reports` |
| جیره | `/api/ration-reports` |
| تحت درمان | `/api/health-treatments` |

اکشن‌های مشترک: `submit`, `approve`, `reject`, `needs-edit`  
تاریخچه روی پروژه: `.../growth-history`, `health-history`, `ration-history`, `ration-feeding`

---

## ۱۴. بلاگ و مقالات

بدون توکن (خواندنی):

| مسیر | توضیح |
|------|--------|
| `GET /api/posts` | لیست منتشرشده (`status = 13`) |
| `GET /api/posts/{slug}` | جزئیات + افزایش بازدید |
| `GET /api/landing/posts` | لندینگ |
| `GET /api/popular-posts` | محبوب (مرتب‌سازی بر اساس `views`) |
| `GET /api/posts-published` | منتشرشده‌ها |
| `GET /api/related/{slug}/posts` | مرتبط |
| `GET /api/categories/{slug}/posts` | بر اساس دسته |
| `GET /api/posts-increase-view/{slug}` | افزایش بازدید |

فیلترها: `postTitle`, `categoryUrl`, `tags`, `sortType` = `latest` | `oldest` | `popular`  
مدیریت محتوا در Filament است.

---

## ۱۵. پشتیبانی، بحث‌ها و اعلان‌ها

### تیکت پشتیبانی (`/api/support-tickets`)
- ایجاد → `open`
- پاسخ ادمین → تیکت `read`؛ پاسخ کاربر → `unread`
- پاسخ روی تیکت بسته → بازگشایی
- کاربر عادی فقط تیکت‌های خودش را می‌بیند

### بحث‌های موضوعی (`/api/discussions`)
- وضعیت: `active` → `ended` / `deleted`
- شرکت‌کنندگان: همه پروژه یا لیست کاربران
- پیام، بلاک/آنبلاک شرکت‌کننده

### اعلان‌ها (`/api/notifications`)
- لیست / به‌روزرسانی / حذف / علامت خوانده‌شده
- پارامتر `only_unread` برای فیلتر

---

## ۱۶. ماشین وضعیت‌های مهم

### پروژه
```
pending (پیش‌نویس/انتظار)
  → unsigned (آماده امضا)
  → waiting (منتظر امضای کارفرما پس از تولیدکننده)
  → active (هر دو امضا / تأیید ادمین)
  → completed (تکمیل نهایی)
```
سایر: `approved`, `rejected`, `edit`, `arbitration`, `cancelled`, `expired`

### فاکتور
```
draft → pending → approved/unpaid → paid
                 ↘ rejected / needs_edit
```

### گزارش (رشد/سلامت/جیره)
```
draft → pending → approved
                ↘ rejected / needs_edit
```

### تولیدکننده / خدمات‌دهنده
```
pending → approved
        ↘ rejected / needs_edit / blocked
```

### درخواست مشاوره (`/api/service-requests`)
```
pending (بررسی ادمین)
  → pending_expert (تایید ادمین، منتظر خدمات‌دهنده)
  → accepted | declined
  ↘ rejected | closed
```

### تیکت
```
open ↔ unread / read → closed
```

---

## خدمات‌دهندگان و درخواست مشاوره

| متد | مسیر | توضیح |
|-----|------|--------|
| GET | `/api/experts` | فیلتر: `q`, `province_id`, `county_id`, `main_category`, `status` |
| GET | `/api/experts/{id}` | کارنامه + `stats` + `featured_projects` |
| POST | `/api/service-requests` | ثبت درخواست → وضعیت `pending` |
| GET | `/api/service-requests?scope=producer\|expert` | لیست درخواست‌ها |
| GET | `/api/service-requests/{id}` | جزئیات + نام/تلفن/آدرس تولیدکننده |
| POST | `/api/service-requests/{id}/accept` | پذیرش مراجعه توسط خدمات‌دهنده |
| POST | `/api/service-requests/{id}/decline` | رد مراجعه (`reason` اختیاری) |

بدنه ثبت:

```json
{
  "expert_id": 3,
  "consultation_type": "feed",
  "mode": "in_person",
  "priority": "high",
  "message": "نیاز به مشاوره خوراک"
}
```

`consultation_type`: `feed` | `herd_management` | `other`  
`mode`: `in_person` | `online`  
`priority`: `low` | `medium` | `high` | `emergency`

---

## گالری، اسناد، امنیت و قیمت‌ها

| متد | مسیر | توضیح |
|-----|------|--------|
| POST | `/api/projects/{id}/gallery` | ثبت تصویر/ویدیو (`title,url,type,category,gps,location_name,description,is_draft`) |
| PUT | `/api/projects/{id}/gallery/{mediaId}` | ویرایش آیتم گالری |
| POST | `/api/projects/{id}/documents` | ثبت سند (+ `document_category,document_number,company_name,company_phone,valid_from,valid_until,notes`) |
| PUT | `/api/projects/{id}/documents/{mediaId}` | ویرایش سند |
| POST | `/api/projects/{id}/media/{mediaId}/flag` | گزارش تخلف `{ reason }` |
| GET | `/api/projects/{id}/producer-stats` | آمار گالری/اسناد تولیدکننده |
| GET | `/api/devices` | لیست دستگاه‌ها |
| DELETE | `/api/devices/{id}` | حذف دستگاه |
| POST | `/api/devices/{id}/block\|unblock` | مسدود/رفع مسدود |
| GET/PUT | `/api/security/two-factor` | تنظیمات ۲FA (`channel`, پرچم‌های login/withdrawal/project_activation) |
| GET | `/api/prices/chart` | نمودار قیمت بازار |
| GET | `/api/invoices/{id}/download?format=pdf\|xlsx` | لینک دانلود `{ url }` |
| POST | `/api/newsletters` | `{ email? }` یا `{ cellphone? }` — حداقل یکی |

آپلود فایل همچنان از `POST /api/uploads`؛ سپس URL در body گالری/سند.

---

## نکات کلی برای فرانت‌اند

1. همه درخواست‌های محافظت‌شده باید `Authorization: Bearer {token}` داشته باشند.
2. برای صفحه‌بندی معمولاً `per_page` (حداکثر حدود ۵۰) و گاهی `noPaginate=1` پشتیبانی می‌شود.
3. بعد از ویرایش پروفایل یا امضای قرارداد، هویت/پروژه را از پاسخ همان API یا `GET /api/user` / `GET /api/users-dashboard` تازه کنید.
4. مسیرهای تأیید درگاه ممکن است به فرانت ریدایرکت شوند (`next` یا URL کالبک).
5. مستند تعاملی Scramble (در صورت فعال بودن) مکمل این فایل است؛ این README تمرکز روی **منطق کسب‌وکار** دارد.

---

*آخرین به‌روزرسانی: هم‌راستا با مسیرهای `routes/api.php` و کنترلرهای اصلی پروژه ریوو.*