Guía del Sistema para QA

Descripción detallada de la arquitectura, alcance, módulos y comportamiento esperado de Nexo para facilitar las pruebas del equipo de Quality Assurance.

1. Introducción y Alcance

Nexo es una plataforma integral SaaS de gestión empresarial y Punto de Venta (POS) diseñada para operar de forma rápida y confiable. El alcance del proyecto incluye desde la operación directa de ventas en mostrador (POS offline-first) hasta la gestión administrativa y contable en tiempo real desde la nube (Web Panel).

Objetivo de las pruebas

El equipo de QA debe garantizar que:

  • Disponibilidad: Las ventas en el POS de escritorio deben funcionar incluso sin conexión a internet (enfoque "local first").
  • Sincronización: Los datos deben fluir correctamente entre el Web Panel y el POS (a través de Pub/Sub) para que precios y productos siempre estén actualizados.
  • Consistencia: Las operaciones financieras (compras, ventas, cuentas por cobrar, pagos, contabilidad) deben generar asientos exactos.
  • Experiencia de Usuario: La interfaz debe mantener la estética "calm precision" (como lo dicta el StyleGuide.MD) sin interacciones "jittery" (brincos).

2. Arquitectura del Sistema

Nexo está compuesto por los siguientes subsistemas principales que deben probarse individual y conjuntamente:

Backend API Core (Express/MySQL)

Servidor REST en Node.js?v=1.0.1/Express. Maneja toda la lógica de negocio sincrónica. Usa bases de datos relacionales para mantener la consistencia (MySQL). Exige validaciones estrictas con Zod. Cada request debe manejar autenticación vía tokens JWT.

Backend Gestor de Eventos

Sistema asíncrono para procesos en background. Usa BullMQ y Redis para procesar colas de trabajo sin bloquear la API. Integra Google Cloud Pub/Sub para enviar eventos en tiempo real al POS (por ejemplo, cuando un admin cambia un precio en el Web Panel).

Frontend Web Panel (React/Antd)

Aplicación web SPA para la administración del negocio (Dueños, Administradores, Contadores). Enrutado protegido que se bloquea si hay problemas de facturación (Suscripciones vencidas). Todo está protegido bajo un "ModuleGuard".

Frontend POS / App Móvil

Aplicaciones para puntos de venta que aplican un enfoque offline-first. Requieren sincronización constante con el servidor cuando hay internet, manejando reconexiones para envío de tickets almacenados localmente.

3. Módulos del Sistema (ERP Completo)

Nexo es un ERP integral. El equipo de QA debe verificar el comportamiento y las interacciones entre todas estas piezas de software que componen el ecosistema:

Catálogo Productos, Ofertas y Menús

Módulos: Productos, Categorías, Marcas, Unidades (UoM), Grupos de Modificadores (Restaurantes), Ofertas.

Uso: Creación de ítems físicos o servicios. Gestión de códigos de barra, imágenes de productos, y asignación a múltiples almacenes.

Condiciones: Probar la búsqueda por código de barras (pesaje de balanzas incluido), actualización de precios que dispare eventos PubSub, y que los modificadores alteren correctamente el precio base y la comanda de cocina.

Logística Inventario y Almacenes

Módulos: Almacenes, Ubicaciones (Pasillos/Estantes), Ajustes de Inventario (Conteos), Historial de Stock, Transferencias entre almacenes.

Uso: Tracking en tiempo real del stock. Las transferencias mueven ítems físicamente en el sistema.

Condiciones: Las transferencias deben ser transacciones atómicas (A -> B). QA debe validar que vender en negativo esté bloqueado o genere alertas (según configuración). El escaneo en lote para ajustes de inventario debe sumarizar cantidades.

Comercial POS, Facturación y Turnos

Módulos: POS (Ventas), Turnos (Shifts), Cotizaciones (Quotes), Conduces (Delivery Notes), Notas de Crédito/Débito (Notes), Mesas (Tables).

