@viamericas/compliance-sar-exception-alert

Componente React empaquetado como librería npm para gestionar Políticas de Excepción SAR (Suspicious Activity Report) en el módulo de Compliance de Viamericas.

Descripción

Permite a usuarios de compliance crear, editar, visualizar y exportar políticas de excepción por agencia. Cada agencia puede tener hasta 4 tipos de excepción (IDs 376–379), cada uno con una fecha de aplicación. El componente se integra dentro de aplicaciones React host proporcionando parámetros de conexión y configuración.

Instalación

npm i -S -E @viamericas/compliance-sar-exception-alert

Las dependencias marcadas como externals en webpack no se incluyen en el bundle y deben estar disponibles en la app host: react, react-dom, i18next, react-i18next, prop-types, axios.

Uso

import ExceptionPolicies from '@viamericas/compliance-sar-exception-alert';

<ExceptionPolicies
  params={{
    connecParam: {
      urlApi: 'https://sar.viamericas.io/dev',  // Base URL del API
      axiosInstance: axiosInstance               // Instancia axios con interceptors (opcional)
    },
    pagination: {
      numberOfRecordsByPage: 15,
      maxButtonsArea: 5
    },
    user: {
      name: 'john.doe'                          // Usuario que se registra en saves
    },
    ux: { /* mapeo semántico de clases CSS - ver sección UX */ }
  }}
  t={t}                    // Función de traducción i18next (opcional, usa interna si no se pasa)
  className="my-wrapper"   // Clase CSS wrapper (default: "exception-policies-wrapper")
/>

Props

| Prop | Tipo | Requerido | Descripción | |------|------|-----------|-------------| | params.connecParam.urlApi | string | ✓ | URL base del API backend | | params.connecParam.axiosInstance | object | — | Instancia axios personalizada (usa axios puro si no se pasa) | | params.pagination.numberOfRecordsByPage | number | — | Registros por página (default: 15) | | params.pagination.maxButtonsArea | number | — | Botones visibles en paginador (default: 5) | | params.user.name | string | — | Nombre de usuario para auditoría | | params.ux | object | — | Mapeo de claves semánticas a clases CSS (personalización visual) | | t | function | — | Función de traducción i18next. Si no se pasa, usa useTranslation('exceptionPolicies') | | className | string | — | Clase wrapper (default: "exception-policies-wrapper") |

API Endpoints

El componente consume estos endpoints (relativos a connecParam.urlApi):

| Método | Endpoint | Body | Descripción | |--------|----------|------|-------------| | POST | /exception-policies/list | { agencyId, pageNumber, pageSize } | Lista agencias con sus políticas (paginado) | | POST | /exception-policies/save | { agencyId, policies[], userName } | Crea/actualiza políticas de una agencia | | GET | /exception-policies/types | — | Obtiene catálogo de tipos de excepción |

Estructura de respuesta de /list

{
  "data": [
    {
      "ID_BRANCH": "AGENCY001",
      "policies": [
        {
          "ID_EXCEPTION": 1,
          "ID_TYPE_EXCEPTION": 376,
          "POLICY_NAME": "Exception Policy 1",
          "DATE_EXCEPTION_APPLIED": "2024-01-15T00:00:00"
        }
      ]
    }
  ],
  "totalCount": 42
}

Estructura del Proyecto

├── src/
│   ├── index.js                          # Entry point - exporta <ExceptionPolicies>
│   ├── core/
│   │   ├── main.js                       # Componente principal (state, handlers, layout)
│   │   ├── axiosInstance.js              # Axios con refresh token (para dev-test)
│   │   ├── utils/
│   │   │   └── i18n.js                   # Configuración i18next (Suspense, backend HTTP)
│   │   ├── components/
│   │   │   ├── filterPanel.js            # Panel lateral: filtro por código de agencia
│   │   │   ├── agencyCard.js             # Card por agencia con filas de políticas
│   │   │   ├── policyRow.js              # Fila individual: checkbox + nombre + datepicker
│   │   │   ├── newPoliciesModal.js       # Modal para crear políticas en nueva agencia
│   │   │   ├── exportButton.js           # Exporta todo a Excel (.xlsx)
│   │   │   ├── alert.js                  # Componente de alertas (error/warning/success/info)
│   │   │   └── resultComponents.js       # (Legacy/demo - no usado activamente)
│   │   ├── business/
│   │   │   ├── services/
│   │   │   │   └── exception-policies.service.js  # Llamadas HTTP al API
│   │   │   ├── rules/
│   │   │   │   └── sum.js               # (Legacy/demo - regla de suma)
│   │   │   └── graphql/                  # (Placeholder - no implementado)
│   │   └── styles/
│   │       ├── style.scss                # Barril: @forward de parciales
│   │       ├── _variables.scss           # Paleta Viamericas ($primary, $secondary, etc.)
│   │       ├── exception-policies.scss   # Estilos legacy (reemplazados por componentes/)
│   │       └── components/
│   │           ├── _layout.scss          # .ep-loading, .ep-main__empty, .ep-pagination
│   │           ├── _header.scss          # HoldsPpal_headFixed, _operator_ppal_*
│   │           ├── _filterVertical.scss  # filter_vertical_ppal, filter_hideFilter
│   │           ├── _resultsTable.scss    # HoldsPpal_rows_pair, HoldsPpal_cols
│   │           └── _buttons.scss         # Botones, footer, modal overlay
│   └── assets/
│       ├── images/
│       └── fonts/                        # FontAwesome (woff2, woff, ttf, svg, eot)
├── __test__/
│   ├── index.test.js                     # Tests del componente Main
│   ├── sum.test.js                       # Test de la regla Sum (legacy)
│   └── mocks/
│       └── assetsTransformer.js          # Mock para imports de assets en Jest
├── dev-test/
│   ├── App.js                            # App de desarrollo con params de ejemplo
│   ├── index.html                        # HTML host para webpack-dev-server
│   ├── locales/
│   │   ├── en/exceptionPolicies.json     # Traducciones inglés
│   │   ├── es/exceptionPolicies.json     # Traducciones español
│   │   └── i18n.js                       # Config i18n para dev-test
│   └── styles/
│       ├── style.scss                    # Estilos globales de desarrollo
│       ├── _fonts.scss
│       └── _demo.scss
├── doc/
│   └── component.png                     # Screenshot de referencia
├── .kiro/
│   └── specs/
│       ├── exception-policies-crud/      # Spec: CRUD de políticas
│       └── design-alignment/             # Spec: alineación visual con referencia
└── config files...

