bert.hausmans/crewli
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: initial commit - Band Management application

Browse Source
This commit is contained in:
Bert Hausmans
2026-01-06 03:11:46 +01:00
commit 34e12e00b3
24543 changed files with 3991790 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

866
.cursor/ARCHITECTURE.md Normal file
View File

@@ -0,0 +1,866 @@
# Band Management - Architecture
> This document describes the system architecture, design decisions, and patterns used in this application.
## System Overview
```
┌─────────────────────────────────────────────────────────────────────────┐
│ INTERNET │
└─────────────────────────────────────────────────────────────────────────┘
│
┌───────────────────────────┼───────────────────────────┐
│ │ │
▼ ▼ ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ Admin SPA │ │ Band SPA │ │ Customer SPA │
│ (Vuexy Full) │ │ (Vuexy Lite) │ │ (Vuexy Lite) │
│ :5173 │ │ :5174 │ │ :5175 │
└───────┬───────┘ └───────┬───────┘ └───────┬───────┘
│ │ │
└───────────────────────────┼───────────────────────────┘
│
▼
┌───────────────────────┐
│ Laravel API │
│ (Sanctum) │
│ :8000 │
└───────────┬───────────┘
│
┌───────────────┼───────────────┐
│ │ │
▼ ▼ ▼
┌───────────┐ ┌───────────┐ ┌───────────┐
│ MySQL │ │ Redis │ │ Mailpit │
│ :3306 │ │ :6379 │ │ :8025 │
└───────────┘ └───────────┘ └───────────┘
```
---
## Applications
### Admin Dashboard (`apps/admin/`)
**Purpose**: Full management interface for band administrators.
**Users**: Band leaders, managers, booking agents
**Features**:
- Member management (CRUD, roles, invitations)
- Event/gig management (calendar, list, RSVP tracking)
- Music catalog (songs, attachments, metadata)
- Setlist builder (drag-drop, templates)
- Location management (venues, contacts)
- Customer CRM (companies, individuals, history)
- Booking request management
- Reports and analytics
**Vuexy Version**: `typescript-version/full-version`
---
### Band Portal (`apps/band/`)
**Purpose**: Member-facing interface for band members.
**Users**: Musicians, performers, crew
**Features**:
- Personal dashboard (upcoming gigs)
- Event calendar with RSVP
- View setlists and music
- Download attachments (lyrics, charts)
- Profile settings
- Notifications
**Vuexy Version**: `typescript-version/starter-kit`
---
### Customer Portal (`apps/customers/`)
**Purpose**: Client-facing interface for customers.
**Users**: Event organizers, venue managers, clients
**Features**:
- View booked events
- Submit booking requests
- Track request status
- View assigned setlists (if permitted)
- Profile settings
**Vuexy Version**: `typescript-version/starter-kit`
---
## API Structure
### Base URL
- Development: `http://localhost:8000/api/v1`
- Production: `https://api.bandmanagement.nl/api/v1`
### Authentication Endpoints
```
POST /auth/register Register new user
POST /auth/login Login, returns token
POST /auth/logout Logout, revokes token
GET /auth/user Get authenticated user
POST /auth/forgot-password Request password reset
POST /auth/reset-password Reset password with token
```
### Resource Endpoints
```
# Events
GET /events List events (paginated, filterable)
POST /events Create event
GET /events/{id} Get event details
PUT /events/{id} Update event
DELETE /events/{id} Delete event
POST /events/{id}/invite Invite members to event
GET /events/{id}/invitations Get event invitations
POST /events/{id}/rsvp Submit RSVP response
POST /events/{id}/duplicate Duplicate event
# Members
GET /members List members
POST /members Create member
GET /members/{id} Get member details
PUT /members/{id} Update member
DELETE /members/{id} Delete/deactivate member
POST /members/invite Send invitation email
# Music
GET /music List music numbers
POST /music Create music number
GET /music/{id} Get music number
PUT /music/{id} Update music number
DELETE /music/{id} Delete music number
POST /music/{id}/attachments Upload attachment
DELETE /music/{id}/attachments/{aid} Delete attachment
# Setlists
GET /setlists List setlists
POST /setlists Create setlist
GET /setlists/{id} Get setlist with items
PUT /setlists/{id} Update setlist
DELETE /setlists/{id} Delete setlist
POST /setlists/{id}/clone Clone setlist
PUT /setlists/{id}/items Reorder/update items
# Locations
GET /locations List locations
POST /locations Create location
GET /locations/{id} Get location
PUT /locations/{id} Update location
DELETE /locations/{id} Delete location
# Customers
GET /customers List customers
POST /customers Create customer
GET /customers/{id} Get customer
PUT /customers/{id} Update customer
DELETE /customers/{id} Delete customer
# Booking Requests (Customer Portal)
GET /booking-requests List user's requests
POST /booking-requests Submit booking request
GET /booking-requests/{id} Get request details
# Notifications
GET /notifications List notifications
PUT /notifications/{id}/read Mark as read
POST /notifications/read-all Mark all as read
```
---
## Database Schema
### Entity Relationship Diagram
```
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ users │ │ customers │ │ locations │
├──────────────┤ ├──────────────┤ ├──────────────┤
│ id (ULID) │──┐ │ id (ULID) │ │ id (ULID) │
│ name │ │ │ user_id (FK) │───────│ name │
│ email │ │ │ name │ │ address │
│ type │ │ │ company_name │ │ city │
│ role │ │ │ type │ │ capacity │
│ status │ │ │ email │ │ contact_* │
└──────────────┘ │ └──────────────┘ └──────────────┘
│ │ │ │
│ │ │ │
▼ │ ▼ ▼
┌──────────────┐ │ ┌──────────────┐ ┌──────────────┐
│event_invites │ │ │ events │───────│ setlists │
├──────────────┤ │ ├──────────────┤ ├──────────────┤
│ id (ULID) │ │ │ id (ULID) │ │ id (ULID) │
│ event_id(FK) │──┼───▶│ title │ │ name │
│ user_id (FK) │──┘ │ location_id │ │ description │
│ rsvp_status │ │ customer_id │ │ is_template │
│ rsvp_note │ │ setlist_id │◀──────│ is_archived │
└──────────────┘ │ event_date │ └──────────────┘
│ status │ │
│ created_by │ │
└──────────────┘ ▼
┌──────────────┐
┌──────────────┐ ┌──────────────┐ │setlist_items │
│music_numbers │───────│music_attach │ ├──────────────┤
├──────────────┤ ├──────────────┤ │ id (ULID) │
│ id (ULID) │ │ id (ULID) │ │ setlist_id │
│ title │ │ music_num_id │ │ music_num_id │
│ artist │ │ file_name │ │ position │
│ duration │ │ file_type │ │ set_number │
│ key, tempo │ │ file_path │ │ is_break │
│ tags (JSON) │ └──────────────┘ └──────────────┘
└──────────────┘
```
### Table Definitions
#### users
| Column | Type | Description |
|--------|------|-------------|
| id | ULID | Primary key |
| name | string | Full name |
| email | string | Unique email |
| email_verified_at | timestamp | Email verification |
| password | string | Hashed password |
| phone | string? | Phone number |
| bio | text? | Biography |
| instruments | json? | Array of instruments |
| avatar_path | string? | Avatar file path |
| type | enum | `member`, `customer` |
| role | enum? | `admin`, `booking_agent`, `music_manager`, `member` |
| status | enum | `active`, `inactive` |
| invited_at | timestamp? | When invited |
| last_login_at | timestamp? | Last login |
| remember_token | string? | Remember me token |
| created_at | timestamp | Created |
| updated_at | timestamp | Updated |
#### customers
| Column | Type | Description |
|--------|------|-------------|
| id | ULID | Primary key |
| user_id | ULID? | FK to users (for portal access) |
| name | string | Contact name |
| company_name | string? | Company name |
| type | enum | `individual`, `company` |
| email | string? | Email |
| phone | string? | Phone |
| address | string? | Street address |
| city | string? | City |
| postal_code | string? | Postal code |
| country | string | Country (default: NL) |
| notes | text? | Internal notes |
| is_portal_enabled | boolean | Can access portal |
| created_at | timestamp | Created |
| updated_at | timestamp | Updated |
#### locations
| Column | Type | Description |
|--------|------|-------------|
| id | ULID | Primary key |
| name | string | Venue name |
| address | string | Street address |
| city | string | City |
| postal_code | string? | Postal code |
| country | string | Country (default: NL) |
| latitude | decimal? | GPS latitude |
| longitude | decimal? | GPS longitude |
| capacity | integer? | Max capacity |
| contact_name | string? | Contact person |
| contact_email | string? | Contact email |
| contact_phone | string? | Contact phone |
| stage_specs | text? | Stage specifications |
| technical_notes | text? | Technical requirements |
| parking_info | text? | Parking information |
| notes | text? | General notes |
| created_at | timestamp | Created |
| updated_at | timestamp | Updated |
#### events
| Column | Type | Description |
|--------|------|-------------|
| id | ULID | Primary key |
| title | string | Event title |
| description | text? | Description |
| location_id | ULID? | FK to locations |
| customer_id | ULID? | FK to customers |
| setlist_id | ULID? | FK to setlists |
| event_date | date | Date of event |
| start_time | time | Start time |
| end_time | time? | End time |
| load_in_time | time? | Load-in time |
| soundcheck_time | time? | Soundcheck time |
| fee | decimal(10,2)? | Payment amount |
| currency | string | Currency (default: EUR) |
| status | enum | `draft`, `pending`, `confirmed`, `completed`, `cancelled` |
| visibility | enum | `private`, `members`, `public` |
| rsvp_deadline | datetime? | RSVP deadline |
| notes | text? | Public notes |
| internal_notes | text? | Admin-only notes |
| is_public_setlist | boolean | Show setlist to customer |
| created_by | ULID | FK to users |
| created_at | timestamp | Created |
| updated_at | timestamp | Updated |
#### event_invitations
| Column | Type | Description |
|--------|------|-------------|
| id | ULID | Primary key |
| event_id | ULID | FK to events |
| user_id | ULID | FK to users |
| rsvp_status | enum | `pending`, `available`, `unavailable`, `tentative` |
| rsvp_note | text? | Response note |
| rsvp_responded_at | timestamp? | When responded |
| invited_at | timestamp | When invited |
| reminder_sent_at | timestamp? | Last reminder |
| created_at | timestamp | Created |
| updated_at | timestamp | Updated |
#### music_numbers
| Column | Type | Description |
|--------|------|-------------|
| id | ULID | Primary key |
| title | string | Song title |
| artist | string? | Original artist |
| genre | string? | Genre/style |
| duration_seconds | integer? | Duration in seconds |
| key | string? | Musical key (e.g., "Am", "G") |
| tempo_bpm | integer? | Tempo in BPM |
| time_signature | string? | Time signature (e.g., "4/4") |
| lyrics | text? | Full lyrics |
| notes | text? | Performance notes |
| tags | json? | Array of tags |
| play_count | integer | Times played (default: 0) |
| last_played_at | timestamp? | Last performed |
| is_active | boolean | Active in catalog |
| created_by | ULID? | FK to users |
| created_at | timestamp | Created |
| updated_at | timestamp | Updated |
#### music_attachments
| Column | Type | Description |
|--------|------|-------------|
| id | ULID | Primary key |
| music_number_id | ULID | FK to music_numbers |
| file_name | string | Stored filename |
| original_name | string | Original filename |
| file_path | string | Storage path |
| file_type | enum | `lyrics`, `chords`, `sheet_music`, `audio`, `other` |
| file_size | integer | Size in bytes |
| mime_type | string | MIME type |
| created_at | timestamp | Created |
| updated_at | timestamp | Updated |
#### setlists
| Column | Type | Description |
|--------|------|-------------|
| id | ULID | Primary key |
| name | string | Setlist name |
| description | text? | Description |
| total_duration_seconds | integer? | Calculated total |
| is_template | boolean | Is a template |
| is_archived | boolean | Archived |
| created_by | ULID? | FK to users |
| created_at | timestamp | Created |
| updated_at | timestamp | Updated |
#### setlist_items
| Column | Type | Description |
|--------|------|-------------|
| id | ULID | Primary key |
| setlist_id | ULID | FK to setlists |
| music_number_id | ULID? | FK to music_numbers |
| position | integer | Order position |
| set_number | integer | Set number (1, 2, 3) |
| is_break | boolean | Is a break |
| break_duration_seconds | integer? | Break length |
| notes | string? | Item notes |
| created_at | timestamp | Created |
| updated_at | timestamp | Updated |
#### booking_requests
| Column | Type | Description |
|--------|------|-------------|
| id | ULID | Primary key |
| customer_id | ULID | FK to customers |
| event_date | date | Requested date |
| start_time | time? | Requested start |
| end_time | time? | Requested end |
| location_name | string? | Venue name |
| location_address | string? | Venue address |
| event_type | string? | Type of event |
| expected_guests | integer? | Guest count |
| message | text? | Request message |
| status | enum | `pending`, `reviewed`, `accepted`, `declined` |
| admin_notes | text? | Admin notes |
| event_id | ULID? | FK to created event |
| reviewed_by | ULID? | FK to users |
| reviewed_at | timestamp? | When reviewed |
| created_at | timestamp | Created |
| updated_at | timestamp | Updated |
#### notifications
| Column | Type | Description |
|--------|------|-------------|
| id | ULID | Primary key |
| user_id | ULID | FK to users |
| type | string | Notification type |
| title | string | Title |
| message | text | Message body |
| data | json? | Additional data |
| action_url | string? | Link URL |
| read_at | timestamp? | When read |
| created_at | timestamp | Created |
| updated_at | timestamp | Updated |
#### activity_logs
| Column | Type | Description |
|--------|------|-------------|
| id | ULID | Primary key |
| user_id | ULID? | FK to users |
| loggable_type | string | Model class |
| loggable_id | ULID | Model ID |
| action | string | Action performed |
| description | text? | Description |
| changes | json? | Before/after data |
| ip_address | string? | Client IP |
| user_agent | string? | Browser info |
| created_at | timestamp | Created |
---
## API Response Format
### Success Response
```json
{
"success": true,
"data": { ... },
"message": "Event created successfully",
"meta": {
"pagination": {
"current_page": 1,
"per_page": 15,
"total": 100,
"last_page": 7,
"from": 1,
"to": 15
}
}
}
```
### Error Response
```json
{
"success": false,
"message": "Validation failed",
"errors": {
"title": ["The title field is required."],
"event_date": ["The event date must be a future date."]
}
}
```
### Single Resource
```json
{
"success": true,
"data": {
"id": "01HQ3K5P7X...",
"title": "Summer Concert",
"event_date": "2025-07-15",
"status": "confirmed",
"location": {
"id": "01HQ3K5P7X...",
"name": "City Park Amphitheater"
},
"created_at": "2025-01-15T10:30:00Z",
"updated_at": "2025-01-15T10:30:00Z"
}
}
```
### Collection (Paginated)
```json
{
"success": true,
"data": [
{ "id": "...", "title": "Event 1" },
{ "id": "...", "title": "Event 2" }
],
"meta": {
"pagination": {
"current_page": 1,
"per_page": 15,
"total": 45,
"last_page": 3
}
}
}
```
---
## User Roles & Permissions
### Roles
| Role | Description |
|------|-------------|
| `admin` | Full access to everything |
| `booking_agent` | Manage events, locations, customers |
| `music_manager` | Manage music catalog and setlists |
| `member` | View events, RSVP, view music |
### Permissions Matrix
| Resource | Admin | Booking Agent | Music Manager | Member |
|----------|-------|---------------|---------------|--------|
| Members | CRUD | Read | Read | Read |
| Events | CRUD | CRUD | Read | Read |
| Locations | CRUD | CRUD | Read | Read |
| Customers | CRUD | CRUD | Read | - |
| Music | CRUD | Read | CRUD | Read |
| Setlists | CRUD | Read | CRUD | Read |
| Booking Requests | CRUD | CRUD | - | - |
| RSVP | All | All | Own | Own |
---
## File Storage
### Structure
```
storage/app/
├── public/
│ ├── avatars/ # User avatars
│ └── music/ # Music attachments
│ ├── lyrics/
│ ├── chords/
│ ├── sheet_music/
│ └── audio/
└── private/
└── exports/ # Generated reports
```
### File Types Allowed
| Type | Extensions | Max Size |
|------|------------|----------|
| Avatar | jpg, png, webp | 2 MB |
| Lyrics | txt, pdf, docx | 5 MB |
| Chords | pdf, png, jpg | 10 MB |
| Sheet Music | pdf, png, jpg | 10 MB |
| Audio | mp3, wav, m4a | 50 MB |
---
## Architectural Decisions
### ADR-001: API-First Architecture
**Status**: Accepted
**Date**: 2025-01-01
**Context**: We need to build a web application with three separate SPAs (Admin, Band, Customers) that may have mobile clients in the future.
**Decision**: Implement a completely separated frontend and backend communicating via RESTful JSON API.
**Consequences**:
- ✅ Frontend and backend can be developed/deployed independently
- ✅ Easy to add mobile or other clients later
- ✅ Clear API contracts
- ✅ Better scalability options
- ⚠️ More complex initial setup
- ⚠️ Requires CORS configuration
---
### ADR-002: Laravel Sanctum for Authentication
**Status**: Accepted
**Date**: 2025-01-01
**Context**: Need authentication for SPAs that's secure and simple to implement.
**Decision**: Use Laravel Sanctum with token-based authentication for the SPAs.
**Alternatives Considered**:
- **Passport**: Too complex for our needs (OAuth2 overkill for first-party SPA)
- **JWT**: Requires token storage in localStorage (XSS vulnerable)
**Consequences**:
- ✅ Simple token-based auth for multiple SPAs
- ✅ Built into Laravel, minimal setup
- ✅ Works well with separate domains
- ⚠️ Need to handle token storage securely
---
### ADR-003: TanStack Query for Server State
**Status**: Accepted
**Date**: 2025-01-01
**Context**: Need efficient data fetching with caching, background updates, and optimistic updates.
**Decision**: Use TanStack Query (Vue Query) for all server state management.
**Consequences**:
- ✅ Automatic caching and deduplication
- ✅ Built-in loading/error states
- ✅ Background refetching
- ✅ Optimistic updates for better UX
- ✅ DevTools for debugging
- ⚠️ Learning curve for query key management
---
### ADR-004: Action Pattern for Business Logic
**Status**: Accepted
**Date**: 2025-01-01
**Context**: Controllers should be thin, and business logic needs to be reusable and testable.
**Decision**: Use single-responsibility Action classes for all business logic.
**Pattern**:
```php
class CreateEventAction
{
public function execute(array $data): Event
{
// Business logic here
}
}
// Usage in controller
public function store(Request $request, CreateEventAction $action)
{
return $action->execute($request->validated());
}
```
**Consequences**:
- ✅ Single Responsibility Principle
- ✅ Easy to test in isolation
- ✅ Reusable across controllers, commands, jobs
- ⚠️ More files to manage
---
### ADR-005: Vuexy for All SPAs
**Status**: Accepted
**Date**: 2025-01-01
**Context**: Need consistent UI across three SPAs with professional admin components.
**Decision**: Use Vuexy Vue template for all SPAs (full version for Admin, starter-kit for Band/Customers).
**Consequences**:
- ✅ Consistent UI/UX across all portals
- ✅ Pre-built admin components
- ✅ Single learning curve for the team
- ✅ Professional look out of the box
- ⚠️ License cost
- ⚠️ Dependency on third-party template
---
## Security Architecture
### Defense in Depth
```
┌─────────────────────────────────────────────────────────────┐
│ 1. Network Layer │
│ - HTTPS only │
│ - Rate limiting │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 2. Application Layer │
│ - CORS validation │
│ - Input validation (Form Requests) │
│ - SQL injection prevention (Eloquent) │
│ - XSS prevention (Vue escaping) │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 3. Authentication & Authorization │
│ - Sanctum token authentication │
│ - Role-based access control │
│ - Resource authorization (Policies) │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 4. Data Layer │
│ - Encrypted connections (TLS) │
│ - Sensitive data hashing (bcrypt) │
│ - Database credentials via environment │
└─────────────────────────────────────────────────────────────┘
```
### CORS Configuration
```php
// config/cors.php
'allowed_origins' => [
'http://localhost:5173', // Admin
'http://localhost:5174', // Band
'http://localhost:5175', // Customers
],
'supports_credentials' => true,
```
---
## Performance Considerations
### Backend Optimizations
1. **Database**
- Eager loading relationships (`with()`)
- Database indexes on filtered/sorted columns
- Query caching for expensive operations
2. **Caching Strategy**
```php
// Cache expensive queries
Cache::remember('stats:dashboard', 3600, fn() =>
$this->calculateStats()
);
```
3. **Queue Heavy Operations**
- Email sending
- File processing
- Report generation
### Frontend Optimizations
1. **Code Splitting**
- Lazy load routes
- Dynamic imports for heavy components
2. **Query Optimization**
```typescript
// Deduplicate requests
useQuery({ queryKey: ['events'], staleTime: 5 * 60 * 1000 })
// Prefetch on hover
queryClient.prefetchQuery({ queryKey: ['event', id] })
```
3. **Bundle Size**
- Tree shaking enabled
- Dynamic imports for routes
---
## Monitoring & Observability
### Logging Strategy
| Level | Use Case | Example |
|-------|----------|---------|
| DEBUG | Development only | Query details, variable dumps |
| INFO | Normal operations | User login, API calls |
| WARNING | Unexpected but handled | Rate limit approached |
| ERROR | Errors requiring attention | Failed payment |
| CRITICAL | System failures | Database down |
### Health Checks
```
GET /api/v1/health
{
"status": "healthy",
"checks": {
"database": "ok",
"redis": "ok",
"queue": "ok"
}
}
```
---
## Model Relationships
**User**
- User has many EventInvitations
- User has many Notifications
- User has many ActivityLogs
- User has many created Events (as creator)
- User has many created MusicNumbers (as creator)
- User has many created Setlists (as creator)
**Event**
- Event belongs to Location (nullable)
- Event belongs to Customer (nullable)
- Event belongs to Setlist (nullable)
- Event belongs to User (created_by)
- Event has many EventInvitations
- Event has many Users through EventInvitations (invited members)
**EventInvitation**
- EventInvitation belongs to Event
- EventInvitation belongs to User
**Location**
- Location has many Events
**Customer**
- Customer belongs to User (nullable, for portal access)
- Customer has many Events
- Customer has many BookingRequests
**MusicNumber**
- MusicNumber belongs to User (created_by, nullable)
- MusicNumber has many MusicAttachments
- MusicNumber has many SetlistItems
- MusicNumber has many Setlists through SetlistItems
**MusicAttachment**
- MusicAttachment belongs to MusicNumber
**Setlist**
- Setlist belongs to User (created_by, nullable)
- Setlist has many SetlistItems
- Setlist has many MusicNumbers through SetlistItems
- Setlist has many Events
**SetlistItem**
- SetlistItem belongs to Setlist
- SetlistItem belongs to MusicNumber (nullable, null when is_break = true)
**BookingRequest**
- BookingRequest belongs to Customer
- BookingRequest belongs to Event (nullable, when accepted)
- BookingRequest belongs to User (reviewed_by, nullable)
**Notification**
- Notification belongs to User
**ActivityLog**
- ActivityLog belongs to User (nullable)
- ActivityLog is polymorphic (loggable_type, loggable_id)
---
*Last updated: 2025-01-01*

