aivfo-tl-3.0/ivf_tl_operate_2.0/ivf_tl_Operate/ViewModel/HouseDebugPageViewModel.cs

using CommunityToolkit.Mvvm.ComponentModel;
using ivf_tl_Entity.CameraEntitys;
using ivf_tl_Entity.ComEntitys;
using ivf_tl_Entity.DebugEntitys;
using ivf_tl_Entity.DTO;
using ivf_tl_Entity.GlobalEnums;
using ivf_tl_Operate.Converts;
using ivf_tl_Operate.Debug;
using ivf_tl_Operate.Helpers;
using ivf_tl_Services;
using IvfTl.Hardware;
using IvfTl.Hardware.Impl;
using IvfTl.AutoFocus.Layout;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using System;
using System.Collections.Generic;
using System.Collections.ObjectModel;
using System.Configuration;
using System.DirectoryServices.ActiveDirectory;
using System.IO;
using System.Linq;
using System.Reflection.Metadata;
using System.Text;
using System.Threading.Tasks;
using System.Windows;
using static ivf_tl_Operate.CustomUserControls.RecordBox;
using System.Windows.Documents;

namespace ivf_tl_Operate.ViewModel
{
    public partial class HouseDebugPageViewModel : ObservableObject
    {
        public event Action<string> MessageEvent;

        public event Action<string, int, int> AddPicEvent;

        public event Action OpenVideoEvent;

        // M1-B2：调试页不再 new ComBin/new Camera 开第二个物理串口/相机。
        // 全部硬件动作走借用到的 HAL 句柄(_halLease.Serial / _halLease.Camera)——与采集端同一物理实例，
        // 配合 T1.3(前台借用时采集端暂停让出 ComBin)，端口/相机占用根除(审计 B2)。
        /// <summary>借用到的串口句柄(与采集端同一实例)；未持借用时为 null。</summary>
        private IvfTl.Hardware.ISerialChannel Serial => _halLease?.Serial;
        /// <summary>借用到的相机句柄(与采集端同一实例)；未持借用时为 null。</summary>
        private IvfTl.Hardware.ICamera Cam => _halLease?.Camera;

        /// <summary>
        /// M1-03 HAL 前台借用凭证。打开调试页时向 HAL 申请该舱独占借用(HardwareUser.OperateDebug)，
        /// HAL 自动暂停 control 对该舱的后台采集；关闭调试页 Dispose 归还，HAL 恢复采集。
        /// ⚠ 待验证 V-024：借用→暂停采集→归还恢复时序（调试取图 vs 后台采集切换不占用/不死锁，01 §3 M1 必过）。
        /// 说明（代码隔离 + 范围控制）：调试页 ComBin/Camera 仍用 operate 侧 ivf_tl_Entity 具体类型——
        /// 因调试栈方法更全(Write*EEPROM / 电机正反向 / RawToRgb 等)，control 侧 SerialHelper ComBin 未覆盖，
        /// 折叠进 HAL ISerialChannel 属 M2 统一。M1 通过 HAL 借用闸门保证"同舱同一时刻单一使用者"，
        /// 杜绝与后台采集同时 Open 同 COM 口/Init 同相机。
        /// </summary>
        private IHardwareLease _halLease = null;

        // ── 自动对焦重构 D2-02-T3.4：调试页标定改"经 control 协作"，不再 operate 本地自建 CalibrationEngine ──
        /// <summary>
        /// 调试会话客户端:经 control 本地 HTTP /debug/acquire 借该舱硬件，拿 sessionId(存 CurrentSessionId)。
        /// control 独立进程持有真硬件;operate 进程内 HAL 是空壳(从不 ScanDevices)，故借硬件/预览/标定全走此 HTTP 协作。
        /// 借到后起心跳;ComHouseUnit 归还。会话失效回调提示重进调试。
        /// </summary>
        private DebugSessionClient _sessionClient;

        /// <summary>
        /// 16 孔标定协作客户端:复用同一 sessionId，封 control /debug/calibrate/{start,progress,recalibrate,stop}。
        /// acquire 成功后构造;ComHouseUnit 释放。
        /// </summary>
        private CalibrationClient _calibClient;

        /// <summary>标定进度轮询任务的取消源(IsRunning 转 false 或停止标定时取消)。</summary>
        private System.Threading.CancellationTokenSource _calibPollCts;

        /// <summary>
        /// 当前housesn
        /// </summary>
        public int CurrentHouseId { get; set; } = 1;

        /// <summary>当前借用会话 id(D2-02 第三阶段 acquire 时赋值;第二阶段预览用)。</summary>
        public string CurrentSessionId { get; set; }

        /// <summary>
        /// 当前ccdID
        /// </summary>
        public int CurrentCCDId { get; set; } = 0;

        /// <summary>
        /// 所有舱室
        /// </summary>
        public List<HouseInfo> HouseList { get; set; } = new List<HouseInfo>();

        /// <summary>
        /// 仪器设置
        /// </summary>
        public TLSetting tLSetting { get; set; } = new TLSetting();

        /// <summary>
        /// 自动对焦和拍照位置
        /// </summary>
        public List<HousePhotographLocation> ccdPhoto = new List<HousePhotographLocation>();

        /// <summary>
        /// 水平电机位置
        /// </summary>
        public List<HouseWellSetting> houseWellSettingList = new List<HouseWellSetting>();

        [ObservableProperty]
        private ObservableCollection<string> messageInfoList = new ObservableCollection<string>();

        [ObservableProperty]
        private decimal temperature = 0m;

        [ObservableProperty]
        private decimal pressure = 0m;

        [ObservableProperty]
        private string doorState = null;

        [ObservableProperty]
        private string ledState = null;

        [ObservableProperty]
        private int currentWell = 0;

        [ObservableProperty]
        private int currentFocal = 0;

        /// <summary>
        /// 结束抓图
        /// </summary>
        public bool IsStop { get; set; } = false;

        /// <summary>
        /// M2-05 一键标定中止标志（工程师可中止；每 well 间检查）。
        /// </summary>
        public bool IsStopCalibrate { get; set; } = false;

        /// <summary>
        /// M2-05 一键标定是否进行中（UI 据此禁用重复触发）。
        /// </summary>
        [ObservableProperty]
        private bool isCalibrating = false;

        /// <summary>
        /// M2-05 场景A 一键标定 16 well 实时结果（合格绿/伪峰红，含 FocusZ/峰比/偏移）。
        /// View 绑定此集合做 4x4 实时呈现（沿用调试页内呈现，不另开 CalibWindow）。
        /// </summary>
        public ObservableCollection<WellCalibUiItem> CalibResults { get; } = new ObservableCollection<WellCalibUiItem>();

        /// <summary>
        /// 垂直电机当前位置
        /// </summary>
        [ObservableProperty]
        private int currentVer = 0;

        /// <summary>
        /// 水平电机当前位置
        /// </summary>
        [ObservableProperty]
        private int currentHor = 0;


        [ObservableProperty]
        private HouseInfo currentHouse = null;

        [ObservableProperty]
        private int houseVentTimeE = 0;

        public HouseDebugPageViewModel()
        {
            //HouseList = AppData.Instance.HttpHelper.GetSettingHouseApi(AppData.Instance.TlSn);
            //CurrentHouse = HouseList.FirstOrDefault(x => x.houseSn == 1);
        }

        private void ExLog(Exception ex, string name)
        {
            AppData.Instance.LogHelper.ExceptionLog(ex, $"HouseDebugPageViewModel.{name}", LogEnum.RunException);
        }

        private void ErrorLog(string message, LogEnum logType)
        {
            AppData.Instance.LogHelper.TLLog($"HouseDebugPageViewModel.{message}", logType);
        }

        public void Start(ref string errora)
        {
            try
            {
                SerialBin serialBin = new SerialBin();
                serialBin.TLLogEvent += AppData.Instance.LogHelper.TLLog;
                serialBin.ExceptionLogEvent += AppData.Instance.LogHelper.ExceptionLog;
                serialBin.HouseLogEvent += AppData.Instance.LogHelper.HouseLog;

                var errorList = serialBin.UpdataCamera();
                AppData.Instance.LogHelper.TLLog($"ccdidsn:{JsonConvert.SerializeObject(serialBin.CCDidSn)}", LogEnum.RunRecord);
                if (errorList.Any())
                {
                    errora = $"获取相机Id和CCDSN错误{JsonConvert.SerializeObject(errorList)}";
                    AppData.Instance.LogHelper.TLLog(errora, LogEnum.RunRecord);
                    return;
                }

                errorList = serialBin.Start(ConfigurationManager.AppSettings["autoFocus"].ToString());
                AppData.Instance.LogHelper.TLLog($"舱室信息:{JsonConvert.SerializeObject(serialBin.SerialModels)}", LogEnum.RunRecord);
                AppData.Instance.LogHelper.TLLog($"E方数据:{JsonConvert.SerializeObject(serialBin.HouseEEPROInfos)}", LogEnum.RunRecord);

                if (errorList.Any())
                {
                    errora = $"获取串口信息错误{JsonConvert.SerializeObject(errorList)}";
                    AppData.Instance.LogHelper.TLLog(errora, LogEnum.RunRecord);
                    return;
                }

                var modelCount = serialBin.SerialModels.Count;
                if (modelCount != 11)
                {
                    //string messageinfo = $"检测到{modelCount}个模块，是否继续运行？";
                     string messageinfo = $" Detected {modelCount} cabin, are you sure to run？";
                    MessageBoxResult aaa = MessageBox.Show(messageinfo, KeyToStringConvert.GetLanguageStringByKey("C0171"), MessageBoxButton.YesNo, MessageBoxImage.Question, MessageBoxResult.No, MessageBoxOptions.DefaultDesktopOnly);
                    if (aaa != MessageBoxResult.Yes)
                    {
                        errora = "结束";
                        return;
                    }
                }
                List<int> listIntRunHoues = serialBin.SerialModels.Select(x => x.houseSn).ToList();
                TLInitData tLInitData = new TLInitData();
                tLInitData.tlSn = $"NEO-1-{serialBin.TLNum}";
                tLInitData.softwareVersion = "V2.0.0";
                tLInitData.verticalMotorPulseMax = 125000;
                tLInitData.houseLinkDataList = serialBin.SerialModels.OrderBy(x => x.houseSn).ToList();
                foreach (var item in serialBin.HouseEEPROInfos)
                {
                    item.tlSn = tLInitData.tlSn;
                }
                tLInitData.houseEEPROInitDTOList = serialBin.HouseEEPROInfos.OrderBy(x => x.houseSn).ToList();

                AppData.Instance.LogHelper.TLLog($"舱室信息:{JsonConvert.SerializeObject(tLInitData)}", LogEnum.RunRecord);

                SettingDataApiData settingDataApiData = AppData.Instance.HttpHelper.GetSettingDataApi(tLInitData);
                if (settingDataApiData == null)
                {
                    errora = $"{tLInitData.tlSn}获取仪器设置失败";
                    return;
                }

                AppData.Instance.LogHelper.TLLog(JsonConvert.SerializeObject(settingDataApiData), LogEnum.RunRecord);

                tLSetting = AppData.Instance.ConvertHelper.ConvertToTLSetting(settingDataApiData.tlInfo, settingDataApiData.tlSetting);
                ccdPhoto = settingDataApiData.housePhotographLocation;
                houseWellSettingList = settingDataApiData.houseWellSettingList;
                HouseList = settingDataApiData.houseList;
                CurrentHouse = HouseList.FirstOrDefault(x => x.houseSn == 1);
            }
            catch (Exception ex)
            {
                AppData.Instance.LogHelper.ExceptionLog(ex, $"调试模式初始化", LogEnum.RunException);
                errora = $"调试模式初始化异常:{ex.Message}";
            }
        }

