using System;
namespace IvfTl.Hardware
{
///
/// 单 COM 口的唯一持有者。封装 SerialPort 打开/独占 + 同步请求-响应收发。
/// 蓝本：autofocustool SerialMotor + HouseMotor + Protocol（最权威），
/// 并补回 control/operate 的温压门 / 写EEPROM / 气阀 能力。
/// 所有方法同步阻塞到下位机回复；内部对该口的收发用实例锁串行化（一个 COM 口同一时刻一条在途指令）。
/// 接口签名权威：13 文档 §3.2。返回值约定：位置/计数失败 -1，温压失败 -1m，布尔操作失败 false。
///
public interface ISerialChannel : IDisposable
{
string PortName { get; }
bool IsOpen { get; }
Action Log { get; set; }
// ── 生命周期 ──
/// 打开串口（含 DiscardIn/OutBuffer）。已开返回 true。独占失败返回 false。
bool Open();
void Close();
// ── 读超时策略（按命令类型分超时，13 §3.5/3；属性化，禁止写死单一超时）──
/// 移动类命令(0x05)读超时(ms)，需覆盖最大行程开环回复，默认 12000。
int MoveReadTimeoutMs { get; set; }
/// 查询类命令读超时(ms)，下位机立即回复，默认 3000。
int QueryReadTimeoutMs { get; set; }
/// 电机到位后默认稳定延时(ms)，移动后等机械停稳再抓图，默认 1500（真机标定）。
int MotorSettleMs { get; set; }
// ── 通用收发（底层）──
/// 发送完整命令帧（含校验），按命令码定长阻塞收帧并校验。extraWaitMs：收到回复后额外等待。失败返回 null。
byte[] SendWait(byte[] frame, int extraWaitMs = 0);
// ── 握手 / 自检 ──
/// 握手，返回下位机自报 houseSn。失败 -1。
int ShakeHandsWait();
// ── EEPROM ──
/// 读本舱相机序列号 CCDSN（EEPROM int）。失败 -1。
int ReadCcdSnWait();
/// 读 EEPROM 灯光亮度（只读）。失败 -1。
int ReadLightBrightnessWait();
/// 读第 well(1-16) 的水平电机位置脉冲（EEPROM）。失败 -1。
int ReadWellHorizontalPosWait(int well);
/// 读第 well(1-16) 的 Z 对焦零点脉冲（EEPROM）。失败 -1。
int ReadWellFocusZeroWait(int well);
/// 读垂直电机扫描间隔脉冲（每层 Z 步距，EEPROM）。失败 -1。
int ReadScanStepWait();
/// 写第 well(1-16) 的水平电机位置脉冲（命令码 0x12）。
/// ⚠ 需真机验证：写命令字节序/地址表须按 control Commander.cs 复核（13 §⑤ V1）。
bool WriteWellHorizontalPosWait(int well, int pulseValue);
// ── 写E方调试动作（M1-B2，operate 调试页接入 lease 后走这些；底层 control ComBin builder 已逐字节核实）──
// ⚠ 待真机 V-010：写E方为破坏性操作，回包"成功判定"语义待真机核对（发送字节已核实一致）。
/// 写E方→垂直电机扫描间隔脉冲。成功 true（control 写命令无显式成功出口，发出即视为已下发）。
bool WriteScanStepWait(int pulseValue);
/// 写E方→舱室进气阀打开时间。isBuffer=true 写缓冲瓶进气阀时间。
bool WriteOpenIntakeTimeWait(int newValue, bool isBuffer = false);
/// 写E方→舱室排气阀打开时间。control Commander 暂缺该 builder → 返回 false（调试页保留旧路径/待真机）。
bool WriteOpenVentTimeWait(int newValue);
/// 读E方→舱室排气阀打开时间。control Commander 暂缺该 builder → 返回 -1（待真机）。
int ReadOpenVentTimeWait();
/// 写E方→灯光亮度。control Commander 暂缺写 builder → 返回 false（调试页保留旧路径/待真机）。
bool WriteLightBrightnessWait(int newValue);
// ── 电机：垂直（Z=对焦轴）/ 水平（皿孔定位）──
/// Z 绝对运动到脉冲，delayMs 缺省用 MotorSettleMs；扫描小步可传短延时提速。失败 false。
bool VerticalMoveToWait(int pulse, int delayMs = -1);
bool VerticalForwardWait(int pulse, int delayMs = -1);
bool VerticalBackwardWait(int pulse, int delayMs = -1);
bool VerticalResetWait(int delayMs = -1);
/// 读 Z 当前位置脉冲。失败 -1。
int ReadVerticalPositionWait();
bool HorizontalMoveToWait(int pulse, int delayMs = -1);
bool HorizontalForwardWait(int pulse, int delayMs = -1);
bool HorizontalBackwardWait(int pulse, int delayMs = -1);
bool HorizontalResetWait(int delayMs = -1);
int ReadHorizontalPositionWait();
// ── 环境量（温压门，control/operate 有，af 无）──
/// 下盖板温度(℃)，失败 -1m。
decimal TemperatureWait();
decimal ShangTemperatureWait(); // 上盖板
decimal BoLiTemperatureWait(); // 玻璃片下方
decimal PressureWait(); // 舱内气压
(decimal pressure, decimal t1, decimal t2) BufferBottleStateWait(); // 缓冲瓶
/// 仓门状态。失败返回 未知。
DoorState DoorStatusWait();
// ── IO / LED / 气阀（control/operate 全，af 仅 LED）──
bool OpenLedWait();
bool CloseLedWait();
bool OpenIntakeValveWait();
bool CloseIntakeValveWait();
bool OpenExhaustValveWait();
bool CloseExhaustValveWait();
bool HouseAerationWait(); // 舱室补气
bool HouseVentWait(); // 舱室排气
bool BufferBottleAerationWait(); // 缓冲瓶补气
/// 自动气体交换开/关（对应 operate AutoWait）。
bool AutoAirSwapWait(bool on);
// ── 直通底层 ComBin（迁移期过渡：调试/采集若需要 ComBin 上 HAL 接口未覆盖的方法可暂取裸实例）──
/// 桥接对象：返回内部包装的具体 ComBin（object 以避免 HAL 接口耦合具体类型）。
/// 仅供迁移期老调用方过渡使用，新代码应只用本接口方法。
object RawComBin { get; }
}
/// 仓门状态（对应 control State 枚举的 未知/打开/关闭 子集）。
public enum DoorState { 未知, 打开, 关闭 }
}