FactuGES_ERP/docs/customer-invoices/sql/README.md

# SQL Customer Invoices

> Referencia manual e histórica. El esquema nuevo se instala mediante las
> [migraciones versionadas](../../desarrollo-y-migraciones-bd.md).
> No ejecutar todos estos scripts como procedimiento de instalación.


## Estado

Este directorio mezcla SQL vigentes de soporte con SQL historicos/transicionales.

Las tablas legacy `customer_invoices`, `customer_invoice_items` y
`customer_invoice_taxes` no forman parte del runtime actual. Solo pueden aparecer
en SQL historico de migracion o validacion.

Regla SSOT relevante para VeriFactu:

- `issued_invoices` no debe reintroducir `verifactu_profile_status`,
  `uses_verifactu` ni `verifactu_effective_at` como columnas vigentes;
- la cardinalidad implementada sigue siendo `IssuedInvoice 1 -> 0..1 VerifactuRecord`;
- `0..N` es objetivo futuro, no estado operativo actual.

## SQL vigentes

- `add-company-verifactu-profiles.sql`
- `add-proforma-document-series-columns.sql`
- `add-proforma-tax-config-columns.sql`
- `add-issued-invoice-reference.sql`
- `normalize-document-series-snapshots.sql`
- `fix-proforma-series-semantics.sql`
- `validate-proforma-tax-config.sql`
- `validate-proforma-soft-delete.sql`

## SQL históricos / transicionales

- `add-issued-invoice-verifactu-snapshots.sql`
- `drop-issued-invoice-verifactu-snapshot-columns.sql`
- `dev-split-proformas-issued-invoices.sql`
- `validate-split-proformas-issued-invoices.sql`

Estos archivos no deben tratarse como el camino normal de entornos nuevos salvo que exista un escenario legacy concreto que los requiera.

## Orden recomendado en desarrollo para el estado vigente

1. Verificar que la BD objetivo es inequívocamente de desarrollo.
2. Hacer backup o confirmar que los datos son descartables.
3. Ejecutar `add-company-verifactu-profiles.sql` si el entorno aún no tiene el perfil VeriFactu empresarial.
4. Ejecutar el DDL vigente que falte para `proformas`.
5. Ejecutar `normalize-document-series-snapshots.sql` para completar snapshots y validaciones de seriado.
6. Ejecutar las validaciones SQL vigentes.
7. Levantar backend V2 y validar flujos funcionales.

## SQL expresamente superados para VeriFactu en `issued_invoices`

- `add-issued-invoice-verifactu-snapshots.sql` responde a una propuesta anterior
  que mezclaba snapshots fiscales con un `verifactuPolicy` hoy descartado.
- `drop-issued-invoice-verifactu-snapshot-columns.sql` se conserva como runbook
  correctivo para entornos legacy donde esas columnas todavía existan.

## Propiedades de los scripts históricos de split

- Crea tablas con `CREATE TABLE IF NOT EXISTS`.
- Añade `verifactu_records.issued_invoice_id` con `ALTER TABLE ... ADD COLUMN IF NOT EXISTS`.
- Conserva UUIDs legacy.
- No borra ni modifica datos legacy.
- Usa `NOT EXISTS` para evitar duplicados en reejecuciones.
- No usa `INSERT IGNORE`.

## Cuándo no ejecutar

No ejecutar si:

- no existe una configuración de desarrollo clara
- hay duda sobre si la BD es producción
- no existe backup verificable
- el entorno no tiene aún las credenciales/localización confirmadas

## Procedimiento preliminar de producción

No ejecutar todavía. Referencia operativa:

1. Backup verificado.
2. Ventana de mantenimiento.
3. Bloquear escrituras del backend.
4. Ejecutar create tables / columnas transicionales.
5. Ejecutar backfill idempotente y conservador.
6. Ejecutar validaciones SQL.
7. Desplegar backend con wiring V2.
8. Monitorizar errores y métricas.
9. Mantener legacy congelado para rollback y auditoría.
10. Ejecutar rollback según punto de corte si alguna validación falla.