# Estrategia de Auditoría Frontend-Backend

**Fecha:** 14 de Marzo de 2026
**Objetivo:** Asegurar consistencia entre frontend y backend antes de aplicar cambios
**Alcance:** Vistas, JavaScript, APIs, Estados de UI

---

## 🎯 ESTRATEGIA DE AUDITORÍA

### Fase 1: Mapeo de Endpoints (30 min)
```bash
# Obtener todas las rutas definidas
php spark routes > routes_backend.txt

# Buscar todas las llamadas AJAX en frontend
grep -r "\.ajax\|fetch\|axios" public/assets/js/ > ajax_calls.txt
grep -r "\$.get\|\$.post\|\$.ajax" public/assets/js/ >> ajax_calls.txt
```

### Fase 2: Inventario de Vistas (45 min)
```bash
# Listar todas las vistas
find app/Views -name "*.php" | sort > views_inventory.txt

# Buscar vistas que usan forms (POST/PUT/DELETE)
grep -r "form.*method" app/Views/ > forms_inventory.txt

# Buscar vistas con JavaScript inline
grep -r "<script>" app/Views/ > inline_scripts.txt
```

### Fase 3: Validación de Estados (60 min)
- Revisar select/dropdowns con estados hardcoded
- Verificar badges/labels con estados
- Validar que coincidan con enums del backend

### Fase 4: Testing Manual (90 min)
- Probar cada flujo crítico en navegador
- Verificar consola de errores
- Revisar Network tab para 404s

---

## 📊 CHECKLIST DE AUDITORÍA

### 1. Endpoints API

#### A. Listar Todos los Endpoints
```bash
php spark routes | grep -E "GET|POST|PUT|DELETE" > endpoints.txt
```

#### B. Por Cada Endpoint Verificar:
- [ ] Existe llamada en frontend
- [ ] Parámetros esperados coinciden
- [ ] Response format es el esperado
- [ ] Manejo de errores implementado
- [ ] Loading states en UI

#### C. Buscar Endpoints Huérfanos
```javascript
// Endpoints en JS que ya no existen en backend
// grep en archivos JS → comparar con routes
```

### 2. Estados y Enums

#### A. Estados de Sale
**Backend (`SaleModel`):**
```php
// Revisar en código
delivery: 'pending' | 'in_process' | 'ready_for_delivery' | 'delivered'
type: 'cash' | 'aside' | 'credit'
payment_type: 'cash' | 'card' | 'transfer' | 'credit' | 'multi'
```

**Frontend (verificar en):**
- [ ] `app/Views/components/sales/` - Dropdowns
- [ ] `public/assets/js/custom/sale.js` - Validaciones
- [ ] Badges/labels de estado

#### B. Estados de Order
**Backend:**
```php
laboratory_status: 'pending_shipment' | 'in_process' | 'received'
```

**Frontend:**
- [ ] Vista de órdenes muestra todos los estados
- [ ] Botones de cambio de estado
- [ ] Validaciones de transiciones

#### C. Estados de Payment
**Backend:**
```php
status: 'pending' | 'paid' | 'deposited'
payment_type: 'cash' | 'card' | 'transfer'
```

**Frontend:**
- [ ] Formulario de nuevo pago
- [ ] Vista de pagos existentes
- [ ] Botón "Marcar como depositado"

### 3. Formularios y Validaciones

#### A. Por Cada Formulario Verificar:
```markdown
- [ ] Action URL existe en routes
- [ ] Method (POST/PUT) es correcto
- [ ] Campos requeridos coinciden con backend
- [ ] Validación en frontend coincide con backend
- [ ] Mensajes de error se muestran
- [ ] Redirección después de submit
```

#### B. Lista de Formularios Críticos:
1. **Nueva Venta** (`/nueva-orden/venta`)
   - [ ] URL existe
   - [ ] Todos los campos se envían
   - [ ] Validación de multipagos
   - [ ] Validación de saldo

2. **Nuevo Pago** (`/sale/:id/payment`)
   - [ ] Valida monto máximo
   - [ ] Tipos de pago disponibles
   - [ ] Cuentas bancarias cargadas

3. **Nueva Orden** (`/order/create`)
   - [ ] Valida paciente
   - [ ] Labs disponibles
   - [ ] Certificados opcionales

4. **Nuevo Paciente** (`/patient/create`)
   - [ ] Detección de duplicados
   - [ ] Todos los campos
   - [ ] Validación de RFC (si aplica)

### 4. JavaScript y AJAX

#### A. Por Cada Archivo JS Verificar:
```javascript
// Buscar todos los AJAX calls
$.ajax({
    url: '/endpoint', // ← Verificar que exista
    type: 'POST',     // ← Verificar método
    data: {...},      // ← Verificar campos esperados
    success: fn,      // ← Verificar response format
    error: fn         // ← Verificar manejo de errores
});
```

