ifnex/01_Documents/PRD_v2.md

⚠️ هشدار: این سند قدیمی است و با نقشه‌ی راه جدید (۴ فازی) تناقض دارد.برای آخرین وضعیت، فایل Phase0_Proposal.md را بخوانید.این سند فقط برای مرجع تاریخی نگه داشته شده است.

سند معماری و نیازمندی‌های پروژه IFNEX Logistics (نسخه 2.0)

تاریخ ایجاد: 2023-10-27 (بر اساس جلسات و تحلیل فایل های عملیاتی) نوع پروژه: سیستم ERP لجستیکی و رهگیری محموله (B2B & B2C) توسعه‌دهنده ارشد: [مهندس کاظم القاصی]

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 لاراول و نمایش نتایج ریالی و درهمی