# AGENTS.md - CartecWeb

## Visión General del Proyecto

**CartecWeb** es una aplicación web empresarial para la gestión integral de instalaciones de dispositivos GPS en vehículos. El sistema gestiona órdenes de trabajo (OT), instaladores/técnicos, clientes, vehículos, empresas y prestadores de servicios. Incluye funcionalidades para rastreo GPS, generación de documentos PDF, gestión de firmas digitales y reportes.

### Propósito Principal
- Gestión de órdenes de trabajo (OT) para instalación, desinstalación y mantenimiento de dispositivos GPS
- Registro de instalaciones sin orden de trabajo previa (DiaSinOT)
- Seguimiento de vehículos y dispositivos GPS en tiempo real
- Generación de documentos PDF con información de servicios y firmas digitales
- Administración de técnicos/instaladores y sus actividades
- Integración con sistemas externos de GPS y servicios de geocodificación

### Dominio del Negocio
El sistema se centra en la industria de telemetría vehicular y servicios de rastreo GPS, donde empresas instaladoras realizan trabajos de campo para clientes corporativos y particulares.

---

## Stack Tecnológico

### Backend
- **Framework**: Laravel 6.0 (PHP 7.2)
- **Base de datos**: MySQL (uso de Eloquent ORM y Query Builder)
- **Autenticación**: Laravel UI con Auth scaffolding
- **Generación de PDFs**: DomPDF (barryvdh/laravel-dompdf 0.8.5)
- **Procesamiento de imágenes**: Intervention Image 2.7
- **Exportación de datos**: Maatwebsite Excel 3.1
- **Validación RUT chileno**: malahierba-lab/chile-rut 5.1
- **Lectura de códigos QR**: tarfin-labs/zbar-php 1.1 + servicio externo (qr.cartec.cl)

### Frontend
- **Framework CSS**: Bootstrap 4.4.x
- **JavaScript**: 
  - Vue.js 2.5.17 (componentes reactivos)
  - jQuery 3.5.0
  - Axios 0.19 (peticiones AJAX)
- **Compilación de assets**: Laravel Mix 4.0.7 con Webpack
- **Datatables**: Para visualización de tablas complejas
- **Select2**: Selectores avanzados con búsqueda
- **Librerías de UI**: Font Awesome, Boxicons, LivIcons

### DevOps e Infraestructura
- **Containerización**: Docker con Docker Compose
- **Servidor web**: Apache 2 (en contenedor Ubuntu 22.04)
- **PHP**: 7.2 con múltiples extensiones (bcmath, curl, gd, imap, intl, mbstring, mysql, opcache, snmp, xml, zip)
- **Herramientas de imagen**: ImageMagick, zbar-tools (lectura de códigos de barras/QR)

### Herramientas de Desarrollo
- **Debugging**: Laravel Debugbar (barryvdh/laravel-debugbar 3.6)
- **Testing**: PHPUnit 8.0, Faker 1.4, Mockery 1.0
- **Control de versiones**: Git (rama actual: feature/CRTDESA-3_InstalacionSinOT)

---

## Arquitectura del Sistema

### Patrón Arquitectónico
El proyecto sigue el patrón **MVC (Model-View-Controller)** estándar de Laravel:
- **Models**: Entidades de negocio en `app/` y `app/models/`
- **Views**: Plantillas Blade en `resources/views/`
- **Controllers**: Lógica de aplicación en `app/Http/Controllers/`

### Estructura de Directorios Principal

```
CartecWeb/
├── app/                          # Código de aplicación
│   ├── Http/Controllers/         # Controladores de la aplicación
│   ├── models/                   # Modelos de base de datos (legacy)
│   ├── Exports/                  # Clases de exportación Excel
│   ├── Notifications/            # Notificaciones personalizadas
│   └── [Modelos Eloquent raíz]   # DiaSinOT, VehiculoSinOT, Empresa, etc.
├── database/
│   ├── migrations/               # Migraciones de base de datos
│   └── seeds/                    # Seeders de datos iniciales
├── resources/
│   ├── views/                    # Plantillas Blade
│   ├── js/                       # JavaScript (Vue components)
│   └── sass/                     # Estilos SCSS
├── public/                       # Assets públicos (CSS, JS compilado, imágenes)
├── routes/
│   └── web.php                   # Definición de rutas web
├── config/                       # Archivos de configuración Laravel
└── docker/                       # Configuración Docker
```

