Add Routing module: EvRoute, pricing, time slots, read API, caching (T3.1-T3.7)

Implements Phase 3 in full: EvRoute model with company/destination relations and a from/to-must-differ guard; the ev_route_time_slots pivot; RoutePricing with a per-route is_blocked flag (every route auto-manages exactly one price row per vehicle option via a fixed-row Filament repeater on both create and edit); PricingService::quote() with a shared VehicleOption enum; RoutingPlugin with the EvRouteResource admin UI (activation gated on non-blocked options being priced); the /api/v1/routes read API (list/show/pricing/time-slots, AI-agent-friendly nested shape); and Redis-tag-based response caching invalidated via EvRoute/RoutePricing observers.
2026-08-06 23:49:42 +07:00
parent 7872105f2f
commit 4da9ecfe7d
38 changed files with 1588 additions and 2 deletions
@@ -0,0 +1,14 @@
+<?php
+
+namespace Modules\Routing\Data;
+
+use Modules\Shared\Enums\VehicleOption;
+
+readonly class PriceQuoteData
+{
+    public function __construct(
+        public int $evRouteId,
+        public VehicleOption $vehicleOption,
+        public string $price,
+    ) {}
+}
@@ -0,0 +1,15 @@
+<?php
+
+namespace Modules\Routing\Exceptions;
+
+use Modules\Routing\Models\EvRoute;
+use Modules\Shared\Enums\VehicleOption;
+use RuntimeException;
+
+class RoutePricingNotFoundException extends RuntimeException
+{
+    public static function forRouteAndOption(EvRoute $route, VehicleOption $vehicleOption): self
+    {
+        return new self("No pricing found for route [{$route->id}] and vehicle option [{$vehicleOption->value}].");
+    }
+}
@@ -0,0 +1,63 @@
+<?php
+
+namespace Modules\Routing\Filament\Resources\EvRoutes;
+
+use BackedEnum;
+use Filament\Resources\Resource;
+use Filament\Schemas\Schema;
+use Filament\Support\Icons\Heroicon;
+use Filament\Tables\Table;
+use Modules\Routing\Filament\Resources\EvRoutes\Pages\CreateEvRoute;
+use Modules\Routing\Filament\Resources\EvRoutes\Pages\EditEvRoute;
+use Modules\Routing\Filament\Resources\EvRoutes\Pages\ListEvRoutes;
+use Modules\Routing\Filament\Resources\EvRoutes\Schemas\EvRouteForm;
+use Modules\Routing\Filament\Resources\EvRoutes\Tables\EvRoutesTable;
+use Modules\Routing\Models\EvRoute;
+use UnitEnum;
+
+class EvRouteResource extends Resource
+{
+    protected static ?string $model = EvRoute::class;
+
+    protected static string|BackedEnum|null $navigationIcon = Heroicon::OutlinedMap;
+
+    protected static string|UnitEnum|null $navigationGroup = 'Routing';
+
+    public static function form(Schema $schema): Schema
+    {
+        return EvRouteForm::configure($schema);
+    }
+
+    public static function table(Table $table): Table
+    {
+        return EvRoutesTable::configure($table);
+    }
+
+    public static function getPages(): array
+    {
+        return [
+            'index' => ListEvRoutes::route('/'),
+            'create' => CreateEvRoute::route('/create'),
+            'edit' => EditEvRoute::route('/{record}/edit'),
+        ];
+    }
+
+    /**
+     * A route can only be activated once every non-blocked vehicle option
+     * carries a price above 0 — enforced here (form/UI level), not as a DB
+     * constraint. A route with every option blocked can never be activated.
+     *
+     * Checked against the raw pricing repeater data submitted on the form
+     * (not a DB read), since on the create form no pricing rows exist yet,
+     * and on the edit form the repeater's relationship save hasn't run yet
+     * by the time this is checked.
+     *
+     * @param  array<int, array{price?: mixed, is_blocked?: mixed}>  $pricingItems
+     */
+    public static function hasCompletePricingData(array $pricingItems): bool
+    {
+        $nonBlocked = collect($pricingItems)->reject(fn (array $item) => (bool) ($item['is_blocked'] ?? false));
+
+        return $nonBlocked->isNotEmpty() && $nonBlocked->every(fn (array $item) => (float) ($item['price'] ?? 0) > 0);
+    }
+}
@@ -0,0 +1,28 @@
+<?php
+
+namespace Modules\Routing\Filament\Resources\EvRoutes\Pages;
+
+use Filament\Notifications\Notification;
+use Filament\Resources\Pages\CreateRecord;
+use Modules\Routing\Filament\Resources\EvRoutes\EvRouteResource;
+
+class CreateEvRoute extends CreateRecord
+{
+    protected static string $resource = EvRouteResource::class;
+
+    protected function beforeCreate(): void
+    {
+        if (
+            ($this->data['is_active'] ?? false)
+            && ! EvRouteResource::hasCompletePricingData($this->data['pricing'] ?? [])
+        ) {
+            Notification::make()
+                ->warning()
+                ->title('Route cannot be activated yet')
+                ->body('Set a price above 0 for every non-blocked vehicle option first, then activate the route.')
+                ->send();
+
+            $this->halt();
+        }
+    }
+}
@@ -0,0 +1,36 @@
+<?php
+
+namespace Modules\Routing\Filament\Resources\EvRoutes\Pages;
+
+use Filament\Actions\DeleteAction;
+use Filament\Notifications\Notification;
+use Filament\Resources\Pages\EditRecord;
+use Modules\Routing\Filament\Resources\EvRoutes\EvRouteResource;
+
+class EditEvRoute extends EditRecord
+{
+    protected static string $resource = EvRouteResource::class;
+
+    protected function getHeaderActions(): array
+    {
+        return [
+            DeleteAction::make(),
+        ];
+    }
+
+    protected function beforeSave(): void
+    {
+        if (
+            ($this->data['is_active'] ?? false)
+            && ! EvRouteResource::hasCompletePricingData($this->data['pricing'] ?? [])
+        ) {
+            Notification::make()
+                ->warning()
+                ->title('Route cannot be activated yet')
+                ->body('Set a price above 0 for every non-blocked vehicle option first, then activate the route.')
+                ->send();
+
+            $this->halt();
+        }
+    }
+}
@@ -0,0 +1,19 @@
+<?php
+
+namespace Modules\Routing\Filament\Resources\EvRoutes\Pages;
+
+use Filament\Actions\CreateAction;
+use Filament\Resources\Pages\ListRecords;
+use Modules\Routing\Filament\Resources\EvRoutes\EvRouteResource;
+
+class ListEvRoutes extends ListRecords
+{
+    protected static string $resource = EvRouteResource::class;
+
+    protected function getHeaderActions(): array
+    {
+        return [
+            CreateAction::make(),
+        ];
+    }
+}
@@ -0,0 +1,89 @@
+<?php
+
+namespace Modules\Routing\Filament\Resources\EvRoutes\Schemas;
+
+use Filament\Forms\Components\Repeater;
+use Filament\Forms\Components\Select;
+use Filament\Forms\Components\TextInput;
+use Filament\Forms\Components\Toggle;
+use Filament\Schemas\Schema;
+use Modules\Shared\Enums\VehicleOption;
+
+class EvRouteForm
+{
+    public static function configure(Schema $schema): Schema
+    {
+        return $schema
+            ->components([
+                Select::make('ev_company_id')
+                    ->label('EV Company')
+                    ->relationship('company', 'name')
+                    ->required()
+                    ->searchable()
+                    ->preload(),
+                Select::make('from_destination_id')
+                    ->label('From')
+                    ->relationship('fromDestination', 'name')
+                    ->required()
+                    ->searchable()
+                    ->preload(),
+                Select::make('to_destination_id')
+                    ->label('To')
+                    ->relationship('toDestination', 'name')
+                    ->required()
+                    ->searchable()
+                    ->preload()
+                    ->different('from_destination_id')
+                    ->validationMessages([
+                        'different' => 'The destination must be different from the origin.',
+                    ]),
+                Select::make('timeSlots')
+                    ->label('Departure Time Slots')
+                    ->relationship('timeSlots', 'label')
+                    ->multiple()
+                    ->searchable()
+                    ->preload(),
+                Toggle::make('is_round_trip')
+                    ->required()
+                    ->default(false),
+                Toggle::make('is_active')
+                    ->required()
+                    ->default(false)
+                    ->helperText('Every non-blocked vehicle option must have a price above 0 before a route can be activated.'),
+                Repeater::make('pricing')
+                    ->relationship()
+                    ->label('Pricing')
+                    ->schema([
+                        Select::make('vehicle_option')
+                            ->options(array_combine(
+                                array_map(fn (VehicleOption $option) => $option->value, VehicleOption::cases()),
+                                array_map(fn (VehicleOption $option) => str($option->value)->headline()->toString(), VehicleOption::cases()),
+                            ))
+                            ->disabled()
+                            ->dehydrated()
+                            ->required(),
+                        TextInput::make('price')
+                            ->numeric()
+                            ->minValue(0)
+                            ->required(),
+                        Toggle::make('is_blocked')
+                            ->label('Blocked')
+                            ->helperText('Hidden from booking regardless of price.'),
+                    ])
+                    ->columns(3)
+                    ->default(
+                        collect(VehicleOption::cases())
+                            ->map(fn (VehicleOption $option) => [
+                                'vehicle_option' => $option->value,
+                                'price' => 0,
+                                'is_blocked' => false,
+                            ])
+                            ->all()
+                    )
+                    ->addable(false)
+                    ->deletable(false)
+                    ->reorderable(false)
+                    ->columnSpanFull(),
+            ]);
+    }
+}
@@ -0,0 +1,65 @@
+<?php
+
+namespace Modules\Routing\Filament\Resources\EvRoutes\Tables;
+
+use Filament\Actions\BulkActionGroup;
+use Filament\Actions\DeleteBulkAction;
+use Filament\Actions\EditAction;
+use Filament\Tables\Columns\IconColumn;
+use Filament\Tables\Columns\TextColumn;
+use Filament\Tables\Filters\TernaryFilter;
+use Filament\Tables\Table;
+use Modules\Routing\Models\EvRoute;
+use Modules\Routing\Models\RoutePricing;
+
+class EvRoutesTable
+{
+    public static function configure(Table $table): Table
+    {
+        return $table
+            ->modifyQueryUsing(fn ($query) => $query->with('pricing'))
+            ->columns([
+                TextColumn::make('company.name')
+                    ->label('EV Company')
+                    ->searchable()
+                    ->sortable(),
+                TextColumn::make('fromDestination.name')
+                    ->label('From')
+                    ->searchable()
+                    ->sortable(),
+                TextColumn::make('toDestination.name')
+                    ->label('To')
+                    ->searchable()
+                    ->sortable(),
+                TextColumn::make('pricing')
+                    ->label('Pricing')
+                    ->state(fn (EvRoute $record) => $record->pricing
+                        ->sortBy(fn (RoutePricing $pricing) => $pricing->vehicle_option->value)
+                        ->map(fn (RoutePricing $pricing) => str($pricing->vehicle_option->value)->headline()
+                            .': '
+                            .($pricing->is_blocked ? 'Blocked' : number_format($pricing->price, 0)))
+                        ->all())
+                    ->listWithLineBreaks(),
+                IconColumn::make('is_round_trip')
+                    ->boolean(),
+                IconColumn::make('is_active')
+                    ->boolean(),
+                TextColumn::make('created_at')
+                    ->dateTime()
+                    ->sortable()
+                    ->toggleable(isToggledHiddenByDefault: true),
+            ])
+            ->filters([
+                TernaryFilter::make('is_active'),
+                TernaryFilter::make('is_round_trip'),
+            ])
+            ->recordActions([
+                EditAction::make(),
+            ])
+            ->toolbarActions([
+                BulkActionGroup::make([
+                    DeleteBulkAction::make(),
+                ]),
+            ]);
+    }
+}
@@ -0,0 +1,84 @@
+<?php
+
+namespace Modules\Routing\Http\Controllers;
+
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\AnonymousResourceCollection;
+use Illuminate\Routing\Controller;
+use Illuminate\Support\Facades\Cache;
+use Modules\Routing\Http\Resources\EvRouteResource;
+use Modules\Routing\Http\Resources\RoutePricingResource;
+use Modules\Routing\Http\Resources\RouteTimeSlotResource;
+use Modules\Routing\Models\EvRoute;
+
+class EvRouteController extends Controller
+{
+    /**
+     * @var list<string>
+     */
+    private const EAGER_LOADS = ['company', 'fromDestination', 'toDestination', 'timeSlots', 'pricing'];
+
+    private const CACHE_TAG = 'routes';
+
+    private const CACHE_TTL_MINUTES = 5;
+
+    public function index(Request $request): AnonymousResourceCollection
+    {
+        $filters = $request->only(['company', 'from', 'to', 'date']);
+
+        $routes = Cache::tags(self::CACHE_TAG)->remember(
+            'routes:index:'.md5(json_encode($filters)),
+            now()->addMinutes(self::CACHE_TTL_MINUTES),
+            fn () => EvRoute::query()
+                ->where('is_active', true)
+                ->when($request->filled('company'), fn ($query) => $query->where('ev_company_id', $request->integer('company')))
+                ->when($request->filled('from'), fn ($query) => $query->where('from_destination_id', $request->integer('from')))
+                ->when($request->filled('to'), fn ($query) => $query->where('to_destination_id', $request->integer('to')))
+                // `date` is accepted for forward-compatibility with future per-date capacity
+                // checks (domain.md §7), but v1 has no route-level calendar to filter against.
+                ->with(self::EAGER_LOADS)
+                ->get(),
+        );
+
+        return EvRouteResource::collection($routes);
+    }
+
+    public function show(EvRoute $route): EvRouteResource
+    {
+        abort_unless($route->is_active, 404);
+
+        $route = Cache::tags(self::CACHE_TAG)->remember(
+            "routes:show:{$route->id}",
+            now()->addMinutes(self::CACHE_TTL_MINUTES),
+            fn () => $route->load(self::EAGER_LOADS),
+        );
+
+        return new EvRouteResource($route);
+    }
+
+    public function pricing(EvRoute $route): AnonymousResourceCollection
+    {
+        abort_unless($route->is_active, 404);
+
+        $pricing = Cache::tags(self::CACHE_TAG)->remember(
+            "routes:pricing:{$route->id}",
+            now()->addMinutes(self::CACHE_TTL_MINUTES),
+            fn () => $route->pricing()->get(),
+        );
+
+        return RoutePricingResource::collection($pricing);
+    }
+
+    public function timeSlots(EvRoute $route): AnonymousResourceCollection
+    {
+        abort_unless($route->is_active, 404);
+
+        $timeSlots = Cache::tags(self::CACHE_TAG)->remember(
+            "routes:time-slots:{$route->id}",
+            now()->addMinutes(self::CACHE_TTL_MINUTES),
+            fn () => $route->timeSlots()->get(),
+        );
+
+        return RouteTimeSlotResource::collection($timeSlots);
+    }
+}
@@ -0,0 +1,30 @@
+<?php
+
+namespace Modules\Routing\Http\Resources;
+
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\JsonResource;
+use Modules\Catalog\Http\Resources\DestinationResource;
+use Modules\Catalog\Http\Resources\EvCompanyResource;
+
+class EvRouteResource extends JsonResource
+{
+    /**
+     * Transform the resource into an array.
+     *
+     * @return array<string, mixed>
+     */
+    public function toArray(Request $request): array
+    {
+        return [
+            'id' => $this->id,
+            'is_round_trip' => $this->is_round_trip,
+            'is_active' => $this->is_active,
+            'company' => new EvCompanyResource($this->whenLoaded('company')),
+            'from_destination' => new DestinationResource($this->whenLoaded('fromDestination')),
+            'to_destination' => new DestinationResource($this->whenLoaded('toDestination')),
+            'time_slots' => RouteTimeSlotResource::collection($this->whenLoaded('timeSlots')),
+            'pricing' => RoutePricingResource::collection($this->whenLoaded('pricing')),
+        ];
+    }
+}
@@ -0,0 +1,23 @@
+<?php
+
+namespace Modules\Routing\Http\Resources;
+
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\JsonResource;
+
+class RoutePricingResource extends JsonResource
+{
+    /**
+     * Transform the resource into an array.
+     *
+     * @return array<string, mixed>
+     */
+    public function toArray(Request $request): array
+    {
+        return [
+            'vehicle_option' => $this->vehicle_option->value,
+            'price' => (string) $this->price,
+            'is_blocked' => $this->is_blocked,
+        ];
+    }
+}
@@ -0,0 +1,24 @@
+<?php
+
+namespace Modules\Routing\Http\Resources;
+
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\JsonResource;
+
+class RouteTimeSlotResource extends JsonResource
+{
+    /**
+     * Transform the resource into an array.
+     *
+     * @return array<string, mixed>
+     */
+    public function toArray(Request $request): array
+    {
+        return [
+            'id' => $this->id,
+            'label' => $this->label,
+            'time' => $this->time?->format('H:i'),
+            'is_active' => $this->whenPivotLoaded('ev_route_time_slots', fn () => (bool) $this->pivot->is_active),
+        ];
+    }
+}
@@ -0,0 +1,78 @@
+<?php
+
+namespace Modules\Routing\Models;
+
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\Relations\BelongsToMany;
+use Illuminate\Database\Eloquent\Relations\HasMany;
+use InvalidArgumentException;
+use Modules\Catalog\Models\DepartureTimeSlot;
+use Modules\Catalog\Models\Destination;
+use Modules\Catalog\Models\EvCompany;
+use Modules\Routing\Database\Factories\EvRouteFactory;
+
+class EvRoute extends Model
+{
+    /** @use HasFactory<EvRouteFactory> */
+    use HasFactory;
+
+    /**
+     * @var list<string>
+     */
+    protected $fillable = [
+        'ev_company_id',
+        'from_destination_id',
+        'to_destination_id',
+        'is_round_trip',
+        'is_active',
+    ];
+
+    /**
+     * @return array<string, string>
+     */
+    protected function casts(): array
+    {
+        return [
+            'is_round_trip' => 'boolean',
+            'is_active' => 'boolean',
+        ];
+    }
+
+    protected static function booted(): void
+    {
+        static::saving(function (self $route): void {
+            if ($route->from_destination_id === $route->to_destination_id) {
+                throw new InvalidArgumentException("A route's from and to destinations must be different.");
+            }
+        });
+    }
+
+    public function company(): BelongsTo
+    {
+        return $this->belongsTo(EvCompany::class, 'ev_company_id');
+    }
+
+    public function fromDestination(): BelongsTo
+    {
+        return $this->belongsTo(Destination::class, 'from_destination_id');
+    }
+
+    public function toDestination(): BelongsTo
+    {
+        return $this->belongsTo(Destination::class, 'to_destination_id');
+    }
+
+    public function timeSlots(): BelongsToMany
+    {
+        return $this->belongsToMany(DepartureTimeSlot::class, 'ev_route_time_slots')
+            ->withPivot('is_active')
+            ->withTimestamps();
+    }
+
+    public function pricing(): HasMany
+    {
+        return $this->hasMany(RoutePricing::class, 'ev_route_id');
+    }
+}
@@ -0,0 +1,44 @@
+<?php
+
+namespace Modules\Routing\Models;
+
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Modules\Routing\Database\Factories\RoutePricingFactory;
+use Modules\Shared\Enums\VehicleOption;
+
+class RoutePricing extends Model
+{
+    /** @use HasFactory<RoutePricingFactory> */
+    use HasFactory;
+
+    protected $table = 'route_pricing';
+
+    /**
+     * @var list<string>
+     */
+    protected $fillable = [
+        'ev_route_id',
+        'vehicle_option',
+        'price',
+        'is_blocked',
+    ];
+
+    /**
+     * @return array<string, string>
+     */
+    protected function casts(): array
+    {
+        return [
+            'vehicle_option' => VehicleOption::class,
+            'price' => 'decimal:2',
+            'is_blocked' => 'boolean',
+        ];
+    }
+
+    public function route(): BelongsTo
+    {
+        return $this->belongsTo(EvRoute::class, 'ev_route_id');
+    }
+}
@@ -0,0 +1,19 @@
+<?php
+
+namespace Modules\Routing\Observers;
+
+use Illuminate\Support\Facades\Cache;
+use Modules\Routing\Models\EvRoute;
+
+class EvRouteObserver
+{
+    public function saved(EvRoute $route): void
+    {
+        Cache::tags('routes')->flush();
+    }
+
+    public function deleted(EvRoute $route): void
+    {
+        Cache::tags('routes')->flush();
+    }
+}
@@ -0,0 +1,19 @@
+<?php
+
+namespace Modules\Routing\Observers;
+
+use Illuminate\Support\Facades\Cache;
+use Modules\Routing\Models\RoutePricing;
+
+class RoutePricingObserver
+{
+    public function saved(RoutePricing $pricing): void
+    {
+        Cache::tags('routes')->flush();
+    }
+
+    public function deleted(RoutePricing $pricing): void
+    {
+        Cache::tags('routes')->flush();
+    }
+}
@@ -4,6 +4,10 @@ namespace Modules\Routing\Providers;

 use Illuminate\Contracts\Auth\Access\Gate;
 use Illuminate\Support\ServiceProvider;
