## **ANÁLISIS TÉCNICO: API DE PANEL Y CHECKLIST**

### **1. ESTRUCTURA DE CARPETAS**

```
api_De_Panel_y_checklist/
├── config/                          # Configuración centralizada
│   └── conexion.php                 # Conexión PDO a MariaDB
├── endpoint/                        # Endpoints de demostración (Residencia Profesional)
│   ├── iniciar.php                  # Crear nuevo reporte
│   ├── consultar_id.php             # Consultar reporte por ID
│   ├── Token.php                    # Validación Bearer Token
│   └── raw.txt                      # Log de depuración de JSON
├── reportes/                        # Endpoints de producción
│   ├── guardar_checklist.php        # Guardar checklist + cambiar estado
│   ├── listar.php                   # Listar todos los reportes
│   └── estado_reporte.php           # Funciones de validación de estados
├── metricas/                        # Endpoints de métricas de revisión
│   ├── iniciar_revision.php         # Registrar inicio de revisión
│   ├── consultar_metricas.php       # Consultar tiempo de revisión
│   ├── consultar_timeline.php       # Consultar historial de cambios
│   └── finalizar_revision.php       # Registrar finalización + calcular duración
├── export/                          # Generador de reportes Excel
│   ├── export_excel.php             # Orquestador principal
│   ├── export.charts.php            # Coordinador de gráficas
│   ├── assets/                      # Recursos (logos)
│   ├── charts/                      # Generadores de gráficas
│   │   ├── operadores/              # Gráfica: Fallas por operador
│   │   ├── unidades/                # Gráfica: Fallas por unidad
│   │   ├── componentes/             # Gráfica: Fallas por componente
│   │   └── estadisticas/            # Gráficas: Estado y semanas
│   ├── covers/                      # Portada del reporte
│   │   ├── export.cover.php         # Genera portada con métricas
│   │   └── export.logo.php          # Inserta logo TSAR
│   ├── metrics/                     # Cálculo de métricas globales
│   │   └── export.metrics.php       # Análisis estadístico
│   ├── styles/                      # Estilos para Excel
│   │   └── export.styles.php        # Estilos reutilizables
│   └── tables/                      # Tablas de datos
│       ├── export.tables.php        # Hojas: Resumen, Fallas, Detalle, Métricas
│       ├── checklist.map.php        # Mapeo ID → Descripción (46 items)
│       └── export.helpers.php       # Funciones auxiliares
├── Uploads/                         # Almacenamiento de archivos
│   ├── upload_foto.php              # Endpoint para cargar evidencias
│   └── Reportes/                    # Carpetas por reporte (ID)
│       ├── 62/                      # Carpeta de reporte 62
│       └── 68/                      # Carpeta de reporte 68
└── README_API.md                    # Documentación del proyecto
```

---

### **2. RESPONSABILIDAD DE CADA CARPETA**

