# ICYLAB Billing v7.0.0 — puesta en producción

## Estado y decisión de integración

- La recepción de DTE usa FACTO REST V1 y mantiene correctamente la dirección financiera: recibido = CxP; emitido = CxC.
- Las facturas de Chilexpress permanecen pagadas. Esta entrega no altera documentos, pagos ni cobros históricos.
- La guía 1338 vinculada a la factura 1261 no es modificada por esta migración.
- La colección técnica entregada documenta emisión mediante `POST /V1/documents`, preview, consulta por `GET /documents/{document_id}` e inbox. Por eso REST V1 es el transporte productivo implementado tanto para emitir como para consultar.
- La captura del portal confirma que la credencial denominada “SOAP” tiene permisos de emisión para facturas, boletas, guías y notas. No confirma un WSDL, operaciones ni esquema SOAP. La configuración incluye campos SOAP separados y deshabilitados; no se realizan llamadas SOAP hasta recibir y homologar el contrato oficial.
- No se necesita una API adicional propia para operar el módulo: los endpoints internos PHP actúan como capa segura entre la UI y FACTO. Nunca se exponen credenciales al navegador.

## Cambios incluidos

- Emisión controlada en sandbox y producción de factura afecta/exenta, boleta nominativa afecta/exenta, factura de exportación, guía y notas nacionales/de exportación.
- Preview obligatorio, verificación posterior por `document_id`, idempotencia y estados de resultado remoto incierto.
- Tres gates productivos: lectura, finanzas y emisión; confirmación reforzada `EMITIR PRODUCCION`.
- Acciones masivas en Documentos emitidos, CxC, CxP, Aging clientes y Aging proveedores: XLSX filtrado/seleccionado y sincronización o recálculo seguro de estados.
- Los pagos y cobros masivos existentes se mantienen. No se permite marcar arbitrariamente un saldo como pagado.
- CSRF en todo Billing, cookies de sesión seguras, regeneración de sesión y parametrización del refresh token de Google.
- Auditoría de actualizaciones masivas en `billing_bulk_action_logs`.

## Plan de cuatro etapas

### 1. Instalación segura y credenciales rotadas

1. Respaldar archivos y base de datos.
2. Descomprimir el paquete fuera del document root.
3. Copiar `core/private_config.example.php` fuera del document root, completar credenciales rotadas y definir `ICYLAB_PRIVATE_CONFIG_PATH`.
4. Mantener `ICYLAB_FACTO_ENVIRONMENT='sandbox'` y los tres gates productivos en `false`.
5. Desplegar y migrar:

```bash
bash ops/deploy_billing_readiness.sh \
  --app-root /home/USUARIO/app.icylab.cl \
  --package-root /ruta/ICYLAB_Billing_v7.0.0 \
  --backup-dir /home/USUARIO/backups/billing-v7-$(date +%Y%m%d-%H%M%S) \
  --php-bin /usr/local/bin/php \
  --db-defaults-file /home/USUARIO/.my.cnf \
  --db-name icylab_app
```

### 2. Homologación REST y lectura productiva

1. Rotar ambas credenciales REST y, si corresponde, la credencial llamada SOAP.
2. Abrir sólo `ICYLAB_BILLING_PRODUCTION_READ_ENABLED=true`.
3. Ejecutar:

```bash
php scripts/billing_production_preflight.php --env=production --stage=readiness --strict --fix-dirs --json=/ruta/evidencia/preflight.json
php scripts/facto_production_probe.php --env=production --scope=full --confirm=READ_ONLY_PRODUCTION --json=/ruta/evidencia/facto.json
php cron/sync_facto_customers.php --env=production --per-page=100 --force=false
php cron/sync_facto_documents.php --env=production --from=2026-01-01 --to=2026-07-14 --per-page=100 --fetch-files=false
php cron/sync_facto_inbox_documents.php --env=production --per-page=100 --fetch-files=false
```

Validar RUT emisor/receptor, tipos FACTO/SII, folios, totales, PDF/XML, vínculos de clientes/proveedores y ausencia de duplicados.

### 3. Finanzas y canary de emisión

1. Abrir `ICYLAB_BILLING_PRODUCTION_FINANCE_ENABLED=true` y validar CxC, CxP, pagos/cobros masivos, aging y XLSX.
2. Otorgar `billing.issue.production` sólo a un supervisor y un operador canary.
3. Abrir `ICYLAB_BILLING_PRODUCTION_ISSUE_ENABLED=true` durante una ventana supervisada.
4. Ejecutar el preflight `--stage=pilot`.
5. Emitir una factura de bajo riesgo ya aprobada internamente: preview, comparación visual, `EMITIR PRODUCCION`, consulta posterior y descarga PDF/XML.
6. Confirmar en FACTO/SII el folio y estado antes de ampliar tipos documentales. Un DTE emitido no se revierte con rollback de código; se corrige tributariamente con nota.

### 4. Operación continua y cierre de homologación

- Programar CLI: documentos emitidos cada 15 minutos, inbox cada 10 minutos, clientes cada 6 horas; inicialmente `fetch-files=false` y descarga bajo demanda.
- Supervisar `facto_sync_logs`, operaciones `remote_uncertain`/`pending_local_commit`, conciliación y logs de acciones masivas.
- Probar por tipo: factura afecta/exenta, boleta afecta/exenta, guía, NC/ND y exportación.
- Solicitar a FACTO el WSDL, métodos, autenticación, idempotencia, códigos de error y ambientes SOAP. Sólo si el contrato aporta una operación no disponible por REST, implementar un adaptador SOAP detrás de la misma interfaz y homologarlo por separado.
- Los dashboards KPI se excluyen de esta versión.

## Criterios de aceptación

| Área | Aceptación |
|---|---|
| Seguridad | No existe `core/private_config.php` en el paquete; secretos rotados; gates y CSRF activos. |
| Emisión | Preview y emisión coinciden en receptor, tipo, moneda y total; el GET posterior confirma `document_id`; PDF/XML disponibles. |
| Recepción | Emisor = proveedor, receptor = ICYLAB, documentos aprobados materializan una sola CxP. |
| Finanzas | Saldos cumplen `total - pagado = saldo`; ninguna guía crea CxC; pagos/cobros son idempotentes. |
| Masivos | XLSX respeta filtros y selección; recálculo no inventa pagos; acción registrada. |
| Operación | Cron sin errores, sin pendientes remotos y con evidencia de canary aprobada. |

## Rollback

1. Cerrar inmediatamente los tres gates productivos.
2. No reintentar una operación `remote_uncertain`; consultar FACTO por `document_id`.
3. Ejecutar `database/migrations/2026_07_14_billing_v7_rollback_gate.sql` si se vuelve al código anterior.
4. Restaurar archivos con `ops/rollback_billing_readiness.sh` y el backup generado.
5. La tabla de auditoría se conserva. No borrar DTE, pagos ni cobros emitidos durante la ventana.