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

4.3 KiB Raw Permalink Blame History