Uecko_ERP/docs/document-series/README.md

# 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,
});
```