| Carpeta | Propósito |
|---------|-----------|
| **config/** | Centraliza credenciales y conexión PDO a MariaDB (UTF-8). Evita duplicación de código. |
| **endpoint/** | Endpoints iniciales para demostración durante Residencia Profesional. iniciar.php y consultar_id.php manejan operaciones básicas con validación Bearer (Token.php). |
| **reportes/** | Endpoints productivos consumidos por Checklist y Panel Administrativo. Gestiona ciclo completo: guardar checklist, cambiar estado, listar. |
| **metricas/** | Registra y consulta métricas de revisión: hora inicio/fin, duración, timeline de cambios. Ejecuta operaciones singleton (evita duplicados). |
| **export/** | Genera reportes administrativos en Excel usando PhpSpreadsheet. Incluye portada, tablas de datos, gráficas estadísticas y estilos. |
| **export/charts/** | Genera 5 gráficas: operadores, unidades, componentes, estado, reportes/semana. Usa DataSeries y PlotArea de PhpOffice. |
| **export/covers/** | Crea portada con logo TSAR, título, fecha y métricas de resumen. |
| **export/metrics/** | Calcula 18+ métricas globales: totales, porcentajes, promedios, fallos por categoría. |
| **export/styles/** | Aplica estilos reutilizables: encabezados (azul #1F4E78), bordes, alineación, congelación de filas. |
| **export/tables/** | Genera 4 hojas Excel: Resumen, Fallas, Detalle, Métricas. Incluye hipervínculos a fotos. |
| **Uploads/** | Almacena evidencias fotográficas organizadas por `reporteId/itemId.ext`. Valida MIME: JPEG, PNG, WebP. |

---

### **3. RESPONSABILIDAD DE CADA ARCHIVO PHP**

#### **Configuración**
| Archivo | Función |
|---------|---------|
| conexion.php | Establece conexión PDO con MariaDB (BD: `tsargroup_ddsriot_db`). Usa try-catch con ERRMODE_EXCEPTION. |

#### **Endpoints de Demostración**
| Archivo | Método | Entrada | Salida | Descripción |
|---------|--------|---------|--------|-------------|
| iniciar.php | POST | JSON: semana, fechaInicio, horaInicio, unidad, operador, placasJaula | `{ok, id}` | Inserta reporte con estado "activo". Devuelve ID generado. Registra JSON en raw.txt. |
| consultar_id.php | GET | URL: `?id=<int>` | `{ok, reporte}` | Consulta reporte, convierte checklists JSON a arrays, devuelve estructura completa. |
| Token.php | N/A (incluido) | Header: `Authorization: Bearer <token>` | Válida o rechaza (401) | Define const `API_TOKEN` (256 caracteres). Usa `hash_equals()` contra ataques timing. |

#### **Endpoints de Producción (reportes/)**
| Archivo | Método | Entrada | Salida | Descripción |
|---------|--------|---------|--------|-------------|
| guardar_checklist.php | POST | JSON: id, checklist[], checklistJaula[], timeline[] | `{ok, mensaje}` | Actualiza reporte si estado="activo". Serializa checklists a JSON. Inserta timeline en `revision_timeline`. Notifica a API externa (curl) en Betics. Usa transacción con rollback. |
| listar.php | GET | Ninguna | `{ok, reportes[]}` | Consulta todos los reportes. Join con `revision_metricas`. Convierte JSON a arrays. Ordena DESC por fecha creación. |
| estado_reporte.php | N/A (funciones) | N/A | Funciones reutilizables | Define 3 funciones: `obtenerReportePorId()`, `validarEstadoReporte()` (valida 3 estados), `cambiarEstado()`. |

#### **Endpoints de Métricas (metricas/)**
| Archivo | Método | Entrada | Salida | Descripción |
|---------|--------|---------|--------|-------------|
| iniciar_revision.php | POST | JSON: reporteId | `{ok, mensaje}` | Inserta en `revision_metricas` si no existe (singleton pattern). Registra `NOW()` en `hora_inicio`. |
| consultar_metricas.php | POST | JSON: reporteId | `{ok, metricas}` | Consulta duración en segundos (puede ser null si no finalizado). |
| consultar_timeline.php | POST | JSON: reporteId | `{ok, timeline[]}` | Valida reporte existe. Devuelve array de eventos ordenados por orden. Normaliza tipos (int). |
| finalizar_revision.php | POST | JSON: reporteId | `{ok, metricas}` | Calcula TIMESTAMPDIFF (SECOND) entre hora_inicio y NOW(). Evita doble finalización. |

#### **Sistema de Carga de Archivos**
| Archivo | Método | Entrada | Salida | Descripción |
|---------|--------|---------|--------|-------------|
| upload_foto.php | POST | Multipart: file, reportId, itemId | `{ok, url}` | Valida MIME (finfo). Crea carpeta `/Uploads/Reportes/{reportId}/`. Mueve archivo a `{itemId}.{ext}`. Devuelve URL pública. |

#### **Sistema de Exportación (export/)**
| Archivo | Función | Descripción |
|---------|---------|-------------|
| export_excel.php | Orquestador | Consulta todos reportes, descodifica JSON, calcula métricas, crea workbook, aplica estilos, genera archivo XLSX con nombre `TSAR_Reportes_[fecha].xlsx`. |
| export.charts.php | Coordinador | Invoca 5 generadores de gráficas. |
| export.tables.php | Generador de hojas | Crea 4 hojas: Resumen (1 fila/reporte), Fallas (1 fila/falla), Detalle (parcial), Métricas. |
| export.helpers.php | Utilidades | Funciones: `obtenerItemsReporte()`, `contarFallas()`, `contarItemsEstado()`, `contarFotos()`, `obtenerDescripcionItem()`. |
| checklist.map.php | Mapa estático | Define `$CHECKLIST_MAP[1..46]` = descripción. Items tractocamión (1-31), lubricación (21-24), operación (25-26), jaula (32-46). |
| export.metrics.php | Cálculo | Calcula 18 métricas: totales, porcentajes, fallos por operador/unidad/componente, reportes/semana. |
| export.cover.php | Portada | Crea hoja "Portada" con logo, título, fecha generación, totales, porcentajes. |
| export.logo.php | Logo | Inserta imagen `assets/tsar_logo.png` en hoja (require archivo). |
| export.styles.php | Estilos | Funciones reutilizables: `aplicarEstiloEncabezado()` (azul, blanco, centrado), `aplicarEstiloTabla()`, `autoAjustarColumnas()`, `congelarEncabezado()`, `aplicarFiltroAutomatico()`, `aplicarFormatoFechas()`, `aplicarFormatoHoras()`. |
| `export/charts/*/chart.*.php` | Gráficas | 5 archivos generan gráficas de barras: operadores, unidades, componentes (todos usan DataSeries, PlotArea, Chart de PhpOffice). |

---

### **4. DEPENDENCIAS ENTRE MÓDULOS**

```
Flujo de Entrada (Checklist App)
└── endpoint/iniciar.php (POST)
    └── config/conexion.php
    ├── endpoint/Token.php (validación Bearer)
    └── INSERT reportes (estado: "activo")

