David
78f5236fe9
* Añadir el componente `DocumentSeriesSettingsPage` para gestionar las series documentales. * Crear diálogos para añadir, editar, avanzar y deshabilitar series documentales. * Implementar esquemas de validación de formularios para crear y editar series documentales. * Añadir funciones de utilidad para construir los payloads de las peticiones de las operaciones sobre series documentales. * Escribir pruebas unitarias para los esquemas de formularios y las funciones de utilidad. * Implementar pruebas end-to-end para la configuración de series documentales, cubriendo la creación, edición, establecimiento como predeterminada, avance y deshabilitación.
108 lines
5.8 KiB
Markdown
108 lines
5.8 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/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,
|
|
});
|
|
```
|