仪器注册与仪器调试 · 系统架构说明（V3.0 重梳理版）

一、总定位：一句话读新架构

二、五域分层模型

三、仪器注册（DeviceConfig）的角色重塑

3.1 新旧职责对照

3.2 设备注册页需新增的字段（改造清单）

executionMode       Local | Broker            // 按物理拓扑决定，禁止运行时混用
authorityId         broker-b01 / local-ipc01  // 所属仲裁域
brokerId            + ownerProcessId          // Broker 域归属
physicalSessionKey  psu01/main                // 同一物理连接标识（SessionGate 键）
physicalIdentity    serial:TBD-PSU01          // SN 物理身份；TBD 禁止过发布门禁
accessPolicy        Exclusive | ExclusiveChannelWithParentPermit
                    | TimeShared | SharedRead // 独占/分时的策略声明位置
safeStateProfile    PSU-SAFE-001              // 恢复/交接时的安全态模板
leasePolicy         TTL / Renew / Handover    // 全局默认 + 域级覆盖

3.3 发布流程（替代现在的"应用"按钮）

四、仪器调试（DeviceDebug）的角色重塑

4.1 最重要的拆分：监控 ≠ 写权限

4.2 维护会话状态机（对现有 DebugSessionState 的扩展）

4.3 "强制释放"按钮的正确语义

4.4 审计升级

debug_operation 保留，新增两列：lease_generation（哪一代持有者）、idempotency_key（重试去重，UNIQUE 部分索引）。任何一条历史指令可回答：谁（OwnerId+Principal）、以哪次授权（Grant 快照）、在哪个配置版本（ConfigHash）下、是否可能被重复执行过。

五、进程拓扑与责任边界

六、接口契约演化映射（现有代码 → V3.0）

七、三条核心数据流

7.1 生产写命令（从步骤到物理 I/O 的完整一跳链）

7.2 维护交接（摘要，对应文档 14.2 六步）

7.3 Broker 重启恢复

八、保持不变的部分（架构连续性资产）

九、TestStep 仪器使用规范（业务执行域使用视图）

前八章定义“系统与职责”，本章定义“使用者怎么写”——Recipe/TestStep 面向测试开发人员的使用契约。

9.1 三条铁律（先立规矩）

9.2 解析链：步骤声明逻辑能力，框架解析物理资源

步骤作者面对的只有两个概念：空位号 + 能力名。DUTContext 每空位独立保存 SN/步骤/计时/结果，120 个空位 ≠ 120 条线程（等待用异步计时）。

9.3 三种使用模式

模式 B（首选）：作用域租约 —— 一个步骤多次操作同一资源

// net472 无 await using，显式 ReleaseAsync + try/finally
public override async void Run()
{
    var req = new AcquireRequest {
        OwnerId           = RunContext.StationId,          // 如 "W02.Run-20261103-A"
        OwnerKind         = OwnerKind.Production,
        ProcessInstanceId = RunContext.ProcessInstanceId,  // boot_id+pid，防串台
        ConfigHash        = RunContext.RunSnapshot.ConfigHash,
        ResourceKeys      = new[] { "psu/psu03/ch/5", "can/can01/ch/2" }, // 框架按序展开组申请
        WaitTimeoutMs     = 60_000
    };

    ILeaseScope scope = null;
    try
    {
        scope = await coordinator.AcquireGroupAsync(req, ct);   // 同域：事务全有全无；跨域：协调式预留
        // LeaseLost 信号：续期失败/被隔离 → 立即停止下发
        var ioCts = CancellationTokenSource.CreateLinkedTokenSource(ct, scope.LeaseLost);

        var psu = executorFactory.For(scope, "psu/psu03/ch/5"); // Local/Broker 路由对步骤透明
        await psu.SetVoltageAsync(12.0, ctx.NextIdempotencyKey(), ioCts.Token);
        await psu.OutputOn(ioCts.Token);
        var v = await psu.ReadVoltage(ioCts.Token);

        Upwards.Find(12.0, v.Readback).Verdict =               // ← 判定在引擎侧（T-3）
            Math.Abs(v.Readback - 12.0) <= 0.5 ? Verdict.Pass : Verdict.Fail;
    }
    finally
    {
        // 显式异步释放：排空 I/O → 读回/安全交接 → 释放；
        // 失败进恢复，绝不假装成功；终态保存用独立有界 token，不受调用方取消影响
        if (scope != null)
            await scope.ReleaseAsync(CancellationToken.None);
    }
}

模式 C（常用封装）：类型化服务 + 双签名

// 独立调用（框架内部走完 申请→执行→释放）——适合单命令步骤
await canBus.SendFrameAsync("CAN-001", 0x100, data, ct);