#### B. Archivos JS Críticos:
```bash
public/assets/js/custom/
├── sale.js                    # Ventas
├── patient.js                 # Pacientes
├── patient-detail.js          # Detalle paciente
├── patient-duplicate-detection.js # Duplicados
├── patient-merge-utility.js   # Fusión
└── order.js                   # Órdenes
```

### 5. DataTables y Listados

#### A. Por Cada DataTable Verificar:
- [ ] URL de datos existe (`ajax.url`)
- [ ] Columnas coinciden con response
- [ ] Botones de acción tienen handlers
- [ ] Filtros funcionan
- [ ] Paginación configurada

#### B. DataTables Conocidos:
```javascript
// Buscar inicializaciones
grep -r "DataTable\|dataTable" public/assets/js/
```

### 6. Modales y Componentes

#### A. Por Cada Modal Verificar:
- [ ] ID único
- [ ] Trigger button existe
- [ ] Submit funciona
- [ ] Close/Cancel limpia estado
- [ ] Validación en submit

#### B. Modales Críticos:
1. **Modal de Fusión de Pacientes** (`#patientMergeModal`)
2. **Modal de Nueva Venta** (si existe)
3. **Modal de Pago** (si existe)
4. **Modal de Consulta** (`#full-consultation`)

---

## 🔍 COMANDOS DE AUDITORÍA

### 1. Mapear Rutas Backend
```bash
# Todas las rutas
php spark routes > audit/backend_routes.txt

# Solo resource routes
php spark routes | grep "resource" > audit/resource_routes.txt

# Routes por Controller
php spark routes | grep "Sale::" > audit/sale_routes.txt
php spark routes | grep "Patient::" > audit/patient_routes.txt
php spark routes | grep "Order::" > audit/order_routes.txt
php spark routes | grep "Payment::" > audit/payment_routes.txt
```

### 2. Inventariar Vistas
```bash
# Todas las vistas
find app/Views -name "*.php" | sort > audit/views_inventory.txt

# Vistas por recurso
find app/Views -path "*/components/sales/*" > audit/sale_views.txt
find app/Views -path "*/components/patients/*" > audit/patient_views.txt
find app/Views -path "*/components/orders/*" > audit/order_views.txt

# Vistas con forms
grep -r "<form" app/Views/ | cut -d: -f1 | sort -u > audit/views_with_forms.txt
```

### 3. Buscar Llamadas AJAX
```bash
# Todas las llamadas AJAX
grep -rn "\.ajax\|fetch(" public/assets/js/ > audit/ajax_calls.txt

# Por método
grep -rn "type.*POST\|method.*POST" public/assets/js/ > audit/ajax_post.txt
grep -rn "type.*GET\|method.*GET" public/assets/js/ > audit/ajax_get.txt
grep -rn "type.*PUT\|method.*PUT" public/assets/js/ > audit/ajax_put.txt
grep -rn "type.*DELETE\|method.*DELETE" public/assets/js/ > audit/ajax_delete.txt

# URLs más llamadas
grep -roh "url.*['\"]\/[^'\"]*" public/assets/js/ | sort | uniq -c | sort -rn > audit/most_called_urls.txt
```

### 4. Buscar Estados Hardcoded
```bash
# En JavaScript
grep -rn "pending\|in_process\|delivered\|received" public/assets/js/ > audit/js_states.txt

# En vistas PHP
grep -rn "pending\|in_process\|delivered\|received" app/Views/ > audit/php_states.txt

# En selects/options
grep -rn "<option.*value" app/Views/ > audit/select_options.txt
```

### 5. Verificar Endpoints No Utilizados
```bash
# Crear script de verificación
cat > audit/check_unused_endpoints.sh << 'EOF'
#!/bin/bash

# Obtener todas las rutas
php spark routes | grep -E "GET|POST|PUT|DELETE" | awk '{print $2}' > /tmp/backend_routes.txt

# Buscar cada ruta en el frontend
while read route; do
    # Limpiar ruta (quitar parámetros)
    clean_route=$(echo "$route" | sed 's/\/([^)]*)//g')

    # Buscar en JS y vistas
    found=$(grep -r "$clean_route" app/Views/ public/assets/js/ 2>/dev/null | wc -l)

    if [ "$found" -eq 0 ]; then
        echo "⚠️  UNUSED: $route"
    fi
done < /tmp/backend_routes.txt
EOF

chmod +x audit/check_unused_endpoints.sh
./audit/check_unused_endpoints.sh > audit/unused_endpoints.txt
```

