# Guía de Mantenimiento - Módulo de Tarjetas (SysIP)

Esta documentación está diseñada para facilitar el traspaso y mantenimiento del módulo de gestión y activación de tarjetas del sistema SIS2000.

## 1. Arquitectura General
El módulo sigue una arquitectura de capas estándar:
- Frontend (Angular): Captura de datos y validaciones de interfaz.
- Backend (Node.js): Orquestación de servicios, APIs y lógica de negocio.
- Base de Datos (SQL Server): Procedimientos almacenados para persistencia y validaciones críticas.

---

## 2. Flujo de Procesos Principal

### A. Registro de Lotes y Tarjetas
1. Interfaz: El usuario selecciona un producto y cantidad.
2. Backend: Llama a cardService.registerLot.
3. Base de Datos: Se ejecuta sp_RegistrarLoteTarjetas_simplificado.
   - Lógica de Plan: El SP intenta buscar un plan (cplan) vinculado directamente al producto. Si no lo encuentra, busca el primer plan del mismo ramo. Esto evita tarjetas "huérfanas" de plan.

### B. Validación y Determinación de Formulario
Este es el punto más crítico para el mantenimiento.
1. Interfaz: El usuario ingresa el código de 8 caracteres.
2. Backend: Llama a CardModel.spValidarTarjeta que ejecuta el SP sp_ValidarTarjetaParaActivacion.
3. Determinación del Formulario (tipo_formulario):
   - El sistema busca: Tarjeta -> Lote -> Plan -> Producto -> Formulario (xform).
   - El valor de tipo_formulario se obtiene del campo xform en la tabla maproductos.
   - Lógica de Fallback (RCV): Si el plan/producto no tiene un formulario definido, el SP busca el primer formulario válido del mismo Ramo. (Ejemplo: Ramo 18 siempre devolverá 'rcv').

### C. Activación y Emisión
1. Interfaz: Se carga el componente específico basado en tipo_formulario:
   - rcv -> card-act-rcv.component
   - automobile -> card-act-automobile.component
   - persons -> card-act-persons.component
2. Backend: Se envían los datos a cardController.submitForm o submitFormAutomobile.
3. Resultado: Se crea la factura en tafactura, se cambia el estado de la tarjeta a 2 (Activada) y se genera el PDF.

---

## 3. Archivos Clave para Mantenimiento

### Backend (SysIP-backend)
- Controlador: src/controllers/cardController.js (Puntos de entrada API).
- Servicio: src/service/cardService.js (Lógica de validación y transformación).
- Modelo: src/db/CardModel.js (Llamadas a Stored Procedures).

### Frontend (SysIP)
- Componente Principal: src/app/views/cards/activation/activacion-tarjeta.component.ts
- Sub-componentes: src/app/views/cards/activation/components/ (Contiene las carpetas card-act-rcv, card-act-automobile, etc).

### Base de Datos (Sis2000)
- sp_ValidarTarjetaParaActivacion: Valida estado y decide qué formulario mostrar.
- sp_RegistrarLoteTarjetas_simplificado: Generador de lotes y códigos únicos.
- sp_GestionarTarjeta: SP centralizado para operaciones administrativas (Búsqueda, Soft-Delete).

---

## 4. Cómo añadir un Nuevo Tipo de Tarjeta/Formulario

1. Base de Datos: En la tabla maproductos, asegúrate de que el producto tenga un nombre en el campo xform (ejemplo: 'rcv').
2. Frontend Component: 
   - Toma como referencia los componentes en activation/components/card-act-rcv.
   - Regístralo en cards.module.ts.
3. Frontend Template: En activacion-tarjeta.component.html, la carga se maneja por condiciones:
   ```html
   <div *ngIf="formData.tipo_formulario === 'rcv'">
       <card-act-rcv ...></card-act-rcv>
   </div>
   ```

---

## 5. Solución de Problemas Comunes (Troubleshooting)

| Problema | Causa Probable | Solución |
| :--- | :--- | :--- |
| Carga el formulario de "Personas" en lugar de RCV | El plan de la tarjeta apunta a un producto sin xform definido. | El SP ahora tiene un fallback por ramo. Verifica que el ramo en tatarlot sea 18 para RCV. |
| Error "Tarjeta no encontrada" | El código ingresado no existe o fue anulado (iestado = 0). | Verificar en tatarjeta usando el xcodigo_unico. |
| El PDF no se genera | Fallo en la conexión con la API de emisión de QA. | Revisar logs del backend para ver el error de node-fetch. |

---
Documentación generada el: 09/03/2026
Ubicación de Scripts SQL: Desktop/solution_final/