docs: 添加开机自启动功能设计文档

docs/superpowers/specs/2026-09-01-autostart-design.md

@@ -0,0 +1,147 @@
+# 开机自启动功能设计
+
+## 概述
+
+为 YZWater3 添加跨平台（Windows/Linux/macOS）开机自启动功能。用户可在参数设置页面（ViewB）切换开关，开启后应用随系统启动自动运行。
+
+## 设计决策
+
+| 决策 | 选择 | 理由 |
+|------|------|------|
+| 启动行为 | 仍显示登录窗口 | 保持安全性，不自动登录 |
+| UI 位置 | ViewB 参数设置页面 | 与其他配置项在一起 |
+| 实现方案 | 单服务 + 平台检测 | 代码集中，改动少，符合项目风格 |
+| 平台支持 | Windows/Linux/macOS | 项目已支持三平台 |
+
+## 架构
+
+### 数据流
+
+```
+用户切换开关 → ViewBViewModel.RunAtStartup setter
+  → StartupService.SetAutoStart(value)     // 操作注册表/autostart/LaunchAgent
+  → ConfigService.GetConfig().RunAtStartup = value  // 持久化到 JSON
+  → ConfigService.SaveConfig()
+```
+
+### 涉及文件
+
+| 层级 | 文件 | 改动 |
+|------|------|------|
+| Model | `src/YZWater.Core/Models/SystemConfig.cs` | 新增 `RunAtStartup` 属性 |
+| Service | `src/YZWater.Core/Services/StartupService.cs` | 新建，跨平台开机自启动管理 |
+| ViewModel | `src/YZWater.Core/ViewModels/ViewBViewModel.cs` | 新增 `RunAtStartup` 属性 + 保存逻辑 |
+| View | `src/YZWater.Avalonia/Views/ViewB.axaml` | 新增 ToggleSwitch 控件 |
+| csproj | `src/YZWater.Core/YZWater.Core.csproj` | 添加 `Microsoft.Win32.Registry` 包引用 |
+
+## 详细设计
+
+### 1. SystemConfig 模型
+
+新增属性：
+
+```csharp
+[ObservableProperty] private bool _runAtStartup;
+```
+
+### 2. StartupService
+
+```csharp
+public static class StartupService
+{
+    private const string AppName = "YZWater";
+    
+    public static bool SetAutoStart(bool enabled)
+    public static bool IsAutoStartEnabled()
+    private static string GetExecutablePath()
+    
+    // 平台特定实现
+    private static bool SetWindowsAutoStart(bool enabled)
+    private static bool SetLinuxAutoStart(bool enabled)
+    private static bool SetMacAutoStart(bool enabled)
+    
+    private static bool IsWindowsAutoStartEnabled()
+    private static bool IsLinuxAutoStartEnabled()
+    private static bool IsMacAutoStartEnabled()
+}
+```
+
+**各平台实现：**
+
+- **Windows**：操作注册表 `HKCU\Software\Microsoft\Windows\CurrentVersion\Run`
+- **Linux**：创建/删除 `~/.config/autostart/yzwater.desktop`
+- **macOS**：创建/删除 `~/Library/LaunchAgents/com.yxwater.yzwater.plist`
+
+**错误处理：**
+- 所有操作包裹 `try-catch`，失败记录日志并返回 `false`
+- 使用 `RuntimeInformation.IsOSPlatform()` 判断平台
+- 未知平台返回 `false`
+
+### 3. ViewBViewModel
+
+新增属性：
+
+```csharp
+[ObservableProperty] private bool _runAtStartup;
+```
+
+属性变更处理：
+
+```csharp
+partial void OnRunAtStartupChanged(bool value)
+{
+    var success = StartupService.SetAutoStart(value);
+    if (!success)
+    {
+        _runAtStartup = !value;  // 回滚
+        OnPropertyChanged(nameof(RunAtStartup));
+    }
+    else
+    {
+        var config = ConfigService.GetConfig();
+        if (config != null)
+        {
+            config.RunAtStartup = value;
+            ConfigService.SaveConfig();
+        }
+    }
+}
+```
+
+加载配置：
+
+```csharp
+private void LoadConfig()
+{
+    var config = ConfigService.GetConfig();
+    if (config != null)
+    {
+        // ... 现有代码
+        RunAtStartup = config.RunAtStartup;
+    }
+}
+```
+
+### 4. ViewB View
+
+添加 ToggleSwitch：
+
+```xml
+<StackPanel Orientation="Horizontal" Spacing="10" Margin="0,10">
+    <TextBlock Text="开机自启动：" VerticalAlignment="Center"/>
+    <ToggleSwitch IsChecked="{Binding RunAtStartup}"/>
+</StackPanel>
+```
+
+## 依赖
+
+- `Microsoft.Win32.Registry` NuGet 包（仅 Windows 平台需要，通过条件引用）
+
+## 测试要点
+
+1. Windows：启用后检查注册表 `HKCU\...\Run` 中是否有 YZWater 键
+2. Linux：启用后检查 `~/.config/autostart/yzwater.desktop` 文件是否存在且内容正确
+3. macOS：启用后检查 `~/Library/LaunchAgents/com.yxwater.yzwater.plist` 文件
+4. 跨平台：在非 Windows 平台上禁用时不应抛出异常
+5. 配置持久化：重启应用后开关状态是否正确恢复
+6. 错误处理：当注册表/文件操作失败时，UI 是否正确回滚