# راهنمای استقرار پروژه Ayron روی هاست

این سند مراحل آماده‌سازی و انتقال پروژه را به صورت بیلد نهایی روی هاست شرح می‌دهد.

---

## روش پیشنهادی: همهٔ بیلدها و وابستگی‌ها روی سیستم خودتان

می‌توانید **همه‌چیز** (نصب وابستگی‌های PHP، بیلد فرانت، و به‌طور اختیاری کش Laravel) را روی کامپیوتر خود انجام دهید و فقط پوشه/فایل‌های نهایی را به هاست منتقل کنید. روی هاست **نیازی به Composer یا Node نیست**.

### روی سیستم خودتان (یک‌بار قبل از آپلود)

```bash
# از روت پروژه
composer install --no-dev --optimize-autoloader
npm run build
composer run deploy
```

- **`composer install --no-dev`** → پوشهٔ `vendor` با وابستگی‌های production ساخته می‌شود.
- **`npm run build`** → فرانت در `public/assets` بیلد می‌شود.
- **`composer run deploy`** → کش config، route و view ساخته می‌شود (اختیاری؛ می‌توان روی هاست هم اجرا کرد).

### چه چیزهایی را به هاست آپلود کنید

| آپلود کنید | آپلود نکنید |
|------------|--------------|
| `app/`, `bootstrap/`, `config/`, `database/`, `public/`, `resources/`, `routes/`, `storage/` (ساختار پوشه‌ها) | `node_modules/` و `frontend/node_modules/` |
| `vendor/` | `.env` (روی هاست از `.env.example` کپی بگیرید) |
| `artisan`, `composer.json`, `composer.lock` | `frontend/` (اختیاری؛ فقط برای بیلد مجدد لازم است) |
| کل محتوای `public/` از جمله `public/assets/` | `.git/`, `tests/`, فایل‌های `.log` (در صورت تمایل) |

اگر پوشهٔ `frontend/` را آپلود نکنید، حجم انتقال کمتر می‌شود؛ برای اجرای سایت فقط `public/assets` و `vendor` لازم است.

### روی هاست (بعد از آپلود)

فقط این کارها لازم است (بدون نصب وابستگی یا بیلد):

1. **Document Root** را به پوشهٔ **`public`** پروژه تنظیم کنید.

2. فایل **`.env`** را روی سرور بسازید (از روی سرور یا از طریق پنل):

   ```bash
   cp .env.example .env
   php artisan key:generate
   ```

   سپس مقادیر را برای production و دیتابیس هاست پر کنید (`APP_ENV=production`, `APP_DEBUG=false`, `APP_URL`, اطلاعات DB).

3. مایگریشن و دسترسی‌ها:

   ```bash
   php artisan migrate --force
   # اگر deploy را لوکال نزده بودید:
   composer run deploy
   chmod -R 775 storage bootstrap/cache
   ```

   اگر بعد از آپلود، لینک **storage** (مثلاً آپلود تصاویر) کار نکرد، روی هاست یک‌بار `php artisan storage:link` بزنید؛ با انتقال فایل، لینک نمادین ممکن است درست منتقل نشده باشد.

بعد از این، سایت باید بدون نیاز به Composer یا Node روی هاست کار کند.

---

## پیش‌نیازهای سرور

- **PHP** >= 8.2 (با اکستنشن‌های معمول Laravel: mbstring, xml, pdo_mysql, curl, openssl, tokenizer, json, bcmath و غیره)
- **Composer**
- **MySQL یا MariaDB**
- برای **بیلد فرانت‌اند** روی سرور (اختیاری): **Node.js** 18+ و npm — در غیر این صورت بیلد را لوکال انجام دهید و خروجی را آپلود کنید.

---

## روش ۱: بیلد لوکال و آپلود (بدون Node روی هاست)

اگر روی هاست دسترسی به Node ندارید، فرانت را روی سیستم خود بیلد کنید و فایل‌های بیلدشده را همراه بقیه پروژه آپلود کنید.

### مرحله ۱ — بیلد فرانت‌اند (روی کامپیوتر خود)

```bash
# از روت پروژه
npm run build
```

این دستور وابستگی‌های `frontend` را نصب و فرانت React را در `public/assets` بیلد می‌کند.

### مرحله ۲ — فایل‌هایی که باید روی هاست آپلود شوند

همهٔ پروژه را آپلود کنید **به جز** این پوشه/فایل‌ها (در صورت تمایل می‌توانید آن‌ها را حذف یا آپلود نکنید تا سبک‌تر شود):

