Sistema de Notificaciones para Centros de Diagnóstico Automotriz

🎯 Tabla de Contenidos

1. Introducción al Sistema
2. Acceso y Autenticación
3. Dashboard Principal
4. Gestión de Clientes
5. Gestión de Vehículos
6. Gestión de Documentos
7. Sistema de Notificaciones
8. Gestión de Promociones
9. Reportes y Analíticas
10. Configuración del Sistema
11. Preguntas Frecuentes

🚀 Introducción al Sistema

El Sistema de Marketing y Recordatorios para Centros de Diagnóstico Automotriz (CDA) es una plataforma integral diseñada para automatizar y optimizar la gestión de clientes, vehículos, documentos y campañas de marketing en tu centro de diagnóstico automotriz.

🔐 Acceso y Autenticación

📋 Requisitos de Acceso

• ✅ Usuario y contraseña proporcionados por el administrador
• ✅ Navegador web moderno (Chrome, Firefox, Safari, Edge)
• ✅ Conexión a internet estable
• ✅ Correo electrónico válido para notificaciones

🔑 Inicio de Sesión

1. Abre tu navegador y visita la URL del sistema
2. Ingresa tus credenciales:
   • 📧 Correo electrónico
   • 🔒 Contraseña
3. Haz clic en "Iniciar Sesión"
4. Verifica tu identidad si se requiere autenticación de dos factores

📊 Dashboard Principal

El dashboard es tu centro de control principal, donde encontrarás información clave y acceso rápido a todas las funcionalidades.

📈 Métricas Principales

👥 Gestión de Clientes

La sección de clientes te permite gestionar toda la información de tus clientes de manera centralizada.

➕ Registro de Nuevo Cliente

🔍 Búsqueda Rápida

• Por nombre: Escribe el nombre del cliente
• Por documento: Ingresa número de identificación
• Por teléfono: Busca por número telefónico
• Por correo: Filtra por dirección email

📧 Sistema de Notificaciones

El sistema de notificaciones envía recordatorios automáticos a los clientes sobre vencimientos de documentos, promociones y comunicaciones importantes.

🎯 Tipos de Notificaciones

❓ Preguntas Frecuentes

🔐 Acceso y Seguridad

P: ¿Olvidé mi contraseña, cómo la recupero?

R: Haz clic en "¿Olvidaste tu contraseña?" en la pantalla de login, ingresa tu correo y sigue las instrucciones.

P: ¿Puedo acceder desde múltiples dispositivos?

R: Sí, puedes acceder desde cualquier dispositivo con internet. Solo un usuario por sesión.

👥 Clientes y Vehículos

P: ¿Puedo importar clientes masivamente?

R: Sí, usa la función de importación CSV desde el panel de clientes.

P: ¿Qué hago si un cliente tiene múltiples vehículos?

R: Registra cada vehículo por separado y asígnales al mismo cliente.

📋 Tabla de Contenidos

1. Arquitectura del Sistema
2. Requisitos del Sistema
3. Instalación y Configuración
4. Base de Datos
5. API Endpoints
6. Seguridad
7. Despliegue en Producción
8. Mantenimiento y Monitoreo

🏗️ Arquitectura del Sistema

El Sistema CDA está construido sobre una arquitectura moderna y escalable diseñada para alto rendimiento y mantenibilidad.

💻 Requisitos del Sistema

🔧 Requisitos Mínimos

📦 Software Requerido

• Node.js: 18.x o superior
• npm: 9.x o superior
• MySQL: 8.0 o superior
• Git: 2.30 o superior

🚀 Instalación y Configuración

📋 Proceso de Instalación Completa

1️⃣ Preparación del Entorno

# Clonar el repositorio
git clone https://github.com/cda-colombia/sistema-marketing-recordatorios.git
cd sistema-marketing-recordatorios

# Instalar dependencias
npm install

# Verificar versión de Node.js
node --version  # >= 18.x
npm --version   # >= 9.x

2️⃣ Configuración de Base de Datos

# Crear base de datos
mysql -u root -p
CREATE DATABASE notificaciones_automotrices 
CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

