# RegiTicket — Claude Code Agent Guide

> Leer `.cursorrules` para el contexto completo del proyecto. Este archivo complementa con reglas específicas para Claude Code.

## Stack y comandos rápidos

```bash
php artisan test                              # correr todos los tests
php artisan test --filter=NombreTest         # test específico
php artisan migrate:fresh --seed             # reset DB completo
npm run dev                                  # assets en modo dev
npm run build                                # build producción
```

Con **Laravel Sail** (PHP no está en el PATH del host): ejecutar Artisan y PHPUnit **dentro del contenedor**, por ejemplo `./vendor/bin/sail artisan test` o `./vendor/bin/sail test tests/Feature/EventAttendeesTest.php` (desde la raíz del proyecto).

## Convenciones críticas

- Validación: SIEMPRE `$request->validated()`, nunca `$request->all()`
- Tests: SQLite + RefreshDatabase, nunca mocks de DB
- Autorización: usar Policies, nunca `if ($user->role->slug ===)` en controladores
- Auditar con `AuditLogger` toda acción significativa en el dashboard
- Los slugs de roles NO se modifican: `super_admin`, `administrador`, `organizador`, `cliente`

## Modelo de comisión (regla de negocio)

```
platform_fee = $2.99 + (subtotal × 5%)
net_organizer = subtotal - platform_fee
```
Implementar en `App\Services\FeeCalculator`.

## Prioridades de desarrollo

1. **P1**: Registro y aprobación de organizadores
2. **P2**: Carga manual y CSV de asistentes (diferenciador clave)
3. **P3**: Checkout público con Stripe/PayPal
4. **P4**: Panel de check-in QR
5. **P5**: Reportes y payouts

## Progreso reciente (mayo 2026)

### P1 — Organizer onboarding (completo)
- Registro público `/registro-organizador` + página de gracias.
- `account_status` en `users` + aprobación/rechazo desde `/dashboard/organizers` (solo staff) con emails.
- Middleware `OrganizerApproved` bloquea dashboard a organizadores no aprobados.
- Perfil organizador `/dashboard/profile` (datos + PayPal + tipo de eventos).
- Tests: `OrganizerOnboardingTest` (pasa en Sail).

### Dashboard de eventos (mejoras UX + base “carreras”)
- `/dashboard/events`: stats, filtros por estado, columna “distancias” y preferencia de BIB desde `events.metadata`.
- `/dashboard/events/create` y `edit`: bloque “Carreras y atletismo” para distancias (5K, 10K, 21K…) y modo de BIB (preferencia).
- “Tipo de evento” dinámico antes de categoría: `event_primary_type` controla el formulario (carrera activa bloque sport); categoría se asigna automáticamente cuando existen slugs en catálogo (fallback: selector manual).
- Se guarda en `events.metadata.primary_type` y `events.metadata.sport`.

## Pendiente inmediato
- Definir formularios específicos por tipo (música/corporativo/festival) y qué campos guardar en `metadata`.
- Implementar módulo real de BIB: asignación manual/en lote, rangos, validación de unicidad por evento.
- Resultados/leaderboards (modelo para tiempos + divisiones) y publicación pública.

## Referencia legacy

Plugin WordPress: `/Volumes/yzamora_ext/Desarrollo/Personales/regiticket_dev/wp-content/plugins/rt-checkin`
Consultar para lógica de aprobación de organizadores, check-in QR y estructura de reportes.

## Frontend

- Blade + Alpine.js (NO Vue/React)
- Bootstrap 5 + Bootstrap Icons
- Bootstrap Table para listas/tablas
- Mobile-first (check-in se usa desde teléfono)
