using System.Text.Json.Serialization;

namespace Cepis;

/// <summary>
/// The CEP's coordinate, when the database has one.
/// </summary>
/// <remarks>
/// <para>
/// The point is the <b>median</b> of the coordinates of that CEP's addresses,
/// not the mean: one badly geocoded address 40 km away shifts a mean and does
/// not move a median.
/// </para>
/// <para>
/// Always check <see cref="Precisao"/> before using <see cref="Lat"/> and
/// <see cref="Lon"/> for distance. <c>"logradouro"</c> means the point is a
/// stretch of street and <see cref="RaioM"/> lands around 100–150 m — good for
/// maps and for distance. <c>"localidade"</c> means the CEP <i>is</i> the whole
/// municipality (a city-wide general CEP) and the point is its centroid, with
/// <see cref="RaioM"/> running from 7 km to 40 km; computing shipping from that
/// is wrong by tens of kilometres.
/// </para>
/// <para>
/// <see cref="RaioM"/> is the radius containing 90% of that CEP's addresses. It
/// exists precisely so that error cannot pass unnoticed.
/// </para>
/// <para>
/// The property names are the API's own, with only the casing adapted:
/// <c>lat</c>, <c>lon</c>, <c>raio_m</c> and <c>precisao</c> on the wire.
/// </para>
/// </remarks>
public sealed record Geo
{
    /// <summary>Latitude in decimal degrees, WGS 84. Wire name <c>lat</c>.</summary>
    [JsonPropertyName("lat")]
    public double Lat { get; init; }

    /// <summary>Longitude in decimal degrees, WGS 84. Wire name <c>lon</c>.</summary>
    [JsonPropertyName("lon")]
    public double Lon { get; init; }

    /// <summary>
    /// The radius, in metres, containing 90% of that CEP's addresses. Wire name
    /// <c>raio_m</c>.
    /// </summary>
    [JsonPropertyName("raio_m")]
    public int RaioM { get; init; }

    /// <summary>
    /// What the point describes: <c>"logradouro"</c> for a stretch of street,
    /// <c>"localidade"</c> for a municipality centroid. Wire name
    /// <c>precisao</c>.
    /// </summary>
    [JsonPropertyName("precisao")]
    public string Precisao { get; init; } = "";

    /// <summary>
    /// <see langword="true"/> when the coordinate points at a street rather than
    /// a municipality.
    /// </summary>
    /// <remarks>
    /// Shorthand for <c>Precisao == "logradouro"</c>, which is the check to make
    /// before using the point to measure distance.
    /// </remarks>
    [JsonIgnore]
    public bool IsPrecise => Precisao == "logradouro";
}