document-series

Centraliza la gestion de series documentales y su numeracion transaccional para documentos ERP. A fecha de cierre V1, es la API canonica y la tabla canonica para series de customer-invoices en issued_invoice y proforma.

Estructura

modules/document-series/src/api/domain: agregado DocumentSeries y VOs
modules/document-series/src/api/application: use cases, servicios y repositorio
modules/document-series/src/api/infrastructure: Sequelize, Express, DI y servicios públicos
modules/document-series/src/common/dto: contratos HTTP y de transporte con Zod

Servicios disponibles

GET /document-series
GET /document-series/:id
POST /document-series
PUT /document-series/:id
PATCH /document-series/:id/disable
POST /document-series/assign-next

POST /document-series/assign-next es un endpoint operativo para casos de uso backend o integraciones controladas. No es un endpoint para que la UI previsualice numeración.

Consumo desde otros módulos

document-series:general expone:

assignNextNumber(params)
listActiveSeries(params)

Estado de integración

issued-invoices ya asigna numeracion nueva mediante document-series
proformas ya asigna referencia nueva mediante document-series
las proformas V2 persisten snapshot explicito de serie con document_series_id, proforma_number y proforma_reference
en create de proformas, proforma_series_code permite seleccionar la serie de document_type = proforma
en emision de proformas, target_invoice_series_code apunta solo a document_type = issued_invoice
el endpoint legacy /catalogs/invoice-series esta retirado del runtime
la UI debe consultar GET /document-series?document_type=proforma&is_active=true
la UI debe consultar GET /document-series?document_type=issued_invoice&is_active=true
la UI no debe consumir POST /document-series/assign-next para previsualizar numeros
customer_invoice_series queda como legado historico a retirar mediante limpieza operativa controlada, no como runtime activo

SQL vigentes de soporte V1

docs/document-series/sql/validate-document-series-migration.sql
docs/document-series/sql/drop-customer-invoice-series-legacy.sql
docs/customer-invoices/sql/add-proforma-document-series-columns.sql
docs/customer-invoices/sql/add-proforma-tax-config-columns.sql

SQL históricos / transicionales

docs/document-series/sql/migrate-customer-invoice-series-to-document-series.sql

Los scripts vigentes son runbooks manuales y no sustituyen una migracion productiva formal. Los scripts históricos deben usarse solo para auditoría o entornos legacy explícitamente identificados.

Estado Fase 2C

el entorno detectado para desarrollo es apps/server/.env.development
el acceso apunta a localhost con NODE_ENV=development
en esta terminal no se pudo ejecutar SQL real porque:
- no existe cliente mysql disponible
- la dependencia mysql2 del workspace no resuelve una dependencia transitiva (sql-escaper), por lo que tampoco fue posible abrir conexion desde Node
por tanto, la Fase 2C queda preparada y documentada, pero no ejecutada desde este workspace

Pendientes conocidos

propagacion real de branchId desde el contexto de negocio hasta assignNextNumber(...)
validacion funcional contra una BD de desarrollo migrada

Ejemplo conceptual:

const documentSeries = getService<DocumentSeriesPublicServicesType>("document-series:general");

const result = await documentSeries.assignNextNumber({
  companyId,
  documentType: "issued_invoice",
  seriesCode: "F",
  transaction,
});

3.6 KiB Raw Permalink Blame History