Uso: Interfaz de venta directa (Offline-first), apertura/cierre de turnos de cajeros, cuadre de caja, emisión de facturas electrónicas (ECF) y facturas de consumo. Conversión de cotización a factura.

Condiciones: Validar el "Offline mode" (vender sin internet y sincronizar después), múltiples métodos de pago, cálculo del 10% de Ley, propinas, y anulación de facturas (generando Nota de Crédito automáticamente si tenía NCF).

Clientes CxC y Portal de Clientes

Módulos: Clientes, Grupos de Clientes, Cuentas por Cobrar (CxC), Pagos/Abonos, Proyecciones (Forecast), Actividades de Cobranza, Portal del Cliente (Statement).

Uso: Seguimiento al límite de crédito, histórico de deudas, estado de cuenta público por cliente (/c/:clientId) y gestión de morosidad.

Condiciones: QA debe validar abonos parciales, pagos múltiples a una misma factura, y que el límite de crédito bloquee ventas a plazo en el POS si es excedido.

Proveedores Compras y Cuentas por Pagar (CxP)

Módulos: Proveedores, Compras, Notas de Compra, Distribución de Costos, Pagos a Proveedores (AP).

Uso: Entrada de mercancía, actualización del costo promedio ponderado de productos, y gestión de deudas con suplidores.

Condiciones: Validar cómo un cambio en el costo en una compra afecta el costo del catálogo y el margen de ganancia histórico. Probar el registro de compras con NCF para alimentar el formato 606 de la DGII.

Finanzas Contabilidad, Fiscalidad y Gastos

Módulos: Plan de Cuentas, Libro Diario, Periodos Contables, ITBIS, IT-1, IR-17, Estados Financieros (General Balance, P&L), Gastos (Expenses).

Uso: Todo evento financiero genera asientos contables (Journal entries). Permite cierres contables mensuales y preparación de anexos DGII.

Condiciones: QA debe verificar la "Partida Doble" estricta (Débitos = Créditos) en cada evento (venta, compra, gasto, transferencia). Validar la generación del JSON/XML para la Facturación Electrónica (FE / ECF API).

Finanzas Reportes y Analíticas

Módulos: Dashboards, Resumen de Ventas, Ganancias (Earnings), Ingresos/Egresos, Inventario Valorado, Deudas por Pagar/Cobrar, Historial de Turnos.

Uso: Vista gerencial en tiempo real. Soporta filtros por fecha, empleado, almacén o sucursal.

Condiciones: El "Dashboard" utiliza webhooks y cron-jobs para agregación. QA debe validar que las exportaciones a PDF/Excel respeten los filtros de la pantalla.

RRHH Empleados, Usuarios y Roles

Módulos: Usuarios (Roles y Permisos, 2FA/TOTP), Empleados, Anticipos (Advances), Pagos de Nómina (Payments).

Uso: Control de acceso al sistema (RBAC) y gestión de finanzas de personal (préstamos y pagos salariales).

Condiciones: Verificar que un usuario con rol "Cajero" no pueda acceder a las rutas de `/admin` o `/contabilidad` vía URL directa. Probar autenticación TOTP.

Hardware Dispositivos y Periféricos

Módulos: Dispositivos (Bootstrap, Heartbeat, Sync Logs), Balanzas Computarizadas (Scales), Impresoras (Printers ESC/POS), Plantillas de Recibos.

Uso: Integración con hardware en la tienda física y telemetría de los equipos conectados al POS.

Condiciones: QA debe emular el "Heartbeat" de los dispositivos, probar el parseo de códigos de balanza (Ej: prefijo + código + peso), y el renderizado dinámico de las plantillas de recibos.

SaaS Admin Nexo Superadmin

Módulos: Negocios (Tenants), Suscripciones y Facturación (Billing/Stripe), Leads, Analíticas Globales.

Uso: Panel exclusivo del equipo de Nexo para gestionar a los clientes, habilitarles el módulo de NCF, bloquear cuentas morosas, o ajustar los límites de sus planes.

