Cosmos.Types.DivisionesTerritoriales 1.1.1

Cosmos.Types.DivisionesTerritoriales

DivisionTerritorial — Value Object de división territorial para el ERP Cosmos, con catálogo DIVIPOLA de Colombia embebido (33 departamentos + 1.122 municipios). Viaja dentro de eventos event-sourced (JSONB) aguas abajo, por lo que su forma serializada es un contrato estable.

Instalación

dotnet add package Cosmos.Types.DivisionesTerritoriales

Construcción

DivisionTerritorial es un VO de catálogo país-scoped: su puerta pública es Obtener(pais, codigo), que lanza ArgumentException si el código no existe o no está activo para ese país. Recibe un Pais ya tipado (que solo se obtiene por Pais.Obtener, validado):

using Cosmos.Types.DivisionesTerritoriales;
using Cosmos.Types.Paises;

var colombia = Pais.Obtener("CO");
var medellin = DivisionTerritorial.Obtener(colombia, "05001");   // Medellín (DIVIPOLA); lanza si no existe

La factory Crear(...) : Result<DivisionTerritorial> es internal: no está disponible para el consumidor. Toda DivisionTerritorial tipada es válida por construcción.

Forma serializada

{ "pais": { "codigo": "CO" }, "codigo": "05001" }

Las claves son camelCase ancladas con [JsonPropertyName]; el Pais anidado serializa su propio { "codigo": … }. Los datos descriptivos (Nombre, Nivel, Superior) son accessors derivados del catálogo, marcados [JsonIgnore]: no viajan en el evento.

Rehidratación (deserialización)

No requiere setup: ni JsonConverter ni JsonSerializerContext registrados; basta el STJ por defecto. Al deserializar un evento histórico el VO se rehidrata crudo ([JsonConstructor]), sin validar — un código que ya no figura igual se rehidrata. En ese estado poison los accessors derivados resuelven a null sin lanzar (division.Nombre == null).

Listado

El catálogo es jerárquico y grande, así que no hay un Listar() plano. Para poblar selectores en un frontend: ListarPorPais(pais) (todas las divisiones activas), RaicesDe(pais) (nivel superior, p. ej. departamentos) y HijasDe(division) (descenso jerárquico). Devuelven los mismos DivisionTerritorial que consume la escritura; el backend proyecta su propio DTO de API:

var departamentosDto = DivisionTerritorial.RaicesDe(colombia)
    .Select(division => new { division.Codigo, division.Nombre });

Dependencias

• Cosmos.Types.Abstractions (kernel: Result<T>)
• Cosmos.Types.Paises (validación del país)

Requiere net10.0. Hoy solo se embebe el catálogo de Colombia; otros países quedan diferidos.

Documentación

• Convenciones de los nuggets

Licencia

Uso interno del ERP Cosmos.