CREATE USER 'app_notificaciones'@'localhost' 
IDENTIFIED BY 'contraseña_segura';

GRANT ALL PRIVILEGES ON notificaciones_automotrices.* 
TO 'app_notificaciones'@'localhost';

FLUSH PRIVILEGES;

# Importar schema
mysql -u app_notificaciones -p notificaciones_automotrices < schema.sql

3️⃣ Configuración de Variables de Entorno

# Copiar archivo de ejemplo
cp .env.example .env

# Editar variables
nano .env

# Base de datos
DB_HOST=localhost
DB_PORT=3306
DB_USER=app_notificaciones
DB_PASSWORD=tu_contraseña_segura
DB_NAME=notificaciones_automotrices

# JWT
JWT_SECRET=tu_clave_secreta_de_al_menos_32_caracteres
JWT_EXPIRES_IN=24h

# SendGrid
SENDGRID_API_KEY=SG.xxxxxxxxxxxxxxxxxxxxxxxxx
SENDGRID_FROM_EMAIL=noreply@cda-colombia.com

# Aplicación
APP_URL=https://tu-dominio.com
NODE_ENV=production
PORT=4321

🗄️ Base de Datos

📊 Esquema Principal

🏢 Tablas Principales

-- Usuarios del sistema
CREATE TABLE usuarios (
    id INT PRIMARY KEY AUTO_INCREMENT,
    nombres VARCHAR(100) NOT NULL,
    apellidos VARCHAR(100) NOT NULL,
    email VARCHAR(255) UNIQUE NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    rol_id INT NOT NULL,
    activo BOOLEAN DEFAULT TRUE,
    creado_en TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    actualizado_en TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

-- Clientes
CREATE TABLE clientes (
    id INT PRIMARY KEY AUTO_INCREMENT,
    nombres VARCHAR(100) NOT NULL,
    apellidos VARCHAR(100) NOT NULL,
    email VARCHAR(255) UNIQUE,
    telefono VARCHAR(20),
    documento_identidad VARCHAR(50) UNIQUE,
    tipo_cliente ENUM('particular', 'empresa') DEFAULT 'particular',
    direccion TEXT,
    creado_en TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

🔧 Índices Optimizados

-- Índices para rendimiento
CREATE INDEX idx_documentos_vencimiento ON documentos(fecha_vencimiento);
CREATE INDEX idx_documentos_vehiculo ON documentos(vehiculo_id);
CREATE INDEX idx_vehiculos_cliente ON vehiculos(cliente_id);
CREATE INDEX idx_cola_notificaciones_estado ON cola_notificaciones(estado);
CREATE INDEX idx_clientes_email ON clientes(email);
CREATE INDEX idx_vehiculos_placa ON vehiculos(placa);

🔌 API Endpoints

🔐 Autenticación

POST /api/auth/login

Descripción: Inicia sesión de usuario

{
  "email": "usuario@ejemplo.com",
  "password": "contraseña123"
}

{
  "success": true,
  "user": {
    "id": 1,
    "nombres": "Juan",
    "apellidos": "Pérez",
    "email": "usuario@ejemplo.com",
    "rol": {
      "nombre": "admin",
      "permisos": {
        "clientes": ["crear", "leer", "actualizar", "eliminar"]
      }
    }
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

👥 Gestión de Clientes

GET /api/clientes

Descripción: Obtiene lista de clientes

Query Parameters:

• page: Número de página (default: 1)
• limit: Resultados por página (default: 10)
• search: Término de búsqueda
• tipo: Tipo de cliente (particular/empresa)

🔐 Seguridad

🛡️ Implementaciones de Seguridad

🔐 Autenticación JWT

• Algoritmo: HS256
• Expiración: 24 horas
• Secret: Mínimo 32 caracteres
• Hash de contraseñas: bcrypt con 10 salt rounds

🚦 Rate Limiting

• Ventana de tiempo: 15 minutos
• Máximo de requests: 100 por IP
• Endpoints sensibles: 10 requests por ventana
• Bloqueo temporal: 1 hora después de exceder límite

🚀 Despliegue en Producción

🐳 Docker Configuration

📄 Dockerfile

FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
COPY tsconfig.json ./
COPY astro.config.mjs ./

RUN npm ci --only=production
COPY . .
RUN npm run build

FROM node:18-alpine AS runner
WORKDIR /app

COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/package.json ./

RUN addgroup -g 1001 -S nodejs
RUN adduser -S astro -u 1001
USER astro

EXPOSE 4321
CMD ["node", "dist/server/entry.mjs"]

🔧 Mantenimiento y Monitoreo

📊 Sistema de Monitoreo

🎯 KPIs Clave

• Disponibilidad: > 99.9%
• Tiempo de respuesta: < 200ms (promedio)
• Tasa de error: < 0.1%
• Throughput: > 1000 req/min
• Uso de CPU: < 80%
• Uso de memoria: < 85%

📋 Tabla de Contenidos

1. Problemas Comunes de Instalación
2. Problemas de Conexión y Acceso
3. Problemas de Base de Datos
4. Problemas de Email y Notificaciones
5. Problemas de Rendimiento
6. Problemas de Frontend
7. Problemas de Seguridad
8. Herramientas de Diagnóstico

🚀 Problemas Comunes de Instalación

❌ "Node.js no encontrado" o versión incompatible

🔍 Síntomas

• Error: command not found: node
• Error: Node.js version too old
• Error: npm command not found

🛠️ Soluciones

Opción 1: Instalar Node.js correcto

# Verificar versión requerida
cat package.json | grep '"node"'

# Instalar Node.js 18+ (Ubuntu/Debian)
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Verificar instalación
node --version  # Debe mostrar v18.x o superior
npm --version   # Debe mostrar 9.x o superior

Opción 2: Usar NVM (Node Version Manager)

# Instalar NVM
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Recargar terminal
source ~/.bashrc

# Instalar y usar Node.js 18
nvm install 18
nvm use 18
nvm alias default 18

❌ "Error al instalar dependencias"

🔍 Síntomas

• Error: npm install failed
• Error: EACCES: permission denied
• Error: network timeout

🛠️ Soluciones

Opción 1: Limpiar caché y reinstalar

# Limpiar caché de npm
npm cache clean --force

# Eliminar node_modules y package-lock.json
rm -rf node_modules package-lock.json

# Reinstalar dependencias
npm install

Opción 2: Problemas de permisos

# Cambiar propietario de npm (Linux/macOS)
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) /usr/local/lib/node_modules

🔐 Problemas de Conexión y Acceso

❌ "No se puede conectar al servidor"

🔍 Síntomas

• Error: ECONNREFUSED
• Error: Connection refused
• Página en blanco o timeout

🛠️ Soluciones

Paso 1: Verificar si el servidor está corriendo

# Verificar procesos de Node.js
ps aux | grep node

# Verificar puerto en uso
netstat -tlnp | grep :4321
# o en macOS/Linux moderno
ss -tlnp | grep :4321

Paso 2: Iniciar el servidor

# Iniciar servidor de desarrollo
npm run dev

# Verificar que inicie correctamente
# Debería mostrar: "Local: http://localhost:4321/"

❌ "Error de autenticación o login fallido"

🔍 Síntomas

• Error: "Credenciales inválidas"
• Error: "Token expirado"
• Ciclo infinito de login

🛠️ Soluciones

Paso 1: Verificar credenciales por defecto

# Conectar a base de datos
mysql -u app_notificaciones -p notificaciones_automotrices

# Verificar usuario admin
SELECT email, password_hash FROM usuarios WHERE rol_id = 1;

Paso 2: Verificar configuración JWT

# Verificar .env
cat .env | grep JWT

# Asegurar que JWT_SECRET tenga 32+ caracteres
# JWT_SECRET=clave_secreta_de_al_menos_32_caracteres

🗄️ Problemas de Base de Datos

❌ "Error de conexión a MySQL"

🔍 Síntomas

• Error: ECONNREFUSED para MySQL
• Error: Access denied for user
• Error: Can't connect to MySQL server

🛠️ Soluciones

Paso 1: Verificar MySQL está corriendo

# Linux (systemd)
systemctl status mysql
systemctl start mysql

# Linux (init.d)
service mysql status
service mysql start

# macOS (brew)
brew services list | grep mysql
brew services start mysql

Paso 2: Verificar credenciales en .env

# Verificar configuración
cat .env | grep DB_

# Probar conexión manual
mysql -u TU_USUARIO -p -h localhost notificaciones_automotrices

❌ "Error: Tabla no existe"

🔍 Síntomas

• Error: Table 'notificaciones_automotrices.usuarios' doesn't exist
• Error: Unknown column en consultas
• Error: Base de datos vacía

🛠️ Soluciones

Paso 1: Importar schema completo

# Importar schema SQL
mysql -u app_notificaciones -p notificaciones_automotrices < schema.sql

# Verificar tablas creadas
mysql -u app_notificaciones -p notificaciones_automotrices -e "SHOW TABLES;"

📧 Problemas de Email y Notificaciones

❌ "SendGrid API Key inválida"

🔍 Síntomas

• Error: 401 Unauthorized de SendGrid
• Error: Invalid API key
• Notificaciones no se envían

🛠️ Soluciones

Paso 1: Verificar API Key

# Verificar configuración
cat .env | grep SENDGRID

# Probar API Key manualmente
curl -X GET "https://api.sendgrid.com/v3/user/account" \
  -H "Authorization: Bearer TU_API_KEY"

❌ "Emails no llegan a destinatarios"

🔍 Síntomas

• Sistema dice "enviado" pero no llegan
• Emails en carpeta de spam
• Bounce o rechazo de emails

🛠️ Soluciones

Paso 1: Verificar cola de notificaciones

-- Verificar estado de notificaciones
SELECT 
    estado,
    COUNT(*) as total,
    MAX(creado_en) as ultimo
FROM cola_notificaciones 
GROUP BY estado;

Paso 2: Procesar cola manualmente

# Procesar notificaciones pendientes
curl -X POST http://localhost:4321/api/notificaciones/procesar \
  -H "Authorization: Bearer TU_ADMIN_TOKEN"

# Verificar respuesta
# Debería mostrar: processed, sent, failed counts

🛠️ Herramientas de Diagnóstico

🔍 Script de Diagnóstico Automático

health-check.sh

#!/bin/bash
# health-check.sh - Diagnóstico completo del sistema

echo "🔍 DIAGNÓSTICO DEL SISTEMA CDA"
echo "================================"

# 1. Verificar servicios
echo "📊 Estado de Servicios:"
systemctl is-active mysql && echo "✅ MySQL: Activo" || echo "❌ MySQL: Inactivo"
pgrep -f "node.*4321" > /dev/null && echo "✅ Node.js: Activo" || echo "❌ Node.js: Inactivo"

# 2. Verificar puertos
echo -e "\n🔌 Puertos en uso:"
netstat -tlnp | grep -E "(3306|4321)" || echo "❌ Puertos no encontrados"

# 3. Verificar espacio en disco
echo -e "\n💾 Espacio en disco:"
df -h | grep -E "(/$|/var)" | awk '{print $5 " " $6}' | \
  while read usage mount; do
    if [ "${usage%}" -gt 80 ]; then
      echo "❌ $mount: $usage (CRÍTICO)"
    else
      echo "✅ $mount: $usage"
    fi
  done

# 4. Verificar base de datos
echo -e "\n🗄️ Base de Datos:"
mysql -u app_notificaciones -p$DB_PASSWORD notificaciones_automotrices -e "
SELECT 
  'Clientes' as tabla, COUNT(*) as total FROM clientes
UNION ALL
SELECT 'Vehículos', COUNT(*) FROM vehiculos
UNION ALL
SELECT 'Documentos', COUNT(*) FROM documentos
UNION ALL
SELECT 'Notificaciones pendientes', COUNT(*) FROM cola_notificaciones WHERE estado = 'pendiente';
" 2>/dev/null && echo "✅ BD accesible" || echo "❌ BD no accesible"

echo -e "\n📊 Diagnóstico completado"