Condiciones: Bloqueos (Suspensiones) en tiempo real, forzando a las sesiones activas del cliente a ver la pantalla `BillingRequiredPage`.

4. Roles y Permisos

La seguridad y visibilidad dependen del rol del usuario autenticado. Verificar el acceso a endpoints de la API y rutas en React:

Rol Capacidades y Accesos
Dueño / Admin Acceso total a todos los módulos, reportes de ganancias y configuraciones de facturación.
Gerente Acceso a inventario, compras, clientes y ventas. No tiene acceso a facturación de la suscripción de Nexo.
Contador Acceso read-only a operaciones de ventas y compras, acceso total al módulo de Contabilidad y Exportaciones DGII.
Cajero Acceso exclusivo al módulo de Ventas (POS), listado de productos y cierre de turno.

5. Rendimiento Esperado (SLAs)

Durante las pruebas de performance, asegúrese de que el sistema cumple con estos lineamientos base establecidos para la versión 4.8.0+:

  • Tiempo de respuesta de API: El p99 debe estar alrededor de los 210ms.
  • Búsqueda en POS: La búsqueda de productos en la aplicación de caja debe resolverse en menos de 120ms (idealmente instantáneo por carga local).
  • Notificaciones Pub/Sub: Un cambio de precio en el Web Panel debe reflejarse en el POS local en menos de 5 segundos (teniendo red estable).
  • Manejo de UI: Ausencia de layouts "bouncy". Las animaciones usan curvas ease-out y no superan los 250ms.

6. Comportamientos Críticos (Edge Cases)

Estos escenarios deben estar cubiertos por las pruebas de QA ya que son de alto riesgo:

  • Offline Mode en POS: Cortar la conexión del cajero durante una venta. La factura debe generarse localmente, imprimir ticket y guardarse en cola. Al reconectar, la sincronización debe validar el envío del ticket sin duplicados.
  • Concurrencia en Inventario: Múltiples cajeros facturando el último artículo de un producto. El backend debe aplicar candados para no dejar el stock en negativo (salvo configuración explícita).
  • Bloqueo por Suscripción: Si la cuenta de un negocio expira o el pago falla, la API debe devolver 402 SUBSCRIPTION_REQUIRED. El frontend intercepta este error y expulsa al usuario al BillingRequiredPage.
  • Consumo de NCF (Comprobantes Fiscales): Cada factura válida para DGII debe incrementar el currentNumber de la secuencia atómicamente, sin saltos ni duplicidad de comprobantes.
  • Modo Oscuro/Claro: El atributo data-theme se altera dinámicamente; las gráficas y componentes deben mantener contraste AA (4.5:1).

7. Guía Operativa y Expectativas para QA

Entender los módulos es solo el primer paso. A continuación, detallamos cómo esperamos que el equipo de QA aborde las pruebas de Nexo y el estándar de calidad al reportar incidencias.

Flujos Críticos de Negocio (Golden Paths)

Antes de probar casos aislados, QA debe asegurar siempre que los flujos principales (End-to-End) no estén rotos en cada despliegue:

  • E2E Ventas y Contabilidad: Crear Producto → Ingresar Compra (Suma Stock) → Abrir Turno → Facturar en POS → Cerrar Turno → Verificar asientos automáticos en Contabilidad (Diario).
  • E2E Crédito y Cobro: Venta a crédito superando límite (debe fallar) → Venta a crédito válida → Recibir Abono Parcial en módulo CxC → Verificar impacto en Flujo de Caja.
  • E2E Resiliencia Offline: Apagar internet (DevTools / Throttling) → Realizar 3 ventas en POS → Encender internet → Verificar que el "Background Sync" procesó los 3 tickets sin duplicarlos y rebajó stock.

Técnicas de Prueba Esperadas

Simulación de Problemas de Red: Dado que el POS es offline-first, es obligatorio usar las herramientas de desarrollador del navegador para simular "Offline", "Slow 3G" y probar la recuperación al volver a "Online".

