Saltar a contenido

0006. DTO generados desde una copia versionada del contrato OpenAPI

Estado: Propuesto Fecha: 2026-11-02 Autor: David Garcia Módulo(s) afectado(s): openapi/, tool/, core/network/generated/ Complementa a: ADR 0001, ADR 0003

Contexto

Cada servicio publica su contrato en /openapi.json. Si los DTO se escriben a mano se desincronizan del backend sin que nadie se entere hasta un 422 en la calle. La web ya decidió copiar el contrato al repositorio y generar sólo los tipos con un script propio, sin generar clientes ni hooks (ADR 0012 del frontend). Dart, además, no tiene tipos estructurales: cada DTO necesita su fromJson y su toJson.

Decisión

  • Copia versionada del contrato en openapi/<servicio>.json, con los mismos nombres que la web (identidad, clientes, fuerza_ventas). Se regenera sin tener el servicio levantado y el PR muestra qué cambió.
  • Generador propio en Dart (tool/generar_dtos.dart <servicio>), sin dependencias: lee sólo components.schemas y escribe core/network/generated/<servicio>/<servicio>_schemas.dart con una clase inmutable por schema, fromJson, toJson y el aviso «CÓDIGO AUTOGENERADO. NO EDITAR».
  • Mapeo: string → String; integer → int; number → double; format: uuid → String; format: date-time → DateTime; format: date → DateTime serializado como yyyy-MM-dd; anyOf con null o propiedad fuera de required → nullable; enum → enum de Dart; $ref → la clase referida.
  • Los decimales quedan como String: las respuestas los traen como texto ("2.0000") y los requests aceptan anyOf de number o string (p. ej. LineaPedidoRequest.cantidad), que se genera como String. Un double perdería precisión en montos; el modelo del módulo los convierte con un tipo decimal.
  • Los DTO no salen del módulo: api/ los usa y el repositorio los pasa a los modelos de la UI (ADR 0002). Clientes y funciones HTTP se escriben a mano.

Alternativas descartadas

  • openapi-generator (dart-dio) — genera clientes y una estructura que no controlamos, lo mismo que la web descartó con Orval.
  • json_serializable / freezed con clases escritas a mano — evitan el fromJson manual pero no el desfase con el contrato.
  • Usar Map<String, dynamic> en los módulos — sin errores de compilación cuando cambia un campo.

Consecuencias

  • Un cambio incompatible del contrato rompe flutter analyze en el código desactualizado.
  • El generador sólo cubre lo que usan hoy los contratos; una construcción nueva (p. ej. oneOf con discriminador) obliga a extenderlo.
  • Para regenerar: copiar /openapi.json, dart run tool/generar_dtos.dart <servicio>, flutter analyze y flutter test.

Media página como máximo. Si el ADR crece más que eso, probablemente estás documentando el diseño completo del módulo, no una decisión puntual — separa.