Document Series Design

Objetivo del módulo

document-series es un módulo propio porque la serie documental no es un catálogo estático: mantiene reglas de vigencia, flags de activación, defaults y estado transaccional de numeración.

Por qué no vive en catalogs

Los catálogos del ERP resuelven valores de referencia. Aquí hay concurrencia, bloqueo de fila y mutación transaccional de next_number, así que el comportamiento es operativo y no meramente descriptivo.

Por qué numeración y serie viven juntas

La numeración depende del estado de la serie:

si está activa
si está vigente
si es la serie por defecto
cuál es su prefijo, sufijo y padding

Separarlo introduciría doble escritura o lecturas no atómicas.

Modelo conceptual

DocumentType: tipo documental cerrado en V1
DocumentSeries: agregado con configuración y contador
AssignedDocumentNumber: resultado de asignación atómica

Campos principales

companyId, branchId
documentType
code, name, description
prefix, suffix
nextNumber, padding
validFrom, validTo
isDefault, isActive

Reglas V1

tipos soportados: proforma, issued_invoice
no asigna si la serie está inactiva
no asigna si la serie está fuera de vigencia
default por empresa + tipo, con prioridad de branch_id cuando aplica
formato de referencia: prefix + padded(next_number) + suffix

Concurrencia

La asignación usa transacción obligatoria y bloqueo de fila con LOCK.UPDATE sobre document_series. El incremento de next_number se persiste dentro de la misma transacción y con comprobación optimista del valor previo para evitar dobles consumos.

Integracion con customer-invoices

En V1:

issued-invoices delega la asignacion de numero en document-series
proformas delega la asignacion de referencia en document-series
proformas persiste document_series_id y proforma_number como snapshot tecnico adicional a proforma_reference
proformas.document_series_id identifica la serie documental usada para numerar la proforma
proformas.proforma_number guarda el numero propio de la proforma
proformas.proforma_reference guarda la referencia visible de la proforma
proforma_series_code es el input funcional de create para elegir la serie de document_type = proforma
proformas.target_invoice_series_code es opcional y, cuando existe, apunta a una serie de issued_invoice, nunca a una serie de proforma
create de proforma solo usa document-series para numerar la cabecera inicial
create de proforma puede persistir tax_config sin materializar impuestos
una proforma puede crearse sin lineas y seguir siendo valida como borrador inicial
si no hay lineas valoradas, proforma_taxes debe quedar vacia y los totales monetarios a 0
si proformas.target_invoice_series_code es NULL, la emision resuelve la serie default activa de issued_invoice
en Fase 2E, series deja de ser el contrato nuevo para create/update de proformas
la UI consulta GET /document-series con filtro por document_type y is_active = true
la UI no consume POST /document-series/assign-next para previsualizar numeracion
/catalogs/invoice-series deja de existir como endpoint runtime
customer_invoice_series no participa ya en flujos activos de lectura o numeracion

Migracion conservadora

la migracion historica de issued_invoice parte de customer_invoice_series
la creacion de series default de proforma usa companies como fuente
las validaciones SQL se mantienen separadas del script de migracion
no hay ejecucion automatica ni cutover productivo en esta fase
la DDL de proformas usa information_schema + SQL dinamico para mantener compatibilidad MariaDB/MySQL sin depender de IF NOT EXISTS en ALTER TABLE

Branch scope pendiente

El modelo ya contempla branchId, y la resolucion default da prioridad a branch_id cuando existe. Aun asi, customer-invoices no propaga un contexto real de sucursal hasta assignNextNumber(...), asi que en esta fase toda la integracion sigue operando con alcance de empresa.

Límites V1

sin format_pattern
sin reseteos anuales automáticos
sin reservas de numeración
sin huecos justificados
sin migración productiva automática de legacy

Extensiones futuras

nuevos DocumentType
seeds/migraciones controladas de series heredadas

4.3 KiB Raw Blame History