Sistema de Pagos

Cobro de la cuota residencial por WhatsApp: el vecino manda su comprobante, el sistema lo lee, lo verifica contra el extracto del banco y le devuelve un recibo numerado. El cobrador registra el efectivo desde su teléfono.

El documento que manda es docs/PLAN.md. Cuando este README y el plan no coincidan, gana el plan.

Recibido no es verificado. Un comprobante leído por OCR no demuestra que el dinero exista. Una transferencia solo queda VERIFICADO cuando un movimiento del extracto del banco la respalda, y un movimiento verifica un solo pago.

Las imágenes no se guardan. Se descargan de WhatsApp, se validan, se les calcula el hash, se procesan con OCR y se descartan. Queda el SHA-256 para reconocer un reenvío exacto, nunca la imagen ni un identificador que permita abrirla.

Cómo funciona

Vecino ──WhatsApp──► Vercel /api/whatsapp/webhook
                       valida la firma, guarda el mensaje, responde 200

GitHub Actions ─► procesar-comprobantes ─► Turso ─► enviar-recibos ─► WhatsApp
               ─► mantenimiento / cierre-mes

Turso es la única fuente de verdad. Vercel solo aloja el webhook y el panel; el trabajo pesado —OCR, conciliación, envíos— corre en GitHub Actions, donde un proceso puede tardar minutos sin que nadie espere una respuesta HTTP.

El efectivo y el extracto del banco entran por otros dos caminos: el cobrador registra el cobro en el panel desde su teléfono, y el tesorero manda el CSV del banco por WhatsApp desde un número autorizado.

Las reglas que manda el plan

Las catorce invariantes están en docs/PLAN.md sección 3. Las que más se notan al usar el sistema:

• La vivienda es Etapa + Bloque + Casa (E1B4C18). Nunca se deduce del teléfono ni del nombre del depositante.
• Una casa está pagada solo con un pago VERIFICADO (transferencia) o EFECTIVO_COBRADO / VERIFICADO (efectivo).
• Septiembre de 2026 es el primer mes de servicio. La deuda anterior no entra como meses ni como pagos: entra una sola vez como ajustes de tipo SALDO_INICIAL.
• La fecha límite es el último día del mes de servicio. La prórroga del mes base —hasta el 14 de octubre de 2026— es única y se guarda como dato del período, no como una excepción escrita en el código.
• El mes que se asigna es el más antiguo desde el alta de la vivienda sin pago VERIFICADO y no reservado por uno pendiente. Nunca un mes futuro.
• El dinero se guarda en centavos enteros.
• Nada se sobrescribe sin evento: toda corrección escribe en eventos, que no se puede editar ni borrar.
• El número de recibo es una secuencia global que nunca se reutiliza. Se anula con motivo y se emite otro; jamás se edita.

La cuota vigente vive en la tabla cuotas con su vigente_desde, así que un mes viejo cuesta lo que costaba entonces. EXPECTED_PAYMENT_AMOUNT es solo el respaldo cuando esa tabla todavía no tiene fila.

Qué está construido

Entrada por WhatsApp. Webhook con verificación de challenge y firma X-Hub-Signature-256, validación de MIME, magic bytes y tamaño antes del OCR, y descarte del reintento de Meta por message_id antes de volver a descargar la media.

Lectura del comprobante. Tesseract.js con modelo español y preprocesamiento con Sharp, todo server-side: el comprobante no se le manda a ningún proveedor de IA. Parser de BAC para banco, depositante, fecha, hora, monto, detalle, referencia, beneficiario y cuenta destino.

Verificación contra el banco. El tesorero manda el CSV del extracto por WhatsApp desde un número que está en usuarios con rol ADMIN o TESORERO. El sistema importa los movimientos sin duplicarlos, manda un resumen y aplica al recibir la confirmación, que expira. Un movimiento verifica un solo pago, y lo garantiza una restricción UNIQUE.

Efectivo. El cobrador entra a /cobros desde su teléfono, busca la casa con filtros de etapa, bloque, casa, estado, método y mes, y marca los meses que paga: el monto no se escribe, sale de la cuota de cada mes. El pago, la reserva de los meses, el recibo y su envío nacen en una sola transacción. La pantalla se instala como app.

Entrega. El cobrador ve su hoja de entrega; el tesorero cuenta y cierra la caja en /admin/caja. Nadie recibe lo que él mismo cobró —lo impide el esquema— y la diferencia entre lo esperado y lo entregado se guarda tal cual.

Recibos. Uno por pago, emitido en la misma transacción que la verificación, enviado con plantilla aprobada de Meta y con una cola que reintenta. /admin/recibos muestra los que no le llegaron al vecino.

Panel. Dashboard mensual, vistas por etapa y bloque, historial por vivienda, bandejas de excepciones, corrección de vivienda y mes sin repetir OCR, y la bandeja de notas del cobrador —que no puede corregir un pago, pero sí dejar escrito lo que vio.

Usuarios. Cada persona entra con su usuario y su rol (ADMIN, TESORERO, COBRADOR). Las claves van con scrypt y la sesión lleva firmado quién es y con qué rol.

This is the beginning of the README. Read the rest at the original. Read the full README ↗