ScreenLockDetector/docs/MIGRATION_GUIDE.md

# ScreenLockDetector 迁移指南

## 从旧版本迁移到重构版本

本指南帮助您从旧的单一类结构迁移到新的面向对象架构。

## 好消息：无需修改代码！

如果您只使用 `ScreenLockDetector` 类的公共接口，**无需修改任何代码**。新版本完全向后兼容。

### 接口保持不变

```cpp
// 创建实例（保持不变）
ScreenLockDetector *detector = new ScreenLockDetector(parent);

// 初始化（保持不变）
detector->initialize();

// 获取状态（保持不变）
bool locked = detector->isScreenLocked();

// 连接信号（保持不变）
connect(detector, &ScreenLockDetector::screenLocked, ...);
connect(detector, &ScreenLockDetector::screenUnlocked, ...);
connect(detector, &ScreenLockDetector::lockStateChanged, ...);
```

## 架构变化

### 旧架构
```
ScreenLockDetector
  ├── Linux 代码 (#ifdef Q_OS_LINUX)
  └── macOS 代码 (#ifdef Q_OS_MAC)
```

### 新架构
```
ScreenLockDetectorBase (抽象基类)
  ├── ScreenLockDetectorLinux
  └── ScreenLockDetectorMacOS

ScreenLockDetector (工厂类)
```

## 文件重命名对照表

| 旧文件名 | 新文件名 | 说明 |
|---------|---------|------|
| `screenlockdetector_mac.h` | `screenlockdetector_macos.h` | 规范化命名 |
| `screenlockdetector_mac.mm` | `screenlockdetector_macos.mm` | 规范化命名 |
| N/A | `screenlockdetector_base.h` | 新增抽象基类 |
| N/A | `screenlockdetector_base.cpp` | 新增抽象基类 |
| N/A | `screenlockdetector_linux.h` | Linux 实现分离 |
| N/A | `screenlockdetector_linux.cpp` | Linux 实现分离 |

## 如果您扩展了原类

如果您继承或扩展了 `ScreenLockDetector` 类，需要做以下调整：

### 场景 1: 继承 ScreenLockDetector

**旧代码:**
```cpp
class MyDetector : public ScreenLockDetector {
    // 自定义实现
};
```

**新代码 - 选项 A (推荐):**
继承抽象基类并实现自己的平台
```cpp
class MyDetector : public ScreenLockDetectorBase {
public:
    bool initialize() override {
        // 您的实现
        return true;
    }
};
```

**新代码 - 选项 B:**
继承现有的平台实现
```cpp
#ifdef Q_OS_LINUX
class MyDetector : public ScreenLockDetectorLinux {
    // 扩展 Linux 实现
};
#endif
```

### 场景 2: 访问平台特定成员

**旧代码:**
```cpp
#ifdef Q_OS_LINUX
detector->m_gnomeInterface->call(...);
#endif
```

**新方法:**
平台特定成员现在是私有的。如果需要访问，应该：

1. 添加公共方法到对应的平台类
2. 或者通过信号/槽机制通信
3. 或者使用组合而非继承

```cpp
// 示例：添加新方法到平台类
class ScreenLockDetectorLinux : public ScreenLockDetectorBase {
public:
    // 添加新的公共方法
    bool querySpecificState() {
        if (m_gnomeInterface) {
            return m_gnomeInterface->call("GetActive").value();
        }
        return false;
    }
};
```

## 构建系统变化

### CMakeLists.txt

如果您修改了 `CMakeLists.txt`，请注意源文件列表的变化：

**旧配置:**
```cmake
if(APPLE)
    list(APPEND SOURCES
        src/screenlockdetector.cpp
        src/screenlockdetector_mac.mm
    )
endif()
```