### Convenciones de Nomenclatura

#### Modelos
- **Ubicación mixta**: Algunos en `app/` (DiaSinOT, VehiculoSinOT, Empresa), otros en `app/models/` (OTModel, ClientesModel)
- **Convención**: PascalCase, nombre singular (DiaSinOT, VehiculoSinOT)
- **Tablas**: snake_case, pueden ser singulares o plurales según legacy (dia_sin_ot, vehiculo_sin_ot, OT, Clientes)

#### Controladores
- **Ubicación**: `app/Http/Controllers/`
- **Convención**: PascalCase con sufijo "Controller" (DiaSinOTController, VehiculoSinOTController)
- **Recursos**: Usan el patrón de controladores de recursos de Laravel cuando aplica

#### Rutas
- **Archivo principal**: `routes/web.php`
- **Convención**: snake_case para nombres de rutas (lista_ot, vehiculo_sin_ot.create)
- **Middleware**: 'auth' para rutas protegidas, middlewares personalizados (LogMail, LogOT)

#### Vistas
- **Ubicación**: `resources/views/`
- **Convención**: kebab-case para archivos (.blade.php)
- **Organización**: Por módulo (dia-sin-ot/, vehiculo-sin-ot/, auth/, parciales/)

---

## Módulos Principales del Sistema

### 1. Módulo de Órdenes de Trabajo (OT)
**Propósito**: Gestión completa del ciclo de vida de órdenes de trabajo.

**Controlador principal**: `OrdentrabajoController.php`

**Funcionalidades**:
- Creación, visualización y edición de OT
- Tipos de trabajo: Instalación, Desinstalación, Visita Técnica, Visita Fallida, Servicio Mecánico
- Asignación de técnicos a OT
- Registro de actividades en OT
- Generación de PDF de OT completadas
- Envío de OT por email
- Consulta de información de GPS asociada a OT

**Modelo**: `OTModel` (tabla: `OT`)

**Rutas relevantes**:
- `/lista_ot` - Lista de todas las OT
- `/lista_otecnico/{id}` - OT asignadas a un técnico específico
- `/realizarot/{id}` - Realizar una OT
- `/verot/{id}` - Ver detalles de una OT
- `/pdfot/{id}` - Generar PDF de OT

### 2. Módulo de Día Sin OT
**Propósito**: Gestión de instalaciones realizadas sin orden de trabajo previa (trabajo de campo sin planificación).

**Controlador**: `DiaSinOTController.php`

**Modelo principal**: `DiaSinOT` (tabla: `dia_sin_ot`)

**Modelo relacionado**: `VehiculoSinOT` (tabla: `vehiculo_sin_ot`)

**Flujo de trabajo**:
1. Instalador crea un registro de "Día Sin OT" al inicio del día
2. Registra información de cliente/empresa, dirección, actividad
3. Agrega uno o más vehículos al día sin OT
4. Escanea códigos QR de dispositivos GPS
5. Registra imágenes de IMEI, VIN, y ubicación GPS
6. Captura firma digital del cliente
7. Confirma y genera PDF del reporte

**Funcionalidades especiales**:
- Decodificación de códigos QR mediante servicio externo (qr.cartec.cl)
- Integración con API de Mapbox para mapas estáticos
- Consulta de datos de vehículos por VIN (Carcloud)
- Restricción: Solo un "Día Sin OT" por instalador por día

**Rutas relevantes**:
- `/diaSinOT/create` - Crear día sin OT
- `/vehiculoSinOT/create` - Agregar vehículo a día sin OT
- `/diaSinOT/confirm/{id}` - Confirmar y firmar
- `/diaSinOT/pdf/{id}` - Generar PDF

### 3. Módulo de Vehículos Sin OT
**Propósito**: Gestión de vehículos asociados a instalaciones sin OT.

**Controlador**: `VehiculoSinOTController.php`

**Modelo**: `VehiculoSinOT`

