Cosmos.Types.UnidadesDeMedida 1.0.0

Cosmos.Types.UnidadesDeMedida

UnidadDeMedida — Value Object de la unidad en que se expresa una cantidad, por su código UN/ECE Recomendación 20 (GLL galón, LTR litro, KGM kilogramo, C62 uno). Catálogo embebido de 1.095 unidades: las que admiten las facturas electrónicas de Colombia (DIAN), República Dominicana (DGII) y Panamá (DGI). Viaja dentro de eventos event-sourced (JSONB), por lo que su forma serializada es un contrato estable. No convierte entre unidades.

Instalación

dotnet add package Cosmos.Types.UnidadesDeMedida

Uso

using Cosmos.Types.Paises;
using Cosmos.Types.UnidadesDeMedida;

var galon = UnidadDeMedida.Obtener("GLL");      // lanza ArgumentException si no existe/activo
galon.Nombre;                                  // "Galón"
galon.Simbolo;                                 // "gal (US)"  (null si la Rec. 20 no le asigna símbolo)
galon.EstadoRec20;                             // EstadoRec20.Vigente

UnidadDeMedida.Existe("gll");                  // false: los códigos distinguen mayúsculas
UnidadDeMedida.Listar();                       // las 1.095 unidades activas

UnidadDeMedida.DesdeAutoridad(Pais.Obtener("DO"), "15");   // GLL («Galones» de la Tabla IV DGII)
UnidadDeMedida.DesdeAutoridad(Pais.Obtener("PA"), "gal");  // GLL (Tabla 29 DGI)
UnidadDeMedida.DesdeAutoridad(Pais.Obtener("CO"), "94");   // 94 («unidad» para la DIAN)
UnidadDeMedida.DesdeAutoridad(Pais.Obtener("DO"), "18");   // null («granel» no tiene equivalente)

• Sin normalización: el código se compara tal cual (gll y " GLL" no son válidos): Existe devuelve false y Obtener lanza ArgumentException.
• DesdeAutoridad devuelve null cuando no puede traducir: país sin tabla, unidad sin equivalente en la Rec. 20, mapeo aún por validar o código que la autoridad no tiene. Nunca lanza. Con null, el consumidor conserva el texto de la autoridad sin traducirlo.
• Ausencia: un concepto que no mide cantidad no lleva unidad. No existe una unidad «no especificada» ni se usa ZZ como comodín.

Forma serializada

{ "codigo": "GLL" }

Clave camelCase anclada con [JsonPropertyName]. Nombre, Simbolo y EstadoRec20 son accessors derivados del catálogo ([JsonIgnore]): no viajan en el evento. La rehidratación no valida: un evento con un código que ya no figura se carga igual y sus accessors devuelven null.

Datos embebidos

Se copian sin modificar de erp-definiciones/compartido/datos-referencia/catalogos/. La regla de traducción de cada país se lee del campo regla de su archivo.

Diferencias con la especificación del Nugget (v0.1)

1. nombre(), simbolo() y estadoRec20() son propiedades (Nombre, Simbolo, EstadoRec20), según la convención de accessors derivados del repo.
2. DesdeAutoridad devuelve null también para un país sin tabla y para un código que la autoridad no tiene.
3. Las equivalencias marcadas porValidar (22 de CO, 26 de DO y 41 de PA; de ellas, 18 de DO y 11 de PA traen un código candidato) no se traducen hasta que se confirmen. Al confirmarlas en Datos de Referencia, se actualiza el JSON y se publica una versión menor.
4. Se agregan Existe y Listar, que la especificación no nombra, al estilo de los demás nuggets.
5. El ejemplo MTK/mtk de la especificación no existe en el catálogo (no hay códigos en minúscula). La regla de no normalizar se mantiene.

Pendientes de la especificación que no bloquean la API: revisión editorial de nombres (P1), confirmación de equivalencias porValidar (P2) y Rec. 21 para empaques (P3).