# Documentación Técnica Oficial - Sistema de Estacionamiento Medido (GovTech)
**Versión:** 1.2.0
**Fecha de Actualización:** 20 de Julio de 2026

Este documento detalla la arquitectura, configuración, modelo de datos, despliegue, seguridad y flujos transaccionales de la plataforma de Estacionamiento Medido para la **Municipalidad de Baradero**.

---

## 1. Resumen Ejecutivo del Sistema

La plataforma es una solución de gobierno digital (GovTech) para la gestión integral del estacionamiento medido en vía pública. Facilita la venta de saldo a través de terminales comerciales (Kioscos), brinda herramientas móviles para inspectores (Fiscalización y Avisos de Deuda), y provee un portal ciudadano público para la autogestión.

### Stack Tecnológico Principal
*   **Core Backend:** Laravel 11.x (PHP 8.2+) como framework REST, MVC e inyección de dependencias.
*   **Core Frontend:** Vue 3 (Composition API) integrado mediante Vite (SPA).
*   **Diseño (UI/UX):** CSS nativo + TailwindCSS (`@layer components` para `.sys-card`, `.sys-input`). **Soporte nativo de Modo Oscuro** institucional en toda la plataforma.
*   **Base de Datos:** MySQL 8.0+ / MariaDB.
*   **Caché y Colas:** Redis.
*   **Roles y Auditoría:** Spatie Laravel-Permission y Spatie Laravel-Activitylog.

---

## 2. Instalación y Configuración del Entorno

### 2.1 Requisitos de Servidor
*   PHP 8.2 o superior (con extensiones: `pdo_mysql`, `mbstring`, `xml`, `cURL`, `bcmath`, `redis`).
*   Node.js 18.x o superior + NPM.
*   MySQL 8.0 o MariaDB 10.6+.
*   Redis Server (Para gestión de colas, trabajos en segundo plano y sesiones).

### 2.2 Archivo de Entorno (`.env`)
Crear el archivo `.env` basándose en `.env.example`. Variables críticas de producción:

```dotenv
APP_ENV=production
APP_DEBUG=false
APP_URL=https://estacionamiento.baradero.gob.ar

# Conexión Base de Datos
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=estacionamiento_prod
DB_USERNAME=em_user
DB_PASSWORD=secret

# Colas y Caché
CACHE_STORE=redis
QUEUE_CONNECTION=redis
SESSION_DRIVER=redis

# Credenciales de MercadoPago (Producción / Sandbox)
# Utilizar credenciales de prueba ("TEST-...") para entornos staging.
MERCADOPAGO_ACCESS_TOKEN=APP_USR-123456789-XXX-XXX
MERCADOPAGO_PUBLIC_KEY=APP_USR-XXX-XXX
```

### 2.3 Pasos de Instalación (Setup Inicial)
```bash
# 1. Instalar dependencias PHP y Node
composer install --no-dev --optimize-autoloader
npm install

# 2. Generar Key y Enlazar Storage
php artisan key:generate
php artisan storage:link

# 3. Migrar base de datos y correr seeders iniciales
php artisan migrate --seed

# 4. Compilar assets frontend
npm run build

# 5. Iniciar workers para procesamiento de colas (Notificaciones, reportes)
php artisan queue:work --daemon
```

---

## 3. Multi-Tenancy y Marca Blanca

El sistema implementa un modelo **"Single Database, Single Schema" con aislamiento lógico parametrizable**. No utiliza una base de datos por municipio, sino que actúa como una plataforma centralizada (Marca Blanca) gobernada por la tabla `tenant_settings`.

El Administrador General configura globalmente los parámetros del Tenant desde el Backoffice:
*   Nombre y CUIT del municipio.
*   Logos institucionales.
*   Tolerancia de minutos para multas.
*   Leyendas legales impresas en tickets térmicos.

---

## 4. Arquitectura de Seguridad, Autenticación y Roles

### 4.1 Roles y Permisos (Spatie)
Gestionado vía el guard `web`.
*   **Administrador (`admin`):** Acceso total al catálogo de permisos.
*   **Tesorero (`tesorero`):** Cajas, arqueos y reportes.
*   **Inspector (`inspector`):** Aplicación móvil en calle (`acceso_inspector`).
*   **Kiosco (`kiosco`):** Terminal comercial (`acceso_kiosco`).

