341 lines
8.3 KiB
Markdown
341 lines
8.3 KiB
Markdown
# 🏗️ 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
|