ifnex/01_Documents/STATUS.md

🚨 STATUS.md — این فایل را اول بخوانید!

آخرین به‌روزرسانی: August 2026
فاز در حال اجرا: فاز ۰ (بنیان داده + ترکینگ دستی + مهاجرت داده‌های تاریخی)
توسعه‌دهنده: VernaSoft Group — Kazem Alghasi
وضعیت کلی پروژه: در حال اجرا — بازنگری مسیر از نقشه‌ی ۳ فازی به ۴ فازی انجام شده است

---

⚠️ هشدار حیاتی — قبل از هر کاری بخوانید

این پروژه دارای سه سند تاریخی است که با هم تناقض دارند. فقط یکی از آن‌ها معتبر است:

فایل	وضعیت	اقدام
01_Documents/Phase0_Proposal.md	✅ معتبر و مرجع اصلی	حتماً کامل بخوانید
01_Documents/PRD_v2.md	❌ قدیمی و ناقص	فقط برای مرجع تاریخی — به اسکیمای دیتابیس آن اعتماد نکنید
01_Documents/Project_Roadmap.md	❌ قدیمی (۳ فازی)	فقط برای مرجع تاریخی — به فازبندی آن اعتماد نکنید
01_Documents/EXCEL_ANALYSIS.md	✅ مرجع تحلیل اکسل	حتماً بخوانید قبل از کار با داده‌های تاریخی
README.md (ریشه)	✅ به‌روز (نسخه ۲)	برای نمای کلی بخوانید

🔴 قانون طلایی: هرجا بین اسناد تناقض دیدی، به Phase0_Proposal.md اعتماد کن. اسناد قدیمی فقط برای فهم تاریخچه‌ی تصمیمات نگه داشته شده‌اند.

---

📌 Quick Reference — نسخه‌ها و معماری

تکنولوژی‌ها (قفل‌شده)

مورد	نسخه/مقدار	دلیل
Laravel	11 (همه‌جا یکسان)	در PRD قدیمی ۱۰+ نوشته، در Roadmap قدیمی ۱۱، در README قدیمی ۱۲ — نسخه نهایی: ۱۱
PHP	8.2+	الزام لاراول ۱۱
MySQL	8+	برای پشتیبانی JSON columns
WordPress	آخرین نسخه پایدار	با Polylang برای چندزبانه
پنل ادمین	Laravel Filament 3.x	برای سرعت توسعه
Frontend	وردپرس + قالب DHL-inspired	کپی نکنید — فقط الهام

معماری کلی

┌─────────────────┐         REST API         ┌─────────────────┐
│   WordPress     │  ←─────────────────────→  │   Laravel 11    │
│  (Frontend)     │   پلاگین IFNEX Bridge     │   (Backend)     │
│                 │                           │  + Filament     │
└─────────────────┘                           └────────┬────────┘
                                                       │
                                              ┌────────┴────────┐
                                              │     MySQL 8     │
                                              └─────────────────┘
                                                       │
                                              (فاز ۳)  │
                                              ┌────────┴────────┐
                                              │  VPS پل خارج    │
                                              │  (هلند/آلمان)   │
                                              └────────┬────────┘
                                                       │
                                              ┌────────┴────────┐
                                              │ TrackingMore /  │
                                              │ 17track API     │
                                              └─────────────────┘

---

✅ وضعیت فعلی کار

کارهای انجام‌شده (تا آخرین به‌روزرسانی)

• تحلیل کامل فایل‌های اکسل عملیاتی شرکت
• شناسایی تناقضات PRD قدیمی با واقعیت اکسل (۴ زون به‌جای ۲، ۳ نوع سرویس به‌جای ۲، فیلدهای غایب VAT/Packing/Warehousing)
• تدوین سند Phase0_Proposal.md (مرجع اصلی پروژه)
• بازنگری نقشه‌ی راه از ۳ فازی به ۴ فازی
• طراحی اسکیمای دیتابیس فاز ۰ (۶ جدول اصلی)
• بازنویسی README.md با ساختار جدید
• تدوین EXCEL_ANALYSIS.md (تحلیل کامل اکسل)