**Campos principales**:
- Información del vehículo: patente, marca, modelo, año, color, VIN
- Información del dispositivo: IMEI, tipo_dispositivo, id_gps, id_inmo
- Imágenes: img_imei, img_vin, img_vin_imei
- Ubicación GPS: lat, lng (calculados desde IMEI)
- Datos adicionales: solicitante, cortac_bombab, observacion

**Funcionalidades**:
- CRUD de vehículos dentro de un día sin OT
- Consulta de posición GPS actual por IMEI
- Obtención de datos de vehículo por VIN desde servicio externo
- Decodificación de QR para obtener IMEI automáticamente

**Rutas relevantes**:
- `/vehiculoSinOT/show/{id}` - Ver detalles de vehículo
- `/vehiculoSinOT/showGPS/{imei}` - Consultar GPS por IMEI
- `/vehiculoSinOT/getCarcloudDataByVin/{vin}` - Datos del vehículo por VIN

### 4. Módulo de Usuarios e Instaladores
**Propósito**: Gestión de técnicos/instaladores del sistema.

**Controlador**: `VerUsuarioController.php`

**Modelo**: `GSInstalador` (tabla: `instaladores`)

**Modelo de usuarios**: `User` (tabla: `users` - Laravel Auth)

**Relación**: 
- Modelo `User` para autenticación Laravel
- Modelo `GSInstalador` para datos específicos de instaladores
- Tabla `historial_instaladores` para registro histórico

**Funcionalidades**:
- Registro de nuevos técnicos
- Listado de usuarios del sistema
- Control de acceso basado en roles (campo `rol` en User)
  - rol > 1: Técnico (redirige a lista_otecnico)
  - rol <= 1: Administrador/Supervisor (acceso completo)

**Middleware de autenticación**:
- Middleware estándar `auth` de Laravel
- Middlewares personalizados: `LogMail`, `LogOT` (acceso directo por email/OT)

### 5. Módulo de Clientes y Empresas
**Propósito**: Gestión de clientes individuales y empresas.

**Modelos**:
- `ClientesModel` (tabla: `Clientes`) - Clientes individuales
- `Empresa` (tabla: `empresa`) - Empresas/organizaciones
- `ContactoModel` (tabla: `Contactos`) - Contactos de clientes

**Características importantes**:
- Los trabajos pueden ser para clientes individuales O empresas (XOR constraint en dia_sin_ot)
- RUT chileno como identificador único (validado con biblioteca malahierba-lab/chile-rut)
- Contactos asociados a clientes para notificaciones

### 6. Módulo de Empresas Instaladoras y Prestadores
**Propósito**: Gestión de empresas que realizan instalaciones y sus prestadores.

**Modelos**:
- `EmpresaInstaladora` (tabla: `empresa_instaladora`) - Empresas que ejecutan trabajos
- `Prestador` (tabla: `prestador`) - Prestadores de servicio

**Funcionalidades**:
- Las empresas instaladoras tienen logo (campo `logo`)
- Ambas entidades se asocian a DiaSinOT y aparecen en PDF generados

### 7. Módulo de Actividades
**Propósito**: Clasificación de tipos de actividades realizadas.

**Modelo**: `Actividad` (tabla: `Actividades`)

**Uso**: Se asocia a OT y DiaSinOT para categorizar el tipo de trabajo realizado.

### 8. Módulo de Firmas Digitales
**Propósito**: Captura y almacenamiento de firmas de clientes.

**Modelo**: `FirmaSinOT` (tabla: `firma_sin_ot`)

**Campos**:
- `id_dia_sin_ot`: Relación con el día sin OT
- `rut_cliente`: RUT del firmante
- `img_firma`: Imagen de firma en formato binario (BLOB)

**Proceso**:
1. Firma se captura en frontend (canvas HTML5)
2. Se envía como base64 en request
3. Backend decodifica y almacena en BLOB
4. Se incluye en PDF generado

### 9. Módulo de GPS
**Propósito**: Integración con sistemas GPS para tracking de vehículos.

**Modelos relacionados**:
- `GpsInfo` (tabla: `gps_info`)
- `GPSModel`
- `Vehiculos_GpsModel`

**Funcionalidades**:
- Consulta de posición GPS en tiempo real por IMEI
- Visualización de última posición conocida
- Integración con Mapbox para mapas
- API para consultar información GPS simple o detallada

