# Plan de migracion backend Bancamiga -> Mercantil

## Objetivo

Reutilizar la base tecnica del backend de Bancamiga en el proyecto Mercantil, incorporando los flujos operativos que ya estan maduros:

- Informacion general mediante Knowledge AI, no por backend.
- Seguridad de tarjetas con bloqueo, reposicion y verificacion TOTP.
- Seguimiento de casos o solicitudes.
- Solicitudes comerciales, por ejemplo cuenta o tarjeta de credito.
- Logica Mercantil existente para OCR, reclamos, reglas y handover summary.

El resultado debe ser un backend Mercantil aislado, con rutas, datos, estados, textos y configuracion propios.

## Restricciones

- No implementar omnicanalidad en Mercantil.
- No migrar integraciones NICE, WhatsApp, Webchat omnicanal ni transformadores omnicanal.
- No incluir reset demo.
- No incluir limpieza de Contact Profile.
- No crear endpoints `/demo/reset`, `/demo/state` ni servicios equivalentes para borrar memoria Cognigy.
- No compartir estado runtime, TOTP secrets ni configuracion Cognigy con Bancamiga.
- No exponer credenciales ni guardar API keys en Markdown.
- No usar datos reales de clientes, tarjetas, OTP, PAN, CVV, PIN o claves.

## Decision de arquitectura

Usar el backend de Bancamiga como plantilla de arquitectura, no como servicio compartido en caliente.

La migracion debe crear/adaptar un backend Mercantil propio dentro de `/home/dunmagno/cognigy-merncantil`, tomando de `/home/dunmagno/cognigy-bancamiga/bancamiga-contigo-backend` los patrones de:

- Express.
- Middlewares.
- Validacion con Zod.
- API key.
- Servicios modulares.
- Tests por modulo.
- TOTP real con `otplib`.
- QR para enrolamiento.

La logica de marca, datos demo, rutas y prefijos debe ser Mercantil.

## Estado actual

### Mercantil

Repositorio: `/home/dunmagno/cognigy-merncantil`

Backend actual:

- `src/server.js`: servidor HTTP nativo.
- `src/mercantilDemo.js`: logica de OCR simulado/nativo, reglas, reclamos, handover summary y OTP demo fijo.

Rutas actuales relevantes:

- `GET /health`
- `POST /bank/mercantil/demo/identity/verify`
- `POST /bank/mercantil/demo/ticket/extract`
- `POST /bank/mercantil/demo/rules/evaluate`
- `POST /bank/mercantil/demo/claims`
- `GET /bank/mercantil/demo/claims/:claimId`
- `POST /bank/mercantil/demo/handover-summary`
- `POST /bank/mercantil/demo/uploads`
- `POST /bank/mercantil/demo/cognigy-rest-test`

### Bancamiga

Repositorio fuente: `/home/dunmagno/cognigy-bancamiga/bancamiga-contigo-backend`

Modulos reutilizables:

- `auth`: enrolamiento y validacion TOTP.
- `users`: consulta de usuario demo.
- `cards`: listado y bloqueo de tarjetas.
- `cases`: creacion, consulta y resumen.
- `replacements`: solicitud de reposicion de tarjeta.
- `applications`: solicitudes comerciales.
- `middlewares`: API key, validacion, errores, not found.
- `utils`: IDs, fechas, mascaras, errores.
- `tests`: cobertura por modulo.

Modulos que no deben migrarse:

- `demo.routes.js`
- `demo.controller.js`
- `cognigyProfiles.service.js`
- scripts de reset de perfiles Cognigy.
- documentacion o scripts NICE/omnichannel.

## Diseño objetivo

### Stack

Migrar el backend Mercantil a Express para alinearlo con el patron Bancamiga.

Dependencias esperadas:

- `express`
- `cors`
- `helmet`
- `morgan`
- `zod`
- `otplib`
- `qrcode`
- `nanoid`

Migrar a ESM, mover el backend completo al patron Bancamiga. Para minimizar riesgo dentro del repo actual.

### Namespace

Todas las rutas operativas deben vivir bajo:

```text
/bank/mercantil/demo
```

No usar rutas genericas `/bank/demo`.

### Estado demo

Crear un store Mercantil aislado con:

