82 lines
3.6 KiB
Markdown
82 lines
3.6 KiB
Markdown
# 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:
|
|
|
|
```ts
|
|
const documentSeries = getService<DocumentSeriesPublicServicesType>("document-series:general");
|
|
|
|
const result = await documentSeries.assignNextNumber({
|
|
companyId,
|
|
documentType: "issued_invoice",
|
|
seriesCode: "F",
|
|
transaction,
|
|
});
|
|
```
|