sackey
a65fee9d75
- Implemented the customer portal workflow progress component with detailed service progress tracking, including current status, workflow steps, and contact information. - Developed a management workflow analytics dashboard featuring key performance indicators, charts for revenue by branch, labor utilization, and recent quality issues. - Created tests for admin-only middleware to ensure proper access control for admin routes. - Added tests for customer portal view rendering and workflow integration, ensuring the workflow service operates correctly through various stages. - Introduced a .gitignore file for the debugbar storage directory to prevent unnecessary files from being tracked.
83 lines
6.8 KiB
Markdown
83 lines
6.8 KiB
Markdown
## Car Repairs Shop — AI agent working notes
|
||
|
||
This repo is a Laravel 12 app with Livewire (Volt + Flux UI), Tailwind, and Vite. The UI is primarily Livewire pages; a few classic controllers exist for resource routes. Tests use in-memory SQLite.
|
||
|
||
### Architecture map
|
||
- **Workflow-driven design**: The app implements an 11-step automotive repair workflow from vehicle reception to delivery with status tracking, inspections, estimates, and customer notifications.
|
||
- Core domains live in `app/Livewire/**` and `app/Models/**` (Customers, Vehicles, Inventory, JobCards, Estimates, Diagnosis, WorkOrders, Timesheets, Users, Reports, CustomerPortal).
|
||
- **WorkflowService** (`app/Services/WorkflowService.php`) orchestrates the complete repair process with methods for each workflow step.
|
||
- **InspectionChecklistService** (`app/Services/InspectionChecklistService.php`) manages standardized vehicle inspections and comparison logic.
|
||
- Routes are in `routes/web.php`:
|
||
- Root decides destination based on `auth()->user()->isCustomer()` → customers go to `/customer-portal`, admins/staff to `/dashboard`, guests to `/login`.
|
||
- Admin/staff area uses `admin.only` + `permission:*` middleware. Customer portal uses `auth` only.
|
||
- Volt pages registered via `Volt::route('settings/...', 'settings.something')`.
|
||
- Middleware aliases are registered in `bootstrap/app.php`:
|
||
- `admin.only`, `role`, `permission` point to custom classes in `app/Http/Middleware`. Route `permission:` strings are the canonical auth gates in this app.
|
||
- Settings use Spatie Laravel Settings (`app/Settings/**`, `config/settings.php`), e.g., `app(\App\Settings\GeneralSettings::class)` for shop phone/email in views.
|
||
- Blade components: anonymous components live under `resources/views/components/**`. Example: `<x-layouts.customer-portal />` is backed by `resources/views/components/layouts/customer-portal.blade.php`.
|
||
|
||
### 11-Step Workflow Implementation
|
||
The system follows a structured automotive repair workflow:
|
||
1. **Vehicle Reception** → `JobCard::STATUS_RECEIVED` - Basic data capture, unique sequence numbers by branch (`ACC/00212`, `KSI/00212`)
|
||
2. **Initial Inspection** → `JobCard::STATUS_INSPECTED` - Standardized checklist via `InspectionChecklistService`
|
||
3. **Service Assignment** → `JobCard::STATUS_ASSIGNED_FOR_DIAGNOSIS` - Assign to Service Coordinator
|
||
4. **Diagnosis** → `JobCard::STATUS_IN_DIAGNOSIS` - Full diagnostic with timesheet tracking
|
||
5. **Estimate** → `JobCard::STATUS_ESTIMATE_SENT` - Detailed estimate with email/SMS notifications
|
||
6. **Approval** → `JobCard::STATUS_APPROVED` - Customer approval triggers team notifications
|
||
7. **Parts Procurement** → `JobCard::STATUS_PARTS_PROCUREMENT` - Inventory management and sourcing
|
||
8. **Repairs** → `JobCard::STATUS_IN_PROGRESS` - Work execution with timesheet tracking
|
||
9. **Final Inspection** → `JobCard::STATUS_COMPLETED` - Outgoing inspection with discrepancy detection
|
||
10. **Delivery** → `JobCard::STATUS_DELIVERED` - Customer pickup and satisfaction tracking
|
||
11. **Archival** - Document archiving and job closure
|
||
|
||
### Conventions and patterns
|
||
- **Status-driven workflow**: Use `JobCard::getStatusOptions()` for consistent status handling. Each status corresponds to a workflow step.
|
||
- **Role hierarchy**: Service Supervisor → Service Coordinator → Technician. Use role helper methods like `$user->isServiceCoordinator()`.
|
||
- Livewire pages reside under `app/Livewire/{Area}/{Page}.php` with views under `resources/views/{area}/{page}.blade.php` (Volt routes may point directly to views).
|
||
- Authorization:
|
||
- Use `admin.only` to gate admin/staff routes.
|
||
- Use `permission:domain.action` strings on routes (e.g., `permission:customers.view`, `inventory.create`). Keep naming consistent with existing routes.
|
||
- **Branch-specific operations**: All job cards have `branch_code`. Use `JobCard::byBranch($code)` scope for filtering.
|
||
- Customer Portal layout requires a `jobCard` prop. When using `<x-layouts.customer-portal>`, pass it explicitly:
|
||
- Example: `<x-layouts.customer-portal :job-card="$jobCard"> ... </x-layouts.customer-portal>`
|
||
- **Inspection system**: Use `InspectionChecklistService` for standardized checklists. Incoming vs outgoing inspections are compared automatically.
|
||
|
||
### Developer workflows
|
||
- Install & run (common):
|
||
- PHP deps: `composer install`
|
||
- Node deps: `npm install`
|
||
- Generate key & migrate: `php artisan key:generate && php artisan migrate --seed`
|
||
- Dev loop (servers + queue + logs + Vite): `composer dev` (runs: serve, queue:listen, pail, vite)
|
||
- Asset build: `npm run build`
|
||
- Testing:
|
||
- Run tests: `./vendor/bin/phpunit` (uses in-memory SQLite per `phpunit.xml`)
|
||
- Alternative: `composer test` (clears config and runs `artisan test`)
|
||
- Debugging:
|
||
- Logs via Laravel Pail are included in `composer dev`. Otherwise: `php artisan pail`.
|
||
|
||
### Routing and modules (examples)
|
||
|
||
### Data Flow and State Management
|
||
- **Status-Driven Design**: Each workflow step corresponds to a specific JobCard status. Always use status constants from the model.
|
||
- **Service Dependencies**: WorkflowService orchestrates the complete flow, InspectionChecklistService handles standardized vehicle inspections.
|
||
- **Customer Communication**: Auto-notifications at each step keep customers informed of progress.
|
||
- **Quality Control**: Built-in inspection comparisons and quality alerts ensure consistent service delivery.
|
||
- Admin resources (with permissions):
|
||
- `Route::resource('customers', CustomerController::class)->middleware('permission:customers.view');`
|
||
- Inventory area pages are Livewire classes under `app/Livewire/Inventory/**` and grouped under `Route::prefix('inventory')` with `permission:inventory.*`.
|
||
- Customer portal routes:
|
||
- `Route::prefix('customer-portal')->middleware(['auth'])->group(function () { Route::get('/status/{jobCard}', \\App\\Livewire\\CustomerPortal\\JobStatus::class)->name('customer-portal.status'); });`
|
||
|
||
### Testing notes (project-specific)
|
||
- Tests use in-memory SQLite; avoid relying on factories that don’t exist. Prefer lightweight stubs or create the minimal model records needed.
|
||
- For Blade/Livewire views using a layout slot, render the page view (not the layout)
|
||
and pass required data. Example: `View::make('livewire.customer-portal.job-status', ['jobCard' => $jobCard])->render();`
|
||
|
||
### Guardrails for agents
|
||
- When adding new admin routes, wire `admin.only` and appropriate `permission:*` middleware, and register Volt pages via `Volt::route` when applicable.
|
||
- Keep anonymous Blade components under `resources/views/components/**` and pass required props explicitly.
|
||
- Use `app(\App\Settings\GeneralSettings::class)` for shop metadata instead of hardcoding.
|
||
- Follow existing permission key patterns (`domain.action`).
|
||
|
||
If anything above is unclear or you need deeper details (e.g., settings schema, specific Livewire page conventions), propose a short diff or ask for a quick pointer to the relevant file.
|