运动控制：新增射线源与探测器 Z 轴联动移动功能，支持同步位移控制，新增实体摇杆实现 PLC 摇杆状态监控和事件发布，IMotionSystem 接口新增 Joystick 属性，更新文档说明联动功能使用方法。

XP.Hardware.MotionControl/Documents/GUIDENCE.md

@@ -21,7 +21,80 @@ protected override void ConfigureModuleCatalog(IModuleCatalog moduleCatalog)
 
 ---
 
-## 2. 获取轴状态和位置 | Reading Axis Status and Position
+## 2. 界面集成 | UI Integration
+
+### AxisControlView 控件使用 | AxisControlView Usage
+
+`AxisControlView` 是运动控制模块的核心用户控件，提供完整的轴控制和调试功能。
+
+**XAML 引用 | XAML Reference**
+
+```xml
+<UserControl x:Class="YourView"
+             xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
+             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+             xmlns:motion="clr-namespace:XP.Hardware.MotionControl.Views;assembly=XP.Hardware.MotionControl">
+    
+    <Grid>
+        <!-- 基本使用 | Basic usage -->
+        <motion:AxisControlView />
+        
+        <!-- 设置最小宽度 | Set minimum width -->
+        <motion:AxisControlView MinWidth="400" />
+    </Grid>
+</UserControl>
+```
+
+**自动 ViewModel 绑定 | Auto ViewModel Binding**
+
+控件使用 Prism 的 `ViewModelLocator.AutoWireViewModel="True"` 自动绑定 `AxisControlViewModel`，无需手动设置 `DataContext`。
+
+**ViewModel 属性说明 | ViewModel Properties**
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `StageXPosition` | double | 载物台 X 轴位置（mm），范围由配置决定 |
+| `StageYPosition` | double | 载物台 Y 轴位置（mm），范围由配置决定 |
+| `SourceZPosition` | double | 射线源 Z 轴位置（mm），范围由配置决定 |
+| `DetectorZPosition` | double | 探测器 Z 轴位置（mm），范围由配置决定 |
+| `DetectorSwingAngle` | double | 探测器摆动角度（度），范围 -45~45 |
+| `StageRotationAngle` | double | 载物台旋转角度（度），范围 -360~360 |
+| `FixtureRotationAngle` | double | 夹具旋转角度（度），范围 -90~90 |
+| `IsJoystickEnabled` | bool | 摇杆使能开关（默认 false） |
+| `SwapMouseButtons` | bool | 摇杆左右键功能切换（默认 false） |
+| `SZDZLock` | bool | 射线源/探测器Z轴锁定移动（默认 false） |
+| `HasSavedPositions` | bool | 是否有已保存的位置快照 |
+
+**交互方式 | Interaction Modes**
+
+1. **手动输入位置**
+   - 直接编辑 RadNumericUpDown 控件
+   - Enter 键确认并移动轴
+   - Escape 键取消修改，恢复原值
+
+2. **单轴摇杆（SourceZ/DetectorZ）**
+   - 左键拖拽：正向 Jog
+   - 右键拖拽：反向 Jog
+   - 松开鼠标：停止 Jog
+
+3. **双轴摇杆（StageX/Y + Rotation）**
+   - 默认模式（SwapMouseButtons=false）：
+     - 左键拖拽：控制 StageX/Y（X轴=左右，Y轴=上下）
+     - 右键拖拽：控制 StageRotation（X轴=旋转）
+   - 切换模式（SwapMouseButtons=true）：
+     - 左键拖拽：控制 StageRotation（X轴=旋转）
+     - 右键拖拽：控制 DetectorSwing（X轴=摆动，Y轴=摆动）
+
+4. **快捷按钮**
+   - **使能开关**：启用/禁用摇杆控制（图标切换）
+   - **摇杆模式**：切换左右键功能（图标切换）
+   - **SZDZ锁定**：锁定 SourceZ/DetectorZ 同步移动（图标切换）
+   - **保存位置**：保存当前所有轴位置到快照
+   - **恢复位置**：恢复到上次保存的位置快照
+
+---
+
+## 3. 获取轴状态和位置 | Reading Axis Status and Position
 
 通过 DI 注入 `IMotionSystem`：
 
@@ -154,7 +227,7 @@ public class YourController
 
 ---
 
