# Servicio conversacional — Etapa 0: cimientos — Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Levantar el servicio conversacional como repositorio independiente que recibe webhooks de WhatsApp, los persiste como conversaciones y mensajes con deduplicación real, y aísla tenants entre sí.

**Architecture:** Servicio NestJS nuevo, con base de datos, tenencia y autenticación propias — sin ninguna tabla ni credencial compartida con el ERP. El código de proveedores de WhatsApp de Novasis (CRM-22) migra acá y se completa con lo que le faltaba: persistencia de `id_externo` para dedupe, descarga de adjuntos desde el *media id*, y procesamiento en cola en lugar de inline. Chatwoot CE se deploya al lado para la etapa 1.

**Tech Stack:** NestJS, Prisma, PostgreSQL, Redis, BullMQ, Jest, Docker Compose. Chatwoot CE (solo el core MIT).

**Spec:** [docs/superpowers/specs/2026-10-17-plataforma-conversacional-erp-design.md](../specs/2026-10-17-plataforma-conversacional-erp-design.md)

> **Nombre provisional.** El repositorio se llama `conversa` y vive en `/var/www/html/proyectos/conversa/`. El spec deja el nombre del producto abierto (§9); cambiarlo es un find/replace sobre este plan antes de empezar.

## Global Constraints

Aplican a todas las tareas.

- **NestJS**, mismo stack que Novasis, para no partir el conocimiento del equipo (D16).
- **Base de datos propia.** Ninguna tabla compartida con el ERP, ninguna credencial cruzada, ningún `import` desde `/var/www/html/proyectos/novasispy-backend-api/src/`. Violar esto vuelve ficción el desacople (§4).
- **Multi-tenencia propia.** Un tenant del servicio es una empresa cliente del servicio. **No** asume el modelo de tenencia de Novasis; el mapeo a `empresa_id` del ERP es configuración del conector y no entra en esta etapa.
- **Enums tipados** en TypeScript y en Prisma para todo discriminador de estado, tipo, categoría o modo. El repo nuevo no arrastra la deuda de `VarChar` + CHECK del CRM de Novasis (§5.5).
- **Migraciones en directorios** `prisma/migrations/YYYYMMDD_nombre/migration.sql`, nunca archivos `.sql` sueltos. El orden de aplicación es **alfabético**, no por dependencia.
- **Prefijo `/api` con versionado URI `/api/v1`**, Swagger en `/docs`.
- **Credenciales de canal siempre enmascaradas** en respuestas de API; nunca salen en claro (§5.7).
- **`VERSION_GRAPH = 'v21.0'`** se mantiene como constante exportada. Subirla es un cambio consciente, no un default flotante.
- **Chatwoot: solo el core MIT.** El directorio `enterprise/` nunca se incluye ni se ejecuta, y no se contrata ningún plan (§5.1).
- **Baileys no hace envíos automáticos.** `permiteAutomaticos()` y `BaileysAutomaticoBloqueadoError` migran con su semántica intacta (§5.7).

## Review Focus

Clases de entrada que el spec implica y que ninguna tarea ejercitaría si no se agregan a propósito. Cada una tiene su test asignado a la tarea que es dueña del código.

1. **Reintento concurrente de Meta con el mismo `id_externo`.** Meta reintenta; dos POST pueden llegar en paralelo, no en secuencia. Un dedupe por `SELECT` y después `INSERT` deja pasar el duplicado. Esperado: un solo mensaje persistido. → Task 7, Step 6.
2. **Webhook para un canal dado de baja.** El `phone_number_id` existe pero el canal tiene `deleted = true`. Esperado: responde 200, descarta, no crea conversación en un canal muerto. → Task 7, Step 8.
3. **Firma válida con cuerpo degenerado.** `entry: []`, o `changes` sin `metadata`, o `messages` ausente. Esperado: 200 sin excepción y sin eventos; reventar hace que Meta reintente para siempre. → Task 7, Step 10.
4. **El mismo teléfono de cliente final en dos tenants.** Es el caso más fácil de filtrar entre tenants. Esperado: cada tenant ve solo su conversación. → Task 6, Step 6.
5. **Media id vencido antes de la descarga.** Meta los vence. Esperado: el mensaje queda legible con su texto y marca de adjunto no disponible; no falla el mensaje entero. → Task 8, Step 5.

---

## File Structure