        public async Task ComHouseInit()
        {
            await Task.Run(async () =>
            {
                try
                {
                    var currentHouse = HouseList.FirstOrDefault(x => x.houseSn == CurrentHouseId);
                    if (currentHouse == null)
                    {
                        AddMessageInfo($"[{CurrentHouseId}]未获取到舱室信息，无法进入调试");
                        return;
                    }

                    // D2-02-T3.4：先经 control HTTP 协作借该舱调试会话拿 sessionId(预览/标定/会话命令均依赖)。
                    // control 独立进程持真硬件;operate 进程内 HAL 是空壳(从不 ScanDevices)、下面的本地 lease.Serial 取不到，
                    // 故借硬件的"真正入口"是这里的 HTTP acquire。放在本地 HAL 借用之前，确保 sessionId 一定先建立。
                    await AcquireDebugSessionAsync(currentHouse.houseSn);

                    // M1-03/B2 HAL: 向 HAL 申请该舱前台借用——HAL 暂停 control 对本舱采集(T1.3)并让采集端让出串口/相机，
                    // 调试页随后复用借用到的同一物理句柄(lease.Serial/lease.Camera)，不再 new 第二个 ComBin/Camera 开同口/同相机。
                    try
                    {
                        var gate = HardwareAccessLayer.Instance.GetHouseGate(currentHouse.houseSn);
                        _halLease = gate.Acquire(HardwareUser.OperateDebug);
                        if (_halLease == null)
                        {
                            AddMessageInfo($"[{currentHouse.houseSn}]该舱正被占用(采集/对焦)，借用超时，稍后重试");
                            return;
                        }
                    }
                    catch (Exception le)
                    {
                        AddMessageInfo($"[{currentHouse.houseSn}]HAL 借用异常:{le.Message}");
                        return;
                    }

                    if (Serial == null)
                    {
                        AddMessageInfo($"[{currentHouse.houseSn}]借用到的串口句柄为空(HAL 未 ScanDevices 到本舱?)，无法进入调试");
                        return;
                    }
                    if (!Serial.IsOpen)
                    {
                        // 物理口由采集端持有并保持打开；T1.3 暂停只停发不关口。此处兜底再开一次(幂等)。
                        if (!Serial.Open())
                        {
                            AddMessageInfo($"[{currentHouse.houseSn}][{currentHouse.housePort}]借用串口未打开且兜底打开失败");
                            return;
                        }
                    }
                    AddMessageInfo($"[{currentHouse.houseSn}][{currentHouse.housePort}]调试已复用采集端串口句柄(同一物理口)");

                    // 相机：复用借用到的同一相机句柄。采集端通常已 Init+SetOpMode；仅在未 Init 时兜底 Init，
                    // 然后统一设单帧采集模式(mode=0)供调试抓图，避免重复 Init 扰动采集端相机。
                    if (Cam == null)
                    {
                        AddMessageInfo($"[{currentHouse.houseSn}]本舱无相机句柄(buffer/无相机舱?)，跳过相机初始化");
                    }
                    else
                    {
                        if (!Cam.IsInit)
                        {
                            int cameraInit = Cam.Init();
                            AddMessageInfo($"[CCD模块初始化]CCDID={CurrentCCDId},SN={currentHouse.ccdSn} 初始化结果:{cameraInit}[0=成功]");
                            if (cameraInit != 0) return;
                        }
                        int cameraSetMode = Cam.SetOpMode();
                        AddMessageInfo($"[CCD模块初始化]开启图像捕捉结果:{cameraSetMode}[0=成功]");
                        if (cameraSetMode != 0) return;
                    }
                    var currentHorSetting = houseWellSettingList.FirstOrDefault(x => x.houseSn == currentHouse.houseSn && x.wellSn == 1);
                    if (currentHorSetting == null)
                    {
                        AddMessageInfo($"[{currentHouse.houseSn}][{currentHouse.housePort}][未获取到1号well的水平电机位置]");
                        return;
                    }

                    //OpenVideoEvent?.Invoke();

                    var verNewValue = currentHorSetting.eepromClearPosition;
                    var cc = ccdPhoto.FirstOrDefault(x => x.houseSn == currentHouse.houseSn && x.wellSn == 1);
                    if (cc != null)
                    {
                        verNewValue = cc.clearestPosition;
                    }

                    // Task3.4b：进入调试的握手/电机归位/读数序列同走 control(operate Serial 空壳)。
                    await RunDebugCommandAsync("进入调试-握手", "ShakeHands", null, new { houseSn = currentHouse.houseSn });

                    await OpenLed();

                    await RunDebugCommandAsync("进入调试-水平复位", "HorizontalReset", new { motorDelay = tLSetting.motorDelay }, new { houseSn = currentHouse.houseSn });
                    CurrentHor = 0;
                    CurrentWell = 0;

                    await RunDebugCommandAsync("进入调试-水平到位", "HorizontalMoveTo",
                        new { pos = currentHorSetting.horizontalMotorPosition, motorDelay = tLSetting.motorDelay }, new { houseSn = currentHouse.houseSn });
                    CurrentHor = currentHorSetting.horizontalMotorPosition;
                    CurrentWell = 1;

                    await RunDebugCommandAsync("进入调试-垂直复位", "VerticalReset", new { motorDelay = tLSetting.motorDelay }, new { houseSn = currentHouse.houseSn });
                    CurrentVer = 0;
                    CurrentFocal = 0;

                    await RunDebugCommandAsync("进入调试-垂直到位", "VerticalMoveTo",
                        new { pos = verNewValue, motorDelay = tLSetting.motorDelay }, new { houseSn = currentHouse.houseSn });
                    CurrentVer = verNewValue;
                    CurrentFocal = 1;

                    await RedTem();
                    await RedPre();
                    await RedDoor();
                    await RedVentTime();
                    return;
                }
                catch (Exception ex)
                {
                    AppData.Instance.LogHelper.ExceptionLog(ex, "调试模式初始化", LogEnum.RunException);
                    AddMessageInfo($"初始化异常:{ex.Message}");
                    return;
                }
            });
        }

        public bool ComHouseUnit()
        {
            try
            {
                // D2-02-T3.4：先停标定轮询、归还 control 协作会话(停心跳)，再归还本地 HAL 借用。
                StopCalibPolling();
                ReleaseDebugSession();

                // M1-B2：物理串口/相机由采集端(control)持有，调试只归还借用，绝不 ClosePort/UnInit 关物理口——
                // 否则会把采集端的口/相机一并关掉。归还后 HAL 触发 ResumeCapture 恢复本舱采集(T1.3)。
                if (_halLease != null)
                {
                    try { _halLease.Dispose(); } catch { }
                    _halLease = null;
                    AddMessageInfo($"[{CurrentHouseId}]已归还借用，恢复后台采集");
                }
                return true;
            }
            catch (Exception ex)
            {
                AppData.Instance.LogHelper.ExceptionLog(ex, "调试模式卸载", LogEnum.RunException);
                AddMessageInfo($"卸载异常:{ex.Message}");
                return false;
            }
        }

        #region D2-02-T3.4 调试会话协作(借硬件拿 sessionId / 归还)

        /// <summary>
        /// 向 control 借该舱调试会话:POST /debug/acquire {houseSn} → 拿 sessionId 存 CurrentSessionId，
        /// 并构造 16 孔标定协作客户端 CalibrationClient(复用同一 sessionId)。
        /// control 借用成功会起心跳;会话失效(SESSION_EXPIRED)回调提示工程师重进调试。
        /// 借不到(BUSY/会话异常)只提示不抛——预览/标定将因 CurrentSessionId 为空而拒绝执行。
        /// </summary>
        private async Task AcquireDebugSessionAsync(int houseSn)
        {
            try
            {
                // 关旧会话(重复初始化时)。
                ReleaseDebugSession();

                var client = new DebugSessionClient(ControlClient.BaseUrl);
                client.OnSessionExpired = () =>
                {
                    CurrentSessionId = null;
                    AddMessageInfo("⚠ 调试会话已失效(control 端超时回收)，请退出后重新进入调试");
                };

                var r = await client.AcquireAsync(houseSn);
                if (!r.Ok || string.IsNullOrEmpty(r.SessionId))
                {
                    try { client.Dispose(); } catch { }
                    AddMessageInfo($"[{houseSn}]借调试会话失败:{r.Code}/{r.Error}(预览与标定不可用，请确认 control 已托管该舱)");
                    return;
                }

                _sessionClient = client;
                CurrentSessionId = r.SessionId;
                // 标定协作客户端复用同一 baseUrl + sessionId。
                _calibClient = new CalibrationClient(ControlClient.BaseUrl, r.SessionId);

                string cultMsg = r.Cultivating ? $"(注意:该舱培养中，胚胎 {r.EmbryoCount} 枚)" : "";
                AddMessageInfo($"[{houseSn}]调试会话已建立 sessionId={r.SessionId}{cultMsg}");
            }
            catch (Exception ex)
            {
                ExLog(ex, "AcquireDebugSessionAsync");
                AddMessageInfo($"[{houseSn}]借调试会话异常:{ex.Message}");
            }
        }

