using System.Text.Json;
using ZB.MOM.WW.Audit;

namespace ZB.MOM.WW.ScadaBridge.Commons.Messages.Management;

/// <summary>
/// Flow Debugger Live run of an inbound API method (design 2026-09-05 §7.1): executes the
/// method script on the ACTIVE central node with <paramref name="Parameters"/> as the request
/// body, tracing every routed site run, and returns the whole flow's audit events inline.
/// Deployer role; refuses on a standby with error code <c>STANDBY_NODE</c>.
/// </summary>
/// <param name="ApiMethodId">The method to run.</param>
/// <param name="Parameters">Flat JSON object of parameters (validated against the method's schema); null = none.</param>
public record FlowDebugRunMethodCommand(int ApiMethodId, JsonElement? Parameters);

/// <summary>
/// Flow Debugger Live run of a value-change trigger (design 2026-09-05 §5.3): writes
/// <paramref name="Value"/> to <paramref name="AttributeName"/> on the instance through the
/// traced routed-write path, then polls the site for the traced run(s) the change spawned.
/// </summary>
/// <param name="InstanceId">The instance to write to.</param>
/// <param name="AttributeName">Canonical attribute name.</param>
/// <param name="Value">Canonical string value to write.</param>
/// <param name="WaitSeconds">How long to wait for a spawned run before reporting <c>NO_TRIGGER_WITHIN_WINDOW</c>.</param>
public record FlowDebugRunValueChangeCommand(int InstanceId, string AttributeName, string Value, int WaitSeconds = 45);

/// <summary>
/// Flow Debugger Live run of a site script by name (design 2026-09-08). The runner resolves the
/// script's effective definition from the flattened instance configuration and branches on its
/// trigger kind: a <c>ValueChange</c>/<c>Conditional</c> script is fired by WRITING its monitored
/// attribute (<paramref name="Value"/>) and polling for the spawned run, exactly like
/// <see cref="FlowDebugRunValueChangeCommand"/>; every other kind is invoked DIRECTLY through the
/// traced routed-call path with <paramref name="Parameters"/>. Deployer role; refuses on a standby
/// with <c>STANDBY_NODE</c>.
/// </summary>
/// <param name="InstanceId">The instance the script belongs to.</param>
/// <param name="ScriptName">Canonical script name from the flattened configuration (case-insensitive).</param>
/// <param name="Parameters">Call kinds: flat JSON object validated against the script's ParameterDefinitions; null = none.</param>
/// <param name="Value">Write kinds: canonical string value to write to the trigger's attribute.</param>
/// <param name="WaitSeconds">Write kinds: how long to wait for a spawned run before <c>NO_TRIGGER_WITHIN_WINDOW</c>.</param>
public record FlowDebugRunScriptCommand(
    int InstanceId,
    string ScriptName,
    JsonElement? Parameters,
    string? Value,
    int WaitSeconds = 45);

/// <summary>
/// Flow Debugger Replay (design 2026-09-05 §7.1): returns the audit events of the execution
/// tree that <paramref name="ExecutionId"/> belongs to, from the central store.
/// </summary>
/// <param name="ExecutionId">Any execution id in the chain.</param>
public record FlowDebugReplayCommand(Guid ExecutionId);

/// <summary>The result of a Flow Debugger run or replay: the flow's audit events plus outcome metadata.</summary>
/// <param name="RootExecutionId">The root execution id (the inbound request / the value-change write).</param>
/// <param name="Completed">True when the run finished (or the replay found rows); false on timeout / no trigger.</param>
/// <param name="Error">Human-readable failure, null on success.</param>
/// <param name="ErrorCode">Machine-readable failure code, null on success.</param>
/// <param name="Events">The flow's audit events, oldest first — feed <c>FlowGraphBuilder.Build</c>.</param>
/// <param name="Truncated">True when the inline event list was capped (the audit rows remain complete).</param>
/// <param name="StartedAtUtc">When the run started.</param>
/// <param name="FinishedAtUtc">When the run finished (or the replay was served).</param>
/// <param name="LogsTruncated">
/// Step-logs (D7, 2026-09-09): true when the inline <c>FlowTraceCollector</c> dropped one
/// or more low-priority <c>ScriptLog</c> rows to protect room for step rows — the run's log lines
/// are incomplete inline, but Replay (which reads the audit store, never truncated) is complete.
/// </param>
public record FlowDebugRunResult(
    Guid RootExecutionId,
    bool Completed,
    string? Error,
    string? ErrorCode,
    IReadOnlyList<AuditEvent> Events,
    bool Truncated,
    DateTimeOffset StartedAtUtc,
    DateTimeOffset FinishedAtUtc,
    bool LogsTruncated = false);