285acdae89
Update project documentation to reflect the completion of Phase 0 and Phase 1, and the commencement of Phase 2. This includes archiving obsolete documents, updating the README with a new architectural overview, and refining the project checklist and status reports. - Archive obsolete PRD and Roadmap documents - Update `IFNEX_Phase0_Checklist.md` with completed tasks and Phase 2 roadmap - Update `STATUS.md` with recent development progress for August 2026 - Refactor `04_Laravel/README.md` to include detailed technical specifications and architecture diagrams - Update root `README.md` with updated versioning and system architecture visualization - Refine `PriceCalculatorServiceTest.php` to align with updated service output structures
371 lines
28 KiB
Markdown
371 lines
28 KiB
Markdown
⚠️ هشدار: این سند قدیمی است و با نقشهی راه جدید (۴ فازی) تناقض دارد.برای آخرین وضعیت، فایل Phase0_Proposal.md را بخوانید.این سند فقط برای مرجع تاریخی نگه داشته شده است.
|
||
|
||
|
||
|
||
# ⚠️ سند قدیمی — فقط برای مرجع تاریخی
|
||
|
||
> **وضعیت:** این سند بهطور کامل **منسوخ** شده و جزو مرجع رسمی پروژه **نیست**.
|
||
> **مرجع اصلی:** `Phase0_Proposal.docx` و `STATUS.md` و `IFNEX_Phase0_Checklist.md`
|
||
> **تاریخ آخرین بهروزرسانی:** 2026-08-04
|
||
>
|
||
> 🔴 **قانون طلایی:** هرگاه بین این سند و اسناد جدید تناقض دیدی، به `STATUS.md` و `Phase0_Proposal.docx` اعتماد کن.
|
||
>
|
||
> این فایل فقط برای فهمیدن **تاریخچه تصمیمات** نگه داشته شده است. از آن برای پیادهسازی استفاده **نکنید**.
|
||
|
||
---
|
||
|
||
# سند معماری و نیازمندیهای پروژه IFNEX Logistics (نسخه 2.0)
|
||
|
||
تاریخ ایجاد: 2023-10-27 (بر اساس جلسات و تحلیل فایل های عملیاتی) نوع پروژه: سیستم ERP لجستیکی و رهگیری محموله (B2B & B2C) توسعهدهنده ارشد: [مهندس کاظم القاصی]
|
||
|
||
---
|
||
|
||
## ⚠️ بخشهای منسوخ این سند
|
||
|
||
### ۱. اسکیمای دیتابیس (بخش ۴) — کاملاً منسوخ
|
||
اسکیمای دیتابیس در این سند **نادرست** است. اسکیمای صحیح در `Phase0_Proposal.docx` و `IFNEX_Phase0_Checklist.md` ثبت شده:
|
||
|
||
| جدول در این سند | وضعیت | جدول صحیح |
|
||
|-----------------|-------|-----------|
|
||
| `countries` با ۲ زون | ❌ غلط | `countries` با ۴ زون مجزا |
|
||
| `shipments` با `forwarder_track_id` | ❌ غلط | `shipment_carrier_mappings` جداگانه |
|
||
| `shipments` با `status` String | ❌ غلط | `ShipmentStatus` Enum |
|
||
| عدم وجود `shipment_tracking_events` | ❌ غلط | جدول جدید برای تایملاین |
|
||
| عدم وجود `system_settings` | ❌ غلط | جدول جدید برای VAT، نرخ ارز |
|
||
| `type` با ۲ مقدار (DOCUMENT/NON DOC) | ❌ غلط | ۳ مقدار: DOC_NORMAL, DOC_ECONOMY, PARCEL |
|
||
|
||
### ۲. فازبندی (بخش ۶) — منسوخ
|
||
این سند ۳ فازی دارد. پروژه حالا **۴ فازی** است:
|
||
- فاز ۰: بنیان داده + ترکینگ دستی + مهاجرت دادههای تاریخی
|
||
- فاز ۱: موتور قیمتگذاری + PDF + فرم سفارش
|
||
- فاز ۲: اتوماسیون مالی
|
||
- فاز ۳: VPS پل + API ترکینگ زنده
|
||
|
||
### ۳. نسخه لاراول (بخش ۲) — منسوخ
|
||
در این سند نوشته «Laravel 10+». نسخه نهایی و قفلشده: **Laravel 11** (در `composer.json` و `STATUS.md` تنظیم شده).
|
||
|
||
### ۴. گزارش پیشرفت (بخش ۸) — نادرست
|
||
ادعای «فاز ۱ تکمیل شده» **نادرست** است. فاز ۰ هنوز در حال اجراست.
|
||
|
||
### ۵. فیلدهای مالی — غایب
|
||
فیلدهای زیر در این سند ذکر نشده بودند ولی در اسکیمای نهایی اضافه شدند:
|
||
- `vat_rate` (9%)
|
||
- `packing_cost_default` (100,000 IRR)
|
||
- `domestic_pickup`, `domestic_delivery`, `warehousing_cost`
|
||
- `extra_service` (نیاز به ذخیره در `shipment_carrier_mappings.notes`)
|
||
|
||
---
|
||
|
||
## ۱. چشمانداز کلی پروژه
|
||
ایفنکس (IFNEX) یک شرکت حمل و نقل بینالمللی مستقر در اصفهان است که به عنوان واسطه (رابط) بین مشتریان ایرانی و شرکتهای بزرگ حمل (DHL, FedEx, UPS) فعالیت میکند. هدف این پروژه، تبدیل فرآیندهای فعلی مبتنی بر فایلهای اکسل به یک سیستم وباپلیکیشن یکپارچه برای ثبت سفارش، محاسبه آنلاین قیمت، صدور بارنامه/لیبل، رهگیری یکپارچه و مدیریت مالی (کیف پول) است.
|
||
|
||
## ۲. معماری فنی (Tech Stack & Architecture)
|
||
سیستم به صورت Headless (بدون سر) طراحی شده است. وردپرس تنها نقش ظاهری دارد و لاراول قلب تپنده سیستم است.
|
||
|
||
فرانتاند (WordPress):
|
||
وظیفه: لندینگ پیج (طراحی شده مشابه DHL - لایت مود)، مقالات SEO، صفحات ثابت.
|
||
پلاگینها: صفحهساز (Elementor)، Polylang (چند زبانه).
|
||
ممنوعیت: هیچگونه پردازش دیتای سفارش، فرمهای سفارش یا رهگیری نباید در وردپرس انجام شود.
|
||
بکاند (Laravel 11):
|
||
وظیفه: API سرور، پنل ادمین، پنل کاربری، موتور قیمتگذاری، صدور PDF، کیف پول، حسابداری پایه.
|
||
محل پروژه: C:\xampp\htdocs\IFNEX-Logistics\04_Laravel
|
||
زیرساخت رهگیری (VPS Bridge):
|
||
به دلیل تحریمها و مسدود بودن APIهای رهگیری از آیپی ایران، یک سرور VPS خارج از کشور (هلند/آلمان) به عنوان پل ارتباطی با سرویسهایی مثل TrackingMore یا 17track تنظیم میشود.
|
||
سیستم رهگیری کراولر پایتون:
|
||
وضعیت: منسوخ شده. سیستم قبلی پایتون کار نمیکند. رهگیری در فاز اول به صورت دستی توسط اپراتور در پنل لاراول انجام میشود و در فازهای بعدی از طریق API پل VPS انجام میشود.
|
||
|
||
## ۳. منطق کسبوکار استخراج شده از فایل اکسل (Business Logic)
|
||
۳.۱. منطق قیمتگذاری (Pricing Engine)
|
||
قیمتگذاری بر اساس فرمول زیر (استخراج شده از شیت Form اکسل) انجام میشود:قیمت نهایی (ریال) = قیمت پایه (درهم) * ضریب سود (Percent - مثلاً 1.25) * نرخ روز درهم (ریال) + هزینههای جانبی - تخفیف
|
||
|
||
قیمت پایه: از جداول Import Rate و Export Rate استخراج میشود.
|
||
پارامترهای تاثیرگذار روی قیمت پایه:
|
||
جهت (Direction): صادرات (Outbound) یا واردات (Inbound).
|
||
نوع (Type): DOCUMENT (مدارک) یا NON DOC (بسته/کالا).
|
||
وزن قابل پرداخت (Chargeable Weight): ماکزیموم بین "وزن واقعی" و "وزن حجمی".
|
||
زون (Zone): بر اساس کشور مقصد/مبدا (استخراج شده از شیت COUNTRIES اکسل).
|
||
نکته: محمولههای بالای 30 کیلوگرم مشمول نرخهای ویژه (Spot Rate) هستند و محاسبه آنلاین ندارند و باید توسط ادمین تایید شوند.
|
||
۳.۲. منطق رهگیری (Tracking Mapping)
|
||
شرکت ایفنکس به مشتری یک کد یکتای اختصاصی (مثلاً IFN-525) میدهد. اما ممکن است بسته از طریق DHL با کد 65986555 ارسال شود.
|
||
|
||
در جدول دیتابیس، هر سفارش دارای awb_no (کد ایفنکس) و carrier_tracking_number (کد شرکت خارجی) است.
|
||
مشتری همیشه با کد ایفنکس جستجو میکند، اما سیستم در پسزمینه وضعیت را بر اساس کد خارجی (در آینده از طریق API) استعلام میکند.
|
||
|
||
## ٤. ساختار دیتابیس (Database Schema - فاز ۰/۱)
|
||
⚠️ این بخش منسوخ است. اسکیمای صحیح در `Phase0_Proposal.docx` و `IFNEX_Phase0_Checklist.md` آمده است.
|
||
|
||
۴.۱. جدول countries (منبع: شیت COUNTRIES + Zone)
|
||
id (PK)
|
||
name (String) - مثلا: United States (US)
|
||
iso_code (String) - مثلا: US
|
||
export_zone_parcel (Integer) - زون صادرات پارسل (1 تا 10)
|
||
export_zone_doc (Integer) - زون صادرات داکیومنت (1 تا 10)
|
||
import_zone_parcel (Integer) - زون واردات پارسل (1 تا 10)
|
||
import_zone_doc (Integer) - زون واردات داکیومنت (1 تا 10)
|
||
is_active (Boolean)
|
||
۴.۲. جدول shipping_rates (منبع: شیتهای Import/Export Rate)
|
||
id (PK)
|
||
direction (Enum: 'import', 'export')
|
||
type (Enum: 'DOC_NORMAL', 'DOC_ECONOMY', 'PARCEL')
|
||
weight (Decimal) - وزن (مثلا 0.5)
|
||
zone_1 تا zone_10 (Decimal) - قیمت پایه به درهم
|
||
۴.۳. جدول shipments (منبع: شیتهای List و Form) - جدول اصلی
|
||
id (PK)
|
||
user_id (FK) - ارتباط با کاربر ثبتکننده
|
||
awb_no (String, Unique) - شماره بارنامه ایفنکس (مثل 980100011)
|
||
direction (Enum: 'export', 'import')
|
||
type (Enum: 'DOC_NORMAL', 'DOC_ECONOMY', 'PARCEL')
|
||
status (Enum: processed/picked_up/in_transit/out_for_delivery/failed/delivered/returned)
|
||
--- اطلاعات وزن ---
|
||
weight (Decimal)
|
||
volumetric_weight (Decimal)
|
||
chargeable_weight (Decimal)
|
||
dimensions (String) - مثال: 25153
|
||
--- اطلاعات مالی ---
|
||
shipping_price (Decimal)
|
||
extra_service (Decimal, default: 0)
|
||
packing_cost (Decimal, default: 0)
|
||
domestic_pickup (Decimal, default: 0)
|
||
domestic_delivery (Decimal, default: 0)
|
||
warehousing_cost (Decimal, default: 0)
|
||
discount (Decimal, default: 0)
|
||
vat_rate (Decimal, default: 0.09)
|
||
total_fee (Decimal)
|
||
net_dirham (Decimal)
|
||
net_rial (Decimal)
|
||
--- اطلاعات فرستنده (Sender) ---
|
||
sender_name, sender_company, sender_phone, sender_email, sender_address, sender_city, sender_zip, sender_id_number
|
||
--- اطلاعات گیرنده (Receiver) ---
|
||
receiver_name, receiver_company, receiver_phone, receiver_email, receiver_address, receiver_city, receiver_zip, receiver_id_number
|
||
--- سایر ---
|
||
content_description (String)
|
||
reason_for_export (String)
|
||
--- تایماستمپها ---
|
||
created_at, updated_at
|
||
۴.۴. جدول shipment_items (منبع: ۹ ردیف کالای گمرکی در اکسل)
|
||
id (PK)
|
||
shipment_id (FK -> shipments.id)
|
||
row_number (TinyInt) - شماره ردیف (1 تا 9)
|
||
description (String) - توضیح کالا
|
||
hs_code (String) - کد گمرکی
|
||
quantity (Integer)
|
||
unit_price (Decimal)
|
||
total_usd (Decimal)
|
||
۴.۵. جدول shipment_carrier_mappings (جدول جدید)
|
||
id (PK)
|
||
shipment_id (FK -> shipments.id)
|
||
carrier_code (Enum: DHL/FEDEX/UPS/ARAMEX/NAGHEL/EMX/APSITEX/IMPEX/OTHER)
|
||
carrier_tracking_number (String)
|
||
booking_number (String, Nullable)
|
||
delivery_status (String, Nullable)
|
||
notes (String, Nullable) - هزینههای جانبی متغیر
|
||
source (Enum: manual/api_carrier/api_aggregator)
|
||
last_synced_at (Timestamp, Nullable)
|
||
created_at, updated_at
|
||
۴.۶. جدول shipment_tracking_events (جدول جدید)
|
||
id (PK)
|
||
shipment_id (FK -> shipments.id)
|
||
event_date (Date)
|
||
event_time (Time, Nullable)
|
||
event_description (String)
|
||
location (String, Nullable)
|
||
delivery_status (String, Nullable)
|
||
source (Enum: manual/api_carrier/api_aggregator)
|
||
created_at, updated_at
|
||
۴.۷. جدول system_settings (جدول جدید)
|
||
id (PK)
|
||
key (String, Unique)
|
||
value (Text)
|
||
type (String)
|
||
description (Text, Nullable)
|
||
created_at, updated_at
|
||
|
||
## ۵. ساختار پوشههای پروژه (Localhost)
|
||
مسیر اصلی: C:\xampp\htdocs\IFNEX-Logistics
|
||
|
||
├── 01_Documents/│ └── PRD_v2.md (همین فایل - منسوخ)├── 02_Design/│ └── Assets/ (لوگوها و فایلهای فیگما)├── 03_WordPress/│ └── (فایلهای وردپرس در آینده اینجا قرار میگیرند)└── 04_Laravel/ └── (پروژه لاراول در اینجا نصب خواهد شد)
|
||
|
||
## ۶. نقشه راه اجرایی (Roadmap - ۴ فاز - منسوخ)
|
||
⚠️ این نقشهی راه ۳ فازی است. پروژه حالا ۴ فازی دارد. برای نقشهی راه جدید، `Phase0_Proposal.docx` را بخوانید.
|
||
|
||
فاز ۰: بنیان داده + وبسایت + ترکینگ دستی + مهاجرت دادههای تاریخی
|
||
نصب لاراول ۱۱ و ساخت جداول بالا (Migrations).
|
||
ساخت پنل ادمین سریع (ترجیحاً با Laravel Filament).
|
||
نوشتن اسکریپت ایمپورت اکسل (ماژول ادمین برای آپلود شیت List قدیمی).
|
||
پیادهسازی موتور قیمتگذاری بر اساس فرمول استخراج شده.
|
||
فرم ثبت سفارش (صادرات/واردات) شامل ۹ ردیف کالای گمرکی.
|
||
تولید فایلهای PDF (بارنامه AWB و فاکتور INVOICE دقیقاً با چیدمان اکسل).
|
||
رهگیری دستی توسط اپراتور در پنل ادمین.
|
||
فاز ۱: اتوماسیون مالی
|
||
اتصال به درگاه پرداخت و ایجاد کیف پول کاربران.
|
||
سیستم شارژ آنلاین و تایید واریز تلفنی توسط ادمین.
|
||
کرونجاب برای بروزرسانی روزانه نرخ ارز (درهم، دلار، یوان، یورو).
|
||
سیستم کوپن تخفیف.
|
||
نمایش مقایسهگر قیمت (قیمت ایفنکس در مقابل قیمت پایه رقبا).
|
||
فاز ۲: رهگیری زنده و عملیات (Operations)
|
||
راهاندازی سرور VPS خارج از کشور (پل ارتباطی).
|
||
اتصال به API رهگیری (TrackingMore یا مشابه آن) از طریق VPS.
|
||
تولید لیبل چاپی (Label PDF) مخصوص چاپگرهای حرارتی دفتر اصفهان.
|
||
داشبورد گزارشگیری مالی (سود و زیان خالص).
|
||
|
||
## ٧. دستورالعملهای ویژه برای AI Agent
|
||
اگر شما یک AI Agent هستید که در حال کمک به کدنویسی این پروژه هستید، رعایت موارد زیر الزامی است:
|
||
|
||
کدهای وردپرس و لاراول کاملاً مجزا هستند. هرگز تو لاراول کدی برای ساخت HTML لندینگ ننویسید و برعکس.
|
||
فرمول قیمتگذاری باید دقیقاً مطابق بخش 3.1 این سند پیادهسازی شود.
|
||
فیلدهای دیتابیس نباید تغییر کنند مگر اینکه با کاربر هماهنگ شده باشد. نامها باید دقیقاً مطابق Schema بخش 4 باشند.
|
||
برای فرمها از فرمتهای Validation استاندارد لاراول استفاده کنید. (مثلاً کد پستی، شماره موبایل ایرانی).
|
||
خروجی PDF باید انگلیسی باشد (مانند فایل اکسل اصلی)، اما رابط کاربری پنل ادمین و فرانتاند فارسی است.
|
||
⚠️ هشدار برای AI Agent: این سند منسوخ است. برای اسکیمای دیتابیس، حتماً `Phase0_Proposal.docx` و `IFNEX_Phase0_Checklist.md` را مطالعه کنید.
|
||
|
||
## ٨. گزارش پیشرفت فاز ۱ (تکمیل شده در جلسه فعلی) — منسوخ
|
||
⚠️ این بخش ادعاهای نادرست دارد. برای گزارش پیشرفت واقعی، `STATUS.md` را بخوانید.
|
||
|
||
در این جلسه، هسته مرکزی سیستم به طور کامل در لاراول پیادهسازی شد و ارتباط اولیه با وردپرس برقرار گردید. کارهای انجام شده شامل موارد زیر است:
|
||
|
||
توسعه دیتابیس: ساخت جداول countries, shipping_rates, shipments, shipment_items با دقیقترین جزئیات استخراج شده از فایل اکسل عملیاتی.
|
||
پنل مدیریت فیلمنت (Filament): ساخت پنل ادمین مدرن برای مدیریت منابع (Resources).
|
||
دادههای پایه: سیدر (Seeder) کشورها (233 کشور با زونهای صادرات/واردات).
|
||
ماژول ایمپورت اکسل تعرفهها: ایجاد دکمه آپلود در پنل ادمین و کلاس ShippingRatesImport برای خواندن خودکار شیتهای Import/Export اکسل و درجور در دیتابیس (حل مشکل دیسکهای لاراول ۱۲ توسط توسعهدهنده).
|
||
تنظیمات سیستم: ساخت جدول system_settings و فرم مدیریت نرخ ارز (درهم، دلار، یوان، یورو) و ضریب سود.
|
||
موتور قیمتگذاری (Pricing Engine): ساخت کلاس PriceCalculatorService شامل محاسبه وزن حجمی (فرمول /5000)، انتخاب زون، استخراج قیمت پایه از دیتابیس، اعمال نرخ ارز و ضریب سود.
|
||
API لاراول: ساخت PricingController و تعریف مسیر api/calculate-price برای پاسخگویی به درخواستهای فرانتاند.
|
||
پلاگین وردپرس (IFNEX Bridge): ایجاد ساختار اولیه پلاگین مستقل از قالب در وردپرس.
|
||
شورتکد استعلام قیمت: ساخت [ifnex_price_checker] با فرم ظاهری زیبا و کد جاوااسکریپت برای اتصال به API لاراول و نمایش نتایج ریالی و درهمی
|
||
|
||
|
||
1. چشمانداز کلی پروژه
|
||
ایفنکس (IFNEX) یک شرکت حمل و نقل بینالمللی مستقر در اصفهان است که به عنوان واسطه (رابط) بین مشتریان ایرانی و شرکتهای بزرگ حمل (DHL, FedEx, UPS) فعالیت میکند. هدف این پروژه، تبدیل فرآیندهای فعلی مبتنی بر فایلهای اکسل به یک سیستم وباپلیکیشن یکپارچه برای ثبت سفارش، محاسبه آنلاین قیمت، صدور بارنامه/لیبل، رهگیری یکپارچه و مدیریت مالی (کیف پول) است.
|
||
|
||
2. معماری فنی (Tech Stack & Architecture)
|
||
سیستم به صورت Headless (بدون سر) طراحی شده است. وردپرس تنها نقش ظاهری دارد و لاراول قلب تپنده سیستم است.
|
||
|
||
فرانتاند (WordPress):
|
||
وظیفه: لندینگ پیج (طراحی شده مشابه DHL - لایت مود)، مقالات SEO، صفحات ثابت.
|
||
پلاگینها: صفحهساز (Elementor)، Polylang (چند زبانه).
|
||
ممنوعیت: هیچگونه پردازش دیتای سفارش، فرمهای سفارش یا رهگیری نباید در وردپرس انجام شود.
|
||
بکاند (Laravel 10+):
|
||
وظیفه: API سرور، پنل ادمین، پنل کاربری، موتور قیمتگذاری، صدور PDF، کیف پول، حسابداری پایه.
|
||
محل پروژه: C:\xampp\htdocs\IFNEX-Logistics\04_Laravel
|
||
زیرساخت رهگیری (VPS Bridge):
|
||
به دلیل تحریمها و مسدود بودن APIهای رهگیری از آیپی ایران، یک سرور VPS خارج از کشور (هلند/آلمان) به عنوان پل ارتباطی با سرویسهایی مثل TrackingMore یا 17track تنظیم میشود.
|
||
سیستم رهگیری کراولر پایتون:
|
||
وضعیت: منسوخ شده. سیستم قبلی پایتون کار نمیکند. رهگیری در فاز اول به صورت دستی توسط اپراتور در پنل لاراول انجام میشود و در فازهای بعدی از طریق API پل VPS انجام میشود.
|
||
|
||
3. منطق کسبوکار استخراج شده از فایل اکسل (Business Logic)
|
||
۳.۱. منطق قیمتگذاری (Pricing Engine)
|
||
قیمتگذاری بر اساس فرمول زیر (استخراج شده از شیت Form اکسل) انجام میشود:قیمت نهایی (ریال) = قیمت پایه (درهم) * ضریب سود (Percent - مثلاً 1.25) * نرخ روز درهم (ریال) + هزینههای جانبی - تخفیف
|
||
|
||
قیمت پایه: از جداول Import Rate و Export Rate استخراج میشود.
|
||
پارامترهای تاثیرگذار روی قیمت پایه:
|
||
جهت (Direction): صادرات (Outbound) یا واردات (Inbound).
|
||
نوع (Type): DOCUMENT (مدارک) یا NON DOC (بسته/کالا).
|
||
وزن قابل پرداخت (Chargeable Weight): ماکزیموم بین "وزن واقعی" و "وزن حجمی".
|
||
زون (Zone): بر اساس کشور مقصد/مبدا (استخراج شده از شیت COUNTRIES اکسل).
|
||
نکته: محمولههای بالای 30 کیلوگرم مشمول نرخهای ویژه (Spot Rate) هستند و محاسبه آنلاین ندارند و باید توسط ادمین تایید شوند.
|
||
۳.۲. منطق رهگیری (Tracking Mapping)
|
||
شرکت ایفنکس به مشتری یک کد یکتای اختصاصی (مثلاً IFN-525) میدهد. اما ممکن است بسته از طریق DHL با کد 65986555 ارسال شود.
|
||
|
||
در جدول دیتابیس، هر سفارش دارای awb_no (کد ایفنکس) و forwarder_track_id (کد شرکت خارجی) است.
|
||
مشتری همیشه با کد ایفنکس جستجو میکند، اما سیستم در پسزمینه وضعیت را بر اساس کد خارجی (در آینده از طریق API) استعلام میکند.
|
||
|
||
4. ساختار دیتابیس (Database Schema - فاز ۱)
|
||
جداول زیر بر اساس تحلیل دقیق فایل اکسل عملیاتی طراحی شدهاند:
|
||
|
||
4.1. جدول countries (منبع: شیت COUNTRIES)
|
||
id (PK)
|
||
name (String) - مثلا: United States (US)
|
||
export_zone (Integer) - زون صادرات (1 تا 10)
|
||
import_zone (Integer) - زون واردات (1 تا 10)
|
||
4.2. جدول shipping_rates (منبع: شیتهای Import/Export Rate)
|
||
id (PK)
|
||
direction (Enum: 'import', 'export')
|
||
type (Enum: 'DOCUMENT', 'NON DOC')
|
||
weight (Decimal) - وزن (مثلا 0.5)
|
||
zone_1 تا zone_10 (Decimal) - قیمت پایه به درهم
|
||
4.3. جدول shipments (منبع: شیتهای List و Form) - جدول اصلی
|
||
id (PK)
|
||
user_id (FK) - ارتباط با کاربر ثبتکننده
|
||
awb_no (String, Unique) - شماره بارنامه ایفنکس (مثل 980100011)
|
||
forwarder (String, Nullable) - نام شرکت حمل (DHL, FedEx, null برای داخلی)
|
||
forwarder_track_id (String, Nullable) - کد رهگیری شرکت خارجی
|
||
direction (Enum: 'Outbound', 'Inbound')
|
||
type (Enum: 'DOC', 'NON DOC')
|
||
status (String) - وضعیت (Processed, Shipped, Delivered)
|
||
reason_for_export (String) - دلیل ارسال (گمرکی)
|
||
--- اطلاعات وزن ---
|
||
weight (Decimal)
|
||
volumetric_weight (Decimal)
|
||
chargeable_weight (Decimal)
|
||
dimensions (String) - مثلا: 25153
|
||
--- اطلاعات مالی ---
|
||
shipping_price (Decimal)
|
||
extra_service (Decimal, default: 0)
|
||
packing_cost (Decimal, default: 0)
|
||
discount (Decimal, default: 0)
|
||
total_fee (Decimal)
|
||
net_dirham (Decimal)
|
||
net_rial (Decimal)
|
||
--- اطلاعات فرستنده (Sender) ---
|
||
sender_name, sender_company, sender_phone, sender_email, sender_address, sender_city, sender_zip, sender_id_number
|
||
--- اطلاعات گیرنده (Receiver) ---
|
||
receiver_name, receiver_company, receiver_phone, receiver_email, receiver_address, receiver_city, receiver_zip, receiver_id_number
|
||
--- تایماستمپها ---
|
||
created_at, updated_at
|
||
4.4. جدول shipment_items (منبع: ۹ ردیف کالای گمرکی در اکسل)
|
||
id (PK)
|
||
shipment_id (FK -> shipments.id)
|
||
row_number (TinyInt) - شماره ردیف (1 تا 9)
|
||
description (String) - توضیح کالا
|
||
hs_code (String) - کد گمرکی
|
||
quantity (Integer)
|
||
unit_price (Decimal)
|
||
total_usd (Decimal)
|
||
|
||
5. ساختار پوشههای پروژه (Localhost)
|
||
مسیر اصلی: C:\xampp\htdocs\IFNEX-Logistics
|
||
|
||
├── 01_Documents/│ └── PRD_v2.md (همین فایل)├── 02_Design/│ └── Assets/ (لوگوها و فایلهای فیگما)├── 03_WordPress/│ └── (فایلهای وردپرس در آینده اینجا قرار میگیرند)└── 04_Laravel/ └── (پروژه لاراول در اینجا نصب خواهد شد)
|
||
|
||
6. نقشه راه اجرایی (Roadmap - ۳ فاز)
|
||
فاز ۱: انتقال از اکسل به دیتابیس (اولویت فعلی)
|
||
نصب لاراول و ساخت جداول بالا (Migrations).
|
||
ساخت پنل ادمین سریع (ترجیحاً با Laravel Filament).
|
||
نوشتن اسکریپت ایمپورت اکسل (ماژول ادمین برای آپلود شیت List قدیمی).
|
||
پیادهسازی موتور قیمتگذاری بر اساس فرمول استخراج شده.
|
||
فرم ثبت سفارش (صادرات/واردات) شامل ۹ ردیف کالای گمرکی.
|
||
تولید فایلهای PDF (بارنامه AWB و فاکتور INVOICE دقیقاً با چیدمان اکسل).
|
||
رهگیری دستی توسط اپراتور در پنل ادمین.
|
||
فاز ۲: اتوماسیون مالی
|
||
اتصال به درگاه پرداخت و ایجاد کیف پول کاربران.
|
||
سیستم شارژ آنلاین و تایید واریز تلفنی توسط ادمین.
|
||
کرونجاب برای بروزرسانی روزانه نرخ ارز (درهم، دلار، یوان، یورو).
|
||
سیستم کوپن تخفیف.
|
||
نمایش مقایسهگر قیمت (قیمت ایفنکس در مقابل قیمت پایه رقبا).
|
||
فاز ۳: عملیات و رهگیری زنده
|
||
راهاندازی VPS پل ارتباطی.
|
||
اتصال به API رهگیری (TrackingMore یا مشابه آن) از طریق VPS.
|
||
تولید لیبل چاپی (Label PDF) مخصوص چاپگرهای حرارتی دفتر اصفهان.
|
||
داشبورد گزارشگیری مالی (سود و زیان خالص).
|
||
|
||
7. دستورالعملهای ویژه برای AI Agent
|
||
اگر شما یک AI Agent هستید که در حال کمک به کدنویسی این پروژه هستید، رعایت موارد زیر الزامی است:
|
||
|
||
کدهای وردپرس و لاراول کاملاً مجزا هستند. هرگز تو لاراول کدی برای ساخت HTML لندینگ ننویسید و برعکس.
|
||
فرمول قیمتگذاری باید دقیقاً مطابق بخش 3.1 این سند پیادهسازی شود.
|
||
فیلدهای دیتابیس نباید تغییر کنند مگر اینکه با کاربر هماهنگ شده باشد. نامها باید دقیقاً مطابق Schema بخش 4 باشند.
|
||
برای فرمها از فرمتهای Validation استاندارد لاراول استفاده کنید. (مثلاً کد پستی، شماره موبایل ایرانی).
|
||
خروجی PDF باید انگلیسی باشد (مانند فایل اکسل اصلی)، اما رابط کاربری پنل ادمین و فرانتاند فارسی است.
|
||
|
||
8. گزارش پیشرفت فاز ۱ (تکمیل شده در جلسه فعلی)
|
||
در این جلسه، هسته مرکزی سیستم به طور کامل در لاراول پیادهسازی شد و ارتباط اولیه با وردپرس برقرار گردید. کارهای انجام شده شامل موارد زیر است:
|
||
|
||
توسعه دیتابیس: ساخت جداول countries, shipping_rates, shipments, shipment_items با دقیقترین جزئیات استخراج شده از فایل اکسل عملیاتی.
|
||
پنل مدیریت فیلمنت (Filament): ساخت پنل ادمین مدرن برای مدیریت منابع (Resources).
|
||
دادههای پایه: سیدر (Seeder) کشورها (233 کشور با زونهای صادرات/واردات).
|
||
ماژول ایمپورت اکسل تعرفهها: ایجاد دکمه آپلود در پنل ادمین و کلاس ShippingRatesImport برای خواندن خودکار شیتهای Import/Export اکسل و درجور در دیتابیس (حل مشکل دیسکهای لاراول ۱۲ توسط توسعهدهنده).
|
||
تنظیمات سیستم: ساخت جدول system_settings و فرم مدیریت نرخ ارز (درهم، دلار، یوان، یورو) و ضریب سود.
|
||
موتور قیمتگذاری (Pricing Engine): ساخت کلاس PriceCalculatorService شامل محاسبه وزن حجمی (فرمول /5000)، انتخاب زون، استخراج قیمت پایه از دیتابیس، اعمال نرخ ارز و ضریب سود.
|
||
API لاراول: ساخت PricingController و تعریف مسیر api/calculate-price برای پاسخگویی به درخواستهای فرانتاند.
|
||
پلاگین وردپرس (IFNEX Bridge): ایجاد ساختار اولیه پلاگین مستقل از قالب در وردپرس.
|
||
شورتکد استعلام قیمت: ساخت [ifnex_price_checker] با فرم ظاهری زیبا و کد جاوااسکریپت برای اتصال به API لاراول و نمایش نتایج ریالی و درهمی |