# 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/next-number`
- `PATCH /document-series/:id/default`
- `PATCH /document-series/:id/enable`
- `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.

## Administración segura

La administración está disponible en Settings > Billing > Series documentales (`/settings/billing/document-series`). No expone `branchId`, no usa `assign-next` y separa las operaciones de edición de formato, avance de contador, default y estado.

- El update ordinario solo admite nombre, descripción, formato y vigencia.
- Código, tipo documental y branch no se modifican tras crear la serie.
- El contador solo puede avanzar con `PATCH /document-series/:id/next-number`; no admite decrementos, reseteos ni reutilización de números.
- `has_assigned_numbers` registra la primera asignación confirmada, incluso cuando procede del endpoint operativo directo.
- El default es opcional y exclusivo por empresa y tipo; se cambia con `PATCH /document-series/:id/default`.
- Enable y disable son transiciones explícitas auditadas. Desactivar una serie default la deja sin default, sin seleccionar otra automáticamente.

### UI de Settings

La administración vive en `/settings/billing/document-series`, bajo la sección Billing de Settings. `modules/document-series/src/web` es su propietario: expone la API web, adapters, entidades, React Query, controller, tabla y diálogos. `customer-invoices` consume series activas, pero no administra esta pantalla ni existe una dependencia inversa.

La pantalla usa el patrón canónico de Settings: listado `DataTable` con búsqueda, filtros, ordenación y paginación server-side; el controller posee los formularios y los diálogos solo presentan campos y errores. El flujo es `API → adapters/entities → React Query → controller → DataTable/dialogs`.

- Alta: permite código, tipo, formato, contador inicial, vigencia y estado inicial. `branchId` no se expone.
- Edición: solo permite nombre, descripción, prefijo, sufijo, padding y vigencia. Código y tipo quedan fijos tras crearla.
- El contador se avanza exclusivamente con su diálogo y operación específica; no se reduce ni se reinicia.
- Default y enable/disable son operaciones específicas. El default es opcional; desactivar una default la desmarca y reactivarla no la restaura.
- Cambiar formato no cambia snapshots ni referencias ya emitidas.

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