Cosmos.Types.DireccionesFisicas 1.1.2

Cosmos.Types.DireccionesFisicas

DireccionFisica — Value Object de dirección física para el ERP Cosmos: país, división territorial (vía Cosmos.Types.DivisionesTerritoriales), línea de dirección y código postal opcional. 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.DireccionesFisicas

Construcción

DivisionTerritorial es un VO de catálogo: se obtiene con DivisionTerritorial.Obtener(pais, codigo), que lanza. DireccionFisica es un VO compuesto: su factory pública Crear(...) : Result<DireccionFisica> valida sin lanzar (EsExitoso / .Valor / .Errores):

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

var colombia = Pais.Obtener("CO");
var medellin = DivisionTerritorial.Obtener(colombia, "05001");   // VO de catálogo: Obtener (lanza)

var resultado = DireccionFisica.Crear(                            // VO compuesto: Crear (Result)
    divisionTerritorial: medellin,
    lineaDireccion: "Calle 10 # 43-12");

if (resultado.EsExitoso)
    UsarDireccion(resultado.Valor);
else
    foreach (var error in resultado.Errores)
        Console.WriteLine(error.Codigo);   // V02 (división), V03 (línea), V04 (código postal)

Crear deriva el país de la división territorial (no se pasa por separado): la división ya carga su país.

Código postal (V04, condicional por perfil)

El perfil del país (derivado de la división) gobierna la validación del código postal:

• Formato: si el perfil declara un formato, un postal que no lo cumpla falla con V04 (bloqueante).
• Existencia: bajo política advertencia (hoy solo Colombia, contra el catálogo embebido de 248 códigos de las 10 ciudades principales), un postal de formato válido ausente del catálogo produce un resultado exitoso con una advertencia V04 (resultado.Advertencias), no lo rechaza.
• Sin catálogo: los países cuyo perfil no declara catálogo (o sin perfil) almacenan el postal crudo.

DireccionFisica.ExisteCodigoPostal("110111");   // true si figura activo en el catálogo embebido

Tipos de dirección (catálogo read-only)

El uso de una dirección (Fiscal, Comercial, Correspondencia, Entrega, Sucursal) es vocabulario compartido, no un campo de DireccionFisica. Se expone para que un frontend lo liste:

var tipos = TipoDireccion.Listar();              // IReadOnlyList<TipoDireccion>: FSC, COM, COR, ENT, SUC
var opciones = tipos.Select(tipo => new { tipo.Codigo, tipo.Nombre });

Forma serializada

{
  "pais": { "codigo": "CO" },
  "divisionTerritorial": { "pais": { "codigo": "CO" }, "codigo": "05001" },
  "lineaDireccion": "Calle 10 # 43-12",
  "lineaDireccion2": null,
  "codigoPostal": null,
  "capturaEstructurada": null
}

Las claves son camelCase ancladas con [JsonPropertyName]. A diferencia de IdentificacionLegal (que aplana su tipo a string), DireccionFisica anida la DivisionTerritorial completa como objeto — decisión deliberada para conservar la jerarquía territorial aguas abajo. La LineaDireccion2 (complemento), el CodigoPostal y la CapturaEstructurada viajan como campos estructurales aunque sean null.

Captura estructurada (opcional)

En los países cuyo perfil la habilita (hoy Colombia), la dirección puede capturarse de forma estructurada (tipo de vía, número, complementos). Un overload de Crear la recibe y deriva la lineaDireccion como su composición canónica; falla V05 si el país no la habilita o si algún código no existe en su catálogo:

var captura = new CapturaEstructurada
{
    TipoVia = "CL",                 // catálogo tipos-via-co
    NumeroVia = "10",
    NumeroPredio = "43A-27",
    Complementos = [new ComplementoDireccion { TipoComplemento = "APT", Valor = "101" }]  // catálogo tipos-complemento
};

var resultado = DireccionFisica.Crear(medellin, captura);
// resultado.Valor.LineaDireccion == "Calle 10 # 43A-27, Apartamento 101"

La línea canónica (V06) se compone con la gramática "{nombreTipoVia} {numeroVia} # {numeroPredio}" + ", {nombreTipoComplemento} {valor}", usando los nombres del catálogo (el valor canónico es para humanos; los códigos viajan en capturaEstructurada para uso de máquina). La captura no participa de la igualdad (con V06, la misma captura ⇒ la misma línea, que ya discrimina) y se serializa como objeto anidado capturaEstructurada con claves camelCase ancladas.

Igualdad de la línea: se compara normalizada (mayúsculas, espacios colapsados, sin puntuación ./,); el valor almacenado conserva la forma capturada. Dos direcciones con la misma división y código postal cuyas líneas difieran solo en mayúsculas/espacios/puntuación son iguales.

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 — una división que ya no figura en el catálogo igual se rehidrata.

Dependencias

• Cosmos.Types.Abstractions (kernel: Result<T>)
• Cosmos.Types.DivisionesTerritoriales

Requiere net10.0. La dirección es línea libre normalizada (o composición canónica de una captura estructurada opcional) con validación de código postal (V04) condicional por perfil de país.

Documentación

• Convenciones de los nuggets (§7: alcance del núcleo, V04 y captura estructurada)

Licencia

Uso interno del ERP Cosmos.