david e5e73a5a13 Refactor documentation for ERP architecture and customer invoices

- Updated general requirements document to clarify its historical context and remove outdated technical details.
- Revised template documentation to serve as a base for writing prompts, emphasizing its auxiliary nature.
- Enhanced architecture documentation with clear distinctions between canonical and complementary documents.
- Added a new document for backend prompt base to centralize common context for backend prompts.
- Created a dedicated README for customer invoices, organizing current contracts, operational support, and historical context.
- Improved clarity and structure in various customer invoice documents, consolidating operational semantics and referencing canonical sources.

2026-08-05 13:18:03 +02:00

4.0 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_series_code guarda el codigo snapshot de la serie 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
la semantica detallada de create sin lineas, tax_config, taxes y totals vive en proforma-create-contract.md

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
la semantica de taxes, tax_config y totals se documenta en proforma-create-contract.md

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
el recalculo de impuestos y totales reales al editar lineas se documenta en proforma-create-contract.md

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_series_code, 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.0 KiB Raw Blame History