323 lines
20 KiB
Markdown
323 lines
20 KiB
Markdown
# 🚨 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 │
|
||
└─────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## ✅ وضعیت فعلی کار
|
||
|
||
### کارهای انجامشده (تا آخرین بهروزرسانی)
|
||
- [x] تحلیل کامل فایلهای اکسل عملیاتی شرکت
|
||
- [x] شناسایی تناقضات PRD قدیمی با واقعیت اکسل (۴ زون بهجای ۲، ۳ نوع سرویس بهجای ۲، فیلدهای غایب VAT/Packing/Warehousing)
|
||
- [x] تدوین سند `Phase0_Proposal.md` (مرجع اصلی پروژه)
|
||
- [x] بازنگری نقشهی راه از ۳ فازی به ۴ فازی
|
||
- [x] طراحی اسکیمای دیتابیس فاز ۰ (۶ جدول اصلی)
|
||
- [x] بازنویسی `README.md` با ساختار جدید
|
||
- [x] تدوین `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 — دستورات پرکاربرد
|
||
|
||
### نصب و راهاندازی لاراول
|
||
```bash
|
||
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)
|
||
```bash
|
||
php artisan make:model Shipment -m
|
||
php artisan make:filament-resource Shipment
|
||
```
|
||
|
||
### ایجاد API Controller
|
||
```bash
|
||
php artisan make:controller Api/TrackController --api
|
||
```
|
||
|
||
### اجرای تست
|
||
```bash
|
||
php artisan test
|
||
php artisan serve # سپس در مرورگر: http://localhost:8000/api/track/980103619
|
||
```
|
||
|
||
### مهاجرت دادههای تاریخی (یکبار)
|
||
```bash
|
||
php artisan ifnex:migrate-historical-data
|
||
# این دستور باید ساخته شود — اسکریپت مخصوص خواندن شیت List اکسل
|
||
```
|
||
|
||
### پشتیبانگیری از دیتابیس (هر روز)
|
||
```bash
|
||
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.
|