Implement a comprehensive overhaul of the Filament admin dashboard,
introducing a structured 12-column responsive grid layout and enhanced
visual identity.
Key changes include:
- Redesigned Dashboard layout with a 4-layer progressive disclosure
architecture (KPIs, Exchange Rates, Data Tables, and Trends).
- Introduced custom IFNEX design tokens via CSS, including branded
stat cards, status badges, and improved sidebar typography.
- Enhanced FinanceOverviewWidget with real-time trend analysis and
sparkline-ready data structures.
- Refactored RecentShipments and RecentTransactions widgets to use
custom Blade templates for a more polished, consistent UI.
- Integrated brand assets including the company logo and custom
authentication pages.
- Added global number formatting helpers and integrated them into
financial widgets.
- Updated AdminPanelProvider to support custom login pages and
brand-specific header/footer hooks.
Migrate exchange rate handling from static system settings to a
centralized `ExchangeRateService`. This change ensures that currency
rates are managed through a single source of truth that supports
history tracking, approval workflows, and API updates.
Laravel:
- Remove manual exchange rate fields (`aed_to_irr`, `usd_to_irr`, etc.)
from `IfnexSettingsPage` and the `SystemSetting` persistence logic.
- Update `PricingPageController` and `PriceCalculatorService` to
retrieve live rates from `ExchangeRateService` instead of `SystemSetting`.
- Refactor `IfnexSettingsPage` UI to display current rates as
read-only information with a link to the dedicated exchange rate
management resource.
Documentation:
- Update `CLIENT_DELIVERY.md` to reflect the change in exchange rate
management workflow.
Refactor the Filament admin dashboard by decoupling the recent shipments
logic into a dedicated widget and improving the sidebar navigation
experience. Additionally, implement several improvements to the
WordPress theme for better client-side usability.
Laravel/Filament:
- Extract `RecentShipmentsWidget` from `DashboardInfoWidget` to improve
modularization and dashboard performance.
- Update widget sorting and layout to accommodate the new structure.
- Inject custom CSS and Alpine.js logic into the admin head to provide
sidebar group toggling and a "collapse all" utility.
- Improve sidebar group label visibility and hover states.
WordPress:
- Implement `ifnex_login_url()` to support Polylang-aware, language-specific
login pages.
- Hide the WordPress admin bar for non-administrator users to provide a
cleaner client interface.
- Add conditional rendering for the registration link in the login
template based on WordPress user registration settings.
Add comprehensive Architecture Decision Records (ADRs) detailing the
new shipment review state machine, review history domain, and customer
resubmission logic. This documentation establishes the separation
between operational shipment status and the review lifecycle.
Additionally, perform repository cleanup by removing obsolete Postman
collections, environment files, test scripts, and unused migrations.
- Add ADR-001 through ADR-005 regarding review workflow and state.
- Add shipment review handoff documentation.
- Remove redundant Postman resources and local environment configs.
- Remove `test_pdf_generation.php` and `resubmit-test.json`.
- Remove unused `shipment_packages` migration.
- Rename and reorganize one-off maintenance scripts.
Integrate a complete workflow for commitment forms including secure template downloads, customer uploads via WordPress AJAX, and administrative verification with automated notifications.
- Implement `downloadTemplate` and `downloadSigned` logic in `CommitmentFormController` to replace public symlinks with ownership-verified routes.
- Add `CommitmentFormVerifiedNotification` and `CommitmentFormRejectedNotification` to alert customers of status changes.
- Enhance WordPress bridge with AJAX-driven form listing, status badges, and upload capabilities.
- Update Filament `CommitmentFormsRelationManager` to provide better visibility into form directions and descriptions while restricting status edits to specific actions.
- Refactor Laravel 11 bootstrap configuration to handle guest redirection for API and web routes correctly.
- Add administrative controllers for secure file access within the admin panel.
Integrate commitment form functionality into the WordPress bridge and update authentication logic to use the Laravel-specific token.
- Add AJAX functionality to fetch and display commitment forms in the order shortcode.
- Implement client-side file upload handling for signed commitment forms.
- Update `user-bridge.php` to use `ifnex_laravel_token` instead of `ifnex_api_token` for secure API requests.
- Add Laravel migration to make file fields nullable in commitment forms to support incremental uploads.
Introduce a 'secure' filesystem disk to prevent public access to sensitive
commitment form uploads. Files are now stored in a non-public directory
and served via a protected controller method that validates user ownership.
Additionally, implement shipment authorization policies to ensure users
can only access PDF documents (AWB, invoice, labels) belonging to their
own orders.
Other changes:
- Add production environment check for Zarinpal gateway configuration
to prevent accidental use of sandbox credentials.
- Move discount code and commitment form routes under authentication
middleware for improved security.
- Add `ShipmentPolicy` to handle resource authorization.
Add logic to automatically create a pending shipment review if one
does not exist when transitioning shipment statuses. This ensures
the review lifecycle remains intact for shipments created through
paths that bypass initial review generation.
Also include migrations to make `user_id` and `status` nullable on
`shipment_checklists` to support unassigned or incomplete checklists.
Introduce a template-based system for shipment checklists to automate
the creation of required inspection items upon shipment approval.
- Add `ShipmentChecklistTemplate` model and migration to define reusable
checklist structures.
- Extend `ShipmentChecklist` schema to support item titles, requirement
flags, sorting, and attachment paths.
- Implement `instantiateChecklist` in `ShipmentReviewService` to
automatically generate checklist items from active templates based on
shipment direction (import/export).
- Refactor `ShipmentChecklistResource` and `ChecklistsRelationManager`
in Filament to support the new data structure and improved UI.
- Update `ShipmentChecklist` model with helper methods for completion
tracking and improved relationship handling.
Refactor `ShipmentReviewService` to update the existing pending review
instead of creating a new `ShipmentReview` record during the approval
and rejection processes. This ensures that the review lifecycle
correctly finalizes the current pending revision.
- Implement `getPendingReview` to retrieve the active pending review
- Update `approve` to modify the existing review record
- Update `reject` to modify the existing review record
- Add documentation clarifying when new revisions are created versus
when existing ones are finalized
Move StaffApiMiddleware from the Controllers directory to the correct
Middleware directory to adhere to Laravel directory structure standards.
- Relocate StaffApiMiddleware from `app/Http/Controllers` to `app/Http/Middleware`
- Update `api.php` to use the correct namespace for `StaffApiMiddleware`
- Add `IFNEX_Logistics_Review_Workflow_HANDOFF.md` documentation for the review workflow
Introduces a complete shipment review system allowing staff to request
changes to customer orders and customers to resubmit corrected orders.
- Add `ReviewState` enum and `ShipmentReview` model to track review history.
- Implement `ShipmentReviewService` to handle approval and change
request logic.
- Add `resubmit` endpoint for customers to update orders when
`changes_requested` state is active.
- Add `request-changes` endpoint for staff to flag orders for correction.
- Update `ShipmentResource` in Filament to display review states and
manage approvals.
- Implement WordPress bridge support for fetching and resubmitting
orders via AJAX.
- Add database migrations for `shipment_reviews` table and `review_state`
column on shipments.
- Add `StaffApiMiddleware` to secure staff-specific API routes.
Update all project documentation including README, Roadmap, Status,
and Agent guides to reflect the transition to Phase 3.6 (Client Meeting
Adjustments).
Key documentation updates:
- Documented the new order approval flow (pending_approval -> approved).
- Added details for shipment commitment forms and document download system.
- Included Kavenegar SMS integration and Audit Log implementation.
- Updated API endpoint references for new verification and commitment routes.
- Reflected increased project metrics (migrations, models, and API endpoints).
- Updated deployment notes regarding SMS configuration.
Update database migrations to support enhanced shipment workflows,
expanded status tracking, and improved payment gateway flexibility.
Includes SQLite compatibility checks for ENUM modifications.
- Expand `shipments.status` enum to include `pending_approval`,
`approved`, `pending_payment`, `cancelled`, and `archived`.
- Add `reason` column to `shipment_status_history` for better audit trails.
- Add missing address and description fields to `shipments` table.
- Add `wallet` to `wallet_transactions.gateway` enum.
- Add `system` and `customer` to `shipment_tracking_events.source` enum.
- Implement SQLite driver checks in migrations to prevent errors during
testing/local development.
Integrate `SystemSetting` into core services to enable dynamic
configuration of business logic and update the WordPress order form
redirection to align with the new order approval workflow.
- Update `PaymentController`, `ShipmentObserver`, and `TrackingService`
to utilize `SystemSetting` for runtime configuration.
- Modify `ifnex-order-form.js` to redirect users to the orders list
instead of order details upon successful submission.
Implement a comprehensive notification system using Kavenegar SMS
gateway and enhance system traceability through audit logging and
detailed shipment status history.
- SMS Integration:
- Add Kavenegar SMS service with configurable API keys and sender
numbers via system settings.
- Implement automated SMS notifications for shipment approval,
rejection, successful payments, and tracking updates.
- Add administrative UI in Filament to manage SMS gateway settings
and toggle specific notification types.
- Audit & Tracking:
- Apply `Auditable` trait to core models (User, Shipment, Wallet,
etc.) to track changes.
- Refactor `ShipmentStatusHistory` to include status transitions
(`from_status` to `to_status`) and specific reasons for changes.
- Implement `ShipmentObserver` to automate notification triggers
on status changes.
- Database & Config:
- Add migrations for enhanced shipment status history tracking.
- Update `.env.example` and `config/ifnex.php` with Kavenegar
configuration parameters.
Introduce a complete workflow for managing shipment-related documents
and mandatory commitment forms between the Laravel backend and
WordPress frontend.
- Laravel:
- Add `ShipmentCommitmentForm` model and migration to track signed
forms per shipment.
- Implement `CommitmentFormController` to handle fetching available
forms and uploading signed documents.
- Add PDF download endpoints for AWB, labels, and invoices via
`ShipmentPdfController`.
- Extend `User` model with notification management methods.
- Add `FinanceOverviewWidget` for Filament dashboard.
- WordPress:
- Implement AJAX handlers in `user-bridge.php` for PDF downloads and
commitment form management.
- Update `shortcodes.php` to display document download grid and
dynamic commitment form upload interface in order details.
- Add styling for document buttons and form status indicators in
`ifnex-orders.css`.
Refactor the order and shipment lifecycle across WordPress and Laravel,
improving multi-package handling, payment automation, and frontend
reliability.
- Laravel:
- Rename `package_number` to `package_no` and `description` to
`content_description` in `ShipmentPackage` model and controller.
- Update `PaymentController` to automatically transition approved
shipments to `Processed` status upon successful payment.
- Adjust `OrderPaymentService` to validate against `Approved` status
instead of `PendingPayment`.
- Expose `/countries` endpoint as a public route (unauthenticated).
- Remove obsolete `read_excel.php` utility.
- WordPress (Bridge Plugin & Theme):
- Implement AJAX handler for wallet-based order payments.
- Update `ifnex-order-form.js` to support multi-package input names
and auto-select Iran based on shipment direction.
- Improve error handling and feedback in the order form and country
loading logic.
- Add automatic tracking submission when an `awb` parameter is
present in the URL.
- Update CSS with `!important` flags to ensure correct visibility
of form steps and dashboard elements.
- Implement cache-busting for plugin assets and prevent OPcache
stale files via header controls.
- Optimize theme logo loading with eager loading and explicit
dimensions.
Handle array-based filter states in CustomerCreditResource and
ShipmentChecklistResource to ensure correct query execution.
Also remove SoftDeletes trait from ShipmentChecklist model.
Introduce a comprehensive set of commercial features including a multi-step
order approval workflow, customer credit management, and specialized
import service invoicing.
Key changes:
- Implement `pending_approval` and `approved` shipment statuses to allow
staff verification before customer payment.
- Add a credit system to `User` model with `credit_limit` and `credit_used`
to manage customer balances and debts.
- Develop a new `importInvoice` PDF generation service following the
"Sheet ENG Invoice" specification for import services.
- Add Filament resources for managing Audit Logs, Commitment Forms,
Customer Credits, and Shipment Checklists.
- Implement staff-specific APIs for order approval/rejection and
customer financial status monitoring.
- Integrate Kavenegar SMS service for mobile verification and notifications.
- Add bulk tracking import functionality via CSV/Excel.
- Update WordPress bridge assets (CSS/JS) to support the new multi-step
order form UI and updated redirection logic.
- Update deployment configurations and documentation to reflect new
production domains and feature sets.
✅ Multi-Package Support (3.5.1)
- Add shipment_packages migration and ShipmentPackage model
- Add packages() relation to Shipment model
- Update CustomerOrderController to accept packages[] array
- Auto-calculate volumetric weight from dimensions (L*W*H/5000)
- Repeater UI for adding/removing packages
- Real-time summary of total weights
✅ Invoice Form for PARCEL (3.5.2)
- New step in order form (only for PARCEL type)
- Customs items: description, HS Code, quantity, unit price (USD)
- Auto-calculate total per item and invoice total
- Maximum 9 items
- 5-step order form structure
✅ PDF Redesign (3.5.4)
- Install picqer/php-barcode-generator
- Redesign AWB with barcode, From/To, Value, Service, Type
- Redesign Invoice with 9-row table, legal declaration
- Redesign Label to A5 landscape with large barcode
- DOC/PARCEL condition (only PARCEL has invoice)
- Barcode as base64 embed
✅ Technical Fixes (3.5.5)
- Add Enum casts to Shipment model (status, direction, type)
- Fix deselectAfterCompletion -> deselectRecordsAfterCompletion
- Migration for shipment_items (row_number, unit_price)
- Migration to make name nullable
- Fix Enum method names (DocNormal/DocEconomy)
✅ Tracking Test (3.5.6)
- Update TrackController with status_label
- Redesign tracking page with beautiful timeline
- Status box with colored badge
- Timeline with date, description, location, source
- Carrier mappings section
Documentation:
- Update README, Laravel_README, Roadmap, Checklist
- Add IFNEX_Meeting_Summary.md for client presentation
- Update IFNEX_I18N_Strategy.md (moved to deploy phase)
Phase 3.5 — 90% complete (i18n moved to deploy phase)"
- Add packages() relation to Shipment model
- Update CustomerOrderController to accept packages[] array
- Auto-calculate volumetric weight from dimensions (L*W*H/5000)
- Redesign order form Step 1 with Multi-Package UI
- Add package repeater (add/remove packages)
- Real-time summary of total weights
- Both real weight and dimensions are required
- Dimensions normalized to * format (5*6*9)
Phase 3.5.1 — Multi-Package complete"
- Redesign AWB PDF with barcode, From/To, Value, Service, Type
- Redesign Invoice PDF with 9-row table, legal declaration, barcode
- Redesign Label PDF to A5 landscape with large barcode
- Add DOC/PARCEL condition for Invoice (only PARCEL has invoice)
- Fix ShipmentType enum names (DocNormal/DocEconomy)
- Add migration for shipment_items (row_number, unit_price)
- Add migration to make name nullable
- Update PdfService with base64 barcode embedding
- Update ShipmentPdfController with DOC type handling
- Add test_pdf_generation.php script
Phase 3.5 — PDF redesign complete"
This commit marks the completion of Phase 3 (Integration and Improvements) and updates the project status to reflect that Phases 0 through 3 are finished.
Key changes include:
- **Laravel (Backend):**
- Added `calling_code` column to `countries` table via new migration.
- Added scripts to update calling codes for all countries.
- Updated `CustomerOrderController` to include `calling_code` in country data.
- Registered `api_key` middleware alias in `bootstrap/app.php`.
- Improved error handling to return JSON 401 for API authentication failures.
- Updated `README.md` with detailed architecture and feature descriptions.
- **WordPress (Frontend/Bridge):**
- Added `ifnex_wallet_charge` shortcode and AJAX handler for wallet top-ups.
- Implemented auto-fill for calling codes in the order form based on selected country.
- Added real-time phone number validation (digits, +, spaces only).
- Added English-only validation for name, city, and address fields with UI warnings.
- Updated asset enqueuing logic and versioning for CSS/JS.
- **Documentation:**
- Updated `IFNEX_File_Map.md`, `IFNEX_Phase0_Checklist.md`, and `IFNEX_Roadmap.md` to reflect completed phases and new features.
- Updated `DEPLOYMENT.md` with new environment variables (`IFNEX_BRIDGE_API_KEY`) and required WordPress pages.
- Updated project `README.md` with comprehensive feature list and system architecture.
Refactor all primary documentation files to improve readability,
visual presentation, and technical accuracy.
- Update `README.md` with a modern layout, including technology badges
and a high-level architecture overview.
- Redesign `04_Laravel/README.md` to include a streamlined installation
guide, environment configuration details, and default credentials.
- Revamp `DEPLOYMENT.md` to provide clear, environment-specific
instructions for production and local setups.
Implement backend support for the user notification system by adding
endpoints to retrieve and manage notifications.
- Add `notifications` and `markNotificationRead` methods to
`CustomerOrderController`
- Register notification routes under the `v1` API prefix
- Update `IFNEX_User_Bridge` in WordPress to support fetching
notifications and marking them as read via API calls
Introduce a shipment status history system to audit status changes,
including the reason for change and the user responsible. This includes
a new `ShipmentStatusHistory` model and a bulk action in the Filament
ShipmentResource to transition statuses.
Enhance the rate import workflow by adding a downloadable Excel
template and refactoring the `ImportRatesPage` to use the modern
Filament form schema.
- Add `ShipmentStatusHistory` model and migration
- Add bulk `changeStatus` action to `ShipmentResource`
- Add `source` field to tracking events
- Implement `ShippingRatesTemplateExport` for rate template downloads
- Refactor `ImportRatesPage` form implementation and UI
- Add `statusHistories` relationship to `Shipment` model
Introduce a new shipment packages system to allow handling shipments
consisting of multiple individual packages. This includes a new
ShipmentPackage model, a dedicated database table, and a repeater
field in the Filament ShipmentResource for managing package details
such as weight, dimensions, and declared value.
Additionally, update the AWB PDF generation service and template to
include a detailed breakdown of all associated packages when multiple
items are present.
Introduce a new currency management module including a dedicated
resource, database migration, and a custom Filament page for importing
exchange rates. Additionally, enhance the ShipmentResource table with
improved column visibility, sorting, and route display, and integrate
shipment update notifications.
Add a new 'download_invoice' action to the ViewShipment Filament page, allowing users to download invoices directly from the shipment details view.
refactor(shipping): remove redundant Persian comments from import classes
Refactor the shipping rates import process to remove redundant comments
and simplify variable assignments. Additionally, update PDF templates
to use the `asset()` helper instead of `public_path()` for logo
rendering to ensure consistent asset loading.
- refactor(import): simplify `ShippingRatesImport` logic and variable naming
- fix(pdf): update logo image source from `public_path` to `asset` in AWB and Label templates
Extend the shipment database schema to support additional tracking fields,
state information, and financial data. This update also transitions
shipment documentation from RTL/Persian to LTR/English layouts and
integrates barcode generation for AWB and labels.
- feat(db): add migration for missing shipment fields (state, cod_amount,
declared_value, etc.)
- feat(shipment): update Shipment model with new casts and helper methods
- feat(ui): refactor Filament resource to use ShipmentStatus enum and
add new input fields
- feat(pdf): implement barcode generation using picqer/php-barcode-generator
- feat(pdf): redesign AWB, Invoice, and Label templates for LTR/English
support
- refactor(enum): simplify ShipmentStatus enum and update labels/colors
- chore(deps): add picqer/php-barcode-generator dependency
Refactor the shipment direction logic from 'outbound/inbound' to 'export/import' to align with the new database schema requirements. This includes updating the `ShippingRatesImport` logic, adjusting the Excel import sheet mappings, and removing the AED to IRR conversion during import as rates are now stored in AED.
Additionally, updated the shipment view action to open PDF documents in a new tab and updated the Phase 0 checklist with the new database schema requirements.
- docs: update Phase 0 checklist with new schema requirements
- refactor(ui): update shipment view actions to open in new tab
- refactor(import): update shipping rates import to use new direction enums and AED values
- docs: add file map and new excel document
WordPress:
- Refactor hero section layout using CSS Grid for better responsiveness across desktop, tablet, and mobile devices.
- Improve spacing and alignment for hero buttons and trust badges.
- Fix admin bar offset issues in the hero section.
- Clean up redundant HTML tags in front-page template.
Laravel:
- Change Filament admin panel path from 'admin' to 'panel'.
- Clean up comments in web routes.
Update project documentation, status reports, and technical READMEs to
reflect the successful completion of Phase 2 (Financial Automation) and
Phase 3 (Customer Portal & WordPress Integration).
Changes include:
- Updated `STATUS.md` and `README.md` to mark Phases 2 and 3 as completed
- Updated `01_Documents/IFNEX_Phase0_Checklist.md` with detailed task
completion status for Phases 1, 2, and 3
- Refined technical architecture documentation in `04_Laravel/README.md`
to include new services (Zarinpal, OrderPayment), controllers (Auth,
CustomerOrder), and Filament resources (Wallet, Payment, DiscountCode)
- Added `DEPLOYMENT.md` for deployment instructions
- Updated system specifications to include Laravel Sanctum, RBAC via
spatie/laravel-permission, and the updated WordPress/IFNEX Bridge
capabilities
Refactor the Filament dashboard by replacing the legacy FinanceOverviewWidget
with a new set of specialized widgets:
- DashboardInfoWidget for general information
- ExchangeRateWidget for real-time rate monitoring
- WalletStats for financial overview
Additionally, refactor the ExchangeRateService to improve encapsulation
and clean up the ExchangeRateHistory model by moving business logic
(change calculation and recording) from the model to the service layer.
Changes include:
- Removing deprecated helper methods from ExchangeRateHistory model
- Implementing direct queries in ExchangeRateService to replace model scopes
- Adding support for rate chart data retrieval
- Reordering and updating widget sorting in AdminPanelProvider
Introduce a mechanism to track and audit changes in exchange rates.
This includes:
- Creating `ExchangeRateHistory` model and migration to store rate changes.
- Implementing `ExchangeRateService` to encapsulate rate logic.
- Updating `UpdateExchangeRates` command to record history when rates change.
- Adding `ExchangeRateHistoryResource` to the Filament admin panel for monitoring.
Integrate Spatie Laravel Permission to replace the legacy role system.
This includes:
- Adding `spatie/laravel-permission` dependency.
- Implementing `Role` and `User` model updates with `HasRoles` trait.
- Adding migrations for permission and role tables.
- Creating `RoleResource` and `UserResource` for Filament administration.
- Adding a `RoleAndPermissionSeeder` for initial setup.
- Updating `User` model helper methods to utilize role checks.
- Refactor ShipmentResource to improve form schema formatting and structure
- Update WalletTransactionResource with improved navigation icons and Persian labels
- Implement dynamic transaction type options using enum cases
- Add dedicated Create and Edit pages for WalletTransactionResource to support full CRUD operations
Enhance the Filament admin panel configuration to align with the new design system and enable core features.
- Implement custom color palette including dark navy for sidebar
- Set Vazirmatn as the primary font
- Enable SPA mode and collapsible sidebar for improved UX
- Configure database-driven notifications and global search bindings
- Add necessary web middleware stack for session and cookie management
- Create new migration for the notifications system
- Add directory for custom Filament render hooks
Introduce a comprehensive design system across WordPress and Laravel
to ensure visual consistency. Implement new financial reporting
capabilities and Excel export functionality within the Filament admin
panel.
- Add `DESIGN_SYSTEM.md` to define brand colors, typography, and spacing
- Implement `FinancialReport` page in Filament for transaction and
shipment summaries
- Add Excel export support for `ShipmentResource` and
`WalletTransactionResource` using Laravel Excel
- Refactor WordPress plugin and Filament CSS to utilize the new
design system variables
- Update project status to reflect new reporting and design milestones
