LanMountainDesktop/docs/04-架构与实现/01-整体架构.md

# 整体架构

本文档描述阑山桌面的整体技术架构、各模块职责和交互方式。

## 架构概览

### 核心模块

```
┌─────────────────────────────────────────────────────────────┐
│                     用户交互层                                │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │桌面组件   │  │主窗口     │  │托盘图标   │  │设置窗口   │   │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│              LanMountainDesktop（桌面宿主）                   │
│  ┌──────────────────────────────────────────────────────┐  │
│  │                   组件系统                             │  │
│  │   组件注册 | 组件渲染 | 布局管理 | 编辑模式            │  │
│  └──────────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────────┐  │
│  │                   插件运行时                           │  │
│  │   插件加载 | 生命周期 | SDK 接入 | 契约装配            │  │
│  └──────────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────────┐  │
│  │                   核心服务层                           │  │
│  │   设置 | 主题 | 本地化 | 日志 | 遥测 | IPC             │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
              ↓                           ↓
┌──────────────────────┐    ┌──────────────────────────────┐
│ LanMountainDesktop   │    │ LanMountainDesktop          │
│   .AirAppRuntime     │←IPC→│   .AirAppHost (多实例)       │
│  Air APP 运行时容器   │    │  Air APP 渲染进程            │
└──────────────────────┘    └──────────────────────────────┘
              ↑
┌──────────────────────┐
│ LanMountainDesktop   │
│   .Launcher          │
│  启动器 (唯一入口)     │
└──────────────────────┘
```

## 项目结构

### 核心项目

| 项目 | 职责 | 类型 |
|------|------|------|
| **LanMountainDesktop** | 桌面宿主主程序 | WPF 应用 |
| **LanMountainDesktop.Launcher** | 启动器（OOBE、Splash、版本管理） | 独立可执行 |
| **LanMountainDesktop.AirAppRuntime** | Air APP 运行时容器 | 独立服务 |
| **LanMountainDesktop.AirAppHost** | Air APP 渲染进程 | 框架依赖应用 |

### SDK 和基础设施

| 项目 | 职责 | 类型 |
|------|------|------|
| **LanMountainDesktop.PluginSdk** | 插件 SDK | NuGet 包 |
| **LanMountainDesktop.AirAppSdk** | Air APP SDK | NuGet 包 |
| **LanMountainDesktop.Shared.Contracts** | 共享契约类型 | 类库 |
| **LanMountainDesktop.Shared.IPC** | IPC 基础设施 | 类库 |

### 功能模块

| 项目 | 职责 | 类型 |
|------|------|------|
| **LanMountainDesktop.Settings.Core** | 设置系统 | 类库 |
| **LanMountainDesktop.Appearance** | 主题和外观 | 类库 |
| **LanMountainDesktop.DesktopComponents.Runtime** | 组件运行时 | 类库 |
| **LanMountainDesktop.DesktopHost** | 桌面宿主生命周期 | 类库 |

### 未来扩展（计划中）

| 项目 | 职责 | 状态 |
|------|------|------|
| **LanMountainDesktop.PluginIsolation.Contracts** | 插件隔离契约 | 已创建 |
| **LanMountainDesktop.PluginIsolation.Ipc** | 插件隔离 IPC | 已创建 |

## 启动流程

### 生产环境启动

```
1. 用户启动 Launcher.exe
         ↓
2. 首次启动？ → 是 → 显示 OOBE 欢迎页
         ↓ 否
3. 显示 Splash 启动动画
         ↓
4. 扫描 app-* 目录，选择最佳版本
   - 优先选择有 .current 标记的
   - 其次选择版本号最高的
   - 跳过有 .partial 或 .destroy 标记的
         ↓
5. 预启动 AirAppRuntime.exe
   - JIT 框架依赖进程
   - 等待 IPC 管道就绪
         ↓
6. 启动 app-{version}/LanMountainDesktop.exe
         ↓
7. Host 初始化
   - 日志系统
   - 遥测系统
   - 设置加载
   - 主题应用
         ↓
8. 初始化桌面环境
   - 创建桌面窗口
   - 加载插件
   - 注册组件
   - 显示托盘图标
         ↓
9. 将 Host PID 附加给 AirAppRuntime
         ↓
10. 清理标记为 .destroy 的旧版本
         ↓
11. 桌面就绪
```

### 开发环境启动

```
开发者直接启动 LanMountainDesktop.exe
         ↓
检测到没有通过 Launcher 启动
         ↓
跳过 OOBE 和版本管理
         ↓
如果 AirAppRuntime 未运行，自动启动
         ↓
正常初始化桌面环境
```

## 核心系统

### 1. 组件系统

**职责**: 管理桌面组件的注册、创建、渲染和布局

**架构**:

```
ComponentRegistry (组件注册表)
    ↓ 注册
ComponentDefinition (组件定义)
    ↓ 创建实例
ComponentInstance (组件实例)
    ↓ 渲染
ComponentView (Avalonia UI)
    ↓ 显示
DesktopWidgetWindow (桌面窗口)
```