318
.cursor/instructions.md Normal file
View File

@@ -0,0 +1,318 @@
# Band Management - Cursor AI Instructions
> This document provides AI assistants with comprehensive context about the project.
> Update this file as the project evolves.
## Project Overview
**Name**: Band Management Platform
**Type**: Full-stack web application (API-first architecture)
**Status**: Development
### Description
Band Management is a full-stack web application designed to streamline band operations by centralizing member coordination, gig management, music cataloging, and setlist planning. The platform serves as the single source of truth for all band-related activities.
## Quick Reference
| Component | Technology | Location | Port |
|-----------|------------|----------|------|
| API | Laravel 12 + Sanctum | `api/` | 8000 |
| Admin Dashboard | Vue 3 + Vuexy (full) | `apps/admin/` | 5173 |
| Band Portal | Vue 3 + Vuexy (starter) | `apps/band/` | 5174 |
| Customer Portal | Vue 3 + Vuexy (starter) | `apps/customers/` | 5175 |
| Database | MySQL 8.0 | Docker | 3306 |
| Cache | Redis | Docker | 6379 |
| Mail | Mailpit | Docker | 8025 |
## Documentation Structure
```
.cursor/
├── instructions.md # This file - overview and quick start
├── ARCHITECTURE.md # System architecture and data models
└── rules/
├── 001_workspace.mdc # Project structure and conventions
├── 100_laravel.mdc # Laravel API patterns
├── 101_vue.mdc # Vue + Vuexy patterns
└── 200_testing.mdc # Testing strategies
```
---
## Core Features
### Authentication & Authorization
- [ ] User registration with email verification
- [ ] User login/logout
- [ ] Password reset functionality
- [ ] Role-based access control (Admin, Booking Agent, Music Manager, Member)
- [ ] Permission middleware for route protection
- [ ] Session management
### Member Management
- [ ] List all members with search and filter
- [ ] Create new member with role assignment
- [ ] Edit member profile and roles
- [ ] Deactivate/reactivate members
- [ ] Member profile page (instruments, bio, contact info)
- [ ] Avatar upload
- [ ] Member invitation via email
- [ ] Activity log per member
### Events/Gigs Management
- [ ] List events with calendar and list view
- [ ] Create event with details (title, date, time, fee, notes)
- [ ] Edit/delete events
- [ ] Link event to location (from Location Manager)
- [ ] Link event to customer (from Customer Manager)
- [ ] Event status workflow (Draft → Pending → Confirmed → Completed → Cancelled)
- [ ] Invite members to event
- [ ] View RSVP responses per event
- [ ] Attach setlist to event
- [ ] Event detail page with all related info
- [ ] Duplicate event functionality
### RSVP System
- [ ] Member receives event invitation notification
- [ ] RSVP response options (Available, Unavailable, Tentative)
- [ ] Add note/reason with RSVP
- [ ] Change RSVP before deadline
- [ ] RSVP deadline per event
- [ ] Overview of member availability per event
- [ ] Automatic reminders for pending RSVPs
### Music Management
- [ ] List all music numbers with search and filter
- [ ] Add music number with metadata (title, artist, genre, duration)
- [ ] Edit/delete music numbers
- [ ] Additional fields: key, tempo (BPM), time signature
- [ ] File attachments (lyrics, chord sheets, audio files)
- [ ] Categorization with tags/genres
- [ ] Notes field for arrangements/cues
### Setlist Manager
- [ ] List all setlists
- [ ] Create setlist with name and description
- [ ] Add music numbers to setlist from catalog
- [ ] Drag-and-drop reordering of songs
- [ ] Add set breaks/intermissions
- [ ] Auto-calculate total duration
- [ ] Clone existing setlist
- [ ] Link setlist to event(s)
- [ ] Delete/archive setlists
### Location Manager
- [ ] List all locations with search
- [ ] Add location with details (name, address, capacity)
- [ ] Edit/delete locations
- [ ] Contact information (phone, email, contact person)
- [ ] Technical specifications (stage size, PA, backline, parking)
- [ ] Notes and special requirements
### Customer Manager
- [ ] List all customers with search
- [ ] Add customer (company or individual)
- [ ] Edit/delete customers
- [ ] Contact details (name, email, phone, address)
- [ ] Customer type classification
- [ ] Notes and preferences
- [ ] View booking history per customer
### Customer Portal
- [ ] Customer dashboard with booked events
- [ ] Submit booking requests
- [ ] Track request status
- [ ] View assigned setlists (if permitted)
- [ ] Profile settings
### Band Member Portal
- [ ] Member dashboard with upcoming events
- [ ] Personal event calendar
- [ ] RSVP management interface
- [ ] View event details (location, time, setlist)
- [ ] Browse music catalog (view-only)
- [ ] View setlists assigned to events
- [ ] Profile settings
- [ ] Notification preferences
### Admin Dashboard
- [ ] Dashboard with statistics/overview
- [ ] Quick actions panel
- [ ] Recent activity feed
- [ ] Upcoming events widget
- [ ] Pending RSVPs overview
- [ ] Booking requests management
### Notifications
- [ ] Email notifications for event invitations
- [ ] RSVP reminder notifications
- [ ] Event update notifications
- [ ] In-app notification center
- [ ] Notification preferences per user
---
## Getting Started Prompts
### 1. Create Laravel API
```
Create a Laravel 12 project in api/ with:
- Sanctum for API authentication
- MySQL configuration (host: 127.0.0.1, db: band_management, user: band_management, pass: secret)
- CORS configured for localhost:5173, localhost:5174, localhost:5175
- API response trait for consistent JSON responses
- Base controller with response helpers
Follow the patterns in .cursor/rules/100_laravel.mdc
```
### 2. Create Database Migrations
```
Create all migrations based on the schema in .cursor/ARCHITECTURE.md:
- Users, Customers, Locations
- Events, EventInvitations
- MusicNumbers, MusicAttachments
- Setlists, SetlistItems
- BookingRequests, Notifications, ActivityLogs
Use ULIDs for primary keys. Follow Laravel conventions.
```
### 3. Create Models with Relationships
```
Create Eloquent models for all tables with:
- HasUlids trait for ULID primary keys
- Proper relationships (belongsTo, hasMany, etc.)
- Fillable arrays
- Casts for enums, dates, and JSON fields
- Scopes for common queries
Follow patterns in .cursor/rules/100_laravel.mdc
```
### 4. Create Authentication System
```
Create auth system with:
- AuthController (login, logout, register, user, forgot-password, reset-password)
- Form requests for validation
- API resources for responses
- Sanctum token generation
Follow patterns in .cursor/rules/100_laravel.mdc
```
### 5. Integrate Vuexy with API
```
I've copied Vuexy Vue (typescript-version/full-version) to apps/admin/.
Update it to:
1. Create src/lib/api-client.ts for API calls with auth token handling
2. Install and configure @tanstack/vue-query
3. Replace Vuexy's fake auth with our Laravel API
4. Update navigation menu for our modules
Follow patterns in .cursor/rules/101_vue.mdc
```
### 6. Create Feature Modules
```
Create the Events module with:
- EventController with CRUD + invite/RSVP endpoints
- StoreEventRequest, UpdateEventRequest for validation
- EventResource, EventCollection for responses
- CreateEventAction, UpdateEventAction for business logic
- EventPolicy for authorization
- Feature tests
Follow patterns in .cursor/rules/100_laravel.mdc and .cursor/rules/200_testing.mdc
```
---
## Common Tasks
### Add a New API Endpoint
1. Create/update Controller in `app/Http/Controllers/Api/V1/`
2. Create Form Request in `app/Http/Requests/Api/V1/`
3. Create/update API Resource in `app/Http/Resources/Api/V1/`
4. Add route in `routes/api.php`
5. Create Action class if complex logic needed
6. Write feature test
### Add a New Vue Page
1. Create page component in `src/pages/`
2. Add route in `src/router/index.ts`
3. Add navigation item in `src/navigation/`
4. Create composable for API calls in `src/composables/`
5. Use Vuexy components for UI
### Add a New Database Table
1. Create migration: `php artisan make:migration create_tablename_table`
2. Create model with relationships
3. Create factory and seeder
4. Create controller, requests, resources
5. Add API routes
6. Write tests
---
## Code Generation Preferences
When generating code, always:
- Use PHP 8.3 features (typed properties, enums, match, readonly)
- Use strict types: `declare(strict_types=1);`
- Use `final` classes for Actions, Form Requests, Resources
- Use ULIDs for all primary keys
- Follow PSR-12 coding standards
- Use TypeScript strict mode in Vue
- Use Vue 3 Composition API with `<script setup lang="ts">`
- Use TanStack Query for API calls
- Return consistent API response format
---
## Environment Setup
### Docker Services
```bash
make services # Start MySQL, Redis, Mailpit
make services-stop # Stop services
```
### Development Servers
```bash
make api # Laravel on :8000
make admin # Admin SPA on :5173
make band # Band Portal on :5174
make customers # Customer Portal on :5175
```
### Database
```bash
make migrate # Run migrations
make fresh # Fresh migrate + seed
make db-shell # MySQL CLI
```

