Uecko_ERP/docs/document-series/migration-from-customer-invoice-series.md

# Migration from customer_invoice_series

Estado: historico/transicional.  
No representa el runtime actual ni el camino normal de entornos nuevos.

## Equivalencia conceptual

- `customer_invoice_series.code` -> `document_series.code`
- `customer_invoice_series.company_id` -> `document_series.company_id`
- `customer_invoice_series.next_number` -> `document_series.next_number`
- `customer_invoice_series.padding_length` -> `document_series.padding`
- `customer_invoice_series.is_default` -> `document_series.is_default`
- `customer_invoice_series.is_active` -> `document_series.is_active`
- `document_series.document_type` para legacy de facturas emitidas será `issued_invoice`

## Migración conservadora de issued invoices

```sql
INSERT INTO document_series (
  id,
  company_id,
  branch_id,
  document_type,
  code,
  name,
  description,
  prefix,
  suffix,
  next_number,
  padding,
  valid_from,
  valid_to,
  is_default,
  is_active,
  created_at,
  updated_at
)
SELECT
  cis.id,
  cis.company_id,
  NULL,
  'issued_invoice',
  cis.code,
  cis.code,
  NULL,
  CONCAT(cis.code, '-'),
  NULL,
  cis.next_number,
  cis.padding_length,
  NULL,
  NULL,
  cis.is_default,
  cis.is_active,
  cis.created_at,
  cis.updated_at
FROM customer_invoice_series cis
WHERE NOT EXISTS (
  SELECT 1
  FROM document_series ds
  WHERE ds.company_id = cis.company_id
    AND ds.document_type = 'issued_invoice'
    AND ds.code = cis.code
);
```

## Series de proformas

Crear una serie por defecto por empresa con:

- `document_type = 'proforma'`
- `code = 'PF'`
- `prefix = 'PF-'`
- `next_number = 1`
- `padding = 6`

En Fase 2B la fuente preferida para este seed pasa a ser `companies`, no `customer_invoice_series`, para cubrir empresas activas sin series legacy previas.

## Cambio de assigner

- antes: `InvoiceSeriesNumberAssigner`
- después: `DocumentSeriesNumberAssigner` o `document-series:general.assignNextNumber`

## Estado actual

- `document_series` es la tabla canonica
- `GET /document-series` es la API canonica
- `/catalogs/invoice-series` ha sido retirado del runtime
- `CustomerInvoiceSeriesModel` y su repositorio legacy ya no participan en runtime
- la UI no usa este documento ni este flujo para el funcionamiento normal

## Pendiente

- migración controlada de otros tipos documentales
- ejecucion manual y controlada del SQL conservador de migracion
- DDL previa de `proformas.document_series_id` y `proformas.proforma_number`
- propagacion real de `branchId` desde `customer-invoices`

## Validacion recomendada

- ejecutar `docs/document-series/sql/validate-document-series-migration.sql`
- revisar que no existan duplicados logicos por `company_id + document_type + code`
- revisar que cada empresa activa tenga una default de `proforma`
- revisar que ninguna proforma quede sin `proforma_reference`

## Estado de ejecucion Fase 2C

- se detecto una configuracion de desarrollo en `apps/server/.env.development`
- no se ejecuto SQL real desde esta terminal por bloqueo operativo del cliente/conector local
- produccion no se considero objetivo de ejecucion