**Rutas relacionadas**:
- `/ultima_posicion` - POST para consultar última posición
- `/pos_gps` - POST para posición GPS
- `/verinfogps` - POST para información detallada
- `/verinfogpsimple` - POST para información simple

### 10. Módulo de Servicios
**Propósito**: Funcionalidades auxiliares y servicios compartidos.

**Controlador**: `ServiciosController.php`

**Funcionalidades**:
- Registro y gestión de servicios de instalación
- Gestión de contactos
- Gestión de técnicos
- Consulta de patentes
- Subida de imágenes
- Envío de emails con reportes
- Generación de PDFs

### 11. Módulo de Exportación
**Propósito**: Exportación de datos a Excel.

**Controlador**: `ExportController.php`

**Clase de exportación**: `ExcelExport` (app/Exports/)

**Librería**: Maatwebsite Excel 3.1

**Rutas**:
- `/export/{id}` - Exportar datos a Excel

---

## Modelo de Datos y Relaciones

### Entidades Principales

#### DiaSinOT
```php
Tabla: dia_sin_ot
Relaciones:
  - hasMany: VehiculoSinOT (1:N)
  - hasOne: ClientesModel (vía rut_cliente)
  - hasOne: Empresa (vía id_empresa)
  - hasOne: Actividad (vía id_actividad)
  - hasOne: FirmaSinOT (1:1)
  - hasOne: EmpresaInstaladora (vía id_empresa_instaladora)
  - hasOne: Prestador (vía id_prestador)
  - getAttribute: instalador (GSInstalador)
  
Constraints:
  - XOR: (id_empresa IS NOT NULL) XOR (rut_cliente IS NOT NULL)
  - Solo un DiaSinOT por instalador por día
```

#### VehiculoSinOT
```php
Tabla: vehiculo_sin_ot
Relaciones:
  - belongsTo: DiaSinOT (N:1)
  
Campos importantes:
  - patente, imei, vin (identificadores)
  - img_imei, img_vin, img_vin_imei (imágenes en storage)
  - lat, lng (coordenadas GPS)
  - id_gps, id_inmo, tipo_dispositivo
  - marca, modelo, anho, color
```

#### OT (Orden de Trabajo)
```php
Tabla: OT
Modelo: OTModel
Primary Key: id_ot
Timestamps: creado_en, actualizado_en
```

#### User/GSInstalador
```php
User:
  Tabla: users (Laravel Auth)
  Campos: id, email, password, rol
  
GSInstalador:
  Tabla: instaladores
  Campos: id, rut_tecnico, nombre, etc.
```

### Diagrama Conceptual de Relaciones

```
DiaSinOT
  ├── N VehiculoSinOT
  ├── 1 Cliente/Empresa (XOR)
  ├── 1 Actividad
  ├── 1 FirmaSinOT
  ├── 1 EmpresaInstaladora
  ├── 1 Prestador
  └── 1 GSInstalador

VehiculoSinOT
  └── belongsTo DiaSinOT

OT (legacy, estructura separada)
  - Relacionada con técnicos, clientes, vehículos
```

---

## Flujos de Trabajo Principales

### Flujo 1: Instalación Sin OT (Nuevo Sistema)
1. **Inicio de sesión**: Técnico inicia sesión en el sistema
2. **Verificación**: Sistema verifica si ya existe un DiaSinOT para hoy
3. **Crear DiaSinOT**: Si no existe, técnico crea registro con:
   - Cliente/Empresa
   - Dirección y comuna
   - Actividad
   - Empresa instaladora
   - Prestador
4. **Agregar Vehículos**: Para cada vehículo:
   - Escanear QR del dispositivo GPS → obtener IMEI
   - Capturar fotos: IMEI, VIN, ambos
   - Obtener datos del vehículo (marca, modelo, año, color)
   - Consultar posición GPS actual
   - Ingresar observaciones
5. **Firma Digital**: Cliente firma en pantalla táctil/mouse
6. **Confirmar**: Sistema genera PDF y marca como confirmado
7. **Finalizar**: Técnico puede continuar con OT normales

