docs(project): update documentation and project status for phase 1
Update project documentation to reflect the completion of Phase 0 and the current progress of Phase 1. This includes: - Updating `STATUS.md` and `README.md` to mark Phase 0 as completed. - Adding details for Phase 1 features: `PriceCalculatorService`, online order forms, and professional PDF generation. - Documenting new API endpoints for price calculation and tracking. - Updating the Laravel technical stack to include `dompdf` and `laravel-dompdf`. - Detailing the new directory structure and public web routes.
This commit is contained in:
Kazem Alghasi
parent
31d28fbe68
commit
91ecbc7656
@ -1,9 +1,9 @@
|
||||
# 🚨 STATUS.md — این فایل را اول بخوانید
|
||||
|
||||
> **آخرین بهروزرسانی:** 2026-08-04 01:10 (Asia/Tehran)
|
||||
> **فاز در حال اجرا:** فاز ۰ (بنیان داده + ترکینگ دستی + مهاجرت دادههای تاریخی)
|
||||
> **آخرین بهروزرسانی:** 2026-08-04 09:50 (Asia/Tehran)
|
||||
> **فاز در حال اجرا:** فاز ۱ (موتور قیمتگذاری + ثبت سفارش آنلاین + تولید PDF)
|
||||
> **توسعهدهنده:** VernaSoft Group — Kazem Alghasi
|
||||
> **وضعیت کلی پروژه:** در حال اجرا — Code Review کامل شد، نیاز به رفع نقص middleware است
|
||||
> **وضعیت کلی پروژه:** فاز ۰ کامل — فاز ۱ در حال اجرا — Code Review انجام شد
|
||||
|
||||
---
|
||||
|
||||
@ -234,12 +234,12 @@
|
||||
|
||||
### کارهای فاز ۱ (پس از تأیید فاز ۰)
|
||||
|
||||
- [ ] موتور قیمتگذاری کامل (PriceCalculatorService) — نوشته شد، نیاز به تست با دادههای واقعی
|
||||
- [ ] جدول `shipping_rates` — ۴۰۴ رکورد import شد، نیاز به تکمیل
|
||||
- [ ] فرم ثبت سفارش آنلاین با ۹ ردیف کالای گمرکی
|
||||
- [x] موتور قیمتگذاری کامل (`PriceCalculatorService`) — نوشته شد، تست با دادههای واقعی انجام شد
|
||||
- [x] جدول `shipping_rates` — ۱۳۸ رکورد import شد با پشتیبانی از ۵ نوع سرویس/جهت
|
||||
- [x] فرم ثبت سفارش آنلاین با ۹ ردیف کالای گمرکی
|
||||
- [x] تولید PDF: AWB، INVOICE، Label — اولیه پیاده شد با لوگوی استخراجشده از اکسل و چیدمان مطابق ساختار شیتها. LABEL برای پرینتر لیزری+A4 طراحی شد. نیاز به تطبیق نهایی با قالبهای اکسل (بعد از تکمیل فاز ۱)
|
||||
- [x] ماژول ایمپورت اکسل تعرفهها — command با قابلیتهای --clear و --dry-run پیاده شد
|
||||
- [ ] صفحه استعلام قیمت واقعی
|
||||
- [x] صفحه استعلام قیمت واقعی — رابط کاربری عمومی + API محاسبه قیمت
|
||||
|
||||
---
|
||||
|
||||
|
||||
@ -24,6 +24,8 @@ php artisan serve
|
||||
| `laravel/framework` | ^11.0 | هسته فریمورک |
|
||||
| `filament/filament` | 3.3.* | پنل مدیریت ادمین |
|
||||
| `maatwebsite/excel` | ^3.1 | ایمپورت اکسل |
|
||||
| `barryvdh/laravel-dompdf` | ^3.1 | تولید PDF |
|
||||
| `dompdf/dompdf` | ^3.0 | موتور تولید PDF |
|
||||
| `morilog/jalali` | ^3.0 | تبدیل تاریخ شمسی/میلادی |
|
||||
|
||||
---
|
||||
@ -35,22 +37,26 @@ php artisan serve
|
||||
├── app/
|
||||
│ ├── Models/ # مدلهای Eloquent
|
||||
│ ├── Enums/ # Enumهای سفارشی
|
||||
│ ├── Services/ # منطق تجاری
|
||||
│ ├── Services/ # PriceCalculatorService, PdfService, ...
|
||||
│ ├── Http/
|
||||
│ │ ├── Controllers/ # کنترلرها
|
||||
│ │ ├── Middleware/ # میانافزارهای سفارشی
|
||||
│ │ ├── Controllers/
|
||||
│ │ │ ├── Api/ # PricingController, TrackController
|
||||
│ │ │ ├── OrderController.php
|
||||
│ │ │ ├── PricingPageController.php
|
||||
│ │ │ └── ShipmentPdfController.php
|
||||
│ │ ├── Middleware/ # ApiKeyMiddleware
|
||||
│ │ └── Requests/ # Form Request Validation
|
||||
│ ├── Imports/ # کلاسهای ایمپورت اکسل
|
||||
│ ├── Console/Commands/ # دستورات Artisan سفارشی
|
||||
│ ├── Imports/ # ShippingRatesImport
|
||||
│ ├── Console/Commands/ # ImportShippingRates
|
||||
│ └── Filament/ # پنل مدیریت
|
||||
│ ├── Resources/ # منابع Filament
|
||||
│ └── Pages/ # صفحات سفارشی
|
||||
│ ├── Resources/ # Country, Shipment, ShippingRate, ShipmentItem
|
||||
│ └── Pages/ # Settings, Dashboard
|
||||
├── database/
|
||||
│ ├── migrations/ # ۷ migration فاز ۰
|
||||
│ └── seeders/ # seeders داده اولیه
|
||||
├── routes/
|
||||
│ ├── web.php # routes وب (Filament)
|
||||
│ └── api.php # routes API
|
||||
│ ├── web.php # /order, /pricing, PDF downloads
|
||||
│ └── api.php # /api/v1/calculate, /api/v1/track/{awb}
|
||||
└── config/
|
||||
├── ifnex.php # تنظیمات اختصاصی
|
||||
└── cors.php # تنظیمات CORS
|
||||
@ -62,11 +68,20 @@ php artisan serve
|
||||
|
||||
| روش | مسیر | توضیحات |
|
||||
|------|------|---------|
|
||||
| POST | `/api/v1/calculate` | محاسبه قیمت حمل (بدون احراز هویت) |
|
||||
| GET | `/api/v1/track/{awb_no}` | استعلام وضعیت مرسوله با API Key |
|
||||
|
||||
**درخواست نمونه:**
|
||||
**درخواست نمونه محاسبه قیمت:**
|
||||
```bash
|
||||
curl -H "Authorization: Bearer ifnex-local-dev-key" http://localhost:8000/api/v1/track/TEST123
|
||||
curl -X POST http://localhost:8000/api/v1/calculate \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"direction": "Outbound",
|
||||
"type": "DOC_NORMAL",
|
||||
"country_iso": "AE",
|
||||
"weight": 1,
|
||||
"volumetric_weight": 1
|
||||
}'
|
||||
```
|
||||
|
||||
---
|
||||
@ -75,14 +90,28 @@ curl -H "Authorization: Bearer ifnex-local-dev-key" http://localhost:8000/api/v1
|
||||
|
||||
```bash
|
||||
# ایمپورت نرخهای حمل از اکسل
|
||||
php artisan ifnex:import:rates {path}
|
||||
php artisan ifnex:import:rates {path} [--clear] [--dry-run]
|
||||
|
||||
# ایمپورت دادههای تاریخی مرسولهها
|
||||
php artisan ifnex:import:shipments {path}
|
||||
# ایمپورت دادههای ترکینگ
|
||||
php artisan ifnex:import:tracking {path}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🌐 صفحات عمومی
|
||||
|
||||
| مسیر | توضیحات |
|
||||
|------|---------|
|
||||
| `/` | صفحه اصلی |
|
||||
| `/order` | فرم ثبت سفارش آنلاین |
|
||||
| `/order/success/{shipment}` | صفحه تایید سفارش |
|
||||
| `/pricing` | صفحه استعلام قیمت |
|
||||
| `/shipments/{id}/pdf/awb` | دانلود AWB (نیاز به لاگین) |
|
||||
| `/shipments/{id}/pdf/invoice` | دانلود INVOICE (نیاز به لاگین) |
|
||||
| `/shipments/{id}/pdf/label` | دانلود LABEL (نیاز به لاگین) |
|
||||
|
||||
---
|
||||
|
||||
## 🔐 احراز هویت و دسترسی
|
||||
|
||||
| نقش | دسترسی |
|
||||
@ -100,6 +129,7 @@ php artisan ifnex:import:shipments {path}
|
||||
- **Livewire 3.8.3** — فرمها با AJAX کار میکنند، POST مستقیم به `/admin/login` ثبت نمیشود
|
||||
- **Filament 3.3.x** — پنل مدیریت در مسیر `/admin`
|
||||
- **MySQL 8+** — الزام migrations با JSON columns
|
||||
- **DomPDF** — برای تولید PDFهای AWB, INVOICE, LABEL استفاده میشود
|
||||
|
||||
---
|
||||
|
||||
@ -109,6 +139,7 @@ php artisan ifnex:import:shipments {path}
|
||||
- `STATUS.md` — وضعیت فعلی و گزارش پیشرفت
|
||||
- `IFNEX_Phase0_Checklist.md` — چکلیست دقیق فاز ۰
|
||||
- `Phase0_Proposal.md` — مرجع اصلی پروژه
|
||||
- `EXCEL_ANALYSIS.md` — تحلیل کامل فایلهای اکسل عملیاتی
|
||||
|
||||
---
|
||||
|
||||
|
||||
92
README.md
92
README.md
@ -3,7 +3,7 @@
|
||||
|
||||
| مورد | توضیحات |
|
||||
| :--- | :--- |
|
||||
| **ویرایش سند** | v3.0 (بازبینی شده — Laravel 11 + Filament 3.3 + مهاجرت اولیه دادههای تاریخی) |
|
||||
| **ویرایش سند** | v4.0 (Laravel 11 + Filament 3.3 + فاز ۰ کامل + فاز ۱ در حال اجرا) |
|
||||
| **توسعهدهنده** | VernaSoft Group — Kazem Alghasi |
|
||||
| **مشتری** | شرکت حمل و نقل بینالمللی ایفنکس (IFNEX) — اصفهان |
|
||||
|
||||
@ -34,8 +34,8 @@
|
||||
|
||||
| فاز | هدف اصلی | مدت زمان | وضعیت |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **فاز ۰** | بنیان داده + وبسایت + ترکینگ دستی + مهاجرت دادههای تاریخی | ۴ هفته | 🚧 در دست اقدام |
|
||||
| **فاز ۱** | موتور قیمتگذاری کامل + ثبت سفارش آنلاین + تولید PDFها | ۴-۶ هفته | ⏳ در صف |
|
||||
| **فاز ۰** | بنیان داده + وبسایت + ترکینگ دستی + مهاجرت دادههای تاریخی | ۴ هفته | ✅ کامل |
|
||||
| **فاز ۱** | موتور قیمتگذاری کامل + ثبت سفارش آنلاین + تولید PDFها + استعلام قیمت | ۴-۶ هفته | 🚧 در حال اجرا |
|
||||
| **فاز ۲** | حساب کاربری مشتری + کیف پول + حسابداری ساده + تخفیف حجمی | ۴ هفته | ⏳ در صف |
|
||||
| **فاز ۳** | VPS پل + API ترکینگ زنده + CRM + داشبورد مالی تحلیلی | ۶-۸ هفته | ⏳ در صف |
|
||||
|
||||
@ -43,30 +43,54 @@
|
||||
|
||||
---
|
||||
|
||||
## ✨ ویژگیهای کلیدی فاز ۰ (مورد اجرا)
|
||||
## ✨ ویژگیهای کلیدی
|
||||
|
||||
### ۱. اسکیمای دیتابیس اصلاحشده (بر اساس فایل اکسل عملیاتی)
|
||||
- جدول `countries` با ۴ زون مجزا (صادرات/واردات × پارسل/داکیومنت) — بهجای ۲ زون قبلی
|
||||
- پشتیبانی از ۳ نوع سرویس: `DOC_NORMAL`, `DOC_ECONOMY`, `PARCEL`
|
||||
- جدول `shipment_carrier_mappings` برای نگاشت چند شرکت حمل به هر بارنامه
|
||||
- جدول `shipment_tracking_events` برای ذخیره تایملاین کامل رویدادهای هر مرسوله
|
||||
### فاز ۰ (تکمیل شده)
|
||||
1. اسکیمای دیتابیس اصلاحشده (بر اساس فایل اکسل عملیاتی)
|
||||
- جدول `countries` با ۴ زون مجزا (صادرات/واردات × پارسل/داکیومنت)
|
||||
- پشتیبانی از ۳ نوع سرویس: `DOC_NORMAL`, `DOC_ECONOMY`, `PARCEL`
|
||||
- جدول `shipment_carrier_mappings` برای نگاشت چند شرکت حمل به هر بارنامه
|
||||
- جدول `shipment_tracking_events` برای ذخیره تایملاین کامل رویدادهای هر مرسوله
|
||||
|
||||
### ۲. پنل مدیریت اختصاصی (Laravel Filament)
|
||||
- مدیریت ۲۳۳ کشور با زونهای صادرات و واردات
|
||||
- ماژول ایمپورت اکسل تعرفهها (در فاز ۱)
|
||||
- فرم تنظیمات سیستم: تغییر سریع ارزها و ضریب سود بدون دستکاری کد
|
||||
- UX تخصصی اپراتور ترکینگ: افزودن رویداد در چند ثانیه با فیلدهای از پیش پر شده
|
||||
2. پنل مدیریت اختصاصی (Laravel Filament)
|
||||
- مدیریت ۲۳۳ کشور با زونهای صادرات و واردات
|
||||
- فرم تنظیمات سیستم: تغییر سریع ارزها و ضریب سود بدون دستکاری کد
|
||||
- UX تخصصی اپراتور ترکینگ: افزودن رویداد در چند ثانیه با فیلدهای از پیش پر شده
|
||||
|
||||
### ۳. ارتباطات API و فرانتاند
|
||||
- **API استعلام قیمت (در فاز ۱):** `POST /api/calculate-price`
|
||||
- **API ترکینگ (در فاز ۰):** `GET /api/track/{awb_no}`
|
||||
- **پلاگین IFNEX Bridge:** شورتکد `[ifnex_tracking_form]` برای فرم رهگیری در وردپرس
|
||||
- **امنیت:** API Key + Rate Limiting + CORS whitelist + Form Request Validation
|
||||
3. ارتباطات API و فرانتاند
|
||||
- **API ترکینگ:** `GET /api/track/{awb_no}` با API Key + Rate Limiting + CORS
|
||||
- **پلاگین IFNEX Bridge:** شورتکد `[ifnex_tracking_form]` برای فرم رهگیری در وردپرس
|
||||
- **امنیت:** API Key + Rate Limiting + CORS whitelist + Form Request Validation
|
||||
|
||||
### ۴. مهاجرت دادههای تاریخی
|
||||
- انتقال ۳۹۵۰ رکورد تاریخی از فایل اکسل به دیتابیس جدید
|
||||
- اعتبارسنجی و پاکسازی خودکار دادهها
|
||||
- در دسترس قرار دادن تاریخچهی کامل برای مشتریان قدیمی
|
||||
4. مهاجرت دادههای تاریخی
|
||||
- انتقال ۳۹۵۰ رکورد تاریخی از فایل اکسل به دیتابیس جدید
|
||||
- اعتبارسنجی و پاکسازی خودکار دادهها
|
||||
|
||||
### فاز ۱ (در حال اجرا)
|
||||
1. موتور قیمتگذاری کامل (`PriceCalculatorService`)
|
||||
- محاسبه خودکار قیمت بر اساس وزن، زون، نوع سرویس و جهت ارسال
|
||||
- پشتیبانی از ۴ زون مجزا (export/import × doc/parcel)
|
||||
- اعمال ضریب سود، VAT و هزینههای اضافی
|
||||
|
||||
2. فرم ثبت سفارش آنلاین
|
||||
- فرم عمومی برای مشتریان با ۹ ردیف کالای گمرکی
|
||||
- اعتبارسنجی خودکار و محاسبه لحظهای قیمت
|
||||
- تولید AWB number خودکار
|
||||
|
||||
3. تولید PDFهای حرفهای
|
||||
- **AWB:** بارنامه هوایی با لوگوی IFNEX
|
||||
- **INVOICE:** فاکتور تجاری با جدول ۹ ردیف کالای گمرکی
|
||||
- **LABEL:** لیبل چاپی برای بستهها (پرینتر لیزری + کاغذ چسبان A4)
|
||||
- تطبیق اولیه با قالبهای اکسل + لوگوی استخراجشده
|
||||
|
||||
4. صفحه استعلام قیمت واقعی
|
||||
- رابط کاربری عمومی برای محاسبه قیمت تقریبی حمل
|
||||
- نمایش قیمت پایه (درهم) و قیمت نهایی (ریال)
|
||||
|
||||
5. ماژول ایمپورت اکسل تعرفهها
|
||||
- کامند `php artisan ifnex:import:rates` با قابلیتهای `--clear` و `--dry-run`
|
||||
- پشتیبانی از شیتهای Export Rate، Import Rate و DocEco
|
||||
- تبدیل خودکار واحد قیمت (ریال → درهم) برای شیتهای DocNor/DocEco
|
||||
|
||||
---
|
||||
|
||||
@ -90,14 +114,19 @@ IFNEX-Logistics/
|
||||
│
|
||||
└── 04_Laravel/ # هسته مرکزی سیستم (بکاند)
|
||||
├── app/
|
||||
│ ├── Models/ # Country, Shipment, ShipmentTrackingEvent, ...
|
||||
│ ├── Models/ # Country, Shipment, ShipmentItem, ShipmentRate, ...
|
||||
│ ├── Enums/ # ShipmentDirection, ShipmentType, ShipmentStatus, ...
|
||||
│ ├── Services/ # TrackingService, PriceCalculatorService
|
||||
│ ├── Services/ # PriceCalculatorService, PdfService, ...
|
||||
│ ├── Http/
|
||||
│ │ ├── Controllers/Api/ # TrackController
|
||||
│ │ ├── Controllers/
|
||||
│ │ │ ├── Api/ # PricingController, TrackController
|
||||
│ │ │ ├── OrderController.php # فرم ثبت سفارش آنلاین
|
||||
│ │ │ ├── PricingPageController.php # صفحه استعلام قیمت
|
||||
│ │ │ └── ShipmentPdfController.php # تولید PDF
|
||||
│ │ ├── Middleware/ # ApiKeyMiddleware
|
||||
│ │ └── Requests/ # Form Request Validation classes
|
||||
│ ├── Imports/ # ShippingRatesImport, HistoricalShipmentsImport
|
||||
│ ├── Imports/ # ShippingRatesImport
|
||||
│ ├── Console/Commands/ # ImportShippingRates
|
||||
│ └── Filament/ # پنل مدیریت ادمین
|
||||
│ ├── Resources/ # Country, Shipment, ShippingRate, ShipmentItem
|
||||
│ └── Pages/ # Settings, Dashboard, Custom pages
|
||||
@ -105,8 +134,13 @@ IFNEX-Logistics/
|
||||
│ ├── migrations/ # ۷ migration فاز ۰
|
||||
│ └── seeders/ # CountriesSeeder, SystemSettingSeeder
|
||||
├── routes/
|
||||
│ ├── web.php
|
||||
│ └── api.php
|
||||
│ ├── web.php # روتهای عمومی: /order, /pricing, PDF download
|
||||
│ └── api.php # API: /api/v1/calculate, /api/v1/track/{awb}
|
||||
├── resources/views/
|
||||
│ ├── layouts/app.blade.php # لایاوت عمومی صفحات
|
||||
│ ├── orders/ # فرم ثبت سفارش + صفحه موفقیت
|
||||
│ ├── pricing/ # صفحه استعلام قیمت
|
||||
│ └── pdfs/ # قالبهای PDF: AWB, INVOICE, LABEL
|
||||
├── config/
|
||||
│ ├── ifnex.php
|
||||
│ └── cors.php
|
||||
|
||||
Loading…
Reference in New Issue
Block a user