کارهای در دست اقدام (فاز ۰)

• نصب و راه‌اندازی پروژه‌ی لاراول ۱۱ در پوشه 04_Laravel
• نصب Filament و احراز هویت ادمین
• نوشتن Migration ها برای ۶ جدول اصلی:
  • countries (با ۴ زون مجزا)
  • shipments (فاز ۰ — فیلدهای حداقلی)
  • shipment_carrier_mappings
  • shipment_tracking_events
  • system_settings
  • users (با نقش‌های super_admin/tracking_operator/data_entry/customer)
• Seeder کشورها (۲۳۳ کشور با ۴ زون از شیت Zone اکسل)
• API ترکینگ: GET /api/track/{awb_no}
• پنل Filament با UX اپراتور ترکینگ (افزودن رویداد سریع)
• پلاگین وردپرس IFNEX Bridge با شورت‌کد [ifnex_tracking_form]
• اسکریپت مهاجرت ۳۹۵۰ رکورد تاریخی از شیت List اکسل
• راه‌اندازی وردپرس روی هاست مشتری
• طراحی لندینگ پیج DHL-inspired (بدون کپی)
• تست نهایی فاز ۰ و تحویل به مشتری

کارهای فاز ۱ (پس از تأیید فاز ۰)

• موتور قیمت‌گذاری کامل (PriceCalculatorService)
• جدول shipping_rates با نرخ‌های Import/Export
• فرم ثبت سفارش آنلاین با ۹ ردیف کالای گمرکی
• تولید PDF: AWB، INVOICE، Label مطابق قالب اکسل
• ماژول ایمپورت اکسل تعرفه‌ها
• صفحه استعلام قیمت واقعی

---

🚫 خط قرمزها (DO NOT) — هرگز این کارها را نکن

این قوانین بر اساس تجربه و تصمیمات تأییدشده‌ی مشتری تنظیم شده‌اند. نقض هر کدام = بازگشت به عقب و کار مضاعف.

🚫 اسکیمای دیتابیس

• NEVER جدول countries را به ۲ زون برگردانی — ۴ زون مجزا (export_parcel, export_doc, import_parcel, import_doc) الزامی است. هر کشور برای پارسل و داکیومنت زون‌های متفاوتی دارد (مثلاً افغانستان: پارسل=۷، داکیومنت=۵).
• NEVER فقط ۲ نوع سرویس (DOCUMENT/NON DOC) پیاده کن — ۳ نوع الزامی است: DOC_NORMAL، DOC_ECONOMY، PARCEL (مطابق شیت‌های DocNor، DocEco، Parcel در اکسل).
• NEVER فیلد forwarder_track_id را به‌عنوان فیلد واحد در shipments نگه دار — باید جدول جداگانه shipment_carrier_mappings ساخته شود، چون هر مرسوله ممکن است با چند شرکت حمل مرتبط باشد (مثلاً اول DHL سپس Aramex).
• NEVER فیلدهای مالی مهم (VAT، Domestic Pickup، Domestic Delivery، Warehousing Cost، Extra Service، Packing Cost) را حذف کن — حتی اگر در فاز ۰ استفاده نمی‌شوند، باید در Migration آماده باشند.
• NEVER فیلد status در shipments را به String تغییر دهی — Enum یکپارچه‌تر و امن‌تر است.

🚫 معماری

• NEVER ترکینگ را در وردپرس پیاده کن — همیشه در لاراول. وردپرس فقط نمایش می‌دهد. اگر این کار را بکنی، در فاز ۳ باید تمام داده‌ها را به لاراول مهاجرت دهی (دوباره‌کاری).
• NEVER در وردپرس پردازش داده‌ی سفارش انجام دهی — تمام فرم‌ها از طریق پلاگین IFNEX Bridge به لاراول ارسال می‌شوند.
• NEVER API لاراول را بدون API Key، Rate Limiting و CORS whitelist بگذاری — امنیت حیاتی است.
• NEVER از CORS * استفاده کنی — فقط دامنه‌ی تولیدی وردپرس باید whitelist شود.
• NEVER تاریخ‌ها را به شمسی در دیتابیس ذخیره کنی — همیشه به‌صورت timestamp میلادی. تبدیل به شمسی فقط در لایه‌ی نمایش (با morilog/jalali).

🚫 طراحی و کپی‌رایت

• NEVER از رنگ، لوگو یا عناصر هویت بصری DHL کپی کنی — نقض کپی‌رایت. الهام از چیدمان و UX مجاز است.
• NEVER خروجی PDF (AWB، Invoice، Label) را به فارسی بسازی — مطابق اکسل اصلی، PDF باید انگلیسی باشد. اما پنل ادمین و رابط کاربری فرانت‌اند فارسی است.

🚫 فرآیند

• NEVER فایل .env را در Git کامیت کنی — در .gitignore است.
• NEVER APP_DEBUG=true را در محیط تولید بگذاری.
• NEVER اسکوپ فاز ۰ را بدون Change Request رسمی تغییر دهی — اگر مشتری درخواست افزودن قابلیت کرد، قیمت‌گذاری جداگانه لازم است.
• NEVER فاز ۱ را قبل از تأیید رسمی فاز ۰ توسط مشتری شروع کنی.

---

❓ سوالات متداول (FAQ)

س: کدام نسخه لاراول استفاده کنم؟

ج: لاراول ۱۱. اگر در PRD_v2.md نوشته «Laravel 10+» یا در Roadmap نوشته «Laravel 11»، نسخه نهایی ۱۱ است.

س: آیا PRD_v2.md هنوز معتبر است؟

ج: بخش‌های کلی آن (معماری Headless، توضیح کسب‌وکار، VPS پل) معتبرند. اما بخش‌های زیر قدیمی و اشتباه هستند:

• اسکیمای دیتابیس (۴.۱ تا ۴.۴) — به ۴ زون و ۳ نوع سرویس به‌روز نشده
• فازبندی — باید ۴ فازی باشد نه ۳ فازی
• ادعای «فاز ۱ تکمیل شده» — نادرست، فاز ۰ هنوز در حال اجراست
• فیلدهای مالی — VAT، Warehousing Cost، Domestic Pickup/Delivery غایب

برای اسکیمای دیتابیس، فقط به بخش ۶ Phase0_Proposal.md اعتماد کن.

س: چرا ترکینگ در لاراول است نه وردپرس؟

ج: چون در فاز ۳ قرار است API ترکینگ واقعی (TrackingMore/17track) متصل شود. اگر الان ترکینگ در وردپرس باشد، در فاز ۳ باید تمام داده‌ها به لاراول مهاجرت داده شوند. با ساخت آن در لاراول از ابتدا، در فاز ۳ فقط یک کلاس TrackingSyncService اضافه می‌شود و هیچ چیز دیگر تغییر نمی‌کند. این تصمیم در جلسه با مشتری تأیید شده است.

س: چرا ۴ زون مجزا لازم است؟

ج: فایل اکسل عملیاتی نشان می‌دهد همان کشور برای پارسل و داکیومنت زون‌های متفاوتی دارد. مثلاً:

• افغانستان: پارسل=۷، داکیومنت=۵
• آلبانی: پارسل=۳، داکیومنت=۷
• استرالیا: پارسل=۷، داکیومنت=۶

اگر فقط ۲ زون (export/import) داشته باشیم، موتور قیمت‌گذاری برای DOCUMENTها اشتباه محاسبه می‌کند.

س: چرا ۳ نوع سرویس داریم نه ۲؟

