# راهنمای نصب قدم‌به‌قدم — RFQ-Core

این راهنما به زبان ساده نوشته شده است. اگر با ترمینال راحت نیستید، از کسی که با Laravel کار کرده کمک بگیرید؛ مراحل را به ترتیب انجام دهید و هیچ مرحله‌ای را جا نیندازید.

---

## پیش‌فرض‌ها

- سیستم‌عامل: **Ubuntu 22.04** یا محیط مشابه (Laragon روی ویندوز هم برای تست محلی مناسب است)
- پکیج کد: فایل `RFQ-Core-12.1.zip` (یا نسخه جدیدتر)

---

## قدم ۱: نصب PHP، Composer، MySQL، Node

### روی Ubuntu (خلاصه)

```bash
sudo apt update
sudo apt install -y php8.2 php8.2-cli php8.2-mysql php8.2-xml php8.2-mbstring \
  php8.2-curl php8.2-zip php8.2-gd php8.2-bcmath unzip curl mysql-server

# Composer
curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer

# Node 20 (نمونه با nodesource یا nvm)
# بعد از نصب:
node -v
npm -v
php -v
composer -V
```

مطمئن شوید نسخه PHP حداقل **۸.۲** است.

---

## قدم ۲: ساخت دیتابیس

وارد MySQL شوید:

```bash
sudo mysql
```

سپس:

```sql
CREATE DATABASE rfq_core CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'rfq_user'@'localhost' IDENTIFIED BY 'یک_رمز_قوی';
GRANT ALL PRIVILEGES ON rfq_core.* TO 'rfq_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;
```

رمز را یادداشت کنید.

---

## قدم ۳: ساخت پروژه Laravel 11

```bash
cd /var/www   # یا پوشه دلخواه شما
composer create-project laravel/laravel rfq-core
cd rfq-core
```

---

## قدم ۴: کپی فایل‌های RFQ-Core

1. فایل ZIP پکیج را باز کنید.
2. محتویات پوشه `purchase-request-system` را **روی** پروژه Laravel کپی کنید.
3. اگر از شما پرسید فایل جایگزین شود، برای فایل‌های متعلق به RFQ (مثل `app/`, `routes/web.php`, `database/migrations` مربوط به سیستم، `resources/views`) **Yes** بزنید.
4. فایل‌های پیش‌فرض Laravel که Breeze بعداً می‌سازد ممکن است با هم هم‌پوشانی داشته باشند؛ مهم‌ترین تداخل معمولاً **migration جدول users** است (قدم ۷).

---

## قدم ۵: نصب Spatie Permission

```bash
composer require spatie/laravel-permission
php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider"
```

در مدل `User` باید trait زیر وجود داشته باشد (معمولاً در پکیج RFQ آمده):

```php
use Spatie\Permission\Traits\HasRoles;
```

و داخل کلاس:

```php
use HasRoles;
```

---

## قدم ۶: نصب Laravel Breeze (صفحه ورود)

```bash
composer require laravel/breeze --dev
php artisan breeze:install blade
npm install
npm run build
```

اگر Breeze فایل `routes/auth.php` ساخت، همان را نگه دارید (پکیج RFQ یک stub ساده دارد که با نصب Breeze جایگزین می‌شود).

---

## قدم ۷: تنظیم `.env`

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

در `.env` حداقل این‌ها را تنظیم کنید:

```env
APP_NAME="RFQ-Core"
APP_URL=http://127.0.0.1:8000

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=rfq_core
DB_USERNAME=rfq_user
DB_PASSWORD=یک_رمز_قوی
```

### تداخل migration جدول users

Breeze و پکیج RFQ ممکن است هر دو جدول `users` بسازند.

کار عملی:

1. پوشه `database/migrations` را باز کنید.
2. اگر **دو** فایل برای `create_users_table` دیدید، یکی را نگه دارید که ستون‌های لازم را دارد (`name`, `email`, `password`, و در صورت نیاز `avatar`, `locale`, `two_factor_secret`).
3. فایل تکراری را حذف یا غیرفعال کنید (مثلاً پسوند `.bak`).

مهاجرت‌های اضافی RFQ (`core_tables`, `notifications`, `two_factor`, `in_app_extras`) را نگه دارید.

---

## قدم ۸: ثبت Middlewareها (locale و module)

