Mulanga/bhoza-shift-manager
1
0
Fork 0
generated from theradcoza/Laravel-Docker-Dev-Template
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

resolve sql port related errors

Browse Source
This commit is contained in:
Mulanga
2026-03-11 11:13:21 +02:00
parent ccabfc5d8a
commit 5a93cc76fd
76 changed files with 235 additions and 6802 deletions
Download Patch File Download Diff File Expand all files Collapse all files

378
AI_CONTEXT.md
View File

@@ -1,343 +1,103 @@
# AI Assistant Context
# AI Assistant Context — Bhoza Shift Manager
This document provides context for AI coding assistants working on projects built with this template.
## What This App Does
## Template Overview
This is a **ready-to-use Laravel Docker Development Template** with everything pre-installed:
- ✅ Laravel 11 with Breeze authentication (Blade + dark mode)
- ✅ Filament v3.3 admin panel with user management
- ✅ Pest testing framework
- ✅ Laravel Pint code style
- ✅ Docker-based development environment
- ✅ Production deployment to Ubuntu 24.04 (no Docker)
- ✅ Modular architecture
- ✅ Multi-database support (MySQL, PostgreSQL, SQLite)
**Setup time:** 2 minutes - just run `./setup.sh` and everything is ready!
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** | Filament 3.x |
| **Database** | MySQL 8 / PostgreSQL 15 / SQLite |
| **Cache/Queue** | Redis |
| **Auth** | Laravel Breeze (Blade + Livewire) - PRE-INSTALLED |
| **Testing** | Pest - PRE-INSTALLED |
| **Permissions** | spatie/laravel-permission - PRE-INSTALLED |
| **Audit** | owen-it/laravel-auditing - PRE-INSTALLED |
| **Error Tracking** | spatie/laravel-flare + spatie/laravel-ignition - PRE-INSTALLED |
| **API Auth** | Laravel Sanctum - PRE-INSTALLED |
| **Code Style** | Laravel Pint |
| 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 |
## 🚨 CRITICAL: Debugging Strategy
## Domain Model
**ALWAYS CHECK LOGS FIRST - NEVER GUESS AT SOLUTIONS**
When encountering errors:
### Step 1: Check Laravel Logs
```bash
docker-compose exec app cat storage/logs/laravel.log | grep -A 20 "Error"
### Shift Lifecycle
```
planned → in_progress → completed
```
### Step 2: Identify Root Cause
- Read the full stack trace
- Find the exact file and line number
- Understand what the code is trying to do
### Core Models
### Step 3: Fix and Verify
- Make targeted fix to root cause
- Clear relevant caches
- Test the specific scenario
- **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
### Common Commands:
```bash
# View recent errors
docker-compose exec app tail -n 100 storage/logs/laravel.log
### Relationships
- Shift belongsTo creator (User), starter (User)
- Shift belongsToMany staff (User) via shift_staff
- Shift hasMany attendances (ShiftAttendance)
# Check container logs
docker-compose logs --tail=50 app
docker-compose logs --tail=50 nginx
## Business Logic
# Clear caches after fixes
docker-compose exec app php artisan optimize:clear
docker-compose exec app php artisan permission:cache-reset
```
All shift operations go through `app/Services/ShiftService.php`:
**See [DEBUGGING.md](DEBUGGING.md) for complete debugging guide.**
- `createShift()` / `quickStartShift()`
- `startShift()` / `completeShift()`
- `assignStaff()` / `removeStaff()`
- `markAttendance()` / `bulkMarkAttendance()`
- `getShiftReport()` / `getTimesheet()`
## Important: No JavaScript Frameworks
## Roles & Permissions
**This template deliberately avoids JavaScript frameworks** (Vue, React, Inertia) to keep debugging simple. All frontend is:
- Blade templates
- Livewire for reactivity
- Alpine.js (included with Livewire)
- Tailwind CSS
**Roles:** admin, manager, editor, viewer
Do NOT suggest or implement Vue/React/Inertia solutions.
**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
## Architecture
**User Permissions:** users.view, users.create, users.edit, users.delete, settings.manage
### Module Structure
Features are organized as **modules** in `app/Modules/`:
```
app/Modules/
└── ModuleName/
├── Config/
│ └── module_name.php # Module config (incl. audit settings)
├── Database/
│ ├── Migrations/
│ └── Seeders/
├── Filament/
│ └── Resources/ # Admin CRUD + Audit Log
├── Http/
│ ├── Controllers/
│ ├── Middleware/
│ └── Requests/
├── Models/ # With ModuleAuditable trait
├── Policies/
├── Services/ # Business logic goes here
├── Routes/
│ ├── web.php
│ └── api.php
├── Resources/
│ ├── views/
│ ├── css/
│ └── lang/
├── Permissions.php # Module permissions
└── ModuleNameServiceProvider.php
```
### Creating Modules
```bash
# Basic module
php artisan make:module ModuleName
# With model + Filament resource + audit
php artisan make:module ModuleName --model=ModelName
# With API routes
php artisan make:module ModuleName --model=ModelName --api
```
### Key Traits and Interfaces
**For auditable models:**
```php
use App\Traits\ModuleAuditable;
use OwenIt\Auditing\Contracts\Auditable;
class YourModel extends Model implements Auditable
{
use ModuleAuditable;
// Exclude sensitive fields from audit
protected $auditExclude = ['password', 'secret_key'];
}
```
## File Locations
## Key File Locations
| What | Where |
|------|-------|
| Laravel app | `src/` |
| Docker configs | `docker/` |
| Production deploy | `deploy/` |
| Setup scripts | `scripts/` |
| Documentation | `docs/` |
| Module code | `src/app/Modules/` |
| Filament resources | `src/app/Modules/*/Filament/Resources/` |
| Module views | `src/app/Modules/*/Resources/views/` |
| Module routes | `src/app/Modules/*/Routes/` |
| Module migrations | `src/app/Modules/*/Database/Migrations/` |
| 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/` |
## Common Tasks
## Architecture Notes
### Add a New Feature
- 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
1. Create module: `php artisan make:module FeatureName --model=MainModel`
2. Edit migration: `app/Modules/FeatureName/Database/Migrations/`
3. Update model fillables: `app/Modules/FeatureName/Models/`
4. Customize Filament resource: `app/Modules/FeatureName/Filament/Resources/`
5. Run migrations: `php artisan migrate`
6. Seed permissions: `php artisan db:seed --class=PermissionSeeder`
## Code Conventions
### Add a Model to Existing Module
- 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
# Create model manually
php artisan make:model Modules/ModuleName/Models/NewModel -m
# Move migration to module folder
mv database/migrations/*_create_new_models_table.php \
app/Modules/ModuleName/Database/Migrations/
# Add audit trait to model
# Create Filament resource manually or use:
php artisan make:filament-resource NewModel \
--model=App\\Modules\\ModuleName\\Models\\NewModel
```
### Add API Endpoint
```php
// app/Modules/ModuleName/Routes/api.php
Route::prefix('api/module-name')
->middleware(['api', 'auth:sanctum'])
->group(function () {
Route::get('/items', [ItemController::class, 'index']);
Route::post('/items', [ItemController::class, 'store']);
});
```
### Add Permission
```php
// app/Modules/ModuleName/Permissions.php
return [
'module_name.view' => 'View Module',
'module_name.create' => 'Create records',
'module_name.edit' => 'Edit records',
'module_name.delete' => 'Delete records',
'module_name.new_action' => 'New custom action', // Add this
];
```
Then run: `php artisan db:seed --class=PermissionSeeder`
### Customize Filament Resource
```php
// app/Modules/ModuleName/Filament/Resources/ModelResource.php
public static function form(Form $form): Form
{
return $form->schema([
Forms\Components\TextInput::make('name')->required(),
Forms\Components\Select::make('status')
->options(['active' => 'Active', 'inactive' => 'Inactive']),
// Add more fields
]);
}
public static function table(Table $table): Table
{
return $table->columns([
Tables\Columns\TextColumn::make('name')->searchable(),
Tables\Columns\BadgeColumn::make('status'),
// Add more columns
]);
}
```
## Environment
### Development
- Run commands via `make shell` then `php artisan ...`
- Or use `make artisan cmd='...'`
- Database: accessible at `localhost:3306` (MySQL) or `localhost:5432` (PostgreSQL)
- Mail: caught by Mailpit at `localhost:8025`
### Production
- No Docker - native PHP on Ubuntu 24.04
- Web server: Nginx or Apache
- Use `deploy/scripts/server-setup.sh` for initial setup
- Use `deploy/scripts/deploy.sh` for deployments
## Code Style
- **Follow Laravel conventions**
- **Use Pint for formatting**: `make lint`
- **Business logic in Services**, not Controllers
- **Use Form Requests** for validation
- **Use Policies** for authorization
- **Use Resources** for API responses
## Testing
```bash
# Run tests
make test
# With coverage
make test-coverage
# Create test
php artisan make:test Modules/ModuleName/FeatureTest
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 Laravel logs**: `storage/logs/laravel.log`
2. **Check container logs**: `make logs`
3. **Use Telescope** (if installed): `/telescope`
4. **Use Tinker**: `make tinker`
5. **Ignition** shows errors in browser (dev only)
## Gotchas
1. **Module views use namespace**: `view('module-slug::viewname')`
2. **Module routes are prefixed**: `/module-slug/...`
3. **Permissions use snake_case**: `module_name.action`
4. **Filament resources auto-discover** from `Filament/Resources/`
5. **Migrations auto-load** from `Database/Migrations/`
6. **Always run PermissionSeeder** after adding permissions
## Quick Reference
### Artisan Commands
```bash
php artisan make:module Name # Create module
php artisan make:module Name --model=M # With model
php artisan make:filament-resource Name # Filament resource
php artisan make:model Name -m # Model + migration
php artisan make:controller Name # Controller
php artisan make:request Name # Form request
php artisan make:policy Name # Policy
php artisan migrate # Run migrations
php artisan db:seed # Run seeders
php artisan config:clear # Clear config cache
php artisan route:list # List routes
```
### Make Commands
```bash
make up # Start containers
make down # Stop containers
make shell # Shell into app
make artisan cmd='...' # Run artisan
make composer cmd='...' # Run composer
make test # Run tests
make lint # Fix code style
make fresh # Reset database
make logs # View logs
make queue-start # Start queue worker
make queue-logs # View queue logs
make scheduler-start # Start scheduler
make backup # Backup database
make restore file=... # Restore database
```
## Documentation Links
- [GETTING_STARTED.md](GETTING_STARTED.md) - Setup walkthrough
- [README.md](README.md) - Overview
- [docs/modules.md](docs/modules.md) - Module system
- [docs/audit-trail.md](docs/audit-trail.md) - Audit configuration
- [docs/filament-admin.md](docs/filament-admin.md) - Admin panel
- [docs/laravel-setup.md](docs/laravel-setup.md) - Laravel setup options
- [docs/error-logging.md](docs/error-logging.md) - Error tracking
- [docs/queues.md](docs/queues.md) - Background jobs
- [docs/ci-cd.md](docs/ci-cd.md) - GitHub Actions
- [docs/backup.md](docs/backup.md) - Database backup
1. Check `storage/logs/laravel.log` first
2. Container logs: `make logs`
3. Ignition error pages in browser when `APP_DEBUG=true`