generated from theradcoza/Laravel-Docker-Dev-Template
161 lines
5.0 KiB
Markdown
161 lines
5.0 KiB
Markdown
# Bhoza Shift Manager
|
|
|
|
A shift management application for scheduling staff, tracking attendance, and generating timesheets. Built with Laravel 11 and Filament 3.
|
|
|
|
## Features
|
|
|
|
- **Shift Lifecycle** — Create, start, and complete shifts (planned → in_progress → completed)
|
|
- **Staff Roster** — Assign/remove staff to shifts
|
|
- **Attendance Tracking** — Mark attendance (present/absent/not_marked)
|
|
- **Active Shifts Dashboard** — Real-time view of in-progress shifts
|
|
- **Reports** — Filter by date, staff, and status
|
|
- **Timesheets** — Generate employee timesheets
|
|
- **Audit Trail** — Full history of all shift and attendance changes
|
|
- **Role-Based Access** — Admin, manager, editor, viewer roles with granular permissions
|
|
|
|
## Tech Stack
|
|
|
|
| Layer | Technology |
|
|
|-------|------------|
|
|
| Backend | Laravel 11, PHP 8.2+ |
|
|
| Admin Panel | Filament 3.3 |
|
|
| Frontend | Blade + Livewire |
|
|
| Database | MySQL 8 / PostgreSQL 16 / SQLite |
|
|
| Permissions | spatie/laravel-permission |
|
|
| Auditing | owen-it/laravel-auditing |
|
|
| API Auth | Laravel Sanctum |
|
|
| Testing | Pest |
|
|
|
|
## Quick Start
|
|
|
|
## Prerequisites
|
|
|
|
- [Docker Desktop](https://www.docker.com/products/docker-desktop) installed
|
|
- [Docker Compose](https://docs.docker.com/compose/) (usually included with Docker Desktop)
|
|
|
|
## Quick Start
|
|
|
|
1. **Clone the repository:**
|
|
```sh
|
|
git clone <your-repo-url>
|
|
cd bhoza-shift-manager
|
|
```
|
|
|
|
2. **Copy the example environment file:**
|
|
```sh
|
|
cp src/.env.example src/.env
|
|
# Or manually create src/.env based on src/.env.example
|
|
```
|
|
|
|
3. **Start the app with MariaDB:**
|
|
```sh
|
|
docker-compose --profile mysql up -d
|
|
```
|
|
This will start the app, Nginx, MariaDB, Redis, and Mailpit containers.
|
|
|
|
4. **Install Composer dependencies:**
|
|
```sh
|
|
docker-compose exec app composer install
|
|
```
|
|
|
|
5. **Generate the application key:**
|
|
```sh
|
|
docker-compose exec app php artisan key:generate
|
|
```
|
|
|
|
6. **Run database migrations and seeders:**
|
|
```sh
|
|
docker-compose exec app php artisan migrate --seed
|
|
```
|
|
|
|
7. **Access the app:**
|
|
- Web: [http://localhost:8080](http://localhost:8080)
|
|
- Admin: [http://localhost:8080/admin/login](http://localhost:8080/admin/login)
|
|
- Mailpit: [http://localhost:8025](http://localhost:8025)
|
|
|
|
### Setup(Maybe you should run the one above 🤷🏿♂️)
|
|
|
|
```bash
|
|
git clone <repo-url> bhoza-shift-manager
|
|
cd bhoza-shift-manager
|
|
|
|
# Run setup (MySQL is default)
|
|
./setup.sh # Linux/Mac
|
|
setup.bat # Windows
|
|
```
|
|
|
|
### Access
|
|
|
|
| URL | Description |
|
|
|-----|-------------|
|
|
| http://localhost:8080/admin | Admin panel |
|
|
| http://localhost:8025 | Mailpit (email testing) |
|
|
|
|
**Default login:** admin@example.com / password
|
|
|
|
## Roles & Permissions
|
|
|
|
| Role | Access |
|
|
|------|--------|
|
|
| **admin** | Full access to everything |
|
|
| **manager** | All shift operations + reports + timesheets |
|
|
| **editor** | User view/edit |
|
|
| **viewer** | Read-only user list |
|
|
|
|
### 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`
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
src/
|
|
├── app/
|
|
│ ├── Models/
|
|
│ │ ├── Shift.php # Core shift model
|
|
│ │ ├── ShiftStaff.php # Staff assignment pivot
|
|
│ │ ├── ShiftAttendance.php # Attendance records
|
|
│ │ ├── User.php # User with shift relationships
|
|
│ │ └── Setting.php # Site settings
|
|
│ ├── Services/
|
|
│ │ └── ShiftService.php # Business logic
|
|
│ ├── Policies/
|
|
│ │ └── ShiftPolicy.php # Authorization
|
|
│ ├── Filament/
|
|
│ │ ├── Resources/
|
|
│ │ │ ├── ShiftResource.php # Shift CRUD + pages
|
|
│ │ │ └── UserResource.php # User management
|
|
│ │ ├── Pages/
|
|
│ │ │ ├── ActiveShifts.php # In-progress shifts dashboard
|
|
│ │ │ ├── ShiftReports.php # Report generator
|
|
│ │ │ ├── Timesheets.php # Timesheet generation
|
|
│ │ │ ├── StaffManagement.php
|
|
│ │ │ └── Settings.php # Site settings
|
|
│ │ └── Widgets/
|
|
│ │ ├── TodaysShifts.php
|
|
│ │ └── ShiftOverview.php
|
|
│ └── Providers/
|
|
├── database/
|
|
│ ├── migrations/
|
|
│ └── seeders/
|
|
│ ├── DatabaseSeeder.php
|
|
│ └── RolePermissionSeeder.php
|
|
├── resources/views/filament/ # Filament page views
|
|
├── routes/
|
|
│ ├── web.php # Redirects to /admin
|
|
│ └── api.php # API routes
|
|
└── tests/
|
|
```
|
|
|
|
## Common Commands
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `make up DB=mysql` | Start containers |
|
|
| `make down` | Stop containers |
|
|
| `make shell` | Shell into app container |
|
|
| `make artisan cmd='migrate'` | Run Artisan commands |
|
|
| `make fresh` | Fresh migrate + seed |
|
|
| `make test` | Run tests |
|
|
| `make lint` | Fix code style |
|