### 4.2 Políticas de Seguridad
*   **Doble Factor (2FA):** Obligatorio para perfiles administrativos. Centralizado en el componente web **"Mi Perfil"** (`SecuritySettingsModal.vue`) integrado en todas las cabeceras. Usa TOTP.
*   **Rate Limiting (Throttle):** Endpoint público `/consulta` protegido con límite estricto de **60 peticiones por minuto por IP** (`throttle:60,1` en `api.php`) para evitar Web Scraping masivo de patentes.
*   **Prevención CSRF & XSS:** Formularios protegidos por tokens `@csrf` (Laravel) y auto-escape de HTML nativo en templates Vue (`{{ variable }}`).
*   **Sesiones:** Manejadas a través de cookies HTTP-Only y seguras, respaldadas en Redis.

---

## 5. Módulos Core Implementados

1.  **Kioscos (Venta y Cajas):** SPA accesible vía `/kiosco`. Soporta modo oscuro. Requiere apertura de caja comercial (`CajaKiosco`) antes de vender.
2.  **Inspectores (Calle):** SPA móvil accesible vía `/inspector`.
    *   *Modos Visuales:* Coexisten el **Modo Noche** (estándar institucional) y un botón especial de **Modo Sol** (alto contraste blanco/negro) para operación diurna intensa.
    *   *Sincronización Offline:* Multas generadas sin internet se guardan en el `localStorage` y se sincronizan vía lote (batch) al recuperar 4G/Wifi.
3.  **Backoffice Admin:** Dashboards reactivos (`TesoreriaFinanzas.vue`), arqueos PDF y control en vivo del municipio.

---

## 6. Diagrama de Flujo Transaccional (Pagos QR)

Flujo exacto de cobro a través de la integración con MercadoPago:

```mermaid
sequenceDiagram
    participant K as Kiosco (Frontend)
    participant B as Backend (Laravel)
    participant MP as MercadoPago API
    
    K->>B: POST /kiosco/mercadopago/preferencia (patente, zona_id)
    B->>MP: POST /checkout/preferences (MERCADOPAGO_ACCESS_TOKEN)
    MP-->>B: Retorna Preference ID y QR Init Point
    B-->>K: JSON (qr_data)
    K->>K: Dibuja QR en Pantalla e inicia Polling
    
    rect rgb(240, 248, 255)
        note right of MP: El Ciudadano escanea el QR y Paga
        MP->>B: POST /api/mercadopago/webhook (Notificación Asíncrona)
        B->>MP: GET /v1/payments/{id} (Valida estado)
        MP-->>B: Status: 'approved'
        B->>B: LockForUpdate en BD. Registra PAGO
        B-->>MP: 200 OK (Confirma recepción)
    end
    
    loop Polling cada 3 segundos
        K->>B: POST /kiosco/mercadopago/verificar (patente)
        B-->>K: Status PAGO
    end
    
    K->>K: Pago detectado -> Imprime Ticket Térmico
```

---

## 7. Especificación de API y Endpoints

### Portal Público (Sin Autenticación)
| Método | Endpoint | Parámetros / Payload | Respuesta Exitosa | Descripción |
| :--- | :--- | :--- | :--- | :--- |
| **GET** | `/api/public/patente/{patente}` | `patente` (string, URL) | `200 OK` (JSON) | Retorna estado, exenciones, vigencia. Limitado (Throttle 60/min). |
| **POST** | `/api/mercadopago/webhook` | Payload IPN de MP (`data.id`) | `200 OK` | Webhook asíncrono para confirmación de pagos. |

### Terminal Kiosco (Requiere Cookie de Sesión - Rol: Kiosco)
| Método | Endpoint | Parámetros (JSON) | Respuesta Exitosa | Códigos de Error |
| :--- | :--- | :--- | :--- | :--- |
| **POST** | `/kiosco/pagar` | `patente`, `zona_id`, `monto` | `200 OK` (JSON confirmación) | `422` (Validación), `403` (Caja cerrada) |
| **POST** | `/kiosco/mercadopago/preferencia` | `patente`, `zona_id` | `200 OK` `{qr_data, preference_id}` | `502` (Fallo MP API) |

