# 🗺️ Roadmap de Refactorización Web - Patrón Action

**Fecha:** Enero 2026  
**Objetivo:** Preparar el sistema para upgrade de Laravel mediante refactorización progresiva  
**Alcance:** Solo versión WEB (móvil se mantiene sin cambios)

---

## ✅ Checklist por Fase

Cada módulo refactorizado debe completar estos pasos:

### 1. Desarrollo
- [ ] Crear Actions necesarias (Create, Update, Delete, Get, etc.)
- [ ] Refactorizar Controller (inyección de Actions)
- [ ] Verificar/Crear Form Requests
- [ ] Verificar/Crear Resources

### 2. Calidad
- [ ] PHPStan nivel 5: 0 errores
- [ ] Tests pasando (existentes + nuevos)
- [ ] Controller ≤ 100 líneas
- [ ] Actions ≤ 150 líneas

### 3. Limpieza ⚠️ CRÍTICO
- [ ] **Identificar archivos obsoletos** (Controllers legacy, Services duplicados)
- [ ] **Verificar referencias** (`grep -r "ClassName" app/`)
- [ ] **Documentar para eliminar** (solo si 0 referencias)
- [ ] **NO eliminar** Repository, Resource, Request (se siguen usando)

### 4. Documentación
- [ ] Actualizar rutas en `routes/web/`
- [ ] Comentar código legacy (// @deprecated - usar V2)
- [ ] Registrar cambios en REFACTORING_ROADMAP.md

---

## 🧹 Estrategia de Limpieza de Archivos Obsoletos

### Reglas de Oro

1. **NUNCA eliminar sin verificar referencias**
   ```bash
   grep -r "ClassName" app/ --include="*.php"
   ```

2. **NUNCA eliminar en Fase 0-8** - Solo marcar como deprecated
3. **Fase 9 (Cleanup)** - Única fase donde se eliminan archivos
4. **Mantener siempre:**
   - Repositories (usados por Actions)
   - Resources (usados por Actions)
   - Form Requests (usados por Controllers)
   - Modelos (compartidos con móvil)

### Archivos Candidatos a Eliminación (verificar en Fase 9)

| Archivo | Cuándo Eliminar |
|---------|-----------------|
| `app/Traits/UtilResponse.php` | Cuando TODO use `ApiResponseTrait` |
| `app/Http/Controllers/ServiceController.php` | Cuando móvil migre o use V2 |
| `app/Http/Controllers/DriverController.php` | Cuando móvil migre o use V2 |
| `app/Http/Controllers/Web/{Module}/Legacy*` | Cuando V2 esté completo |
| Services duplicados | Cuando Actions los reemplacen 100% |

### Comando de Verificación por Módulo

Ejecutar después de cada fase:

```bash
# Ejemplo para Configuration
echo "=== Verificando archivos obsoletos en Configuration ==="

# 1. Verificar uso de Controller legacy (debe dar 0 si ya no se usa)
grep -r "ConfigurationsController" routes/ --include="*.php" | grep -v "web.php"

# 2. Verificar uso de UtilResponse en el módulo (debe dar 0)
grep -r "UtilResponse" app/Actions/Configuration/ --include="*.php"

# 3. Listar qué archivos usan el Repository (Actions deben estar)
grep -r "ConfigurationsRepository" app/ --include="*.php"

# 4. Verificar que Controller V2 esté en rutas
grep "ConfigurationsController" routes/web/*.php
```

**Resultado esperado por fase:**
- Controller legacy: Solo en `routes/web/` (API web)
- UtilResponse: 0 usos en módulo refactorizado
- Repository: Usado por Actions (correcto)
- Resources/Requests: Usados por Actions/Controller (correcto)

---

## ⚠️ REGLA CRÍTICA: PROTECCIÓN DE MÓVIL

### Archivos/Carpetas INTOCABLES (Móvil)

```
❌ NO MODIFICAR BAJO NINGUNA CIRCUNSTANCIA:

routes/api/mobile/              ← Rutas móviles
app/Http/Controllers/Mobile/    ← Controladores móviles
app/Http/Resources/Movile/      ← Resources móviles (sic)

Controladores compartidos (solo agregar, NO modificar):
├── app/Http/Controllers/ServiceController.php    ← Usado por móvil
├── app/Http/Controllers/DriverController.php     ← Usado por móvil  
├── app/Http/Controllers/ClientController.php     ← Usado por móvil
├── app/Http/Controllers/ApiController.php        ← Base para móvil
└── app/Http/Controllers/AuthController.php       ← Auth móvil
```

### Identificadores de Rutas Móviles (NO TOCAR)

| Middleware | Descripción | Rutas |
|------------|-------------|-------|
| `jwt-auth:driver` | Conductores móviles | 11 rutas |
| `jwt-auth:client` | Clientes móviles | ~5 rutas |
| Prefijo `/api/mobile/` | API móvil exclusiva | Todas |

### Estrategia de Separación

1. **Crear nuevos controladores** en `Web/V2/` - NUNCA modificar legacy
2. **Nuevas rutas** en `routes/web/` con prefijo `/api-web/`
3. **Middleware web**: `web.session` + `bouncer:permission`
4. **Los modelos son compartidos** - No modificar estructura de BD

---

## 📊 Estado Actual del Sistema

### Inventario de Controladores Web (por complejidad)

| Controlador | Líneas | Estado | Prioridad |
|------------|--------|--------|-----------|
| `ServiceController.php` | 854 | 🔴 Legacy | Alta |
| `DriverController.php` | 355 | 🔴 Legacy | Alta |
| `ApiController.php` | 285 | 🟡 Base class | Media |
| `ClientController.php` | 243 | 🔴 Legacy | Alta |
| `CostController.php` | 186 | 🔴 Legacy | Media |
| `Web/Services/ServicesController.php` | 168 | 🟡 Parcialmente V2 | Media |
| `Web/UserController.php` | 128 | 🟡 Parcialmente V2 | Media |
| `Web/Driver/DriverController.php` | 123 | 🟡 Legacy V2 | Baja |
| `UserController.php` | 119 | 🔴 Legacy | Media |
| `AnalyticsController.php` | 114 | 🔴 Legacy | Baja |
| `SuggestionController.php` | 102 | 🔴 Legacy | Baja |
| `Web/V2/DriverController.php` | 86 | ✅ **Refactorizado** | N/A |
| `Web/Vehicle/VehicleController.php` | 79 | 🟡 Parcialmente V2 | Media |
| `ConfigurationController.php` | 72 | 🔴 Legacy | Baja |

### Recursos Existentes

| Tipo | Cantidad | Ubicación |
|------|----------|-----------|
| Form Requests | 18 | `app/Http/Requests/` |
| API Resources | 14 | `app/Http/Resources/` |
| Actions (Driver) | 4 | `app/Services/Driver/Actions/` |
| Actions (Root) | 4 | `app/Actions/` |
| Services | 6 | `app/Services/` |

### Modelo de Referencia: Driver V2 ✅

El módulo **Driver V2** ya implementa el patrón correctamente:

```
app/
├── Http/
│   └── Controllers/Web/V2/
│       └── DriverController.php (86 líneas) ← Controller delgado
├── Services/Driver/
│   ├── DriverService.php                    ← Lógica de negocio
│   └── Actions/
│       ├── CreateDriverAction.php           ← Acción específica
│       ├── UpdateDriverAction.php
│       ├── GetAllDriversAction.php
│       └── GetDriversForMapAction.php
```

---

## 🏗️ Arquitectura Target

### Estructura por Módulo

```
app/
├── Actions/
│   └── {Module}/
│       ├── Create{Entity}Action.php
│       ├── Update{Entity}Action.php
│       ├── Delete{Entity}Action.php
│       ├── Get{Entity}Action.php
│       └── List{Entity}Action.php
│
├── Http/
│   ├── Controllers/Web/V2/
│   │   └── {Entity}Controller.php           # Máximo 100 líneas
│   │
│   ├── Requests/Web/
│   │   └── {Entity}/
│   │       ├── Store{Entity}Request.php
│   │       └── Update{Entity}Request.php
│   │
│   └── Resources/Web/
│       └── {Entity}/
│           ├── {Entity}Resource.php
│           └── {Entity}Collection.php
│
├── Services/
│   └── {Module}/
│       └── {Entity}Service.php              # Lógica reutilizable
│
└── Traits/
    └── ResponseTrait.php                    # Respuestas estandarizadas
```

### Principios de Diseño

1. **Single Responsibility**: Cada Action hace UNA cosa
2. **Controller Delgado**: Solo orquesta, no tiene lógica
3. **Form Requests**: Validación fuera del controller
4. **API Resources**: Transformación de respuestas
5. **Services**: Lógica reutilizable entre Actions
6. **Dependency Injection**: Actions inyectados en Controller

---

## 📋 Fases de Implementación (Ordenadas por Complejidad)

> **Estrategia:** Empezar por módulos simples para establecer patrones, 
> luego abordar los complejos con experiencia adquirida.

---

### Fase 0: Preparación y Fundamentos (3-4 días)
**Objetivo:** Establecer herramientas y estándares antes de refactorizar

| # | Tarea | Descripción | Horas |
|---|-------|-------------|-------|
| 0.1 | Trait de Respuestas | Unificar `UtilResponse` → `ApiResponseTrait` | 2h |
| 0.2 | Comando Make:Action | Generador Artisan para Actions | 3h |
| 0.3 | Clase Base Action | `BaseAction` con métodos comunes | 2h |
| 0.4 | Estándares de Código | Documentar convenciones | 2h |
| 0.5 | PHPStan Nivel 5 | Configurar análisis estático | 2h |

**Entregables:**
```
app/
├── Traits/ApiResponseTrait.php
├── Actions/BaseAction.php
└── Console/Commands/MakeActionCommand.php

docs/
└── CODING_STANDARDS.md

phpstan.neon
```

**Total Fase 0:** 11 horas

---

### Fase 1: Configuration (El más simple) - 1 día
**Objetivo:** Primer módulo para validar patrones

#### Estado Actual ✅ Casi listo
- `Web/Configurations/ConfigurationsController.php`: 35 líneas
- Ya usa Repository + Resource
- Solo necesita migrar a patrón Action

#### Trabajo a Realizar

| Componente | Estado | Acción |
|------------|--------|--------|
| Controller | ✅ Delgado | Solo refactor menor |
| Repository | ✅ Existe | Mantener |
| Resource | ✅ Existe | Mantener |
| Actions | ❌ Falta | Crear 2 |
| Requests | ✅ Existe | Mantener |

#### Actions a Crear

```php
app/Actions/Configuration/
├── GetConfigurationAction.php    # 1 hora
└── UpdateConfigurationAction.php # 1 hora
```

**Total Fase 1:** 4 horas

---

### Fase 2: Vehicles (Simple, ya tiene Service) - 1-2 días
**Objetivo:** Completar módulo parcialmente refactorizado

#### Estado Actual 🟡 Parcial
- `Web/Vehicle/VehicleController.php`: 79 líneas
- Ya usa VehicleService + VehicleRepository + VehicleResource
- Ya tiene `UpdateVehicleAction` en `app/Actions/`

#### Trabajo a Realizar

| Componente | Estado | Acción |
|------------|--------|--------|
| Controller | ✅ Delgado | Solo refactor menor |
| Service | ✅ Existe | Mantener |
| Repository | ✅ Existe | Mantener |
| Resource | ✅ Existe | Mantener |
| Actions | 🟡 Parcial | Crear 3 faltantes |
| Requests | ✅ Existe | Mantener |

#### Actions a Crear

```php
app/Actions/Vehicle/
├── ListVehiclesAction.php   # 1 hora
├── GetVehicleAction.php     # 1 hora
├── CreateVehicleAction.php  # 2 horas
└── UpdateVehicleAction.php  # ✅ Ya existe
```

**Total Fase 2:** 6 horas

---

### Fase 3: Clients Web (Simple, independiente) - 2 días
**Objetivo:** CRUD completo con patrón Action

#### Estado Actual 🟡 Mínimo
- `Web/Client/ClientsController.php`: 28 líneas (solo GET)
- Ya usa Repository + Resource
- Falta CRUD completo para web

#### ⚠️ IMPORTANTE: No tocar ClientController.php (legacy móvil)

#### Trabajo a Realizar

| Componente | Estado | Acción |
|------------|--------|--------|
| Controller V2 | ❌ Crear | Nuevo en `Web/V2/` |
| Repository | ✅ Existe | Extender |
| Resource | ✅ Existe | Mantener |
| Actions | ❌ Falta | Crear 4 |
| Requests | ❌ Falta | Crear 2 |

#### Estructura a Crear

```php
app/Actions/Client/
├── GetClientAction.php           # 1 hora
├── ListClientsAction.php         # 1.5 horas
├── CreateClientAction.php        # 2 horas
└── UpdateClientAction.php        # 2 horas

app/Http/Requests/Web/Client/
├── StoreClientRequest.php        # 1 hora
└── UpdateClientRequest.php       # 0.5 horas

app/Http/Controllers/Web/V2/
└── ClientController.php          # 1 hora
```

**Total Fase 3:** 9 horas

---

### Fase 4: Costs/Tarifas (CRUD independiente) - 2 días
**Objetivo:** Módulo CRUD completo, sin dependencias móviles

#### Estado Actual 🔴 Legacy
- `CostController.php`: 186 líneas (100% legacy)
- No tiene versión V2
- CRUD completo pero código antiguo

#### ⚠️ Este módulo es 100% WEB - No hay uso móvil

#### Trabajo a Realizar

| Componente | Estado | Acción |
|------------|--------|--------|
| Controller V2 | ❌ Crear | Nuevo |
| Service | ❌ Crear | Nuevo |
| Resource | ❌ Crear | Nuevo |
| Actions | ❌ Crear | 5 nuevos |
| Requests | ❌ Crear | 2 nuevos |
| Routes | ❌ Crear | Nueva ruta V2 |

#### Estructura a Crear

```php
app/Actions/Cost/
├── ListCostsAction.php       # 1.5 horas
├── GetCostAction.php         # 1 hora
├── CreateCostAction.php      # 2 horas
├── UpdateCostAction.php      # 2 horas
└── DeleteCostAction.php      # 1 hora

app/Services/Cost/
└── CostService.php           # 2 horas

app/Http/
├── Controllers/Web/V2/CostController.php    # 1 hora
├── Requests/Web/Cost/
│   ├── StoreCostRequest.php                 # 1 hora
│   └── UpdateCostRequest.php                # 0.5 horas
└── Resources/Web/Cost/
    └── CostResource.php                     # 1 hora

routes/web/
└── cost.php                                 # 0.5 horas
```

**Total Fase 4:** 13.5 horas

---

### Fase 5: Users Web (Administración) - 3 días
**Objetivo:** Gestión de usuarios web con Bouncer

#### Estado Actual 🟡 Mixto
- `Web/UserController.php`: 128 líneas
- Ya tiene algunos Requests
- Integración con Bouncer para roles

#### Trabajo a Realizar

| Componente | Estado | Acción |
|------------|--------|--------|
| Controller | 🟡 Existe | Refactorizar |
| Actions | ❌ Falta | Crear 5 |
| Requests | 🟡 Parcial | Completar |
| Resource | ❌ Falta | Crear |

#### Estructura a Crear

```php
app/Actions/User/
├── ListUsersAction.php           # 2 horas
├── GetUserAction.php             # 1 hora
├── CreateUserAction.php          # 3 horas
├── UpdateUserAction.php          # 2 horas
└── AssignRoleAction.php          # 2 horas

app/Http/Resources/Web/User/
└── UserResource.php              # 1 hora

app/Http/Controllers/Web/V2/
└── UserController.php            # 2 horas
```

**Total Fase 5:** 13 horas

---

### Fase 6: Analytics & Reports (Solo lectura) - 2 días
**Objetivo:** Dashboards y reportes

#### Estado Actual 🟡 Funcional
- `AnalyticsController.php`: 114 líneas
- Ya tiene Resource y Repository
- Solo necesita migrar a Actions

#### Trabajo a Realizar

```php
app/Actions/Analytics/
├── GetDashboardAction.php        # 3 horas
└── GetDriverStatsAction.php      # 2 horas

app/Actions/Report/
├── ListReportsAction.php         # 1.5 horas
└── GenerateReportAction.php      # 2.5 horas
```

**Total Fase 6:** 9 horas

---

### Fase 7: Suggestions (Simple) - 1 día
**Objetivo:** Gestión de sugerencias

#### Estado Actual 🔴 Legacy
- `SuggestionController.php`: 102 líneas

#### Trabajo a Realizar

```php
app/Actions/Suggestion/
├── ListSuggestionsAction.php     # 1.5 horas
├── GetSuggestionAction.php       # 1 hora
├── UpdateSuggestionAction.php    # 1.5 horas
└── DeleteSuggestionAction.php    # 1 hora
```

**Total Fase 7:** 5 horas

---

### Fase 8: Services (El más complejo) - 1.5 semanas
**Objetivo:** Módulo crítico del negocio

#### Estado Actual 🔴🟡 Mixto
- `ServiceController.php`: 854 líneas (LEGACY - NO TOCAR, usado por móvil)
- `Web/Services/ServicesController.php`: 168 líneas (V2 parcial)

#### ⚠️ CRÍTICO: NO modificar ServiceController.php (legacy móvil)

#### Estrategia
1. Crear nuevas Actions en `app/Actions/Service/`
2. Refactorizar SOLO `Web/Services/ServicesController.php`
3. Mantener rutas legacy intactas

#### Trabajo a Realizar

```php
app/Actions/Service/
├── ListServicesByStatusAction.php    # 3 horas
├── CreateServiceAction.php           # 4 horas (complejo)
├── UpdateServiceAction.php           # 2 horas
├── CancelServiceAction.php           # 2 horas
├── AssignDriverAction.php            # 3 horas (ya existe parcial)
├── GetServicePointsAction.php        # 1.5 horas
└── GetDashboardMetricsAction.php     # 2 horas

app/Services/Service/
└── ServiceService.php                # 4 horas

app/Http/
├── Controllers/Web/V2/ServiceController.php  # 3 horas
├── Requests/Web/Service/
│   ├── StoreServiceRequest.php               # 2 horas
│   ├── UpdateServiceRequest.php              # 1 hora
│   └── AssignDriverRequest.php               # 1 hora
└── Resources/Web/Service/
    ├── ServiceResource.php                   # 2 horas
    └── ServicePointResource.php              # 1 hora
```

**Total Fase 8:** 31.5 horas

---

### Fase 9: Limpieza y Documentación - 3 días
**Objetivo:** Finalizar migración

| Tarea | Descripción | Horas |
|-------|-------------|-------|
| 9.1 | Deprecar rutas legacy web | 2h |
| 9.2 | Actualizar RouteServiceProvider | 1h |
| 9.3 | Tests de regresión completos | 6h |
| 9.4 | Documentar API V2 | 4h |
| 9.5 | Eliminar código muerto | 2h |

**Total Fase 9:** 15 horas

---

## 📅 Timeline y Resumen de Esfuerzo

### Resumen por Fase

| Fase | Módulo | Complejidad | Horas | Días |
|------|--------|-------------|-------|------|
| 0 | Preparación | ⭐ | 11 | 1.5 |
| 1 | Configuration | ⭐ | 4 | 0.5 |
| 2 | Vehicles | ⭐⭐ | 6 | 1 |
| 3 | Clients | ⭐⭐ | 9 | 1.5 |
| 4 | Costs | ⭐⭐ | 13.5 | 2 |
| 5 | Users | ⭐⭐⭐ | 13 | 2 |
| 6 | Analytics/Reports | ⭐⭐ | 9 | 1.5 |
| 7 | Suggestions | ⭐ | 5 | 0.5 |
| 8 | **Services** | ⭐⭐⭐⭐ | 31.5 | 4 |
| 9 | Limpieza | ⭐⭐ | 15 | 2 |
| | **TOTAL** | | **117h** | **~17 días** |

### Calendario Visual

```
Semana 1:  ████████████████ Fase 0 + Fase 1 (Configuration)
Semana 2:  ████████████████ Fase 2 (Vehicles) + Fase 3 (Clients)  
Semana 3:  ████████████████ Fase 4 (Costs) + Fase 5 (Users - inicio)
Semana 4:  ████████████████ Fase 5 (Users - fin) + Fase 6 (Analytics)
Semana 5:  ████████████████ Fase 7 (Suggestions) + Fase 8 (Services - inicio)
Semana 6:  ████████████████ Fase 8 (Services - continúa)
Semana 7:  ████████████████ Fase 8 (Services - fin) + Fase 9 (Limpieza)

Total: ~7 semanas (~117 horas de desarrollo)
```

### Orden de Ejecución Recomendado

```
[Más Simple] ────────────────────────────────────────► [Más Complejo]

Fase 0 → Fase 1 → Fase 2 → Fase 3 → Fase 7 → Fase 4 → Fase 6 → Fase 5 → Fase 8 → Fase 9
Prep    Config   Vehicle  Client   Suggest   Cost    Analytics  User   Service  Cleanup
```

---

## ✅ Proceso de Verificación

### Checklist por Action

Cada Action debe cumplir:

```markdown
## Checklist: {ActionName}

### Estructura
- [ ] Namespace correcto: `App\Actions\{Module}`
- [ ] Clase con suffix `Action`
- [ ] Método principal: `execute()` o `__invoke()`
- [ ] Inyección de dependencias en constructor
- [ ] Retorno tipado: `JsonResponse` o DTO

### Validación
- [ ] Form Request creado si requiere input
- [ ] Mensajes de error en español
- [ ] Validación completa de campos

### Respuesta
- [ ] Usa API Resource para transformar
- [ ] Códigos HTTP correctos
- [ ] Estructura de respuesta estándar

### Tests
- [ ] Test unitario creado
- [ ] Test de integración creado
- [ ] Cobertura mínima 80%

### Documentación
- [ ] PHPDoc completo
- [ ] Ejemplo de uso en código
```

### Verificación Automática por Fase

```bash
# Script de verificación: scripts/verify-refactor.sh

#!/bin/bash
MODULE=$1

echo "🔍 Verificando módulo: $MODULE"

# 1. Verificar estructura de archivos
echo "📁 Verificando estructura..."
test -d "app/Actions/$MODULE" || echo "❌ Falta directorio Actions/$MODULE"
test -d "app/Http/Requests/Web/$MODULE" || echo "❌ Falta directorio Requests/$MODULE"
test -d "app/Http/Resources/Web/$MODULE" || echo "❌ Falta directorio Resources/$MODULE"

# 2. Verificar que controller es delgado
LINES=$(wc -l < "app/Http/Controllers/Web/V2/${MODULE}Controller.php" 2>/dev/null)
if [ "$LINES" -gt 100 ]; then
    echo "⚠️ Controller tiene $LINES líneas (máximo 100)"
fi

# 3. Ejecutar tests del módulo
echo "🧪 Ejecutando tests..."
vendor/bin/phpunit tests/Feature/Web/V2/${MODULE}Test.php --testdox

# 4. Análisis estático
echo "🔬 Análisis estático..."
vendor/bin/phpstan analyse app/Actions/$MODULE --level=5

echo "✅ Verificación completada"
```

### Métricas de Éxito

| Métrica | Valor Objetivo | Cómo Medir |
|---------|---------------|------------|
| Líneas por Controller | < 100 | `wc -l` |
| Líneas por Action | < 150 | `wc -l` |
| Cobertura de tests | > 80% | PHPUnit coverage |
| Complejidad ciclomática | < 10 | PHPStan |
| Errores PHPStan nivel 5 | 0 | PHPStan |
| Rutas V2 migrads | 100% | `php artisan route:list` |

### Proceso de Code Review

Cada PR debe incluir:

1. **Descripción clara** del módulo/action refactorizado
2. **Screenshot/diff** de antes/después en líneas
3. **Tests pasando** con cobertura
4. **Checklist** del Action completado
5. **Backward compatibility** verificada

---

## 🔄 Compatibilidad con Versión Móvil

### Reglas de Convivencia

1. **Rutas legacy se mantienen** en `/api/` para móvil
2. **Rutas V2** usan `/api-web/` exclusivamente
3. **Modelos compartidos** - no modificar estructura
4. **Responses legacy** - mantener formato `flag/code/message/data`
5. **Middleware separado**:
   - Móvil: `jwt-auth:driver`
   - Web: `web.session` + `bouncer`

### Mapeo de Rutas

| Función | Ruta Móvil (Legacy) | Ruta Web V2 |
|---------|---------------------|-------------|
| Listar servicios | `GET /api/services/na` | `GET /api-web/services/v2/na` |
| Crear servicio | `POST /api/services` | `POST /api-web/services/v2/store` |
| Asignar driver | `GET /api/services/{id}/driver/{d}/asignar` | `PATCH /api-web/services/v2/{id}/assign-driver/{d}` |

---

## 📚 Referencias

- [Laravel Actions Pattern](https://laravel-news.com/action-pattern-laravel)
- [Form Requests](https://laravel.com/docs/validation#form-request-validation)
- [API Resources](https://laravel.com/docs/eloquent-resources)
- Driver V2 como modelo: `app/Http/Controllers/Web/V2/DriverController.php`

---

## 🚀 Comenzando: Fase 0 + Fase 1

### Primera Semana - Preparación y Configuration

**Día 1-2: Fase 0 - Fundamentos**
1. ✅ Crear `app/Traits/ApiResponseTrait.php`
2. ✅ Crear `app/Actions/BaseAction.php`
3. ✅ Crear comando `php artisan make:action`
4. ✅ Crear `docs/CODING_STANDARDS.md`

**Día 2-3: Fase 1 - Configuration (módulo más simple)**
1. ✅ Crear `app/Actions/Configuration/GetConfigurationAction.php`
2. ✅ Crear `app/Actions/Configuration/UpdateConfigurationAction.php`
3. ✅ Refactorizar controller existente
4. ✅ Tests de verificación

### ¿Por qué empezar con Configuration?

| Razón | Detalle |
|-------|---------|
| ✅ Ya tiene Repository | `ConfigurationsRepository` existe |
| ✅ Ya tiene Resource | `ConfigurationResource` existe |
| ✅ Ya tiene Request | `ConfigurationRequest` existe |
| ✅ Solo 2 endpoints | GET y PUT |
| ✅ 100% Web | No afecta móvil |
| ✅ Controller pequeño | Solo 35 líneas |

**Este módulo sirve como "template" para todos los demás.**

---

## 📋 Comandos Útiles

```bash
# Verificar estado de rutas web
php artisan route:list --path=api-web

# Verificar estado de rutas móviles (NO TOCAR)
php artisan route:list --path=api/mobile

# Ejecutar tests de un módulo
vendor/bin/phpunit tests/Feature/Web/V2/{Module}Test.php --testdox

# Análisis estático
vendor/bin/phpstan analyse app/Actions/{Module} --level=5

# Contar líneas de un controller
wc -l app/Http/Controllers/Web/V2/{Module}Controller.php
```

---

**¿Procedemos con la Fase 0?**