- `node_modules` (هم روت هم `frontend/node_modules`)
- `frontend/` به‌طور کامل **اختیاری** است؛ فقط اگر می‌خواهید بعداً روی سرور دوباره بیلد بگیرید لازم است. برای استقرار ساده فقط همین که `public/assets` پر از فایل بیلد باشد کافی است.
- `.env` را آپلود **نکنید**؛ روی سرور از `.env.example` کپی بگیرید و مقادیر را پر کنید.
- `.git`, `tests`, `storage/logs/*.log` و فایل‌های موقت را در صورت تمایل حذف/آپلود نکنید.

حتماً این‌ها را آپلود کنید:

- تمام پوشه‌های `app`, `bootstrap`, `config`, `database`, `public`, `resources`, `routes`, `storage` (ساختار پوشه‌ها؛ فایل‌های حساس را روی سرور بسازید)
- فایل‌های `artisan`, `composer.json`, `composer.lock`
- محتویات **`public/assets`** (شامل `.vite/manifest.json` و فایل‌های JS/CSS بیلدشده)

### مرحله ۳ — روی هاست

1. **Document Root** هاست را به پوشه **`public`** پروژه تنظیم کنید (مثلاً `public_html` را به `.../ayron/public` اشاره دهید یا محتویات `public` را داخل `public_html` بریزید و بقیهٔ پروژه بیرون از Document Root بماند).

2. فایل **`.env`** را روی سرور بسازید:

   ```bash
   cp .env.example .env
   php artisan key:generate
   ```

3. مقادیر **production** را در `.env` تنظیم کنید:

   ```env
   APP_ENV=production
   APP_DEBUG=false
   APP_URL=https://your-domain.com
   # دیتابیس و بقیهٔ متغیرها را با اطلاعات هاست پر کنید.
   ```

4. وابستگی‌های PHP و بهینه‌سازی Laravel:

   ```bash
   composer install --no-dev --optimize-autoloader
   php artisan migrate --force
   composer run deploy
   ```

   اسکریپت `deploy` در composer این کارها را انجام می‌دهد: `config:cache`, `route:cache`, `view:cache`, `storage:link`.

5. دسترسی نوشتن برای Laravel:

   ```bash
   chmod -R 775 storage bootstrap/cache
   # اگر کاربر وب سرور مشخص است (مثلاً www-data):
   chown -R www-data:www-data storage bootstrap/cache
   ```

6. در صورت استفاده از **صف (queue)**، یک کرون‌جاب یا پروسس دائمی برای صف اضافه کنید:

   ```bash
   php artisan queue:work --tries=3
   ```

بعد از این مراحل، با باز کردن دامنه باید SPA و API هر دو از همان دامنه سرو شوند.

---

## روش ۲: بیلد روی خود سرور (در صورت داشتن Node روی هاست)

اگر روی هاست به SSH و Node دسترسی دارید:

```bash
# نصب وابستگی‌ها و بیلد فرانت
composer install --no-dev --optimize-autoloader
cp .env.example .env
php artisan key:generate
# مقادیر .env را ویرایش کنید (APP_ENV=production و ...)

npm run build          # بیلد فرانت در public/assets
php artisan migrate --force
composer run deploy
chmod -R 775 storage bootstrap/cache
```

بقیهٔ تنظیمات (Document Root، queue، دسترسی‌ها) مثل روش ۱ است.

---

## چک‌لیست نهایی قبل از استقرار

- [ ] `APP_ENV=production` و `APP_DEBUG=false` در `.env` روی سرور
- [ ] `APP_URL` برابر آدرس نهایی سایت (مثلاً `https://your-domain.com`)
- [ ] دیتابیس ایجاد شده و اطلاعات در `.env` درست است
- [ ] بیلد فرانت با `npm run build` انجام شده و `public/assets` پر از فایل (از جمله `.vite/manifest.json`) است
- [ ] Document Root به پوشه `public` اشاره می‌کند
- [ ] پوشه‌های `storage` و `bootstrap/cache` قابل نوشتن هستند
- [ ] در صورت نیاز، لینک storage با `php artisan storage:link` ایجاد شده (معمولاً داخل `deploy`)
- [ ] در صورت استفاده از queue، worker صف راه‌اندازی شده (کرون یا سرویس)

---

## دستورات مفید

| دستور | توضیح |
|--------|--------|
| `npm run build` | بیلد فرانت React و خروجی در `public/assets` |
| `composer run deploy` | کش config، route، view و لینک storage |
| `php artisan config:clear` | پاک کردن کش config (در صورت تغییر .env) |
| `php artisan storage:link` | لینک نمادین `public/storage` به `storage/app/public` |

با رعایت این مراحل، پروژه به صورت بیلد نهایی و قابل استفاده روی هاست قابل انتقال است.