### Terminal Inspector (Requiere Cookie de Sesión - Rol: Inspector)
| Método | Endpoint | Parámetros (JSON) | Respuesta Exitosa | Descripción |
| :--- | :--- | :--- | :--- | :--- |
| **POST** | `/inspector/consultar` | `patente` | `200 OK` (Datos vehículo) | Valida si la patente tiene pago activo o es exenta. Deja registro de auditoría. |
| **POST** | `/inspector/infraccion` | `patente`, `zona_id`, `latitud`, `longitud`, `foto` | `201 Created` | Genera Acta / Aviso de Deuda. |

---

## 8. Esquema de Base de Datos y Diccionario

### Diagrama de Relaciones Lógicas (Entity-Relationship)

```mermaid
erDiagram
    USER {
        bigint id PK
        string name
        string email
        boolean two_factor_enabled
    }
    ROLES {
        bigint id PK
        string name
    }
    MODEL_HAS_ROLES {
        bigint role_id FK
        bigint model_id FK
    }
    ACTIVITY_LOG {
        bigint id PK
        string log_name
        string description
        json properties
    }
    PAGO {
        bigint id PK
        string patente
        string mp_payment_id
        decimal monto
    }
    INFRACCION {
        bigint id PK
        string patente
    }
    VEHICULO_EXENTO {
        bigint id PK
        string patente
        date vigente_desde
        date vigente_hasta
    }

    USER ||--o{ MODEL_HAS_ROLES : "asignado a"
    ROLES ||--o{ MODEL_HAS_ROLES : "contiene"
    USER ||--o{ ACTIVITY_LOG : "genera"
    USER ||--o{ PAGO : "vende"
```

### Diccionario de Datos Breve (Tablas Críticas)
*   `pagos`: `patente` (varchar 15, indexado), `fecha_vigencia` (date, indexado), `mp_payment_id` (varchar, Unique index).
*   `vehiculo_exentos`: Controla franquicias. `vigente_desde` y `vigente_hasta` validan estado activo en tiempo real.
*   `tenant_settings`: Tabla de configuración global en formato Key-Value.

---

## 9. Despliegue y CI/CD (Deployment)

### Entorno de Producción Recomendado
*   **Servidor:** Instancia Ubuntu 22.04 / 24.04 aprovisionada mediante Laravel Forge o automatización Ansible.
*   **Servidor Web:** NGINX actuando como Reverse Proxy hacia PHP-FPM.
*   **Colas:** Uso de `Supervisor` para garantizar que los procesos `php artisan queue:work` se mantengan vivos ininterrumpidamente.

### Estrategia de Backups
Se utiliza el paquete `spatie/laravel-backup`.
*   Ejecución programada diaria vía Laravel Scheduler (`cron`).
*   Respaldo enviado automáticamente a un bucket S3 compatible (AWS / DigitalOcean Spaces).

---

## 10. Testing, Manejo de Errores y Logging

### Testing y Calidad de Código (QA)
*   **Estado Actual:** Cobertura Parcial Inicial. Existen pruebas unitarias enfocadas en componentes críticos (Ej. `tests/Feature/CajaTest.php`).
*   **Estrategia a Futuro:** Migración progresiva a **Pest PHP** para pruebas E2E (End-to-End) sobre el `EstacionamientoService` y flujos de cobro.

### Manejo de Errores e Idempotencia
*   **Webhooks de MercadoPago (Idempotencia):** El controlador `MercadoPagoController` maneja fallos de red bloqueando reintentos duplicados. Verifica si `Pago::where('mp_payment_id')` existe antes de inyectar saldo. El método usa `lockForUpdate()` para mitigar concurrencia extrema (Race Conditions).
*   **Logging Estructurado:** Los errores críticos y fallos de API de terceros se registran en `storage/logs/laravel.log` y están preparados para ingestión en plataformas de monitoreo como Sentry/Flare.

---

## 11. Changelog (Historial de Versiones)

*   **v1.2.0 (20/07/2026):** Implementación de Sistema de Diseño semántico, Modo Oscuro Global, unificación del Modal de Seguridad ("Mi Perfil") y Rate Limiting en portal público. Reescritura exhaustiva de documentación técnica.
*   **v1.1.0 (2025):** Integración inicial con Webhooks IPN de MercadoPago y lectura OCR en aplicación de Inspectores.
*   **v1.0.0 (2024):** Lanzamiento oficial de marca blanca (GovTech). Módulo administrativo y Terminal Kiosco básica.