# RaySourceOperateView 使用说明

## 概述

`RaySourceOperateView` 是射线源操作和监控面板，提供射线源开关控制、电压电流实时调节和状态监控功能。

## 架构设计

### MVVM 模式

- **View**: `RaySourceOperateView.xaml` - WPF 用户控件界面
- **ViewModel**: `RaySourceOperateViewModel.cs` - 视图模型，处理业务逻辑
- **Model**: `RaySourceStatus.cs` - 射线源状态枚举（Unavailable / Closed / Opened）

### 依赖注入

ViewModel 通过构造函数注入以下依赖：
- `IRaySourceService` - 射线源业务服务
- `IEventAggregator` - Prism 事件聚合器
- `RaySourceConfig` - 射线源配置
- `ILoggerService` - 日志服务
- `ILocalizationService` - 多语言服务

## 功能特性

### 1. 状态监控

- **腰圆状态指示器**：
  - 灰色径向渐变 = 射线源不可用（Unavailable）
  - 绿色径向渐变 (#8BC34A → #4CAF50) = 射线源已关闭（Closed）
  - 红色径向渐变 (#FF8A80 → #F44336) = 射线源已开启（Opened）
- **呼吸闪烁动画**：射线源开启时，状态指示器播放呼吸闪烁动画（透明度 1.0 → 0.6 循环，周期约 1.5 秒）
- **实时状态文本**：通过 `ILocalizationService` 获取多语言状态文字

### 2. 射线源控制

- **开启射线源按钮**：
  - 仅在 Closed 状态、已初始化且变量已连接时可用
  - 调用 `IRaySourceService.TurnOn()`
  - 按钮文字通过多语言绑定：`{loc:Localization RaySource_TurnOnButton}`
- **关闭射线源按钮**：
  - 仅在 Opened 状态、已初始化且变量已连接时可用
  - 调用 `IRaySourceService.TurnOff()`
  - 按钮文字通过多语言绑定：`{loc:Localization RaySource_TurnOffButton}`
- **配置按钮**：
  - 打开 `RaySourceConfigWindow`（射线源配置窗口）
  - 窗口已存在时激活而非重复创建
- **高级/设置按钮**：
  - 启动外部高级设置程序（`FXEControl.exe`）
  - 如果程序已运行则将窗口置前
  - 使用 `ProcessHelper.StartOrActivate()` 实现

### 3. 电压调节

- **滑块范围**：从配置文件读取（默认 20-225 kV）
- **双向绑定**：滑块和数值输入框绑定同一属性 `VoltageValue`，使用 `Mode=TwoWay`
- **延迟拖拽**：滑块使用 `IsDeferredDraggingEnabled="True"`，松手时才提交值
- **手动提交**：通过 `ApplyVoltageCommand` 提交电压值到硬件（滑块松手/输入框失焦时触发）
- **启用条件**：仅在服务已初始化且变量已连接时可调节（`IsSlidersEnabled`）
- **范围显示**：滑块下方显示最小值和最大值
- **实际值显示**：右上角显示当前实际电压值

### 4. 电流调节

- **滑块范围**：从配置文件读取（默认 10-1000 μA）
- **双向绑定**：滑块和数值输入框绑定同一属性 `CurrentValue`，使用 `Mode=TwoWay`
- **延迟拖拽**：滑块使用 `IsDeferredDraggingEnabled="True"`，松手时才提交值
- **手动提交**：通过 `ApplyCurrentCommand` 提交电流值到硬件
- **启用条件**：仅在服务已初始化且变量已连接时可调节（`IsSlidersEnabled`）
- **范围显示**：滑块下方显示最小值和最大值
- **实际值显示**：右上角显示当前实际电流值

### 5. 自动初始化

- ViewModel 提供 `AutoInitializeAsync()` 方法
- 由 View 的 `Loaded` 事件触发，仅执行一次
- 异步执行 `InitializeAndConnectAsync()`（初始化 + 连接变量）
- 如果已初始化且变量已连接则跳过

## 关联视图：RaySourceConfigView

`RaySourceConfigView` 是射线源配置和设备状态监控面板，通过 `RaySourceConfigWindow` 包裹为独立窗口。

### ConfigView 功能

- **设备信息**：显示射线源类型和连接状态（颜色编码：灰色=未连接，橙色=已初始化，绿色=变量已连接）
- **操作按钮**：初始化 / 连接变量 / 断开（三列等宽布局）
- **设备状态面板**：暖机/真空/启动/自动定心/灯丝校准/射线开启/连锁/看门狗/TXI/功率模式
- **TXI 控制**：TXI ON / TXI OFF 按钮
- **功率模式切换**：High Power / Micro Focus 按钮
- **功能设置按钮**：暖机设置 / 训机设置 / 灯丝校准 / 自动定心（四列等宽布局，带确认对话框和进度条窗口）
- **灯丝寿命进度条**：显示灯丝使用百分比（60 秒定时刷新），颜色随百分比变化（绿/黄/红）

### ConfigView 依赖注入

- `IRaySourceService` - 射线源业务服务
- `IEventAggregator` - Prism 事件聚合器
- `RaySourceConfig` - 射线源配置
- `ILoggerService` - 日志服务
- `ILocalizationService` - 多语言服务
- `IFilamentLifetimeService` - 灯丝寿命管理服务

## 多语言支持

### XAML 中使用

```xml
xmlns:loc="clr-namespace:XP.Common.Localization.Extensions;assembly=XP.Common"

<TextBlock Text="{loc:Localization RaySource_VoltageLabel}"/>
<telerik:RadButton Content="{loc:Localization RaySource_TurnOnButton}"/>
```

### ViewModel 中使用

```csharp
_localizationService.GetString("RaySource_StatusClosed")
```

### 资源键列表

#### OperateView 资源键

| 资源键 | 中文 | 英文 |
|--------|------|------|
| RaySource_VoltageLabel | 电压（kV） | Voltage (kV) |
| RaySource_CurrentLabel | 电流（μA） | Current (μA) |
| RaySource_ActualValueLabel | 当前值: {0} | Actual: {0} |
| RaySource_TurnOnButton | 开启射线源 | Turn On X-Ray |
| RaySource_TurnOffButton | 关闭射线源 | Turn Off X-Ray |
| RaySource_AdvanceButton | 高级 | Advance |
| RaySource_ConfigButton | 配置 | Config |
| RaySource_StatusUnavailable | 射线源\n不可用 | X-Ray\nUnavailable |
| RaySource_StatusClosed | 射线源\n已关闭 | X-Ray\nClosed |
| RaySource_StatusOpened | 射线源\n已开启 | X-Ray\nOpened |

#### ConfigView 资源键

| 资源键 | 中文 | 英文 |
|--------|------|------|
| RaySource_SourceTypeLabel | 射线源类型 | Source Type |
| RaySource_InitializeButton | 初始化 | Initialize |
| RaySource_ConnectVariablesButton | 连接变量 | Connect Variables |
| RaySource_DisconnectButton | 断开 | Disconnect |
| RaySource_WarmUpLabel | 暖机 | Warm-up |
| RaySource_VacuumLabel | 真空 | Vacuum |
| RaySource_StartUpLabel | 启动 | Startup |
| RaySource_AutoCenterLabel | 自动定心 | Auto-center |
| RaySource_FilamentLabel | 灯丝校准 | Filament |
| RaySource_XRayOnLabel | 射线 | X-Ray |
| RaySource_InterlockLabel | 连锁 | Interlock |
| RaySource_WatchdogLabel | 看门狗 | Watchdog |
| RaySource_TxiStatusLabel | TXI | TXI |
| RaySource_TxiOnButton | TXI ON | TXI ON |
| RaySource_TxiOffButton | TXI OFF | TXI OFF |
| RaySource_PowerModeLabel | 功率模式 | Power Mode |
| RaySource_HighPowerButton | High Power | High Power |
| RaySource_MicroFocusButton | Micro Focus | Micro Focus |
| RaySource_WarmUpSettingButton | 暖机设置 | Warm-up |
| RaySource_TrainingSettingButton | 训机设置 | Training |
| RaySource_FilamentCalibrationButton | 灯丝校准 | Filament Cal. |
| RaySource_AutoCenterSettingButton | 自动定心 | Auto-center |
| RaySource_FilamentLifetimeLabel | 灯丝寿命 | Filament Life |
| RaySource_ConfigWindowTitle | 射线源配置 | X-Ray Source Config |

> 注意：多语言仅在应用启动时加载，无需运行时热切换。

## 呼吸闪烁动画

射线源开启时，状态指示器播放呼吸闪烁动画，增强视觉警示效果。

### 动画定义

```xml
<Storyboard x:Key="BreathingAnimation" RepeatBehavior="Forever">
    <DoubleAnimation Storyboard.TargetProperty="Opacity"
                     From="1.0" To="0.6" Duration="0:0:0.75"
                     AutoReverse="True"/>
</Storyboard>
```

### 触发机制

通过 `DataTrigger` 监听 `RaySourceStatus` 属性：
- 当状态变为 `Opened` 时，自动开始动画
- 当状态离开 `Opened` 时，自动停止动画

## 事件订阅

### OperateViewModel 订阅事件

1. **RaySourceStatusChangedEvent**：射线源状态变更（三态）
   - 更新 `RaySourceStatus` 属性和按钮/滑块启用状态
   - 异常断联时重置变量连接状态

2. **StatusUpdatedEvent**：系统状态更新
   - 更新实际电压和电流值（仅在值真正变化时更新，避免无意义赋值）
   - 同步服务层权威状态

3. **ErrorOccurredEvent**：错误发生
   - 显示错误消息对话框

4. **OperationResultEvent**：操作结果
   - 操作失败时显示警告消息

5. **VariablesConnectedEvent**：变量连接状态变更
   - 更新 `IsVariablesConnected` 属性
   - 连接成功时主动读取最新设备状态

### ConfigViewModel 订阅事件

1. **RaySourceStatusChangedEvent**：刷新初始化状态和命令可执行状态
2. **StatusUpdatedEvent**：刷新设备状态面板所有字段
3. **VariablesConnectedEvent**：刷新连接状态和命令可执行状态

## 数据绑定

### OperateView 状态绑定

```xml
<!-- 状态指示器背景色（径向渐变）-->
Background="{Binding RaySourceStatus, Converter={StaticResource StatusToColorConverter}}"

<!-- 状态指示器边框色 -->
BorderBrush="{Binding RaySourceStatus, Converter={StaticResource StatusToBorderColorConverter}}"

<!-- 状态文本（多语言）-->
Text="{Binding StatusText}"
```

### OperateView 命令绑定

```xml
<telerik:RadButton Content="{loc:Localization RaySource_TurnOnButton}" Command="{Binding TurnOnCommand}"/>
<telerik:RadButton Content="{loc:Localization RaySource_TurnOffButton}" Command="{Binding TurnOffCommand}"/>
<telerik:RadButton Content="{loc:Localization RaySource_AdvanceButton}" Command="{Binding SettingsCommand}"/>
<telerik:RadButton Content="{loc:Localization RaySource_ConfigButton}" Command="{Binding ConfigCommand}"/>
```

### OperateView 滑块绑定

```xml
<!-- 电压滑块（延迟拖拽模式）-->
<telerik:RadSlider Minimum="{Binding VoltageMin}" Maximum="{Binding VoltageMax}"
                   Value="{Binding VoltageValue, Mode=TwoWay}"
                   IsDeferredDraggingEnabled="True"
                   IsEnabled="{Binding IsSlidersEnabled}"/>

<!-- 电压数值输入框 -->
<telerik:RadNumericUpDown Minimum="{Binding VoltageMin}" Maximum="{Binding VoltageMax}"
                          Value="{Binding VoltageValue, Mode=TwoWay}"
                          IsEnabled="{Binding IsSlidersEnabled}" NumberDecimalDigits="1"/>
```

## 转换器

### 1. RaySourceStatusToColorConverter
将 `RaySourceStatus` 枚举转换为径向渐变背景色：
- `Unavailable` → 灰色渐变（#E0E0E0 → #BDBDBD）
- `Closed` → 绿色渐变（#8BC34A → #4CAF50）
- `Opened` → 红色渐变（#FF8A80 → #F44336）

### 2. RaySourceStatusToBorderColorConverter
将 `RaySourceStatus` 枚举转换为边框色：
- `Unavailable` → #9E9E9E
- `Closed` → #2E7D32
- `Opened` → #C62828

### 3. FilamentLifetimeColorConverter
将灯丝寿命百分比转换为进度条颜色：
- < 80% → 绿色 (#4CAF50)
- 80%-89% → 黄色 (#FFC107)
- ≥ 90% → 红色 (#E53935)

## 业务规则

### 安全规则

1. **未初始化禁止操作**：所有操作前检查 `IsInitialized` 和 `IsVariablesConnected`
2. **参数范围校验**：电压和电流值必须在配置的范围内
3. **操作失败回滚**：设置失败时恢复滑块到实际值（仅当实际值在有效范围内时）
4. **连接丢失处理**：连接丢失时状态设为 `Unavailable`，重置变量连接状态，禁用所有操作
5. **设备反馈保护**：`IsUpdatingFromDevice` 标志防止设备反馈更新时误触发写入

### 状态管理

- 状态变更通过事件驱动，确保 UI 与硬件状态同步
- 使用 `RaisePropertyChanged` 通知 UI 更新
- 命令的 `CanExecute` 自动监听状态变化
- 三态管理：Unavailable → Closed → Opened

## 使用示例

### 在独立窗口中使用

```csharp
var raySourceView = _containerProvider.Resolve<RaySourceOperateView>();
var window = new Window
{
    Title = "射线源操作",
    Content = raySourceView,
    SizeToContent = SizeToContent.WidthAndHeight,
    ResizeMode = ResizeMode.NoResize,
    WindowStartupLocation = WindowStartupLocation.CenterOwner,
    Owner = Application.Current.MainWindow
};
window.ShowDialog();
```

### 在主窗口 Region 中加载

```xml
<ContentControl prism:RegionManager.RegionName="RaySourceOperateRegion" />
```

```csharp
_regionManager.RequestNavigate("RaySourceOperateRegion", "RaySourceOperateView");
```

## XAML 命名空间引用

```xml
xmlns:local="clr-namespace:XP.Hardware.RaySource.Views"
xmlns:converters="clr-namespace:XP.Hardware.RaySource.Converters"
xmlns:enums="clr-namespace:XP.Hardware.RaySource.Abstractions.Enums"
xmlns:loc="clr-namespace:XP.Common.Localization.Extensions;assembly=XP.Common"
xmlns:prism="http://prismlibrary.com/"
xmlns:telerik="http://schemas.telerik.com/2008/xaml/presentation"
```

## 注意事项

1. **线程安全**：所有事件处理使用 `ThreadOption.UIThread` 确保在 UI 线程执行
2. **资源释放**：ViewModel 实现 `IDisposable`，在 Dispose 时取消事件订阅、断开射线源连接、关闭配置窗口
3. **同步操作**：硬件操作为同步方法，ViewModel 中直接调用（不阻塞 UI 因为操作通过 IPC 快速返回）
4. **错误处理**：所有操作包含 try-catch，确保异常不会导致程序崩溃
5. **多语言**：所有界面文字通过 `{loc:Localization}` 或 `ILocalizationService` 获取，无硬编码文字
6. **动画性能**：呼吸闪烁动画使用 WPF Storyboard，性能开销极低
7. **日志规范**：使用 `_logger.ForModule("RaySource.ViewModel")` 和结构化日志消息
8. **自动初始化**：OperateView 加载时自动执行 `AutoInitializeAsync()`，仅执行一次
9. **配置窗口**：通过 ConfigCommand 打开，单例模式（已存在时激活而非重复创建）

## 故障排查

### 按钮不可用
- 检查 `IsInitialized` 和 `IsVariablesConnected` 状态
- 检查 `RaySourceStatus` 是否正确
- 查看命令的 `CanExecute` 逻辑

### 滑块不可用
- 确认服务已初始化且变量已连接（`IsSlidersEnabled`）

### 实际值不更新
- 确认已订阅 `StatusUpdatedEvent`
- 检查 Host 进程是否正常推送状态
- 验证 `ThreadOption.UIThread` 设置

### 设置值不生效
- 检查 `ApplyVoltageCommand` / `ApplyCurrentCommand` 是否正确触发
- 查看业务规则校验逻辑
- 确认 IPC 管道连接正常

### 多语言文字不显示
- 确认 XP.Common 资源文件中已添加对应的资源键
- 检查 XAML 中 `xmlns:loc` 命名空间引用是否正确

### 动画不播放
- 确认 `RaySourceStatus` 已变为 `Opened`
- 检查 `enums` 命名空间引用是否正确

### 状态显示为"不可用"
- 检查射线源服务连接状态
- 确认 Host 进程是否正常运行
- 查看日志中是否有连接丢失的警告信息

---

**最后更新 | Last Updated**: 2026-03-26