        /// <summary>归还调试会话(停心跳、通知 control)并释放协作客户端。幂等。
        /// release 的 HTTP POST 放后台跑(避免 control 失联时 HttpClient 默认 100s 超时卡死 UI 线程)；
        /// DebugSessionClient.ReleaseAsync 在 await POST 前已同步置闸+停心跳，故心跳即时停止、不必等 POST。</summary>
        private void ReleaseDebugSession()
        {
            var calib = _calibClient; _calibClient = null;
            if (calib != null) { try { calib.Dispose(); } catch { } }

            var sc = _sessionClient; _sessionClient = null;
            if (sc != null)
            {
                // 后台 best-effort 归还+释放;失败也无妨(control 端 TTL 看门狗会超时回收会话)。
                Task.Run(async () =>
                {
                    try { await sc.ReleaseAsync(); } catch { }
                    try { sc.Dispose(); } catch { }
                });
            }
            CurrentSessionId = null;
        }

        #endregion


        // ── 自动对焦重构 D2-02-T3.4b:调试页手动命令统一走 control 的 /debug/command ──
        // operate 进程内 HAL 是空壳(从不 ScanDevices)、Serial/Cam 在真机上取不到真硬件;
        // control 独立进程持真硬件,故手动电机/光源/阀/EEPROM/曝光全经 _sessionClient.CommandAsync 下发。
        // 埋点不丢:沿用 OperationScope(同 M8-G3-1),据 CommandAsync 返回 Ok 记成功/失败。
        /// <summary>
        /// 统一执行一个调试手动命令:经 control HTTP /debug/command 下发 + 操作日志埋点 + 失败/会话失效提示。
        /// 返回 control 的 AcquireResult(读命令的值从 r.Result 取);会话未建立或失败返回 null/!Ok。
        /// </summary>
        private async Task<AcquireResult> RunDebugCommandAsync(string operation, string op, object args, object input)
        {
            if (_sessionClient == null || string.IsNullOrEmpty(CurrentSessionId))
            {
                AddMessageInfo($"[{operation}]未持调试会话,请重新进入调试页");
                return null;
            }
            using var _op = Aivfo.OperationLog.OperationLogger.Begin("对焦调试", operation, houseSn: CurrentHouseId);
            try { _op.Input(input); } catch { }
            AcquireResult r;
            try
            {
                r = await _sessionClient.CommandAsync(op, args);
            }
            catch (Exception ex)
            {
                _op.Fail(ex.GetType().Name + ": " + ex.Message);
                AddMessageInfo($"[{operation}]下发异常:{ex.Message}");
                return null;
            }
            if (r == null) { _op.Fail("空响应"); AddMessageInfo($"[{operation}]无响应"); return null; }
            if (r.Ok) { _op.Success(r.Result); }
            else
            {
                _op.Fail(r.Code + ": " + r.Error);
                if (r.Code == "SESSION_EXPIRED")
                    AddMessageInfo($"[{operation}]调试会话已失效,请重新进入调试页");
                else
                    AddMessageInfo($"[{operation}]失败:{r.Error}");
            }
            return r;
        }

        /// <summary>
        /// 读温度
        /// </summary>
        public async Task RedTem()
        {
            var r = await RunDebugCommandAsync("读温度", "ReadTemp", null, new { houseSn = CurrentHouseId });
            if (r != null && r.Ok && r.Result != null && decimal.TryParse(r.Result.ToString(), out var t)) Temperature = t;
        }

        /// <summary>
        /// 读压力
        /// </summary>
        public async Task RedPre()
        {
            var r = await RunDebugCommandAsync("读压力", "ReadPressure", null, new { houseSn = CurrentHouseId });
            if (r != null && r.Ok && r.Result != null && decimal.TryParse(r.Result.ToString(), out var p)) Pressure = p;
        }

        /// <summary>
        /// 读舱门
        /// </summary>
        public async Task RedDoor()
        {
            var r = await RunDebugCommandAsync("读舱门", "ReadDoor", null, new { houseSn = CurrentHouseId });
            if (r == null || !r.Ok) return;
            string DoorStateString = r.Result?.ToString();
            if(DoorStateString == "关闭")
            {
                DoorState = KeyToStringConvert.GetLanguageStringByKey("C0305");
            }
            if (DoorStateString == "打开")
            {
                DoorState = KeyToStringConvert.GetLanguageStringByKey("C0306");
            }


        }

        /// <summary>
        /// 打开Led灯
        /// </summary>
        public async Task OpenLed()
        {
            // M8-G3-1：LED 开关为串口设备命令入口,补操作日志埋点（module=对焦调试）。
            await RunDebugCommandAsync("打开LED灯", "OpenLed", null, new { houseSn = CurrentHouseId });
            LedState = KeyToStringConvert.GetLanguageStringByKey("C0306");
            //LedState = "开启";
        }

        /// <summary>
        /// 关闭Led灯
        /// </summary>
        public async Task CloseLed()
        {
            // M8-G3-1：LED 开关为串口设备命令入口,补操作日志埋点（module=对焦调试）。
            await RunDebugCommandAsync("关闭LED灯", "CloseLed", null, new { houseSn = CurrentHouseId });
            //LedState = "关闭";
            LedState = KeyToStringConvert.GetLanguageStringByKey("C0305");
        }

        /// <summary>
        /// 打开进气阀
        /// </summary>
        public async Task OpenIntake()
        {
            // M8-G3-1：进气阀开关为串口设备命令入口,补操作日志埋点（module=对焦调试）。
            await RunDebugCommandAsync("打开进气阀", "OpenIntake", null, new { houseSn = CurrentHouseId });
        }

        /// <summary>
        /// 关闭进气阀
        /// </summary>
        public async Task CloseIntake()
        {
            // M8-G3-1：进气阀开关为串口设备命令入口,补操作日志埋点（module=对焦调试）。
            await RunDebugCommandAsync("关闭进气阀", "CloseIntake", null, new { houseSn = CurrentHouseId });
        }

        /// <summary>
        /// 打开排气阀
        /// </summary>
        public async Task OpenExhaust()
        {
            // M8-G3-1：排气阀开关为串口设备命令入口,补操作日志埋点（module=对焦调试）。
            await RunDebugCommandAsync("打开排气阀", "OpenExhaust", null, new { houseSn = CurrentHouseId });
        }


        /// <summary>
        /// 关闭排气阀
        /// </summary>
        public async Task CloseExhaust()
        {
            // M8-G3-1：排气阀开关为串口设备命令入口,补操作日志埋点（module=对焦调试）。
            await RunDebugCommandAsync("关闭排气阀", "CloseExhaust", null, new { houseSn = CurrentHouseId });
        }

        /// <summary>
        /// 舱室补气
        /// </summary>
        public async Task HouseAeration()
        {
            // M8-G3-1：舱室补气为串口设备命令入口,补操作日志埋点（module=对焦调试）。
            await RunDebugCommandAsync("舱室补气", "HouseAeration", null, new { houseSn = CurrentHouseId });
        }

        /// <summary>
        /// 舱室排气
        /// </summary>
        public async Task HouseVent()
        {
            // M8-G3-1：舱室排气为串口设备命令入口,补操作日志埋点（module=对焦调试）。
            await RunDebugCommandAsync("舱室排气", "HouseVent", null, new { houseSn = CurrentHouseId });
        }


        /// <summary>
        /// 写舱室进气阀时间
        /// </summary>
        /// <param name="newValue"></param>
        public async Task WriteOpenIntakeTime(int newValue)
        {
            // M8-G3-1：写舱室进气阀时间为写 EEPROM 设备命令入口,补操作日志埋点（module=对焦调试）。
            await RunDebugCommandAsync("写舱室进气阀时间", "WriteOpenIntakeTime", new { value = newValue },
                new { houseSn = CurrentHouseId, newValue });
        }

        /// <summary>
        /// 写舱室排气阀时间
        /// </summary>
        /// <param name="newValue"></param>
        public async Task WriteOpenVentTime(int newValue)
        {
            // M8-G3-1：写舱室排气阀时间为写 EEPROM 设备命令入口,补操作日志埋点（module=对焦调试）。
            var r = await RunDebugCommandAsync("写舱室排气阀时间", "WriteOpenVentTime", new { value = newValue },
                new { houseSn = CurrentHouseId, newValue });
            if (r == null || !r.Ok)
            {
                AddMessageInfo($"[排气阀时间]下发失败,仅本地暂存{newValue}");
            }
            HouseVentTimeE = newValue;
        }

        /// <summary>
        /// 读舱室排气阀打开时间
        /// </summary>
        public async Task RedVentTime()
        {
            var r = await RunDebugCommandAsync("读排气阀时间", "ReadVentTime", null, new { houseSn = CurrentHouseId });
            if (r != null && r.Ok && r.Result != null && int.TryParse(r.Result.ToString(), out var v) && v >= 0)
                HouseVentTimeE = v;
        }