223
.cursor/rules/001_workspace.mdc Normal file
View File

@@ -0,0 +1,223 @@
---
description: Core workspace rules for Laravel + Vue/TypeScript full-stack application
globs: ["**/*"]
alwaysApply: true
---
# Workspace Rules
You are an expert full-stack developer working on a Laravel API backend with a Vue 3/TypeScript frontend using Vuexy admin template. This is an API-first architecture where the backend and frontend are completely separated.
## Tech Stack
### Backend (Laravel)
- PHP 8.3+
- Laravel 12+
- Laravel Sanctum for SPA authentication (token-based)
- MySQL 8.0 database
- Redis for cache and queues
- Pest for testing
### Frontend (Vue)
- Vue 3 with TypeScript (strict mode)
- Vite as build tool
- Vuexy Admin Template
- TanStack Query (Vue Query) for server state
- Pinia for client state
- Vue Router for routing
- Axios for HTTP client
## Project Structure
```
band-management/
├── api/ # Laravel 12 API
│ ├── app/
│ │ ├── Actions/ # Single-purpose business logic
│ │ ├── Enums/ # PHP enums
│ │ ├── Http/
│ │ │ ├── Controllers/Api/V1/
│ │ │ ├── Middleware/
│ │ │ ├── Requests/ # Form Request validation
│ │ │ └── Resources/ # API Resources
│ │ ├── Models/ # Eloquent models
│ │ ├── Policies/ # Authorization
│ │ ├── Services/ # Complex business logic
│ │ └── Traits/ # Shared traits
│ ├── database/
│ │ ├── factories/
│ │ ├── migrations/
│ │ └── seeders/
│ ├── routes/
│ │ └── api.php # API routes
│ └── tests/
│ ├── Feature/Api/
│ └── Unit/
│
├── apps/
│ ├── admin/ # Admin Dashboard (Vuexy full)
│ │ ├── src/
│ │ │ ├── @core/ # Vuexy core (don't modify)
│ │ │ ├── @layouts/ # Vuexy layouts (don't modify)
│ │ │ ├── components/ # Custom components
│ │ │ ├── composables/ # Vue composables
│ │ │ ├── layouts/ # App layouts
│ │ │ ├── lib/ # Utilities (api-client, etc.)
│ │ │ ├── navigation/ # Menu configuration
│ │ │ ├── pages/ # Page components
│ │ │ ├── plugins/ # Vue plugins
│ │ │ ├── router/ # Vue Router
│ │ │ ├── stores/ # Pinia stores
│ │ │ └── types/ # TypeScript types
│ │ └── ...
│ │
│ ├── band/ # Band Portal (Vuexy starter)
│ └── customers/ # Customer Portal (Vuexy starter)
│
├── docker/ # Docker configurations
├── docs/ # Documentation
└── .cursor/ # Cursor AI configuration
```
## Naming Conventions
### PHP (Laravel)
| Type | Convention | Example |
|------|------------|---------|
| Models | Singular PascalCase | `Event`, `MusicNumber` |
| Controllers | PascalCase + Controller | `EventController` |
| Form Requests | Action + Resource + Request | `StoreEventRequest` |
| Resources | Resource + Resource | `EventResource` |
| Actions | Verb + Resource + Action | `CreateEventAction` |
| Migrations | snake_case with timestamp | `create_events_table` |
| Tables | Plural snake_case | `events`, `music_numbers` |
| Columns | snake_case | `event_date`, `created_at` |
| Enums | Singular PascalCase | `EventStatus` |
### TypeScript (Vue)
| Type | Convention | Example |
|------|------------|---------|
| Components | PascalCase | `EventCard.vue` |
| Pages | PascalCase + Page | `EventsPage.vue` |
| Composables | camelCase with "use" | `useEvents.ts` |
| Stores | camelCase | `authStore.ts` |
| Types/Interfaces | PascalCase | `Event`, `ApiResponse` |
| Files | kebab-case or camelCase | `api-client.ts` |
## Code Style
### General Principles
1. **Explicit over implicit** - Be clear about types, returns, and intentions
2. **Small, focused units** - Each file/function does one thing well
3. **Consistent formatting** - Use automated formatters
4. **Descriptive names** - Names should explain purpose
5. **No magic** - Avoid hidden behavior
### PHP
- Use `declare(strict_types=1);` in all files
- Use `final` for classes that shouldn't be extended
- Use readonly properties where applicable
- Prefer named arguments for clarity
- Use enums instead of string constants
### TypeScript
- Enable strict mode in tsconfig
- No `any` types - use `unknown` if truly unknown
- Use interface for objects, type for unions/primitives
- Prefer `const` over `let`
- Use optional chaining and nullish coalescing
## Environment Configuration
### Development URLs
| Service | URL |
|---------|-----|
| API | http://localhost:8000/api/v1 |
| Admin SPA | http://localhost:5173 |
| Band SPA | http://localhost:5174 |
| Customer SPA | http://localhost:5175 |
| MySQL | localhost:3306 |
| Redis | localhost:6379 |
| Mailpit | http://localhost:8025 |
### Database Credentials (Development)
```
Host: 127.0.0.1
Port: 3306
Database: band_management
Username: band_management
Password: secret
```
### Production URLs
| Service | URL |
|---------|-----|
| API | https://api.bandmanagement.nl |
| Admin | https://admin.bandmanagement.nl |
| Band | https://band.bandmanagement.nl |
| Customers | https://customers.bandmanagement.nl |
## Git Conventions
### Branch Names
- `feature/event-management`
- `fix/rsvp-validation`
- `refactor/auth-system`
### Commit Messages
```
feat: add event RSVP functionality
fix: correct date validation in events
refactor: extract event creation to action class
docs: update API documentation
test: add event controller tests
```
## Dependencies
### PHP (api/composer.json)
- PHP 8.3+
- Laravel 12
- Laravel Sanctum
- Laravel Pint (formatting)
- Pest PHP (testing)
### Node (apps/*/package.json)
- Vue 3.4+
- TypeScript 5.3+
- Vite 5+
- Pinia
- @tanstack/vue-query
- axios
## Code Style Principles
1. **Readability over cleverness** - Write code that is easy to understand
2. **Single Responsibility** - Each class/function does one thing well
3. **Type Safety** - Leverage TypeScript and PHP type hints everywhere
4. **Testability** - Write code that is easy to test
5. **API Consistency** - Follow RESTful conventions
## Response Format
When generating code:
1. Always include proper type hints/annotations
2. Add brief comments for complex logic only
3. Follow the established patterns in the codebase
4. Consider error handling and edge cases
5. Suggest tests for new functionality
## Communication Style
- Be concise and direct
- Provide working code examples
- Explain architectural decisions briefly
- Ask clarifying questions only when truly ambiguous

