Convert the documentation files from Word (.docx) to a more gegeneric Markdown format
This commit is contained in:
Binary file not shown.
Binary file not shown.
Binary file not shown.
1149
resources/design/design-document.md
Normal file
1149
resources/design/design-document.md
Normal file
File diff suppressed because it is too large
Load Diff
759
resources/design/dev-guide.md
Normal file
759
resources/design/dev-guide.md
Normal file
@@ -0,0 +1,759 @@
|
||||
# Crewli Development Guide
|
||||
|
||||
Cursor & Claude Code — Van Leeg Project naar Productie
|
||||
|
||||
**Versie:** 1.0 | **Datum:** Maart 2026 | **Stack:** Laravel 12 + Vue 3 | **AI Tools:** Cursor + Claude Code
|
||||
|
||||
## 1. Strategie & Mindset
|
||||
|
||||
Cursor vs Claude Code — wanneer gebruik je wat?
|
||||
|
||||
Voordat je begint met ontwikkelen is het belangrijk te begrijpen hoe Cursor en Claude Code zich tot elkaar verhouden. Ze zijn complementair — niet concurrerend.
|
||||
|
||||
| **Tool** | **Wanneer inzetten** |
|
||||
|----|----|
|
||||
| Cursor (IDE) | Dagelijks coderen. Inline autocomplete, context-aware suggesties, kleine refactors, code reviews, directe file-edits. Beste voor: een specifiek component bouwen, een bug fixen, een test schrijven. |
|
||||
| Claude Code (Terminal) | Grote, multi-file taken. Scaffolding van een volledig module (migrations + model + controller + tests + Vue-pagina). Autonome agent die zelfstandig werkt, tests uitvoert en fouten corrigeert. Beste voor: 'Bouw het volledige shift-module end-to-end.' |
|
||||
| Samen | Aanbevolen workflow: Claude Code genereert het skelet en alle bestanden. Cursor verfijnt, debugt en voegt details toe. Claude Code draait de test-suite. Cursor doet code review en stijlcorrecties. |
|
||||
|
||||
> **KERNPRINCIPE**
|
||||
>
|
||||
> Claude Code is je senior developer die grote blokken werk autonoom uitvoert.
|
||||
>
|
||||
> Cursor is je pair programmer die naast je zit terwijl jij zelf ook werkt.
|
||||
>
|
||||
> Jij bent de architect en product owner: jij beslist, zij bouwen.
|
||||
|
||||
## 2. De Eerste Stappen
|
||||
|
||||
Wat je vandaag doet voordat je één regel code schrijft
|
||||
|
||||
### 2.1 Repository structuur definitief maken
|
||||
|
||||
Controleer en bevestig de folderstructuur
|
||||
|
||||
Jouw huidige setup heeft al een goede basis. Bevestig of maak de volgende structuur:
|
||||
|
||||
```
|
||||
crewli/ # Monorepo root
|
||||
├── api/ # Laravel 12 backend
|
||||
│ ├── app/
|
||||
│ │ ├── Http/
|
||||
│ │ │ ├── Controllers/Api/V1/
|
||||
│ │ │ ├── Middleware/
|
||||
│ │ │ └── Requests/ # Form Requests per endpoint
|
||||
│ │ ├── Models/
|
||||
│ │ ├── Policies/ # Laravel Policies per model
|
||||
│ │ ├── Services/ # Business logic buiten controllers
|
||||
│ │ ├── Events/ + Listeners/
|
||||
│ │ └── Jobs/ # Queue jobs (briefings, PDF, notifs)
|
||||
│ ├── database/
|
||||
│ │ ├── migrations/
|
||||
│ │ ├── factories/
|
||||
│ │ └── seeders/
|
||||
│ └── tests/Feature/Api/V1/ # PHPUnit feature tests per controller
|
||||
├── apps/
|
||||
│ ├── admin/ # Super Admin SPA (Vuexy)
|
||||
│ ├── app/ # Organizer SPA (Vuexy) -- HOOFDAPP
|
||||
│ └── portal/ # Externe portals (vrijwilliger, artiest, leverancier)
|
||||
├── docs/ # Design document, API docs, ERD
|
||||
│ ├── design-document.md
|
||||
│ └── dev-guide.md
|
||||
└── .cursorrules # Cursor workspace rules
|
||||
```
|
||||
|
||||
### 2.2 Dependencies installeren
|
||||
|
||||
Backend en frontend klaarstomen
|
||||
|
||||
**Backend (api/)**
|
||||
|
||||
```bash
|
||||
cd api
|
||||
|
||||
# Spatie permissions (rollen/permissies)
|
||||
composer require spatie/laravel-permission
|
||||
|
||||
# Audit log
|
||||
composer require spatie/laravel-activitylog
|
||||
|
||||
# Media library (bestandsbeheer)
|
||||
composer require spatie/laravel-medialibrary
|
||||
|
||||
# PDF generatie
|
||||
composer require barryvdh/laravel-dompdf
|
||||
|
||||
# QR codes
|
||||
composer require endroid/qr-code
|
||||
|
||||
# Publiceer Spatie configs
|
||||
php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider"
|
||||
php artisan vendor:publish --provider="Spatie\LaravelActivitylog\ActivitylogServiceProvider"
|
||||
```
|
||||
|
||||
**Frontend — alle apps (apps/app/, apps/admin/, apps/portal/)**
|
||||
|
||||
```bash
|
||||
# TanStack Query voor API state management
|
||||
npm install @tanstack/vue-query
|
||||
|
||||
# Formuliervalidatie
|
||||
npm install vee-validate zod @vee-validate/zod
|
||||
|
||||
# Drag-and-drop (form builder, timetable, prioriteitsranking)
|
||||
npm install vuedraggable@next
|
||||
|
||||
# In apps/app/ en apps/admin/ ook:
|
||||
npm install @fullcalendar/vue3 @fullcalendar/timeline @fullcalendar/resource-timeline
|
||||
```
|
||||
|
||||
### 2.3 CLAUDE.md aanmaken
|
||||
|
||||
Het belangrijkste bestand in je hele repo
|
||||
|
||||
CLAUDE.md is de instructieset voor Claude Code. Het wordt automatisch geladen bij elke sessie. Dit bestand is de meest impactvolle investering die je doet — een uur hieraan besteden bespaart honderden uren aan correcties.
|
||||
|
||||
Maak aan: /crewli/CLAUDE.md (root niveau, zodat het voor alle sub-projecten geldt)
|
||||
|
||||
## 3. Helper Files — Volledige Inhoud
|
||||
|
||||
De exacte bestanden die je aanmaakt voor de eerste prompt
|
||||
|
||||
### 3.1 CLAUDE.md — Root niveau
|
||||
|
||||
Dit is de volledige, aanbevolen inhoud voor je CLAUDE.md. Kopieer dit letterlijk en pas aan waar nodig.
|
||||
|
||||
```
|
||||
# Crewli — Claude Code Instructies
|
||||
|
||||
## Project Context
|
||||
Crewli is een multi-tenant SaaS platform voor event- en festivalbeheer.
|
||||
Gebouwd voor een professionele vrijwilligersorganisatie, met SaaS-uitbreidingspotentieel.
|
||||
Design Document: /resources/design/design-document.md
|
||||
|
||||
## Tech Stack
|
||||
- Backend: PHP 8.2+, Laravel 12, Sanctum, Spatie Permission, MySQL 8, Redis
|
||||
- Frontend: TypeScript, Vue 3 (Composition API), Vuexy/Vuetify, Pinia, TanStack Query
|
||||
- Testing: PHPUnit (backend), Vitest (frontend)
|
||||
|
||||
## Repository Structuur
|
||||
- api/ Laravel backend
|
||||
- apps/app/ Organizer SPA (hoofdapp)
|
||||
- apps/admin/ Super Admin SPA
|
||||
- apps/portal/ Externe portals (vrijwilliger, artiest, leverancier)
|
||||
|
||||
## Backend Regels (STRIKT VOLGEN)
|
||||
|
||||
### Multi-tenancy
|
||||
- ELKE query op event-data MOET scoperen op organisation_id
|
||||
- Gebruik OrganisationScope als Eloquent Global Scope op alle event-gerelateerde modellen
|
||||
- Nooit directe id-checks in controllers — gebruik altijd Policies
|
||||
|
||||
### Controllers
|
||||
- Gebruik Resource Controllers (index/show/store/update/destroy)
|
||||
- Namespace: App\Http\Controllers\Api\V1\
|
||||
- Alle responses via API Resources (nooit model-attributen direct teruggeven)
|
||||
- Validatie via Form Requests (nooit inline validate())
|
||||
|
||||
### Modellen
|
||||
- Gebruik HasUlids trait op alle business-modellen (GEEN UUID v4)
|
||||
- Soft deletes op: Organisation, Event, FestivalSection, Shift, ShiftAssignment, Person, Artist
|
||||
- GEEN soft deletes op: CheckIn, BriefingSend, MessageReply, ShiftWaitlist (audit-records)
|
||||
- JSON kolommen ALLEEN voor opaque configuratie — nooit voor queryable data
|
||||
|
||||
### Database
|
||||
- Primaire sleutels: ULID via HasUlids (niet UUID v4, niet auto-increment voor business tables)
|
||||
- Elke migratie in volgorde aanmaken: eerst foundation, dan afhankelijke tabellen
|
||||
- ALTIJD composite indexes toevoegen zoals gedocumenteerd in het design document sectie 3.5
|
||||
|
||||
### Rollen & Permissies
|
||||
- Gebruik Spatie laravel-permission
|
||||
- Check rollen via $user->hasRole() en Policies — nooit hardcoded role strings in controllers
|
||||
- Drie niveaus: app (super_admin), organisatie (org_admin/org_member), event (event_manager etc.)
|
||||
|
||||
### Testing
|
||||
- Schrijf PHPUnit Feature Tests per controller
|
||||
- Minimaal per endpoint: happy path + unauthenticated (401) + wrong organisation (403)
|
||||
- Gebruik factories voor alle test-data
|
||||
- Draai tests NA elke module: php artisan test --filter=ModuleNaam
|
||||
|
||||
## Frontend Regels (STRIKT VOLGEN)
|
||||
|
||||
### Vue Componenten
|
||||
- Altijd <script setup lang='ts'> — nooit Options API
|
||||
- Props altijd getypeerd met defineProps<{...}>()
|
||||
- Emits altijd gedeclareerd met defineEmits<{...}>()
|
||||
|
||||
### API Calls
|
||||
- Gebruik TanStack Query (useQuery / useMutation) voor ALLE API calls
|
||||
- Nooit direct axios in een component — altijd via een composable in composables/api/
|
||||
- Pinia stores voor cross-component state — nooit prop drilling
|
||||
|
||||
### Naamgeving
|
||||
- DB kolommen: snake_case
|
||||
- TypeScript/JS variabelen: camelCase
|
||||
- Vue componenten: PascalCase (bijv. ShiftAssignPanel.vue)
|
||||
- Composables: use-prefix (bijv. useShifts.ts)
|
||||
- Pinia stores: use-suffix store (bijv. useEventStore.ts)
|
||||
|
||||
### UI
|
||||
- Gebruik ALTIJD Vuexy/Vuetify componenten voor layout, forms, tabellen, dialogen
|
||||
- Nooit custom CSS schrijven als een Vuetify klasse bestaat
|
||||
- Responsief: mobile-first, minimaal werkend op 375px breedte
|
||||
|
||||
## Verboden Patronen
|
||||
- NOOIT: $user->role === 'admin' (gebruik policies)
|
||||
- NOOIT: Model::all() zonder where-clausule (altijd scopen)
|
||||
- NOOIT: dd() of var_dump() achterlaten in code
|
||||
- NOOIT: .env waarden hardcoden in code
|
||||
- NOOIT: JSON kolommen gebruiken voor data waarop gefilterd wordt
|
||||
- NOOIT: UUID v4 als primaire sleutel (gebruik HasUlids)
|
||||
|
||||
## Volgorde bij elke nieuwe module
|
||||
1. Migratie(s) aanmaken en draaien
|
||||
2. Eloquent Model met relaties, scopes en HasUlids
|
||||
3. Factory voor test-data
|
||||
4. Policy voor autorisatie
|
||||
5. Form Request(s) voor validatie
|
||||
6. API Resource voor response transformatie
|
||||
7. Resource Controller
|
||||
8. Routes registreren in api.php
|
||||
9. PHPUnit Feature Test schrijven en draaien
|
||||
10. Vue composable voor API calls (useModuleNaam.ts)
|
||||
11. Pinia store indien cross-component state nodig
|
||||
12. Vue pagina component
|
||||
13. Route toevoegen in Vue Router
|
||||
```
|
||||
|
||||
### 3.2 .cursorrules — Root niveau
|
||||
|
||||
Dit is het equivalent van CLAUDE.md maar voor Cursor's autocomplete en inline AI. Korter en meer gefocust op directe code-stijl.
|
||||
|
||||
```
|
||||
# Crewli Cursor Rules
|
||||
|
||||
## Stack
|
||||
PHP 8.2 + Laravel 12 | TypeScript + Vue 3 + Vuexy/Vuetify | Pinia + TanStack Query
|
||||
|
||||
## Laravel
|
||||
- Resource Controllers, Form Requests, API Resources — altijd
|
||||
- HasUlids op business modellen, HasFactory, SoftDeletes waar gedocumenteerd
|
||||
- Global Scope OrganisationScope op event-gerelateerde modellen
|
||||
- Policies voor autorisatie, nooit inline role checks
|
||||
|
||||
## Vue 3
|
||||
- <script setup lang='ts'> altijd
|
||||
- TanStack Query voor API state, Pinia voor UI state
|
||||
- Vuetify componenten eerst, custom CSS als laatste redmiddel
|
||||
|
||||
## Naamgeving
|
||||
- snake_case DB | camelCase JS | PascalCase Vue | use* composables | use*Store Pinia
|
||||
|
||||
## Tests
|
||||
- PHPUnit Feature Test per controller, minimaal: 200 + 401 + 403
|
||||
```
|
||||
|
||||
### 3.3 docs/SCHEMA.md — Levend schema-document
|
||||
|
||||
Maak een Markdown bestand aan in /docs/ dat de tabel-definitie bevat als platte tekst. Claude Code gebruikt dit als primaire referentie bij het genereren van migraties.
|
||||
|
||||
```
|
||||
# Crewli Database Schema
|
||||
# Versie: 1.3 | Gegenereerd vanuit Design Document
|
||||
|
||||
## Regels
|
||||
- Primaire sleutels: ULID via HasUlids (nooit UUID v4)
|
||||
- Soft delete: zie lijst per tabel hieronder
|
||||
- JSON kolommen: alleen voor opaque config
|
||||
|
||||
## Tabellen
|
||||
|
||||
### users
|
||||
- id (ulid, PK)
|
||||
- name (string)
|
||||
- email (string, unique)
|
||||
- password (string)
|
||||
- timezone (string, default: Europe/Amsterdam)
|
||||
- locale (string, default: nl)
|
||||
- avatar (string, nullable)
|
||||
- email_verified_at (timestamp, nullable)
|
||||
- deleted_at (timestamp, nullable) -- soft delete
|
||||
|
||||
### organisations
|
||||
- id (ulid, PK)
|
||||
- name (string)
|
||||
- slug (string, unique)
|
||||
- billing_status (enum: trial|active|suspended|cancelled, default: trial)
|
||||
- settings (json, nullable) -- UI display prefs only
|
||||
- deleted_at (timestamp, nullable)
|
||||
|
||||
# ... (volledig schema uit Design Document sectie 3.5)
|
||||
```
|
||||
|
||||
### 3.4 docs/API.md — API contract
|
||||
|
||||
Een simpele route-lijst die Claude Code gebruikt als referentie bij het genereren van controllers en Vue composables.
|
||||
|
||||
```
|
||||
# Crewli API Contract
|
||||
# Base: /api/v1/
|
||||
# Auth: Bearer token (Sanctum)
|
||||
|
||||
## Auth
|
||||
POST /auth/login
|
||||
POST /auth/logout
|
||||
GET /auth/me
|
||||
|
||||
## Organisations
|
||||
GET /organisations -- lijst (super admin)
|
||||
POST /organisations -- aanmaken
|
||||
GET /organisations/{org} -- detail
|
||||
PUT /organisations/{org} -- bijwerken
|
||||
GET /organisations/{org}/members -- leden
|
||||
POST /organisations/{org}/invite -- uitnodigen
|
||||
|
||||
## Events
|
||||
GET /organisations/{org}/events
|
||||
POST /organisations/{org}/events
|
||||
GET /organisations/{org}/events/{event}
|
||||
PUT /organisations/{org}/events/{event}
|
||||
|
||||
## Festival Sections
|
||||
GET /events/{event}/sections
|
||||
POST /events/{event}/sections
|
||||
GET /events/{event}/sections/{section}
|
||||
|
||||
## Time Slots
|
||||
GET /events/{event}/time-slots
|
||||
POST /events/{event}/time-slots
|
||||
|
||||
## Shifts
|
||||
GET /events/{event}/sections/{section}/shifts
|
||||
POST /events/{event}/sections/{section}/shifts
|
||||
PUT /events/{event}/sections/{section}/shifts/{shift}
|
||||
POST /events/{event}/sections/{section}/shifts/{shift}/assign
|
||||
POST /events/{event}/sections/{section}/shifts/{shift}/claim
|
||||
|
||||
## Persons
|
||||
GET /events/{event}/persons
|
||||
POST /events/{event}/persons
|
||||
GET /events/{event}/persons/{person}
|
||||
PUT /events/{event}/persons/{person}
|
||||
POST /events/{event}/persons/{person}/approve
|
||||
|
||||
# ... (volledig API contract uitbreiden per module)
|
||||
```
|
||||
|
||||
## 4. Development Workflow
|
||||
|
||||
Hoe je van leeg project naar werkende feature gaat
|
||||
|
||||
Elke feature volgt dezelfde drielaagse workflow. Commit altijd per voltooide laag — nooit halfafgebouwde code in main.
|
||||
|
||||
| **Laag** | **Wat je doet en met welk tool** |
|
||||
|----|----|
|
||||
| Laag 1 — Backend (API) | Claude Code genereert: migratie + model + factory + policy + form request + resource + controller + test. Jij reviewt en draait tests. |
|
||||
| Laag 2 — Frontend (Vue) | Claude Code genereert: composable + Pinia store + Vue pagina + router entry. Cursor verfijnt de UI met Vuexy componenten. |
|
||||
| Laag 3 — Integration | Cursor: verbind frontend met backend. Test end-to-end. Fix type-errors. Review mobile weergave. |
|
||||
|
||||
### 4.1 De Module-generatie volgorde
|
||||
|
||||
Altijd in deze volgorde. Nooit stappen overslaan — later toevoegen kost meer tijd dan nu correct doen.
|
||||
|
||||
| **Stap** | **Commando / Actie** |
|
||||
|----|----|
|
||||
| 1. Migratie | php artisan make:migration create_shifts_table |
|
||||
| 2. Model | php artisan make:model Shift -mfp (migration + factory + policy) |
|
||||
| 3. Form Request | php artisan make:request StoreShiftRequest + UpdateShiftRequest |
|
||||
| 4. API Resource | php artisan make:resource ShiftResource + ShiftCollection |
|
||||
| 5. Controller | php artisan make:controller Api/V1/ShiftController --api |
|
||||
| 6. Registreer routes | In api/routes/api.php toevoegen |
|
||||
| 7. Test | php artisan make:test ShiftControllerTest + draaien |
|
||||
| 8. Composable | apps/app/src/composables/api/useShifts.ts aanmaken |
|
||||
| 9. Store (indien nodig) | apps/app/src/stores/useShiftStore.ts |
|
||||
| 10. Vue pagina | apps/app/src/pages/sections/[id]/shifts.vue |
|
||||
| 11. Route | apps/app/src/router/index.ts |
|
||||
|
||||
### 4.2 Fase-planning: wat bouw je wanneer
|
||||
|
||||
| **Fase** | **Inhoud** |
|
||||
|----|----|
|
||||
| Fase 1 — Foundation (nu) | Auth (login/logout/me), Organisations CRUD, Events CRUD, User invitations, Multi-tenant scope, Roles & permissions setup, Basis dashboard shell |
|
||||
| Fase 2 — Core Operations | Persons & Crowd Types, Festival Sections + Time Slots + Shifts, Shift claiming + goedkeuring, Vrijwilligers registratie + portaal, Accreditatie engine, Basis briefings |
|
||||
| Fase 3 — Advancing & Show Day | Artist advancing + portaal, Timetable, Mission Control, Formulierbouwer, Post-festival evaluatie, PDF allocatiesheet, Campagnes (email + WhatsApp via Zender) |
|
||||
| Fase 4 — Differentiators | Real-time WebSockets, Show Day Mode, Vrijwilligersprofiel + festival-paspoort, Shift swap & wachtlijst, Retrospectief rapport, Leveranciersportaal uitgebreid |
|
||||
|
||||
## 5. Prompt Bibliotheek
|
||||
|
||||
Kant-en-klare prompts voor elke ontwikkelstap
|
||||
|
||||
Gebruik deze prompts letterlijk of als basis. De meest effectieve prompts zijn: specifiek, contextueel en taak-gebaseerd. Verwijs altijd naar de docs/ bestanden die je hebt aangemaakt.
|
||||
|
||||
### 5.1 Kickstart prompts
|
||||
|
||||
> **Fase 1 kickstart — Alles genereren in een sweep**
|
||||
>
|
||||
> Lees /resources/design/design-document.md sectie 3.5 (schema) en /CLAUDE.md.
|
||||
>
|
||||
> Genereer alle Fase 1 componenten in de juiste volgorde:
|
||||
>
|
||||
> 1. Migrations voor: users (update), organisations, organisation_user, user_invitations, events, event_user_roles
|
||||
> 2. Eloquent modellen met HasUlids, relaties, OrganisationScope global scope waar van toepassing
|
||||
> 3. Factories met realistic test data
|
||||
> 4. Spatie Permission seeder: maak rollen aan (super_admin, org_admin, org_member, event_manager, staff_coordinator, volunteer_coordinator)
|
||||
> 5. Auth controller (login/logout/me) met Sanctum
|
||||
> 6. Organisations controller (CRUD) met Policy en Feature Test
|
||||
> 7. Events controller (CRUD) met Policy en Feature Test
|
||||
>
|
||||
> Draai na elke stap: php artisan test. Los fouten op voor je verder gaat.
|
||||
|
||||
> **Module genereren — Shifts als voorbeeld**
|
||||
>
|
||||
> Lees /CLAUDE.md en /docs/SCHEMA.md voor de shifts tabel definitie.
|
||||
>
|
||||
> Bouw het volledige Shifts module in de volgorde uit CLAUDE.md sectie 'Volgorde bij elke nieuwe module'.
|
||||
>
|
||||
> Specifieke eisen voor Shifts:
|
||||
>
|
||||
> - time_slot_id MOET gedenormaliseerd worden in shift_assignments voor de UNIQUE(person_id, time_slot_id) constraint
|
||||
> - ShiftAssignment heeft een status machine: pending_approval > approved/rejected/cancelled/completed
|
||||
> - Auto-approve is configureerbaar per shift (auto_approved bool op shift niveau)
|
||||
> - Bij approve: stuur notificatie naar vrijwilliger (queued job, gebruik ZenderService voor WhatsApp)
|
||||
> - ShiftResource moet slots_filled (count van approved assignments) en fill_rate (percentage) berekend teruggeven
|
||||
>
|
||||
> Eindig met: php artisan test --filter=Shift
|
||||
|
||||
### 5.2 Backend prompts
|
||||
|
||||
> **Migration genereren**
|
||||
>
|
||||
> Genereer een Laravel migratie voor de tabel [TABELNAAM] op basis van /docs/SCHEMA.md.
|
||||
>
|
||||
> Gebruik $table->ulid('id')->primary() als PK.
|
||||
>
|
||||
> Voeg alle indexes toe zoals gedocumenteerd (composite indexes, unique constraints).
|
||||
>
|
||||
> Voeg timestamps() en softDeletes() toe indien van toepassing per CLAUDE.md.
|
||||
>
|
||||
> Gebruik constrained() op alle foreign keys voor cascade-gedrag.
|
||||
|
||||
> **Model met alle features**
|
||||
>
|
||||
> Genereer het Eloquent model voor [MODELNAAM].
|
||||
>
|
||||
> Gebruik: HasUlids, HasFactory, SoftDeletes (indien van toepassing).
|
||||
>
|
||||
> Voeg toe: OrganisationScope global scope, alle relaties (hasMany, belongsTo, belongsToMany),
|
||||
> computed accessors (fill_rate, available_slots), status-gerelateerde scopes (scopePending, scopeApproved),
|
||||
> en $fillable of $guarded array.
|
||||
>
|
||||
> Schrijf ook de factory met realistic Nederlandse testdata.
|
||||
|
||||
> **API Resource met computed velden**
|
||||
>
|
||||
> Genereer een Laravel API Resource voor [MODELNAAM].
|
||||
>
|
||||
> Voeg toe: alle relevante velden, computed velden (fill_rate, status_label),
|
||||
> conditioneel geladen relaties (whenLoaded), en wanneer van toepassing: when() voor permissie-afhankelijke velden.
|
||||
>
|
||||
> De Resource mag NOOIT model-attributen direct weggeven zonder transformatie.
|
||||
|
||||
> **Feature test schrijven**
|
||||
>
|
||||
> Schrijf een PHPUnit Feature Test voor [CONTROLLERNAAM].
|
||||
>
|
||||
> Dek minimaal af: index (200), show (200), store (201), update (200), destroy (204),
|
||||
> unauthenticated (401 op alle routes), wrong organisation (403), validatiefouten (422).
|
||||
>
|
||||
> Gebruik RefreshDatabase, ActingAs met correcte rol via Spatie Permission.
|
||||
>
|
||||
> Maak test data via factories — nooit hardcoded IDs.
|
||||
|
||||
> **ZenderService aanmaken (WhatsApp/SMS)**
|
||||
>
|
||||
> Maak app/Services/ZenderService.php aan.
|
||||
>
|
||||
> Zender is een self-hosted SMS/WhatsApp gateway (CodeCanyon product).
|
||||
>
|
||||
> Config: ZENDER_API_URL en ZENDER_API_KEY uit .env.
|
||||
>
|
||||
> Methoden: sendSms(string $to, string $message): bool
|
||||
> sendWhatsApp(string $to, string $message): bool
|
||||
> sendByUrgency(string $to, string $message, string $urgency): bool
|
||||
>
|
||||
> urgency: normal=email only, urgent=whatsapp, emergency=sms+whatsapp parallel
|
||||
>
|
||||
> Gebruik Laravel HTTP Client (Http::). Log alle sends via activitylog.
|
||||
>
|
||||
> Schrijf ook een ZenderServiceTest met HTTP fake.
|
||||
|
||||
### 5.3 Frontend prompts
|
||||
|
||||
> **Vue pagina voor een lijst-overzicht**
|
||||
>
|
||||
> Maak apps/app/src/pages/[module]/index.vue.
|
||||
>
|
||||
> Gebruik \<script setup lang='ts'\>.
|
||||
>
|
||||
> API calls via useQuery() uit TanStack Query — niet direct axios.
|
||||
>
|
||||
> Tabel via VDataTable van Vuetify — niet custom HTML.
|
||||
>
|
||||
> Bovenaan: status KPI-tiles (totaal, goedgekeurd, pending) als klikbare VCard componenten.
|
||||
>
|
||||
> Rij klik: opent een side panel (niet navigeert naar nieuwe pagina) met detail-informatie.
|
||||
>
|
||||
> Loading state: VSkeleton loader. Error state: VAlert met retry knop.
|
||||
>
|
||||
> Mobiel: tabel collapst naar een VList op viewport < 768px.
|
||||
|
||||
> **Composable voor API calls**
|
||||
>
|
||||
> Maak apps/app/src/composables/api/use[Module].ts.
|
||||
>
|
||||
> Exporteer: use[Module]List (useQuery), use[Module]Detail (useQuery met id param),
|
||||
> useCreate[Module] (useMutation), useUpdate[Module] (useMutation), useDelete[Module] (useMutation).
|
||||
>
|
||||
> Gebruik axios via de centrale api.ts instance (met Sanctum CSRF en auth header).
|
||||
>
|
||||
> Mutations invalideren automatisch de relevante query keys na succes.
|
||||
>
|
||||
> Alle response types volledig getypeerd via TypeScript interfaces in types/[module].ts.
|
||||
|
||||
> **Pinia store aanmaken**
|
||||
>
|
||||
> Maak apps/app/src/stores/use[Module]Store.ts.
|
||||
>
|
||||
> Gebruik defineStore met Setup syntax (niet Options syntax).
|
||||
>
|
||||
> Sla op: geselecteerde IDs, UI state (open sidepanel, actief tab), filters.
|
||||
>
|
||||
> NIET in Pinia: server data (dat zit in TanStack Query). Pinia is alleen voor UI state.
|
||||
>
|
||||
> Exporteer: alle state als readonly via storeToRefs.
|
||||
|
||||
> **Shift claim workflow — volledig end-to-end**
|
||||
>
|
||||
> Bouw de volledige shift claim workflow:
|
||||
>
|
||||
> Backend: POST /shifts/{shift}/claim endpoint in ShiftController.
|
||||
>
|
||||
> - Valideer: shift heeft slots_open_for_claiming beschikbaar
|
||||
> - Valideer: geen bestaande approved assignment voor zelfde time_slot_id voor deze person
|
||||
> - Maak ShiftAssignment aan met status=pending_approval
|
||||
> - Dispatch NotifyCoordinatorOfClaimJob (queued)
|
||||
> - Return ShiftAssignmentResource
|
||||
>
|
||||
> Frontend: 'Claim' knop in portal/shifts/index.vue.
|
||||
>
|
||||
> - Disable knop als conflict of geen slots beschikbaar
|
||||
> - Na claim: toon 'Wachten op goedkeuring' badge
|
||||
> - Optioneel: 'Op wachtlijst' knop als shift vol is
|
||||
|
||||
### 5.4 Agent-aanstuurprompts
|
||||
|
||||
> **Grote module — een prompt voor alles**
|
||||
>
|
||||
> Je bent een senior fullstack developer die werkt aan Crewli. Lees /CLAUDE.md volledig.
|
||||
>
|
||||
> Bouw het volledige [MODULE] module:
|
||||
>
|
||||
> Backend (in volgorde):
|
||||
>
|
||||
> 1. Migrations voor alle tabellen uit /docs/SCHEMA.md sectie [X.X]
|
||||
> 2. Models met alle relaties, scopes en accessors
|
||||
> 3. Factories
|
||||
> 4. Policies
|
||||
> 5. Form Requests
|
||||
> 6. API Resources
|
||||
> 7. Controllers
|
||||
> 8. Routes
|
||||
> 9. Feature tests — draai ze, los fouten op
|
||||
>
|
||||
> Frontend:
|
||||
>
|
||||
> 10. TypeScript types in apps/app/src/types/[module].ts
|
||||
> 11. Composables in apps/app/src/composables/api/
|
||||
> 12. Vue pagina's (lijst + detail side panel)
|
||||
> 13. Router entries
|
||||
>
|
||||
> Stop na elke laag en vraag bevestiging voor je doorgaat.
|
||||
>
|
||||
> Als een test faalt: los het op voor je verdergaat — nooit overslaan.
|
||||
|
||||
> **Bug fix prompt**
|
||||
>
|
||||
> Er is een probleem met [BESCHRIJVING VAN HET PROBLEEM].
|
||||
>
|
||||
> Relevante bestanden: [BESTANDSPADEN].
|
||||
>
|
||||
> Foutmelding: [PLAK EXACTE ERROR].
|
||||
>
|
||||
> Verwacht gedrag: [WAT ZOU ER MOETEN GEBEUREN].
|
||||
>
|
||||
> Analyseer de oorzaak, schrijf een failing test die het probleem reproduceert,
|
||||
> fix het probleem, en bevestig dat de test slaagt.
|
||||
|
||||
> **Code review prompt**
|
||||
>
|
||||
> Review de code in [BESTANDSPAD] als senior Laravel/Vue developer.
|
||||
>
|
||||
> Check specifiek op:
|
||||
>
|
||||
> - Multi-tenancy: wordt organisation_id correct gescopeerd?
|
||||
> - Security: worden Policies gebruikt? Geen directe role-checks?
|
||||
> - Performance: ontbrekende eager loading (N+1), ontbrekende indexes?
|
||||
> - Conventies: volgt het CLAUDE.md regels?
|
||||
> - Types: zijn alle TypeScript types volledig (geen any)?
|
||||
>
|
||||
> Geef concrete verbeterpunten met codevoorbeelden.
|
||||
|
||||
## 6. Agents — Autonome Ontwikkeling
|
||||
|
||||
Hoe je Claude Code en Cursor agents effectief inzet
|
||||
|
||||
### 6.1 Claude Code als Agent
|
||||
|
||||
Claude Code kan volledig autonoom werken: bestanden lezen, aanmaken, aanpassen, tests draaien en fouten corrigeren — zonder dat jij elke stap bevestigt. Dit is het krachtigste en snelste werkmode.
|
||||
|
||||
| **Mode** | **Wanneer gebruiken** |
|
||||
|----|----|
|
||||
| Interactief (standaard) | Als je wil meekijken en goedkeuren. Claude Code stelt elke actie voor en wacht. Gebruik voor: eerste keer een module bouwen, complexe refactors. |
|
||||
| Autonoom (--dangerously-skip-permissions) | Als je een grote taak wil delegeren en wegloopt. Claude Code werkt door tot klaar. Gebruik voor: routine-modules die je eerder hebt gebouwd, test-driven fixes. |
|
||||
| Aanbevolen aanpak | Start autonoom voor scaffolding. Schakel naar interactief bij UI-componenten of business-logica die project-specifieke kennis vereist. |
|
||||
|
||||
**Claude Code opstarten**
|
||||
|
||||
```bash
|
||||
# Installeer Claude Code (eenmalig)
|
||||
npm install -g @anthropic-ai/claude-code
|
||||
|
||||
# Start in je project root
|
||||
cd /pad/naar/crewli
|
||||
claude
|
||||
|
||||
# Of: direct met een taak
|
||||
claude --print 'Genereer de Shift migration op basis van CLAUDE.md'
|
||||
|
||||
# Autonoom mode (voorzichtig gebruiken)
|
||||
claude --dangerously-skip-permissions
|
||||
```
|
||||
|
||||
### 6.2 Cursor Agent Mode
|
||||
|
||||
Cursor heeft een ingebouwde Agent mode die vergelijkbaar is met Claude Code maar geintegreerd in de IDE. Activeer via Cmd+Shift+P > 'Cursor: Open Agent'.
|
||||
|
||||
| **Feature** | **Gebruik** |
|
||||
|----|----|
|
||||
| @workspace | Geeft de agent toegang tot je hele codebase als context. Altijd meegeven bij module-niveau taken. |
|
||||
| @file | Verwijs naar een specifiek bestand. Bijv: @CLAUDE.md @api/app/Models/Shift.php |
|
||||
| @docs | Verwijs naar externe documentatie (Laravel docs, Vuetify docs). Cursor indexeert deze. |
|
||||
| Composer mode | Meerdere bestanden tegelijk bewerken. Ideaal voor: tegelijk model + controller + test aanpassen. |
|
||||
|
||||
### 6.3 De optimale agent-workflow per dag
|
||||
|
||||
> **DAGELIJKSE ROUTINE**
|
||||
>
|
||||
> Ochtend: Open Claude Code. Geef de taak voor die dag: 'Bouw het volledig Persons module op basis van CLAUDE.md en SCHEMA.md.' Laat autonoom draaien.
|
||||
>
|
||||
> Middag: Review de gegenereerde code in Cursor. Check: volgt het de conventies? Zijn de tests groen? Zijn de TypeScript types compleet?
|
||||
>
|
||||
> Namiddag: Cursor voor UI fijnafstelling, Vuexy componenten integratie, visuele correcties.
|
||||
>
|
||||
> Einde dag: php artisan test (alle tests groen). Commit alles met duidelijke commit messages.
|
||||
|
||||
### 6.4 Context window management
|
||||
|
||||
Claude Code heeft een beperkt context window. Bij grote taken verliest het de context van eerdere bestanden. Beheer dit proactief:
|
||||
|
||||
- Begin elke nieuwe sessie met: 'Lees /CLAUDE.md voor je begint.'
|
||||
|
||||
- Verwijs expliciet naar relevante bestanden: 'Zie /docs/SCHEMA.md voor de tabel definitie.'
|
||||
|
||||
- Splits grote modules: 'Bouw eerst alleen de backend (stappen 1-9). Stop dan.'
|
||||
|
||||
- Na een context-verlies: geef een samenvatting: 'We bouwen Crewli. Tot nu toe klaar: auth, organisations, events. Nu: Shifts module backend.'
|
||||
|
||||
- Gebruik /docs/API.md als levend document — houd bij wat er al gebouwd is.
|
||||
|
||||
## 7. Tips, Valkuilen & Best Practices
|
||||
|
||||
Geleerd van ervaring — lees dit voordat je begint
|
||||
|
||||
### 7.1 De grootste tijdverspillers
|
||||
|
||||
| **Valkuil** | **Oplossing** |
|
||||
|----|----|
|
||||
| Te brede prompts: 'Bouw de hele app' | Altijd per module. Per module maximaal 1 laag tegelijk. Breed = vaag = slechte output. |
|
||||
| CLAUDE.md niet up-to-date houden | Na elke architectuurbeslissing: update CLAUDE.md. Dit is je bron van waarheid. Verouderde regels leiden tot inconsistente code. |
|
||||
| Tests overslaan 'want het werkt toch' | Schrijf tests altijd. AI-gegenereerde code heeft subtiele bugs die pas later opduiken. Tests vangen dit vroeg. |
|
||||
| Alle gegenereerde code blindelings accepteren | Review altijd: check multi-tenancy scoping, check indexes, check error handling. AI mist soms subtiele business logica. |
|
||||
| Frontend en backend tegelijk bouwen | Backend eerst, compleet en getest. Dan frontend. Nooit parallel — je verliest overzicht. |
|
||||
| Geen versiecontrole per module | Commit na elke voltooide module (backend + frontend + tests). Kleine commits = makkelijk terugdraaien. |
|
||||
|
||||
### 7.2 Prompts die altijd goed werken
|
||||
|
||||
- **Geef altijd context: 'Crewli is een multi-tenant SaaS voor festival-organisatie...'**
|
||||
|
||||
- **Verwijs naar bestanden: 'Op basis van CLAUDE.md en SCHEMA.md...'**
|
||||
|
||||
- **Specificeer de output: 'Genereer X, Y en Z. Niets anders.'**
|
||||
|
||||
- **Vraag om uitleg: 'Leg uit waarom je deze aanpak kiest voor de shift conflict-check.'**
|
||||
|
||||
- **Gebruik iteratief: 'Dit klopt niet omdat... Pas aan en draai tests opnieuw.'**
|
||||
|
||||
### 7.3 Kwaliteitscontrole checklist
|
||||
|
||||
Gebruik dit als checklist voor elke voltooide module voordat je verder gaat:
|
||||
|
||||
| **Check** | **Wat je controleert** |
|
||||
|----|----|
|
||||
| Tests | php artisan test draait groen. Minimaal: 200, 401, 403 per endpoint. |
|
||||
| Multi-tenancy | Elke query heeft organisation_id scope. Controleer via tinker. |
|
||||
| N+1 queries | Gebruik Laravel Debugbar of query logging. Geen N+1 in lijst-endpoints. |
|
||||
| TypeScript | Geen 'any' types in Vue composables en components. npx tsc --noEmit groen. |
|
||||
| Mobile | Pagina is bruikbaar op 375px. Open Chrome DevTools en check. |
|
||||
| Error states | Wat ziet een gebruiker bij: lege lijst, API fout, netwerk timeout? |
|
||||
| CLAUDE.md | Geen verboden patronen (Model::all, hardcoded roles, UUID v4). |
|
||||
|
||||
### 7.4 Handige Laravel commando's
|
||||
|
||||
```bash
|
||||
# Alles in een keer voor een nieuwe model
|
||||
php artisan make:model Shift -a # model + migration + factory + seeder + policy + controller + resource
|
||||
|
||||
# Tests draaien
|
||||
php artisan test # alle tests
|
||||
php artisan test --filter=ShiftTest # specifieke test class
|
||||
php artisan test --coverage # met coverage rapport
|
||||
|
||||
# Database
|
||||
php artisan migrate:fresh --seed # reset + migreer + seed
|
||||
php artisan tinker # REPL voor quick checks
|
||||
|
||||
# Routes inspecteren
|
||||
php artisan route:list --path=api/v1 # alle API routes
|
||||
|
||||
# Queue (voor briefings, notificaties)
|
||||
php artisan queue:work --queue=notifications,briefings,default
|
||||
```
|
||||
|
||||
### 7.5 Eerste dag: exacte volgorde
|
||||
|
||||
| **#** | **Actie** |
|
||||
|----|----|
|
||||
| 1 | Repository structuur controleren (sectie 2, stap 01) |
|
||||
| 2 | Dependencies installeren (sectie 2, stap 02) |
|
||||
| 3 | CLAUDE.md aanmaken en invullen (sectie 3.1) |
|
||||
| 4 | .cursorrules aanmaken (sectie 3.2) |
|
||||
| 5 | docs/SCHEMA.md aanmaken met volledig schema uit design document |
|
||||
| 6 | docs/API.md aanmaken met initiiele routes |
|
||||
| 7 | Claude Code starten: 'Lees CLAUDE.md. Daarna: genereer Fase 1 — auth, organisations, events.' |
|
||||
| 8 | Tests draaien: php artisan test — los fouten op |
|
||||
| 9 | Commit: 'feat: fase 1 foundation — auth, organisations, events' |
|
||||
| 10 | Morgen: Fase 2 starten met Persons & Crowd Types |
|
||||
|
||||
---
|
||||
|
||||
Crewli Development Guide v1.0 — Maart 2026
|
||||
457
resources/design/start-guide.md
Normal file
457
resources/design/start-guide.md
Normal file
@@ -0,0 +1,457 @@
|
||||
**Crewli**
|
||||
|
||||
Start — Definitieve Actielijst
|
||||
|
||||
Architectuur + Technologie + Stap-voor-stap naar eerste werkende code
|
||||
|
||||
**Versie:** 1.0 — Definitief | **Datum:** Maart 2026 | **Status:** Klaar om te starten
|
||||
|
||||
## 1 — Definitieve Architectuur
|
||||
|
||||
Dit is de volledige, vastgestelde architectuur van Crewli. Alle beslissingen hierin zijn definitief — verwerk ze in CLAUDE.md en .cursorrules zodat Claude Code dit altijd als context heeft.
|
||||
|
||||
### 1.1 Systeemoverzicht
|
||||
|
||||
| **apps/admin/** | **apps/app/** | **apps/portal/** |
|
||||
|---|---|---|
|
||||
| Super Admin SPA | Organizer SPA | Portal SPA |
|
||||
|
||||
Vuexy + Vue 3 + TypeScript | Pinia + TanStack Query | Axios → CORS → Sanctum Token
|
||||
Alle drie apps zijn Vue 3 SPA's — Vuexy template — communiceren uitsluitend via REST API
|
||||
|
||||
**api/ — Laravel 12 REST API (ENIGE backend — geen Blade views)**
|
||||
PHP 8.2 | Sanctum | Spatie Permission | MySQL 8 | Redis | Queue Workers
|
||||
|
||||
### 1.2 Laravel vs Vue — de harde scheiding
|
||||
|
||||
> **GOUDEN REGEL**
|
||||
>
|
||||
> Laravel doet NIKS met HTML of UI. Geen Blade views, geen Mix, geen Inertia.
|
||||
>
|
||||
> Laravel is uitsluitend een JSON REST API. Elke response is application/json.
|
||||
>
|
||||
> Vue doet ALLES met de gebruikersinterface. De drie SPA's communiceren via HTTPS met de API.
|
||||
|
||||
| **App / Laag** | **Technology** | **Gebruik & verantwoordelijkheid** |
|
||||
|----|----|----|
|
||||
| api/ | Laravel 12 + Sanctum | REST API, authenticatie, business logic, database, queue workers, e-mail, PDF-generatie. Geen enkele HTML pagina. |
|
||||
| apps/admin/ | Vue 3 + Vuexy (vol) | Super Admin SPA: organisations beheren, billing, platform-gebruikers. Klein en eenvoudig. |
|
||||
| apps/app/ | Vue 3 + Vuexy (vol) | Organizer SPA: de hoofdapp. Events, shifts, persons, artists, briefings, Mission Control. 90% van je werk. |
|
||||
| apps/portal/ | Vue 3 + Vuexy (gestript) | Portal SPA: twee toegangsmodi. Login voor vrijwilligers/crew. Token voor artiesten/leveranciers/pers. |
|
||||
|
||||
### 1.3 Vuexy — waar en hoe
|
||||
|
||||
| **App / Laag** | **Technology** | **Gebruik & verantwoordelijkheid** |
|
||||
|----|----|----|
|
||||
| apps/admin/ | Vuexy volledig | Admin template ongewijzigd: sidebar, dark mode, customizer. Weinig aanpassingen nodig. |
|
||||
| apps/app/ | Vuexy volledig | Sidebar nav aanpassen voor Crewli-structuur. Customizer/demo-componenten verwijderen. Full Vuetify component gebruik. |
|
||||
| apps/portal/ | Vuexy gestript | Geen sidebar nav, geen customizer, geen dark mode toggle. Wel: Vuetify componenten, Vuexy SCSS variabelen, Vuexy fonts. Eigen layout: top-bar met event-logo + naam. Mobile-first. |
|
||||
|
||||
### 1.4 Portal: twee toegangsmodi
|
||||
|
||||
Eén portal app met twee modi — op basis van hoe de gebruiker binnenkomt:
|
||||
|
||||
| **Gebruiker** | **Identiteit** | **Toegang** | **Waarom** |
|
||||
|----|:--:|:--:|----|
|
||||
| **Vrijwilliger** | Langdurig | **Login** | Festival-paspoort, reliability score, shift-historie accumuleren over jaren |
|
||||
| **Crew / Staff** | Langdurig | **Login** | Kan ook organizer-rechten hebben; organisatie-medewerker |
|
||||
| **Artiest** | Per event | **Token** | Eenmalige booking-relatie; advancing via gesignde URL |
|
||||
| **Tour manager** | Per event | **Token** | Namens artiest; geen platform-account nodig |
|
||||
| **Leverancier** | Per event | **Token** | Productieaanvraag is event-specifiek; token via production_requests.token |
|
||||
| **Pers / Media** | Per event | **Token** | Accreditatie per event; geen terugkerende relatie |
|
||||
|
||||
**Hoe de router dit afhandelt (apps/portal/)**
|
||||
|
||||
```ts
|
||||
// apps/portal/src/router/guards.ts
|
||||
|
||||
export const accessMode = computed(() => {
|
||||
const token = route.query.token as string | undefined
|
||||
const isAuth = authStore.isAuthenticated
|
||||
|
||||
if (token) return 'token' // artiest, leverancier, pers → token-flow
|
||||
if (isAuth) return 'login' // vrijwilliger, crew → login-flow
|
||||
return 'unauthenticated' // → redirect naar /login
|
||||
})
|
||||
|
||||
// Token-based: geen login nodig, token gevalideerd via API
|
||||
// POST /api/v1/portal/token-auth { token: '...' } → person context terug
|
||||
```
|
||||
|
||||
### 1.5 Hoe de API authorisatie werkt — backend
|
||||
|
||||
```php
|
||||
// api/routes/api.php
|
||||
|
||||
Route::prefix('v1')->group(function () {
|
||||
|
||||
// Publiek (login, token-auth)
|
||||
Route::post('auth/login', [AuthController::class, 'login']);
|
||||
Route::post('portal/token-auth', [PortalTokenController::class, 'auth']);
|
||||
Route::post('portal/form-submit', [PublicFormController::class, 'submit']);
|
||||
|
||||
// Login-based (Sanctum)
|
||||
Route::middleware('auth:sanctum')->group(function () {
|
||||
Route::post('auth/logout', [AuthController::class, 'logout']);
|
||||
Route::get('auth/me', [AuthController::class, 'me']);
|
||||
// ... alle organizer + portal-login routes
|
||||
});
|
||||
|
||||
// Token-based portal (eigen middleware)
|
||||
Route::middleware('portal.token')->group(function () {
|
||||
Route::get('portal/artist', [ArtistPortalController::class, 'index']);
|
||||
Route::post('portal/advancing', [AdvancingController::class, 'submit']);
|
||||
// ... alle token-portal routes
|
||||
});
|
||||
|
||||
});
|
||||
```
|
||||
|
||||
> **LET OP — CORS**
|
||||
>
|
||||
> Laravel CORS config (config/cors.php) moet drie origins toestaan:
|
||||
>
|
||||
> admin.crewli.app | app.crewli.app | portal.crewli.app
|
||||
>
|
||||
> In development: http://localhost:5173 | :5174 | :5175
|
||||
|
||||
## 2 — Actielijst: Wat Je Nu Doet
|
||||
|
||||
Voer deze stappen uit in volgorde. Sla niets over — elke stap is input voor de volgende. Tijdsinschatting totaal: 2-4 uur. Daarna kun je de eerste Claude Code prompt sturen.
|
||||
|
||||
### Stap 1 — Repository herstructureren **NU**
|
||||
|
||||
apps/band/ hernoemen, demo-rommel verwijderen
|
||||
|
||||
- ☐ **Hernoem apps/band/ naar apps/portal/**
|
||||
|
||||
```
|
||||
mv apps/band apps/portal
|
||||
# Update package.json naam in apps/portal/package.json:
|
||||
# "name": "crewli-portal"
|
||||
```
|
||||
|
||||
- ☐ **Verwijder Vuexy demo-bestanden uit apps/app/src/**
|
||||
|
||||
- Te verwijderen uit apps/app/src/components/dialogs/:
|
||||
- AddAuthenticatorAppDialog.vue, AddPaymentMethodDialog.vue, CardAddEditDialog.vue
|
||||
- PricingPlanDialog.vue, ReferAndEarnDialog.vue, UserUpgradePlanDialog.vue
|
||||
|
||||
- Te verwijderen uit apps/app/src/@core/components/:
|
||||
- BuyNow.vue — 'buy template' knop
|
||||
- TheCustomizer.vue — theme demo-customizer (niet nodig in productie)
|
||||
|
||||
- Te verwijderen uit apps/app/src/pages/:
|
||||
- second-page.vue — demo pagina
|
||||
|
||||
- Te verwijderen uit apps/app/public/:
|
||||
- mockServiceWorker.js — MSW service worker (alleen in dev nodig, niet committen)
|
||||
|
||||
### Stap 2 — API-laag opruimen in apps/app/ **NU**
|
||||
|
||||
Een centrale axios instance — dubbele laag verwijderen
|
||||
|
||||
- **!** apps/app/ heeft nu drie overlappende API-bestanden: src/lib/api-client.ts, src/utils/api.ts, en src/composables/useApi.ts. Dit moet worden een bestand.
|
||||
|
||||
- ☐ **Bepaal: src/lib/axios.ts wordt de ENIGE axios instance**
|
||||
|
||||
```ts
|
||||
// apps/app/src/lib/axios.ts — de ENIGE axios instance
|
||||
import axios from 'axios'
|
||||
import { useAuthStore } from '@/stores/useAuthStore'
|
||||
|
||||
const api = axios.create({
|
||||
baseURL: import.meta.env.VITE_API_URL + '/api/v1',
|
||||
withCredentials: true,
|
||||
headers: { 'Accept': 'application/json' },
|
||||
})
|
||||
|
||||
// Request interceptor: voeg Bearer token toe
|
||||
api.interceptors.request.use(config => {
|
||||
const auth = useAuthStore()
|
||||
if (auth.token) config.headers.Authorization = `Bearer ${auth.token}`
|
||||
return config
|
||||
})
|
||||
|
||||
// Response interceptor: 401 → redirect naar login
|
||||
api.interceptors.response.use(
|
||||
res => res,
|
||||
err => {
|
||||
if (err.response?.status === 401) useAuthStore().logout()
|
||||
return Promise.reject(err)
|
||||
}
|
||||
)
|
||||
|
||||
export default api
|
||||
```
|
||||
|
||||
- ☐ Verwijder daarna: src/lib/api-client.ts en src/utils/api.ts
|
||||
- ☐ Hernoem src/composables/useApi.ts → src/composables/useApiHelpers.ts (algemene helpers)
|
||||
- ☐ Doe hetzelfde voor apps/portal/ en apps/admin/ (zelfde patroon)
|
||||
|
||||
### Stap 3 — TanStack Query installeren **NU**
|
||||
|
||||
Ontbreekt nog — vereist voor alle API state management
|
||||
|
||||
- ☐ **Installeer in alle drie apps (app/, admin/, portal/)**
|
||||
|
||||
```sh
|
||||
cd apps/app && pnpm add @tanstack/vue-query
|
||||
cd ../admin && pnpm add @tanstack/vue-query
|
||||
cd ../portal && pnpm add @tanstack/vue-query
|
||||
```
|
||||
|
||||
- ☐ Registreer in main.ts van elke app
|
||||
|
||||
```ts
|
||||
// apps/app/src/main.ts — voeg toe
|
||||
import { VueQueryPlugin } from '@tanstack/vue-query'
|
||||
|
||||
app.use(VueQueryPlugin, {
|
||||
queryClientConfig: {
|
||||
defaultOptions: {
|
||||
queries: { staleTime: 1000 * 60 * 5, retry: 1 },
|
||||
},
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
- ☐ Installeer ook formuliervalidatie (alle apps)
|
||||
|
||||
```sh
|
||||
pnpm add vee-validate zod @vee-validate/zod
|
||||
```
|
||||
|
||||
### Stap 4 — Backend dependencies installeren **NU**
|
||||
|
||||
Spatie packages zijn vereist voor fase 1
|
||||
|
||||
- ☐ **Installeer Spatie packages in api/**
|
||||
|
||||
```sh
|
||||
cd api
|
||||
composer require spatie/laravel-permission
|
||||
composer require spatie/laravel-activitylog
|
||||
composer require spatie/laravel-medialibrary
|
||||
composer require barryvdh/laravel-dompdf
|
||||
composer require endroid/qr-code
|
||||
|
||||
# Publiceer configs
|
||||
php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider"
|
||||
php artisan vendor:publish --provider="Spatie\LaravelActivitylog\ActivitylogServiceProvider"
|
||||
|
||||
# Voeg HasUlids toe als trait — Laravel native, geen extra package nodig
|
||||
# use Illuminate\Database\Eloquent\Concerns\HasUlids;
|
||||
```
|
||||
|
||||
- ☐ Voeg PortalToken middleware toe (skeleton voor later)
|
||||
|
||||
```sh
|
||||
php artisan make:middleware PortalTokenMiddleware
|
||||
# Registreer in bootstrap/app.php als 'portal.token'
|
||||
```
|
||||
|
||||
- ☐ Update config/cors.php voor drie frontend origins
|
||||
|
||||
```php
|
||||
// config/cors.php
|
||||
'allowed_origins' => [
|
||||
env('FRONTEND_ADMIN_URL', 'http://localhost:5173'),
|
||||
env('FRONTEND_APP_URL', 'http://localhost:5174'),
|
||||
env('FRONTEND_PORTAL_URL','http://localhost:5175'),
|
||||
],
|
||||
```
|
||||
|
||||
### Stap 5 — Helper bestanden aanmaken **NU**
|
||||
|
||||
CLAUDE.md, .cursorrules, docs/ — dit is het belangrijkste wat je doet
|
||||
|
||||
- **!** Dit zijn de vier bestanden die Claude Code altijd laadt als context. Een uur hieraan besteden bespaart honderden uren aan correcties. Gebruik de volledige inhoud uit Dev Guide sectie 3.
|
||||
|
||||
- ☐ **Maak aan in de root van je project:**
|
||||
|
||||
```sh
|
||||
# Root van het project (naast api/ en apps/)
|
||||
touch CLAUDE.md # Dev Guide sectie 3.1 — volledig invullen
|
||||
touch .cursorrules # Dev Guide sectie 3.2 — volledig invullen
|
||||
mkdir -p docs
|
||||
touch docs/SCHEMA.md # Schema uit Design Document v1.3 sectie 3.5
|
||||
touch docs/API.md # API contract — begin met auth + organisations + events
|
||||
```
|
||||
|
||||
- ☐ Voeg toe aan CLAUDE.md (update ten opzichte van Dev Guide v1.0):
|
||||
|
||||
- Portal architectuur: een app, twee toegangsmodi
|
||||
- Login-based (auth:sanctum): vrijwilligers, crew — persons met user_id
|
||||
- Token-based (portal.token middleware): artiesten, leveranciers, pers — persons zonder user_id
|
||||
|
||||
- apps/ mapping: admin/ = Super Admin, app/ = Organizer, portal/ = Externe gebruikers
|
||||
|
||||
- CORS: drie origins configureren in zowel Laravel als Vite dev server
|
||||
|
||||
### Stap 6 — Vite dev ports configureren **NU**
|
||||
|
||||
Elk frontend-app een eigen port zodat CORS werkt
|
||||
|
||||
- ☐ **Pas vite.config.ts aan in elke app**
|
||||
|
||||
```ts
|
||||
// apps/admin/vite.config.ts → port: 5173
|
||||
// apps/app/vite.config.ts → port: 5174
|
||||
// apps/portal/vite.config.ts → port: 5175
|
||||
server: {
|
||||
port: 5174, // aanpassen per app
|
||||
proxy: { // optioneel: proxy API calls in dev
|
||||
'/api': {
|
||||
target: 'http://localhost:8000',
|
||||
changeOrigin: true,
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- ☐ Voeg .env.local toe aan elke app
|
||||
|
||||
```sh
|
||||
# apps/app/.env.local
|
||||
VITE_API_URL=http://localhost:8000
|
||||
VITE_APP_NAME=Crewli
|
||||
|
||||
# apps/portal/.env.local
|
||||
VITE_API_URL=http://localhost:8000
|
||||
VITE_APP_NAME=Crewli Portal
|
||||
```
|
||||
|
||||
### Stap 7 — Eerste Claude Code prompt sturen **NU**
|
||||
|
||||
Je bent klaar om de eerste module te laten genereren
|
||||
|
||||
- **!** Na stappen 1-6 ben je klaar. Onderstaande prompt kun je letterlijk in Claude Code plakken.
|
||||
|
||||
- ☐ **Start Claude Code vanuit je project root**
|
||||
|
||||
```sh
|
||||
cd /pad/naar/crewli
|
||||
claude
|
||||
```
|
||||
|
||||
- ☐ **Plak deze prompt als eerste bericht:**
|
||||
|
||||
```
|
||||
Lees eerst volledig /CLAUDE.md en /docs/SCHEMA.md.
|
||||
|
||||
Bouw daarna Fase 1 — Foundation — in deze volgorde:
|
||||
|
||||
1. Migrations in api/database/migrations/:
|
||||
- update users tabel (voeg timezone, locale, deleted_at toe)
|
||||
- organisations (ULID, name, slug, billing_status, settings JSON, deleted_at)
|
||||
- organisation_user pivot (int PK, user_id, organisation_id, role)
|
||||
- user_invitations (ULID, email, invited_by, organisation_id, event_id nullable,
|
||||
token ULID unique, status enum, expires_at)
|
||||
- events (ULID, organisation_id, name, slug, start_date, end_date,
|
||||
timezone, status enum, deleted_at)
|
||||
- event_user_roles pivot
|
||||
|
||||
2. Models: User (update), Organisation, UserInvitation, Event
|
||||
- HasUlids op alle business modellen
|
||||
- SoftDeletes op Organisation, Event
|
||||
- OrganisationScope global scope op Event
|
||||
- Alle relaties (hasMany, belongsToMany)
|
||||
|
||||
3. Spatie Permission setup:
|
||||
- RoleSeeder: super_admin, org_admin, org_member,
|
||||
event_manager, staff_coordinator, volunteer_coordinator
|
||||
|
||||
4. Auth: LoginController, LogoutController, MeController
|
||||
- Sanctum token-based (geen session)
|
||||
- MeController geeft user + organisations + active event roles terug
|
||||
|
||||
5. Organisations: OrganisationController (index/show/store/update)
|
||||
- OrganisationPolicy
|
||||
- OrganisationRequest (store + update)
|
||||
- OrganisationResource
|
||||
|
||||
6. Events: EventController (index/show/store/update) genest onder organisations
|
||||
- EventPolicy
|
||||
- EventRequest
|
||||
- EventResource
|
||||
|
||||
7. Feature tests voor alles bovenstaande:
|
||||
- Happy path (200/201)
|
||||
- Unauthenticated (401)
|
||||
- Wrong organisation (403)
|
||||
|
||||
Draai na elke stap: php artisan test
|
||||
Los fouten op voor je verdergaat.
|
||||
Stop na stap 7 en rapporteer wat er gebouwd is en of alle tests groen zijn.
|
||||
```
|
||||
|
||||
## 3 — Daarna: Frontend Fase 1 + Fase 2 Planning
|
||||
|
||||
### Stap 8 — Frontend Fase 1 — Auth + Shell **DAARNA**
|
||||
|
||||
Na groene backend tests
|
||||
|
||||
- Auth flow bouwen in apps/app/
|
||||
- stores/useAuthStore.ts — token opslaan, isAuthenticated, me() laden
|
||||
- pages/login.vue — Vuexy login layout gebruiken (al aanwezig als basis)
|
||||
- router guard — redirect naar login als niet authenticated
|
||||
|
||||
- Navigatiestructuur Crewli invullen
|
||||
- src/navigation/vertical/index.ts — verwijder Vuexy demo-items, voeg Crewli items toe
|
||||
- Events → Sections → Shifts, Persons, Artists, Briefings, Rapportage
|
||||
|
||||
- CASL permissions setup
|
||||
- src/plugins/casl.ts koppelen aan Spatie roles vanuit auth/me response
|
||||
- useAbility() gebruiken voor conditionele UI-elementen (aanpassen-knop tonen/verbergen)
|
||||
|
||||
### Stap 9 — Fase 2 — Core module volgorde **DAARNA**
|
||||
|
||||
Na werkende auth en shell
|
||||
|
||||
- **Bouw in deze volgorde — altijd eerst backend, dan frontend:**
|
||||
|
||||
1. Crowd Types + Persons + Crowd Lists (basis guest management)
|
||||
2. Festival Sections + Time Slots + Shifts (het hart van het platform)
|
||||
3. Shift Assignments — claim workflow met approval flow
|
||||
4. Vrijwilligers registratie (public form → portal login flow)
|
||||
5. Accreditatie engine + Access Zones
|
||||
6. Basis briefings (template + send + track)
|
||||
|
||||
- **!** Elke module: gebruik de module-prompt uit Dev Guide sectie 5.2. Altijd: migrations → model → factory → policy → resource → controller → test → composable → pagina.
|
||||
|
||||
### Stap 10 — Portal app inrichten **DAARNA**
|
||||
|
||||
Na werkende apps/app/ basis
|
||||
|
||||
- apps/portal/ strippen tot portal-layout
|
||||
- Verwijder: sidebar nav, customizer, dark mode toggle, demo-dialogen
|
||||
- Maak: PortalLayout.vue — top-bar met event-logo, naam, hamburger menu
|
||||
- Maak: twee router guards — loginGuard en tokenGuard
|
||||
|
||||
- Login-flow (vrijwilligers/crew): zelfde /api/v1/auth/login endpoint als app/
|
||||
- Token-flow (artiesten/leveranciers): POST /api/v1/portal/token-auth
|
||||
- Routing op basis van accessMode computed + person.crowd_type
|
||||
|
||||
## 4 — Checklist: Ben Je Klaar om te Starten?
|
||||
|
||||
| **#** | **Actie** | **Status** |
|
||||
|:--:|----|:--:|
|
||||
| **1** | apps/band/ hernoemd naar apps/portal/ | ☐ Klaar |
|
||||
| **2** | Demo-rommel verwijderd uit apps/app/ | ☐ Klaar |
|
||||
| **3** | Dubbele API-laag opgeruimd → een src/lib/axios.ts per app | ☐ Klaar |
|
||||
| **4** | TanStack Query geinstalleerd in alle drie apps + geregistreerd in main.ts | ☐ Klaar |
|
||||
| **5** | VeeValidate + Zod geinstalleerd in alle drie apps | ☐ Klaar |
|
||||
| **6** | Spatie packages geinstalleerd in api/ + configs gepubliceerd | ☐ Klaar |
|
||||
| **7** | PortalTokenMiddleware skeleton aangemaakt | ☐ Klaar |
|
||||
| **8** | config/cors.php: drie frontend origins geconfigureerd | ☐ Klaar |
|
||||
| **9** | Vite dev ports: admin=5173, app=5174, portal=5175 | ☐ Klaar |
|
||||
| **10** | .env.local aangemaakt per app met VITE_API_URL | ☐ Klaar |
|
||||
| **11** | CLAUDE.md aangemaakt en volledig ingevuld (Dev Guide sectie 3.1 + portal architectuur) | ☐ Klaar |
|
||||
| **12** | .cursorrules aangemaakt (Dev Guide sectie 3.2) | ☐ Klaar |
|
||||
| **13** | docs/SCHEMA.md aangemaakt (schema uit Design Document v1.3 sectie 3.5) | ☐ Klaar |
|
||||
| **14** | docs/API.md aangemaakt met initiele route-lijst | ☐ Klaar |
|
||||
| **15** | claude (Claude Code) gestart en Fase 1 prompt ingevoerd | ☐ Klaar |
|
||||
| **16** | php artisan test — alle tests groen | ☐ Klaar |
|
||||
|
||||
Crewli Start Guide v1.0 — Maart 2026 | Architectuur + Actielijst
|
||||
Reference in New Issue
Block a user