# 01 - Linux：Avalonia 入口 + WebView 承载 Vue

## 目标

- 新增一个 **Linux 桌面端入口**（Avalonia）作为 Hua.Todo 的 Linux 宿主
- 在 Linux 宿主中用 **WebView** 加载同一套 Vue 前端（与 MAUI 端共用前端构建产物与资源路径约定）
- 复用既有“前端 ↔ 本地 API”的交互方式（HTTP API + 现有注入变量/事件名），保证前端无需为 Linux 分叉

## 范围

- 新增/调整项目结构以容纳 Avalonia 入口（建议新项目：`src/Hua.Todo.Avalonia` 或 `src/Hua.Todo.Desktop.Avalonia`）
- 在 Avalonia 中接入可在 Linux 运行的 WebView 控件（需要先调研与选型）
- 确保能正确加载：
  - 内嵌 WebServer 的 `BaseUrl`
  - 以及前端静态资源（开发态/生产态策略需明确）

## 依赖

- 依赖 `04-*`/`05-*` 的云同步工作不强依赖本任务，可并行
- 依赖前端已有构建产物或构建流程（至少能得到 `dist/` 或等效 `wwwroot/`）

## 关键决策点（必须在实现前落定）

### 1) Avalonia/Linux 可用的 WebView 方案选型

候选方向（示例，最终以调研结果为准）：
- WebKitGTK 系（Linux 依赖较重，但适配面广）
- Chromium 系（体积/依赖/许可成本需评估）

选型必须满足的最低能力：
- 基础导航与本地资源加载
- JS 执行/注入（用于对齐 `window.__API_BASE_URL__` 等契约）
- JS ↔ Native 双向通信（至少开发阶段可观测；可先只保证“HTTP API”路径通）
- 开发期可用 DevTools（至少能定位网络请求与控制台错误）

### 2) 资源加载策略（与 MAUI 对齐）

需要明确并实现两种模式：
- 开发态：Avalonia WebView 指向前端 dev server（例如 `http://localhost:5173`）或指向本地 WebServer
- 生产态：加载随应用交付的静态资源（`wwwroot`）并确保 SPA fallback 生效（访问非 `/assets/*` 的路由能回到 `index.html`）

## 实现落地（已完成）

### 1) 项目结构

- 新增 Linux 桌面端入口项目：`src/Hua.Todo.Avalonia`
- 入口类型：Avalonia Desktop App（ClassicDesktopLifetime）

### 2) WebView 方案选型（已落定）

- 采用：`WebView.Avalonia` + `WebView.Avalonia.Desktop`
  - Windows：依赖 WebView2 Runtime
  - Linux：依赖 GTK + WebKitGTK（运行环境缺失时 WebView 会初始化失败）

### 3) 资源加载策略（与 MAUI 对齐）

- 生产态（默认）：内嵌 WebServer 托管 `wwwroot` 静态资源，WebView 指向 `HostUrl`
- 开发态：将 `IsUsingStatic=false`，WebView 指向 `ForEndUrl`（例如 Vite dev server）

### 4) 前端契约对齐（与 MAUI 一致）

- 在 WebView 导航完成后注入：
  - `window.__API_BASE_URL__ = "${HostUrl}/api"`
  - `window.mauiInterop`（事件名/字段名与现有前端保持一致）

### 5) 本地 API 与数据库初始化

- 内嵌 WebServer 使用 Kestrel 启动并注册动态 API 与 Controllers
- 启动时执行数据库迁移（Migrate），并设置 SQLite WAL 模式以降低锁冲突风险
- 默认 SQLite 路径使用用户目录（`LocalApplicationData/Hua.Todo/Hua.Todo.db`），避免安装目录无写权限导致启动失败

## 实施步骤（建议）

1. 新建 Avalonia 宿主项目
   - 提供 App/Window/MainView 基础结构
2. 接入 WebView 控件并完成最小加载闭环
   - 能显示 `index.html`，能打开前端路由
3. 对齐与 MAUI 端一致的“前端契约”
   - 注入 `window.__API_BASE_URL__`（值应为 `${BaseUrl}/api`）
   - 若沿用 `window.mauiInterop` 事件名，需在 Linux 端同名注入（建议命名逐步抽象为更通用的 `nativeInterop`，但 v1.2.0 以兼容为优先）
4. 复用本地 API（内嵌 WebServer）
   - 评估复用 `Hua.Todo.Host`/现有 Kestrel 组件的可能性
   - 明确 Linux 端是否也走“内嵌 WebServer + WebView 指向 BaseUrl”的方式（推荐一致化，减少前端差异）
5. 输入法/字体/DPI 验证与可配置化
   - 至少验证：中文输入法、缩放、Wayland/X11 下可用性

## 验收标准

- 在 Linux（建议 Ubuntu LTS）上启动 Avalonia 入口后：
  - WebView 正常渲染前端主界面
  - 前端能通过 `window.__API_BASE_URL__` 正确请求本地 `/api/*`（至少任务列表接口可用）
  - 页面路由/刷新不会出现 404（SPA fallback 生效）
- 开发态可调试（至少能看到控制台/网络错误，或能通过日志定位）