در Laravel 11 فایل تقریباً این است: `bootstrap/app.php`

نمونه ثبت alias:

```php
->withMiddleware(function (Middleware $middleware) {
    $middleware->alias([
        'role' => \Spatie\Permission\Middleware\RoleMiddleware::class,
        'permission' => \Spatie\Permission\Middleware\PermissionMiddleware::class,
        'role_or_permission' => \Spatie\Permission\Middleware\RoleOrPermissionMiddleware::class,
        'module' => \App\Http\Middleware\EnsureModuleEnabled::class,
        'locale' => \App\Http\Middleware\SetLocale::class,
    ]);
})
```

اگر نسخه Laravel شما ساختار متفاوتی دارد، همان الگوی «alias middleware» را در مستندات Laravel 11 دنبال کنید.

`AppServiceProvider` پکیج هم تلاش می‌کند alias ثبت کند؛ ثبت در `bootstrap/app.php` مطمئن‌تر است.

---

## قدم ۹: اجرا کردن Migration و Seeder

```bash
php artisan migrate
php artisan db:seed
php artisan storage:link
```

اگر خطا دیدید:

- متن خطا را کامل بخوانید (معمولاً جدول تکراری یا foreign key است).
- با `php artisan migrate:status` وضعیت را ببینید.

پس از seed موفق، کاربر پیش‌فرض:

| فیلد | مقدار |
|------|--------|
| ایمیل | `admin@example.com` |
| رمز | `password` |

**بلافاصله بعد از ورود در محیط واقعی، رمز را عوض کنید.**

---

## قدم ۱۰: اجرا برای تست

```bash
php artisan serve
```

مرورگر:

```
http://127.0.0.1:8000
```

وارد شوید و چک‌لیست smoke test را انجام دهید (فایل نیازمندی‌ها، بخش ۵-E).

---

## قدم ۱۱: اجرا روی سرور واقعی (خلاصه)

1. دامنه را به سرور اشاره دهید.
2. Nginx/Apache را روی `public/` پروژه تنظیم کنید (document root = پوشه `public`).
3. `APP_DEBUG=false` و `APP_ENV=production` در `.env`.
4. `php artisan config:cache` و `php artisan route:cache`.
5. مجوز پوشه‌ها:

```bash
sudo chown -R www-data:www-data storage bootstrap/cache
sudo chmod -R 775 storage bootstrap/cache
```

6. HTTPS (Let's Encrypt) فعال کنید.

---

## رفع اشکال رایج

| مشکل | کار پیشنهادی |
|------|----------------|
| صفحه سفید / 500 | `storage/logs/laravel.log` را بخوانید |
| Class middleware not found | alias در `bootstrap/app.php` |
| Table users already exists | migration تکراری را حذف کنید |
| 403 روی تنظیمات | کاربر نقش `admin` دارد؟ دوباره seed |
| عکس/پیوست باز نمی‌شود | `php artisan storage:link` |
| استایل خراب | `npm run build` دوباره |
| `can:dashboard.view` خطا | permissionها seed شده‌اند؟ Spatie cache: `php artisan permission:cache-reset` |

---

## پایان نصب

اگر لاگین شدید، پرونده ساختید و کانبان را دیدید، نصب هسته موفق بوده است.  
برای آموزش کار روزمره با سیستم، فایل **یوزرمنوال** را به کاربران بدهید.

---

## نصب با ویزارد وب (جایگزین ساده‌تر برای بخش تنظیم .env و migrate)

پس از اینکه پروژه روی سرور قرار گرفت و **حداقل یک‌بار** `composer install` اجرا شد:

1. مرورگر را باز کنید:  
   `https://your-domain.com/install/`  
   یا در لوکال: `http://127.0.0.1:8000/install/`
2. مرحله **نیازمندی‌ها** را ببینید؛ موارد قرمز را رفع کنید.
3. اطلاعات دیتابیس و آدرس سایت را وارد کنید.
4. روی **شروع نصب** بزنید تا migrate و seed اجرا شود.
5. با `admin@example.com` / `password` وارد شوید.
6. **حتماً** پوشه `public/install` را حذف کنید.

اگر وب‌سرور اجازه `exec` / `proc_open` ندهد، مرحله artisan از ویزارد شکست می‌خورد و باید همان دستورها را دستی در SSH بزنید.