diff --git a/01_Documents/PRD_v2.md b/01_Documents/PRD_v2.md index 66c689a..65d8499 100644 --- a/01_Documents/PRD_v2.md +++ b/01_Documents/PRD_v2.md @@ -2,10 +2,237 @@ -سند معماری و نیازمندی‌های پروژه IFNEX Logistics (نسخه 2.0) +# ⚠️ سند قدیمی — فقط برای مرجع تاریخی + +> **وضعیت:** این سند به‌طور کامل **منسوخ** شده و جزو مرجع رسمی پروژه **نیست**. +> **مرجع اصلی:** `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) فعالیت می‌کند. هدف این پروژه، تبدیل فرآیندهای فعلی مبتنی بر فایل‌های اکسل به یک سیستم وب‌اپلیکیشن یکپارچه برای ثبت سفارش، محاسبه آنلاین قیمت، صدور بارنامه/لیبل، رهگیری یکپارچه و مدیریت مالی (کیف پول) است. diff --git a/01_Documents/Project_Roadmap.md b/01_Documents/Project_Roadmap.md index bb50858..2480c68 100644 --- a/01_Documents/Project_Roadmap.md +++ b/01_Documents/Project_Roadmap.md @@ -1,52 +1,94 @@ -⚠️ هشدار: این سند قدیمی است و با نقشه‌ی راه جدید (۴ فازی) تناقض دارد.برای آخرین وضعیت، فایل Phase0_Proposal.md را بخوانید.این سند فقط برای مرجع تاریخی نگه داشته شده است. +# ⚠️ هشدار: این سند قدیمی است و با نقشه‌ی راه جدید (۴ فازی) تناقض دارد. +> **وضعیت:** این سند به‌طور کامل **منسوخ** شده و جزو مرجع رسمی پروژه **نیست**. +> **مرجع اصلی:** `Phase0_Proposal.docx` و `STATUS.md` و `IFNEX_Phase0_Checklist.md` +> **تاریخ آخرین به‌روزرسانی:** 2026-08-04 +> +> 🔴 **قانون طلایی:** هرگاه بین این سند و اسناد جدید تناقض دیدی، به `STATUS.md` و `Phase0_Proposal.docx` اعتماد کن. +> +> این فایل فقط برای فهمیدن **تاریخچه تصمیمات** نگه داشته شده است. از آن برای پیاده‌سازی استفاده **نکنید**. +--- -نقشه راه و چک‌لیست پروژه IFNEX (Task List) -فاز ۱: انتقال از اکسل به دیتابیس و زیرساخت اولیه (در حال انجام) -زیرساخت و دیتابیس - نصب لاراول ۱۱ و آماده‌سازی محیط لوکال - طراحی و ساخت Migration ها (4 جدول اصلی) - ساخت مدل‌های (Models) لاراول - سیدر (Seeder) کشورها -پنل مدیریت (فیلمنت) - نصب و تنظیمات اولیه فیلمنت - ساخت Resource برای کشورها - ساخت Resource برای تعرفه‌ها (با زون‌های ۱ تا ۱۰) - ساخت Resource برای سفارشات (با فرم Repeater برای اقلام گمرکی) - اضافه کردن دکمه آپلود اکسل در پنل تعرفه‌ها -ماژول‌های دیتای پایه - ماژول ایمپورت اکسل تعرفه‌ها (با توجه به ساختار پیچیده اکسل اصلی) - (پنت) ماژول ایمپورت اکسل سفارشات قدیمی (شیت List) - فرم تنظیمات نرخ ارز و ضریب سود (نظام پولی) -منطق تجاری (Business Logic) - موتور محاسبه قیمت (Pricing Engine Service) - تست موتور قیمت‌گذاری در پنل ادمین -ارتباطات و API - تنظیمات CORS در لاراول ۱۲ - ساخت API استعلام قیمت (api/calculate-price) - ساخت پلاگین اختصاصی در وردپرس - ساخت شورت‌کد فرم استعلام قیمت در وردپرس - (پنت) داینامیک کردن لیست کشورها در فرم وردپرس (گرفتن لیست از API و پر کردن Select ها) -اسناد و فرم‌ها (بخش GUI) - (پنت) ساخت بارنامه PDF (Waybill) دقیقاً مشابه شیت AWB اکسل - (پنت) ساخت فاکتور PDF (Invoice) مشابه شیت INVOICE اکسل - (پنت) ساخت لیبل چاپی PDF (Label) مشابه شیت label اکسل - (پنت) فرم رهگیری اولیه در وردپرس (استایل دارک مود با تایم‌لاین) - (پنت) اتصال فرم رهگیری به API لاراول (استعلام وضعیت از دیتابیس) -فاز ۲: اتوماسیون مالی و رقابت‌پذیری - (پنت) اتصال به درگاه پرداخت (مثل زرین‌پال) - (پنت) ایجاد جدول کیف پول (wallets) و تراکنش‌ها (transactions) - (پنت) شارژ اعتبار آنلاین توسط کاربر - (پنت) شارژ اعتبار دستی توسط ادمین (تایید واریز تلفنی) - (پنت) کرون‌جاب (Cron Job) برای بروزرسانی روزانه نرخ ارز از API - (پنت) سیستم کوپن و تخفیف‌ها - (پنت) فرمول محاسبه قیمت رقبا و نمایش جدول مقایسه‌ای به کاربر -فاز ۳: رهگیری زنده و عملیات (Operations) - (پنت) راه‌اندازی سرور VPS خارج از کشور (پل ارتباطی) - (پنت) اتصال به API رهگیری (پیشنهاد: TrackingMore) - (پنت) ایجاد سیستم دریافت وب‌هوک (Webhook) از سرویس رهگیری - (پنت) مپ کردن کدهای رهگیری (کد IFNEX به کد DHL/FedEx) - (پنت) ساخت داشبورد مالی ساده در پنل ادمین (سود و زیان خالص) - (پنت) فرم نظرسنجی و رضایت مشتری - (پنت) ساخت پنل کاربری مشتریان در وردپرس (لیست سفارشات، بارنامه‌ها) +# نقشه راه و چک‌لیست پروژه IFNEX (Task List) + +> ⚠️ این فایل ۳ فازی دارد. پروژه حالا ۴ فازی است. برای چک‌لیست دقیق و به‌روز، `IFNEX_Phase0_Checklist.md` را بخوانید. + +--- + +## فاز ۰: بنیان داده + وب‌سایت + ترکینگ دستی + مهاجرت داده‌های تاریخی (در حال اجرا) + +### زیرساخت و دیتابیس +- [x] نصب لاراول ۱۱ و آماده‌سازی محیط لوکال +- [x] طراحی و ساخت Migration ها (۷ جدول اصلی) +- [x] ساخت مدل‌های (Models) لاراول + ۶ Enum +- [x] سیدر (Seeder) کشورها (۲۳۲ کشور با ۴ زون) +- [x] سیدر System Settings (VAT 9%, packing 100000 IRR) +- [x] سیدر Super Admin User + +### پنل مدیریت (فیلمنت) +- [x] نصب و تنظیمات اولیه فیلمنت 3.3 +- [x] ساخت Resource برای کشورها +- [x] ساخت Resource برای shipments +- [x] ساخت Resource برای تعرفه‌ها (با ۱۰ zone + enum type/direction) +- [x] ساخت Resource برای shipment_items +- [x] RelationManagers برای CarrierMappings و TrackingEvents +- [x] SettingsPage برای System Settings + +### ماژول‌های دیتای پایه +- [x] ماژول ایمپورت اکسل تعرفه‌ها (۴۰۴ رکورد import شد) +- [x] ماژول ایمپورت اکسل سفارشات قدیمی (شیت List) — ۱ رکورد موفق (بلاک: فایل اکسل فرمول دارد) +- [x] فرم تنظیمات نرخ ارز و ضریب سود (نظام پولی) + +### منطق تجاری (Business Logic) +- [x] موتور محاسبه قیمت (PriceCalculatorService) +- [ ] تست موتور قیمت‌گذاری در پنل ادمین + +### ارتباطات و API +- [x] تنظیمات CORS در لاراول ۱۱ +- [x] ساخت API ترکینگ (`GET /api/v1/track/{awb_no}`) +- [ ] ساخت API استعلام قیمت (`POST /api/calculate-price`) — فاز ۱ +- [ ] ساخت پلاگین اختصاصی در وردپرس — فاز ۰/۱ +- [ ] ساخت شورت‌کد فرم رهگیری در وردپرس — فاز ۰/۱ + +### اسناد و فرم‌ها (بخش GUI) +- [ ] ساخت بارنامه PDF (Waybill) دقیقاً مشابه شیت AWB اکسل — فاز ۱ +- [ ] ساخت فاکتور PDF (Invoice) مشابه شیت INVOICE اکسل — فاز ۱ +- [ ] ساخت لیبل چاپی PDF (Label) مشابه شیت label اکسل — فاز ۱ +- [ ] فرم رهگیری اولیه در وردپرس (استایل دارک مود با تایم‌لاین) — فاز ۰/۱ +- [ ] اتصال فرم رهگیری به API لاراول — فاز ۰/۱ + +--- + +## فاز ۱: موتور قیمت‌گذاری کامل + ثبت سفارش آنلاین + تولید PDFها (در صف) + +- [ ] موتور قیمت‌گذاری کامل (PriceCalculatorService) — نوشته شد، نیاز به تست با داده‌های واقعی +- [ ] جدول `shipping_rates` با نرخ‌های Import/Export — ۴۰۴ رکورد import شد +- [ ] فرم ثبت سفارش آنلاین با ۹ ردیف کالای گمرکی +- [ ] تولید PDF: AWB، INVOICE، Label مطابق قالب اکسل +- [ ] ماژول ایمپورت اکسل تعرفه‌ها +- [ ] صفحه استعلام قیمت واقعی + +--- + +## فاز ۲: اتوماسیون مالی و رقابت‌پذیری (در صف) + +- [ ] اتصال به درگاه پرداخت (مثل زرین‌پال) +- [ ] ایجاد جدول کیف پول (wallets) و تراکنش‌ها (transactions) +- [ ] شارژ اعتبار آنلاین توسط کاربر +- [ ] شارژ اعتبار دستی توسط ادمین (تایید واریز تلفنی) +- [ ] کرون‌جاب (Cron Job) برای بروزرسانی روزانه نرخ ارز از API +- [ ] سیستم کوپن و تخفیف‌ها +- [ ] فرمول محاسبه قیمت رقبا و نمایش جدول مقایسه‌ای به کاربر + +--- + +## فاز ۳: رهگیری زنده و عملیات (Operations) (در صف) + +- [ ] راه‌اندازی سرور VPS خارج از کشور (پل ارتباطی) +- [ ] اتصال به API رهگیری (پیشنهاد: TrackingMore) +- [ ] ایجاد سیستم دریافت وب‌هوک (Webhook) از سرویس رهگیری +- [ ] مپ کردن کدهای رهگیری (کد IFNEX به کد DHL/FedEx) +- [ ] ساخت داشبورد مالی ساده در پنل ادمین (سود و زیان خالص) +- [ ] فرم نظرسنجی و رضایت مشتری +- [ ] ساخت پنل کاربری مشتریان در وردپرس (لیست سفارشات، بارنامه‌ها) diff --git a/04_Laravel/README.md b/04_Laravel/README.md index 0165a77..8a67064 100644 --- a/04_Laravel/README.md +++ b/04_Laravel/README.md @@ -1,59 +1,119 @@ -

