ShaoHua
d81aa06681
1. 更新 .env 配置文件，替换原有云同步变量为 API 目标配置 2. 调整 publish-linux.ps1 中的文档路径，使用研发工单目录 3. 重构项目文档目录：将原 v1.2.0-tasks 迁移为研发工单-v1.2.0 目录，统一术语为"研发工单"替代"任务" 4. 更新 README.md 与各 PRD 文档的术语对照表，明确业务实体与研发工作项的区分 5. 新增多个研发工单文档，覆盖搜索、云同步、Linux 打包等模块 6. 删除旧的任务拆分文档，统一使用新的研发工单体系
94 lines
4.3 KiB
Markdown
94 lines
4.3 KiB
Markdown
# 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/*`（至少 Todo 待办项列表接口可用）
|
||
- 页面路由/刷新不会出现 404（SPA fallback 生效）
|
||
- 开发态可调试（至少能看到控制台/网络错误，或能通过日志定位）
|