Uecko_ERP/docs/customer-invoices/proforma-tax-config.md

# Proforma Tax Config

## Objetivo

Persistir la configuracion fiscal de cabecera de una proforma sin confundirla con los impuestos realmente calculados desde lineas valoradas.

## Alcance

- `tax_regime_code` sigue representando el regimen fiscal general
- `tax_config` representa los controles fiscales de cabecera usados por la UI
- `taxes` sigue representando solo desglose fiscal materializado
- `totals` sigue representando solo importes calculados desde lineas valoradas

## Campos persistidos en `proformas`

- `tax_mode`
- `default_iva_code`
- `uses_equivalence_surcharge`
- `default_rec_code`
- `uses_retention`
- `default_retention_code`

## Contrato publico

`GET /proformas/:id` debe devolver:

```ts
{
  tax_regime: {
    code: string;
    name: string;
    description: string;
  } | null;
  tax_config: {
    tax_mode: "single" | "per_line";
    default_iva_code: string | null;
    uses_equivalence_surcharge: boolean;
    default_rec_code: string | null;
    uses_retention: boolean;
    default_retention_code: string | null;
  };
}
```

`POST /proformas` y `PATCH /proformas/:id` pueden aceptar `tax_config` como bloque independiente de `items`.

## Regla funcional

- una proforma puede existir con `items = []`
- en ese caso `taxes = []`
- en ese caso todos los totales monetarios deben quedar a `0`
- la UI debe hidratar los controles de fiscalidad desde `tax_config`, no desde `taxes`

## Resolucion de defaults en create

Los defaults del cliente solo se usan al crear la proforma y el resultado se persiste.

Fallback actual:

- `tax_mode`: `single`
- IVA por defecto: `iva_21`
- recargo de equivalencia: desactivado salvo indicacion explicita
- retencion: desactivada salvo indicacion explicita
- codigo de retencion por defecto si `uses_retention = true`: `retention_15`

Si el cliente cambia despues de crear la proforma:

- no se reconstruye `tax_config` desde el cliente actual
- la proforma conserva su `tax_config` persistido

## Regla de update

`tax_config` se actualiza de forma parcial y se mergea sobre la configuracion persistida actual.

No debe reconstruirse desde:

- `taxes`
- el cliente actual
- defaults implícitos de frontend

## No incluido

- nueva tabla para configuracion fiscal
- recalculo fiscal fuera del flujo normal de lineas
- cambios de Verifacti
- cobros o vencimientos vivos
- rectificativas