david 5ed6556036 feat(document-series): implement document series management API

- Add UpdateDocumentSeriesController for updating document series.
- Create documentSeriesApiErrorMapper for error handling.
- Define document series routes including CRUD operations.
- Implement Sequelize-based persistence layer for document series.
- Add DTOs for request and response schemas for document series operations.
- Establish common structures for document series data handling.
- Configure TypeScript settings for the document series module.

2026-07-28 18:04:57 +02:00

3.2 KiB

Raw Blame History

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

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 transicional /catalogs/invoice-series queda eliminado antes de produccion
la UI debe consultar GET /document-series filtrando por document_type
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 de soporte V1

docs/document-series/sql/migrate-customer-invoice-series-to-document-series.sql
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

Estos scripts son conservadores e idempotentes. No se han ejecutado automaticamente en este workspace ni sustituyen una migracion productiva formal.

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.2 KiB Raw Blame History