Hua.Todo/docs/project/v1.2.0-tasks/01-Linux-Avalonia入口与WebView.md

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 生效）
• 开发态可调试（至少能看到控制台/网络错误，或能通过日志定位）