### 6. Verificar Endpoints 404
```bash
# Buscar URLs en JS que podrían no existir
grep -roh "url.*['\"]\/[^'\"]*" public/assets/js/ | sed "s/url.*['\"]//g" | sed "s/['\"].*//g" | sort -u > /tmp/frontend_urls.txt

# Comparar con rutas backend
while read url; do
    # Verificar si existe en routes
    php spark routes | grep -q "$url"
    if [ $? -ne 0 ]; then
        echo "❌ 404: $url"
    fi
done < /tmp/frontend_urls.txt > audit/potential_404s.txt
```

---

## 📝 TEMPLATE DE REPORTE POR VISTA

Para cada vista principal, llenar:

### Vista: `app/Views/components/sales/new.php`

**Formularios:**
- [ ] Form action: `/sale/create` - ✅ Existe | ❌ No existe
- [ ] Method: POST - ✅ Correcto | ❌ Incorrecto
- [ ] Validación JS: ✅ Sí | ❌ No

**AJAX Calls:**
```javascript
// Listar todas las llamadas
1. POST /sale/create
   - Status: ✅ Existe
   - Params: ✅ Coinciden
   - Response: ✅ OK / ❌ Difiere

2. GET /patient/search
   - Status: ⚠️ Ruta cambió a /patient/search-duplicates
```

**Estados Mostrados:**
```php
// Listar todos los estados hardcoded
- delivery: ['pending', 'in_process', 'ready', 'delivered']
  Status: ✅ Coinciden | ❌ Falta 'ready_for_delivery'
```

**Dependencias:**
```javascript
// Scripts requeridos
- jQuery 3.7 ✅
- SweetAlert2 ✅
- sale.js ✅
```

**Problemas Encontrados:**
1. [ ] Estado 'ready' debería ser 'ready_for_delivery'
2. [ ] Falta validación de saldo antes de marcar delivered
3. [ ] ...

---

## 🧪 TESTING MANUAL POR FLUJO

### Flujo 1: Nueva Venta Completa
```markdown
1. Abrir navegador en /nueva-orden/venta
   - [ ] Vista carga sin errores console
   - [ ] Todos los dropdowns se llenan

2. Seleccionar paciente
   - [ ] Autocomplete funciona
   - [ ] Carga prescripciones del paciente

3. Agregar items al carrito
   - [ ] Buscar item funciona
   - [ ] Agregar al carrito funciona
   - [ ] Cálculo de total correcto

4. Seleccionar tipo de pago
   - [ ] Opciones correctas (cash, card, transfer, credit, multi)
   - [ ] Si multi: permite agregar N pagos
   - [ ] Validación de suma = total

5. Submit
   - [ ] Request se envía correctamente
   - [ ] Response 200 OK
   - [ ] Redirección a detalle de venta

6. Verificar en detalle
   - [ ] Venta creada correctamente
   - [ ] Items guardados
   - [ ] Pagos registrados
```

### Flujo 2: Cambiar Estado de Delivery
```markdown
1. Abrir venta existente
   - [ ] Vista carga

2. Verificar estado actual
   - [ ] Badge muestra estado correcto

3. Intentar cambiar a 'delivered'
   - [ ] Si saldo > 0: ❌ Debe mostrar error
   - [ ] Si saldo = 0: ✅ Debe permitir

4. Después de cambiar
   - [ ] Badge actualiza
   - [ ] DB actualizado
```

### Flujo 3: Generar Comisiones Mensuales
```markdown
⚠️ IMPORTANTE: Este flujo AÚN NO EXISTE en UI
Necesita implementarse según AGENTS.md

1. [ ] Vista /commission/monthly-review no existe
2. [ ] Método Commission::monthlyReview() no existe
3. [ ] Vista de aprobación no existe
```

---

## 📊 MATRIZ DE VERIFICACIÓN

### Recursos Principales

| Recurso | Vistas | JS | Endpoints | Estados | Status |
|---------|--------|----|-----------|---------| -------|
| Patient | ✅ 5 | ✅ 3 | ✅ 7 | N/A | ✅ OK |
| Sale | ? | ? | ? | ? | 🔍 Auditar |
| Order | ? | ? | ? | ? | 🔍 Auditar |
| Payment | ? | ? | ? | ? | 🔍 Auditar |
| Invoice | ? | ? | ? | ? | 🔍 Auditar |
| Commission | ? | ? | ? | ⚠️ | ❌ UI faltante |

### Componentes Críticos