Scripts NPM

| Comando | Descripción | |---------|-------------| | npm start:dev | Dev server en http://localhost:9020 (usa dev-test/App.js) | | npm run build | Compila a build/index.js (producción, commonjs2) | | npm run build:debug | Build con source maps | | npm test | Ejecuta Jest con coverage | | npm run test:w | Jest en modo watch | | npm run lint | Prettier + ESLint con auto-fix | | npm run analizedependences | Analiza bundle con source-map-explorer |

Stack Técnico

| Categoría | Tecnología | |-----------|------------| | UI | React 18, react-bootstrap 2.10, react-icons | | State | useState/useEffect (hooks, sin state manager externo) | | HTTP | axios (instancia configurable por la app host) | | i18n | i18next + react-i18next (namespace: exceptionPolicies) | | Datepicker | react-datepicker | | Export | xlsx (SheetJS) | | Build | Webpack 5 (output commonjs2) | | Transpile | Babel (preset-env + preset-react) | | Styles | SCSS (Dart Sass, módulos con @forward/@use) | | Tests | Jest 29 + @testing-library/react 16 | | Lint | ESLint + Prettier + Husky (pre-commit) | | Paginación | @viamericas/viam-pagination-reports | | Utilidades | @viamericas/viam-utils (peer dependency) |

Internacionalización (i18n)

• Namespace: exceptionPolicies
• Idiomas: en, es
• Carga: HTTP backend (/locales/{{lng}}/{{ns}}.json)
• El componente acepta t como prop o usa useTranslation('exceptionPolicies') internamente

Sistema de Estilos

El componente usa el patrón UX de compliance-invoices-hold: las clases CSS se pasan desde la app host a través del objeto params.ux. Esto permite personalización sin tocar el componente.

Variables de paleta (_variables.scss)

$primary: #f36421;    // Naranja Viamericas
$secondary: #075ca6;  // Azul
$green: #58b950;
$dark: #666666;
$snow: #dedede;
$snow-light: #f3f3f3;
$snow-dark: #e8e8e8;
$body-bg: #f5f5f5;

Claves UX soportadas

ppalContainer, ppalHeader, ppalFooter, ppalBody, ppalFilter,
info, infoMax, infoMin, headerIcon, icon, titlePpal,
verticalFilter, hideFilter, filterTitle, filterBody,
titlesFilter, inputFilter, buttonFilter, btnFilter,
titleCols, rowsPair, rowsNotPair, cols,
btnPrimary, btnSave, btnExport

Tipos de Políticas (hardcoded)

| ID | Nombre | |----|--------| | 376 | Exception Policy 1 | | 377 | Exception Policy 2 | | 378 | Exception Policy 3 | | 379 | Exception Policy 4 |

Nota: Estos IDs están hardcoded en agencyCard.js, newPoliciesModal.js y exportButton.js. El endpoint GET /exception-policies/types existe pero actualmente no se usa para poblar la lista.

Tests

• Framework: Jest + jsdom
• Ubicación: __test__/
• Estrategia: mockea react-i18next y exception-policies.service con jest.fn()
• Cobertura mínima configurada: 0% (thresholds en 0 en jest.config.js)

Tests existentes (index.test.js)

1. Renderiza el contenedor de Exception Policies
2. Renderiza el sidebar de filtro
3. Renderiza botón "New Policies"
4. Renderiza botón "Export"
5. Abre modal al hacer clic en "New Policies"
6. Toggle de visibilidad del panel de filtro
7. Muestra datos de agencia después de cargar

Configuración de Desarrollo

# Instalar dependencias
npm install

# Levantar dev server
npm run start:dev
# → http://localhost:9020

# El dev-test/App.js apunta a:
# API: https://sar.viamericas.io/dev
# Auth: Token JWT hardcoded (expirado, actualizar si se necesita)

Publicación NPM

npm login
npm run build
npm publish

El paquete se publica bajo el scope @viamericas. El registro está configurado en .npmrc.

Notas para el Desarrollador

• El axiosInstance.js en src/core/ tiene refresh token logic contra Cognito, pero es solo para dev-test. En producción, la app host pasa su propia instancia.
• resultComponents.js y sum.js son legado del template y no se usan en el componente real.
• El layout replica el patrón de compliance-invoices-hold: header fijo, filtro lateral colapsable (col-3), contenido principal (col-9/col-12), footer fijo.
• Los estilos usan el sistema de módulos moderno de Sass (@use/@forward) para evitar deprecation warnings de Dart Sass 3.0.