### Flujo 2: Procesamiento de Orden de Trabajo (Sistema Legacy)
1. **Lista de OT**: Técnico ve lista de OT asignadas
2. **Seleccionar OT**: Técnico abre una OT
3. **Tipo de Trabajo**: Selecciona tipo (Instalación, Desinstalación, etc.)
4. **Realizar Actividad**: Registra información según tipo
5. **Servicios**: Registra servicios de instalación/mecánicos
6. **Finalizar**: Marca OT como completada
7. **PDF**: Sistema genera PDF con información de OT
8. **Envío**: PDF se envía por email al cliente

### Flujo 3: Decodificación de Código QR
1. **Captura**: Frontend captura imagen desde cámara
2. **Envío**: Imagen se envía como binario al backend
3. **Almacenamiento temporal**: Backend guarda en storage/tmp
4. **Servicio externo**: Backend envía imagen (base64) a qr.cartec.cl
5. **Respuesta**: Servicio externo retorna datos decodificados
6. **Devolución**: Backend retorna imagen (base64) + datos al frontend
7. **Autocompletado**: Frontend completa campo IMEI automáticamente

### Flujo 4: Generación de PDF
1. **Request**: Usuario solicita PDF (DiaSinOT o OT)
2. **Carga de datos**: Sistema carga todas las relaciones necesarias
3. **Preparación de imágenes**:
   - Firma digital (desde BLOB)
   - Mapas de Mapbox (URL dinámica con lat/lng)
   - Logos de empresas
4. **Renderizado**: DomPDF renderiza vista Blade a PDF
5. **Respuesta**: PDF se retorna como stream o se envía por email

---

## Configuración y Variables de Entorno

### Variables importantes esperadas (.env)
```env
APP_NAME=CartecWeb
APP_ENV=local|production
APP_KEY=[Laravel key]
APP_DEBUG=true|false
APP_URL=http://localhost

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=[nombre_bd]
DB_USERNAME=[usuario]
DB_PASSWORD=[contraseña]

MAIL_DRIVER=smtp
MAIL_HOST=[smtp_host]
MAIL_PORT=[smtp_port]
MAIL_USERNAME=[email]
MAIL_PASSWORD=[contraseña]
```

### Servicios Externos Configurados
- **qr.cartec.cl**: Servicio de decodificación de QR (endpoint: /read-img-qr)
- **Mapbox API**: Mapas estáticos (token hardcoded en código)
- **Carcloud**: Servicio de datos vehiculares por VIN

---

## Docker y Deployment

### Configuración Docker
**Archivo**: `docker-compose.yml`
- Servicio: `cartec-instalador`
- Puerto: 80 (host) → 80 (contenedor)
- Volumen: `.` → `/var/www/W_CartecInstalador`

**Dockerfile**:
- Base: Ubuntu 22.04
- PHP: 7.2 con Apache 2
- Extensiones PHP: bcmath, curl, gd, imap, intl, mbstring, mysql, opcache, snmp, xml, zip
- Herramientas: ImageMagick, zbar-tools (para QR)
- Configuración Apache: Virtual host para Laravel (000-laravel.conf)
- Módulos Apache habilitados: rewrite, headers, remoteip

### Directorio de trabajo
```
/var/www/W_CartecInstalador
```

### Comandos útiles
```bash
# Levantar contenedor
docker-compose up -d

# Acceder al contenedor
docker exec -it cartec-instalador bash

# Instalar dependencias
composer install
npm install

# Migraciones
php artisan migrate

# Permisos (dentro del contenedor)
chown -R www-data:www-data storage bootstrap/cache
chmod -R 775 storage bootstrap/cache
```

---

## Patrones de Código y Convenciones

### Controladores
- **Recursos RESTful**: Se usa `Route::resource()` para CRUD estándar
- **Validación**: En métodos de controlador (no Form Requests en este proyecto)
- **Respuestas JSON**: Para AJAX, estructura común:
  ```php
  [
    "status" => "success|error|warning",
    "message" => "Mensaje descriptivo",
    "data" => [...]
  ]
  ```

