using System;
|
using System.Threading;
|
using System.Threading.Tasks;
|
|
namespace Aging.Infrastructure.Contracts
|
{
|
/// <summary>
|
/// 自动化设备门面：为全自动测试程序提供"一次调用/一次作用域"的语义，
|
/// 内部封装资源预约、驱动分派、审计。
|
///
|
/// 使用场景对比：
|
/// 手动调试（DeviceDebug）：需要 UI 逐步控制会话状态（ReadOnly → Maintenance）。
|
/// 全自动测试（TestStep）：只关心"发命令拿结果"，不希望暴露状态机。
|
/// 本接口面向后者。
|
/// </summary>
|
public interface IAutoDeviceFacade
|
{
|
/// <summary>
|
/// 一次性执行：内部自动完成 申请租约 → 打开会话 → 执行 → 关闭会话 → 释放租约。
|
/// 适合单条命令调用。多条命令建议使用 AcquireAsync 复用租约。
|
/// </summary>
|
Task<DeviceCommandResult> ExecuteAsync(
|
string deviceId, string command, CancellationToken ct = default);
|
|
/// <summary>
|
/// 一次性查询：内部自动完成完整生命周期。
|
/// </summary>
|
Task<DeviceCommandResult> QueryAsync(
|
string deviceId, string query, CancellationToken ct = default);
|
|
/// <summary>
|
/// 申请作用域租约：占用设备，返回 lease 句柄。
|
/// using 结束时（Dispose）自动关会话 + 释放租约。
|
/// 同一 lease 内的多次调用共享同一份资源占用，保证原子性。
|
/// </summary>
|
/// <param name="deviceId">设备标识</param>
|
/// <param name="stepName">测试步骤名称（用于日志/审计标识）</param>
|
/// <param name="ct">取消令牌；申请超时视为失败</param>
|
Task<IAutoDeviceLease> AcquireAsync(
|
string deviceId, string stepName, CancellationToken ct = default);
|
|
/// <summary>
|
/// 默认租约超时（秒）。可申请更短的 per-call 超时。
|
/// </summary>
|
int DefaultLeaseTimeoutSeconds { get; set; }
|
}
|
|
/// <summary>
|
/// 自动化设备作用域租约。
|
/// 一次申请，多次调用；Dispose 时自动释放。
|
/// </summary>
|
public interface IAutoDeviceLease : IDisposable
|
{
|
/// <summary>本次租约关联的设备 ID</summary>
|
string DeviceId { get; }
|
|
/// <summary>本次租约的内部会话标识（用于审计关联）</summary>
|
string SessionId { get; }
|
|
/// <summary>测试步骤名称</summary>
|
string StepName { get; }
|
|
/// <summary>申请时刻</summary>
|
DateTime AcquiredAt { get; }
|
|
/// <summary>租约是否已被释放</summary>
|
bool IsReleased { get; }
|
|
/// <summary>
|
/// 在租约作用域内发送命令。
|
/// </summary>
|
Task<DeviceCommandResult> ExecuteAsync(string command, CancellationToken ct = default);
|
|
/// <summary>
|
/// 在租约作用域内查询。
|
/// </summary>
|
Task<DeviceCommandResult> QueryAsync(string query, CancellationToken ct = default);
|
|
/// <summary>V3.0：租约失效（续期连续失败/被回收）时触发；订阅者应停止下发。</summary>
|
event EventHandler LeaseLost;
|
|
/// <summary>V3.0：显式异步释放。</summary>
|
Task ReleaseAsync(CancellationToken ct = default);
|
|
/// <summary>V3.0：维护让渡请求（Draining 预留，MVP 恒 false）。</summary>
|
bool HandoverRequested { get; }
|
}
|
}
|
