chore(docs): update project documentation and repository maintenance

Update core project documentation to reflect recent architectural changes, security implementations, and deployment requirements. This includes refining the status tracking system and cleaning up the repository. - Update `AGENT.md` and `STATUS.md` to establish `AGENT.md` as the primary source of truth for project state and contracts. - Add `CLIENT_DELIVERY.md` as the definitive checklist for customer delivery status. - Update `DEPLOYMENT.md` with new production domain information, storage linking instructions, and secure disk configuration for commitment forms. - Update `README.md` with current migration/model counts and link to the new delivery checklist. - Update `.gitignore` to exclude local AI tools and Postman workspaces. - Remove obsolete `IFNEX-Logistics.zip` and `IFNEX_DEPRECATED_FILES_NOTICE.md`. - Fix typos in `DEPLOYMENT.md` deployment scripts.
2026-10-03 06:21:10 +03:30 · 2026-10-03 06:21:10 +03:30 · 40cb104a86
commit 40cb104a86
parent 78d21942db
7 changed files with 78 additions and 43 deletions
--- a/.gitignore
+++ b/.gitignore
@ -5,6 +5,15 @@ Thumbs.db
 .vscode/
 *.log

+# ابزارهای هوش مصنوعی (فایل‌های محلی — هرگز کامیت نشوند)
+.continue/
+.kilo/
+.qodo/
+
+# workspace پستمن (فایل‌های محلی — هرگز کامیت نشوند)
+04_Laravel/postman/
+04_Laravel/.postman/
+
 # هسته وردپرس (فایل‌های اصلی و افزونه‌های شخص ثالث نباید آپلود بشن)
 03_WordPress/wp-content/plugins/*
 03_WordPress/wp-content/uploads/
--- a/01_Documents/STATUS.md
+++ b/01_Documents/STATUS.md
@ -22,7 +22,7 @@
 | `README.md` (ریشه) | ✅ به‌روز | برای نمای کلی بخوانید |
 | `AGENT.md` (ریشه) | ✅ **مرجع اصلی وضعیت و قراردادها** | اول این را بخوانید |

-> 🔴 **قانون طلایی:** هرجا بین اسناد تناقض دیدی، به `Phase0_Proposal.md` اعتماد کن. اسناد قدیمی فقط برای فهم تاریخچه‌ی تصمیمات نگه داشته شده‌اند.
+> 🔴 **قانون طلایی:** هرجا بین اسناد تناقض دیدی، به `AGENT.md` (ریشه) اعتماد کن — مرجع اصلی وضعیت و قراردادها. (`Phase0_Proposal.md` از مخزن حذف شده و فقط تاریخچه است.) اسناد قدیمی فقط برای فهم تاریخچه‌ی تصمیمات نگه داشته شده‌اند.

 ---

--- a/AGENT.md
+++ b/AGENT.md
@ -2,8 +2,8 @@

 > **هدف:** راهنمای جامع برای دستیار هوش مصنوعی جهت درک سریع پروژه، معماری، قراردادها و نکات کلیدی.
 >
-> **نسخه:** 1.1  
-> **تاریخ:** 2026-09-10  
+> **نسخه:** 1.2  
+> **تاریخ:** 2026-10-03  

 ---

@ -56,10 +56,11 @@ IFNEX-Logistics/
 │   │   ├── Traits/        # Auditable
 │   │   ├── Imports/       # OldShipmentsImport, ShippingRatesImport
 │   │   └── Exports/       # ShippingRatesTemplateExport
-│   ├── database/migrations/   # ۳۸+ migration
+│   ├── database/migrations/   # ۵۲ migration
 │   ├── resources/views/pdfs/  # awb, invoice, label, import-invoice (با بارکد)
 │   └── routes/api.php         # ۴۰+ endpoint
 ├── AGENT.md               # همین سند
+├── CLIENT_DELIVERY.md     # چک‌لیست وضعیت تحویل مشتری (منبع اصلی وضعیت تحویل)
 ├── DEPLOYMENT.md          # راهنمای استقرار در سرور
 └── README.md              # معرفی کلی پروژه
 ```
@ -116,7 +117,7 @@ IFNEX-Logistics/
 - مدیر فرم‌های تعهدنامه را در فیلمنت (`CommitmentFormResource`) آپلود می‌کند (با direction: export/import/both).
 - مشتری در جزئیات سفارش وردپرس، لیست تعهدنامه‌ها را می‌بیند → دانلود/پرینت/امضا → آپلود فایل امضاشده (`POST /orders/{shipment}/commitment-forms/{form}/upload`)؛ ثبت در جدول `shipment_commitment_forms`.
 - دانلود AWB / Invoice / Label هم از همین بخش (`/orders/{shipment}/pdf/*`) انجام می‌شود.
- ⚠️ هنوز چک مالکیت (ownership) در کنترلر PDF/تعهدنامه اضافه نشده — کار باقی‌مانده.
+- ✅ چک مالکیت اعمال شده: `ShipmentPolicy` + بررسی `user_id` در کنترلرهای PDF/تعهدنامه (کامیت `8cf4075`)؛ دانلود قالب تعهدنامه از route محافظت‌شده با auth (جایگزین asset عمومی) و دانلود ادمین از دیسک secure از طریق روت‌های `admin.commitment-forms.*`.

 ### ۱۰. اعلان‌ها و SMS کاوه‌نگار
 - تنظیمات از `SystemSetting` خوانده می‌شود (`kavenegar_api_key` + سوییچ هر نوع پیام مثل `kavenegar_send_shipment_approved`).
@ -259,12 +260,12 @@ WALLET_AUTO_CREATE=true

 | # | کار | وضعیت |
 |---|-----|-------|
-| 1 | تست انتهای فلوی سفارش: آپلود تعهدنامه → تأیید کارمند → پرداخت کیف پول/درگاه | ⏳ اولویت اول |
-| 2 | امنیت: چک نقش روی `/staff/*`، چک مالکیت PDF/تعهدنامه، ثبت شورت‌کد `[ifnex_wallet_charge]` (صفحه /wallet/ خراب است)، محدودسازی `GET /discount-codes`، rate limiting | ⏳ |
+| 1 | تست انتهای فلوی سفارش: آپلود تعهدنامه → تأیید کارمند → پرداخت کیف پول/درگاه | 🟡 چرخه تعهدنامه (دانلود → آپلود → تأیید/رد ادمین → اعلان مشتری) در 2026-10-03 تست شد؛ تست پرداخت باقی است |
+| 2 | امنیت: چک نقش روی `/staff/*` ✅ (StaffApiMiddleware)، چک مالکیت PDF/تعهدنامه ✅ (ShipmentPolicy)، محدودسازی `GET /discount-codes` ✅ (گروه auth:sanctum)، ثبت شورت‌کد `[ifnex_wallet_charge]` (صفحه /wallet/ خراب است) ⏳، rate limiting ⏳ | 🟡 |
 | 3 | بازطراحی سیستم اعتبار (بدهی چندارزی مطابق نیاز کارفرما) + رفع اکشن‌های `CustomerCreditResource` | ⏳ |
 | 4 | چک‌لیست خودکار کارمند بعد از تأیید سفارش + نمایش در صفحه سفارش (فعلاً فقط CRUD دستی) | ⏳ |
 | 5 | سند پیشنهادی سیستم مالی (درخواست ۱۳ کارفرما) | ⏳ |
-| 6 | پاک‌سازی: opcache_reset/header ها، cache-buster `time()`، هک‌های `!important` CSS، صفحات تستی منتشرشده، پلاگین ifnex-bridge-test، فایل‌های آشغال ریشه | ⏳ |
+| 6 | پاک‌سازی: opcache_reset/header ها، cache-buster `time()`، هک‌های `!important` CSS، صفحات تستی منتشرشده، پلاگین ifnex-bridge-test، فایل‌های آشغال ریشه | 🟡 فایل‌های آشغال ریشه و لاراول پاک‌سازی/آرشیو شد (2026-10-03)؛ هک‌های دیباگ و صفحات تستی هنوز ⏳ |
 | 7 | نمایش وزن واقعی/حجمی در خلاصه قیمت وردپرس (API فیلد `weight` را برنمی‌گرداند) | ⏳ |
 | 8 | چندزبانه (i18n) — به زمان دیپلوی موکول شده | ⏳ |

@ -285,6 +286,6 @@ WALLET_AUTO_CREATE=true
 | 04_Laravel/README.md | راهنمای بک‌اند |

 ---
-تاریخ: 2026-09-10
-نسخه: 1.1
+تاریخ: 2026-10-03
+نسخه: 1.2
 تهیه‌کننده: VernaSoft Group — Kazem Alghasi
--- a/CLIENT_DELIVERY.md
+++ b/CLIENT_DELIVERY.md
@ -75,9 +75,9 @@

 ---

-# 3. Customer Dashboard / Financial Status
+## 3. Customer Dashboard / Financial Status

-## 3.1 Customer Balance
+### 3.1 Customer Balance

 **Requirement:**
 در Dashboard مشتری، علاوه بر Wallet Balance و Orders، مانده حساب مشتری نیز نمایش داده شود.
@ -99,9 +99,9 @@

 ---

-# 4. Order Approval Before Payment
+## 4. Order Approval Before Payment

-## 4.1 General Flow
+### 4.1 General Flow

 **Required Flow:**

@ -122,7 +122,7 @@

 ---

-## 4.2 Export Order
+### 4.2 Export Order

 **Required Flow:**

@ -149,9 +149,15 @@

 **Status:** 🟡 Implemented — Needs End-to-End Verification

+> 🔧 **به‌روزرسانی 2026-10-03:** چرخه تعهدنامه به‌صورت End-to-End تست و تأیید شد —
+> دانلود قالب توسط مشتری (پروکسی وردپرس با توکن)، آپلود فایل امضاشده، تأیید/رد توسط ادمین در Filament
+> همراه با اعلان دیتابیسی به مشتری، و نمایش وضعیت (تأیید شده / رد شده + دلیل رد) در پورتال مشتری.
+> دانلود امن فایل‌ها در پنل ادمین از طریق روت‌های `admin.commitment-forms.*` از دیسک secure انجام می‌شود.
+> حلقه باقی‌مانده این فلو: تست پرداخت (Wallet / Online) پس از تأیید تعهدنامه‌ها.
+
 ---

-## 4.3 Import Order
+### 4.3 Import Order

 **Required Flow:**

@ -170,7 +176,7 @@

 ---

-# 5. Employee Checklist
+## 5. Employee Checklist

 **Requirement:**
 برای هر سفارش یک Checklist عملیاتی وجود داشته باشد.
@ -198,7 +204,7 @@

 ---

-# 6. Shipment History / Timeline
+## 6. Shipment History / Timeline

 **Requirement:**
 مدیر بتواند تاریخچه کامل هر Shipment را از شروع تا پایان مشاهده کند.
@ -216,9 +222,9 @@

 ---

-# 7. PDF Documents
+## 7. PDF Documents

-## Required Documents
+### Required Documents

 * AWB
 * Invoice
@ -234,7 +240,7 @@

 **Status:** 🟡 Requires Final Client Review

-### Final PDF Acceptance
+#### Final PDF Acceptance

 * [ ] AWB
 * [ ] Export Invoice
@ -248,12 +254,12 @@

 ---

-# 8. Customer Financial Information — Staff / Manager
+## 8. Customer Financial Information — Staff / Manager

 **Requirement:**
 کارمند یا مدیر بتواند با انتخاب یا جستجوی مشتری، اطلاعات مالی کامل او را مشاهده کند.

-### Required Information
+#### Required Information

 * Current Balance
 * Receivables / Payables
@ -270,12 +276,12 @@

 ---

-# 9. Customer Credit
+## 9. Customer Credit

 **Requirement:**
 فقط مدیر کل بتواند برای مشتری شناخته‌شده Credit ایجاد یا افزایش دهد.

-### Important Rule
+#### Important Rule

 اگر مشتری:

@ -303,7 +309,7 @@

 ---

-# 10. Bulk Tracking Import
+## 10. Bulk Tracking Import

 **Requirement:**
 امکان Import گروهی آخرین وضعیت Trackingها در پنل مدیریت.
@ -324,7 +330,7 @@ CSV / approved import format

 ---

-# 11. Admin Editing + Audit Log
+## 11. Admin Editing + Audit Log

 **Requirement:**
 مدیر بتواند تقریباً همه اطلاعات عملیاتی لازم را ویرایش کند.
@ -332,7 +338,7 @@ CSV / approved import format
 **Important Rule:**
 تغییرات مدیریتی باید قابل Audit باشند.

-### Audit Information
+#### Audit Information

 * User
 * Action
@ -348,11 +354,11 @@ CSV / approved import format

 ---

-# 12. SMS Integration
+## 12. SMS Integration

 **Provider:** Kavenegar

-### Required Use Cases
+#### Required Use Cases

 * Mobile Verification
 * Registration Verification
@ -472,9 +478,9 @@ Before Production:

 **Current Status:** IN PROGRESS

-**Next Task:** End-to-End Order Flow Review
+**Next Task:** End-to-End Order Flow Review — حلقه باقی‌مانده: تست پرداخت (کیف پول / درگاه) پس از تأیید تعهدنامه‌ها

-**Last Reviewed Commit:** `e032fceb34`
+**Last Reviewed Commit:** `d6f9ce5` (بازبینی 2026-10-03 — شامل مدیریت کامل تعهدنامه‌ها در پنل ادمین: دانلود امن، تأیید/رد، اعلان مشتری)

 **Source Repository:**

--- a/DEPLOYMENT.md
+++ b/DEPLOYMENT.md
@ -8,8 +8,8 @@

 | محیط | دامنه | نقش |
 |-------|-------|------|
-| Production | system.ifnex.ir | API لاراول |
-| Production | ifnex.ir | وب‌سایت وردپرس |
+| Production | api.ifnex.vernahost.ir (دامنه اختصاصی آینده: system.ifnex.ir) | API لاراول |
+| Production | ifnex.vernahost.ir (دامنه اختصاصی آینده: ifnex.ir) | وب‌سایت وردپرس |
 | Local | localhost:8000 | توسعه |

 ---
@ -36,7 +36,7 @@ git clone https://www.git.vernahost.ir/gitmodir110/ifnex.git .

 ```bash
 cd /home/USER/web/api.ifnex.vernahost.ir/public_html
-ngit clone https://www.git.vernahost.ir/gitmodir110/ifnex.git tmp-ifnex
+git clone https://www.git.vernahost.ir/gitmodir110/ifnex.git tmp-ifnex
 cp -r tmp-ifnex/04_Laravel/* .
 cp -r tmp-ifnex/04_Laravel/.* . 2>/dev/null
 rm -rf tmp-ifnex
@ -45,7 +45,7 @@ rm -rf tmp-ifnex
 ### ۱.۲ نصب وابستگی‌ها

 ```bash
-ncd /home/USER/web/api.ifnex.vernahost.ir/public_html
+cd /home/USER/web/api.ifnex.vernahost.ir/public_html
 composer install --no-dev --optimize-autoloader
 ```

@ -103,12 +103,29 @@ php artisan db:seed --force
 ### ۱.۵ پیکربندی نهایی

 ```bash
+php artisan storage:link
 php artisan config:cache
 php artisan route:cache
 php artisan view:cache
 php artisan filament:clear-cached-components
 ```

+### ۱.۶ آپلود تعهدنامه‌ها و دیسک امن
+
+فایل‌های آپلودی مشتری (تعهدنامه‌های امضاشده) روی دیسک `secure` در `storage/app/secure` ذخیره می‌شوند و URL عمومی ندارند — فقط از طریق روت‌های محافظت‌شده (`/api/v1/customer/...` و `/admin/shipments/...`) سرو می‌شوند:
+
+```bash
+# مسیر دیسک امن باید قابل نوشتن باشد
+mkdir -p storage/app/secure && chmod -R 775 storage
+```
+
+محدودیت آپلود PHP سرور باید با اعتبارسنجی اپلیکیشن (۵ مگابایت) همخوان باشد — در php.ini مربوط به PHP-FPM:
+
+```ini
+upload_max_filesize = 8M
+post_max_size = 8M
+```
+
 ---

 ## ۲. استقرار وردپرس (پلاگین و قالب)
--- a/IFNEX-Logistics.zip
+++ b/IFNEX-Logistics.zip
--- a/README.md
+++ b/README.md
@ -78,7 +78,7 @@
                               │
                  ┌────────────▼────────────┐
                  │     MySQL 8 Database    │
-                  │  (23 migrations, 13     │
+                  │  (52 migrations, 22     │
                  │   models)               │
                  └─────────────────────────┘
 ```
@ -105,7 +105,7 @@ IFNEX-Logistics/
 │   ├── IFNEX_File_Map.md             # نقشه کامل ۱۰۰+ فایل
 │   ├── IFNEX_Roadmap.md              # نقشه راه ۴ فازی
 │   ├── IFNEX_Phase0_Checklist.md     # چک‌لیست تکمیل فازها
-│   ├── IFNEX_DEPRECATED_FILES_NOTICE.md
+│   ├── IFNEX_ADR.md                  # تصمیمات معماری (ADR-001 تا 009)
 │   └── EXCEL_ANALYSIS.md             # تحلیل داده‌های تاریخی
 │
 ├── 🌐 03_WordPress/                  # فرانت‌اند (WordPress 7.0.3)
@ -335,10 +335,10 @@ php artisan serve

 | معیار | مقدار |
 |-------|-------|
-| تعداد مایگریشن‌ها | ۳۸ |
+| تعداد مایگریشن‌ها | ۵۲ |
 | تعداد API endpoints | ۴۰+ |
 | تعداد Filament Resources | ۱۷ |
-| تعداد مدل‌ها | ۲۲ |
+| تعداد مدل‌ها | ۲۶ |
 | تعداد شورت‌کدهای وردپرس | ۱۰+ |
 | تعداد کشورها با پیش‌شماره | ۱۹۲ |
 | رکوردهای تاریخی مهاجرت‌شده | ۳۹۵۰ |
@ -359,15 +359,17 @@ php artisan serve
 | [IFNEX_Commercial_Model.md](01_Documents/IFNEX_Commercial_Model.md) | مدل تجاری و پلن‌های فروش | ⭐⭐ |
 | [DEPLOYMENT.md](DEPLOYMENT.md) | راهنمای استقرار Production | ⭐⭐ |
 | [04_Laravel/README.md](04_Laravel/README.md) | راهنمای بک‌اند | ⭐⭐ |
-| [IFNEX_DEPRECATED_FILES_NOTICE.md](01_Documents/IFNEX_DEPRECATED_FILES_NOTICE.md) | فایل‌های منسوخ | ⭐ |
+| [CLIENT_DELIVERY.md](CLIENT_DELIVERY.md) | **چک‌لیست وضعیت تحویل مشتری (منبع اصلی)** | ⭐⭐⭐ |

 ---

 ## 🚀 مراحل بعدی

+> 📌 **فهرست دقیق و به‌روزِ وضعیت تحویل در [CLIENT_DELIVERY.md](CLIENT_DELIVERY.md) نگهداری می‌شود** — این بخش فقط نمای کلی است.
+
 ### فاز ۳.۶ — باقیمانده (تست و تکمیل)
- تست انتهای فلو: آپلود تعهدنامه → تأیید کارمند → پرداخت (کیف پول / درگاه)
- امنیت: چک نقش روی روت‌های `/staff/*`، چک مالکیت PDF/تعهدنامه، ثبت شورت‌کد `[ifnex_wallet_charge]`، محدودسازی `GET /discount-codes`، rate limiting
+- تست انتهای فلو: آپلود تعهدنامه → تأیید کارمند → پرداخت (کیف پول / درگاه) — چرخه تعهدنامه تا تأیید ادمین 2026-10-03 تست شد؛ تست پرداخت باقی است
+- امنیت: چک نقش `/staff/*` ✅، چک مالکیت PDF/تعهدنامه ✅، محدودسازی `GET /discount-codes` ✅ — باقی: ثبت شورت‌کد `[ifnex_wallet_charge]`، rate limiting
 - بازطراحی سیستم اعتبار مطابق نیاز کارفرما (بدهی به ارز سفارش + تسویه ریالی)
 - چک‌لیست خودکار کارمند بعد از تأیید سفارش + نمایش در صفحه سفارش
 - سند پیشنهادی سیستم مالی