# API de Creación de OT Cartec - Guía de Implementación

## 📋 Descripción General

Esta es una API Node.js lista para producción para crear Órdenes de Trabajo (OT) en el sistema Cartec. La API proporciona un único endpoint para crear OTs con gestión automática de clientes y registro de vehículos.

**Versión:** 1.0.0  
**Fecha:** Diciembre 2025

---

## 🎯 Características

- ✅ Crear OT con una sola llamada a la API
- ✅ Creación/actualización automática de clientes (UPSERT)
- ✅ Registro y vinculación de vehículos
- ✅ Validación de RUT chileno
- ✅ Mapeo de proveedores GPS (gpsimple, entel, tattersall, cemin, carflex)
- ✅ Mapeo de tipos de servicio (instalacion_gps, visita_tecnica, desinstalacion_gps)
- ✅ Mapeo de talleres (cartec, servitattersall)
- ✅ Seguridad con transacciones de base de datos
- ✅ Manejo completo de errores

---

## 📦 Requisitos Previos

### Requisitos del Sistema
- Ubuntu 22.04 LTS (o similar)
- Node.js 12+ (recomendado: 16 LTS)
- MySQL 8.0+
- Acceso root o sudo

### Requisitos de Base de Datos
- Base de datos `revisa` existente
- Tablas: `OT`, `Clientes`, `Tecnicos`, `Vehiculos`, `OT_Vehiculos`
- Al menos un técnico registrado en la tabla `Tecnicos`

---

## 🚀 Pasos de Instalación

### Paso 1: Instalar Node.js

```bash
# Verificar si Node.js está instalado
node --version

# Si no está instalado, instalar Node.js 16 LTS
curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash -
sudo apt-get install -y nodejs

# Verificar instalación
node --version
npm --version
```

---

### Paso 2: Desplegar Archivos de la API

```bash
# Crear directorio de la API
sudo mkdir -p /opt/cartec_api
sudo chown $USER:$USER /opt/cartec_api

# Copiar archivos desde la carpeta api_deployment
cd /var/www/html/W_CartecInstalador/api_deployment
cp -r src package.json env.example .gitignore /opt/cartec_api/
cp -r sql /opt/cartec_api/
cp -r docs /opt/cartec_api/

# Navegar al directorio de la API
cd /opt/cartec_api
```

---

### Paso 3: Configurar Entorno

```bash
# Copiar archivo de ejemplo de entorno
cp env.example .env

# Editar variables de entorno
nano .env
```

**Variables requeridas:**
```env
# Configuración del Servidor
PORT=3000
NODE_ENV=production

# Configuración de Base de Datos
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=tu_contraseña_mysql
DB_NAME=revisa
DB_CONNECTION_LIMIT=10
```

**Guardar y salir:** `Ctrl+X`, `Y`, `Enter`

---

### Paso 4: Instalar Dependencias

```bash
cd /opt/cartec_api
npm install
```

Salida esperada:
```
added 50 packages, and audited 51 packages in 3s
```

---

### Paso 5: Instalar Procedimiento Almacenado

```bash
# Instalar el procedimiento almacenado
mysql -u root -p revisa < /opt/cartec_api/sql/api_procedure.sql

# Verificar instalación
mysql -u root -p revisa -e "SHOW PROCEDURE STATUS WHERE Name = 'prc_api_create_OT';"
```

La salida esperada debe mostrar que el procedimiento existe.

---

### Paso 6: Crear Técnico de Prueba (si es necesario)

```bash
mysql -u root -p revisa -e "
INSERT IGNORE INTO Tecnicos (rut_tecnico, nombre, creado_en) 
VALUES ('11111111-1', 'Técnico de Prueba API', NOW());
"
```

---

### Paso 7: Probar API Manualmente

```bash
# Iniciar API manualmente (para pruebas)
cd /opt/cartec_api
node src/index.js
```

Salida esperada:
```
Server running on port 3000
```

**En otra terminal, probar la API:**
```bash
curl -X POST http://localhost:3000/api/health | python3 -m json.tool
```

