LanMountainDesktop/.trae/documents/update-settings-redesign.md

更新设置界面重设计实施计划

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 将更新设置页面从丑陋的卡片堆叠布局重设计为遵循 Fluent Design 的 FASettingsExpander 列表布局，与项目其他设置页面保持视觉一致性。

Architecture: 移除所有 Border.settings-section-card 包裹，改用 FASettingsExpander + IconText 分节标题 + Separator 分隔线的统一模式。操作按钮改为仅显示当前可用操作。版本信息改为 FASettingsExpanderItem 行项目展示。ViewModel 层新增 ActiveActions 计算属性来驱动按钮可见性。

Tech Stack: Avalonia UI 11, FluentAvalonia 2.x, CommunityToolkit.Mvvm

---

当前状态分析

现有文件

文件	职责
LanMountainDesktop/Views/SettingsPages/UpdateSettingsPage.axaml	更新页面 AXAML 布局
LanMountainDesktop/Views/SettingsPages/UpdateSettingsPage.axaml.cs	代码隐藏
LanMountainDesktop/ViewModels/UpdateSettingsViewModel.cs	视图模型
LanMountainDesktop/Styles/SettingsCardStyles.axaml	通用设置样式
LanMountainDesktop/Controls/IconText.axaml(.cs)	分节标题控件
LanMountainDesktop.Shared.Contracts/Update/UpdateState.cs	UpdatePhase 枚举和扩展方法

核心问题

1. 4 个 Border.settings-section-card 卡片：状态卡、版本信息卡、进度卡、操作卡，每个都带边框+阴影+圆角，视觉零碎
2. FAInfoBar 嵌套在卡片内：冗余的容器层级
3. 7 个按钮 3×3 网格：大量按钮在当前阶段不可用但仍然占据空间
4. 与其他设置页面风格不一致：GeneralSettingsPage、AppearanceSettingsPage 等全部使用 FASettingsExpander 列表

参考基准

• GeneralSettingsPage.axaml：IconText 分节标题 → FASettingsExpander 列表 → Separator 分隔
• AppearanceSettingsPage.axaml：同上模式
• AboutSettingsPage.axaml：FAInfoBar 用于静态信息展示
• Windows 11 设置 > Windows Update：顶部状态区 + 进度条 + 操作按钮，下方展开区展示详情

---

设计决策

决策项	选择	理由
布局模式	FASettingsExpander 列表	与其他设置页面统一，Fluent Design 原生控件
按钮策略	仅显示可用操作	简洁、不混乱，Windows 11 更新页面也是此模式
版本信息	FASettingsExpanderItem 行项目	每行一个信息，干净可扫描
进度展示	内嵌在状态 Expander 内	进度是状态的一部分，不应独立成卡
偏好设置	保留 FASettingsExpander	已经是正确模式，微调即可

---

新布局结构

ScrollViewer
└── StackPanel (settings-page-container settings-page-animated)
    ├── TextBlock (settings-section-title: "更新")
    ├── TextBlock (settings-section-description: 描述文字)
    │
    ├── IconText (Icon="ArrowSync", Text="更新状态")
    │
    ├── FASettingsExpander "检查更新" (IsClickEnabled=True, Command=CheckCommand)
    │   ├── IconSource: ArrowSync 图标
    │   └── Footer: Button "检查更新" (仅 CanCheck 时可见)
    │
    ├── FASettingsExpander "更新进度" (IsVisible=IsBusy||IsProgressVisible||IsPaused)
    │   ├── IconSource: FAProgressRing / 对应阶段图标
    │   ├── Footer: PhaseText + ProgressFraction
    │   └── FASettingsExpanderItem
    │       ├── ProgressBar (ProgressFraction)
    │       ├── ProgressDetail 文字
    │       └── 操作按钮行 (仅可用操作)
    │           ├── Button "下载" (CanDownload)
    │           ├── Button "安装" (CanInstall)
    │           ├── Button "暂停" (CanPause)
    │           ├── Button "继续" (CanResume)
    │           ├── Button "回滚" (CanRollback)
    │           └── Button "取消" (CanCancel)
    │
    ├── FASettingsExpander "暂停" (IsVisible=IsPaused)
    │   └── FAInfoBar (PausedBadgeText + PausedHintText)
    │
    ├── Separator (settings-separator)
    │
    ├── IconText (Icon="Info", Text="版本信息")
    │
    ├── FASettingsExpander "当前版本" (IsClickEnabled=False)
    │   ├── IconSource: 版本图标
    │   └── Footer: CurrentVersionText
    │
    ├── FASettingsExpander "最新版本" (IsClickEnabled=False)
    │   ├── IconSource: 下载图标
    │   └── Footer: LatestVersionText (或 "已是最新")
    │
    ├── FASettingsExpander "发布时间" (IsClickEnabled=False)
    │   ├── IconSource: 日历图标
    │   └── Footer: PublishedAtText
    │
    ├── FASettingsExpander "上次检查" (IsClickEnabled=False)
    │   ├── IconSource: 时钟图标
    │   └── Footer: LastCheckedText
    │
    ├── FASettingsExpander "更新类型" (IsClickEnabled=False)
    │   ├── IconSource: 标签图标
    │   └── Footer: UpdateTypeText
    │
    ├── Separator (settings-separator)
    │
    ├── IconText (Icon="Settings", Text="更新偏好")
    │
    └── FASettingsExpander "更新偏好" (IsExpanded=True)
        ├── IconSource: 设置齿轮图标
        ├── FASettingsExpanderItem "更新频道"
        │   └── Footer: ComboBox (stable/preview)
        ├── FASettingsExpanderItem "下载源"
        │   └── Footer: ComboBox (plonds/github/proxy)
        ├── FASettingsExpanderItem "更新模式"
        │   └── Footer: ComboBox (manual/confirm/silent)
        └── FASettingsExpanderItem "下载线程数"
            └── Footer: Slider + TextBlock