+use Modules\Routing\Models\EvRoute;
+use Modules\Routing\Models\RoutePricing;
+use Modules\Routing\Observers\EvRouteObserver;
+use Modules\Routing\Observers\RoutePricingObserver;
 use Modules\Routing\Policies\RoutePolicy;

 class RoutingServiceProvider extends ServiceProvider
@@ -12,6 +16,9 @@ class RoutingServiceProvider extends ServiceProvider

    public function boot(Gate $gate): void
    {
-        $gate->policy('Modules\Routing\Models\EvRoute', RoutePolicy::class);
+        $gate->policy(EvRoute::class, RoutePolicy::class);
+
+        EvRoute::observe(EvRouteObserver::class);
+        RoutePricing::observe(RoutePricingObserver::class);
    }
 }
@@ -0,0 +1,38 @@
+<?php
+
+namespace Modules\Routing;
+
+use Filament\Contracts\Plugin;
+use Filament\Panel;
+
+class RoutingPlugin implements Plugin
+{
+    public function getId(): string
+    {
+        return 'routing';
+    }
+
+    public function register(Panel $panel): void
+    {
+        $panel
+            ->discoverResources(
+                in: __DIR__.'/Filament/Resources',
+                for: 'Modules\Routing\Filament\Resources',
+            )
+            ->discoverPages(
+                in: __DIR__.'/Filament/Pages',
+                for: 'Modules\Routing\Filament\Pages',
+            )
+            ->discoverWidgets(
+                in: __DIR__.'/Filament/Widgets',
+                for: 'Modules\Routing\Filament\Widgets',
+            );
+    }
+
+    public function boot(Panel $panel): void {}
+
+    public static function make(): static
+    {
+        return app(static::class);
+    }
+}
@@ -0,0 +1,28 @@
+<?php
+
+namespace Modules\Routing\Services;
+
+use Modules\Routing\Data\PriceQuoteData;
+use Modules\Routing\Exceptions\RoutePricingNotFoundException;
+use Modules\Routing\Models\EvRoute;
+use Modules\Shared\Enums\VehicleOption;
+
+class PricingService
+{
+    public function quote(EvRoute $route, VehicleOption $vehicleOption): PriceQuoteData
+    {
+        $pricing = $route->pricing()
+            ->where('vehicle_option', $vehicleOption)
+            ->first();
+
+        if (! $pricing) {
+            throw RoutePricingNotFoundException::forRouteAndOption($route, $vehicleOption);
+        }
+
+        return new PriceQuoteData(
+            evRouteId: $route->id,
+            vehicleOption: $vehicleOption,
+            price: (string) $pricing->price,
+        );
+    }
+}