Uecko_ERP/docs/customer-invoices/proforma-series-contract.md

# Proforma Series Contract

## Objetivo

Normalizar el contrato publico de proformas para separar definitivamente la serie propia de la proforma de la serie futura de la factura emitida.

## Semantica correcta

En proformas:

- `document_series_id` identifica la serie documental propia de la proforma
- `proforma_number` guarda el numero propio de la proforma
- `proforma_reference` guarda la referencia visible de la proforma, por ejemplo `PF-0139`
- `proforma_series_code` es el codigo funcional que se usa solo en create para elegir una serie de `document_type = proforma`
- `target_invoice_series_code` identifica la serie futura que se usara al emitir una `issued_invoice`, por ejemplo `F26`

`target_invoice_series_code` nunca debe apuntar implicitamente a la serie documental de proforma. Un valor como `PF` solo seria valido si existiera tambien una serie activa `PF` de `document_type = issued_invoice`, lo cual no debe asumirse.

## Reglas funcionales

### Crear proforma

- se pide fecha
- se pide cliente
- `proforma_series_code` es opcional; si falta, se usa la serie default activa de `document_type = proforma`
- `target_invoice_series_code` es opcional; si falta, se persiste `NULL`
- la creacion de proforma genera una cabecera valida aunque no existan lineas
- `items` puede omitirse o enviarse como `[]`
- si no hay lineas valoradas, la response debe devolver `items = []`, `taxes = []` y totales a `0`
- `tax_regime_code` en create representa configuracion fiscal inicial, no impuestos ya aplicados
- la UI obtiene ambas listas desde `GET /document-series`, filtrando por `document_type`

### Editar draft

- se permiten cambios comerciales
- se permite cambiar `target_invoice_series_code`
- se permite cambiar `tax_config`
- no se permite cambiar `proforma_series_code`, `document_series_id`, `proforma_number` ni `proforma_reference`
- la UI hidrata la configuracion fiscal desde `tax_config`, no desde `taxes`

### Editar approved

- la edicion queda restringida
- solo se permite ajustar `target_invoice_series_code` antes de emitir

### Editar issued

- no se permite edicion funcional

## Contrato actual

### Requests

- create acepta `proforma_series_code`
- create acepta `target_invoice_series_code`
- create puede aceptar `tax_config`
- update acepta `target_invoice_series_code`
- update puede aceptar `tax_config`
- el flujo nuevo ya no necesita `series`

### Responses

- el backend emite `target_invoice_series_code` como nombre preferente
- `series` puede mantenerse solo como alias legacy/deprecated de salida mientras existan consumidores antiguos
- `taxes` representa impuestos calculados a partir de lineas valoradas
- `tax_config` representa la configuracion fiscal persistida de cabecera
- `totals` representa importes calculados a partir de lineas valoradas
- create no debe inventar filas fiscales sobre base `0`

## Regla de emision

- si `target_invoice_series_code` tiene valor, la emision usa ese `seriesCode` para `document_type = issued_invoice`
- si `target_invoice_series_code` es `NULL`, `document-series` resuelve la serie default activa de `issued_invoice`
- la UI nunca debe consumir numeracion directa desde `POST /document-series/assign-next`
- los impuestos y totales reales se recalculan cuando la proforma ya tiene lineas en update

## Regla de borrado y numeracion

- borrar una proforma draft no libera ni reutiliza `proforma_reference`
- el siguiente alta consume el siguiente numero disponible de `document-series`
- no se decrementa `document_series.next_number`
- las proformas `rejected` no se borran; quedan para una futura operacion de archivado

## Validacion defensiva

Si el request informa `target_invoice_series_code`:

- debe corresponder a una serie activa de `document_type = issued_invoice`
- no se permite volver a persistir series de `document_type = proforma` como target de factura

Si el request informa `proforma_series_code`:

- debe corresponder a una serie activa de `document_type = proforma`
- solo se usa para numerar la proforma en create
- despues queda congelado en `document_series_id`, `proforma_number` y `proforma_reference`

## Retirada futura de `series`

- `series` era ambiguo porque mezclaba dos conceptos distintos
- el contrato correcto usa `proforma_series_code` y `target_invoice_series_code`
- `series` debe retirarse por completo cuando ya no queden consumidores legacy de responses