### Modelos Eloquent
- **Timestamps personalizados**: Algunos modelos usan `const CREATED_AT/UPDATED_AT`
- **Relaciones**: Se definen con type hints de retorno (HasOne, HasMany, BelongsTo)
- **Fillable**: Se define `$fillable` para asignación masiva
- **Hidden**: Se ocultan campos binarios (imágenes) en serialización JSON

### Vistas Blade
- **Layouts**: `layouts/app.blade.php`, `layouts/appnomenu.blade.php`
- **Parciales**: Carpeta `parciales/` para componentes reutilizables
- **Directivas**: `@auth`, `@if`, `@foreach`, `@include`
- **Assets**: Se incluyen con `asset()` o `url()`

### JavaScript
- **AJAX**: Uso de Axios para peticiones asíncronas
- **Vue.js**: Componentes reactivos (usado limitadamente)
- **jQuery**: Manipulación del DOM y eventos
- **Select2**: Selectores mejorados con búsqueda
- **DataTables**: Tablas interactivas con paginación y búsqueda

### Manejo de Imágenes
- **Storage**: Uso de `Storage` facade de Laravel
- **Subida**: `Storage::putFile('carpeta', $file)`
- **Lectura**: `Storage::get('path')` o `Storage::url('path')`
- **Base64**: Conversión frecuente para transmisión (firmas, QR)

### PDFs
- **Librería**: DomPDF vía `PDF` facade
- **Proceso**:
  ```php
  $pdf = PDF::loadView('vista', $datos)->setPaper('a4');
  return $pdf->stream(); // o ->download()
  ```
- **Imágenes en PDF**: Usar base64 en src de `<img>` para mejor compatibilidad

---

## Middleware y Autenticación

### Middleware Estándar Laravel
- `auth`: Requiere autenticación
- `guest`: Solo usuarios no autenticados
- `verified`: Email verificado

### Middleware Personalizado
- **LogMail**: Permite acceso directo por email sin autenticación tradicional
  - Ruta: `/logmail/{email}`
- **LogOT**: Permite acceso directo a OT específica
  - Ruta: `/logot/{email}/{ot}`

### Roles de Usuario
Sistema de roles simple basado en campo `rol` en tabla `users`:
- **rol <= 1**: Administrador/Supervisor (acceso completo)
- **rol > 1**: Técnico (redirige automáticamente a sus OT)

### Lógica en `/` (home)
```php
if (Auth::check()) {
    if (Auth::user()->rol > 1) {
        return redirect()->route('lista_otecnico', Auth::user()->id);
    } else {
        return view('revisa');
    }
} else {
    return view('auth.login');
}
```

---

## APIs y Endpoints Externos

### API Interna (AJAX Routes)
Rutas POST para funcionalidades AJAX:
- `/verificar` - Verificar datos
- `/ultima_posicion` - Consultar última posición GPS
- `/pos_gps` - Posición GPS de dispositivo
- `/verinfogps` - Información completa de GPS
- `/verinfogpsimple` - Información simple de GPS
- `/veractividades` - Ver actividades de OT
- `/servinstall` - Servicios de instalación
- `/servmecanico` - Servicios mecánicos
- `/guardarot` - Guardar orden de trabajo
- `/tablevehinok` - Tabla de vehículos no OK
- `/diaSinOT/decodeQR` - Decodificar QR

### APIs Externas
1. **qr.cartec.cl**
   - Endpoint: `POST /read-img-qr`
   - Payload: `{"image64": "base64_string"}`
   - Response: `{"success": boolean, "qr_result": {...}}`

2. **Mapbox Static API**
   - URL template: `https://api.mapbox.com/styles/v1/mapbox/streets-v11/static/pin-m-circle+000({lng},{lat})/{lng},{lat},15/500x500`
   - Token: Incluido en URL

3. **Carcloud API** (inferido)
   - Ruta: `/vehiculoSinOT/getCarcloudDataByVin/{vin}`
   - Obtiene datos de vehículo por VIN

---

## Testing y Debugging

### Herramientas de Debugging
- **Laravel Debugbar**: Disponible en desarrollo (`barryvdh/laravel-debugbar`)
  - Se usa en código: `debugbar()->log($variable)`
- **Laravel Telescope**: No instalado
- **dd() y dump()**: Funciones de debugging de Laravel disponibles

