generated from theradcoza/Laravel-Docker-Dev-Template
104 lines
3.3 KiB
Markdown
104 lines
3.3 KiB
Markdown
# AI Assistant Context — Bhoza Shift Manager
|
|
|
|
## What This App Does
|
|
|
|
Bhoza Shift Manager handles shift scheduling, staff assignment, attendance tracking, and timesheet generation. The entire UI is the Filament admin panel at `/admin`.
|
|
|
|
## Technology Stack
|
|
|
|
| Layer | Technology |
|
|
|-------|------------|
|
|
| Backend | Laravel 11, PHP 8.2+ |
|
|
| Frontend | Blade + Livewire (NO Vue/React/Inertia) |
|
|
| Admin Panel | Filament 3.3 |
|
|
| Database | MySQL 8 / PostgreSQL 16 / SQLite |
|
|
| Permissions | spatie/laravel-permission 6.x |
|
|
| Audit | owen-it/laravel-auditing 14.x |
|
|
| API Auth | Laravel Sanctum |
|
|
| Testing | Pest |
|
|
|
|
## Domain Model
|
|
|
|
### Shift Lifecycle
|
|
```
|
|
planned → in_progress → completed
|
|
```
|
|
|
|
### Core Models
|
|
|
|
- **Shift** — Title, date, planned/actual times, status, notes, creator, starter
|
|
- **ShiftStaff** — Junction table linking users to shifts
|
|
- **ShiftAttendance** — Attendance records per shift per staff (present/absent/not_marked)
|
|
- **User** — Extended with shift relationships + HasRoles
|
|
- **Setting** — Key-value site configuration
|
|
|
|
### Relationships
|
|
- Shift belongsTo creator (User), starter (User)
|
|
- Shift belongsToMany staff (User) via shift_staff
|
|
- Shift hasMany attendances (ShiftAttendance)
|
|
|
|
## Business Logic
|
|
|
|
All shift operations go through `app/Services/ShiftService.php`:
|
|
|
|
- `createShift()` / `quickStartShift()`
|
|
- `startShift()` / `completeShift()`
|
|
- `assignStaff()` / `removeStaff()`
|
|
- `markAttendance()` / `bulkMarkAttendance()`
|
|
- `getShiftReport()` / `getTimesheet()`
|
|
|
|
## Roles & Permissions
|
|
|
|
**Roles:** admin, manager, editor, viewer
|
|
|
|
**Shift Permissions:** shifts.view, shifts.create, shifts.edit, shifts.delete, shifts.start, shifts.complete, shifts.manage_roster, shifts.mark_attendance, shifts.view_reports, shifts.generate_timesheets
|
|
|
|
**User Permissions:** users.view, users.create, users.edit, users.delete, settings.manage
|
|
|
|
## Key File Locations
|
|
|
|
| What | Where |
|
|
|------|-------|
|
|
| Models | `src/app/Models/` |
|
|
| Business logic | `src/app/Services/ShiftService.php` |
|
|
| Authorization | `src/app/Policies/ShiftPolicy.php` |
|
|
| Filament resources | `src/app/Filament/Resources/` |
|
|
| Filament pages | `src/app/Filament/Pages/` |
|
|
| Filament widgets | `src/app/Filament/Widgets/` |
|
|
| Filament views | `src/resources/views/filament/` |
|
|
| Migrations | `src/database/migrations/` |
|
|
| Seeders | `src/database/seeders/` |
|
|
| Routes | `src/routes/` |
|
|
| Tests | `src/tests/` |
|
|
|
|
## Architecture Notes
|
|
|
|
- The root `/` route redirects to `/admin`
|
|
- Filament handles all authentication (login at `/admin/login`)
|
|
- No Breeze auth scaffolding — Filament has its own auth
|
|
- Admin panel configured in `app/Providers/Filament/AdminPanelProvider.php`
|
|
- Module system available via `php artisan make:module` for future features
|
|
|
|
## Code Conventions
|
|
|
|
- Business logic goes in **Services**, not Controllers
|
|
- Use **Policies** for authorization
|
|
- Use **Filament Resources** for admin CRUD
|
|
- Follow Laravel naming conventions
|
|
- No JavaScript frameworks — Blade + Livewire only
|
|
|
|
## Development
|
|
|
|
```bash
|
|
make shell # Enter container
|
|
php artisan migrate # Run migrations
|
|
php artisan db:seed # Seed roles/permissions
|
|
php artisan db:seed --class=RolePermissionSeeder # Re-seed permissions
|
|
```
|
|
|
|
## Debugging
|
|
|
|
1. Check `storage/logs/laravel.log` first
|
|
2. Container logs: `make logs`
|
|
3. Ignition error pages in browser when `APP_DEBUG=true`
|