Flujo de Revisión (Operador)
└── metricas/iniciar_revision.php (POST) → INSERT revision_metricas
└── metricas/consultar_timeline.php (POST) → SELECT revision_timeline
└── reportes/guardar_checklist.php (POST)
    ├── reportes/estado_reporte.php (validar estado = "activo")
    ├── INSERT revision_timeline (para cada evento)
    ├── UPDATE reportes (estado: "enviado", serializa checklists)
    └── curl → API externa Betics

Flujo de Consultas (Panel Admin)
├── reportes/listar.php (GET)
│   └── LEFT JOIN revision_metricas
├── endpoint/consultar_id.php (GET)
└── metricas/consultar_metricas.php (POST)
└── metricas/finalizar_revision.php (POST)

Flujo de Evidencias
└── Uploads/upload_foto.php (POST)
    ├── Valida MIME: image/jpeg, image/png, image/webp
    ├── mkdir /Uploads/Reportes/{reportId}/
    └── Devuelve URL pública

Flujo de Exportación
└── export/export_excel.php
    ├── SELECT reportes (todos)
    ├── export/metrics/export.metrics.php → calcula 18+ métricas
    ├── export/tables/checklist.map.php → obtiene descripciones
    ├── export/covers/export.cover.php → crea portada
    ├── export/covers/export.logo.php → inserta logo
    ├── export/tables/export.tables.php → crea 4 hojas
    │   ├── Resumen (items, fallas por reporte)
    │   ├── Fallas (detalles de cada falla)
    │   ├── Detalle (parcial)
    │   └── Métricas
    ├── export/charts/export.charts.php → 5 gráficas
    │   ├── operadores → chart.operadores.php
    │   ├── unidades → chart.unidades.php
    │   ├── componentes → chart.componentes.php
    │   ├── estado → chart.estado.php
    │   └── semanas → chart.semanas.php
    ├── export/styles/export.styles.php → aplica formatos
    └── Genera XLSX descargable