// 借用作用域（推荐：与模式B组合，复用已持有租约）
await canBus.SendFrameAsync(scope.LeaseOf("can/can01/ch/2"), 0x100, data, ct);

模式选择速查

9.4 幂等键与超时重试规范

// 键的生成规则：全局唯一、可重放定位、重试不换内容只增 attempt 序号
string idemKey = $"{RunId}/{DutExecId}/{StepExecId}/attempt-{attempt}";

客户端重连必须保留原 ClientInstanceId 查询，不生成新键重发。

9.5 交接、续期与 LeaseLost：步骤作者的义务

// 步骤收尾点检查（框架在 HandoverRequested 时置位）
if (scope.HandoverRequested) return;  // 本步骤正常结束，作用域退出时安全让渡
// 注意：长 Delay 应拆成可中断的异步等待片段，保证 30s handover 窗口内能到达边界

9.6 长周期任务：交给 Broker，步骤不养线程

// 步骤侧订阅形态：提交-查询-ACK，不驻留
var sub = await broker.SubscribeAsync(new { resource = "can/can01/ch/2",
    signal = "Motor.Temp", templateId = "can.acq.motor-temp" }, ct);

// 等待信号达标（判定仍在引擎）
var sample = await sub.WaitMatchingAsync(s => s.Value > 85.0, TimeSpan.FromMinutes(30), ct);
if (sample == null) Upwards.Find().Fail($"超时未达85℃，Gap={sub.GapCount}");

await sub.UnsubscribeAsync(ct);   // 取消并确认停采/解绑

结果消费遵循 Outbox：ACK 只在结果落盘成功后发送，步骤崩溃重启用同 IdempotencyKey 找回未 ACK 结果，不重跑设备动作。

9.7 完整示例：多工位 CAN 老化步骤（B + C + 订阅 拼成真实工艺）

[Display("CAN 通信老化", Group = "Aging")]
public class CanCommAgingStep : TestStep
{
    [ResourceProperty("CAN")] public string SlotId { get; set; } = "S001";
    public int Cycles { get; set; } = 100;

    public override async void Run()
    {
        var ctx  = RunContext.Current;                     // Run/DUT/Step 关联ID
        var auto = AgingRuntime.Coordinator;               // IResourceCoordinator
        var cans = AgingRuntime.CanBus;                    // ICanBusService(类型化)

        var req  = ctx.BuildAcquire(new[] { "can/" + ctx.SlotOf(SlotId) + "/ch/2" });
        using var cts = Utils.LinkedWithVerdictCancel(Upwards);

        ILeaseScope scope = await auto.AcquireGroupAsync(req, cts.Token);
        try
        {
            var lease = scope.LeaseOf(ctx.ResourceOf(SlotId));

            // ① 起周期激励（驻留 Broker，随租约失效自动停）
            var periodic = await lease.StartTemplateAsync("can.periodic.keepalive",
                new { frameId = 0x3E0, periodMs = 500 }, cts.Token);

            // ② 订阅响应信号
            var sub = await lease.SubscribeAsync("can.acq.response-0x3E1", cts.Token);

            for (int i = 0; i < Cycles && !scope.HandoverRequested; i++)
            {
                await cans.SendFrameAsync(lease, 0x100 + (uint)i, ctx.Payload(i),
                    ctx.NextIdempotencyKey(), cts.Token);

                var echo = await sub.WaitMatchingAsync(f => f.MatchRequest(0x100 + i),
                    TimeSpan.FromSeconds(2), cts.Token);

                if (echo == null) { Verdict = Verdict.Fail; break; }  // 判定在引擎
                Report.Sample(i, echo);                                // 采样走结果通路
            }

            await periodic.StopAsync(cts.Token);   // 周期任务显式停止并“确认停止”
            await sub.UnsubscribeAsync(cts.Token);
        }
        finally
        {
            await scope.ReleaseAsync(CancellationToken.None);  // 异步、可失败进恢复
        }
    }
}

9.8 步骤生命周期时序

OnPlanLoad    解析 Slot+Capability → 预检配置存在性（不占资源）
Run() 入口     DUTContext 状态检查 → AcquireGroup（排队等待=异步，不阻塞他位）
持租阶段      类型化操作/订阅 → 每命令带 Grant+IdemKey+Deadline → 读回质量核对
退出边界      HandoverRequested? → 让渡或续跑
finally       停后台任务(确认) → ReleaseAsync → 结果 Outbox ACK 后终态保存
异常路径      LeaseLost / Unknown → 停止下发 → 上报 → 交给恢复/RunService 决策（不自动判合否）

9.9 反模式清单（TestStep 侧汇总）

十、结论