        /// <summary>
        /// 写垂直电机间隔脉冲
        /// </summary>
        /// <param name="newValue"></param>
        public async Task WriteOVerSpace(int newValue)
        {
            // M8-G3-1：写垂直电机间隔脉冲为写 EEPROM 设备命令入口,补操作日志埋点（module=对焦调试）。
            await RunDebugCommandAsync("写垂直电机间隔脉冲", "WriteScanStep", new { value = newValue },
                new { houseSn = CurrentHouseId, newValue });
        }

        /// <summary>
        /// 保存水平电机位置
        /// </summary>
        /// <param name="newValue"></param>
        public async Task SaveWellHor()
        {
            // M8-P3b：手调保存水平电机位置（关键命令入口,module=对焦调试）。
            await RunDebugCommandAsync("手调保存水平电机位置", "WriteWellHorizontalPos",
                new { well = CurrentWell, hor = CurrentHor },
                new { houseSn = CurrentHouseId, well = CurrentWell, hor = CurrentHor });
        }

        #region 电机运动
        /// <summary>
        /// 水平电机复位
        /// </summary>
        public async Task HorizontalMotorReset()
        {
            // M8-P3b：电机控制命令埋点（module=对焦调试）。
            await RunDebugCommandAsync("水平电机复位", "HorizontalReset", new { motorDelay = tLSetting.motorDelay },
                new { houseSn = CurrentHouseId });
            CurrentHor = 0;
            CurrentWell = 0;
        }

        /// <summary>
        /// 水平电机正向
        /// </summary>
        public async Task HorizontalMotorForward(int value)
        {
            // M8-G3-1：电机控制命令入口,补操作日志埋点（module=对焦调试）。
            await RunDebugCommandAsync("水平电机正向", "HorizontalForward", new { value, motorDelay = tLSetting.motorDelay },
                new { houseSn = CurrentHouseId, value });
            CurrentHor += value;
        }

        /// <summary>
        /// 水平电机反向
        /// </summary>
        public async Task HorizontalMotorBackward(int value)
        {
            // M8-G3-1：电机控制命令入口,补操作日志埋点（module=对焦调试）。
            await RunDebugCommandAsync("水平电机反向", "HorizontalBackward", new { value, motorDelay = tLSetting.motorDelay },
                new { houseSn = CurrentHouseId, value });
            CurrentHor -= value;
        }

        /// <summary>
        /// 水平电机到目标well
        /// </summary>
        /// <param name="newWell"></param>
        public async Task HorizontalMotorToWell(int newWell)
        {
            var currentHorSetting = houseWellSettingList.FirstOrDefault(x => x.houseSn == CurrentHouseId && x.wellSn == newWell);
            if (currentHorSetting == null)
            {
                AddMessageInfo($"[未获取到{newWell}号well的水平电机位置]");
                return;
            }
            // M8-G3-1：电机控制命令入口,补操作日志埋点（module=对焦调试）。
            await RunDebugCommandAsync("水平电机到well", "HorizontalMoveTo",
                new { pos = currentHorSetting.horizontalMotorPosition, motorDelay = tLSetting.motorDelay },
                new { houseSn = CurrentHouseId, well = newWell, hor = currentHorSetting.horizontalMotorPosition });
            CurrentHor = currentHorSetting.horizontalMotorPosition;
            CurrentWell = newWell;
        }

        /// <summary>
        /// 垂直电机复位
        /// </summary>
        public async Task VerticalMotorReset()
        {
            // M8-P3b：电机控制命令埋点（module=对焦调试）。
            await RunDebugCommandAsync("垂直电机复位", "VerticalReset", new { motorDelay = tLSetting.motorDelay },
                new { houseSn = CurrentHouseId });
            CurrentVer = 0;
        }

        /// <summary>
        /// 垂直电机正向运动
        /// </summary>
        public async Task VerticalMotorForward(int newValue)
        {
            // M8-G3-1：电机控制命令入口,补操作日志埋点（module=对焦调试）。
            await RunDebugCommandAsync("垂直电机正向", "VerticalForward", new { value = newValue, motorDelay = tLSetting.motorDelay },
                new { houseSn = CurrentHouseId, newValue });
            CurrentVer += newValue;
        }

        /// <summary>
        /// 垂直电机反向运动
        /// </summary>
        public async Task VerticalMotorBackward(int newValue)
        {
            // M8-G3-1：电机控制命令入口,补操作日志埋点（module=对焦调试）。
            await RunDebugCommandAsync("垂直电机反向", "VerticalBackward", new { value = newValue, motorDelay = tLSetting.motorDelay },
                new { houseSn = CurrentHouseId, newValue });
            CurrentVer -= newValue;
        }

        /// <summary>
        /// 垂直电机绝对运动
        /// </summary>
        public async Task VerticalMotorAbsolute(int newValue)
        {
            // M8-G3-1：电机控制命令入口,补操作日志埋点（module=对焦调试）。
            await RunDebugCommandAsync("垂直电机绝对运动", "VerticalMoveTo", new { pos = newValue, motorDelay = tLSetting.motorDelay },
                new { houseSn = CurrentHouseId, newValue });
            CurrentVer = newValue;
        }

        /// <summary>
        /// 一键电机准备
        /// </summary>
        public async Task MototReady()
        {
            var currentHorSetting = houseWellSettingList.FirstOrDefault(x => x.houseSn == CurrentHouseId && x.wellSn == 1);
            if (currentHorSetting == null)
            {
                AddMessageInfo($"[未获取到1号well的水平电机位置]");
                return;
            }

            var verNewValue = currentHorSetting.eepromClearPosition;
            var cc = ccdPhoto.FirstOrDefault(x => x.houseSn == CurrentHouseId && x.wellSn == 1);
            if (cc != null)
            {
                verNewValue = cc.clearestPosition;
            }

            // M8-G3-1：一键电机准备为多步串口动作流程,各子动作经 control 顺序下发（module=对焦调试）。
            using var _op = Aivfo.OperationLog.OperationLogger.Begin("对焦调试", "一键电机准备",
                houseSn: CurrentHouseId);
            try { _op.Input(new { houseSn = CurrentHouseId, targetHor = currentHorSetting.horizontalMotorPosition, targetVer = verNewValue }); } catch { }

            await RunDebugCommandAsync("一键电机准备-水平复位", "HorizontalReset", new { motorDelay = tLSetting.motorDelay }, new { houseSn = CurrentHouseId });
            CurrentHor = 0;
            CurrentWell = 0;

            await RunDebugCommandAsync("一键电机准备-水平到位", "HorizontalMoveTo",
                new { pos = currentHorSetting.horizontalMotorPosition, motorDelay = tLSetting.motorDelay }, new { houseSn = CurrentHouseId });
            CurrentHor = currentHorSetting.horizontalMotorPosition;
            CurrentWell = 1;

            await RunDebugCommandAsync("一键电机准备-垂直复位", "VerticalReset", new { motorDelay = tLSetting.motorDelay }, new { houseSn = CurrentHouseId });
            CurrentVer = 0;
            CurrentFocal = 0;

            await RunDebugCommandAsync("一键电机准备-垂直到位", "VerticalMoveTo",
                new { pos = verNewValue, motorDelay = tLSetting.motorDelay }, new { houseSn = CurrentHouseId });
            CurrentVer = verNewValue;
            CurrentFocal = 1;
        }

        /// <summary>
        /// 单张抓拍
        /// </summary>
        public bool SavePic(string fullName)
        {
            try
            {
                if (GetPicData() == 0)
                {
                    if (Cam == null) return false;
                    // M8-G3-1：单张抓拍落盘为相机采图+保存命令入口，补操作日志埋点（module=对焦调试）。
                    // 批量抓图(水平抓图/清晰图层抓图)经 Begin scope 调用时，本埋点自动成为其子埋点（父子链）。
                    return Aivfo.OperationLog.OperationLogger.Run("对焦调试", "单张抓拍",
                        () => Cam.SavePic(fullName, CurrentHouse.ccdWidth, CurrentHouse.ccdHeight),
                        input: new { houseSn = CurrentHouseId, well = CurrentWell, focal = CurrentFocal, hor = CurrentHor, ver = CurrentVer });

                }
                return false;
            }
            catch (Exception ex)
            {
                AppData.Instance.LogHelper.ExceptionLog(ex, $"单张抓拍", LogEnum.RunException);
                AddMessageInfo($"单张抓拍异常：{ex.Message}");
                return false;
            }
        }

        /// <summary>
        /// 水平抓图
        /// </summary>
        public void ShuiPingZhuaPai()
        {
            try
            {
                IsStop = false;
                if (Serial == null) return;
                if (IsStop) return;
                // M8-G3-1：水平抓图为多步循环采图流程，用 Begin scope 串联各 well 抓拍子埋点（module=对焦调试）。
                using var _op = Aivfo.OperationLog.OperationLogger.Begin("对焦调试", "水平抓图",
                    houseSn: CurrentHouseId);
                try { _op.Input(new { houseSn = CurrentHouseId }); } catch { }
                Serial.HorizontalResetWait(tLSetting.motorDelay);
                CurrentHor = 0;
                CurrentWell = 0;
                HouseWellSetting currentHorSetting = null;

                string dtnow = string.Format("{0:yyyy-MM-dd-HH-mm-ss}", DateTime.Now); //24小时制
                string path = AppData.Instance.LogHelper.GetDeBugShuiPingDirectory(CurrentHouse.houseSn, dtnow);

                if (!Directory.Exists(path))
                {
                    Directory.CreateDirectory(path);
                }

                for (int i = 1; i <= 16; i++)
                {
                    currentHorSetting = houseWellSettingList.FirstOrDefault(x => x.houseSn == CurrentHouseId && x.wellSn == i);
                    if (currentHorSetting == null)
                    {
                        AddMessageInfo($"[未获取到1号well的水平电机位置]");
                        continue;
                    }
                    if (IsStop) return;
                    if (Serial == null) return;
                    Serial.HorizontalMoveToWait(currentHorSetting.horizontalMotorPosition, tLSetting.motorDelay);
                    if (IsStop) return;
                    CurrentHor = currentHorSetting.horizontalMotorPosition;
                    CurrentWell = i;

                    string filename = $"{dtnow}-house{CurrentHouse.houseSn}-well{CurrentWell}-{CurrentFocal}-{CurrentHor}-{CurrentVer}.jpg";

                    string fullName = $"{path}{filename}";
                    if (Cam == null) return;
                    if (SavePic(fullName))
                    {
                        AddPic(fullName);
                    }
                }
            }
            catch (Exception ex)
            {
                AppData.Instance.LogHelper.ExceptionLog(ex, $"水平抓拍", LogEnum.RunException);
                AddMessageInfo($"水平抓拍异常：{ex.Message}");
            }
        }