```
/var/www/html/proyectos/conversa/
├── Dockerfile
├── docker-compose.yml              postgres, redis, chatwoot
├── .github/workflows/ci.yml
├── package.json  tsconfig.json  jest.config.js
├── prisma/schema.prisma
└── src/
    ├── main.ts  app.module.ts
    ├── config/envs.ts              validación Joi
    ├── prisma/prisma.service.ts
    ├── tenants/                    tenant + resolución de contexto
    ├── auth/                       usuarios, JWT, API keys, scopes
    ├── canales/
    │   ├── canales.service.ts      CRUD + cifrado de credenciales
    │   ├── proveedores/            migrados desde Novasis CRM-22
    │   └── webhooks.controller.ts  migrado, sin guards, firma HMAC
    ├── conversaciones/             conversaciones, mensajes, ingesta
    ├── adjuntos/                   media id → almacenamiento
    └── colas/                      registro BullMQ
```

Responsabilidades: `canales/` sabe de proveedores y credenciales y nada de conversaciones; `conversaciones/` sabe de persistencia e ingesta y nada de HTTP; `adjuntos/` es el único que habla con el almacenamiento. Lo que cambia junto vive junto.

---

### Task 1: Scaffold del servicio

**Files:**
- Create: `/var/www/html/proyectos/conversa/package.json`, `tsconfig.json`, `jest.config.js`, `Dockerfile`, `docker-compose.yml`, `.github/workflows/ci.yml`, `.env.example`, `.gitignore`
- Create: `src/main.ts`, `src/app.module.ts`, `src/config/envs.ts`, `src/prisma/prisma.service.ts`, `src/health/health.controller.ts`
- Create: `prisma/schema.prisma`
- Test: `test/health.e2e-spec.ts`

**Interfaces:**
- Consumes: nada.
- Produces: `PrismaService extends PrismaClient implements OnModuleInit`, inyectable en todo el proyecto. `envs` como objeto congelado con `DATABASE_URL`, `REDIS_URL`, `PORT`, `JWT_SECRET`, `CIFRADO_KEY` validados por Joi al arrancar.

- [ ] **Step 1: Escribir el test e2e que falla**

```ts
// test/health.e2e-spec.ts
it('GET /api/v1/health devuelve 200 y ok:true', async () => {
  const res = await request(app.getHttpServer()).get('/api/v1/health');
  expect(res.status).toBe(200);
  expect(res.body).toEqual({ ok: true });
});
```

- [ ] **Step 2: Correr el test y verificar que falla**

Run: `pnpm test:e2e`
Expected: FAIL — no existe el proyecto.

- [ ] **Step 3: Inicializar el proyecto NestJS con Prisma**

`pnpm` como gestor. Prefijo global `/api` y versionado URI `v1` en `main.ts`, igual que Novasis. `ValidationPipe` global con `whitelist`, `forbidNonWhitelisted`, `transform`. Swagger en `/docs`.

- [ ] **Step 4: Implementar `envs` en `src/config/envs.ts`**

Schema Joi que falla al arrancar si falta cualquiera de las cinco variables. `CIFRADO_KEY` debe exigir 32 bytes en hex: una clave corta rompe el cifrado de credenciales de la Task 5 en runtime en lugar de al arrancar.

- [ ] **Step 5: Implementar `PrismaService` y `HealthController`**

`HealthController` devuelve `{ ok: true }` solo si `prisma.$queryRaw` responde; un health que no toca la base miente cuando la base está caída.

- [ ] **Step 6: Escribir `docker-compose.yml` con postgres y redis**

Chatwoot se agrega en la Task 11.

- [ ] **Step 7: Escribir el workflow de CI**

Corre `pnpm lint`, `pnpm test`, `pnpm test:e2e` con postgres y redis como servicios.

- [ ] **Step 8: Correr el test y verificar que pasa**

Run: `pnpm test:e2e`
Expected: PASS

- [ ] **Step 9: Commit**

```bash
git init && git add -A
git commit -m "feat: scaffold del servicio conversacional"
```

---

### Task 2: Tenencia

**Files:**
- Modify: `prisma/schema.prisma`
- Create: `prisma/migrations/20261017_tenants/migration.sql`
- Create: `src/tenants/tenants.module.ts`, `tenants.service.ts`, `tenant-context.ts`
- Test: `src/tenants/tenants.service.spec.ts`

**Interfaces:**
- Consumes: `PrismaService` (Task 1).
- Produces: modelo `tenants { id, nombre, slug, estado: tenant_estado, deleted, creado_en }` con `enum tenant_estado { ACTIVO SUSPENDIDO }`. `TenantContext` con `getTenantId(): string` y `runWith<T>(tenantId: string, fn: () => Promise<T>): Promise<T>`, implementado sobre `AsyncLocalStorage`. Toda consulta de tenant en adelante filtra por `getTenantId()`.

- [ ] **Step 1: Escribir los tests que fallan**

```ts
it('runWith expone el tenant a getTenantId dentro del callback', ...)
it('getTenantId lanza fuera de runWith', ...)   // falla ruidosa, no undefined silencioso
it('runWith anidado no filtra el tenant externo al interno', ...)
```

- [ ] **Step 2: Correr y verificar que fallan**

Run: `pnpm test src/tenants`
Expected: FAIL — `TenantContext` no existe.

- [ ] **Step 3: Agregar el modelo `tenants` y su enum al schema, y crear la migración**

Directorio con fecha, SQL idempotente (`IF NOT EXISTS`, `DO $$ ... EXCEPTION WHEN duplicate_object THEN NULL; END $$`).

- [ ] **Step 4: Implementar `TenantContext` en `src/tenants/tenant-context.ts`**

`AsyncLocalStorage<{ tenantId: string }>`. `getTenantId()` lanza si no hay store: un `undefined` silencioso acá se convierte en una consulta sin filtro de tenant, que es la peor falla posible de este servicio.

- [ ] **Step 5: Implementar `TenantsService` con `crear`, `porSlug`, `porId`**

- [ ] **Step 6: Correr y verificar que pasan**

Run: `pnpm test src/tenants`
Expected: PASS

- [ ] **Step 7: Commit**

```bash
git add prisma src/tenants && git commit -m "feat: tenencia propia del servicio"
```

---

### Task 3: Autenticación de usuarios

**Files:**
- Modify: `prisma/schema.prisma`
- Create: `prisma/migrations/20261018_usuarios/migration.sql`
- Create: `src/auth/auth.module.ts`, `auth.service.ts`, `jwt.strategy.ts`, `dto/login.dto.ts`, `get-user.decorator.ts`
- Test: `src/auth/auth.service.spec.ts`, `test/auth.e2e-spec.ts`

**Interfaces:**
- Consumes: `PrismaService`, `TenantsService`, `TenantContext`.
- Produces: modelo `usuarios { id, tenant_id, email, password_hash, rol: usuario_rol, deleted }` con `enum usuario_rol { ADMIN AGENTE }`. `AuthService.login(email, password): Promise<{ access_token, usuario }>`. `@GetUser()` devuelve `{ id, tenant_id, rol, email }`. Guard `AuthGuard('jwt')` disponible globalmente.

- [ ] **Step 1: Escribir los tests que fallan**

```ts
it('login con credenciales válidas devuelve access_token', ...)
it('login con password incorrecta lanza UnauthorizedException', ...)
it('login de un tenant SUSPENDIDO lanza UnauthorizedException', ...)
it('el payload del JWT incluye tenant_id', ...)
```

- [ ] **Step 2: Correr y verificar que fallan**

Run: `pnpm test src/auth`
Expected: FAIL

- [ ] **Step 3: Agregar `usuarios` + enum al schema y crear la migración**

`@@unique([tenant_id, email])` — el mismo email puede existir en dos tenants.

- [ ] **Step 4: Implementar `AuthService.login` y `JwtStrategy`**

`bcrypt` para el hash. El payload del JWT lleva `tenant_id`, y `JwtStrategy.validate` es lo que alimenta `TenantContext` en cada request autenticado.

- [ ] **Step 5: Correr y verificar que pasan**

Run: `pnpm test src/auth && pnpm test:e2e`
Expected: PASS

- [ ] **Step 6: Commit**

```bash
git add prisma src/auth && git commit -m "feat: autenticación de usuarios por tenant"
```

---

### Task 4: API keys con scopes, rate limiting y auditoría

**Files:**
- Modify: `prisma/schema.prisma`
- Create: `prisma/migrations/20261019_api_keys/migration.sql`
- Create: `src/auth/api-keys.service.ts`, `api-key.guard.ts`, `require-scope.decorator.ts`, `api-keys.controller.ts`
- Test: `src/auth/api-keys.service.spec.ts`, `src/auth/api-key.guard.spec.ts`

**Interfaces:**
- Consumes: `PrismaService`, `TenantContext`.
- Produces: modelo `api_keys { id, tenant_id, nombre, key_hash, scopes: api_scope[], revocada_en, ultimo_uso_en }` y `api_key_audit { id, api_key_id, ruta, metodo, status, creado_en }`, con `enum api_scope { MENSAJES_ENVIAR MENSAJES_LEER CANALES_LEER WEBHOOKS_ADMIN }`. `ApiKeysService.crear(nombre, scopes): Promise<{ id, plaintext }>` (el plaintext se devuelve una sola vez), `validar(plaintext): Promise<ApiKeyContext | null>`, `revocar(id)`. `@RequireScope(...scopes: api_scope[])` + `ApiKeyGuard`.

> Esta tarea existe para **no repetir** los cuatro defectos verificados de `src/cartera/api-publica/` en Novasis: sin rate limiting, sin idempotencia, scopes chequeados a mano en cada método, y `auditar()` sin ningún llamador (§6.4). Las piezas 4 y 5 se construyen sobre esto.

- [ ] **Step 1: Escribir los tests que fallan**

```ts
it('validar acepta la key recién creada y devuelve su tenant y scopes', ...)
it('validar rechaza una key revocada', ...)
it('validar rechaza una key inexistente sin filtrar si existía', ...)
it('el guard rechaza con 403 cuando falta el scope requerido', ...)
it('el guard registra en api_key_audit cada request, incluso los rechazados', ...)
it('ThrottlerGuard limita por api_key_id, no por IP', ...)
```

- [ ] **Step 2: Correr y verificar que fallan**

Run: `pnpm test src/auth/api-key`
Expected: FAIL

- [ ] **Step 3: Agregar `api_keys`, `api_key_audit` y el enum al schema, y crear la migración**

- [ ] **Step 4: Implementar `ApiKeysService`**

La key se guarda **solo hasheada**; `validar` compara hash. El prefijo visible de la key se almacena aparte para poder identificarla en la UI sin guardar el secreto.

- [ ] **Step 5: Implementar `ApiKeyGuard` y `@RequireScope`**

El guard lee los scopes requeridos por `Reflector` desde el decorador. **Un endpoint protegido por `ApiKeyGuard` sin `@RequireScope` debe fallar**, no pasar: es lo que convierte un scope olvidado en un test roto en lugar de un agujero silencioso.

- [ ] **Step 6: Configurar `ThrottlerGuard` con el `api_key_id` como discriminante**

- [ ] **Step 7: Correr y verificar que pasan**

Run: `pnpm test src/auth`
Expected: PASS

- [ ] **Step 8: Commit**

```bash
git add prisma src/auth && git commit -m "feat: api keys con scopes, rate limiting y auditoría"
```

---

### Task 5: Canales y migración de los proveedores de WhatsApp

**Files:**
- Modify: `prisma/schema.prisma`
- Create: `prisma/migrations/20261020_canales/migration.sql`
- Create: `src/canales/canales.module.ts`, `canales.service.ts`, `dto/canal.dto.ts`
- Create: `src/common/cifrado.util.ts`
- Migrate: desde `/var/www/html/proyectos/novasispy-backend-api/src/crm/canales/whatsapp/` → `src/canales/proveedores/`: `whatsapp-provider.interface.ts`, `meta-cloud.provider.ts`, `evolution.provider.ts`, `whatsapp-provider.factory.ts` y sus specs.
- Test: `src/canales/canales.service.spec.ts`, `src/canales/proveedores/meta-cloud.provider.spec.ts` (migrado)

**Interfaces:**
- Consumes: `PrismaService`, `TenantContext`, `envs.CIFRADO_KEY`.
- Produces: modelo `canales { id, tenant_id, tipo: canal_tipo, proveedor: canal_proveedor, identificador, identificador_externo, credenciales_cifradas, webhook_verify_token, deleted }` con `enum canal_tipo { WHATSAPP SMS EMAIL WEBHOOK }` y `enum canal_proveedor { META_CLOUD EVOLUTION_CLOUD EVOLUTION_BAILEYS }`. `CanalesService.porIdentificadorExterno(id)`, `.porVerifyToken(token)`, `.crear(dto)`, `.findAll()` — las tres primeras devuelven credenciales **descifradas** para uso interno; `findAll` las devuelve **enmascaradas**. `permiteAutomaticos(proveedor): boolean` y `BaileysAutomaticoBloqueadoError` migran con su semántica intacta.

> Los `ProveedorWhatsApp` del código migrado pasan de union de strings a `enum canal_proveedor` de Prisma (Global Constraints). Los specs migrados hay que ajustarlos a los nuevos nombres; **su cobertura no se recorta**.

- [ ] **Step 1: Migrar los archivos de proveedor y sus specs, ajustando imports y el enum**

`VERSION_GRAPH = 'v21.0'` se mantiene exportada.

- [ ] **Step 2: Correr los specs migrados y verificar que fallan**

Run: `pnpm test src/canales/proveedores`
Expected: FAIL — falta `cifrado.util` y el modelo `canales`.

- [ ] **Step 3: Escribir los tests de `CanalesService` que fallan**

```ts
it('crear cifra las credenciales: credenciales_cifradas no contiene el access_token en claro', ...)
it('porIdentificadorExterno devuelve las credenciales descifradas', ...)
it('findAll enmascara las credenciales', ...)
it('porIdentificadorExterno no devuelve canales de otro tenant', ...)
it('crear rechaza un proveedor que no corresponde al tipo de canal', ...)
```

- [ ] **Step 4: Agregar `canales` + enums al schema y crear la migración**

`@@unique([identificador_externo])` donde no sea null: dos canales con el mismo `phone_number_id` hacen que el ruteo del webhook sea ambiguo.

- [ ] **Step 5: Implementar `cifrado.util.ts`**

AES-256-GCM con `envs.CIFRADO_KEY`. Exporta también `firmaCoincide(a, b): boolean` con comparación en tiempo constante — la usa `MetaCloudProvider` para validar el HMAC y una comparación con `===` ahí es un oráculo de temporización.

- [ ] **Step 6: Implementar `CanalesService`**

- [ ] **Step 7: Correr todo y verificar que pasa**

Run: `pnpm test src/canales`
Expected: PASS, incluidos los specs migrados.

- [ ] **Step 8: Commit**

```bash
git add prisma src/canales src/common && git commit -m "feat: canales con credenciales cifradas; migra proveedores de CRM-22"
```

---

### Task 6: Conversaciones y mensajes

**Files:**
- Modify: `prisma/schema.prisma`
- Create: `prisma/migrations/20261021_conversaciones/migration.sql`
- Create: `src/conversaciones/conversaciones.module.ts`, `conversaciones.service.ts`, `mensajes.service.ts`
- Test: `src/conversaciones/conversaciones.service.spec.ts`

**Interfaces:**
- Consumes: `PrismaService`, `TenantContext`.
- Produces: modelos `contactos { id, tenant_id, telefono_e164, nombre, verificado_hasta, cliente_ref }`, `conversaciones { id, tenant_id, canal_id, contacto_id, estado: conversacion_estado, asignado_a, ultimo_mensaje_en }`, `mensajes { id, tenant_id, conversacion_id, direccion: mensaje_direccion, tipo: mensaje_tipo, texto, adjunto_url, adjunto_mime, id_externo, estado: mensaje_estado, error, fecha }`. Enums: `conversacion_estado { ABIERTA BOT HUMANO CERRADA }`, `mensaje_direccion { ENTRANTE SALIENTE }`, `mensaje_tipo { TEXTO ADJUNTO OTRO }`, `mensaje_estado { ENCOLADO ENVIADO ENTREGADO LEIDO FALLIDO }`.
  `ConversacionesService.resolverOAbrir(canal_id, telefono, nombre): Promise<Conversacion>`, `MensajesService.registrarEntrante(conversacion_id, evento): Promise<Mensaje | null>` (null si era duplicado), `MensajesService.actualizarEstado(id_externo, estado, error?)`.

> `cliente_ref` en `contactos` es la referencia opaca a la identidad comercial del ERP (§5.6). En esta etapa se modela y queda null; la resolución es de la etapa 2. `verificado_hasta` es el estado de verificación por OTP (D8) y se usa en la etapa 3.

- [ ] **Step 1: Escribir los tests que fallan**

```ts
it('resolverOAbrir crea contacto y conversación la primera vez', ...)
it('resolverOAbrir reusa la conversación ABIERTA existente del mismo contacto y canal', ...)
it('resolverOAbrir abre una nueva si la anterior está CERRADA', ...)
it('registrarEntrante persiste el mensaje y actualiza ultimo_mensaje_en', ...)
it('actualizarEstado pasa el mensaje a ENTREGADO por su id_externo', ...)
it('dos tenants con el mismo telefono_e164 tienen contactos y conversaciones separados', ...)  // Review Focus 4
```

- [ ] **Step 2: Correr y verificar que fallan**

Run: `pnpm test src/conversaciones`
Expected: FAIL

- [ ] **Step 3: Agregar los tres modelos y los cuatro enums al schema, y crear la migración**

Dos constraints que importan: `@@unique([tenant_id, telefono_e164])` en `contactos`, y `@@unique([tenant_id, id_externo])` en `mensajes` — este último es el que hace posible el dedupe de la Task 7 a nivel de base y no de aplicación.

- [ ] **Step 4: Implementar `ConversacionesService.resolverOAbrir`**

- [ ] **Step 5: Implementar `MensajesService.registrarEntrante` y `.actualizarEstado`**

`registrarEntrante` devuelve `null` cuando el `id_externo` ya existía, en lugar de lanzar: el llamador necesita distinguir "duplicado" de "error".

- [ ] **Step 6: Correr y verificar que pasan**

Run: `pnpm test src/conversaciones`
Expected: PASS

- [ ] **Step 7: Commit**

```bash
git add prisma src/conversaciones && git commit -m "feat: modelo de conversaciones, contactos y mensajes"
```

---

### Task 7: Webhook e ingesta con deduplicación

**Files:**
- Create: `src/conversaciones/ingesta.service.ts`
- Migrate: desde Novasis `src/crm/canales/webhooks.controller.ts` → `src/canales/webhooks.controller.ts`
- Test: `src/conversaciones/ingesta.service.spec.ts`, `test/webhooks.e2e-spec.ts`

**Interfaces:**
- Consumes: `CanalesService.porIdentificadorExterno`, `.porVerifyToken` (Task 5), `ConversacionesService.resolverOAbrir`, `MensajesService.registrarEntrante` (Task 6), el factory de proveedores (Task 5).
- Produces: `IngestaService.procesar(canal, eventos: WebhookEvento[]): Promise<{ mensajes: number, estados: number, duplicados: number }>`.

> El controller migra con su propiedad más importante intacta: **siempre responde 200 salvo firma inválida**. Meta reintenta ante cualquier otra respuesta, y con varios reintentos un error nuestro se convierte en mensajes duplicados para el cliente final. La firma inválida sí corta antes de tocar nada.
>
> Esta tarea cierra lo que CRM-22 dejó pendiente: hoy el webhook de Novasis solo cuenta eventos en el log.

- [ ] **Step 1: Escribir los tests de ingesta que fallan**

```ts
it('procesar crea conversación y mensaje para un evento de clase mensaje', ...)
it('procesar actualiza el estado del mensaje para un evento de clase estado', ...)
it('procesar cuenta como duplicado un id_externo ya persistido', ...)
```

- [ ] **Step 2: Correr y verificar que fallan**

Run: `pnpm test src/conversaciones/ingesta`
Expected: FAIL

- [ ] **Step 3: Implementar `IngestaService.procesar`**

Recorre los eventos y despacha por `clase`. El dedupe se apoya en que `registrarEntrante` devuelve `null`, no en consultar antes.

- [ ] **Step 4: Migrar el controller y escribir el test e2e del handshake**

```ts
it('GET /crm/webhooks/whatsapp/meta devuelve el hub.challenge en texto plano', ...)
it('GET rechaza con 401 un verify_token que no corresponde a ningún canal', ...)
```

Devolver JSON en el handshake hace que Meta rechace la suscripción. El `challenge` va en texto plano.

- [ ] **Step 5: Escribir el test e2e del POST y de la firma**

```ts
it('POST con firma válida persiste el mensaje y responde 200', ...)
it('POST con firma inválida responde 401 y no persiste nada', ...)
it('POST sin la cabecera X-Hub-Signature-256 responde 401', ...)
```

La firma se calcula sobre el cuerpo **crudo**: recalcularla sobre el JSON reparseado y reserializado hace fallar firmas válidas por diferencias de orden de claves o de escape. El `rawBody` tiene que estar habilitado en `main.ts`.

- [ ] **Step 6: Escribir el test de reintento concurrente** *(Review Focus 1)*

```ts
it('dos POST idénticos en paralelo persisten un solo mensaje', async () => {
  await Promise.all([postWebhook(payload), postWebhook(payload)]);
  expect(await contarMensajes(idExterno)).toBe(1);
});
```

- [ ] **Step 7: Verificar que el dedupe aguanta la concurrencia**

El unique de `[tenant_id, id_externo]` (Task 6) es lo que lo garantiza: `registrarEntrante` tiene que capturar la violación de constraint y devolver `null`, no consultar primero. Si el test del Step 6 falla, el arreglo va acá y no en el test.

- [ ] **Step 8: Escribir el test del canal dado de baja** *(Review Focus 2)*

```ts
it('POST para un canal con deleted=true responde 200 y no crea conversación', ...)
```

- [ ] **Step 9: Escribir el test del `phone_number_id` desconocido**

```ts
it('POST para un phone_number_id sin canal responde 200 y descarta', ...)
```

- [ ] **Step 10: Escribir los tests de cuerpo degenerado** *(Review Focus 3)*

```ts
it.each([
  ['entry vacío', { entry: [] }],
  ['changes sin metadata', { entry: [{ changes: [{ value: {} }] }] }],
  ['value sin messages ni statuses', { entry: [{ changes: [{ value: { metadata: { phone_number_id: 'x' } } }] }] }],
])('POST con %s responde 200 sin excepción', ...)
```

- [ ] **Step 11: Correr todo y verificar que pasa**

Run: `pnpm test && pnpm test:e2e`
Expected: PASS

- [ ] **Step 12: Commit**

```bash
git add src/canales src/conversaciones test && git commit -m "feat: ingesta de webhooks con dedupe por id_externo"
```

---

### Task 8: Descarga de adjuntos

**Files:**
- Create: `src/adjuntos/adjuntos.module.ts`, `adjuntos.service.ts`
- Modify: `src/conversaciones/ingesta.service.ts`
- Test: `src/adjuntos/adjuntos.service.spec.ts`

**Interfaces:**
- Consumes: `CanalesService.porIdentificadorExterno` (para el `access_token`), `MensajesService`.
- Produces: `AdjuntosService.descargar(canal, mediaId): Promise<{ url: string, mime: string } | null>` — `null` cuando Meta no lo entrega.

> `MetaCloudProvider` entrega un **media id**, no una URL: la descarga es un paso aparte que necesita el token. Hoy ese id queda guardado tal cual en `adjunto_url` (§5.5).

- [ ] **Step 1: Escribir los tests que fallan**

```ts
it('descargar resuelve el media id a una URL de almacenamiento', ...)
it('descargar devuelve null cuando Meta responde 404', ...)
it('descargar devuelve null cuando Meta responde 401 por token vencido', ...)
```

- [ ] **Step 2: Correr y verificar que fallan**

Run: `pnpm test src/adjuntos`
Expected: FAIL

- [ ] **Step 3: Implementar `AdjuntosService.descargar`**

Dos llamadas a Graph API: `GET /{media-id}` devuelve una URL temporal, y la descarga de esa URL requiere el mismo `Authorization: Bearer`. Nunca lanza: devuelve `null` y registra.

- [ ] **Step 4: Conectar la descarga a la ingesta**

Cuando el evento trae `adjunto_url` (que es el media id), se descarga y se guarda la URL real.

- [ ] **Step 5: Escribir el test de media id vencido** *(Review Focus 5)*

```ts
it('un mensaje con adjunto cuyo media id venció se persiste con su texto y adjunto_url null', ...)
```

El mensaje tiene que quedar legible. Perder el mensaje entero porque Meta venció un archivo es peor que perder el archivo.

- [ ] **Step 6: Correr y verificar que pasa**

Run: `pnpm test src/adjuntos src/conversaciones`
Expected: PASS

- [ ] **Step 7: Commit**

```bash
git add src/adjuntos src/conversaciones && git commit -m "feat: descarga de adjuntos desde el media id de Meta"
```

---

### Task 9: Procesamiento en cola

**Files:**
- Create: `src/colas/colas.module.ts`, `src/colas/ingesta.processor.ts`
- Modify: `src/canales/webhooks.controller.ts`
- Test: `src/colas/ingesta.processor.spec.ts`, `test/webhooks.e2e-spec.ts`

