Uecko_ERP/docs/customer-invoices/invoice-series.md

InvoiceSeries (Histórico / Obsoleto)

Documento mantenido solo como referencia histórica previa a la retirada de /catalogs/invoice-series. Estado actual: la API canónica es /document-series y la tabla canónica es document_series.

Decisión consolidada

Antes de la migración, el recurso backend para las series de facturación de cliente se llamaba:

InvoiceSeries

Su tabla Sequelize asociada era:

customer_invoice_series

Este contenido ya no describe el runtime activo del ERP.

No usar este documento para desarrollo nuevo. La referencia vigente es docs/document-series/*.

Alcance funcional

InvoiceSeries representa la serie usada para numerar facturas emitidas de cliente.

La proforma:

- guarda una referencia legacy en Proforma.series
- ese valor corresponde a InvoiceSeries.code
- no consume numeración de factura emitida

Modelo mínimo

Campos activos en V1:

id
company_id
code
next_number
padding_length
is_default
is_active
created_at
updated_at

No existen en V1:

prefix
name
description
document_type

Reglas de numeración

next_number es obligatorio y es la fuente de verdad para asignar el siguiente número de factura emitida.

El flujo de emisión desde proforma es:

1. leer la proforma
2. tomar Proforma.series como InvoiceSeries.code
3. buscar InvoiceSeries por company_id + code
4. validar que la serie existe y está activa
5. bloquear la fila de customer_invoice_series dentro de la misma transacción
6. leer next_number
7. asignar ese número a la issued invoice
8. incrementar next_number
9. confirmar issued invoice + increment en una sola transacción

No se permite:

- MAX(invoice_number) + 1
- consumir numeración al crear o actualizar proformas
- separar el lock y el update en transacciones distintas

Formato visible

El formato visible deriva de:

formatted_number = code + "-" + number.padStart(padding_length, "0")

Ejemplo:

code = A
number = 23
padding_length = 6

=> A-000023

En V1 no existe prefix. code actúa a la vez como identificador funcional y prefijo visible.

Integridad defensiva

En customer_invoice_series debe existir:

UNIQUE (company_id, code)

En customer_invoices la regla defensiva para numeración emitida es:

company + series + invoice_number debe ser único

Actualmente el modelo Sequelize usa:

UNIQUE (company_id, series, invoice_number, is_proforma)

Esto evita colisiones entre proformas y facturas emitidas mientras ambas comparten customer_invoices.

Seeds e inicialización

No se ha añadido seed automático por empresa porque el repo no expone un sistema real de seeders versionados ni una estrategia fiable para inicializar todas las companies existentes.

Regla operativa:

cada company necesita al menos una InvoiceSeries activa antes de emitir facturas

Serie mínima recomendada:

code = A
next_number = 1
padding_length = 6
is_default = true
is_active = true

Estado técnico del repo

En este repo no se localizó un framework de migraciones versionadas con sequelize-cli, umzug o equivalente.

El arranque del servidor registra modelos Sequelize y sincroniza base de datos mediante:

database.sync({ alter: true })

Por eso el SQL manual asociado a customer_invoice_series vive en:

customer-invoice-series.sql

Ese archivo debe integrarse en el pipeline real de despliegue DB cuando exista.

Sustitución vigente

• API canónica: /document-series
• tabla canónica: document_series
• proformas: proforma_series_code y target_invoice_series_code
• SQL histórico de apoyo: docs/dev/customer-invoice-series.sql