**关键类**:
- `ComponentRegistry` - 组件注册和查找
- `ComponentBase` - 组件基类
- `ComponentInstanceManager` - 组件实例管理
- `DesktopLayoutService` - 布局管理

### 2. 插件系统

**职责**: 加载、初始化和管理插件生命周期

**运行时模式**:

| 模式 | 状态 | 说明 |
|------|------|------|
| **in-proc** | ✅ 当前默认 | 插件运行在宿主进程内 |
| **isolated-background** | 🚧 规划中 | 后台逻辑隔离进程 |
| **isolated-window** | 🚧 规划中 | UI 渲染隔离进程 |

**加载流程**:

```
1. 扫描插件目录
   %LOCALAPPDATA%\LanMountainDesktop\plugins\
         ↓
2. 读取 plugin.json 清单
         ↓
3. 验证依赖关系
         ↓
4. 创建 PluginLoadContext
         ↓
5. 加载插件程序集
         ↓
6. 创建 IPlugin 实例
         ↓
7. 调用 InitializeAsync()
         ↓
8. 注册组件和服务
```

### 3. 设置系统

**职责**: 管理应用和插件的配置数据

**设置域**:

```
Settings Root
├── General (通用设置)
├── Appearance (外观设置)
├── Components (组件设置)
├── Plugins (插件设置)
│   ├── Plugin A
│   └── Plugin B
└── Advanced (高级设置)
```

**持久化**:
- 位置: `%LOCALAPPDATA%\LanMountainDesktop\settings\`
- 格式: JSON
- 实时保存，延迟写入

### 4. 主题系统

**职责**: 管理亮色/暗色主题、圆角系统

**圆角规范**:

| 级别 | Token | 值 | 用途 |
|------|-------|----|------|
| 基础 | `DesignCornerRadiusBasic` | 4 | 按钮、输入框 |
| 组件 | `DesignCornerRadiusComponent` | 8 | 卡片、面板 |
| 窗口 | `DesignCornerRadiusWindow` | 12 | 窗口、对话框 |

**主题切换**:
1. 用户选择主题
2. `AppearanceService` 切换资源字典
3. 广播主题变更事件
4. 各组件响应并更新 UI
5. 通过 IPC 通知 Air APP

### 5. IPC 系统

**职责**: 进程间通信

**通信拓扑**:

```
┌────────────────┐
│     Host       │ ← 外部 IPC 入口点
│  (主程序)       │
└────────┬───────┘
         │ IPC
    ┌────┴────┐
    ↓         ↓
┌────────┐ ┌────────────┐
│Launcher│ │AirAppRuntime│
└────────┘ └──────┬──────┘
                  │ IPC
            ┌─────┴─────┐
            ↓           ↓
      ┌─────────┐ ┌─────────┐
      │AirAppHost│ │AirAppHost│
      └─────────┘ └─────────┘
```

**IPC 管道**:
- `LanMountainDesktop.Host.v1` - 宿主公共服务
- `LanMountainDesktop.AirAppRuntime.v1` - Air APP 生命周期
- `LanMountainDesktop.AirAppRuntimeControl.v1` - Runtime 控制

## 数据流

### 设置变更流程

```
用户修改设置
    ↓
SettingsService.SetValue()
    ↓
触发 SettingChanged 事件
    ↓
相关组件监听并响应
    ↓
延迟写入磁盘（防抖 500ms）
```

### 组件更新流程

```
定时器触发 (默认 1 秒)
    ↓
ComponentUpdateService.UpdateAsync()
    ↓
遍历所有组件实例
    ↓
调用 Component.UpdateAsync()
    ↓
组件更新数据
    ↓
UI 自动刷新（数据绑定）
```

### 插件通信流程

```
Plugin A 发送消息
    ↓
PluginMessenger.Send()
    ↓
消息总线分发
    ↓
Plugin B 接收消息
    ↓
处理并可选回复
```

## 安全性

### 权限系统

插件需要声明所需权限：

```json
{
  "Permissions": [
    "FileSystem.Read",      // 读取文件
    "FileSystem.Write",     // 写入文件
    "Network.Access",       // 网络访问
    "System.Info"           // 系统信息
  ]
}
```

### 沙箱隔离（未来）

进程隔离模式下：
- 插件运行在独立进程
- 通过 IPC 访问宿主服务
- 限制文件系统访问
- 限制网络访问

## 性能优化

### 启动优化
- ✅ 延迟加载插件
- ✅ 异步初始化
- ✅ 组件按需创建
- ✅ 资源延迟加载

### 运行时优化
- ✅ 虚拟化列表
- ✅ 图片缓存
- ✅ 布局缓存
- ✅ 事件防抖/节流

### 内存优化
- ✅ 弱事件模式
- ✅ 及时释放资源
- ✅ 图片降采样
- ✅ 组件卸载清理

## 相关文档

- [启动器系统](02-启动器系统.md) - 启动器详细设计
- [插件运行时](04-插件运行时.md) - 插件加载和管理
- [组件系统](05-组件系统.md) - 组件架构和渲染
- [IPC 通信](07-IPC通信.md) - 进程间通信设计