**Interfaces:**
- Consumes: `IngestaService.procesar`, `CanalesService`.
- Produces: cola `ingesta` registrada en BullMQ. `IngestaProcessor` consume jobs `{ canal_id, eventos }`.

> El webhook pasa a encolar y responder 200 de inmediato. Procesar inline funciona hasta que la descarga de un adjunto tarda y Meta da timeout — y un timeout es un reintento, que es un duplicado.

- [ ] **Step 1: Escribir los tests que fallan**

```ts
it('el processor procesa un job y persiste los mensajes', ...)
it('un job que falla se reintenta con backoff', ...)
it('un job que agota reintentos queda en la cola de fallidos, no se pierde', ...)
```

- [ ] **Step 2: Correr y verificar que fallan**

Run: `pnpm test src/colas`
Expected: FAIL

- [ ] **Step 3: Registrar la cola `ingesta` y su conexión Redis**

- [ ] **Step 4: Implementar `IngestaProcessor`**

- [ ] **Step 5: Modificar el controller para encolar en vez de procesar inline**

La validación de firma se mantiene **sincrónica, antes de encolar**: encolar un payload sin verificar es inyectar mensajes en la cola.

- [ ] **Step 6: Actualizar el e2e para esperar el drenado de la cola**

Los tests de la Task 7 siguen valiendo; lo que cambia es que esperan a que la cola drene antes de verificar la persistencia.

- [ ] **Step 7: Correr todo y verificar que pasa**

Run: `pnpm test && pnpm test:e2e`
Expected: PASS

- [ ] **Step 8: Commit**

```bash
git add src/colas src/canales test && git commit -m "feat: ingesta asíncrona por cola BullMQ"
```

---

### Task 10: Chatwoot en el compose

**Files:**
- Modify: `docker-compose.yml`
- Create: `docs/deploy-chatwoot.md`
- Test: `test/chatwoot-health.e2e-spec.ts`

**Interfaces:**
- Consumes: nada del servicio.
- Produces: Chatwoot CE accesible en `http://localhost:3000`, con su propia base de datos. La integración como *API channel* (D2) es de la etapa 1; acá solo se levanta.

- [ ] **Step 1: Escribir el test de health que falla**

```ts
it('Chatwoot responde en /api', async () => {
  const res = await fetch(`${process.env.CHATWOOT_URL}/api`);
  expect(res.status).toBe(200);
});
```

- [ ] **Step 2: Correr y verificar que falla**

Run: `pnpm test:e2e test/chatwoot-health`
Expected: FAIL — no hay servicio levantado.

- [ ] **Step 3: Agregar Chatwoot al compose**

Imagen oficial de Chatwoot CE, postgres y redis propios — **no** los del servicio: compartir la base acopla dos aplicaciones que deben poder versionarse por separado.

- [ ] **Step 4: Documentar el deploy y la restricción de licencia**

`docs/deploy-chatwoot.md` deja escrito que se usa **solo el core MIT**, que el directorio `enterprise/` no se incluye ni se ejecuta, y que no se contrata ningún plan de Chatwoot. Es la restricción que vuelve revendible al producto (§5.1); si queda solo en el spec, alguien va a habilitar una feature enterprise sin saber lo que implica.

- [ ] **Step 5: Correr y verificar que pasa**

Run: `docker compose up -d && pnpm test:e2e test/chatwoot-health`
Expected: PASS

- [ ] **Step 6: Commit**

```bash
git add docker-compose.yml docs test && git commit -m "feat: Chatwoot CE en el compose"
```

---

## Cierre de la etapa

Al terminar, el servicio: arranca con un comando, aísla tenants, autentica usuarios y API keys con scopes verificados por decorador, recibe webhooks de Meta validando firma, persiste conversaciones y mensajes sin duplicar ante reintentos, descarga adjuntos, procesa en cola, y tiene Chatwoot al lado.

**Lo que NO hace todavía, a propósito:** no envía mensajes (etapa 1), no habla con el ERP (etapa 2), no tiene agente (etapa 3), no tiene Embedded Signup (etapa 4).

**Pendiente de coordinación con Novasis, fuera de este plan:** eliminar `src/crm/canales/**` del repo del ERP una vez que este servicio esté en producción, y actualizar `docs/plan-crm-360.md` según §11 del spec. Hacerlo antes deja a Novasis sin su adaptador; no hacerlo nunca deja dos implementaciones divergentes.
