Bot de WhatsApp que escucha grupos configurados, levanta los comprobantes (imagen o PDF) que entran, los manda a Claude Vision para extraer monto/banco/fecha, y escribe la fila en una planilla de Google Sheets.

Reacciona ✔ si lo registró, ✖ si falló, ⏳ si quedó como pendiente.

Tiene dashboard web en localhost:3001 con saldos, movimientos, palanca, cuenta corriente y más.

1. Mandá cualquier mensaje al grupo nuevo (cualquier mensaje, no importa).
2. En bot.log aparece: [CHAT DESCONOCIDO] ID: 12036...@g.us (Nombre del Grupo).
3. Andá al tab Config (o editá config.json) y agregá en la sección chats:
   "12036...@g.us": "NOMBRE_OPERADOR"
4. Si el chat es USDT/USD/Cable PURO (sin foto, solo texto), agregalo a chat_meta:
   "12036...@g.us": { "tipo": "usdt" }
5. Reiniciá el bot. Cambios en config.json requieren reinicio.

1. Llega un mensaje con foto/PDF a un grupo del whitelist.
2. El bot busca un ancla en el caption o en los últimos 50 mensajes del chat.
3. Si no hay ancla → ✖.
4. Descarga la media (PDF → primera página como PNG).
5. Manda a Claude Vision: extrae monto, banco, fecha, tipo del comprobante.
6. Cliente y cotización siempre vienen del ancla (lo que diga la foto se descarta).
7. Escribe la fila en INGRESOS o EGRESOS según el tipo. ✔.

Formato típico de ancla:

Cliente: Carlos
🟢 Ingreso
Cotización: 1430
Divisa: ARS
Estado: confirmado

Reacciones del bot:

• ✔ Cargado OK
• ✖ Falló (sin ancla, error de Vision, etc.)
• ⏳ Cargado pero quedó pendiente (falta cotización, spread, cliente canónico, etc.)
• 📌 Ancla válida sin foto adjunta (espera comprobante)
• ❓ Ancla con cliente desconocido
• ⚠️ Ancla sin cotización y sin default
• ✍️ Cierre de caja marcador

Tip: el ancla vale para TODOS los comprobantes que vengan después en el chat, hasta que aparezca otro ancla. No hace falta repetirlo.

Para que el bot trate un comprobante como operación USDT con spread, el ancla debe tener Cliente: Venta USDT o Cliente: Compra USDT.

• Venta = entran pesos (ingreso ARS) + sale USDT.
• Compra = salen pesos (egreso ARS) + entra USDT.

El bot escribe la fila ARS con coti pendiente, y encola un pendiente cotizacion_usdt para que el operador complete el spread desde la web. Al resolver: se calcula cotAjustada y se escribe la fila en CAJA USDT (partida doble).

Cuando no hay comprobante (operación con cliente conocido), el operador puede cargarla solo con texto:

Cliente: venta usdt
🟢
Cotización: 1468
BANCO: FIWIND JUAN
Divisa: usdt
Usdt: 6.252
Ars: $9.178.000

El bot encola un pendiente venta_compra_usdt_texto. El operador confirma desde la web y se cargan las 2 filas (INGRESO ARS + VENTA USDT).

Nota: la coti del ancla (1468) es la al cliente. La coti ajustada (con spread aplicado) es la que va a planilla.

Si el chat tiene chat_meta.tipo seteado a "usdt", "usd" o "cable", el bot procesa los mensajes solo con texto (sin foto). Formato:

USDT puro:

Cliente: Melo
🟢 Ingreso
Banco: Trust Maxi
Cotización: 2,2
Monto: 1500 usdt

Cable: agrega Cotización: 0.18 a su favor (o en contra) + Monto: 1500 usd.

USD efectivo: sin banco, sin spread. Solo cliente + USD: monto.

Cuando el bot no puede completar una carga, encola un pendiente que el operador resuelve desde la tab Pendientes.

• cliente: cliente del ancla no matchea canónico → operador elige o agrega
• banco_persona: comprobante tiene CBU/Alias desconocido → mapear a cuenta
• sin_cotizacion: fila ARS sin coti (sin default en chat_meta)
• cotizacion_usdt: venta/compra USDT — falta completar spread
• sin_ancla: foto sin ancla detectable
• comprobante_fallido: Vision no pudo leer (carga manual)
• venta_compra_usdt_texto: venta USDT por texto puro — confirmar y cargar 2 filas

El banner rojo arriba indica si hay alertas críticas. Click → tab Alertas.

• error_log: error técnico (Vision falló, Sheets desconectado, etc.)
• fallidos_seguidos: 3+ comprobantes ✖ seguidos en un chat
• wa_caido: WhatsApp Web desconectado
• fix_no_funciono: una correción IA no se aplicó
• auth_sin_ready: bot autenticado pero no llega a ready
• grupo_inactivo: chat sin actividad x días
• cliente_fallback_recurrente: cliente cae a "Final" repetidamente
• monto_chico: comprobante con monto < umbral (spam/prueba)
• anomalia_dia_quieto: pasaron horas sin movs
• anomalia_volumen_alto: hoy hubo 3× más movs que el promedio
• comprobante_sospechoso: Vision detectó signos de edición