ج: فایل اکسل شیت‌های جداگانه دارد برای DocNor (Document Normal)، DocEco (Document Economy) و Parcel. هر کدام جدول قیمت جداگانه. پس type در shipments باید enum با سه مقدار باشد: DOC_NORMAL, DOC_ECONOMY, PARCEL.

س: کدام فایل اکسل عملیاتی است؟

ج: دو فایل:

• 4_5989927490271846355.xlsx — فایل اصلی عملیاتی شرکت با شیت‌های Form, List, COUNTRIES, AWB, INVOICE + label, label, Import Rate, Export Rate, Zone, DocNor, Parcel, DocEco, Assumptions, DATES
• Data entry 2026-06-28.xlsx — فایل ترکینگ دستی روزانه با شیت‌های Sheet1, Refrence, Paste, copy, Delivered, test

برای تحلیل کامل هر شیت، فایل EXCEL_ANALYSIS.md را بخوان.

س: مهاجرت داده‌های تاریخی چقدر مهم است؟

ج: بسیار مهم. ۳۹۵۰ رکورد در شیت List وجود دارد از سال ۲۰۲۰ تا الان. این داده‌ها باید به جدول shipments مهاجرت داده شوند. بدون این کار، مشتریان قدیمی نمی‌توانند تاریخچه ببینند و اعتماد به سیستم جدید کاهش می‌یابد.

س: آیا باید VPS پل را در فاز ۰ راه‌اندازی کنم؟

ج: خیر. VPS پل مخصوص فاز ۳ است. در فاز ۰ ترکینگ کاملاً دستی است (اپراتور در پنل Filament رویداد اضافه می‌کند). اما اسکیمای دیتابیس باید به‌گونه‌ای باشد که در فاز ۳ بتوان به‌سادگی API را اضافه کرد (به فیلد source در shipment_tracking_events و last_synced_at در shipment_carrier_mappings دقت کن).

س: مشتری چه انتظاری از فاز ۰ دارد؟

ج: مشتری در جلسه صراحتاً گفت: «اول سایت بالا بیاید و ترکینگ دستی حل شود، بقیه بعد.» یعنی: ۱. وب‌سایت وردپرس کامل آنلاین شود ۲. مشتری نهایی بتواند با کد AWB، تایم‌لاین ترکینگ را ببیند ۳. اپراتور به‌جای اکسل، از پنل Filament استفاده کند

این سه هدف، حداقل قابل‌قبول برای تحویل فاز ۰ است.

س: اگر باگی دیدم یا مشکل پیدا کردم چه کنم؟

ج: اول EXCEL_ANALYSIS.md و بخش «ریسک‌ها» در Phase0_Proposal.md را چک کن. اگر حل نشد، در گزارش کار (worklog) توضیح بده و به توسعه‌دهنده اصلی (Kazem) اطلاع بده.

---

🛠️ Quick Commands — دستورات پرکاربرد

نصب و راه‌اندازی لاراول

cd 04_Laravel
composer install
cp .env.example .env
php artisan key:generate
php artisan migrate
php artisan db:seed --class=CountrySeeder
php artisan serve

ایجاد Model + Migration + Resource (Filament)

php artisan make:model Shipment -m
php artisan make:filament-resource Shipment

ایجاد API Controller

php artisan make:controller Api/TrackController --api

اجرای تست

php artisan test
php artisan serve  # سپس در مرورگر: http://localhost:8000/api/track/980103619

مهاجرت داده‌های تاریخی (یک‌بار)

php artisan ifnex:migrate-historical-data
# این دستور باید ساخته شود — اسکریپت مخصوص خواندن شیت List اکسل

پشتیبان‌گیری از دیتابیس (هر روز)

mysqldump -u root -p ifnex > backups/ifnex_$(date +%Y%m%d).sql

---

📂 ساختار پوشه‌های پروژه (پس از تکمیل فاز ۰)

