david
e5e73a5a13
- 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.
97 lines
4.0 KiB
Markdown
97 lines
4.0 KiB
Markdown
# 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
|