namespace ZB.MOM.WW.ScadaBridge.Commons.Entities.SecuredWrites;

/// <summary>
/// Central operational state row for a two-person ("secured") write through its
/// lifecycle. One row per pending write in the
/// central <c>PendingSecuredWrites</c> MS SQL table — append-once at submission then
/// mutated as the request is approved/rejected and executed against the target.
/// </summary>
/// <remarks>
/// <para>
/// Persistence-ignorant POCO; the EF Core mapping lives in the Configuration Database
/// component (<c>PendingSecuredWriteEntityTypeConfiguration</c>). Unlike the partitioned
/// append-only <c>AuditLog</c> this entity backs mutable operational state on a standard
/// non-partitioned table on the <c>[PRIMARY]</c> filegroup; no DB-role restriction
/// applies. It mirrors the <see cref="ZB.MOM.WW.ScadaBridge.Commons.Entities.Audit.SiteCall"/>
/// entity/config/repository shape.
/// </para>
/// <para>
/// All timestamps are UTC, like every timestamp in the system.
/// </para>
/// </remarks>
public sealed class PendingSecuredWrite
{
    /// <summary>Surrogate identity key assigned by the store.</summary>
    public long Id { get; set; }

    /// <summary>Site id the secured write targets.</summary>
    public required string SiteId { get; set; }

    /// <summary>Data connection name within the site the write is routed through.</summary>
    public required string ConnectionName { get; set; }

    /// <summary>Fully-qualified tag path the value is written to.</summary>
    public required string TagPath { get; set; }

    /// <summary>JSON-serialised value to write (interpreted per <see cref="ValueType"/>).</summary>
    public required string ValueJson { get; set; }

    /// <summary>The target data type name (e.g. <c>Boolean</c>, <c>Double</c>, <c>String</c>).</summary>
    public required string ValueType { get; set; }

    /// <summary>
    /// Lifecycle status — one of
    /// <c>Pending|Approved|Rejected|Executed|Failed|Expired</c>.
    /// </summary>
    public required string Status { get; set; }

    /// <summary>The operator who submitted (requested) the secured write.</summary>
    public required string OperatorUser { get; set; }

    /// <summary>Optional free-text comment supplied by the requesting operator.</summary>
    public string? OperatorComment { get; set; }

    /// <summary>UTC instant the secured write was submitted.</summary>
    public required DateTime SubmittedAtUtc { get; set; }

    /// <summary>The verifier who approved/rejected the write; <c>null</c> while pending.</summary>
    public string? VerifierUser { get; set; }

    /// <summary>Optional free-text comment supplied by the verifier on decision.</summary>
    public string? VerifierComment { get; set; }

    /// <summary>UTC instant the write was approved/rejected; <c>null</c> while pending.</summary>
    public DateTime? DecidedAtUtc { get; set; }

    /// <summary>UTC instant the approved write was executed against the target; <c>null</c> until executed.</summary>
    public DateTime? ExecutedAtUtc { get; set; }

    /// <summary>Most recent execution error message; <c>null</c> when no failure has occurred.</summary>
    public string? ExecutionError { get; set; }
}