Respuesta esperada:
```json
{
  "status": "ok",
  "timestamp": "2025-12-29T20:00:00.000Z"
}
```

**Detener la prueba manual:** `Ctrl+C`

---

### Paso 8: Instalar como Servicio del Sistema

```bash
# Copiar archivo de servicio
sudo cp /var/www/html/W_CartecInstalador/api_deployment/config/cartec-api.service /etc/systemd/system/

# Recargar systemd
sudo systemctl daemon-reload

# Habilitar servicio (iniciar al arrancar)
sudo systemctl enable cartec-api

# Iniciar servicio
sudo systemctl start cartec-api

# Verificar estado
sudo systemctl status cartec-api
```

Salida esperada:
```
● cartec-api.service - API de Creación de OT Cartec
   Loaded: loaded (/etc/systemd/system/cartec-api.service; enabled)
   Active: active (running) since ...
```

---

### Paso 9: Verificar que la API Funciona

```bash
# Verificación de salud
curl http://localhost:3000/api/health

# Crear OT de prueba
curl -X POST http://localhost:3000/api/ot/create \
  -H "Content-Type: application/json" \
  -d '{
    "cliente": {
      "rut": "12345678-5",
      "nombre": "Cliente Prueba Producción",
      "direccion": "Av. Prueba 123",
      "comuna": "Santiago",
      "telefono": "+56912345678",
      "email": "prueba@cartec.cl"
    },
    "tecnico": {
      "rut": "11111111-1"
    },
    "servicio": {
      "presGPS": "gpsimple",
      "tiposerv": "instalacion_gps",
      "taller_install": "cartec"
    },
    "vehiculos": [
      {
        "patente": "PROD01",
        "marca": "Toyota",
        "modelo": "Corolla",
        "color": "Blanco",
        "anio": 2021
      }
    ]
  }' | python3 -m json.tool
```

Respuesta esperada:
```json
{
  "success": 1,
  "message": "OT creada correctamente ID: 1656 Vehiculos: 1",
  "data": {
    "id_ot": 1656,
    "rut_cliente": "12345678-5",
    "rut_tecnico": "11111111-1",
    "vehiculos_procesados": 1
  }
}
```

---

## 🔍 Verificación

### Verificar Registros en Base de Datos

```bash
# Ejecutar script de verificación
mysql -u root -p revisa < /opt/cartec_api/sql/verify_ot_data.sql
```

### Verificar Logs del Servicio

```bash
# Ver logs recientes
sudo journalctl -u cartec-api -n 50

# Seguir logs en tiempo real
sudo journalctl -u cartec-api -f
```

### Verificar Proceso de la API

```bash
# Verificar si la API está ejecutándose
ps aux | grep node

# Verificar que el puerto está escuchando
sudo netstat -tlnp | grep 3000
```

---

## 🔧 Mantenimiento

### Reiniciar Servicio

```bash
sudo systemctl restart cartec-api
```

### Detener Servicio

```bash
sudo systemctl stop cartec-api
```

### Ver Logs

```bash
sudo journalctl -u cartec-api -n 100 --no-pager
```

### Actualizar Código

```bash
cd /opt/cartec_api
# Copiar nuevos archivos o actualizar código
npm install  # Si cambiaron las dependencias
sudo systemctl restart cartec-api
```

### Actualizar Procedimiento Almacenado

```bash
mysql -u root -p revisa < /opt/cartec_api/sql/api_procedure.sql
# No es necesario reiniciar la API
```

---

## 🛡️ Consideraciones de Seguridad

### Configuración del Firewall

```bash
# Si se expone la API externamente
sudo ufw allow 3000/tcp
```

### Permisos de Usuario de Base de Datos

**Recomendado:** Crear usuario dedicado de base de datos para la API:
```sql
CREATE USER 'cartec_api'@'localhost' IDENTIFIED BY 'contraseña_segura';
GRANT SELECT, INSERT, UPDATE ON revisa.* TO 'cartec_api'@'localhost';
FLUSH PRIVILEGES;
```