Laravel Logo

+# IFNEX Logistics — Backend (Laravel 11) -

-Build Status -Total Downloads -Latest Stable Version -License -

+> بخش بک‌اند سیستم لجستیک ایف‌نکس. این پوشه به تنهایی یک اپلیکیشن لاراول ۱۱ کامل است. -## About Laravel +--- -Laravel is a web application framework with expressive, elegant syntax. We believe development must be an enjoyable and creative experience to be truly fulfilling. Laravel takes the pain out of development by easing common tasks used in many web projects, such as: +## 🚀 راه‌اندازی سریع -- [Simple, fast routing engine](https://laravel.com/docs/routing). -- [Powerful dependency injection container](https://laravel.com/docs/container). -- Multiple back-ends for [session](https://laravel.com/docs/session) and [cache](https://laravel.com/docs/cache) storage. -- Expressive, intuitive [database ORM](https://laravel.com/docs/eloquent). -- Database agnostic [schema migrations](https://laravel.com/docs/migrations). -- [Robust background job processing](https://laravel.com/docs/queues). -- [Real-time event broadcasting](https://laravel.com/docs/broadcasting). +```bash +composer install +cp .env.example .env +php artisan key:generate +php artisan migrate --force +php artisan db:seed --force +php artisan serve +``` -Laravel is accessible, powerful, and provides tools required for large, robust applications. +--- -## Learning Laravel +## 📦 پکیج‌های اصلی -Laravel has the most extensive and thorough [documentation](https://laravel.com/docs) and video tutorial library of all modern web application frameworks, making it a breeze to get started with the framework. You can also check out [Laravel Learn](https://laravel.com/learn), where you will be guided through building a modern Laravel application. +| پکیج | نسخه | نقش | +|------|------|-----| +| `laravel/framework` | ^11.0 | هسته فریم‌ورک | +| `filament/filament` | 3.3.* | پنل مدیریت ادمین | +| `maatwebsite/excel` | ^3.1 | ایمپورت اکسل | +| `morilog/jalali` | ^3.0 | تبدیل تاریخ شمسی/میلادی | -If you don't feel like reading, [Laracasts](https://laracasts.com) can help. Laracasts contains thousands of video tutorials on a range of topics including Laravel, modern PHP, unit testing, and JavaScript. Boost your skills by digging into our comprehensive video library. +--- -## Laravel Sponsors +## 📁 ساختار کد -We would like to extend our thanks to the following sponsors for funding Laravel development. If you are interested in becoming a sponsor, please visit the [Laravel Partners program](https://partners.laravel.com). +``` +04_Laravel/ +├── app/ +│ ├── Models/ # مدل‌های Eloquent +│ ├── Enums/ # Enumهای سفارشی +│ ├── Services/ # منطق تجاری +│ ├── Http/ +│ │ ├── Controllers/ # کنترلرها +│ │ ├── Middleware/ # میان‌افزارهای سفارشی +│ │ └── Requests/ # Form Request Validation +│ ├── Imports/ # کلاس‌های ایمپورت اکسل +│ ├── Console/Commands/ # دستورات Artisan سفارشی +│ └── Filament/ # پنل مدیریت +│ ├── Resources/ # منابع Filament +│ └── Pages/ # صفحات سفارشی +├── database/ +│ ├── migrations/ # ۷ migration فاز ۰ +│ └── seeders/ # seeders داده اولیه +├── routes/ +│ ├── web.php # routes وب (Filament) +│ └── api.php # routes API +└── config/ + ├── ifnex.php # تنظیمات اختصاصی + └── cors.php # تنظیمات CORS +``` -### Premium Partners +--- -- **[Vehikl](https://vehikl.com)** -- **[Tighten Co.](https://tighten.co)** -- **[Kirschbaum Development Group](https://kirschbaumdevelopment.com)** -- **[64 Robots](https://64robots.com)** -- **[Curotec](https://www.curotec.com/services/technologies/laravel)** -- **[DevSquad](https://devsquad.com/hire-laravel-developers)** -- **[Redberry](https://redberry.international/laravel-development)** -- **[Active Logic](https://activelogic.com)** +## 🔌 API Endpoints -## Contributing +| روش | مسیر | توضیحات | +|------|------|---------| +| GET | `/api/v1/track/{awb_no}` | استعلام وضعیت مرسوله با API Key | -Thank you for considering contributing to the Laravel framework! The contribution guide can be found in the [Laravel documentation](https://laravel.com/docs/contributions). +**درخواست نمونه:** +```bash +curl -H "Authorization: Bearer ifnex-local-dev-key" http://localhost:8000/api/v1/track/TEST123 +``` -## Code of Conduct +--- -In order to ensure that the Laravel community is welcoming to all, please review and abide by the [Code of Conduct](https://laravel.com/docs/contributions#code-of-conduct). +## 🛠️ دستورات Artisan سفارشی -## Security Vulnerabilities +```bash +# ایمپورت نرخ‌های حمل از اکسل +php artisan ifnex:import:rates {path} -If you discover a security vulnerability within Laravel, please send an e-mail to Taylor Otwell via [taylor@laravel.com](mailto:taylor@laravel.com). All security vulnerabilities will be promptly addressed. +# ایمپورت داده‌های تاریخی مرسوله‌ها +php artisan ifnex:import:shipments {path} +``` -## License +--- -The Laravel framework is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT). +## 🔐 احراز هویت و دسترسی + +| نقش | دسترسی | +|------|--------| +| `super_admin` | دسترسی کامل به همه بخش‌های Filament | +| `tracking_operator` | مدیریت ترکینگ و رویدادها | +| `data_entry` | وارد کردن داده‌های مرسوله | +| `customer` | دسترسی محدود (در فاز بعدی) | + +--- + +## ⚠️ نکات مهم + +- **Laravel 11** — با سوییچ از v12 انجام شد +- **Livewire 3.8.3** — فرم‌ها با AJAX کار می‌کنند، POST مستقیم به `/admin/login` ثبت نمی‌شود +- **Filament 3.3.x** — پنل مدیریت در مسیر `/admin` +- **MySQL 8+** — الزام migrations با JSON columns + +--- + +## 📚 مستندات بیشتر + +برای اطلاعات کامل‌تر به پوشه `01_Documents` در ریشه پروژه مراجعه کنید: +- `STATUS.md` — وضعیت فعلی و گزارش پیشرفت +- `IFNEX_Phase0_Checklist.md` — چک‌لیست دقیق فاز ۰ +- `Phase0_Proposal.md` — مرجع اصلی پروژه + +--- + +## 📜 لایسنس + +© 2026 VernaSoft Group (Kazem Alghasi). All rights reserved. + +این پروژه اختصاصی شرکت IFNEX است و کپی یا استفاده‌ی غیرمجاز از آن ممنوع است. diff --git a/README.md b/README.md index ce0f9e8..f7765a3 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ | مورد | توضیحات | | :--- | :--- | -| **ویرایش سند** | v2.0 (نقشه راه ۴ فازی) | +| **ویرایش سند** | v3.0 (بازبینی شده — Laravel 11 + Filament 3.3 + مهاجرت اولیه داده‌های تاریخی) | | **توسعه‌دهنده** | VernaSoft Group — Kazem Alghasi | | **مشتری** | شرکت حمل و نقل بین‌المللی ایف‌نکس (IFNEX) — اصفهان | @@ -23,7 +23,7 @@ | لایه | تکنولوژی | نقش | | :--- | :--- | :--- | | **فرانت‌اند** | WordPress | مدیریت ظاهر، منوها، لندینگ پیج‌ها، صفحات ثابت، وبلاگ سئو | -| **بک‌اند** | Laravel 11 | API سرور، پنل ادمین (Filament)، موتور قیمت‌گذاری، صدور PDF، کیف پول | +| **بک‌اند** | Laravel 11 | API سرور، پنل ادمین (Filament 3.3)، موتور قیمت‌گذاری، صدور PDF، کیف پول | | **پل ارتباطی** | پلاگین اختصاصی IFNEX Bridge | ارسال درخواست‌های کاربر از وردپرس به لاراول | | **زیرساخت رهگیری** | VPS خارج از کشور (در فاز ۳) | واسط برای دسترسی به APIهای رهگیری بین‌المللی | @@ -74,8 +74,11 @@ ```text IFNEX-Logistics/ ├── 01_Documents/ # مستندات فنی پروژه -│ ├── PRD_v2.md # سند نیازمندی‌ها (نسخه قدیمی — به‌زودی بازنویسی) +│ ├── STATUS.md # ⭐ وضعیت فعلی و گزارش پیشرفت +│ ├── IFNEX_Phase0_Checklist.md # ⭐ چک‌لیست دقیق فاز ۰ │ ├── Phase0_Proposal.md # ⭐ سند پیشنهاد فاز ۰ (نقشه راه جدید) +│ ├── EXCEL_ANALYSIS.md # ⭐ تحلیل فایل‌های اکسل +│ ├── PRD_v2.md # سند نیازمندی‌ها (نسخه قدیمی — به‌زودی بازنویسی) │ └── Project_Roadmap.md # نقشه راه و چک‌لیست (به‌زودی به‌روزرسانی) │ ├── 02_Design/ # فایل‌های UI/UX و فیگما @@ -88,14 +91,27 @@ IFNEX-Logistics/ └── 04_Laravel/ # هسته مرکزی سیستم (بک‌اند) ├── app/ │ ├── Models/ # Country, Shipment, ShipmentTrackingEvent, ... - │ ├── Services/ # PriceCalculatorService (فاز ۱), TrackingService - │ ├── Http/Controllers/Api/ # TrackController, PricingController, ... + │ ├── Enums/ # ShipmentDirection, ShipmentType, ShipmentStatus, ... + │ ├── Services/ # TrackingService, PriceCalculatorService + │ ├── Http/ + │ │ ├── Controllers/Api/ # TrackController + │ │ ├── Middleware/ # ApiKeyMiddleware + │ │ └── Requests/ # Form Request Validation classes │ ├── Imports/ # ShippingRatesImport, HistoricalShipmentsImport │ └── Filament/ # پنل مدیریت ادمین + │ ├── Resources/ # Country, Shipment, ShippingRate, ShipmentItem + │ └── Pages/ # Settings, Dashboard, Custom pages ├── database/ - │ ├── migrations/ # جداول دیتابیس - │ └── seeders/ # داده‌های اولیه (۲۳۳ کشور) - └── config/ # تنظیمات سیستم + │ ├── migrations/ # ۷ migration فاز ۰ + │ └── seeders/ # CountriesSeeder, SystemSettingSeeder + ├── routes/ + │ ├── web.php + │ └── api.php + ├── config/ + │ ├── ifnex.php + │ └── cors.php + └── bootstrap/ + └── app.php 🚀 راه‌اندازی و اجرا (Localhost) @@ -120,10 +136,10 @@ cp .env.example .env php artisan key:generate # ۵. اجرای Migration ها -php artisan migrate +php artisan migrate --force # ۶. درج داده‌های اولیه (کشورها و نرخ ارز اولیه) -php artisan db:seed +php artisan db:seed --force # ۷. اجرای سرور توسعه php artisan serve @@ -149,7 +165,10 @@ php artisan serve برای مطالعه دقیق منطق‌های سیستم، حتماً فایل‌های داخل پوشه 01_Documents را مطالعه کنید: فایل محتوا +STATUS.md ⭐ وضعیت فعلی، گزارش پیشرفت، خط قرمزها و راهنمایی‌های توسعه بعدی +IFNEX_Phase0_Checklist.md ⭐ چک‌لیست دقیق تمام کارهای فاز ۰ با وضعیت هر آیتم Phase0_Proposal.md ⭐ سند پیشنهاد فاز ۰ — شامل اسکیمای دیتابیس، جدول زمانی، ریسک‌ها، معیارهای پذیرش +EXCEL_ANALYSIS.md ⭐ تحلیل کامل فایل‌های اکسل عملیاتی و ساختار داده‌های تاریخی PRD_v2.md سند نیازمندی‌ها (نسخه قدیمی — برخی بخش‌های آن در سند فاز ۰ بازنویسی شده) Project_Roadmap.md چک‌لیست کارهای انجام‌شده و در دست اقدام (به‌زودی به‌روزرسانی می‌شود) 🔐 امنیت و گزارش مشکلات @@ -158,4 +177,4 @@ Project_Roadmap.md چک‌لیست کارهای انجام‌شده و در دس 📜 لایسنس © 2026 VernaSoft Group (Kazem Alghasi). All rights reserved. -این پروژه اختصاصی شرکت IFNEX است و کپی یا استفاده‌ی غیرمجاز از آن ممنوع است. \ No newline at end of file +این پروژه اختصاصی شرکت IFNEX است و کپی یا استفاده‌ی غیرمجاز از آن ممنوع است.