- usuarios demo.
- tarjetas demo.
- casos.
- reposiciones.
- solicitudes comerciales.
- secretos TOTP.
- usuarios validados por TOTP.
- intentos fallidos de OTP.
- reclamos OCR existentes.

No incluir reset publico de estado.

### Configuracion

Variables sugeridas:

```text
PORT=3001
MERCANTIL_DEMO_API_KEY=<secret>
MERCANTIL_DEMO_USER_ID=demo-user-001
MERCANTIL_DEMO_CUSTOMER_NAME=Cliente Mercantil Demo
MERCANTIL_DEMO_PHONE=584121234567
MERCANTIL_TOTP_ISSUER=Mercantil Demo
MERCANTIL_TOTP_ACCOUNT_NAME=migura.demo@mercantil
MERCANTIL_TOTP_SECRETS_FILE=storage/mercantil-totp-secrets.json
MERCANTIL_COGNIGY_REST_ENDPOINT=<endpoint-rest-si-se-usa-ocr-test>
MERCANTIL_OCR_FORCE_DOWN=false
CORS_ORIGIN=*
```

No agregar:

```text
COGNIGY_PROFILE_RESET_CONTACT_ID
COGNIGY_PROFILE_RESET_ALLOW_FILTER_MATCHES
ENABLE_DEMO_RESET
```

## Endpoints objetivo

### Health

```text
GET /health
```

Respuesta esperada:

```json
{
  "status": "ok",
  "service": "mercantil-demo-backend"
}
```

### Autenticacion TOTP

```text
POST /auth/enroll
GET  /auth/qr/:userId
POST /auth/verify-totp
```

Uso:

- `POST /auth/enroll`: genera o reutiliza secreto TOTP para el usuario demo.
- `GET /auth/qr/:userId`: devuelve HTML con QR o JSON si `?format=json`.
- `POST /auth/verify-totp`: valida codigo de 6 digitos y marca el usuario como validado.

Reglas:

- Reemplaza el OTP fijo `123456` de `verifyIdentity`.
- Mantener limite de intentos, por ejemplo 3 intentos fallidos.
- No loguear OTP ni secreto.
- No devolver `manualSecret` salvo modo debug local explicitamente habilitado.

### Usuarios

```text
GET /bank/mercantil/demo/users/:userId
```

Devuelve solo datos publicos y seguros:

- `userId`
- `customerName`
- `firstName`
- `documentId` enmascarado si aplica.
- `phone` enmascarado si aplica.
- `city`
- `status`

### Tarjetas

```text
GET  /bank/mercantil/demo/users/:userId/cards
POST /bank/mercantil/demo/cards/:cardId/block
```

Reglas:

- Devolver tarjetas enmascaradas.
- No devolver PAN completo.
- Bloqueo requiere `userId`.
- El flujo Cognigy debe validar TOTP antes de llamar bloqueo, o el backend debe rechazar bloqueo si el usuario no esta validado en `validatedUsers`.

Decision recomendada:

- Backend debe exigir usuario validado por TOTP para bloqueo.
- Si no esta validado, responder `403 IDENTITY_NOT_VERIFIED`.

### Reposicion de tarjeta

```text
POST /bank/mercantil/demo/card-replacement
```

Reglas:

- Requiere `caseId`, `cardId`, `userId`, `branchName`, `city`.
- Debe existir caso.
- La tarjeta debe estar bloqueada.
- Debe crear `replacementId` con prefijo Mercantil, por ejemplo `REP`.
- Debe actualizar el estado del caso a `replacement_requested`.

### Casos

```text
POST /bank/mercantil/demo/cases
GET  /bank/mercantil/demo/cases/:caseId
```

Prefijo:

```text
MC-YYYY-000001
```

Tipos iniciales:

- `card_loss`
- `card_theft`
- `unrecognized_transaction`
- `commercial_request`
- `general_support`

Estados iniciales:

- `created`
- `card_blocked`
- `replacement_requested`
- `needs_human`
- `resolved`

### Solicitudes comerciales

```text
POST /bank/mercantil/demo/applications
GET  /bank/mercantil/demo/applications/:requestId
```

Productos iniciales:

- `account`
- `credit_card`

Campos minimos:

- `userId`
- `productType`
- `fullName`
- `documentId`
- `phone`
- `email`
- `city`
- `preferredBranchName`

Prefijo:

```text
SOL-YYYY-000001
```

### OCR y reclamos Mercantil existentes

Mantener o portar las rutas actuales:

```text
POST /bank/mercantil/demo/ticket/extract
POST /bank/mercantil/demo/rules/evaluate
POST /bank/mercantil/demo/claims
GET  /bank/mercantil/demo/claims/:claimId
POST /bank/mercantil/demo/handover-summary
```

Reglas:

- Conservar mascarado de datos sensibles.
- Conservar `mc_*` custom attributes.
- Conservar decision de reglas para `needs_human`.
- Integrar con TOTP real: `identityVerified` debe venir de `auth.service`, no de OTP fijo.

### OCR test opcional

Mantener solo si sigue siendo util para pruebas:

```text
GET  /ocr-test
GET  /ocr/:fileName
POST /bank/mercantil/demo/uploads
POST /bank/mercantil/demo/cognigy-rest-test
```

Esto no es omnicanalidad. Es una utilidad local para probar imagenes OCR contra el endpoint REST de Cognigy.

## Mapeo de Bancamiga a Mercantil

| Bancamiga | Mercantil objetivo | Accion |
| --- | --- | --- |
| `src/app.js` | `src/app.js` | Reutilizar estructura Express sin demo reset |
| `src/server.js` | `src/server.js` | Adaptar nombre del servicio |
| `auth.*` | `auth.*` | Reutilizar, cambiar issuer/account/env |
| `cards.*` | `cards.*` | Reutilizar, exigir TOTP validado |
| `cases.*` | `cases.*` | Adaptar prefijo `BM` a `MC` |
| `replacements.*` | `replacements.*` | Reutilizar |
| `applications.*` | `applications.*` | Adaptar `tdc` a `credit_card` |
| `demo.*` | No aplica | No migrar |
| `cognigyProfiles.service.js` | No aplica | No migrar |
| `seed.js` | `seed.js` Mercantil | Reescribir datos demo |
| `README.md` | README Mercantil | Documentar solo Mercantil |
| NICE/omnichannel scripts | No aplica | No migrar |

## Datos demo Mercantil

Crear datos separados:

```js
demoUser = {
  userId: "demo-user-001",
  customerName: "Cliente Mercantil Demo",
  firstName: "Cliente",
  documentId: "V00000000",
  phone: "584121234567",
  email: "cliente.demo@correo.com",
  city: "Caracas",
  status: "active"
}
```

Tarjetas:

```js
[
  {
    cardId: "mc-card-001",
    type: "debit",
    brand: "Mercantil",
    maskedPan: "**** **** **** 4821",
    last4: "4821",
    status: "active",
    canBlock: true
  },
  {
    cardId: "mc-card-002",
    type: "credit",
    brand: "Mercantil",
    maskedPan: "**** **** **** 9134",
    last4: "9134",
    status: "active",
    canBlock: true
  }
]
```

## Trabajo en Cognigy

Seguir reglas del repo:

1. Usar Cognigy Tools MCP primero.
2. Consultar documentacion si la operacion no es clara.
3. Usar Postman/OpenAPI solo si el MCP no cubre la operacion.
4. Usar API directa solo si es necesario y confirmado.

Tools Cognigy a crear o actualizar:

- `tool_verify_totp` -> `POST /auth/verify-totp`
- `tool_get_demo_user` -> `GET /bank/mercantil/demo/users/:userId`
- `tool_get_demo_cards` -> `GET /bank/mercantil/demo/users/:userId/cards`
- `tool_block_demo_card` -> `POST /bank/mercantil/demo/cards/:cardId/block`
- `tool_create_demo_case` -> `POST /bank/mercantil/demo/cases`
- `tool_get_demo_case` -> `GET /bank/mercantil/demo/cases/:caseId`
- `tool_create_card_replacement` -> `POST /bank/mercantil/demo/card-replacement`
- `tool_create_application` -> `POST /bank/mercantil/demo/applications`
- `tool_get_application` -> `GET /bank/mercantil/demo/applications/:requestId`
- `tool_extract_ticket_data` -> `POST /bank/mercantil/demo/ticket/extract`
- `tool_evaluate_claim_rules` -> `POST /bank/mercantil/demo/rules/evaluate`
- `tool_create_claim` -> `POST /bank/mercantil/demo/claims`
- `tool_build_handover_summary` -> `POST /bank/mercantil/demo/handover-summary`

