Two issues caused the rate import to fail with 1237 'Out of range
value for column rate' errors:
1. The rate column was decimal(12,4) — max ~100 million. Converted
IRR values for larger shipments exceed this. Migrate to
decimal(20,4) which handles up to ~100 trillion.
2. The fallback AED→IRR rate in config/ifnex.php was 455,000 (way
too high — should be ~14,000). Update to a realistic market rate.
Also improve the CurrencyResource helperText to remind users to
enter rates in Rials (not Tomans) and provide realistic examples
for AED, USD, and EUR.
Make Iranian Rial (IRR) the sole base currency for shipping rates:
- RateImportService now converts all imported rates to IRR at import
time using the current daily exchange rate (source currency AED/USD/
EUR/IRR). Rates are stored in rate_entries with currency='IRR'.
- PriceCalculatorService looks up IRR rates directly — no conversion
at calc time. Also fixes a pre-existing bug where extras (in IRR)
were incorrectly added to the AED base before conversion.
- RateEntry::lookup() default currency changed from 'AED' to 'IRR'.
- Migration changes the column default to 'IRR'.
- Filament import form: relabel 'Rate currency' to 'Source currency
(in Excel file)' with helper text explaining the conversion.
- WordPress JS: update price summary labels from 'درهم' to 'ریال'
and drop the deprecated net_dirham field.
Architectural benefit: rates are 'frozen' in IRR at import time —
daily exchange rate changes only affect NEW imports, not already-
stored rates. This is more stable and predictable for customers.
The page view 'filament.pages.rate-import' resolves to namespace 'filament'
+ view 'pages.rate-import' in Laravel (the first dot segment is the
namespace). The previous addNamespace('filament.pages', ...) was wrong
because it registered a new namespace nobody looks up.
Move the blade file to resources/views/filament/pages/rate-import.blade.php
where Laravel's default view paths find it. Revert the AppServiceProvider
hack since it was ineffective.
Pages in app/Filament/Resources/*/Pages/ with view='filament.pages.xxx'
keep their blade files in app/Filament/Resources/views/, not in the
default resources/views/filament/pages/. Add the path to the view
finder so Laravel can locate them without requiring each Resource's
view to be copied to resources/views/.
- Fix 'File not found' error in ImportRates page by using Storage facade
to resolve the actual path on the 'local' disk (which points to
storage/app/private, not storage/app).
- Deprecate the old ImportRatesPage (2-zone format) — hide from navigation
and redirect anyone hitting its URL to /admin/rate-import.
- Update the template download route to serve the new 4-quadrant
IFNEX_Rate_Template.xlsx from public/templates/ instead of the old
ShippingRatesTemplateExport (2-zone format).
- Update rate-import.blade.php to use the named route for the download link.
- Add public/templates/IFNEX_Rate_Template.xlsx for direct web access.
Restore the array-based signature of PriceCalculatorService::calculate()
to fix the TypeError thrown when PricingController and CustomerOrderController
called it with an array (the previous commit had switched to 4 separate
string params without updating the callers).
- PriceCalculatorService: support multiple input formats for direction
(export|import|Outbound|Inbound) and type (DOC_NORMAL|DOC_ECONOMY|PARCEL|
DOCUMENT|NON DOC) for backward compatibility with admin and customer flows.
- ExchangeRateService: add convertToIrr() for explicit AED→IRR conversion
(was missing but referenced by the calculator).
- PricingController: expand validation rules to accept new shipment types
and a discount_code string (was 'discount' numeric). Add 3-layer exception
handling (422 validation / 400 business / 500 server).
- PriceTestPage: compute volumetric weight from dimensions (IATA: L×W×H/5000),
resolve destination country by direction, and show errors as Filament
notifications instead of crashing.
Implement a new pricing architecture based on a 4-quadrant model (Export/Import
x Document/Non-Document) to replace the previous 2-zone model. This includes
the ability to handle different zones for parcels and documents per country.
- Add `RateEntry` and `CountryZone` models for managing complex rate matrices.
- Implement `RateImportService` to parse Excel templates using PhpSpreadsheet.
- Add `RateImportResource` in Filament for administrative rate uploads.
- Refactor `PriceCalculatorService` to utilize the new 4-quadrant lookup logic.
- Add database migrations to extend `rate_entries` and create `country_zones`.
- Update `DEPLOYMENT.md` with new architectural details and deployment steps.
Refactor the currency management system to eliminate the redundant
`rate_to_aed` field and transition to a single-base model where all
rates are stored relative to the Iranian Rial (IRR).
Key changes:
- Removed `rate_to_aed` from `currencies` table via new migration.
- Updated `ExchangeRateService` to handle rates using a single
`currency_code` parameter instead of currency pairs.
- Refactored `UpdateExchangeRates` command to fetch rates from the
Exir.io API and support multiple currencies (AED, USD, EUR, CNY).
- Updated Filament resources (`CurrencyResource`,
`ExchangeRateHistoryResource`) and widgets to reflect the new
single-base architecture.
- Improved `PriceCalculatorService` to use the updated service
methodology for fetching the AED/IRR conversion rate.
- Localized console command output to Persian.
Implement additional address and identification fields for both sender
and receiver across the WordPress plugin and Laravel API. This includes
state, postal code, and national ID/passport information.
Key changes:
- Added database migration to include postal and national ID fields in
the shipments table.
- Updated WordPress order form shortcodes and JavaScript to capture
new address fields.
- Refactored Laravel `CustomerOrderController` validation and storage
to support expanded shipment data.
- Implemented tiered data visibility in `TrackController` to protect
PII, providing masked data to anonymous users and full data to
owners/admins.
- Fixed weight-based rate lookup logic in `PriceCalculatorService` to
correctly select the appropriate shipping tier.
- Add DEPLOYMENT_HANDOFF.md for client IT team with full production steps
- Fix ApiKeyMiddleware: correct Response import and fail-closed on unset key
- Remove committed Bridge API secret from all tracked docs
- Document seed, admin provisioning, WP user sync, Kavenegar, and wp-config hardening
- Reformat AGENT.md, README.md, CLIENT_DELIVERY.md to consistent structure
Refactor core documentation files to Persian and introduce a deployment handoff guide.
- Translate `AGENT.md`, `CLIENT_DELIVERY.md`, and `README.md` to Persian for better local stakeholder alignment
- Restructure `AGENT.md` with improved technical specifications and versioning
- Update `CLIENT_DELIVERY.md` with localized status legends and requirement tables
- Enhance `README.md` with detailed feature lists and improved formatting
- Add `DEPLOYMENT_HANDOFF.md` to facilitate production deployment processes
Update AGENT.md, CLIENT_DELIVERY.md, and README.md to reflect the
completion of Phase 3.6 milestones.
- Update project status from 80% to 95% completion
- Document E2E verification of the commitment form and order approval flows
- Detail the implementation of the multi-currency credit system and
customer financial overview
- Update the employee checklist automation details
- Document the redesigned PDF templates (AWB, Invoice, Label) using
dompdf
- Include newly implemented security features like 6-layer API rate
limiting
- Reflect code cleanup activities including removal of debug tools and
test files
Introduce a new, modern user profile interface with a dedicated
statistics grid and improved visual hierarchy.
- Implement `.ifnex-user-profile` and `.ifnex-profile-header` components
- Add responsive statistics grid with support for warning, info, and
success color variants
- Add dark mode support via `prefers-color-scheme` media queries
- Refactor profile shortcode to use new CSS classes instead of inline
styles
- Remove legacy inline-styled multi-currency credit table in favor of
the new design system
Introduce granular rate limiting across various API categories to
improve security and prevent abuse. This includes protection against
brute-force attacks on authentication and SMS endpoints, as well as
resource management for public, customer, wallet, and staff APIs.
- Add `auth` rate limiter (5 requests/min per IP)
- Add `sms` rate limiter (1 request/min per phone/IP)
- Add `public` rate limiter (30 requests/min per IP)
- Add `customer` rate limiter (60 requests/min per user)
- Add `wallet` rate limiter (30 requests/min per user)
- Add `staff` rate limiter (60 requests/min per user)
- Apply middleware to corresponding routes in `api.php`
- Remove obsolete `test_pdf_generation.php` script
Integrate multi-currency debt visibility across the platform by adding
support for foreign currency credits in the user profile shortcode,
improving the admin dashboard with unsettled credits widgets, and
enhancing the Filament admin panel with navigation badges and relation
managers.
- Add multi-currency debt table to WordPress user profile shortcode
- Implement `UnsettledCreditsWidget` for Filament dashboard
- Add navigation badge to `CustomerCreditResource` for open credits
- Add `CreditsRelationManager` to `UserResource`
- Update `CustomerOrderController` API to include `foreign_credits`
- Add concurrency check in `CustomerCreditService` during settlement
Update the styling and layout of PDF invoices and labels to align with
the new brand identity (Navy and Amber color scheme).
Key changes:
- Refactor `invoice.blade.php` to use a structured table-based layout
for better Dompdf compatibility.
- Implement a new color palette using Navy (#1a1a2e) and Amber (#f59e0b).
- Redesign `label.blade.php` with a split-cell layout (barcode left,
info right) for improved readability.
- Standardize typography and spacing across all document templates.
- Remove obsolete sample PDF files from the repository.
Update the AWB document generation to use landscape mode and adjust
the layout to utilize the additional horizontal space.
Key changes:
- Change `PdfService` orientation from portrait to landscape for AWB.
- Refactor `awb.blade.php` to use a side-by-side layout for terms
and signatures.
- Adjust grid column widths from 50% to 25% to accommodate the
new orientation.
- Update `@page` margin definitions for better print alignment.
Refactor AWB, Import Invoice, and Invoice Blade templates to improve
rendering compatibility with Dompdf.
Key changes:
- Replace flexbox and box-sizing with table-based layouts to ensure
consistent rendering in Dompdf.
- Implement `@page` margins instead of container padding to prevent
content overflow and clipping.
- Update color palette to a modern navy and gray scheme.
- Adjust font sizes and typography for better readability and
professional appearance.
- Fix width issues by using 100% width containers instead of fixed
millimeter widths.
Relocate PDF and commitment form download logic from shortcode execution
to the `template_redirect` hook to prevent HTML output from corrupting
binary streams.
Key improvements:
- Moved download interception to `template_redirect` to ensure clean
headers and prevent partial file downloads caused by early buffer
output.
- Replaced direct `get_user_meta` calls with `IFNEX_User_Bridge::get_user_token`
to support automatic token renewal and improved authentication reliability.
- Added PDF signature validation (`%PDF` header check) to ensure
integrity of remote file responses.
- Updated Laravel base controller to include standard `AuthorizesRequests`
and `ValidatesRequests` traits.
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.
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.
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.
Refactor the `ifnex_order_detail_shortcode` function to improve code structure and visual presentation.
- Implement a modern, grid-based layout for order details.
- Replace inline HTML/CSS with a more structured approach using internal CSS.
- Add a visual progress tracker (stages) based on the order status.
- Clean up redundant comments and improve variable handling for AWB and download links.
- Improve responsiveness and styling of action buttons and status badges.
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.
