namespace ScadaLink.Commons.Types.Flattening;

/// <summary>
/// The complete deployment package for an instance, transmitted to site clusters and stored in SQLite.
/// Contains the flattened configuration, revision hash, and deployment metadata.
///
/// JSON serialization format:
/// {
///   "instanceUniqueName": "PumpStation1",
///   "deploymentId": "dep-abc123",
///   "revisionHash": "sha256:...",
///   "deployedBy": "admin@company.com",
///   "deployedAtUtc": "2026-03-16T12:00:00Z",
///   "configuration": { /* FlattenedConfiguration */ },
///   "diff": { /* ConfigurationDiff, null for first deployment */ },
///   "previousRevisionHash": null
/// }
/// </summary>
public sealed record DeploymentPackage
{
    /// <summary>
    /// The unique name of the instance being deployed.
    /// </summary>
    public string InstanceUniqueName { get; init; } = string.Empty;

    /// <summary>
    /// Unique deployment ID for idempotency (deployment ID + revision hash).
    /// </summary>
    public string DeploymentId { get; init; } = string.Empty;

    /// <summary>
    /// SHA-256 hash of the flattened configuration for staleness detection.
    /// </summary>
    public string RevisionHash { get; init; } = string.Empty;

    /// <summary>
    /// The user who initiated the deployment.
    /// </summary>
    public string DeployedBy { get; init; } = string.Empty;

    /// <summary>
    /// UTC timestamp when the deployment was created.
    /// </summary>
    public DateTimeOffset DeployedAtUtc { get; init; }

    /// <summary>
    /// The fully resolved configuration to deploy.
    /// </summary>
    public FlattenedConfiguration Configuration { get; init; } = new();

    /// <summary>
    /// Diff against the previously deployed configuration. Null for first-time deployments.
    /// </summary>
    public ConfigurationDiff? Diff { get; init; }

    /// <summary>
    /// The revision hash of the previously deployed configuration, if any.
    /// Used for optimistic concurrency on deployment status records.
    /// </summary>
    public string? PreviousRevisionHash { get; init; }
}