786
.cursor/rules/100_laravel.mdc Normal file
View File

@@ -0,0 +1,786 @@
---
description: Laravel API development guidelines
globs: ["api/**/*.php"]
alwaysApply: true
---
# Laravel API Development Rules
## PHP Conventions
- Use PHP 8.3+ features: constructor property promotion, readonly properties, match expressions
- Use `match` operator over `switch` wherever possible
- Import all classes with `use` statements; avoid fully-qualified class names inline
- Use named arguments for functions with 3+ parameters
- Prefer early returns over nested conditionals
```php
// ✅ Good - constructor property promotion
public function __construct(
private readonly UserRepository $users,
private readonly Mailer $mailer,
) {}
// ✅ Good - early return
public function handle(Request $request): Response
{
if (!$request->user()) {
return response()->json(['error' => 'Unauthorized'], 401);
}
// Main logic here
}
// ❌ Avoid - nested conditionals
public function handle(Request $request): Response
{
if ($request->user()) {
// Nested logic
} else {
return response()->json(['error' => 'Unauthorized'], 401);
}
}
```
## Core Principles
1. **API-only** - No Blade views, no web routes
2. **Thin controllers** - Business logic in Actions
3. **Consistent responses** - Use API Resources and response trait
4. **Validate everything** - Use Form Requests
5. **Authorize properly** - Use Policies
6. **Test thoroughly** - Feature tests for all endpoints
## File Templates
### Model
```php
<?php
declare(strict_types=1);
namespace App\Models;
use App\Enums\EventStatus;
use Illuminate\Database\Eloquent\Concerns\HasUlids;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;
use Illuminate\Database\Eloquent\Relations\HasMany;
final class Event extends Model
{
use HasFactory;
use HasUlids;
protected $fillable = [
'title',
'description',
'location_id',
'customer_id',
'setlist_id',
'event_date',
'start_time',
'end_time',
'fee',
'currency',
'status',
'visibility',
'rsvp_deadline',
'notes',
'internal_notes',
'created_by',
];
protected $casts = [
'event_date' => 'date',
'start_time' => 'datetime:H:i',
'end_time' => 'datetime:H:i',
'fee' => 'decimal:2',
'status' => EventStatus::class,
'rsvp_deadline' => 'datetime',
];
// Relationships
public function location(): BelongsTo
{
return $this->belongsTo(Location::class);
}
public function customer(): BelongsTo
{
return $this->belongsTo(Customer::class);
}
public function setlist(): BelongsTo
{
return $this->belongsTo(Setlist::class);
}
public function creator(): BelongsTo
{
return $this->belongsTo(User::class, 'created_by');
}
public function invitations(): HasMany
{
return $this->hasMany(EventInvitation::class);
}
// Scopes
public function scopeUpcoming($query)
{
return $query->where('event_date', '>=', now()->toDateString())
->orderBy('event_date');
}
public function scopeConfirmed($query)
{
return $query->where('status', EventStatus::Confirmed);
}
}
```
### Enum
```php
<?php
declare(strict_types=1);
namespace App\Enums;
enum EventStatus: string
{
case Draft = 'draft';
case Pending = 'pending';
case Confirmed = 'confirmed';
case Completed = 'completed';
case Cancelled = 'cancelled';
public function label(): string
{
return match ($this) {
self::Draft => 'Draft',
self::Pending => 'Pending Confirmation',
self::Confirmed => 'Confirmed',
self::Completed => 'Completed',
self::Cancelled => 'Cancelled',
};
}
public function color(): string
{
return match ($this) {
self::Draft => 'gray',
self::Pending => 'yellow',
self::Confirmed => 'green',
self::Completed => 'blue',
self::Cancelled => 'red',
};
}
}
```
### Migration
```php
<?php
declare(strict_types=1);
use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;
return new class extends Migration
{
public function up(): void
{
Schema::create('events', function (Blueprint $table) {
$table->ulid('id')->primary();
$table->string('title');
$table->text('description')->nullable();
$table->foreignUlid('location_id')->nullable()->constrained()->nullOnDelete();
$table->foreignUlid('customer_id')->nullable()->constrained()->nullOnDelete();
$table->foreignUlid('setlist_id')->nullable()->constrained()->nullOnDelete();
$table->date('event_date');
$table->time('start_time');
$table->time('end_time')->nullable();
$table->time('load_in_time')->nullable();
$table->time('soundcheck_time')->nullable();
$table->decimal('fee', 10, 2)->nullable();
$table->string('currency', 3)->default('EUR');
$table->enum('status', ['draft', 'pending', 'confirmed', 'completed', 'cancelled'])->default('draft');
$table->enum('visibility', ['private', 'members', 'public'])->default('members');
$table->dateTime('rsvp_deadline')->nullable();
$table->text('notes')->nullable();
$table->text('internal_notes')->nullable();
$table->boolean('is_public_setlist')->default(false);
$table->foreignUlid('created_by')->constrained('users');
$table->timestamps();
$table->index(['event_date', 'status']);
});
}
public function down(): void
{
Schema::dropIfExists('events');
}
};
```
### Controller
```php
<?php
declare(strict_types=1);
namespace App\Http\Controllers\Api\V1;
use App\Actions\Events\CreateEventAction;
use App\Actions\Events\UpdateEventAction;
use App\Http\Controllers\Controller;
use App\Http\Requests\Api\V1\StoreEventRequest;
use App\Http\Requests\Api\V1\UpdateEventRequest;
use App\Http\Resources\Api\V1\EventCollection;
use App\Http\Resources\Api\V1\EventResource;
use App\Models\Event;
use Illuminate\Http\JsonResponse;
final class EventController extends Controller
{
public function index(): EventCollection
{
$events = Event::query()
->with(['location', 'customer'])
->latest('event_date')
->paginate();
return new EventCollection($events);
}
public function store(StoreEventRequest $request, CreateEventAction $action): JsonResponse
{
$event = $action->execute($request->validated());
return $this->created(
new EventResource($event->load(['location', 'customer'])),
'Event created successfully'
);
}
public function show(Event $event): EventResource
{
return new EventResource(
$event->load(['location', 'customer', 'setlist', 'invitations.user'])
);
}
public function update(UpdateEventRequest $request, Event $event, UpdateEventAction $action): JsonResponse
{
$event = $action->execute($event, $request->validated());
return $this->success(
new EventResource($event),
'Event updated successfully'
);
}
public function destroy(Event $event): JsonResponse
{
$event->delete();
return $this->success(null, 'Event deleted successfully');
}
}
```
### Form Request
```php
<?php
declare(strict_types=1);
namespace App\Http\Requests\Api\V1;
use App\Enums\EventStatus;
use App\Enums\EventVisibility;
use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Validation\Rule;
final class StoreEventRequest extends FormRequest
{
public function authorize(): bool
{
return true; // Or use policy
}
public function rules(): array
{
return [
'title' => ['required', 'string', 'max:255'],
'description' => ['nullable', 'string', 'max:5000'],
'location_id' => ['nullable', 'ulid', 'exists:locations,id'],
'customer_id' => ['nullable', 'ulid', 'exists:customers,id'],
'setlist_id' => ['nullable', 'ulid', 'exists:setlists,id'],
'event_date' => ['required', 'date', 'after_or_equal:today'],
'start_time' => ['required', 'date_format:H:i'],
'end_time' => ['nullable', 'date_format:H:i', 'after:start_time'],
'load_in_time' => ['nullable', 'date_format:H:i'],
'soundcheck_time' => ['nullable', 'date_format:H:i'],
'fee' => ['nullable', 'numeric', 'min:0', 'max:999999.99'],
'currency' => ['sometimes', 'string', 'size:3'],
'status' => ['sometimes', Rule::enum(EventStatus::class)],
'visibility' => ['sometimes', Rule::enum(EventVisibility::class)],
'rsvp_deadline' => ['nullable', 'date', 'before:event_date'],
'notes' => ['nullable', 'string', 'max:5000'],
'internal_notes' => ['nullable', 'string', 'max:5000'],
];
}
public function messages(): array
{
return [
'event_date.after_or_equal' => 'The event date must be today or a future date.',
'end_time.after' => 'The end time must be after the start time.',
];
}
}
```
### API Resource
```php
<?php
declare(strict_types=1);
namespace App\Http\Resources\Api\V1;
use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;
final class EventResource extends JsonResource
{
public function toArray(Request $request): array
{
return [
'id' => $this->id,
'title' => $this->title,
'description' => $this->description,
'event_date' => $this->event_date->toDateString(),
'start_time' => $this->start_time?->format('H:i'),
'end_time' => $this->end_time?->format('H:i'),
'load_in_time' => $this->load_in_time?->format('H:i'),
'soundcheck_time' => $this->soundcheck_time?->format('H:i'),
'fee' => $this->fee,
'currency' => $this->currency,
'status' => $this->status->value,
'status_label' => $this->status->label(),
'visibility' => $this->visibility,
'rsvp_deadline' => $this->rsvp_deadline?->toIso8601String(),
'notes' => $this->notes,
'internal_notes' => $this->when(
$request->user()?->isAdmin(),
$this->internal_notes
),
'location' => new LocationResource($this->whenLoaded('location')),
'customer' => new CustomerResource($this->whenLoaded('customer')),
'setlist' => new SetlistResource($this->whenLoaded('setlist')),
'invitations' => EventInvitationResource::collection(
$this->whenLoaded('invitations')
),
'created_at' => $this->created_at->toIso8601String(),
'updated_at' => $this->updated_at->toIso8601String(),
];
}
}
```
### Resource Collection
```php
<?php
declare(strict_types=1);
namespace App\Http\Resources\Api\V1;
use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\ResourceCollection;
final class EventCollection extends ResourceCollection
{
public $collects = EventResource::class;
public function toArray(Request $request): array
{
return [
'data' => $this->collection,
];
}
public function with(Request $request): array
{
return [
'success' => true,
'meta' => [
'pagination' => [
'current_page' => $this->currentPage(),
'per_page' => $this->perPage(),
'total' => $this->total(),
'last_page' => $this->lastPage(),
'from' => $this->firstItem(),
'to' => $this->lastItem(),
],
],
];
}
}
```
### Action Class
```php
<?php
declare(strict_types=1);
namespace App\Actions\Events;
use App\Models\Event;
use Illuminate\Support\Facades\Auth;
final class CreateEventAction
{
public function execute(array $data): Event
{
$data['created_by'] = Auth::id();
return Event::create($data);
}
}
```
### API Response Trait
```php
<?php
declare(strict_types=1);
namespace App\Traits;
use Illuminate\Http\JsonResponse;
trait ApiResponse
{
protected function success(mixed $data = null, string $message = 'Success', int $code = 200): JsonResponse
{
return response()->json([
'success' => true,
'data' => $data,
'message' => $message,
], $code);
}
protected function created(mixed $data = null, string $message = 'Created'): JsonResponse
{
return $this->success($data, $message, 201);
}
protected function error(string $message, int $code = 400, array $errors = []): JsonResponse
{
$response = [
'success' => false,
'message' => $message,
];
if (!empty($errors)) {
$response['errors'] = $errors;
}
return response()->json($response, $code);
}
protected function notFound(string $message = 'Resource not found'): JsonResponse
{
return $this->error($message, 404);
}
protected function unauthorized(string $message = 'Unauthorized'): JsonResponse
{
return $this->error($message, 401);
}
protected function forbidden(string $message = 'Forbidden'): JsonResponse
{
return $this->error($message, 403);
}
}
```
### Base Controller
```php
<?php
declare(strict_types=1);
namespace App\Http\Controllers;
use App\Traits\ApiResponse;
abstract class Controller
{
use ApiResponse;
}
```
### Policy
```php
<?php
declare(strict_types=1);
namespace App\Policies;
use App\Models\Event;
use App\Models\User;
final class EventPolicy
{
public function viewAny(User $user): bool
{
return true;
}
public function view(User $user, Event $event): bool
{
return true;
}
public function create(User $user): bool
{
return $user->isAdmin() || $user->isBookingAgent();
}
public function update(User $user, Event $event): bool
{
return $user->isAdmin() || $user->isBookingAgent();
}
public function delete(User $user, Event $event): bool
{
return $user->isAdmin();
}
}
```
### Routes (api.php)
```php
<?php
declare(strict_types=1);
use App\Http\Controllers\Api\V1\AuthController;
use App\Http\Controllers\Api\V1\EventController;
use App\Http\Controllers\Api\V1\LocationController;
use App\Http\Controllers\Api\V1\MemberController;
use App\Http\Controllers\Api\V1\MusicController;
use App\Http\Controllers\Api\V1\SetlistController;
use App\Http\Controllers\Api\V1\CustomerController;
use Illuminate\Support\Facades\Route;
Route::prefix('v1')->group(function () {
// Public routes
Route::post('auth/login', [AuthController::class, 'login']);
Route::post('auth/register', [AuthController::class, 'register']);
Route::post('auth/forgot-password', [AuthController::class, 'forgotPassword']);
Route::post('auth/reset-password', [AuthController::class, 'resetPassword']);
// Protected routes
Route::middleware('auth:sanctum')->group(function () {
// Auth
Route::get('auth/user', [AuthController::class, 'user']);
Route::post('auth/logout', [AuthController::class, 'logout']);
// Resources
Route::apiResource('events', EventController::class);
Route::post('events/{event}/invite', [EventController::class, 'invite']);
Route::post('events/{event}/rsvp', [EventController::class, 'rsvp']);
Route::apiResource('members', MemberController::class);
Route::apiResource('music', MusicController::class);
Route::apiResource('setlists', SetlistController::class);
Route::apiResource('locations', LocationController::class);
Route::apiResource('customers', CustomerController::class);
});
});
```
## Best Practices
### Always Use
- `declare(strict_types=1)` at the top of every file
- `final` keyword for Action classes, Form Requests, Resources
- Type hints for all parameters and return types
- Named arguments for better readability
- Enums for status fields and fixed options
- ULIDs for all primary keys
- Eager loading to prevent N+1 queries
- API Resources for all responses
### Avoid
- Business logic in controllers
- String constants (use enums)
- Auto-increment IDs
- Direct model creation in controllers
- Returning raw models (use Resources)
- Hardcoded strings for error messages
## DTOs (Data Transfer Objects)
Use DTOs for complex data passing between layers:
```php
<?php
declare(strict_types=1);
namespace App\DTOs;
readonly class CreateEventDTO
{
public function __construct(
public string $title,
public string $eventDate,
public string $startTime,
public ?string $description = null,
public ?string $locationId = null,
public ?string $customerId = null,
public ?string $endTime = null,
public ?float $fee = null,
) {}
public static function from(array $data): self
{
return new self(
title: $data['title'],
eventDate: $data['event_date'],
startTime: $data['start_time'],
description: $data['description'] ?? null,
locationId: $data['location_id'] ?? null,
customerId: $data['customer_id'] ?? null,
endTime: $data['end_time'] ?? null,
fee: $data['fee'] ?? null,
);
}
}
// Usage
$dto = CreateEventDTO::from($request->validated());
$event = $action->execute($dto);
```
## Helpers
Use Laravel helpers instead of facades:
```php
// ✅ Good
auth()->id()
auth()->user()
now()
str($string)->slug()
collect($array)->filter()
cache()->remember('key', 3600, fn() => $value)
// ❌ Avoid
Auth::id()
Carbon::now()
Str::slug($string)
Cache::remember(...)
```
## Error Handling
Create domain-specific exceptions:
```php
<?php
declare(strict_types=1);
namespace App\Exceptions;
use Exception;
use Illuminate\Http\JsonResponse;
class EventNotFoundException extends Exception
{
public function render(): JsonResponse
{
return response()->json([
'success' => false,
'message' => 'Event not found',
], 404);
}
}
class EventAlreadyConfirmedException extends Exception
{
public function render(): JsonResponse
{
return response()->json([
'success' => false,
'message' => 'Event has already been confirmed and cannot be modified',
], 422);
}
}
// Usage in Action
if ($event->isConfirmed()) {
throw new EventAlreadyConfirmedException();
}
```
## Query Scopes
Add reusable query scopes to models:
```php
// In Event model
public function scopeUpcoming(Builder $query): Builder
{
return $query->where('event_date', '>=', now()->toDateString())
->orderBy('event_date');
}
public function scopeForUser(Builder $query, User $user): Builder
{
return $query->whereHas('invitations', fn ($q) =>
$q->where('user_id', $user->id)
);
}
public function scopeConfirmed(Builder $query): Builder
{
return $query->where('status', EventStatus::Confirmed);
}
// Usage
Event::upcoming()->confirmed()->get();
Event::forUser($user)->upcoming()->get();
```

