david 5ed6556036 feat(document-series): implement document series management API

- Add UpdateDocumentSeriesController for updating document series.
- Create documentSeriesApiErrorMapper for error handling.
- Define document series routes including CRUD operations.
- Implement Sequelize-based persistence layer for document series.
- Add DTOs for request and response schemas for document series operations.
- Establish common structures for document series data handling.
- Configure TypeScript settings for the document series module.

2026-07-28 18:04:57 +02:00

3.1 KiB

Raw Blame History

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 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
no se permite cambiar proforma_series_code, document_series_id, proforma_number ni proforma_reference

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
update acepta target_invoice_series_code
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 de salida mientras existan consumidores antiguos

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

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

3.1 KiB Raw Blame History