No crear:

- herramientas omnicanal.
- handover NICE.
- reset de demo.
- limpieza de Contact Profile.

## Plan por fases

### Fase 1 - Preparacion

1. Crear snapshot de seguridad del proyecto Mercantil antes de tocar Cognigy.
2. Revisar estado git de Mercantil y separar cambios no relacionados.
3. Confirmar puerto local objetivo.
4. Confirmar URL publica si se necesitara exponer el backend con cloudflared.

Criterio de salida:

- Snapshot creado.
- Repo identificado.
- Sin cambios Cognigy todavia.

### Fase 2 - Estructura backend

1. Agregar dependencias Express/Zod/TOTP/QR si no existen.
2. Crear estructura modular:

```text
src/app.js
src/server.js
src/config/env.js
src/data/seed.js
src/data/demoStore.js
src/middlewares/apiKey.js
src/middlewares/validate.js
src/middlewares/errorHandler.js
src/middlewares/notFound.js
src/utils/dates.js
src/utils/errors.js
src/utils/ids.js
src/utils/mask.js
src/storage/totpSecretsStore.js
```

3. Mantener compatibilidad con las rutas existentes de Mercantil.
4. Evitar rutas de reset.

Criterio de salida:

- `npm run check` pasa.
- `GET /health` responde.

### Fase 3 - TOTP real

1. Portar `auth.service.js`, `auth.controller.js`, `auth.routes.js`.
2. Cambiar issuer y account a Mercantil.
3. Persistir secretos en archivo Mercantil.
4. Agregar limite de intentos.
5. Actualizar `verifyIdentity` para usar estado TOTP validado o reemplazarlo por `verifyTotp`.

Criterio de salida:

- Enrolamiento genera QR.
- Verificacion acepta TOTP real.
- OTP incorrecto falla.
- Bloqueo de tarjeta sin TOTP validado falla.

### Fase 4 - Tarjetas, casos y reposicion

1. Portar usuarios y tarjetas.
2. Portar bloqueo de tarjetas.
3. Portar creacion/consulta de casos.
4. Portar reposicion.
5. Adaptar prefijos a Mercantil.
6. Asegurar respuestas enmascaradas.

Criterio de salida:

- Usuario demo consultable.
- Tarjetas demo listables.
- Tarjeta bloqueable despues de TOTP.
- Caso creado con prefijo `MC`.
- Reposicion creada solo si la tarjeta esta bloqueada.

### Fase 5 - Solicitudes comerciales

1. Portar `applications`.
2. Cambiar enum `tdc` a `credit_card`.
3. Mantener `account`.
4. Crear seguimiento por `requestId`.

Criterio de salida:

- Solicitud de cuenta creada.
- Solicitud de tarjeta de credito creada.
- Consulta por `requestId` funciona.

### Fase 6 - OCR y reclamos Mercantil

1. Portar la logica actual de `src/mercantilDemo.js` al nuevo esquema modular o mantenerla como servicio.
2. Conservar:
   - `extractTicketData`
   - `evaluateClaimRules`
   - `createClaim`
   - `getClaim`
   - `buildHandoverSummary`
   - `redactSensitive`
3. Integrar estado compartido con casos si aplica.
4. Mantener `mc_*` custom attributes.

Criterio de salida:

- Tests actuales de OCR/reclamos siguen pasando.
- No hay filtracion de datos sensibles.
- Handover summary conserva formato usado por Cognigy.

### Fase 7 - Knowledge AI

1. NO ELIMINAR O ACTUALIZAR EL ACTUAL Knowledge AI

2. Mantener informacion general fuera del backend.

3. Crear o verificar herramienta Knowledge en el AI Agent.

Criterio de salida:

- Preguntas informativas responden desde Knowledge AI.
- Backend solo se usa para acciones y seguimiento.

### Fase 8 - Cognigy Tools