```

---

### **5. FLUJO GENERAL DE EJECUCIÓN**

#### **Escenario 1: Crear y Completar un Checklist**
1. **App Checklist** → POST iniciar.php con datos básicos (semana, operador, unidad, etc.)
   - BD crea reporte en estado `"activo"` con ID
   - Devuelve `{ok, id}`
2. **App Checklist** → POST iniciar_revision.php con `reporteId`
   - BD registra hora de inicio en `revision_metricas`
3. **Operador** completa checklist en tiempo real (JavaScript frontend)
   - Cada cambio se registra localmente
4. **App Checklist** → POST guardar_checklist.php con checklist[], timeline[]
   - Valida estado = `"activo"`
   - Serializa checklists a JSON
   - Inserta timeline (orden, itemId, acción, timestamp)
   - Cambia estado a `"enviado"` (evita reutilización)
   - Notifica API externa Betics vía curl
   - Responde `{ok}`
5. **App Checklist** → POST finalizar_revision.php con `reporteId`
   - Calcula `TIMESTAMPDIFF(SECOND, hora_inicio, NOW())`
   - Actualiza `duracion_segundos`

#### **Escenario 2: Consultar Reportes (Panel Administrativo)**
1. **Panel Admin** → GET listar.php
   - Retorna todos reportes con LEFT JOIN `revision_metricas`
   - Convierte checklists JSON a arrays
   - Ordena DESC por fecha creación
   - Devuelve `{ok, reportes[]}`
2. **Panel Admin** → GET `/endpoint/consultar_id.php?id=N`
   - Consulta reporte específico, convierte JSON
   - Devuelve `{ok, reporte}`
3. **Panel Admin** → POST consultar_timeline.php con `reporteId`
   - Devuelve historial de cambios ordenado
   - Devuelve `{ok, timeline[]}`

#### **Escenario 3: Exportar Reporte Excel**
1. **Admin** accede a export_excel.php
   - Consulta TODOS los reportes
   - Calcula 18+ métricas globales (fallos, operadores, unidades, semanas, etc.)
   - Crea workbook con 5+ hojas:
     - **Portada**: logo, título, fecha, totales
     - **Resumen**: tabla 1 fila/reporte (fecha, operador, unidad, items, fallas)
     - **Fallas**: tabla con detalle cada falla (descripción, comentario, URL foto)
     - **Métricas**: análisis estadístico
     - **Gráficas**: 5 gráficos de barras (operadores, unidades, componentes, estado, semanas)
   - Aplica estilos (azul encabezados, bordes, congelación)
   - Genera archivo `TSAR_Reportes_[Y-m-d].xlsx`
   - Descarga al navegador

#### **Escenario 4: Cargar Evidencia Fotográfica**
1. **App Checklist** → POST upload_foto.php (multipart)
   - Parámetros: `file`, `reportId`, `itemId`
   - Valida MIME real (finfo)
   - Crea carpeta `/Uploads/Reportes/{reportId}/`
   - Mueve archivo a `{itemId}.{ext}`
   - Devuelve URL pública
   - App guarda URL en checklist, luego envía con guardar_checklist.php

---

### **6. POSIBLES ARCHIVOS SIN USO**

| Archivo/Carpeta | Evidencia de Falta de Uso |
|-----------------|---------------------------|
| raw.txt | LOG DE DEPURACIÓN. Appenda JSON cada que se invoca iniciar.php. Comentario en código: "Puede eliminarse cuando el sistema esté terminado". No usado en producción. |
| iniciar.php y consultar_id.php | Documentación (README_API.md) indica son "Endpoints de demostración durante Residencia Profesional". Panel/Checklist reales consumen reportes no endpoint. |
| assets | Carpeta vacía mencionada en lista pero sin archivos listados (excepto `tsar_logo.png` que se requiere en export.logo.php). |
| tables - `crearHojaDetalle()` | Mencionado en export_excel.php como `crearHojaDetalle()` pero **la función está incompleta** en export.tables.php (se corta la lectura). Estado: parcialmente implementado/posiblemente sin terminar. |
| estadisticas | Se refieren `chart.estado.php` y `chart.semanas.php` en export.charts.php, pero no fueron listados en el directorio. Posiblemente no existen o están fuera de scope. |
| `reportes/finalizar_revision.php` | No existe en carpeta reportes. Existe equivalente funcional en finalizar_revision.php. |

**Conclusión**: El proyecto está **parcialmente completo**:
- ✅ Core funciona: CRUD reportes, métricas, timeline
- ✅ Exportación Excel está implementada (con 4 hojas + gráficas)
- ⚠️ Algunos generadores de gráficas pueden no estar finalizados
- ⚠️ raw.txt es DEBUG innecesario en producción
- ⚠️ Endpoints endpoint son históricos (Residencia), producción usa reportes

---

### **7. TABLAS DE BASE DE DATOS INFERIDAS**

Por las consultas SQL observadas:

| Tabla | Columnas Inferidas |
|-------|--------------------|
| reportes | id (PK), semana, fecha_inicio, hora_inicio, unidad, operador, placas_jaula, checklist (JSON), checklist_jaula (JSON), estado (enum: activo/enviado/cerrado), creado_en (timestamp) |
| `revision_metricas` | id (PK), reporte_id (FK), hora_inicio, hora_fin, duracion_segundos |
| `revision_timeline` | id (PK), reporte_id (FK), orden, item_id, accion, timestamp_evento, creado_en |

---

**Resumen Final**: Arquitectura REST PHP con capas bien definidas (entrada, lógica, exportación). Usa PDO+MariaDB, PhpSpreadsheet para Excel, y transacciones para integridad. Sistema productivo consumido por Checklist + Panel; endpoints legacy de demostración.