---

Proposed Changes

Task 1: 重写 UpdateSettingsPage.axaml 布局

Files:

• Modify: LanMountainDesktop/Views/SettingsPages/UpdateSettingsPage.axaml

What: 完全重写 AXAML，将 4 个 Border.settings-section-card 替换为 FASettingsExpander 列表布局。

Key changes:

1. 移除所有 Border.settings-section-card 包裹
2. 使用 controls:IconText 做分节标题（与 GeneralSettingsPage 一致）
3. 状态区域：FASettingsExpander + IsClickEnabled=True + Command=CheckCommand，Footer 放检查按钮
4. 进度区域：FASettingsExpander 内嵌 ProgressBar + 操作按钮，仅 IsBusy||IsProgressVisible||IsPaused 时可见
5. 版本信息：每个字段一个 FASettingsExpander，Footer 直接显示值（参考 Windows 11 更新页面的行项目模式）
6. 偏好设置：保留 FASettingsExpander + FASettingsExpanderItem 模式，但将 TextBox 改为 ComboBox（更符合 Fluent 规范）
7. 使用 Separator classes="settings-separator" 分隔三大区域

Why: 与项目其他设置页面统一风格，遵循 Fluent Design，消除卡片堆叠的视觉噪音。

How:

• 参照 GeneralSettingsPage.axaml 的布局模式
• 参照 AppearanceSettingsPage.axaml 的 FASettingsExpander 使用方式
• 参照 AboutSettingsPage.axaml 的 FAInfoBar 使用方式

Task 2: 更新 ViewModel — 添加 ComboBox 数据源和按钮可见性属性

Files:

• Modify: LanMountainDesktop/ViewModels/UpdateSettingsViewModel.cs

What:

1. 将更新频道、下载源、更新模式从 TextBox 绑定改为 ComboBox 绑定，添加 ObservableCollection<SelectionOption> 类型的数据源属性
2. 添加 IsProgressSectionVisible 计算属性（IsBusy || IsProgressVisible || IsPaused）
3. 添加 IsUpdateAvailableSectionVisible 计算属性（IsUpdateAvailable）
4. 添加 IsStatusInfoVisible 计算属性（有 StatusMessage 且非空闲时）
5. 移除不再需要的独立按钮文本属性（CheckButtonText 保留，其他按钮文本属性保留但仅在可见时使用）

Why: ComboBox 比 TextBox 更适合有限选项的输入，且与 GeneralSettingsPage 的模式一致。按钮可见性属性让 AXAML 可以用 IsVisible 绑定控制按钮显示。

How:

• 参考 GeneralSettingsPageViewModel 中 SelectionOption 的使用方式
• 在 OnCurrentPhaseChanged 中触发新属性的 OnPropertyChanged

Task 3: 将偏好设置 TextBox 替换为 ComboBox

Files:

• Modify: LanMountainDesktop/Views/SettingsPages/UpdateSettingsPage.axaml (在 Task 1 中一并完成)
• Modify: LanMountainDesktop/ViewModels/UpdateSettingsViewModel.cs (在 Task 2 中一并完成)

What: 将更新频道、下载源、更新模式三个 TextBox 替换为 ComboBox，使用 SelectionOption 数据模板。

Why: 有限选项应使用 ComboBox 而非自由文本输入，这是 Fluent Design 的基本规范，也与 GeneralSettingsPage 中的语言/时区选择一致。

Task 4: 构建验证

Files:

• 无新文件

What: 运行 dotnet build 确保编译通过，检查 AXAML 绑定是否正确。

---

Assumptions & Decisions

1. 不修改 UpdateOrchestrator 和 UpdateState — 只改 UI 层和 ViewModel 的展示逻辑，不改底层更新引擎
2. 不修改 SettingsCardStyles.axaml — 通用样式保持不变，移除的是 UpdateSettingsPage 对它的使用
3. 保留所有 ViewModel 属性 — 即使某些属性在新布局中不再直接使用（如独立的 ActionsTitle），也保留以避免破坏本地化系统
4. ComboBox 选项硬编码在 ViewModel — 参考 GeneralSettingsPageViewModel 的 SelectionOption 模式
5. 进度区域在空闲时隐藏 — 不显示空的进度条，只在有活动时展示
6. FAInfoBar 仅用于暂停/错误提示 — 不再嵌套在卡片内，直接放在 FASettingsExpanderItem 内

---

Verification Steps

1. dotnet build LanMountainDesktop.slnx -c Debug 编译通过
2. 运行应用，导航到设置 > 更新页面，验证：
   • 页面布局与 GeneralSettingsPage 风格一致
   • 无圆角矩形卡片包裹
   • 检查更新按钮可用
   • 进度区域在空闲时隐藏
   • 版本信息以行项目形式展示
   • 偏好设置使用 ComboBox
   • 操作按钮仅显示当前可用的
3. 点击「检查更新」，验证状态变化和进度展示
4. 验证偏好设置的 ComboBox 选择能正确保存和加载