ifnex/IFNEX_Logistics_Review_Workflow_HANDOFF.md

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

جریان:

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 این مسیرها وجود دارند:

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

این گروه با:

\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:

GET /api/v1/staff/orders/pending-approval

با Super Admin و Bearer Token تست شد و:

HTTP/1.1 200 OK

برگشت.

یک Shipment فعلی در پاسخ:

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 اضافه/اصلاح شده:

use App\Enums\ShipmentStatus;

و:

->where('status', ShipmentStatus::PendingApproval)

ابتدا خطای:

Class "App\Http\Controllers\Api\ShipmentStatus" not found

وجود داشت.

بعد از اصلاح، Tinker تأیید کرد:

\App\Enums\ShipmentStatus::PendingApproval

و:

value = pending_approval

پس این مشکل حل شده است.

---

7. ShipmentStatus.php

فایل:

app\Enums\ShipmentStatus.php

Enum شامل statusهای اصلی است:

pending_approval
approved
pending_payment
cancelled
processed
picked_up
in_transit
out_for_delivery
failed
delivered
returned
archived

متدهای مهم:

isApproved()
isPendingApproval()
canBeApprovedByStaff()
canBePaid()

انتهای فایل بررسی شد و canBeApprovedByStaff() و canBePaid() به‌درستی بسته شده‌اند.

---

8. مشکل ShipmentPdfController — حل شد

route:list ابتدا به علت نبود import صحیح برای ShipmentPdfController خطا می‌داد.

فایل واقعی:

app\Http\Controllers\ShipmentPdfController.php

Namespace:

namespace App\Http\Controllers;

پس import صحیح باید بر اساس همین namespace باشد.

بعد از اصلاح، این دستور موفق شد:

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 — هنوز حل نشده

این دستور دو فایل پیدا کرده:

Get-ChildItem .\app -Recurse -Filter "StaffApiMiddleware.php" | Select-Object FullName

نتیجه:

app\Http\Controllers\StaffApiMiddleware.php
app\Http\Middleware\StaffApiMiddleware.php

Composer هشدار می‌دهد:

Class App\Http\Middleware\StaffApiMiddleware located in
./app/Http/Controllers/StaffApiMiddleware.php
does not comply with psr-4 autoloading standard.

بنابراین باید قبل از هر چیز دو فایل را مقایسه کنیم.

قدم بعدی دقیق

اجرا:

Get-Content .\app\Http\Controllers\StaffApiMiddleware.php

و:

Get-Content .\app\Http\Middleware\StaffApiMiddleware.php

سپس:

Select-String -Path .\app\**\*.php -Pattern "StaffApiMiddleware"

هدف:

1. مشخص شود کدام فایل Middleware واقعی است.
2. بررسی شود فایل Controllers duplicate است یا خیر.
3. فقط پس از تأیید، duplicate حذف شود.
4. سپس:

composer dump-autoload

و هشدار PSR-4 دیگر نباید ظاهر شود.

---

10. پاک‌سازی‌ها

این‌ها با موفقیت اجرا شده‌اند:

php artisan optimize:clear
composer dump-autoload

Composer package discovery و Filament upgrade نیز موفق بوده‌اند.

---

11. PowerShell

نوشتن:

GET /api/v1/staff/orders/pending-approval

مستقیم در PowerShell اشتباه است؛ PowerShell آن را command تلقی می‌کند.

برای تست HTTP:

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

متدهای اصلی:

pendingApproval()
requestChanges()
approve()
reject()
formatShipment()
toJalali()

Business logic Review به:

ShipmentReviewService

سپرده شده و نباید منطق اصلی Review را داخل Controller کپی کنیم.

---

14. تست‌های بعدی

A — Request Changes

POST /api/v1/staff/orders/{shipment}/request-changes

نمونه:

{
  "reason": "لطفاً اطلاعات گیرنده اصلاح شود.",
  "notes": "شماره تماس کامل نیست."
}

انتظار:

• review_state = changes_requested
• ایجاد Review History
• سفارش قابل ویرایش/Resubmit باشد.

B — Approve API

POST /api/v1/staff/orders/{shipment}/approve

انتظار:

review_state = approved
status = approved

C — Reject API

POST /api/v1/staff/orders/{shipment}/reject

با reason اجباری.

انتظار:

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 است.

ساختار هدف:

shipment
├── status
├── review
├── sender
├── receiver
├── packages[]
├── items[]
├── financial
├── documents[]
└── tracking_events[]

WordPress باید این contract را مصرف کند، نه اینکه روی flattened legacy fields تکیه کند.

Mismatchهای شناخته‌شده:

Laravel:

sender.*
receiver.*

WordPress قدیمی:

sender_name
sender_phone
receiver_name
receiver_phone

Tracking:

Laravel:

date
description
location

WordPress:

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

هدف نهایی:

Shipment Operational Status
Review State
Payment State

سه domain مستقل.

فعلاً:

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 هدف

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. پیام شروع پیشنهادی برای چت جدید

ما روی پروژه 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 را تست کنیم.