-## 4. 几何计算 | Geometry Calculation
+## 5. 几何计算 | Geometry Calculation
 
 ```csharp
 public class YourGeometryUser
@@ -207,7 +280,7 @@ public class YourGeometryUser
 
 ---
 
-## 5. 事件订阅 | Event Subscription
+## 6. 事件订阅 | Event Subscription
 
 通过 Prism `IEventAggregator` 被动接收状态变化：
 
@@ -260,35 +333,86 @@ public class YourMonitor
 
 ---
 
-## 6. PLC 信号定义 | PLC Signal Definitions
+## 7. PLC 信号定义 | PLC Signal Definitions
 
-信号名称硬编码在 `MotionSignalNames.cs` 中，信号地址定义在 `PlcAddrDfn.xml`。
+信号名称硬编码在 `MotionSignalNames.cs` 中，信号地址定义在 `PlcAddrDfn.xml`（位于 `XplorePlane/bin/Debug/net8.0-windows/win-x64/`）。
 
-每个轴包含以下信号（以 SourceZ 为例）：
+### 7.1 写入信号（WriteCommon，DB31）
 
-| 信号名 | 方向 | 类型 | 说明 |
+| 信号名 | 类型 | 地址 | 说明 |
 |--------|------|------|------|
-| `MC_SourceZ_Pos` | Read | single | 实际位置 |
-| `MC_SourceZ_Target` | Write | single | 目标位置 |
-| `MC_SourceZ_Speed` | Write | single | 运动速度 |
-| `MC_SourceZ_JogPos` | Write | byte | 正向 Jog |
-| `MC_SourceZ_JogNeg` | Write | byte | 反向 Jog |
-| `MC_SourceZ_Home` | Write | byte | 回零 |
-| `MC_SourceZ_Stop` | Write | byte | 停止 |
+| `MC_SourceZ_Target` | single | 10 | 射线源Z目标位置（mm） |
+| `MC_SourceZ_Speed` | single | 14 | 射线源Z运动速度 |
+| `MC_SourceZ_JogPos` | byte | 18 | 射线源Z正向Jog |
+| `MC_SourceZ_JogNeg` | byte | 19 | 射线源Z反向Jog |
+| `MC_SourceZ_Home` | byte | 20 | 射线源Z回零 |
+| `MC_SourceZ_Stop` | byte | 21 | 射线源Z停止 |
+| `MC_DetZ_Target` | single | 22 | 探测器Z目标位置（mm） |
+| `MC_DetZ_Speed` | single | 26 | 探测器Z运动速度 |
+| `MC_DetZ_JogPos` | byte | 30 | 探测器Z正向Jog |
+| `MC_DetZ_JogNeg` | byte | 31 | 探测器Z反向Jog |
+| `MC_DetZ_Home` | byte | 32 | 探测器Z回零 |
+| `MC_DetZ_Stop` | byte | 33 | 探测器Z停止 |
+| `MC_StageX_Target` | single | 34 | 载物台X目标位置（mm） |
+| `MC_StageX_Speed` | single | 38 | 载物台X运动速度 |
+| `MC_StageX_JogPos` | byte | 42 | 载物台X正向Jog |
+| `MC_StageX_JogNeg` | byte | 43 | 载物台X反向Jog |
+| `MC_StageX_Home` | byte | 44 | 载物台X回零 |
+| `MC_StageX_Stop` | byte | 45 | 载物台X停止 |
+| `MC_StageY_Target` | single | 46 | 载物台Y目标位置（mm） |
+| `MC_StageY_Speed` | single | 50 | 载物台Y运动速度 |
+| `MC_StageY_JogPos` | byte | 54 | 载物台Y正向Jog |
+| `MC_StageY_JogNeg` | byte | 55 | 载物台Y反向Jog |
+| `MC_StageY_Home` | byte | 56 | 载物台Y回零 |
+| `MC_StageY_Stop` | byte | 57 | 载物台Y停止 |
+| `MC_DetSwing_Target` | single | 58 | 探测器摆动目标角度（度） |
+| `MC_DetSwing_Speed` | single | 62 | 探测器摆动运动速度 |
+| `MC_DetSwing_JogPos` | byte | 66 | 探测器摆动正向Jog |
+| `MC_DetSwing_JogNeg` | byte | 67 | 探测器摆动反向Jog |
+| `MC_DetSwing_Home` | byte | 68 | 探测器摆动回零 |
+| `MC_DetSwing_Stop` | byte | 69 | 探测器摆动停止 |
+| `MC_StageRot_Target` | single | 70 | 载物台旋转目标角度（度） |
+| `MC_StageRot_Speed` | single | 74 | 载物台旋转运动速度 |
+| `MC_StageRot_JogPos` | byte | 78 | 载物台旋转正向Jog |
+| `MC_StageRot_JogNeg` | byte | 79 | 载物台旋转反向Jog |
+| `MC_StageRot_Home` | byte | 80 | 载物台旋转回零 |
+| `MC_StageRot_Stop` | byte | 81 | 载物台旋转停止 |
+| `MC_FixRot_Target` | single | 82 | 夹具旋转目标角度（度） |
+| `MC_FixRot_Speed` | single | 86 | 夹具旋转运动速度 |
+| `MC_FixRot_JogPos` | byte | 90 | 夹具旋转正向Jog |
+| `MC_FixRot_JogNeg` | byte | 91 | 夹具旋转反向Jog |
+| `MC_FixRot_Home` | byte | 92 | 夹具旋转回零 |
+| `MC_FixRot_Stop` | byte | 93 | 夹具旋转停止 |
+| `MC_Door_Open` | byte | 94 | 安全门开门 |
+| `MC_Door_Close` | byte | 95 | 安全门关门 |
+| `MC_Door_Stop` | byte | 96 | 安全门停止 |
+| `MC_SourceDetZ_Linkage_Enable` | bool | 101 | 射线源与探测器Z轴联动使能 |
+| `MC_VirtualJoystick_Enable` | bool | 111 | 虚拟摇杆使能 |
 
-安全门信号：
+### 7.2 读取信号（ReadCommon，DB31）
 
-| 信号名 | 方向 | 说明 |
-|--------|------|------|
-| `MC_Door_Open` | Write | 开门 |
-| `MC_Door_Close` | Write | 关门 |
-| `MC_Door_Stop` | Write | 停门 |
-| `MC_Door_Status` | Read | 门状态（int: 0-6） |
-| `MC_Door_Interlock` | Read | 联锁信号 |
+| 信号名 | 类型 | 地址 | 说明 |
+|--------|------|------|------|
+| `MC_SourceZ_Pos` | single | 100 | 射线源Z实际位置（mm） |
+| `MC_DetZ_Pos` | single | 104 | 探测器Z实际位置（mm） |
+| `MC_StageX_Pos` | single | 108 | 载物台X实际位置（mm） |
+| `MC_StageY_Pos` | single | 112 | 载物台Y实际位置（mm） |
+| `MC_DetSwing_Angle` | single | 116 | 探测器摆动实际角度（度） |
+| `MC_StageRot_Angle` | single | 120 | 载物台旋转实际角度（度） |
+| `MC_FixRot_Angle` | single | 124 | 夹具旋转实际角度（度） |
+| `MC_Door_Status` | byte | 128 | 安全门状态（0:未知,1:开门中,2:已开,3:关门中,4:已关,5:已锁定,6:故障） |
+| `MC_Door_Interlock` | byte | 130 | 安全门联锁信号（0:无联锁,10:联锁有效） |
+| `MC_Joystick_Active` | bool | 110 | 实体摇杆输入激活 |
+
+### 7.3 信号类型说明 | Signal Type Notes
+
+- **single**：32位浮点数（4字节）
+- **byte**：8位无符号整数（1字节）
+- **bool**：布尔值（1字节，0=false, 非0=true）
 
 ---
 
-## 7. 安全机制 | Safety Mechanisms
+## 8. 安全机制 | Safety Mechanisms
 
 | 机制 | 说明 |
 |------|------|
@@ -303,7 +427,7 @@ public class YourMonitor
 
 ---
 
-## 8. 轮询机制 | Polling Mechanism
+## 9. 轮询机制 | Polling Mechanism
 
 `MotionControlService` 使用 `System.Threading.Timer` 以配置的 `PollingInterval`（默认 100ms）周期执行：
 
@@ -319,4 +443,4 @@ public class YourMonitor
 
 ---
 
-**最后更新 | Last Updated**: 2026-04-14
+**最后更新 | Last Updated**: 2026-05-08