### Testing
- **Framework**: PHPUnit 8.0
- **Tests**: Carpeta `tests/`
  - Feature tests: `tests/Feature/`
  - Unit tests: `tests/Unit/`
- **Base**: `TestCase` con trait `CreatesApplication`

### Logs
- **Ubicación**: `storage/logs/laravel.log`
- **Canales**: Configurados en `config/logging.php`

---

## Consideraciones de Seguridad

### Autenticación
- Sistema de autenticación Laravel estándar
- Passwords hasheados con bcrypt
- Reset de password mediante email

### Autorización
- Control básico por rol de usuario
- Sin sistema de permisos granular (no usa políticas de Laravel)

### Validación
- Validación de RUT chileno con biblioteca especializada
- Validación de datos en controladores
- CSRF token en formularios (automático con Blade)

### Subida de Archivos
- Se almacenan en `storage/app/`
- Imágenes procesadas con Intervention Image
- Validación de tipos de archivo esperada en controladores

### SQL Injection
- Protección mediante Eloquent ORM y Query Builder
- Uso de bindings preparados

---

## Migraciones y Base de Datos

### Migraciones Principales
```
2014_10_12_000000_create_instaladores_table.php
2014_10_12_100000_create_password_resets_table.php
2019_08_19_000000_create_historial_instaladores_table.php
2024_02_02_092135_create_empresa_instaladora.php
2024_02_02_092159_create_empresa.php
2024_02_13_094901_create_dia_sin_ot.php
2024_02_13_094918_create_vehiculo_sin_ot.php
2024_02_29_151923_create_firma_sin_ot.php
2024_03_13_170147_create_prestador.php
2024_03_14_142459_add_logo_to_empresa_instaladora.php
```

### Observaciones
- Sistema tiene tablas legacy (OT, Clientes, Tecnicos, etc.) que NO tienen migraciones
- Nuevas features (DiaSinOT, VehiculoSinOT) SÍ tienen migraciones
- Se usan constraints de base de datos (foreign keys, checks)

### Seeders
- `DatabaseSeeder.php`
- `InstaladorTableSeeder.php`

---

## Assets y Frontend

### Compilación de Assets
**Laravel Mix** (`webpack.mix.js`):
```javascript
mix.js('resources/js/app.js', 'public/js')
   .sass('resources/sass/app.scss', 'public/css');
```

### CSS
- Bootstrap 4.4.x (base)
- Estilos personalizados en `public/css/`:
  - `alex.css`, `app.css`
  - `diaSinOT.css`, `vehiculoSinOT.css`
  - `servicio.css`, `wizard.css`
  - DataTables CSS
  - Select2 con tema Bootstrap 4

### JavaScript
- Archivos en `public/js/`:
  - Librerías: jQuery, Bootstrap, Select2, DataTables
  - Scripts personalizados por módulo
- Vue.js para componentes reactivos (uso limitado)

### Imágenes
- Logos: `logo-cartec.png`, `logo-cartec-azul.png`, etc.
- Iconos: Font Awesome, Boxicons, LivIcons
- Imágenes de carga: `cargando.gif`, `cargando_cartec.gif`
- Imágenes de módulos: `instalador.png`, `proveedor.png`

### Fuentes
- Boxicons (iconos)
- Flag Icons CSS (banderas de países)
- LivIcons Evo (iconos animados)

---

## Comandos Artisan Útiles

```bash
# Desarrollo
php artisan serve                    # Servidor de desarrollo
php artisan migrate                  # Ejecutar migraciones
php artisan migrate:fresh --seed     # Resetear DB y poblar
php artisan db:seed                  # Ejecutar seeders
php artisan tinker                   # REPL de Laravel

# Cache
php artisan cache:clear              # Limpiar cache
php artisan config:clear             # Limpiar config cache
php artisan view:clear               # Limpiar vistas compiladas
php artisan route:clear              # Limpiar cache de rutas

# Información
php artisan route:list               # Listar todas las rutas
php artisan list                     # Todos los comandos

# Storage
php artisan storage:link             # Crear symlink public/storage
```

---

## Notas Importantes para Agentes de IA