        /// <summary>
        /// 清晰图层抓图
        /// </summary>
        public async Task AutoFocusPic(int focalCount, int xun)
        {
            await Task.Run(async () =>
            {
                try
                {
                    IsStop = false;

                    var startAutoFocus = -1;
                    var cc = ccdPhoto.FirstOrDefault(x => x.houseSn == CurrentHouseId && x.wellSn == CurrentWell);
                    if (cc == null)
                    {
                        AddMessageInfo($"[未获取到{CurrentWell}号well的自动对焦起点]");
                        return;
                    }
                    // M8-G3-1：清晰图层抓图为多步循环采图流程，用 Begin scope 串联各层抓拍子埋点（module=对焦调试）。
                    using var _op = Aivfo.OperationLog.OperationLogger.Begin("对焦调试", "清晰图层抓图",
                        houseSn: CurrentHouseId);
                    try { _op.Input(new { houseSn = CurrentHouseId, well = CurrentWell, focalCount, xun }); } catch { }
                    startAutoFocus = cc.autoFocusPosition;
                    string dtnow = string.Format("{0:yyyy-MM-dd-HH-mm-ss}", DateTime.Now); //24小时制
                    string path = null;
                    string fullName = null;
                    for (int k = 0; k < xun; k++)
                    {
                        if (IsStop) return;
                        if (Serial == null) return;
                        Serial.VerticalResetWait(tLSetting.motorDelay);
                        CurrentVer = 0;
                        CurrentFocal = 0;
                        var verSpacePulse = 128;
                        if (CurrentHouse.verticalMotorSpacePulse.HasValue) verSpacePulse = CurrentHouse.verticalMotorSpacePulse.Value;
                        path = $"{AppData.Instance.LogHelper.GetDeBugQingXiDirectory(CurrentHouse.houseSn, CurrentWell, dtnow)}{(k + 1)}_{CurrentHor}";
                        if (!Directory.Exists(path)) Directory.CreateDirectory(path);
                        for (int i = 0; i < focalCount; i++)
                        {
                            CurrentFocal = i + 1;
                            var currentVerValue = startAutoFocus + (i * verSpacePulse);
                            if (IsStop) return;
                            if (Serial == null) return;
                            if(currentVerValue > tLSetting.verticalMotorPulseMax)
                            {
                                AddMessageInfo($"清晰图层抓图超出垂直电机上限：{tLSetting.verticalMotorPulseMax}");
                                return;
                            }
                            Serial.VerticalMoveToWait(currentVerValue, tLSetting.motorDelay);
                            CurrentVer = currentVerValue;
                            fullName = $"{path}\\{currentVerValue}.jpg";
                            if (IsStop) return;
                            if (Cam == null) return;
                            if (SavePic(fullName)) AddPic(fullName);
                        }
                    }
                }
                catch (Exception ex)
                {
                    AppData.Instance.LogHelper.ExceptionLog(ex, $"清晰图层抓图", LogEnum.RunException);
                    AddMessageInfo($"清晰图层抓图异常：{ex.Message}");
                }
            });
        }

        /// <summary>
        /// 抓图
        /// </summary>
        public int GetPicData()
        {
            try
            {
                if (Cam == null) return -1;
                int GetRgbData = -1;
                bool isWuTu = false;

                if (isWuTu)
                {
                    GetRgbData = Cam.GrabRaw();//获取字节流

                    AddMessageInfo($"[抓拍结果:{GetRgbData}][注:0表示成功]");

                    if (GetRgbData == 0)
                    {
                        GetRgbData = Cam.RawToRgb();
                        AddMessageInfo($"[rawToRgb结果:{GetRgbData}][注:0表示成功]");
                    }
                }
                else
                {
                    GetRgbData = Cam.GrabRgb();//获取字节流
                    AddMessageInfo($"[抓拍结果:{GetRgbData}][注:0表示成功]");
                }
                return GetRgbData;
            }
            catch (Exception ex)
            {
                AppData.Instance.LogHelper.ExceptionLog(ex, $"调试模式抓拍", LogEnum.RunException);
                AddMessageInfo($"相机抓拍异常：{ex.Message}");
                return -1;
            }
        }
        #endregion

        #region 相机操作

        /// <summary>
        /// 设置曝光值
        /// </summary>
        /// <param name="newExporuse"></param>
        public async Task SetExposure(int newExporuse)
        {
            // M8-G3-1：设置相机曝光为相机设备命令入口,补操作日志埋点（module=对焦调试）。
            // Task3.4b：operate 相机空壳,曝光改走 control 借用的真相机(control 端 Execute 新增 SetExposure op)。
            var r = await RunDebugCommandAsync("设置相机曝光值", "SetExposure", new { value = newExporuse },
                new { houseSn = CurrentHouseId, ccdId = CurrentCCDId, newExporuse });
            if (r != null && r.Ok) AddMessageInfo($"设置曝光结果:{r.Result}");
        }

        /// <summary>
        /// 打开实时预览（贴宿主窗口句柄）。M1-B2：走借用到的 lease.Camera(StartPreview)，不再触碰具体 Camera。
        /// 返回 0 成功；相机句柄为空返回 -1。
        /// </summary>
        public int StartPreview(IntPtr hostControl, int left, int top, int width, int height)
        {
            if (Cam == null) return -1;
            return Cam.StartPreview(hostControl, left, top, width, height);
        }

        /// <summary>关闭实时预览。返回 0 成功；相机句柄为空返回 -1。</summary>
        public int StopPreview()
        {
            if (Cam == null) return -1;
            return Cam.StopPreview();
        }


        //public bool OpenVideo(IntPtr mControlPtr, int left, int top, int width, int height)
        //{
        //    try
        //    {
        //        var a = camera.Usb2Start(mControlPtr, left, top, width, height);
        //        AddMessageInfo($"图像打开结果[0表示成功]:{a}");
        //        return a == 0;
        //    }
        //    catch (Exception ex)
        //    {
        //        ExLog(ex, "OpenVideo");
        //        AddMessageInfo($"图像打开异常:{ex.Message}");
        //        return false;
        //    }
        //}


        //public bool CloseVideo()
        //{
        //    try
        //    {
        //        var a = camera.Usb2Stop();
        //        AddMessageInfo($"图像关闭结果[0表示成功]:{a}");
        //        return a == 0;
        //    }
        //    catch (Exception ex)
        //    {
        //        ExLog(ex, "CloseVideo");
        //        AddMessageInfo($"图像关闭异常:{ex.Message}");
        //        return false;
        //    }
        //}
        #endregion

        #region 参数保存

        /// <summary>
        /// 保存舱室参数
        /// </summary>
        /// <returns></returns>
        public bool SetHouseInfo()
        {
            try
            {
                if (CurrentHouse == null) return true;
                string body = JsonConvert.SerializeObject(new
                {
                    tlSn = CurrentHouse.tlSn,
                    houseSn = CurrentHouse.houseSn,
                    ccdExposure = CurrentHouse.ccdExposure,
                    inletValveOpeningTime = CurrentHouse.inletValveOpeningTime,
                    verticalMotorSpacePulse = CurrentHouse.verticalMotorSpacePulse,
                });
                return AppData.Instance.HttpHelper.HouseDebuggingApi(body);
            }
            catch (Exception ex)
            {
                ExLog(ex, "SetHouseExposure");
                return false;
            }
        }

        /// <summary>
        /// 保存当前well位置
        /// </summary>
        /// <returns></returns>
        public bool SetWellMotorPosition()
        {
            try
            {
                if (CurrentHouse == null)
                {
                    AddMessageInfo("获取舱室信息失败");
                }

                string body = JsonConvert.SerializeObject(new
                {
                    horizontalMotorPosition = CurrentHor,
                    houseSn = CurrentHouse.houseSn,
                    tlSn = CurrentHouse.tlSn,
                    wellSn = CurrentWell,
                });
                return AppData.Instance.HttpHelper.WellUpdateApi(body);
            }
            catch (Exception ex)
            {
                ExLog(ex, "SetWellMotorPosition");
                return false;
            }
        }

        /// <summary>
        /// 保存自动对焦起点
        /// </summary>
        /// <returns></returns>
        public bool SetWellAutoFocus()
        {
            try
            {
                if (CurrentHouse == null)
                {
                    AddMessageInfo("获取舱室信息失败");
                }



                string body = JsonConvert.SerializeObject(new
                {
                    verticalMotorPosition = CurrentVer,
                    houseSn = CurrentHouse.houseSn,
                    tlSn = CurrentHouse.tlSn,
                    wellSn = CurrentWell,
                });
                return AppData.Instance.HttpHelper.WellUpdateApi(body);
            }
            catch (Exception ex)
            {
                ExLog(ex, "SetWellAutoFocus");
                return false;
            }
        }
        #endregion

        private void ComBin_ExceptionLogEvent(Exception exception, string arg2, string arg3, LogEnum @enum)
        {
            AppData.Instance.LogHelper.ExceptionLog(exception, $"{arg2}{arg3}", @enum);
        }

        private void ComBin_ErrorLogEvent(string arg1, LogEnum @enum)
        {
            AppData.Instance.LogHelper.TLLog(arg1, @enum);
        }

        private void ComBin_CommandLogEvent(int arg1, DateTime time, string arg3, LogEnum @enum)
        {
            AppData.Instance.LogHelper.HouseLog(arg1, time, arg3, @enum);
        }

        public void AddMessageInfo(string mess)
        {
            MessageEvent?.Invoke(mess);
        }