ifnex/
├── 01_Documents/
│   ├── STATUS.md                  ⭐ این فایل — اول بخوان
│   ├── Phase0_Proposal.md         ⭐ مرجع اصلی پروژه
│   ├── EXCEL_ANALYSIS.md          ⭐ تحلیل فایل‌های اکسل
│   ├── PRD_v2.md                  (قدیمی — مرجع تاریخی)
│   ├── Project_Roadmap.md         (قدیمی — مرجع تاریخی)
│   └── AI_AGENT_GUIDE.md          (راهنمای مخصوص AI Agents — اختیاری)
│
├── 02_Design/
│   └── Assets/                    (لوگوها، آیکون‌ها، فایل‌های فیگما)
│
├── 03_WordPress/
│   └── wp-content/plugins/
│       └── ifnex-bridge/          (پلاگین اختصاصی)
│           ├── ifnex-bridge.php
│           ├── includes/
│           │   ├── api-client.php
│           │   ├── shortcodes.php
│           │   └── tracking-form.php
│           └── assets/
│               ├── css/
│               └── js/
│
├── 04_Laravel/
│   ├── app/
│   │   ├── Models/
│   │   │   ├── Country.php
│   │   │   ├── Shipment.php
│   │   │   ├── ShipmentCarrierMapping.php
│   │   │   ├── ShipmentTrackingEvent.php
│   │   │   ├── SystemSetting.php
│   │   │   └── User.php
│   │   ├── Services/
│   │   │   ├── TrackingService.php         (فاز ۰)
│   │   │   ├── PriceCalculatorService.php  (فاز ۱)
│   │   │   └── TrackingSyncService.php     (فاز ۳)
│   │   ├── Http/Controllers/Api/
│   │   │   └── TrackController.php
│   │   ├── Imports/
│   │   │   ├── ShippingRatesImport.php     (فاز ۱)
│   │   │   └── HistoricalShipmentsImport.php (فاز ۰)
│   │   └── Filament/
│   │       └── Resources/
│   │           ├── CountryResource.php
│   │           ├── ShipmentResource.php
│   │           └── Pages/
│   │               └── AddTrackingEvent.php  (UX اختصاصی اپراتور)
│   ├── database/
│   │   ├── migrations/
│   │   └── seeders/
│   │       └── CountrySeeder.php
│   ├── routes/api.php
│   ├── config/
│   │   └── ifnex.php                       (تنظیمات اختصاصی)
│   └── .env.example
│
├── README.md                                (نسخه به‌روز ۲)
└── .gitignore

---

🎯 گام بعدی برای ادامه‌ی کار

اگر نمونه‌ی جدیدی از AI Agent هستی که می‌خواهی کار را ادامه دهی، این مراحل را به ترتیب برو:

۱. این فایل (STATUS.md) را کامل بخوان — حالا خواندی ✅ ۲. EXCEL_ANALYSIS.md را کامل بخوان — برای فهم داده‌های تاریخی ضروری است ۳. Phase0_Proposal.md را کامل بخوان — مرجع اصلی پروژه ۴. README.md ریشه را بخوان — برای نمای کلی ۵. کد موجود در 04_Laravel را بررسی کن — ببین چه چیزی نوشته شده ۶. با کاربر (Kazem) هماهنگ کن — بپرس کدام کار را باید ادامه دهی

سپس کار را ادامه بده. موفق باشی! 🚀

---

📞 تماس

• توسعه‌دهنده اصلی: Kazem Alghasi (VernaSoft Group)
• مشتری: شرکت IFNEX اصفهان
• مخزن: https://www.git.vernahost.ir/gitmodir110/ifnex

اگر سوالی داشتی که در این فایل یا EXCEL_ANALYSIS.md یا Phase0_Proposal.md پاسخ آن نبود، از کاربر بپرس — حدس نزن.

---

© 2026 VernaSoft Group. Internal use only.