1. Listar proyecto Mercantil con MCP.
2. Listar agente, flow, endpoints y tools existentes.
3. Crear o actualizar tools HTTP segun endpoints objetivo.
4. Evitar duplicar `toolId`.
5. Probar con `talk_to_agent` solo si el LLM esta confirmado.

Criterio de salida:

- Tools apuntan a rutas Mercantil.
- No hay referencias a Bancamiga.
- No hay tools de reset ni Contact Profile cleanup.
- No hay tools omnicanal.

### Fase 9 - Pruebas

Tests unitarios:

- TOTP enroll/verify.
- usuarios.
- tarjetas.
- bloqueo con/sin TOTP.
- casos.
- reposicion.
- solicitudes.
- OCR/reclamos.
- handover summary.
- mascarado de datos sensibles.

Tests HTTP:

- `GET /health`
- `POST /auth/enroll`
- `POST /auth/verify-totp`
- `GET /bank/mercantil/demo/users/:userId/cards`
- `POST /bank/mercantil/demo/cards/:cardId/block`
- `POST /bank/mercantil/demo/cases`
- `POST /bank/mercantil/demo/card-replacement`
- `POST /bank/mercantil/demo/applications`
- `POST /bank/mercantil/demo/ticket/extract`
- `POST /bank/mercantil/demo/claims`

Tests Cognigy:

- consulta informativa.
- bloqueo de tarjeta con TOTP.
- reposicion despues del bloqueo.
- seguimiento de caso.
- solicitud comercial.
- reclamo OCR.

Criterio de salida:

- `npm test` pasa.
- `npm run check` pasa.
- Flujo principal probado desde Cognigy.

### Fase 10 - Limpieza

1. Eliminar referencias textuales a Bancamiga en codigo Mercantil.
2. Verificar que no existan rutas `/bank/demo`.
3. Verificar que no existan rutas `/demo/reset` ni `/demo/state`.
4. Verificar que no existan imports de `cognigyProfiles.service`.
5. Actualizar README o docs operativas de Mercantil.
6. Crear snapshot final de Cognigy despues de validar.

Criterio de salida:

- Backend Mercantil aislado.
- Cognigy Mercantil probado.
- Documentacion actualizada.

## Riesgos

### Mezcla de marca

Riesgo:

- Que respuestas, QR o seeds digan Bancamiga.

Mitigacion:

- Buscar `Bancamiga`, `BEA`, `BM-`, `/bank/demo` antes de cerrar.

### Estado compartido

Riesgo:

- Compartir secretos TOTP o estado demo de Bancamiga.

Mitigacion:

- Archivo `MERCANTIL_TOTP_SECRETS_FILE` propio.
- Store propio.
- Project ID Mercantil propio.

### Seguridad de operaciones

Riesgo:

- Permitir bloqueo sin identidad validada.

Mitigacion:

- Rechazar acciones sensibles si `validatedUsers[userId] !== true`.

### Sobrecargar backend con informacion general

Riesgo:

- Duplicar productos, agencias y horarios en codigo.

Mitigacion:

- Usar Knowledge AI para informacion general.
- Backend solo para operaciones.

### Omnicanalidad accidental

Riesgo:

- Migrar NICE/Webchat/WhatsApp de Bancamiga por copia completa.

Mitigacion:

- No copiar scripts ni docs omnicanal.
- No crear endpoints ni tools para handover NICE.
- Revisar referencias `nice`, `omnichannel`, `whatsapp` si no son estrictamente necesarias.

## Checklist de aceptacion

- [ ] No existe endpoint publico de reset.
- [ ] No existe limpieza de Contact Profile.
- [ ] No hay integracion omnicanal.
- [ ] Todas las rutas operativas usan `/bank/mercantil/demo`.
- [ ] TOTP real reemplaza OTP fijo para operaciones sensibles.
- [ ] Bloqueo de tarjeta requiere identidad validada.
- [ ] Casos usan prefijo Mercantil.
- [ ] Solicitudes comerciales funcionan para cuenta y tarjeta de credito.
- [ ] OCR/reclamos actuales siguen funcionando.
- [ ] Handover summary conserva atributos `mc_*`.
- [ ] Knowledge AI cubre informacion general.
- [ ] Tests pasan.
- [ ] Snapshot Cognigy final creado despues de validar.