        public void AddPic(string picFullName)
        {
            AddPicEvent?.Invoke(picFullName, CurrentWell, CurrentFocal);
        }

        #region 场景A 一键全自动标定（经 control 协作，D2-02-T3.4 重构）

        /// <summary>
        /// 一键全自动标定（D2-02-T3.4 重构为"经 control 协作"）。
        /// 旧实现:operate 本地 new CalibrationEngine 逐 well 跑 + CalibrationStore 写 JSON/scene0(已停用)。
        /// 新实现:operate 仅发 /debug/calibrate/start(经 CalibrationClient,复用 acquire 的 sessionId) →
        ///        起轮询 /debug/calibrate/progress(~800ms) 把每孔状态映射到 16 格 UI(合格绿/伪峰橙/失败红 + FocusZ/峰比/偏移)。
        ///        标定由 control 协作端真正执行(持真硬件)、scene=0 基准由 control 端落库。
        /// 前提:ComHouseInit 已成功 acquire(CurrentSessionId 非空、_calibClient 已构造)。
        /// 中止:StopCalibrate → /debug/calibrate/stop + 停轮询。
        ///
        /// ⚠ 待验证(compile-pending,operate.exe 卡死未编译):start/progress/stop 协作往返、16 格映射、合格判定一致。
        /// </summary>
        /// <param name="wells">勾选的 well 列表（空/null 视为全 16 well）。</param>
        public async Task OneClickCalibrate(IEnumerable<int> wells = null)
        {
            if (IsCalibrating)
            {
                AddMessageInfo("[一键标定]已在标定中，请勿重复触发");
                return;
            }
            if (_calibClient == null || string.IsNullOrEmpty(CurrentSessionId))
            {
                AddMessageInfo("[一键标定]未建立调试会话(请先初始化舱室借硬件)，无法发起协作标定");
                return;
            }
            if (CurrentHouse == null)
            {
                AddMessageInfo("[一键标定]未获取到舱室信息");
                return;
            }

            // 勾选 well：未传则默认 16 well；去重、按序、限定 1-16。
            var wellList = (wells ?? Enumerable.Range(1, 16))
                .Where(w => w >= 1 && w <= 16).Distinct().OrderBy(w => w).ToList();
            if (wellList.Count == 0) wellList = Enumerable.Range(1, 16).ToList();

            IsCalibrating = true;
            IsStopCalibrate = false;

            try
            {
                // M8-P3b：一键标定发起为关键命令入口，记一条操作日志(start 同步发起;异步轮询单独不再串 scope，
                // 避免 using scope 在方法返回即 Dispose 后被后台轮询误用)。
                using (var _opScope = Aivfo.OperationLog.OperationLogger.Begin("对焦调试", "一键标定发起(协作)", houseSn: CurrentHouseId))
                {
                    try { _opScope.Input(new { houseSn = CurrentHouseId, wells = wellList.ToArray() }); } catch { }

                    ResetCalibResults(wellList);

                    // D2-02-T3.4：标定由 control 协作端执行(scene=0 落库由 control 端处理)。
                    // operate 仅发 start + 轮询进度刷新 16 格 UI，不再 operate 本地 new CalibrationEngine/CalibrationStore。
                    var r = await _calibClient.StartAsync(wellList);
                    if (!r.Ok)
                    {
                        IsCalibrating = false;
                        AddMessageInfo($"[一键标定]发起失败:{r.Code}/{r.Error}");
                        try { _opScope.Fail($"start 失败:{r.Code}/{r.Error}"); } catch { }
                        return;
                    }
                    try { _opScope.Output(new { started = true }).Success(); } catch { }
                }
                AddMessageInfo($"[一键标定]已发起(control 协作)：舱{CurrentHouse.houseSn} 共 {wellList.Count} well，开始轮询进度...");

                // 起轮询任务,把 control 端进度映射到 16 格 UI;IsRunning 转 false 即停。
                StartCalibPolling();
            }
            catch (Exception ex)
            {
                IsCalibrating = false;
                ExLog(ex, "OneClickCalibrate");
                AddMessageInfo($"[一键标定]整体异常：{ex.Message}");
            }
        }

        /// <summary>
        /// D2-02-T3.4 单孔重标:经 control 协作端对该 well 重新标定一次，并起轮询刷新该格。
        /// </summary>
        public async Task RecalibrateWell(int wellSn)
        {
            if (_calibClient == null || string.IsNullOrEmpty(CurrentSessionId))
            {
                AddMessageInfo("[重标]未建立调试会话，无法重标");
                return;
            }
            if (IsCalibrating)
            {
                AddMessageInfo("[重标]批量标定进行中，请先中止或等待结束");
                return;
            }
            if (wellSn < 1 || wellSn > 16)
            {
                AddMessageInfo("[重标]well 只能为 1-16");
                return;
            }
            try
            {
                IsCalibrating = true;
                IsStopCalibrate = false;
                UpdateCalibResult(wellSn, item => { item.State = WellCalibState.Running; item.Note = "重标中..."; });
                var r = await _calibClient.RecalibrateAsync(wellSn);
                if (!r.Ok)
                {
                    IsCalibrating = false;
                    AddMessageInfo($"[重标]well{wellSn} 发起失败:{r.Code}/{r.Error}");
                    return;
                }
                AddMessageInfo($"[重标]well{wellSn} 已发起，轮询进度...");
                StartCalibPolling();
            }
            catch (Exception ex)
            {
                IsCalibrating = false;
                ExLog(ex, "RecalibrateWell");
                AddMessageInfo($"[重标]well{wellSn} 异常：{ex.Message}");
            }
        }

        /// <summary>工程师中止一键标定:通知 control 停标，停本地轮询。</summary>
        public void StopCalibrate()
        {
            IsStopCalibrate = true;
            AddMessageInfo("[一键标定]收到中止请求，通知 control 停止...");
            var calib = _calibClient;
            if (calib != null)
            {
                Task.Run(async () =>
                {
                    try { await calib.StopAsync(); } catch (Exception ex) { ExLog(ex, "StopCalibrate.StopAsync"); }
                });
            }
            // 轮询任务读到 IsRunning=false 后会自停;此处也主动停一次兜底。
            StopCalibPolling();
        }

        /// <summary>
        /// 起标定进度轮询(~800ms 一次):调 control /debug/calibrate/progress，
        /// 把每孔 WellCalibProgressDto(State 数字枚举)映射到 16 格 WellCalibUiItem。
        /// IsRunning 转 false(或会话失效返回 null)即停轮询并复位 IsCalibrating。
        /// 同一时刻只跑一个轮询任务(先停旧的)。
        /// </summary>
        private void StartCalibPolling()
        {
            StopCalibPolling();
            var cts = new System.Threading.CancellationTokenSource();
            _calibPollCts = cts;
            var token = cts.Token;
            var calib = _calibClient;

            Task.Run(async () =>
            {
                try
                {
                    while (!token.IsCancellationRequested)
                    {
                        var dto = await calib.PollProgressAsync();
                        if (token.IsCancellationRequested) break;

                        if (dto == null)
                        {
                            // 会话失效/无进度:停轮询(会话失效另由 DebugSessionClient.OnSessionExpired 提示)。
                            AddMessageInfo("[一键标定]进度查询无结果(会话可能已失效)，停止轮询");
                            break;
                        }

                        MapProgressToUi(dto);

                        if (!dto.IsRunning)
                        {
                            int okCount = CalibResults.Count(x => x.State == WellCalibState.Qualified);
                            AddMessageInfo($"[一键标定]结束：合格 {okCount}/{dto.Total}（scene=0 基准由 control 协作端落库）");
                            break;
                        }
                        await Task.Delay(800, token);
                    }
                }
                catch (TaskCanceledException) { /* 主动停 */ }
                catch (Exception ex)
                {
                    ExLog(ex, "CalibPolling");
                    AddMessageInfo($"[一键标定]轮询异常：{ex.Message}");
                }
                finally
                {
                    IsCalibrating = false;
                }
            }, token);
        }

        /// <summary>停标定进度轮询(取消轮询任务)。幂等。</summary>
        private void StopCalibPolling()
        {
            var cts = _calibPollCts;
            _calibPollCts = null;
            if (cts != null) { try { cts.Cancel(); } catch { } try { cts.Dispose(); } catch { } }
        }

        /// <summary>把 control 进度 DTO 的每孔状态映射到 16 格 UI(State 为数字枚举:0待标/1标定中/2合格/3伪峰/4失败)。</summary>
        private void MapProgressToUi(CalibProgressDto dto)
        {
            if (dto?.Wells == null) return;
            foreach (var w in dto.Wells)
            {
                var well = w;   // 闭包捕获
                UpdateCalibResult(well.WellSn, item =>
                {
                    item.State = (WellCalibState)well.State;   // 0..4 与 operate 端枚举顺序一致
                    item.FocusZ = well.FocusZ;
                    item.Exposure = well.Exposure;
                    item.PeakRatio = well.PeakRatio;
                    item.CenterOffsetPct = well.CenterOffsetPct;
                    item.CircleFound = well.CircleFound;
                    item.Note = string.IsNullOrEmpty(well.Note)
                        ? StateNote((WellCalibState)well.State, well.FocusZ, well.PeakRatio)
                        : well.Note;
                });
            }
        }

        private static string StateNote(WellCalibState st, int focusZ, double peakRatio) => st switch
        {
            WellCalibState.Pending => "待标定",
            WellCalibState.Running => "标定中...",
            WellCalibState.Qualified => $"合格 Z={focusZ} 峰比={peakRatio:F2}",
            WellCalibState.FakePeak => $"伪峰 Z={focusZ} 峰比={peakRatio:F2}",
            WellCalibState.Failed => "失败",
            _ => ""
        };