### Código Legacy vs Nuevo
El proyecto tiene **dos sistemas paralelos**:
1. **Sistema Legacy**: Órdenes de Trabajo (OT) tradicionales
   - Tablas sin migraciones: `OT`, `Clientes`, `Tecnicos`, `Vehiculos`
   - Controlador: `OrdentrabajoController`
   - Menos estructurado, algo más antiguo
2. **Sistema Nuevo**: Día Sin OT
   - Tablas con migraciones: `dia_sin_ot`, `vehiculo_sin_ot`, `firma_sin_ot`
   - Controladores: `DiaSinOTController`, `VehiculoSinOTController`
   - Más moderno, mejor estructura

### Al Modificar Código
- **Respetar convenciones existentes** incluso si no son las mejores prácticas actuales
- **No mezclar ubicaciones de modelos**: Algunos en `app/`, otros en `app/models/`
- **Mantener compatibilidad con sistema legacy** de OT
- **Considerar rol de usuario** en rutas y vistas

### Dependencias de Servicios Externos
- **qr.cartec.cl**: Crítico para escaneo de QR - sin él, no funciona el escaneo
- **Mapbox**: Necesario para mapas en PDFs
- **Servidor GPS**: Necesario para consultas de posición en tiempo real

### Datos Sensibles
- Imágenes de firmas digitales (BLOB en BD)
- Credenciales de email (MAIL_* en .env)
- Tokens de APIs externas
- Contraseñas de usuarios (hasheadas)

### Características de Chile
- **RUT**: Identificador único chileno (formato: 12345678-9)
- **Comunas**: Divisiones administrativas chilenas
- **Patentes**: Formato chileno de matrículas vehiculares

### Branch Actual
- **feature/CRTDESA-3_InstalacionSinOT**: Desarrollo del módulo de instalación sin OT
- Working tree limpio (no hay cambios sin commitear)

---

## Glosario de Términos del Dominio

- **OT**: Orden de Trabajo - Solicitud formal de servicio
- **DiaSinOT**: Día Sin Orden de Trabajo - Instalación sin OT previa
- **IMEI**: International Mobile Equipment Identity - Identificador de dispositivo GPS
- **VIN**: Vehicle Identification Number - Número de serie de vehículo
- **RUT**: Rol Único Tributario - Identificador único chileno
- **Prestador**: Empresa que presta servicios de instalación
- **Empresa Instaladora**: Empresa que ejecuta las instalaciones
- **Técnico/Instalador**: Persona que realiza el trabajo de campo
- **GPS**: Dispositivo de rastreo instalado en vehículo
- **Cortac/Bombab**: Corta corriente/Bomba de bencina - Dispositivos de inmovilización
- **Patente**: Matrícula/placa del vehículo

---

## Recursos Adicionales

### Documentación de Tecnologías
- Laravel 6.x: https://laravel.com/docs/6.x
- Vue.js 2.x: https://v2.vuejs.org/
- Bootstrap 4.x: https://getbootstrap.com/docs/4.6/
- DomPDF: https://github.com/barryvdh/laravel-dompdf
- Intervention Image: http://image.intervention.io/

### Estructura del Código
- **Punto de entrada web**: `public/index.php`
- **Bootstrap de aplicación**: `bootstrap/app.php`
- **Service Providers**: `app/Providers/`
- **Configuración**: `config/`

---

## Mejoras Potenciales Identificadas

(Estas son observaciones del código actual, NO implementadas):

1. **Testing**: Muy poca cobertura de tests
2. **Validación**: No usa Form Requests de Laravel
3. **APIs**: No hay versionamiento de API
4. **Autorización**: No usa Policies de Laravel
5. **Código duplicado**: Algunos controladores tienen lógica repetida
6. **Documentación**: Poca documentación inline en código
7. **Archivos guardados**: Múltiples archivos `.save`, `.save.1` en Controllers
8. **Tokens hardcodeados**: Token de Mapbox en código (debería estar en .env)
9. **Error handling**: Manejo de errores podría ser más robusto
10. **Modelos mixtos**: Ubicación inconsistente (app/ vs app/models/)

---

**Versión del documento**: 1.0  
**Fecha**: Noviembre 2025  
**Branch analizado**: feature/CRTDESA-3_InstalacionSinOT  
**Estado del proyecto**: En desarrollo activo