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ólocomponents.schemasy escribecore/network/generated/<servicio>/<servicio>_schemas.dartcon una clase inmutable por schema,fromJson,toJsony el aviso «CÓDIGO AUTOGENERADO. NO EDITAR». - Mapeo:
string→String;integer→int;number→double;format: uuid→String;format: date-time→DateTime;format: date→DateTimeserializado comoyyyy-MM-dd;anyOfconnullo propiedad fuera derequired→ nullable;enum→enumde Dart;$ref→ la clase referida. - Los decimales quedan como
String: las respuestas los traen como texto ("2.0000") y los requests aceptananyOfdenumberostring(p. ej.LineaPedidoRequest.cantidad), que se genera comoString. Undoubleperderí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/freezedcon clases escritas a mano — evitan elfromJsonmanual 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 analyzeen el código desactualizado. - El generador sólo cubre lo que usan hoy los contratos; una construcción
nueva (p. ej.
oneOfcon discriminador) obliga a extenderlo. - Para regenerar: copiar
/openapi.json,dart run tool/generar_dtos.dart <servicio>,flutter analyzeyflutter 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.