        private void ResetCalibResults(List<int> wells)
        {
            void build()
            {
                CalibResults.Clear();
                foreach (var w in wells)
                    CalibResults.Add(new WellCalibUiItem { Well = w, State = WellCalibState.Pending, Note = "待标定" });
            }
            // 集合改动需在 UI 线程（ObservableCollection 绑定）。
            var disp = System.Windows.Application.Current?.Dispatcher;
            if (disp != null && !disp.CheckAccess()) disp.Invoke(build); else build();
        }

        private void UpdateCalibResult(int well, Action<WellCalibUiItem> mutate)
        {
            void apply()
            {
                var item = CalibResults.FirstOrDefault(x => x.Well == well);
                if (item == null)
                {
                    item = new WellCalibUiItem { Well = well };
                    CalibResults.Add(item);
                }
                mutate(item);
            }
            var disp = System.Windows.Application.Current?.Dispatcher;
            if (disp != null && !disp.CheckAccess()) disp.Invoke(apply); else apply();
        }

        #endregion

        #region M2-07 对焦后手动微调拍摄层（层数/层间距/下移）持久化 well 级

        /// <summary>
        /// M2-07 手调"实际拍摄层数"（well 级覆盖）。空字符串=留空继承设备级（保存写 null）。
        /// View TextBox 双向绑定；校验在保存/预览时做（层数≥1）。
        /// </summary>
        [ObservableProperty] private string manualLayerCount = "";

        /// <summary>
        /// M2-07 手调"实际拍摄层间距脉冲"（well 级覆盖）。空=继承设备级（写 null）。校验：>0。
        /// </summary>
        [ObservableProperty] private string manualLayerSpacing = "";

        /// <summary>
        /// M2-07 手调"对焦起点下移层数"（复用 move_down_layer）。空=继承设备级。
        /// 校验：≥0 且 &lt;层数（下移层须落在拍摄范围内，§2.4 清晰层=第 down 层）。
        /// </summary>
        [ObservableProperty] private string manualMoveDown = "";

        /// <summary>
        /// M2-07 实时预览各层绝对 Z 位置（调 M2-02 ComputeLayerPositions 生成，关联 V-045）。
        /// View 绑定此集合显示 N 层位置列表，让工程师看到手调效果。
        /// </summary>
        public ObservableCollection<LayerPreviewItem> LayerPreview { get; } = new ObservableCollection<LayerPreviewItem>();

        /// <summary>
        /// M2-07 预览/手调锚点 well（默认随水平电机当前 well / 一键标定取 CurrentWell）。
        /// </summary>
        [ObservableProperty] private int manualTuneWell = 1;

        /// <summary>
        /// 取该 well 当前生效的"实际拍摄层"配置（well 级覆盖优先，空则回退设备级），
        /// 回填三个手调输入框 + 触发一次预览。供"载入当前值"按钮调用。
        /// </summary>
        public void LoadManualLayerSetting(int well)
        {
            ManualTuneWell = well;
            var ws = houseWellSettingList.FirstOrDefault(x => x.houseSn == CurrentHouseId && x.wellSn == well);

            // well 级覆盖非空显示 well 值，否则显示继承的设备级值作占位（§2.5 就近优先）。
            int? wellCount = ws?.focusLayerCount;
            int? wellSpacing = ws?.focusLayerSpacingPulse;
            // 下移复用 moveDownLayer（well 级为非空 int 列；0 视为有效覆盖值）。
            int? wellDown = ws != null ? (int?)ws.moveDownLayer : null;

            ManualLayerCount = (wellCount ?? tLSetting?.focusLayerCount)?.ToString() ?? "";
            ManualLayerSpacing = (wellSpacing ?? tLSetting?.focusLayerSpacingPulse)?.ToString() ?? "";
            ManualMoveDown = (wellDown ?? tLSetting?.focusLayerDown)?.ToString() ?? "";

            PreviewManualLayers();
        }

        /// <summary>
        /// 取该 well 最近标定的 FocusZ 作预览锚点（M2-05 一键标定结果 CalibResults 优先；
        /// 回退 ccdPhoto 的 clearestPosition 即 scene0/1 库下发的清晰位置）。
        /// 返回 null 表示无标定可用（须提示先标定）。
        /// </summary>
        private int? GetPreviewFocusZ(int well)
        {
            var calib = CalibResults.FirstOrDefault(x => x.Well == well
                && (x.State == WellCalibState.Qualified || x.State == WellCalibState.FakePeak));
            if (calib != null && calib.FocusZ > 0) return calib.FocusZ;

            // 回退：调试页加载的清晰位置(scene0/1 库值 clearestPosition)。
            var cc = ccdPhoto.FirstOrDefault(x => x.houseSn == CurrentHouseId && x.wellSn == well);
            if (cc != null && cc.clearestPosition > 0) return cc.clearestPosition;

            return null;
        }

        /// <summary>
        /// 解析三个手调输入框（空=继承设备级取回退值），返回有效 (count,spacing,down) 或 null（非法/缺失）。
        /// validateMsg 携带校验失败原因。
        /// </summary>
        private (int count, int spacing, int down)? ResolveEffectiveTune(out string validateMsg)
        {
            validateMsg = null;

            // 解析层数：空→设备级回退；非空→必须 int。
            int? count;
            if (string.IsNullOrWhiteSpace(ManualLayerCount)) count = tLSetting?.focusLayerCount;
            else if (int.TryParse(ManualLayerCount.Trim(), out int c)) count = c;
            else { validateMsg = "层数只能输入整数"; return null; }

            int? spacing;
            if (string.IsNullOrWhiteSpace(ManualLayerSpacing)) spacing = tLSetting?.focusLayerSpacingPulse;
            else if (int.TryParse(ManualLayerSpacing.Trim(), out int s)) spacing = s;
            else { validateMsg = "层间距只能输入整数"; return null; }

            int? down;
            if (string.IsNullOrWhiteSpace(ManualMoveDown)) down = tLSetting?.focusLayerDown;
            else if (int.TryParse(ManualMoveDown.Trim(), out int d)) down = d;
            else { validateMsg = "下移层数只能输入整数"; return null; }

            if (!count.HasValue) { validateMsg = "层数未配置(设备级也为空)，请填层数或先初始化设备级"; return null; }
            if (!spacing.HasValue) { validateMsg = "层间距未配置(设备级也为空)，请填层间距或先初始化设备级(§2.5 不兜底)"; return null; }
            if (!down.HasValue) { validateMsg = "下移层数未配置(设备级也为空)，请填下移层数"; return null; }

            // 校验：层数≥1、间距>0、下移≥0 且 <层数（下移层须落在拍摄范围内）。
            if (count.Value < 1) { validateMsg = "层数必须 ≥ 1"; return null; }
            if (spacing.Value <= 0) { validateMsg = "层间距必须 > 0"; return null; }
            if (down.Value < 0) { validateMsg = "下移层数必须 ≥ 0"; return null; }
            if (down.Value >= count.Value) { validateMsg = $"下移层数必须 < 层数({count.Value})，否则清晰层落在拍摄范围外"; return null; }

            return (count.Value, spacing.Value, down.Value);
        }

        /// <summary>
        /// M2-07 实时预览：用该 well 标定 FocusZ + 当前手调值，调 M2-02
        /// ComputeLayerPositions(focusZ, cfg, pulseMax) 生成各层绝对 Z，刷新 LayerPreview（关联 V-045）。
        /// 无标定锚点 → 清空预览并提示先标定；校验非法 → 清空预览并提示。
        /// </summary>
        public void PreviewManualLayers()
        {
            try
            {
                var focusZ = GetPreviewFocusZ(ManualTuneWell);
                if (!focusZ.HasValue)
                {
                    SetLayerPreview(null);
                    AddMessageInfo($"[手调拍摄层]well{ManualTuneWell} 无标定结果，请先对该 well 标定(或确认已下发清晰位置)再预览");
                    return;
                }

                var eff = ResolveEffectiveTune(out string msg);
                if (eff == null)
                {
                    SetLayerPreview(null);
                    AddMessageInfo($"[手调拍摄层]预览失败：{msg}");
                    return;
                }

                var cfg = new FocusLayerConfig
                {
                    LayerCount = eff.Value.count,
                    LayerSpacingPulse = eff.Value.spacing,
                    LayerDown = eff.Value.down,
                };
                int pulseMax = tLSetting != null ? tLSetting.verticalMotorPulseMax : 0;
                int[] positions = PhotoLayerCalculator.ComputeLayerPositions(focusZ.Value, cfg, pulseMax);

                var items = new List<LayerPreviewItem>();
                for (int i = 0; i < positions.Length; i++)
                {
                    items.Add(new LayerPreviewItem
                    {
                        LayerIndex = i,
                        ZPulse = positions[i],
                        IsFocusLayer = (i == eff.Value.down), // 第 down 层 = 清晰层(FocusZ 锚点)
                    });
                }
                SetLayerPreview(items);
                AddMessageInfo($"[手调拍摄层]well{ManualTuneWell} 预览：锚点FocusZ={focusZ.Value} 层数={eff.Value.count} " +
                               $"间距={eff.Value.spacing} 下移={eff.Value.down} → 第0层Z={positions[0]} 第{positions.Length - 1}层Z={positions[positions.Length - 1]}");
            }
            catch (Exception ex)
            {
                SetLayerPreview(null);
                ExLog(ex, "PreviewManualLayers");
                AddMessageInfo($"[手调拍摄层]预览异常：{ex.Message}");
            }
        }