1056
.cursor/rules/101_vue.mdc Normal file
View File

File diff suppressed because it is too large Load Diff

870
.cursor/rules/200_testing.mdc Normal file
View File

@@ -0,0 +1,870 @@
---
description: Testing standards for Laravel API and Vue frontend
globs: ["**/tests/**", "**/*.test.ts", "**/*.test.tsx", "**/*.spec.ts", "**/*.spec.tsx", "**/Test.php"]
alwaysApply: true
---
# Testing Standards
## Philosophy
1. **Test behavior, not implementation** - Focus on what, not how
2. **Feature tests for APIs** - Test full request/response cycles
3. **Unit tests for logic** - Test Actions and complex functions
4. **Integration tests for Vue** - Test component interactions
5. **Fast and isolated** - Each test should be independent
## Laravel Testing
### Directory Structure
```
api/tests/
├── Feature/
│ └── Api/
│ ├── AuthTest.php
│ ├── EventTest.php
│ ├── MemberTest.php
│ ├── MusicTest.php
│ ├── SetlistTest.php
│ ├── LocationTest.php
│ └── CustomerTest.php
├── Unit/
│ ├── Actions/
│ │ ├── CreateEventActionTest.php
│ │ └── ...
│ └── Models/
│ ├── EventTest.php
│ └── ...
└── TestCase.php
```
### Feature Test Template
```php
<?php
declare(strict_types=1);
namespace Tests\Feature\Api;
use App\Enums\EventStatus;
use App\Models\Event;
use App\Models\Location;
use App\Models\User;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;
final class EventTest extends TestCase
{
use RefreshDatabase;
private User $admin;
private User $member;
protected function setUp(): void
{
parent::setUp();
$this->admin = User::factory()->admin()->create();
$this->member = User::factory()->member()->create();
}
// ==========================================
// INDEX
// ==========================================
public function test_guests_cannot_list_events(): void
{
$response = $this->getJson('/api/v1/events');
$response->assertStatus(401);
}
public function test_authenticated_users_can_list_events(): void
{
Event::factory()->count(3)->create();
$response = $this->actingAs($this->member)
->getJson('/api/v1/events');
$response->assertStatus(200)
->assertJsonStructure([
'success',
'data' => [
'*' => ['id', 'title', 'event_date', 'status'],
],
'meta' => ['pagination'],
])
->assertJsonCount(3, 'data');
}
public function test_events_are_paginated(): void
{
Event::factory()->count(20)->create();
$response = $this->actingAs($this->member)
->getJson('/api/v1/events?per_page=10');
$response->assertStatus(200)
->assertJsonCount(10, 'data')
->assertJsonPath('meta.pagination.total', 20)
->assertJsonPath('meta.pagination.per_page', 10);
}
// ==========================================
// SHOW
// ==========================================
public function test_can_view_single_event(): void
{
$event = Event::factory()->create(['title' => 'Summer Concert']);
$response = $this->actingAs($this->member)
->getJson("/api/v1/events/{$event->id}");
$response->assertStatus(200)
->assertJsonPath('success', true)
->assertJsonPath('data.title', 'Summer Concert');
}
public function test_returns_404_for_nonexistent_event(): void
{
$response = $this->actingAs($this->member)
->getJson('/api/v1/events/nonexistent-id');
$response->assertStatus(404);
}
// ==========================================
// STORE
// ==========================================
public function test_admin_can_create_event(): void
{
$location = Location::factory()->create();
$eventData = [
'title' => 'New Year Concert',
'event_date' => now()->addMonth()->toDateString(),
'start_time' => '20:00',
'location_id' => $location->id,
'status' => 'draft',
];
$response = $this->actingAs($this->admin)
->postJson('/api/v1/events', $eventData);
$response->assertStatus(201)
->assertJsonPath('success', true)
->assertJsonPath('data.title', 'New Year Concert');
$this->assertDatabaseHas('events', [
'title' => 'New Year Concert',
'location_id' => $location->id,
]);
}
public function test_member_cannot_create_event(): void
{
$eventData = [
'title' => 'Unauthorized Event',
'event_date' => now()->addMonth()->toDateString(),
'start_time' => '20:00',
];
$response = $this->actingAs($this->member)
->postJson('/api/v1/events', $eventData);
$response->assertStatus(403);
}
public function test_validation_errors_are_returned(): void
{
$response = $this->actingAs($this->admin)
->postJson('/api/v1/events', []);
$response->assertStatus(422)
->assertJsonPath('success', false)
->assertJsonValidationErrors(['title', 'event_date', 'start_time']);
}
public function test_event_date_must_be_future(): void
{
$response = $this->actingAs($this->admin)
->postJson('/api/v1/events', [
'title' => 'Past Event',
'event_date' => now()->subDay()->toDateString(),
'start_time' => '20:00',
]);
$response->assertStatus(422)
->assertJsonValidationErrors(['event_date']);
}
// ==========================================
// UPDATE
// ==========================================
public function test_admin_can_update_event(): void
{
$event = Event::factory()->create(['title' => 'Old Title']);
$response = $this->actingAs($this->admin)
->putJson("/api/v1/events/{$event->id}", [
'title' => 'Updated Title',
]);
$response->assertStatus(200)
->assertJsonPath('data.title', 'Updated Title');
$this->assertDatabaseHas('events', [
'id' => $event->id,
'title' => 'Updated Title',
]);
}
public function test_can_update_event_status(): void
{
$event = Event::factory()->draft()->create();
$response = $this->actingAs($this->admin)
->putJson("/api/v1/events/{$event->id}", [
'status' => 'confirmed',
]);
$response->assertStatus(200)
->assertJsonPath('data.status', 'confirmed');
}
// ==========================================
// DELETE
// ==========================================
public function test_admin_can_delete_event(): void
{
$event = Event::factory()->create();
$response = $this->actingAs($this->admin)
->deleteJson("/api/v1/events/{$event->id}");
$response->assertStatus(200)
->assertJsonPath('success', true);
$this->assertDatabaseMissing('events', ['id' => $event->id]);
}
public function test_member_cannot_delete_event(): void
{
$event = Event::factory()->create();
$response = $this->actingAs($this->member)
->deleteJson("/api/v1/events/{$event->id}");
$response->assertStatus(403);
$this->assertDatabaseHas('events', ['id' => $event->id]);
}
// ==========================================
// RELATIONSHIPS
// ==========================================
public function test_event_includes_location_when_loaded(): void
{
$location = Location::factory()->create(['name' => 'City Hall']);
$event = Event::factory()->create(['location_id' => $location->id]);
$response = $this->actingAs($this->member)
->getJson("/api/v1/events/{$event->id}");
$response->assertStatus(200)
->assertJsonPath('data.location.name', 'City Hall');
}
}
```
### Unit Test Template (Action)
```php
<?php
declare(strict_types=1);
namespace Tests\Unit\Actions;
use App\Actions\Events\CreateEventAction;
use App\Models\Event;
use App\Models\User;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;
final class CreateEventActionTest extends TestCase
{
use RefreshDatabase;
private CreateEventAction $action;
protected function setUp(): void
{
parent::setUp();
$this->action = new CreateEventAction();
}
public function test_creates_event_with_valid_data(): void
{
$user = User::factory()->create();
$this->actingAs($user);
$data = [
'title' => 'Test Event',
'event_date' => now()->addMonth()->toDateString(),
'start_time' => '20:00',
];
$event = $this->action->execute($data);
$this->assertInstanceOf(Event::class, $event);
$this->assertEquals('Test Event', $event->title);
$this->assertEquals($user->id, $event->created_by);
}
public function test_sets_default_values(): void
{
$user = User::factory()->create();
$this->actingAs($user);
$event = $this->action->execute([
'title' => 'Test',
'event_date' => now()->addMonth()->toDateString(),
'start_time' => '20:00',
]);
$this->assertEquals('EUR', $event->currency);
$this->assertEquals('draft', $event->status->value);
}
}
```
### Model Factory Template
```php
<?php
declare(strict_types=1);
namespace Database\Factories;
use App\Enums\EventStatus;
use App\Enums\EventVisibility;
use App\Models\Event;
use App\Models\Location;
use App\Models\User;
use Illuminate\Database\Eloquent\Factories\Factory;
/**
* @extends Factory<Event>
*/
final class EventFactory extends Factory
{
protected $model = Event::class;
public function definition(): array
{
return [
'title' => fake()->sentence(3),
'description' => fake()->optional()->paragraph(),
'event_date' => fake()->dateTimeBetween('+1 week', '+6 months'),
'start_time' => fake()->time('H:i'),
'end_time' => fake()->optional()->time('H:i'),
'fee' => fake()->optional()->randomFloat(2, 100, 5000),
'currency' => 'EUR',
'status' => fake()->randomElement(EventStatus::cases()),
'visibility' => EventVisibility::Members,
'created_by' => User::factory(),
];
}
public function draft(): static
{
return $this->state(fn () => ['status' => EventStatus::Draft]);
}
public function confirmed(): static
{
return $this->state(fn () => ['status' => EventStatus::Confirmed]);
}
public function withLocation(): static
{
return $this->state(fn () => ['location_id' => Location::factory()]);
}
public function upcoming(): static
{
return $this->state(fn () => [
'event_date' => fake()->dateTimeBetween('+1 day', '+1 month'),
'status' => EventStatus::Confirmed,
]);
}
public function past(): static
{
return $this->state(fn () => [
'event_date' => fake()->dateTimeBetween('-6 months', '-1 day'),
'status' => EventStatus::Completed,
]);
}
}
```
### User Factory States
```php
<?php
// In UserFactory.php
public function admin(): static
{
return $this->state(fn () => [
'type' => 'member',
'role' => 'admin',
'status' => 'active',
]);
}
public function member(): static
{
return $this->state(fn () => [
'type' => 'member',
'role' => 'member',
'status' => 'active',
]);
}
public function bookingAgent(): static
{
return $this->state(fn () => [
'type' => 'member',
'role' => 'booking_agent',
'status' => 'active',
]);
}
public function customer(): static
{
return $this->state(fn () => [
'type' => 'customer',
'role' => null,
'status' => 'active',
]);
}
```
### Test Helpers (TestCase.php)
```php
<?php
declare(strict_types=1);
namespace Tests;
use App\Models\User;
use Illuminate\Foundation\Testing\TestCase as BaseTestCase;
abstract class TestCase extends BaseTestCase
{
/**
* Create and authenticate as admin user.
*/
protected function actingAsAdmin(): User
{
$admin = User::factory()->admin()->create();
$this->actingAs($admin);
return $admin;
}
/**
* Create and authenticate as regular member.
*/
protected function actingAsMember(): User
{
$member = User::factory()->member()->create();
$this->actingAs($member);
return $member;
}
/**
* Assert API success response structure.
*/
protected function assertApiSuccess($response, int $status = 200): void
{
$response->assertStatus($status)
->assertJsonStructure(['success', 'data'])
->assertJsonPath('success', true);
}
/**
* Assert API error response structure.
*/
protected function assertApiError($response, int $status = 400): void
{
$response->assertStatus($status)
->assertJsonPath('success', false)
->assertJsonStructure(['success', 'message']);
}
}
```
## Running Tests
### Laravel
```bash
# Run all tests
cd api && php artisan test
# Run with coverage
php artisan test --coverage
# Run specific test file
php artisan test tests/Feature/Api/EventTest.php
# Run specific test method
php artisan test --filter test_admin_can_create_event
# Run in parallel
php artisan test --parallel
```
### Pest PHP Syntax
```php
<?php
use App\Models\Event;
use App\Models\User;
beforeEach(function () {
$this->admin = User::factory()->admin()->create();
});
it('allows admin to create events', function () {
$response = $this->actingAs($this->admin)
->postJson('/api/v1/events', [
'title' => 'Concert',
'event_date' => now()->addMonth()->toDateString(),
'start_time' => '20:00',
]);
$response->assertStatus(201);
expect(Event::count())->toBe(1);
});
it('validates required fields', function () {
$response = $this->actingAs($this->admin)
->postJson('/api/v1/events', []);
$response->assertStatus(422)
->assertJsonValidationErrors(['title', 'event_date']);
});
it('returns paginated results', function () {
Event::factory()->count(25)->create();
$response = $this->actingAs($this->admin)
->getJson('/api/v1/events?per_page=10');
expect($response->json('data'))->toHaveCount(10);
expect($response->json('meta.pagination.total'))->toBe(25);
});
```
## Vue Testing (Vitest + Vue Test Utils)
### File Organization
```
src/
├── components/
│ └── EventCard/
│ ├── EventCard.vue
│ └── EventCard.test.ts
├── composables/
│ └── useEvents.test.ts
└── test/
├── setup.ts
├── mocks/
│ ├── handlers.ts # MSW handlers
│ └── server.ts
└── utils.ts # Custom render with providers
```
### Vitest Configuration
```typescript
// vitest.config.ts
import { defineConfig } from 'vitest/config'
import vue from '@vitejs/plugin-vue'
import { fileURLToPath } from 'node:url'
export default defineConfig({
plugins: [vue()],
test: {
environment: 'jsdom',
globals: true,
setupFiles: ['./src/test/setup.ts'],
},
resolve: {
alias: {
'@': fileURLToPath(new URL('./src', import.meta.url)),
},
},
})
```
### Test Setup
```typescript
// src/test/setup.ts
import { vi, beforeAll, afterAll, afterEach } from 'vitest'
import { config } from '@vue/test-utils'
import { server } from './mocks/server'
// Start MSW server
beforeAll(() => server.listen({ onUnhandledRequest: 'error' }))
afterEach(() => server.resetHandlers())
afterAll(() => server.close())
// Global stubs for Vuexy components
config.global.stubs = {
VBtn: true,
VCard: true,
VCardText: true,
VCardTitle: true,
VTable: true,
VDialog: true,
VProgressCircular: true,
RouterLink: true,
}
```
### MSW Setup for API Mocking
```typescript
// src/test/mocks/handlers.ts
import { http, HttpResponse } from 'msw'
export const handlers = [
http.get('/api/v1/events', () => {
return HttpResponse.json({
success: true,
data: [
{ id: '1', title: 'Event 1', status: 'confirmed' },
{ id: '2', title: 'Event 2', status: 'draft' },
{ id: '3', title: 'Event 3', status: 'pending' },
],
meta: { pagination: { current_page: 1, total: 3, per_page: 15 } }
})
}),
http.post('/api/v1/events', async ({ request }) => {
const body = await request.json()
return HttpResponse.json({
success: true,
data: { id: '4', ...body },
message: 'Event created successfully'
}, { status: 201 })
}),
http.get('/api/v1/auth/user', () => {
return HttpResponse.json({
success: true,
data: { id: '1', name: 'Test User', email: 'test@example.com', role: 'admin' }
})
}),
]
// src/test/mocks/server.ts
import { setupServer } from 'msw/node'
import { handlers } from './handlers'
export const server = setupServer(...handlers)
```
### Test Utilities
```typescript
// src/test/utils.ts
import { mount, VueWrapper } from '@vue/test-utils'
import { createPinia, setActivePinia } from 'pinia'
import { QueryClient, VueQueryPlugin } from '@tanstack/vue-query'
import { createRouter, createWebHistory } from 'vue-router'
import type { Component } from 'vue'
export function createTestingPinia() {
const pinia = createPinia()
setActivePinia(pinia)
return pinia
}
export function createTestQueryClient() {
return new QueryClient({
defaultOptions: {
queries: { retry: false, gcTime: 0 },
mutations: { retry: false },
},
})
}
export function mountWithProviders(component: Component, options = {}) {
const pinia = createTestingPinia()
const queryClient = createTestQueryClient()
const router = createRouter({
history: createWebHistory(),
routes: [{ path: '/', component: { template: '<div />' } }],
})
return mount(component, {
global: {
plugins: [pinia, router, [VueQueryPlugin, { queryClient }]],
stubs: {
VBtn: true,
VCard: true,
VTable: true,
},
},
...options,
})
}
```
### Component Test Pattern
```typescript
// src/components/EventCard.test.ts
import { describe, it, expect, vi } from 'vitest'
import { mount } from '@vue/test-utils'
import EventCard from './EventCard.vue'
describe('EventCard', () => {
const mockEvent = {
id: '1',
title: 'Summer Concert',
event_date: '2025-07-15',
status: 'confirmed',
status_label: 'Confirmed',
}
it('displays event title', () => {
const wrapper = mount(EventCard, {
props: { event: mockEvent },
})
expect(wrapper.text()).toContain('Summer Concert')
})
it('emits edit event when edit button clicked', async () => {
const wrapper = mount(EventCard, {
props: { event: mockEvent },
})
await wrapper.find('[data-test="edit-btn"]').trigger('click')
expect(wrapper.emitted('edit')).toBeTruthy()
expect(wrapper.emitted('edit')?.[0]).toEqual([mockEvent])
})
it('shows correct status color', () => {
const wrapper = mount(EventCard, {
props: { event: mockEvent },
})
const chip = wrapper.find('[data-test="status-chip"]')
expect(chip.classes()).toContain('bg-success')
})
})
```
### Composable Test Pattern
```typescript
// src/composables/__tests__/useEvents.test.ts
import { describe, it, expect, vi, beforeEach } from 'vitest'
import { flushPromises } from '@vue/test-utils'
import { useEvents } from '../useEvents'
import { createTestQueryClient, createTestingPinia } from '@/test/utils'
import { VueQueryPlugin } from '@tanstack/vue-query'
import { createApp } from 'vue'
describe('useEvents', () => {
beforeEach(() => {
createTestingPinia()
})
it('fetches events successfully', async () => {
const app = createApp({ template: '<div />' })
const queryClient = createTestQueryClient()
app.use(VueQueryPlugin, { queryClient })
// Mount and test...
await flushPromises()
// Assertions
})
})
```
### Pest Expectations (Laravel)
```php
// Use fluent expectations
expect($user)->toBeInstanceOf(User::class);
expect($collection)->toHaveCount(5);
expect($response->json('data'))->toMatchArray([...]);
// Chain expectations
expect($user)
->name->toBe('John')
->email->toContain('@')
->created_at->toBeInstanceOf(Carbon::class);
```
## Test Coverage Goals
| Area | Target | Priority |
|------|--------|----------|
| API Endpoints | 90%+ | High |
| Actions | 100% | High |
| Models | 80%+ | Medium |
| Vue Composables | 80%+ | Medium |
| Vue Components | 60%+ | Low |
**Minimum Coverage**: 80% line coverage
## Coverage Requirements
- **Feature tests**: All API endpoints must have tests
- **Unit tests**: All Actions and Services with business logic
- **Component tests**: All interactive components
- **Composable tests**: All custom composables that fetch data
## Best Practices
### Do
- Test happy path AND edge cases
- Use descriptive test names
- One assertion focus per test
- Use factories for test data
- Clean up after tests (RefreshDatabase)
- Test authorization separately
### Don't
- Test framework code (Laravel, Vue)
- Test private methods directly
- Share state between tests
- Use real external APIs
- Over-mock (test real behavior)