En el dashboard (home → card "Cotización promedio TT") hay botón "Cierre de caja" que:

1. Muestra preview de comisiones del día por sub-banco (COPTER MATEO, TP JUAN, etc.) con % editable.
2. Permite ajustar la coti que se usa para dolarizar.
3. Checkbox para cerrar la palanca al confirmar.
4. Al confirmar: escribe N filas de "Comisión bancaria" en EGRESOS + cierra palanca si correspondía.

Idempotente: si lo apretás 2 veces el mismo día, no duplica.

Páginas:

• / Saldos — cards de las 7 cajas + cot promedio + spread + evolución.
• /caja Caja Detalle — breakdown por banco/wallet, editor por caja.
• /movimientos Tabla unificada con filtros (caja, ingreso/egreso, fecha, búsqueda), stats por día.
• /actividad Conteo de movimientos por día (gráfico de barras), top 20 clientes y bancos.
• /cuenta-corriente Saldo USD por cliente con desglose por moneda nativa, editar/ajustar saldo.
• /cargar Form manual para agregar movimiento.
• /recuperar Re-procesar comprobantes viejos de chats WhatsApp.
• /simular Calculadora qué-pasaría-si de palanca/spread.
• /health Estado del bot (uptime, WA, IA, alertas, snapshot).
• /settings Editor estructurado del config.json.

Pantalla para procesar comprobantes que no se cargaron en su momento (bot apagado, error, etc.).

1. Tab "Recuperar 📥" → elegí chat por nombre.
2. Opcional: filtrar por fecha específica (date picker).
3. Vista de mensajes con foto / venta USDT texto + estado (procesado / sin procesar).
4. Tildá los que querés y "Procesar seleccionados".
5. Botón "📅 Procesar todos los del día (N)" selecciona todos los del día filtrado de una.

Cap interno: 50 mensajes por batch. Si hay más, repetir.

Sub-tabs:

• Pendientes en el bot: filas en INGRESOS/EGRESOS del bot que NO están en tu Excel. Marcá "Ya cargada" si las cargaste manual.
• Faltantes en el bot: filas en tu Excel que NO están en el bot. Importá una por una o en bloque.

El matching es por fecha + monto + banco (fingerprint con año desde el último fix). Los falsos negativos se marcan ✓ a mano.

Filtros: por fecha exacta (date picker) o últimos N días.

Tab "Chat IA 🤖" — conversación con Claude (Sonnet) con tools del bot. Cuota: 100 llamadas/día.

Tools disponibles:

• listar_pendientes_abiertos
• listar_alertas_abiertas
• listar_filas_recientes
• obtener_clientes_canonicos / obtener_bancos_canonicos
• recuperar_comprobantes_chat (cuesta plata por Vision)
• consultar_actividad (movs por día, top clientes/bancos)
• proponer_accion (sugerencia con botón "Aplicar")

Slash commands: /ayuda, /resumen, /alertas, /pendientes, /aprendido.

Cuando los saldos del histórico se ensucian, podés crear un snapshot inicial con los saldos correctos al día X (fecha_corte). El bot ignora todos los movs anteriores a esa fecha y arranca con los saldos declarados.

Se edita desde el modal "Editar snapshot completo" en la pantalla Caja del dashboard. Soporta las 7 cajas + cuenta corriente por cliente + palanca abierta inicial.

En el chat-bot configurado en config.chat_bot_id:

• !recuperar comprobantes: backfill manual (~300 últimos msgs por chat).
• !pausar / !despausar: silencia el bot.
• !cierre de caja: marcador para el próximo backfill (anchor).

• Ctrl+K (Cmd+K en Mac): abre la búsqueda global en el sidebar — busca clientes, bancos, pendientes y alertas.
• Botón "Refrescar todo" al pie del sidebar: limpia todos los caches y relee Sheets en vivo. Usar después de editar manualmente la planilla.
• SSE en tiempo real: las cards se actualizan solas cada vez que cambia algo (mov, edit, pendiente resuelto, etc.). Throttle de 3s para evitar saturar.

• Comprobante sin reacción: el chat no está en config.chats (ver bot.log "[CHAT DESCONOCIDO]"), o el bot está pausado, o el mensaje es anterior al arranque del bot (usar Recuperar).
• ✖ rojo: abrí bot.log con Bloc de notas, buscá la línea con el msgId. Causas típicas: ancla no detectada, foto ilegible, monto no parseable.
• Sheets no actualiza: verificá que la planilla esté compartida con el email del Service Account. Probá click "Refrescar todo" en el sidebar.
• "Cuota IA agotada": el bot llegó al límite diario (100/día por default). Esperar a medianoche o resetear desde el chat.
• WhatsApp pide QR cada vez: sesión corrupta. Borrar carpeta jano_session/ y re-escanear.
• Bot lento al arrancar: normal, WhatsApp Web tarda ~30-60s en sincronizar. Si tarda más de 4 min, mirar bot.log por errores.
• Saldo incorrecto: capaz hay fechas mal formateadas (número serial vs DD/MM/YYYY). Probá click "Refrescar todo".