        /// <summary>
        /// M2-07 保存为该 well 默认：校验通过后，把手调值写 house_well_setting well 级覆盖
        /// (focus_layer_spacing_pulse/focus_layer_count + 复用 move_down_layer)。
        /// 复用现有 operate 端 well 设置保存通道 HttpHelper.WellUpdateApi(同 SetWellMotorPosition/SetWellAutoFocus)，
        /// 走 /api/tl/control/setting/house/well/update。留空字段=继承设备级(写 null)。
        /// 下次该 well 经 §2.5 就近优先(PhotoLayerCalculator.Resolve)沿用 well 覆盖值。
        /// 返回 true=保存成功。
        /// </summary>
        public bool SaveManualLayerTune()
        {
            try
            {
                if (CurrentHouse == null)
                {
                    AddMessageInfo("[手调拍摄层]未获取到舱室信息");
                    return false;
                }

                // M8-G3-1：保存手调拍摄层为"本地校验/计算 + HTTP 持久化 + 内存同步"打包的关键业务操作，
                // 用 Begin scope 给一个父操作名（统一 traceId 串联其内的 WellUpdateApi HTTP 埋点；module=对焦调试）。
                using var _op = Aivfo.OperationLog.OperationLogger.Begin("对焦调试", "保存手调拍摄层设置",
                    houseSn: CurrentHouseId);

                // 校验：层数≥1、间距>0、下移≥0 且 <层数；非法不保存。
                var eff = ResolveEffectiveTune(out string msg);
                if (eff == null)
                {
                    AddMessageInfo($"[手调拍摄层]保存被拦截(非法值)：{msg}");
                    try { _op.Output(new { rejected = msg }).Fail("校验未通过:" + msg); } catch { }
                    return false;
                }

                // 留空字段=继承设备级 → 写 null（well 级覆盖留空，§2.5）。非空字段写实际值。
                int? wellCount = string.IsNullOrWhiteSpace(ManualLayerCount) ? (int?)null : int.Parse(ManualLayerCount.Trim());
                int? wellSpacing = string.IsNullOrWhiteSpace(ManualLayerSpacing) ? (int?)null : int.Parse(ManualLayerSpacing.Trim());
                // 下移复用 move_down_layer（库列非空）；留空时回退取生效值(eff.down)写回，不破坏旧列语义。
                int wellMoveDown = string.IsNullOrWhiteSpace(ManualMoveDown) ? eff.Value.down : int.Parse(ManualMoveDown.Trim());
                try { _op.Input(new { houseSn = CurrentHouseId, well = ManualTuneWell, wellCount, wellSpacing, wellMoveDown }); } catch { }

                // 复用现有 well 设置保存通道：与 SetWellMotorPosition/SetWellAutoFocus 同一 WellUpdateApi。
                // 后端按 tlSn/houseSn/wellSn 定位 house_well_setting 行做部分更新(仅本次携带的字段)。
                string body = JsonConvert.SerializeObject(new
                {
                    tlSn = CurrentHouse.tlSn,
                    houseSn = CurrentHouse.houseSn,
                    wellSn = ManualTuneWell,
                    focusLayerSpacingPulse = wellSpacing,   // null=继承设备级
                    focusLayerCount = wellCount,            // null=继承设备级
                    moveDownLayer = wellMoveDown,           // 复用既有列(下移)
                });
                bool ok = AppData.Instance.HttpHelper.WellUpdateApi(body);
                if (!ok)
                {
                    AddMessageInfo("[手调拍摄层]保存失败(接口返回失败)");
                    try { _op.Fail("WellUpdateApi 返回失败"); } catch { }
                    return false;
                }

                // 本地内存同步，使"下次该 well 沿用"在不重载设置时也即时生效(预览/取数一致)。
                var ws = houseWellSettingList.FirstOrDefault(x => x.houseSn == CurrentHouseId && x.wellSn == ManualTuneWell);
                if (ws != null)
                {
                    ws.focusLayerCount = wellCount;
                    ws.focusLayerSpacingPulse = wellSpacing;
                    ws.moveDownLayer = wellMoveDown;
                }
                AddMessageInfo($"[手调拍摄层]well{ManualTuneWell} 已存为默认：层数={(wellCount?.ToString() ?? "继承")} " +
                               $"间距={(wellSpacing?.ToString() ?? "继承")} 下移={wellMoveDown}(写 house_well_setting well 级覆盖，留空继承设备级)");
                try { _op.Output(new { ok = true }).Success(); } catch { }
                return true;
            }
            catch (Exception ex)
            {
                ExLog(ex, "SaveManualLayerTune");
                AddMessageInfo($"[手调拍摄层]保存异常：{ex.Message}");
                return false;
            }
        }

        private void SetLayerPreview(List<LayerPreviewItem> items)
        {
            void build()
            {
                LayerPreview.Clear();
                if (items != null)
                    foreach (var it in items) LayerPreview.Add(it);
            }
            var disp = System.Windows.Application.Current?.Dispatcher;
            if (disp != null && !disp.CheckAccess()) disp.Invoke(build); else build();
        }

        #endregion

        #region D2-02-T3.5 保存 per-well 对焦搜索范围(半幅)

        /// <summary>
        /// 当前编辑的 well 级"水平搜索半幅"(围绕 horizontalMotorPosition)。空字符串=留空继承设备级(保存写 null)。
        /// View TextBox 双向绑定;校验在保存时做(非空须为 ≥0 整数)。
        /// </summary>
        [ObservableProperty] private string currentHFocusRange = "";

        /// <summary>
        /// 当前编辑的 well 级"垂直搜索半幅"(围绕 eepromClearPosition/清晰位)。空=继承设备级(写 null)。校验:≥0。
        /// </summary>
        [ObservableProperty] private string currentVFocusRange = "";

        /// <summary>
        /// 取该 well 当前 well 级半幅覆盖值回填两个输入框(空=继承设备级,显示空占位)。供"载入半幅"按钮调用。
        /// 复用 ManualTuneWell 作为锚点 well(与手调拍摄层同一选定 well)。
        /// </summary>
        public void LoadWellFocusRange(int well)
        {
            ManualTuneWell = well;
            var ws = houseWellSettingList.FirstOrDefault(x => x.houseSn == CurrentHouseId && x.wellSn == well);
            CurrentHFocusRange = ws?.horizontalFocusRange?.ToString() ?? "";
            CurrentVFocusRange = ws?.verticalFocusRange?.ToString() ?? "";
            AddMessageInfo($"[对焦半幅]已载入 well{well} 当前覆盖:水平={(ws?.horizontalFocusRange?.ToString() ?? "继承")} 垂直={(ws?.verticalFocusRange?.ToString() ?? "继承")}");
        }

        /// <summary>
        /// D2-02-T3.5 保存该 well 对焦搜索半幅:校验通过后写 house_well_setting well 级覆盖
        /// (horizontal_focus_range/vertical_focus_range)。留空字段=继承设备级(写 null)。
        /// 复用现有 well 设置保存通道 HttpHelper.WellUpdateApi(同 SetWellMotorPosition/SaveManualLayerTune)，
        /// 走 /well/update;后端 well/update 已支持这两列(Java HouseWellSettingUpdate.horizontalFocusRange/verticalFocusRange)。
        /// 字段名与 Java DTO 完全一致:horizontalFocusRange / verticalFocusRange。
        /// 返回 true=保存成功。
        /// </summary>
        public bool SaveWellFocusRange()
        {
            try
            {
                if (CurrentHouse == null)
                {
                    AddMessageInfo("[对焦半幅]未获取到舱室信息");
                    return false;
                }
                if (ManualTuneWell < 1 || ManualTuneWell > 16)
                {
                    AddMessageInfo("[对焦半幅]well 只能为 1-16");
                    return false;
                }

                // 校验:非空须为 ≥0 整数;留空=继承设备级(写 null)。
                int? hRange;
                if (string.IsNullOrWhiteSpace(CurrentHFocusRange)) hRange = null;
                else if (int.TryParse(CurrentHFocusRange.Trim(), out int hv) && hv >= 0) hRange = hv;
                else { AddMessageInfo("[对焦半幅]水平半幅只能输入 ≥0 整数(留空=继承设备级)"); return false; }

                int? vRange;
                if (string.IsNullOrWhiteSpace(CurrentVFocusRange)) vRange = null;
                else if (int.TryParse(CurrentVFocusRange.Trim(), out int vv) && vv >= 0) vRange = vv;
                else { AddMessageInfo("[对焦半幅]垂直半幅只能输入 ≥0 整数(留空=继承设备级)"); return false; }

                // M8 埋点:保存对焦半幅为关键业务操作(统一 traceId 串其内 WellUpdateApi HTTP 埋点)。
                using var _op = Aivfo.OperationLog.OperationLogger.Begin("对焦调试", "保存对焦搜索半幅",
                    houseSn: CurrentHouseId);
                try { _op.Input(new { houseSn = CurrentHouseId, well = ManualTuneWell, horizontalFocusRange = hRange, verticalFocusRange = vRange }); } catch { }

                // body 字段名与 Java HouseWellSettingUpdate 完全一致;留空=null 清空继承设备级(与 SaveManualLayerTune 一致)。
                string body = JsonConvert.SerializeObject(new
                {
                    tlSn = CurrentHouse.tlSn,
                    houseSn = CurrentHouse.houseSn,
                    wellSn = ManualTuneWell,
                    horizontalFocusRange = hRange,   // null=继承设备级 focus_h_range_default
                    verticalFocusRange = vRange,     // null=继承设备级 focus_v_range_default
                });
                bool ok = AppData.Instance.HttpHelper.WellUpdateApi(body);
                if (!ok)
                {
                    AddMessageInfo("[对焦半幅]保存失败(接口返回失败)");
                    try { _op.Fail("WellUpdateApi 返回失败"); } catch { }
                    return false;
                }

                // 本地内存同步,使取数一致(不重载设置即生效)。
                var ws = houseWellSettingList.FirstOrDefault(x => x.houseSn == CurrentHouseId && x.wellSn == ManualTuneWell);
                if (ws != null)
                {
                    ws.horizontalFocusRange = hRange;
                    ws.verticalFocusRange = vRange;
                }
                AddMessageInfo($"[对焦半幅]well{ManualTuneWell} 已保存:水平={(hRange?.ToString() ?? "继承")} 垂直={(vRange?.ToString() ?? "继承")}(写 house_well_setting well 级覆盖，留空继承设备级)");
                try { _op.Output(new { ok = true }).Success(); } catch { }
                return true;
            }
            catch (Exception ex)
            {
                ExLog(ex, "SaveWellFocusRange");
                AddMessageInfo($"[对焦半幅]保存异常：{ex.Message}");
                return false;
            }
        }

        #endregion
    }
}