# 🏗️ Projectra - راهنمای نصب و راه‌اندازی

## پیش‌نیازها

قبل از شروع، مطمئن شوید این نرم‌افزارها روی سیستم شما نصب هستند:

| نرم‌افزار | حداقل نسخه | بررسی |
|-----------|------------|-------|
| PHP | 8.2+ | `php -v` |
| Composer | 2.x | `composer --version` |
| Node.js | 18+ | `node -v` |
| npm/bun | هر دو قابل استفاده‌اند | `npm -v` |
| MySQL | 8.0+ / MariaDB 10.6+ | `mysql --version` |
| Git | 2.x | `git --version` |

### اکستنشن‌های PHP مورد نیاز:
```bash
php -m | grep -E "intl|pdo|mbstring|xml|curl|openssl|fileinfo"
```
باید شامل: `intl`, `pdo_mysql`, `mbstring`, `simplexml`, `curl`, `openssl`, `fileinfo`

---

## مرحله ۱: ساخت پروژه Laravel

```bash
# ساخت پروژه جدید Laravel
composer create-project laravel/laravel projectra
cd projectra
```

---

## مرحله ۲: کپی فایل‌های Projectra

فایل‌های ZIP دانلود شده را Extract کنید و **فقط** پوشه‌ها و فایل‌های زیر را در پروژه Laravel کپی کنید:

### فایل‌های ریشه (جایگزین کنید):
```
composer.json
package.json
vite.config.js
tailwind.config.js
postcss.config.js
.env.example
```

### پوشه app/ (جایگزین کنید):
```
app/Http/Controllers/
app/Http/Middleware/
app/Http/Requests/
app/Http/Kernel.php
app/Models/
app/Helpers/
app/Policies/
app/Providers/AppServiceProvider.php
app/Providers/BladeServiceProvider.php
```

### پوشه‌های دیگر:
```
config/projectra.php
config/projectra_app_additions.php
database/migrations/
database/seeders/
resources/views/
resources/lang/
resources/css/
resources/js/
routes/web.php
routes/api.php
public/logo.svg
```

---

## مرحله ۳: نصب وابستگی‌ها

```bash
# نصب پکیج‌های PHP
composer install

# نصب پکیج‌های Frontend
npm install
```

---

## مرحله ۴: تنظیم محیط

```bash
# کپی فایل env
cp .env.example .env

# ساخت کلید اپلیکیشن
php artisan key:generate
```

فایل `.env` را باز کنید و تنظیمات دیتابیس را وارد کنید:
```env
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=projectra
DB_USERNAME=root
DB_PASSWORD=your_password
```

---

## مرحله ۵: تنظیمات اضافی config/app.php

فایل `config/app.php` را باز کنید و تغییرات زیر را اعمال کنید:

### اضافه کردن Providers:
```php
'providers' => [
    // ... existing providers ...
    
    // Projectra additions
    Spatie\Permission\PermissionServiceProvider::class,
    Morilog\Jalali\JalaliServiceProvider::class,
    Maatwebsite\Excel\ExcelServiceProvider::class,
    Barryvdh\DomPDF\ServiceProvider::class,
    App\Providers\BladeServiceProvider::class,
],
```

### اضافه کردن Aliases:
```php
'aliases' => [
    // ... existing aliases ...
    
    // Projectra additions
    'Jalali' => Morilog\Jalali\JalaliFacade::class,
    'Excel' => Maatwebsite\Excel\Facades\Excel::class,
    'PDF' => Barryvdh\DomPDF\Facade\Pdf::class,
],
```

### تنظیم locale پیش‌فرض:
```php
'locale' => env('APP_LOCALE', 'fa'),
'fallback_locale' => 'en',
```

---

## مرحله ۶: تنظیم composer.json

فایل `composer.json` را باز کنید و در بخش `autoload` اضافه کنید:

```json
"autoload": {
    "psr-4": {
        "App\\": "app/",
        "Database\\Factories\\": "database/factories/",
        "Database\\Seeders\\": "database/seeders/"
    },
    "files": [
        "app/Helpers/helpers.php"
    ]
},
```

سپس:
```bash
composer dump-autoload
```

---

## مرحله ۷: ساخت دیتابیس

```bash
# ورود به MySQL
mysql -u root -p

# ساخت دیتابیس
CREATE DATABASE projectra CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
EXIT;
```

---

## مرحله ۸: اجرای Migration و Seeder

```bash
# اجرای Migration‌ها
php artisan migrate

# اجرای Seeder (داده نمونه)
php artisan db:seed
```

---

## مرحله ۹: ساخت Asset‌ها