Actualizar `.env`:
```env
DB_USER=cartec_api
DB_PASSWORD=contraseña_segura
```

### SSL/TLS (Producción)

Para producción, usar **Nginx como proxy reverso** con SSL:

```nginx
server {
    listen 443 ssl;
    server_name api.cartec.cl;

    ssl_certificate /ruta/a/cert.pem;
    ssl_certificate_key /ruta/a/key.pem;

    location /api/ {
        proxy_pass http://localhost:3000/api/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

---

## 🐛 Solución de Problemas

### La API No Inicia

**Verificar logs:**
```bash
sudo journalctl -u cartec-api -n 50
```

**Problemas comunes:**
1. **Puerto ya en uso:**
   ```bash
   sudo netstat -tlnp | grep 3000
   sudo kill <PID>
   ```

2. **Fallo de conexión a base de datos:**
   - Verificar credenciales en `.env`
   - Verificar que MySQL está ejecutándose: `sudo systemctl status mysql`

3. **Node.js no encontrado:**
   - Verificar ruta de Node.js: `which node`
   - Actualizar archivo de servicio si es necesario

### Falla la Creación de OT

**Verificar que existe el procedimiento almacenado:**
```bash
mysql -u root -p revisa -e "SHOW PROCEDURE STATUS WHERE Name = 'prc_api_create_OT';"
```

**Verificar que existe el técnico:**
```bash
mysql -u root -p revisa -e "SELECT * FROM Tecnicos WHERE rut_tecnico = '11111111-1';"
```

**Verificar restricciones de base de datos:**
```bash
mysql -u root -p revisa -e "SHOW CREATE TABLE OT\G"
```

### Problemas de Rendimiento

**Verificar pool de conexiones:**
```env
DB_CONNECTION_LIMIT=20  # Aumentar si es necesario
```

**Monitorear base de datos:**
```sql
SHOW PROCESSLIST;
```

---

## 📊 Monitoreo

### Endpoint de Verificación de Salud

```bash
# Agregar a cron para monitoreo
*/5 * * * * curl -f http://localhost:3000/api/health || echo "API CAIDA" | mail -s "Alerta API Cartec" admin@cartec.cl
```

### Rotación de Logs

Los logs del servicio son gestionados automáticamente por systemd journal.

**Limpieza manual:**
```bash
sudo journalctl --vacuum-time=7d  # Mantener solo 7 días
```

---

## 📚 Recursos Adicionales

- **Documentación de la API:** `/opt/cartec_api/docs/DOCUMENTACION_API.md`
- **Guía de Pruebas:** `/opt/cartec_api/docs/TESTING.md`
- **Scripts SQL:** `/opt/cartec_api/sql/`
- **Código Fuente:** `/opt/cartec_api/src/index.js`

---

## 📞 Soporte

Para problemas o preguntas:
1. Verificar logs: `sudo journalctl -u cartec-api -n 100`
2. Revisar documentación en `/opt/cartec_api/docs/`
3. Verificar conectividad de base de datos y procedimiento almacenado
4. Verificar estado del servicio: `sudo systemctl status cartec-api`

---

## ✅ Lista de Verificación de Implementación

- [ ] Node.js instalado
- [ ] Archivos de la API desplegados en `/opt/cartec_api`
- [ ] `.env` configurado con credenciales de base de datos
- [ ] Dependencias instaladas (`npm install`)
- [ ] Procedimiento almacenado instalado en base de datos
- [ ] Técnico de prueba creado
- [ ] API probada manualmente
- [ ] Servicio systemd instalado y habilitado
- [ ] API accesible en puerto 3000
- [ ] Endpoint de salud funcionando
- [ ] OT de prueba creada exitosamente
- [ ] Registros de base de datos verificados
- [ ] Logs revisados sin errores
- [ ] Firewall configurado (si es necesario)
- [ ] Monitoreo/alertas configuradas (opcional)

---

**¡Implementación Completa! 🎉**

Tu API de Creación de OT Cartec ahora está ejecutándose en producción.