| Componente | Ubicación | Depende de | Status |
|------------|-----------|------------|--------|
| PatientMergeUtility | patient-merge-utility.js | /patient/merge, /patient/stats | ✅ OK |
| DuplicateDetection | patient-duplicate-detection.js | /patient/search-duplicates | ✅ OK |
| SaleForm | sale.js | /sale/create | 🔍 Auditar |
| OrderTracking | order.js | /order/*, /shipment/* | 🔍 Auditar |

---

## 🚀 PLAN DE EJECUCIÓN

### Día 1: Mapeo (2-3 horas)
```bash
# 1. Crear carpeta de auditoría
mkdir -p audit

# 2. Ejecutar todos los comandos de mapeo
php spark routes > audit/backend_routes.txt
find app/Views -name "*.php" > audit/views_inventory.txt
grep -r "\.ajax\|fetch" public/assets/js/ > audit/ajax_calls.txt

# 3. Crear spreadsheet con matriz de verificación
```

### Día 2: Análisis (3-4 horas)
```bash
# 1. Por cada recurso principal
#    - Listar vistas
#    - Listar JS files
#    - Listar endpoints
#    - Verificar coincidencias

# 2. Documentar discrepancias
```

### Día 3: Testing Manual (4-5 horas)
```bash
# 1. Probar flujo completo de Ventas
# 2. Probar flujo completo de Pagos
# 3. Probar flujo completo de Órdenes
# 4. Probar cambios de estado
# 5. Documentar bugs encontrados
```

### Día 4: Reporte y Priorización (2 horas)
```bash
# 1. Consolidar hallazgos
# 2. Priorizar por severidad:
#    - Crítico: Rompe flujo de negocio
#    - Alto: UX pobre o estados incorrectos
#    - Medio: Inconsistencias menores
#    - Bajo: Mejoras opcionales

# 3. Crear plan de corrección
```

---

## 📄 TEMPLATE DE REPORTE FINAL

```markdown
# Auditoría Frontend-Backend - Reporte

**Fecha:** DD/MM/YYYY
**Auditor:** Nombre
**Recursos Auditados:** X de Y

## Resumen Ejecutivo

- Total vistas: X
- Total endpoints: Y
- Vistas con problemas: Z
- Endpoints huérfanos: W
- Severidad promedio: Alta/Media/Baja

## Hallazgos por Severidad

### Críticos (Rompen funcionalidad)
1. **Sale delivery sin validación de saldo**
   - Vista: `app/Views/components/sales/detail.php`
   - Problema: Botón "Entregar" no valida saldo
   - Solución: Agregar validación antes de submit

2. ...

### Altos (UX pobre)
1. **Estados de Order no sincronizados**
   - Vista: `app/Views/components/orders/list.php`
   - Problema: Muestra estados desactualizados
   - Solución: Refrescar después de actualizar

2. ...

### Medios (Inconsistencias)
1. **Estados hardcoded incorrectos**
   - Vista: `app/Views/components/sales/filters.php`
   - Problema: 'ready' debería ser 'ready_for_delivery'
   - Solución: Usar constantes del backend

2. ...

### Bajos (Mejoras)
1. ...

## Estadísticas

| Métrica | Valor |
|---------|-------|
| Vistas sin problemas | X% |
| Endpoints utilizados | Y% |
| Cobertura de tests | Z% |

## Plan de Acción

1. Corregir críticos (1-2 días)
2. Corregir altos (2-3 días)
3. Corregir medios (3-5 días)
4. Mejoras opcionales (backlog)

## Anexos

- Lista completa de vistas
- Lista completa de endpoints
- Capturas de errores
```

---

## 💡 TIPS Y MEJORES PRÁCTICAS

### 1. Usar Constantes para Estados
```php
// Backend: app/Config/Constants.php
define('SALE_STATUS', [
    'PENDING' => 'pending',
    'IN_PROCESS' => 'in_process',
    'READY' => 'ready_for_delivery',
    'DELIVERED' => 'delivered'
]);

// Frontend: Exponer en JavaScript
<script>
const SALE_STATUS = <?=json_encode(SALE_STATUS)?>;
</script>
```

### 2. Validar Endpoints en Build
```bash
# Script que falla CI si hay endpoints 404
# check-endpoints.sh
#!/bin/bash
errors=0

while read url; do
    php spark routes | grep -q "$url" || {
        echo "ERROR: Endpoint no existe: $url"
        errors=$((errors+1))
    }
done < frontend_urls.txt

exit $errors
```

### 3. Documentar Cambios de API
```markdown
# CHANGELOG_API.md

## v2.1.0 - 2026-03-14

### Breaking Changes
- `/patient/search` → `/patient/search-duplicates`
  - Afecta: `patient-duplicate-detection.js`
  - Migración: Actualizar URL en línea 45

### New Endpoints
- `POST /commission/monthly-review` - Generar comisiones del mes
```

---

**Siguiente Paso:** ¿Ejecutamos el mapeo automático primero o prefieres que empiece con la auditoría manual de un flujo específico?