**新配置:**
```cmake
# 通用源文件（所有平台）
set(SOURCES
    src/screenlockdetector.cpp
    src/screenlockdetector_base.cpp
    ...
)

# 平台特定源文件
if(APPLE)
    list(APPEND SOURCES
        src/screenlockdetector_macos.mm
    )
elseif(UNIX)
    list(APPEND SOURCES
        src/screenlockdetector_linux.cpp
    )
endif()
```

## 添加新平台支持

新架构使添加平台变得更容易：

### 步骤 1: 创建平台类

```cpp
// screenlockdetector_windows.h
#ifndef SCREENLOCKDETECTOR_WINDOWS_H
#define SCREENLOCKDETECTOR_WINDOWS_H

#include "screenlockdetector_base.h"

#ifdef Q_OS_WIN
class ScreenLockDetectorWindows : public ScreenLockDetectorBase {
    Q_OBJECT
public:
    explicit ScreenLockDetectorWindows(QObject *parent = nullptr);
    ~ScreenLockDetectorWindows() override;
    bool initialize() override;
};
#endif

#endif
```

### 步骤 2: 实现平台类

```cpp
// screenlockdetector_windows.cpp
#include "screenlockdetector_windows.h"

#ifdef Q_OS_WIN
ScreenLockDetectorWindows::ScreenLockDetectorWindows(QObject *parent)
    : ScreenLockDetectorBase(parent) {
}

bool ScreenLockDetectorWindows::initialize() {
    // Windows 特定的初始化代码
    return true;
}
#endif
```

### 步骤 3: 更新工厂方法

```cpp
// screenlockdetector.cpp
ScreenLockDetectorBase* ScreenLockDetector::createPlatformDetector() {
#ifdef Q_OS_MAC
    return new ScreenLockDetectorMacOS(this);
#elif defined(Q_OS_LINUX)
    return new ScreenLockDetectorLinux(this);
#elif defined(Q_OS_WIN)
    return new ScreenLockDetectorWindows(this);  // 新增
#else
    return nullptr;
#endif
}
```

### 步骤 4: 更新 CMakeLists.txt

```cmake
if(WIN32)
    list(APPEND SOURCES src/screenlockdetector_windows.cpp)
    list(APPEND HEADERS src/screenlockdetector_windows.h)
endif()
```

## 调试技巧

### 查看使用的平台实现

```cpp
ScreenLockDetector *detector = new ScreenLockDetector(this);
if (detector->initialize()) {
    // 在调试器中检查 detector->m_detector 的实际类型
    qDebug() << "Detector initialized successfully";
}
```

### 测试不同平台

在开发时，可以临时修改工厂方法来测试特定平台：

```cpp
ScreenLockDetectorBase* ScreenLockDetector::createPlatformDetector() {
    // 强制使用特定平台（仅用于测试）
    // return new ScreenLockDetectorLinux(this);
    
    // 正常的平台检测
#ifdef Q_OS_MAC
    return new ScreenLockDetectorMacOS(this);
    // ...
}
```

## 常见问题

### Q: 为什么要重构？

A: 新架构提供：
- 更清晰的代码组织
- 更容易添加新平台
- 更好的可测试性
- 减少预处理器指令

### Q: 性能有影响吗？

A: 没有。运行时性能完全相同，只是多了一层间接调用（虚函数），但这对于事件驱动的应用影响可以忽略不计。

### Q: 旧的头文件还能用吗？

A: `screenlockdetector_mac.h/mm` 文件仍然存在但已弃用。建议在方便时更新引用。

### Q: 如何回退到旧版本？

A: 使用 git：
```bash
git checkout <old-commit-hash> src/screenlockdetector*
```

## 支持

如果遇到迁移问题，请：
1. 查看 `docs/REFACTORING.md` 了解架构详情
2. 检查示例代码在 `src/main.cpp` 和 `src/mainwindow.cpp`
3. 提交 Issue 或联系开发团队

## 总结

对于大多数用户：**无需任何修改**，直接重新编译即可。

对于高级用户：新架构提供了更好的扩展性和可维护性，值得花时间理解新的设计。

祝您使用愉快！