Testing de Concurrencia (Race Conditions): Nexo es multi-usuario. Esperamos que QA abra dos ventanas (o dos usuarios) e intente vender o modificar el último ítem de inventario simultáneamente para validar los bloqueos (Locks) del backend.

Pruebas de Zona Horaria: Los reportes de cierre de caja (Turnos) operan frecuentemente a medianoche. Prueben generar cierres en el límite de la medianoche para asegurar que las ventas caen en el día fiscal correcto.

Estándar de Reporte de Bugs

Cuando encuentren una anomalía, no basta con decir "falló". Un reporte de bug válido en Nexo debe contener:

  • Pasos para reproducir (STR): Instrucciones exactas 1, 2, 3.
  • Rol utilizado: ¿Ocurrió siendo Admin, Cajero o Contador?
  • Logs y Red: Captura de la consola del navegador y de la pestaña "Network" mostrando si la API retornó un error 400 o 500, incluyendo el Response de error del servidor.
  • Comportamiento Actual vs. Esperado: Qué pasó vs. qué debió pasar según esta documentación.

8. Entornos y Datos de Prueba

Para evitar contaminar la data real de producción, el equipo de QA debe operar estrictamente en los entornos designados y usar la data de prueba aprobada.

Entornos (Environments)

  • Development (Dev): Rama `develop`. Entorno inestable. Aquí se prueban los tickets recién cerrados por los desarrolladores. La base de datos puede limpiarse sin previo aviso.
  • Staging (QA): Rama `release`. Entorno estable, réplica exacta de producción. Aquí se realiza la Prueba de Regresión antes del despliegue final.
  • Production (Prod): Rama `main`. Sistema en vivo. QA solo debe realizar "Smoke Tests" de solo lectura en producción o usando cuentas marcadas explícitamente como "Test Tenant" para no afectar las analíticas globales.

Datos Mockeados Oficiales

Al realizar pruebas que involucran integraciones externas, utilice estrictamente estos datos:

  • Pagos con Tarjeta (SaaS Billing / Stripe): Use las tarjetas de prueba oficiales de Stripe (ej. 4242 4242 4242 4242 con cualquier fecha futura y CVC). Nunca use tarjetas reales.
  • Facturación Electrónica (NCF / DGII): Utilice RNCs de prueba genéricos como 131-01646-6 o 1-31-00632-4 para verificar validaciones de contribuyentes sin disparar alertas en servicios reales.
  • Correos Electrónicos: Para probar el envío de cotizaciones y facturas por correo, use cuentas de prueba terminadas en @nexo.com.do o servicios como Mailtrap.

9. Severidad y Ciclo de Vida de Bugs

Cada reporte de bug debe ser categorizado correctamente para que el equipo de desarrollo pueda priorizarlo de inmediato.

Severidad Criterio de Asignación (Cuándo usarlo) SLA de Resolución Esperado
Blocker El sistema está caído (503/500 general), el POS no puede facturar de ninguna forma, o hay pérdida de datos. No existe un workaround. Inmediato (Hotfix)
Critical Una función core falla (ej. cálculo de ITBIS incorrecto, cobros dobles) pero el resto del sistema opera, o el POS falla pero la Web funciona. 2 - 4 Horas
Major Un módulo secundario no funciona (ej. un reporte de ganancias no carga, o no se pueden crear nuevas ubicaciones de almacén) pero existe un camino alternativo. En el Sprint actual
Minor/UI Fallos estéticos (colores, alineaciones "jittery"), errores de ortografía, o funciones de bajo uso que no bloquean operaciones. Backlog (Próximos Sprints)

Ciclo de Vida (Estados en Jira/Linear)

Nuevo → Triage (Revisión de Dev) → En Progreso → En Revisión (Code Review) → A la espera de QA → Done (Verificado) o Rechazado (Devuelto al Dev).

10. Checklist de Regresión Obligatoria

Antes de aprobar cualquier Release para Producción, QA debe asegurar de forma manual o automatizada (Cypress/Playwright) este flujo mínimo garantizado: