factura-mensual

name	factura-mensual
description	Ejecuta la facturacion mensual via init-fact-mensual.php con dry-run obligatorio, validacion de zona muerta (dias 10-20), confirmacion explicita y reporte del batch_id para rollback. Usar cuando el usuario diga "facturar", "correr facturacion mensual", "generar facturas del mes" o similar.

Skill: factura-mensual

Ejecuta la facturacion mensual. Este script mueve dinero (crea facturas con saldo). Toda ejecucion en modo --ejecutar requiere aprobacion explicita del usuario.

Multi-tenant: SIEMPRE una empresa por corrida

El script factura una sola empresa (--empresa-id=N, obligatorio en --ejecutar). Esto aisla el batch por tenant y evita facturar clientes de otros ISPs.

• Sin --empresa-id (dry-run o pipe/cron) el script lista las empresas con sus afiliados facturables y aborta (no factura nada). Usa esto primero para confirmar a qué empresa vas y cuántos clientes tiene.
• Pregunta/confirma con el usuario qué empresa se va a facturar antes de ejecutar. Para el ISP de Omar (AG) es --empresa-id=1.
• La deteccion de duplicados (3 capas) y el fact_batch quedan scopeados por empresa: facturar empresa 1 no bloquea facturar otra empresa el mismo periodo.

cd /var/www/ispexperts && php init-fact-mensual.php   # lista empresas y facturables, no factura

Selector interactivo multi-empresa: php init-fact-mensual.php --ejecutar (sin --empresa-id, en terminal) abre un selector con barra espaciadora — todas desmarcadas por defecto, flechas/jk para mover, ESPACIO para marcar, a todas, ENTER confirma, q cancela. Antes de generar muestra la lista de empresas elegidas con sus facturables y pide confirmación REAL. Genera un batch independiente por empresa (rollback aislado). En pipe/cron (sin terminal) este modo aborta y exige --empresa-id=N. Como esto es interactivo (raw TTY), el usuario debe correrlo él mismo con ! php init-fact-mensual.php --ejecutar — Claude no puede manejar el selector por SSH no-interactivo; Claude usa la vía --empresa-id=N.

Reglas de periodo automatico

Dia del mes	Comportamiento
1-9	Factura el mes actual
10-20	Zona muerta: el script aborta. Solo se puede forzar con --periodo=NombreMes
21-31	Factura el mes siguiente

Paso 1 — Dry-run obligatorio

Siempre empieza con dry-run de la empresa elegida, sin importar lo que pida el usuario:

cd /var/www/ispexperts && php init-fact-mensual.php --empresa-id=N

(Si no sabes la empresa, corre primero sin --empresa-id para ver el listado.)

Si el dia esta en zona muerta (10-20) y el usuario no especifico periodo, el dry-run abortara — informa al usuario y pregunta si quiere forzar con un periodo especifico.

Paso 2 — Mostrar y confirmar

Resume al usuario:

• Periodo que se va a facturar
• Cantidad de afiliados a procesar (cuenta lineas / "se crearan N facturas" del output)
• Cualquier warning del dry-run

Pide confirmacion explicita: "ejecuta", "si", "aprobado". No ejecutes sin esto.

Paso 3 — Ejecutar

Sin override de periodo:

cd /var/www/ispexperts && php init-fact-mensual.php --empresa-id=N --ejecutar

Con periodo forzado (zona muerta o ajuste manual):

cd /var/www/ispexperts && php init-fact-mensual.php --empresa-id=N --ejecutar --periodo=Abril

Periodos validos: Enero, Febrero, Marzo, Abril, Mayo, Junio, Julio, Agosto, Septiembre, Octubre, Noviembre, Diciembre (capitalizados, en español).

Paso 4 — Reportar batch_id

El script imprime un batch_id al final. Reportalo al usuario explicitamente:

Batch creado: #N. Para revertir: /rollback-factura (o php rollback-fact-mensual.php N).

Guarda mentalmente este batch_id por si el usuario pide rollback en la misma conversacion.

Reglas estrictas

• Nunca ejecutes con --ejecutar sin pasar primero por dry-run y obtener aprobacion.
• Nunca ejecutes sin --empresa-id: confirma con el usuario a qué empresa va. El script aborta si falta en --ejecutar.
• Nunca corras el script desde HTTP: solo CLI (el script bloquea SAPI != cli con 403).
• Si el usuario pide facturar fuera del periodo natural (ej. dia 12 sin override), confirma dos veces y exige --periodo= explicito.
• Si el script falla a mitad, no lo reejecutes: muestra el output completo y sugiere correr list-fact-batches.php para ver el estado.