v0.4.0 — Rate Engine

Rate Engine

The fourth release of Signals Framework adds the rate engine — a composable pricing system of calculation strategies, base periods, and modifiers, with CRMS-parity presets, a reusable config-schema system, REST API, and admin UI.

Added

Rate Engine

• Composable rate engine — a rate definition combines a calculation strategy, a base period, and optional modifiers to describe how a charge is calculated over a rental window
• Three calculation strategies — Period-based (charge per chargeable unit), Fixed (flat charge), and Hybrid (fixed initial charge plus per-unit charge thereafter)
• Five base periods — half-hourly, hourly, daily, weekly, and monthly, each converting elapsed time into chargeable units
• Multiplier modifier — tiered duration multipliers that scale the unit price as a rental lengthens, with the final tier inheriting forward
• Factor modifier — quantity ranges that scale the per-unit subtotal, with an open-ended final range
• Rate breakdown value objects — lossless integer-minor-unit arithmetic via Brick Money, rounded once at assembly, with structured line items and applied-modifier records
• Time options for period and hybrid strategies — clock vs business-hours day type, business hours, rental days per week, leeway minutes, and first/last day cutoffs
• 11 rate definition presets replicating the Current RMS engine types (Daily Rate, Daily Multiplier and Factor, Hourly Rate, Hourly Multiplier and Factor, Half Hourly Rate, Weekly Rate, Monthly Rate, Monthly Multiplier and Factor, Fixed Rate, Fixed Rate and Factor, Fixed Rate and Subs Days)
• Presets seeded on install and re-runnable from the Database Seeders admin panel
• Rate resolver — resolves the highest-priority product rate by store, transaction type, date validity, and priority, with per-product tagged caching invalidated on write
• RateTransactionType enum (rental, sale, service) for product rates, distinct from the int-backed stock transaction type

Config Schema System

• Reusable App\Support\ConfigSchema subsystem for dynamic, schema-driven configuration forms — Field hierarchy (Text, Number, Decimal, Toggle, Select, Time), GroupField, RepeaterField, Schema, and Section
• Conditional field visibility evaluated server-side, validation rule generation for visible fields, and sanitisation that strips hidden and disabled-modifier values

Persistence

• rate_definitions table — strategy, base period, JSONB enabled modifiers and config, preset slug, and self-referential clone tracking
• product_rates table — integer minor-unit price, transaction type, currency, optional store scope, validity dates, and priority
• RateDefinition and ProductRate models with factories, schema definitions, and a Product.rates() relationship

Actions & DTOs

• Seven rate actions — Create/Update/Delete/Duplicate RateDefinition and Create/Update/Delete ProductRate — each authorising via gate, wrapping writes in a transaction, firing audit events, and dispatching webhooks
• Rate DTOs for input validation and API serialisation, including RateBreakdownData (decimal-string money, structured line items)
• Config validation on create/update against the composed schema; disabled-modifier configs stripped on update
• Non-blocking product rate overlap detection surfaced as a warning

API

• Rate definition endpoints — full CRUD plus duplicate, with Ransack filtering by strategy, base period, and preset
• Nested product rate endpoints under products/{product}/rates, with an overlapping_rate_ids warning in the response meta
• POST products/{product}/calculate_rate — returns a rate breakdown, or a zero-priced breakdown with meta.resolved: false when no rate is configured
• Rate engine metadata endpoints — rate_engine/strategies, /modifiers, /presets, and /schema for external form builders
• rates:read / rates:write Sanctum abilities and the rates.* permission group

Admin & Catalogue UI

• Rate Definitions admin panel under Admin → Pricing — list of presets and custom definitions with in-use counts, schema-driven create/edit form with preset picker and From Scratch option, and duplicate support
• Server-driven config form — choosing a strategy constrains base periods, enabling a modifier reveals its tier/range table, and fields show/hide based on other values
• Config-schema Blade field partials styled to Signals conventions, including bordered repeater row cards with add/remove/reorder controls
• Product Rates tab on the product detail page with a dedicated rate assignment form, modal-confirmed removal, and an overlap warning banner
• New Pricing group in the admin sidebar, landing grid, and group switcher

Documentation

• Platform documentation page for Rate Definitions
• API documentation page for rate definitions, product rates, calculation, and metadata, including the Current RMS rate engine mapping table

Changed

• AppServiceProvider registers the rate engine registry as a singleton with the three strategies and two modifiers
• PermissionSeeder adds the rates.* permission group, assigned to the Admin and Operations Manager roles
• CompleteSetup and DatabaseSeeder seed the rate definition presets on install