```bash
# ساخت CSS/JS برای توسعه
npm run dev

# یا برای تولید
npm run build
```

---

## مرحله ۱۰: اجرای پروژه

```bash
php artisan serve
```

پروژه در آدرس `http://localhost:8000` در دسترس خواهد بود.

---

## 👤 حساب‌های پیش‌فرض (بعد از db:seed)

| نقش | ایمیل | رمز عبور | Tenant |
|------|-------|----------|--------|
| Super Admin | admin@projectra.ir | password | - |
| Admin (سازندگی سپید) | admin@sepideh.ir | password | سازندگی سپید |
| Project Manager | manager@sepideh.ir | password | سازندگی سپید |
| Admin (Global) | admin@global.com | password | Global Construction |

> ⚠️ رمز عبور‌ها را حتماً بعد از نصب تغییر دهید!

---

## 📁 ساختار پوشه‌ها

```
projectra/
├── app/
│   ├── Http/
│   │   ├── Controllers/     ← ۸ کنترلر
│   │   ├── Middleware/       ← ۳ میدلور (SetTenant, SetLocale, TenantScope)
│   │   ├── Requests/         ← ۴ Form Request
│   │   └── Kernel.php
│   ├── Models/              ← ۱۹ مدل Eloquent
│   ├── Helpers/             ← ۵ فایل Helper (Jalali, Number, Currency, Calendar, helpers)
│   ├── Policies/            ← ۴ Policy
│   └── Providers/           ← AppServiceProvider + BladeServiceProvider
├── config/
│   └── projectra.php        ← تنظیمات اختصاصی Projectra
├── database/
│   ├── migrations/          ← ۲۰ Migration
│   └── seeders/             ← ۹ Seeder
├── resources/
│   ├── views/               ← ۱۸ Blade Template
│   │   ├── layouts/         ← app, sidebar, header
│   │   ├── dashboard/       ← داشبورد اصلی
│   │   ├── projects/        ← لیست، فرم، جزئیات
│   │   ├── tasks/           ← لیست، فرم
│   │   ├── employees/       ← لیست، فرم
│   │   ├── expenses/        ← لیست، فرم
│   │   ├── auth/            ← صفحه ورود
│   │   └── components/      ← status-badge, localized-date, currency-display, priority-badge
│   ├── lang/
│   │   ├── fa.json          ← ۱۱۲ کلید فارسی
│   │   └── en.json          ← ۱۱۲ کلید انگلیسی
│   ├── css/
│   └── js/
└── routes/
    ├── web.php              ← مسیرهای وب
    └── api.php              ← مسیرهای API
```

---

## 🔧 قابلیت‌های بین‌المللی‌سازی (i18n)

### Blade Directive‌ها:
```blade
@localizeNumber(1234567)           ← ۱,۲۳۴,۵۶۷ (فارسی) / 1,234,567 (انگلیسی)
@localizeDate($date)               ← ۱۴۰۴/۰۳/۰۵ (شمسی) / 2025/05/26 (میلادی)
@localizeCurrency(45000000, 'IRR') ← ۴۵,۰۰۰,۰۰۰ ﷼
@direction                         ← rtl یا ltr
@isRtl ... @endIsRtl              ← بلوک شرطی RTL
```

### Helper Function‌ها:
```php
jalali_date($date)              // تبدیل به شمسی
persian_num(12345)              // ۱۲۳۴۵
format_currency(45000000, 'IRR')// ۴۵,۰۰۰,۰۰۰ ﷼
format_number(1234567)          // ۱,۲۳۴,۵۶۷
calendar_date($date)            // تاریخ بر اساس تقویم فعلی
get_direction()                 // 'rtl' یا 'ltr'
```

### اولویت زبان/تقویم:
```
کاربر (User) → Tenant → Session → مرورگر → پیش‌فرض سیستم
```

---

## ❓ مشکلات رایج

### 1. خطای "Class not found"
```bash
composer dump-autoload
```

### 2. خطای permission در storage
```bash
chmod -R 775 storage bootstrap/cache
```

### 3. خطای اکستنشن intl
```bash
# Ubuntu
sudo apt-get install php8.2-intl

# macOS
brew install php@8.2
```

### 4. مشکل Vite
```bash
npm install && npm run build
```

---

## 📞 پشتیبانی

- مستندات پروژه: پوشه `upload/` (اسناد ۱ تا ۱۱)
- لاگ تغییرات: `worklog.md`

---

**نسخه:** MVP (Phase 0)  
**تاریخ:** ۱۴۰۴/۰۳/۰۶  
**تکنولوژی:** Laravel 11 + Blade + Tailwind CSS + Alpine.js