diff --git a/04_Laravel/app/Http/Controllers/Api/StaffOrderController.php b/04_Laravel/app/Http/Controllers/Api/StaffOrderController.php index 9de4c23..a1cf6a1 100644 --- a/04_Laravel/app/Http/Controllers/Api/StaffOrderController.php +++ b/04_Laravel/app/Http/Controllers/Api/StaffOrderController.php @@ -9,6 +9,7 @@ use App\Services\ShipmentReviewService; use Illuminate\Http\JsonResponse; use Illuminate\Http\Request; use Illuminate\Support\Facades\Auth; +use App\Enums\ShipmentStatus; class StaffOrderController extends Controller { diff --git a/04_Laravel/app/Http/Controllers/StaffApiMiddleware.php b/04_Laravel/app/Http/Middleware/StaffApiMiddleware.php similarity index 100% rename from 04_Laravel/app/Http/Controllers/StaffApiMiddleware.php rename to 04_Laravel/app/Http/Middleware/StaffApiMiddleware.php diff --git a/04_Laravel/routes/api.php b/04_Laravel/routes/api.php index 511eb68..4787fd9 100644 --- a/04_Laravel/routes/api.php +++ b/04_Laravel/routes/api.php @@ -12,9 +12,11 @@ use App\Http\Controllers\Api\StaffOrderController; use App\Http\Controllers\Api\TrackController; use App\Http\Controllers\Api\WalletController; use App\Http\Middleware\ApiKeyMiddleware; +use App\Http\Middleware\StaffApiMiddleware; use Illuminate\Support\Facades\Route; use App\Http\Controllers\Api\AuthController; use App\Http\Controllers\Api\BridgeAuthController; +use App\Http\Controllers\ShipmentPdfController; // ══════════════════════════════════════════════════════════════ @@ -97,7 +99,7 @@ Route::middleware(['auth:sanctum'])->prefix('v1')->group(function () { }); // ─── Staff Orders API (تأیید سفارشات) ─── - Route::middleware([\App\Http\Middleware\StaffApiMiddleware::class]) + Route::middleware([StaffApiMiddleware::class]) ->prefix('staff') ->group(function () { diff --git a/IFNEX_Logistics_Review_Workflow_HANDOFF.md b/IFNEX_Logistics_Review_Workflow_HANDOFF.md new file mode 100644 index 0000000..3740574 --- /dev/null +++ b/IFNEX_Logistics_Review_Workflow_HANDOFF.md @@ -0,0 +1,635 @@ +# IFNEX Logistics — Review Workflow & Continuation Handoff + +## وضعیت پروژه + +مسیر Laravel: +`C:\xampp\htdocs\IFNEX-Logistics\04_Laravel` + +هدف فعلی: تکمیل Client Delivery و Hardening؛ سپس Productization. + +--- + +## 1. Review Architecture + +Review از Shipment Operational Status جدا شده است. + +Review State: +- `pending` +- `changes_requested` +- `approved` +- `rejected` + +جریان: + +```text +Create Order + -> review_state=pending / status=pending_approval + -> Staff Review + -> Request Changes -> Customer Edit -> Resubmit -> pending + -> Approve -> review_state=approved / status=approved + -> Reject -> review_state=rejected / status=cancelled +``` + +Review History با مدل `ShipmentReview` و revision مستقل نگهداری می‌شود و جایگزین `ShipmentStatusHistory` نیست. + +--- + +## 2. وضعیت Filament + +در لیست مرسولات Actionها ساخته و تست شده‌اند: + +- نمایش +- ویرایش +- تأیید +- درخواست اصلاح +- رد سفارش + +Approve تست شده: +- Dialog تأیید نمایش داده شد. +- پیام موفقیت نمایش داده شد. +- Status به `Approved` تغییر کرد. +- Actionهای Review از ردیف حذف شدند. +- مشتری پس از تأیید وارد مرحله پرداخت می‌شود. + +Reject نیز تست شده: +- با موفقیت انجام شد. +- عنوان/وضعیت به «رد شد» تغییر کرد. +- Actionهای Review حذف شدند. + +Request Changes هنوز باید از API و End-to-End تست شود. + +--- + +## 3. APIهای Staff Review + +در `routes/api.php` این مسیرها وجود دارند: + +```text +GET /api/v1/staff/orders/pending-approval +POST /api/v1/staff/orders/{shipment}/request-changes +POST /api/v1/staff/orders/{shipment}/approve +POST /api/v1/staff/orders/{shipment}/reject +``` + +این گروه با: + +```php +\App\Http\Middleware\StaffApiMiddleware::class +``` + +محافظت می‌شود. + +--- + +## 4. Authorization + +User از Spatie Permission استفاده می‌کند. + +Roleهای مهم: +- `super_admin` +- `admin` +- `staff` +- `customer` + +تست‌ها: + +Customer با Token معتبر -> `403 Forbidden` + +Super Admin -> دسترسی موفق. + +User شماره 1: +- name: مدیر کاظم +- role: `super_admin` +- Spatie role: `super_admin` + +--- + +## 5. Pending Approval API — موفق + +Endpoint: + +```text +GET /api/v1/staff/orders/pending-approval +``` + +با Super Admin و Bearer Token تست شد و: + +```text +HTTP/1.1 200 OK +``` + +برگشت. + +یک Shipment فعلی در پاسخ: + +```text +id = 22 +awb_no = IFN-2026-39337 +status.value = pending_approval +review.state = pending +``` + +API شامل: +- shipment id +- AWB +- direction/type +- status +- review +- from/to country +- user +- weight +- chargeable_weight +- total_fee +- created_at +- created_at_jalali +- pagination + +است. + +--- + +## 6. مشکل ShipmentStatus — حل شد + +در `StaffOrderController.php` این import اضافه/اصلاح شده: + +```php +use App\Enums\ShipmentStatus; +``` + +و: + +```php +->where('status', ShipmentStatus::PendingApproval) +``` + +ابتدا خطای: + +```text +Class "App\Http\Controllers\Api\ShipmentStatus" not found +``` + +وجود داشت. + +بعد از اصلاح، Tinker تأیید کرد: + +```php +\App\Enums\ShipmentStatus::PendingApproval +``` + +و: + +```text +value = pending_approval +``` + +پس این مشکل حل شده است. + +--- + +## 7. ShipmentStatus.php + +فایل: + +`app\Enums\ShipmentStatus.php` + +Enum شامل statusهای اصلی است: + +```text +pending_approval +approved +pending_payment +cancelled +processed +picked_up +in_transit +out_for_delivery +failed +delivered +returned +archived +``` + +متدهای مهم: + +```php +isApproved() +isPendingApproval() +canBeApprovedByStaff() +canBePaid() +``` + +انتهای فایل بررسی شد و `canBeApprovedByStaff()` و `canBePaid()` به‌درستی بسته شده‌اند. + +--- + +## 8. مشکل ShipmentPdfController — حل شد + +`route:list` ابتدا به علت نبود import صحیح برای `ShipmentPdfController` خطا می‌داد. + +فایل واقعی: + +`app\Http\Controllers\ShipmentPdfController.php` + +Namespace: + +```php +namespace App\Http\Controllers; +``` + +پس import صحیح باید بر اساس همین namespace باشد. + +بعد از اصلاح، این دستور موفق شد: + +```powershell +php artisan route:list --path=api/v1/staff +``` + +و 6 route نشان داده شد: +- customers/search +- customers/{customer}/financial-status +- orders/pending-approval +- orders/{shipment}/approve +- orders/{shipment}/reject +- orders/{shipment}/request-changes + +--- + +## 9. مشکل PSR-4 — هنوز حل نشده + +این دستور دو فایل پیدا کرده: + +```powershell +Get-ChildItem .\app -Recurse -Filter "StaffApiMiddleware.php" | Select-Object FullName +``` + +نتیجه: + +```text +app\Http\Controllers\StaffApiMiddleware.php +app\Http\Middleware\StaffApiMiddleware.php +``` + +Composer هشدار می‌دهد: + +```text +Class App\Http\Middleware\StaffApiMiddleware located in +./app/Http/Controllers/StaffApiMiddleware.php +does not comply with psr-4 autoloading standard. +``` + +بنابراین باید قبل از هر چیز دو فایل را مقایسه کنیم. + +### قدم بعدی دقیق + +اجرا: + +```powershell +Get-Content .\app\Http\Controllers\StaffApiMiddleware.php +``` + +و: + +```powershell +Get-Content .\app\Http\Middleware\StaffApiMiddleware.php +``` + +سپس: + +```powershell +Select-String -Path .\app\**\*.php -Pattern "StaffApiMiddleware" +``` + +هدف: +1. مشخص شود کدام فایل Middleware واقعی است. +2. بررسی شود فایل Controllers duplicate است یا خیر. +3. فقط پس از تأیید، duplicate حذف شود. +4. سپس: + +```powershell +composer dump-autoload +``` + +و هشدار PSR-4 دیگر نباید ظاهر شود. + +--- + +## 10. پاک‌سازی‌ها + +این‌ها با موفقیت اجرا شده‌اند: + +```powershell +php artisan optimize:clear +composer dump-autoload +``` + +Composer package discovery و Filament upgrade نیز موفق بوده‌اند. + +--- + +## 11. PowerShell + +نوشتن: + +```text +GET /api/v1/staff/orders/pending-approval +``` + +مستقیم در PowerShell اشتباه است؛ PowerShell آن را command تلقی می‌کند. + +برای تست HTTP: + +```powershell +curl.exe -i ` + -H "Authorization: Bearer YOUR_TOKEN" ` + -H "Accept: application/json" ` + http://127.0.0.1:8000/api/v1/staff/orders/pending-approval +``` + +--- + +## 12. Token + +یک Token تستی برای Super Admin ساخته و استفاده شد. Token واقعی را در این فایل ثبت نکرده‌ایم. + +برای ادامه، در صورت نیاز Token جدید بساز و Token تستی را credential دائمی تلقی نکن. + +--- + +## 13. StaffOrderController + +فایل: + +`app\Http\Controllers\Api\StaffOrderController.php` + +متدهای اصلی: + +```text +pendingApproval() +requestChanges() +approve() +reject() +formatShipment() +toJalali() +``` + +Business logic Review به: + +```text +ShipmentReviewService +``` + +سپرده شده و نباید منطق اصلی Review را داخل Controller کپی کنیم. + +--- + +## 14. تست‌های بعدی + +### A — Request Changes + +```text +POST /api/v1/staff/orders/{shipment}/request-changes +``` + +نمونه: + +```json +{ + "reason": "لطفاً اطلاعات گیرنده اصلاح شود.", + "notes": "شماره تماس کامل نیست." +} +``` + +انتظار: +- `review_state = changes_requested` +- ایجاد Review History +- سفارش قابل ویرایش/Resubmit باشد. + +### B — Approve API + +```text +POST /api/v1/staff/orders/{shipment}/approve +``` + +انتظار: + +```text +review_state = approved +status = approved +``` + +### C — Reject API + +```text +POST /api/v1/staff/orders/{shipment}/reject +``` + +با reason اجباری. + +انتظار: + +```text +review_state = rejected +status = cancelled +``` + +### D — Customer Resubmit + +پس از Request Changes: +- Customer دلیل اصلاح را ببیند. +- سفارش را اصلاح کند. +- Resubmit کند. +- Review State دوباره `pending` شود. +- revision جدید ایجاد شود. +- AWB تغییر نکند. +- Shipment/Packages/Items transactional به‌روزرسانی شوند. + +--- + +## 15. API Contract + +Laravel منبع canonical Order Detail API است. + +ساختار هدف: + +```text +shipment +├── status +├── review +├── sender +├── receiver +├── packages[] +├── items[] +├── financial +├── documents[] +└── tracking_events[] +``` + +WordPress باید این contract را مصرف کند، نه اینکه روی flattened legacy fields تکیه کند. + +Mismatchهای شناخته‌شده: + +Laravel: +```text +sender.* +receiver.* +``` + +WordPress قدیمی: +```text +sender_name +sender_phone +receiver_name +receiver_phone +``` + +Tracking: + +Laravel: +```text +date +description +location +``` + +WordPress: +```text +event_date +event_description +event_time +``` + +--- + +## 16. موارد Hardening شناخته‌شده + +1. `ShipmentStatus::isPaid()` از نظر semantic امن نیست. +2. `Shipment::isDelivered()` باید از نظر Enum/string بررسی شود. +3. Staff authorization باید صریح و role-aware بماند. +4. Sender/receiver API contract باید یکسان شود. +5. Tracking event contract باید یکسان شود. +6. PDF token key باید با Bridge token استاندارد هماهنگ شود. +7. Commitment Form requirement باید برای Shipment snapshot شود. +8. Signed-document upload باید از public storage semantics خارج/harden شود. +9. `ShipmentPackage` و `ShipmentItem` در detailed customer response بررسی شوند. +10. Payment state نباید در بلندمدت از Shipment status استنتاج شود. +11. Preview pricing و committed pricing باید تفکیک شوند. +12. Migrationهای تاریخی rewrite نشوند. + +--- + +## 17. Payment Architecture + +هدف نهایی: + +```text +Shipment Operational Status +Review State +Payment State +``` + +سه domain مستقل. + +فعلاً: + +```text +Approved -> payment available +``` + +اما این coupling باید در معماری نهایی حذف/deprecate شود. + +--- + +## 18. Commitment Documents + +`CommitmentForm` = template + +`ShipmentCommitmentForm` = requirement/instance برای Shipment + +برای Client فعلی: +- physical delivery فرآیند اصلی است. +- online upload اختیاری است. +- signed document نباید بدون business policy صریح approval/payment را block کند. + +هدف بعدی: snapshot شدن required documents برای هر Shipment. + +--- + +## 19. Finance Boundary + +IFNEX نباید accounting system کامل شود. + +حوزه مالی IFNEX: +- wallet +- receivable/debt +- order financial status +- payment transactions +- credit/settlement +- audit trail + +Accounting عمیق در صورت نیاز باید external integration باشد. + +--- + +## 20. End-to-End هدف + +```text +Customer creates order + ↓ +Pending Approval + ↓ +Staff Review + ┌────┼─────┐ + ↓ ↓ ↓ +Changes Approve Reject + ↓ +Customer Edit + ↓ +Resubmit + ↓ +Pending Approval + ↓ +Approve + ↓ +Payment +``` + +--- + +## 21. ترتیب ادامه کار + +1. مقایسه دو `StaffApiMiddleware.php`. +2. رفع duplicate/PSR-4 warning. +3. `composer dump-autoload`. +4. `php artisan route:list --path=api/v1/staff`. +5. تست Pending Approval مجدد. +6. تست Request Changes API. +7. تست Approve API. +8. تست Reject API. +9. بررسی `ShipmentReviewService` و `ShipmentReview`. +10. تست Customer Resubmit. +11. بررسی Customer Order Detail API. +12. هماهنگ‌سازی WordPress Bridge با Laravel canonical contract. +13. تست End-to-End کامل. +14. سپس سایر Hardeningهای Client Delivery. + +--- + +## 22. پیام شروع پیشنهادی برای چت جدید + +```text +ما روی پروژه IFNEX-Logistics کار می‌کنیم. +فایل IFNEX_Logistics_Review_Workflow_HANDOFF.md را مبنا قرار بده. + +آخرین وضعیت: +GET /api/v1/staff/orders/pending-approval با super_admin موفقاً HTTP 200 می‌دهد. +Approve و Reject در Filament تست شده‌اند. +Request Changes و Resubmit هنوز باید تست شوند. + +اولین کار: +دو فایل زیر را مقایسه کنیم و PSR-4 warning را بدون خراب کردن Middleware واقعی رفع کنیم: + +app\Http\Controllers\StaffApiMiddleware.php +app\Http\Middleware\StaffApiMiddleware.php + +بعد APIهای request-changes / approve / reject و customer resubmit را تست کنیم. +```