Files

T

ShaoHua d53828c150 feat: v1.2.0 开发进度更新

### 新增功能
- **Linux 官方支持**：新增 Hua.Todo.Avalonia 项目，正式适配 Linux 平台，同时支持 Windows 和 macOS
- **Avalonia 桌面交互**：增加托盘菜单（显示/退出）、关闭隐藏到托盘、Windows 全局热键唤起主窗口、热键配置本地持久化
- **SQLite DateTime 兼容修复**：新增 LenientUtcDateTimeStringConverter，解决历史遗留的 DateTime 脏数据解析问题
- **用户文档完善**：新增 docs/manual/新手指南.md 和 docs/manual/用户指南.md
- **部署文档**：新增 docs/manual/部署文档.md，详细说明多平台发布流程

### 优化与修复
- **发布脚本整理**：拆分/对齐各平台发布入口，新增 publish.ps1 作为统一入口
- **Windows WebView2 优化**：数据目录调整到 %LocalAppData%\Hua.Todo\WebView2，修复 Runtime 误判问题
- **MAUI 多平台构建**：在 Windows 开发机上默认仅构建 Android + Windows 目标
- **SPA 路由回落**：修复 Release 模式下 /swagger 路径的 404 问题
- **Swagger 输出**：补齐 Dynamic API 端点，避免接口缺失

### 文档更新
- **版本记录**：更新 v1.2.0 开发进度和功能列表
- **技术设计文档**：添加 Avalonia 项目架构和模块设计
- **项目结构**：更新 README.md 中的项目结构说明

### 其他变更
- 新增 Directory.Build.props 和更新 Directory.Build.targets
- 调整 src/Hua.Todo.Avalonia 项目配置和资源文件
- 更新 src/Hua.Todo.Web 前端资源文件
- 修复 src/Hua.Todo.Maui 相关配置和打包脚本

2026-04-09 21:39:07 +08:00

16 KiB

Raw Permalink Blame History

Hua.Todo 技术设计文档 v1.1.0

1. 项目概述

本文档描述 Hua.Todo v1.1.0 的技术设计方案，包括项目文件目录结构、模块划分、技术选型和实现细节。

2. 技术栈

2.1 后端技术栈

开发语言: C# 10
框架: .NET 10
UI 框架: MAUI (Multi-platform App UI) + Avalonia (Linux 支持)
Web 服务器: Kestrel (ASP.NET Core 内置)
API 框架: ASP.NET Core Web API
数据访问: Entity Framework Core
数据库: SQLite (本地存储)
日志: Serilog
依赖注入: Microsoft.Extensions.DependencyInjection

2.2 前端技术栈

开发语言: JavaScript/TypeScript
框架: Vue.js 3
构建工具: Vite
HTTP 客户端: Axios
状态管理: Pinia
UI 组件库: Element Plus / Vant (移动端)
CSS 预处理器: SCSS

3. 项目目录结构

Hua.Todo/
├── docs/                              # 文档目录
│   ├── manual/                        # 用户/开发者手册
│   │   ├── 技术栈与模块.md
│   │   ├── 版本记录.md
│   │   ├── 技术设计文档.md（本文件）
│   │   ├── 代码规范文档.md
│   │   └── 部署文档.md
│   └── project/                       # 项目进度/需求文档
│       ├── 产品需求文档.md
│       └── ...
│
├── src/                               # 源代码目录
│   ├── Hua.Todo.Maui/                 # MAUI 主项目（跨平台入口）
│   │   ├── Platforms/                 # 平台特定代码
│   │   │   ├── Windows/               # Windows 平台代码
│   │   │   │   ├── App.xaml           # Windows 应用入口
│   │   │   │   └── Services/          # Windows 平台服务
│   │   │   │       └── HotKeyService.cs
│   │   │   ├── MacCatalyst/           # macOS 平台代码
│   │   │   │   ├── App.xaml
│   │   │   │   └── Services/
│   │   │   │       └── HotKeyService.cs
│   │   │   ├── Android/               # Android 平台代码
│   │   │   │   ├── MainActivity.cs
│   │   │   │   └── Services/
│   │   │   │       └── NotificationService.cs
│   │   │   └── iOS/                   # iOS 平台代码
│   │   │       ├── AppDelegate.cs
│   │   │       └── Services/
│   │   │           └── NotificationService.cs
│   │   ├── Resources/                 # 资源文件
│   │   │   ├── Images/                # 图片资源
│   │   │   ├── Styles/                # 样式资源
│   │   │   └── Fonts/                 # 字体资源
│   │   ├── Controls/                  # 自定义控件
│   │   │   └── WebViewContainer.xaml
│   │   ├── Services/                  # 服务层
│   │   │   ├── IHotKeyService.cs
│   │   │   ├── IPlatformService.cs
│   │   │   └── AppLifecycleService.cs
│   │   ├── App.xaml                   # MAUI 应用入口
│   │   ├── App.xaml.cs
│   │   ├── MauiProgram.cs             # MAUI 程序配置
│   │   └── Hua.Todo.Maui.csproj       # MAUI 项目文件
│   │
│   ├── Hua.Todo.Avalonia/             # Avalonia 项目（Linux 支持）
│   │   ├── Assets/                    # 资源文件
│   │   │   └── icon.ico               # 应用图标
│   │   ├── Services/                  # 服务层
│   │   │   ├── EmbeddedWebServerServiceFactory.cs
│   │   │   ├── GlobalHotKeyServiceFactory.cs
│   │   │   ├── NoopEmbeddedWebServerService.cs
│   │   │   └── Platforms/             # 平台特定服务
│   │   │       ├── AndroidGlobalHotKeyService.cs
│   │   │       └── LinuxGlobalHotKeyService.cs
│   │   ├── Views/                     # 视图
│   │   │   ├── MainView.axaml
│   │   │   ├── MainView.axaml.cs
│   │   │   ├── MainWindow.axaml
│   │   │   └── MainWindow.axaml.cs
│   │   ├── App.axaml                  # Avalonia 应用入口
│   │   ├── App.axaml.cs
│   │   ├── Program.cs                 # Avalonia 程序配置
│   │   ├── appsettings.json           # 配置文件
│   │   ├── setup.iss                  # 安装脚本
│   │   ├── wwwroot/                   # 前端静态资源
│   │   └── Hua.Todo.Avalonia.csproj   # Avalonia 项目文件
│   │
│   ├── Hua.Todo.Host/                 # 后端 API 项目
│   │   ├── Controllers/               # API 控制器
│   │   │   ├── TasksController.cs
│   │   │   ├── SettingsController.cs
│   │   │   └── SyncController.cs
│   │   ├── Models/                    # 数据模型
│   │   │   ├── Task.cs
│   │   │   ├── TaskDto.cs
│   │   │   └── ApiResponse.cs
│   │   ├── Services/                  # 业务服务
│   │   │   ├── ITaskService.cs
│   │   │   ├── TaskService.cs
│   │   │   ├── ISyncService.cs
│   │   │   └── SyncService.cs
│   │   ├── Data/                      # 数据访问层
│   │   │   ├── TodoDbContext.cs
│   │   │   ├── Converters/            # 类型转换器
│   │   │   │   └── LenientUtcDateTimeStringConverter.cs
│   │   │   ├── Repositories/
│   │   │   │   ├── ITaskRepository.cs
│   │   │   │   └── TaskRepository.cs
│   │   │   └── Migrations/            # 数据库迁移
│   │   ├── Middleware/                # 中间件
│   │   │   └── ExceptionMiddleware.cs
│   │   ├── Extensions/                # 扩展方法
│   │   │   └── ServiceCollectionExtensions.cs
│   │   ├── Program.cs                 # API 入口
│   │   ├── appsettings.json           # 配置文件
│   │   └── Hua.Todo.Host.csproj       # Host 项目文件
│   │
│   ├── Hua.Todo.Application/          # 应用层
│   │   ├── Data/                      # 数据访问
│   │   │   ├── TodoDbContext.cs
│   │   │   └── Converters/            # 类型转换器
│   │   │       └── LenientUtcDateTimeStringConverter.cs
│   │   └── Hua.Todo.Application.csproj # Application 项目文件
│   │
│   ├── Hua.Todo.Core/                 # 核心业务逻辑层
│   │   ├── Entities/                  # 实体类
│   │   │   ├── Task.cs
│   │   │   └── TaskPriority.cs
│   │   ├── Interfaces/                # 接口定义
│   │   │   ├── ITaskRepository.cs
│   │   │   └── IUnitOfWork.cs
│   │   ├── ValueObjects/              # 值对象
│   │   │   └── TaskTitle.cs
│   │   ├── Specifications/            # 规范模式
│   │   │   └── TaskSpecifications.cs
│   │   └── Hua.Todo.Core.csproj       # Core 项目文件
│   │
│   ├── Hua.Todo.Web/                  # 前端 Web 项目 (Vue.js)
│   │   ├── public/                    # 静态资源
│   │   │   └── favicon.svg            # 网站图标
│   │   ├── src/                       # 源代码
│   │   │   ├── api/                   # API 调用
│   │   │   │   ├── client.ts         # HTTP 客户端配置
│   │   │   │   ├── tasks.ts          # 任务相关 API
│   │   │   │   └── settings.ts       # 设置相关 API
│   │   │   ├── assets/                # 资源文件
│   │   │   │   ├── images/
│   │   │   │   └── styles/
│   │   │   ├── components/            # Vue 组件
│   │   │   │   ├── TaskList.vue
│   │   │   │   ├── TaskItem.vue
│   │   │   │   ├── QuickEntry.vue
│   │   │   │   └── Settings.vue
│   │   │   ├── composables/           # 组合式函数
│   │   │   │   ├── useTasks.ts
│   │   │   │   └── useHotKey.ts
│   │   │   ├── stores/                # 状态管理 (Pinia)
│   │   │   │   ├── tasks.ts
│   │   │   │   └── settings.ts
│   │   │   ├── types/                 # TypeScript 类型定义
│   │   │   │   ├── task.ts
│   │   │   │   └── api.ts
│   │   │   ├── utils/                 # 工具函数
│   │   │   │   ├── date.ts
│   │   │   │   └── storage.ts
│   │   │   ├── App.vue                # 根组件
│   │   │   └── main.ts                # 应用入口
│   │   ├── package.json               # 依赖配置
│   │   ├── vite.config.ts             # Vite 配置
│   │   ├── tsconfig.json              # TypeScript 配置
│   │   └── index.html                 # HTML 模板
│   │
│   └── Hua.Todo.Tests/                # 测试项目
│       ├── Unit/                      # 单元测试
│       │   ├── Services/
│       │   │   └── TaskServiceTests.cs
│       │   └── Controllers/
│       │       └── TasksControllerTests.cs
│       ├── Integration/               # 集成测试
│       │   └── ApiIntegrationTests.cs
│       └── Hua.Todo.Tests.csproj
│
├── .gitignore                         # Git 忽略文件
├── Hua.Todo.sln                       # 解决方案文件
└── README.md                          # 项目说明文档

4. 模块设计

4.1 MAUI 主项目 (Hua.Todo.Maui)

职责:

应用程序入口和生命周期管理
平台特定功能封装
WebView 容器管理
本地 HTTP 服务器启动

调试与接口文档：

Windows Debug 模式下，内嵌 WebServer 默认提供 Swagger UI（{HostUrl}/swagger）与 OpenAPI JSON（{HostUrl}/swagger/v1/swagger.json），用于本地接口联调。

关键组件:

MauiProgram.cs: 配置 MAUI 应用和依赖注入
App.xaml.cs: 应用程序主入口
WebViewContainer: 封装 WebView 控件
平台特定服务: 快捷键、通知等

4.2 Avalonia 项目 (Hua.Todo.Avalonia)

职责:

Linux 平台支持
桌面交互功能（托盘菜单、全局热键等）
WebView 容器管理
本地 HTTP 服务器启动

关键组件:

Program.cs: 配置 Avalonia 应用和依赖注入
App.axaml.cs: 应用程序主入口
MainWindow.axaml.cs: 主窗口管理
MainView.axaml.cs: 主视图管理
GlobalHotKeyServiceFactory: 全局热键服务工厂
EmbeddedWebServerServiceFactory: 内嵌 Web 服务器服务工厂
平台特定服务: Linux 全局热键等

4.3 后端 API 项目 (Hua.Todo.Host)

职责:

提供 RESTful API 接口
业务逻辑处理
数据访问和持久化
本地 HTTP 服务器托管

接口文档：

开发环境（ASPNETCORE_ENVIRONMENT=Development）下提供 Swagger UI：http://localhost:5173/swagger（或 https://localhost:7175/swagger）。

关键组件:

CloudSync: 云同步 Minimal APIs（/auth、/tasks、/sync、/security）
DynamicApiMiddleware: 任务管理等业务接口通过 Dynamic API（/api/{service}/...）对外暴露
Data: 数据访问层和数据库上下文
Program.cs: API 服务器配置和启动

4.4 核心业务层 (Hua.Todo.Core)

职责:

定义领域模型和业务规则
提供核心业务接口
实现领域驱动设计模式

关键组件:

Entities: 领域实体
Interfaces: 业务接口定义
ValueObjects: 值对象
Specifications: 业务规范

4.5 前端 Web 项目 (Hua.Todo.Web)

职责:

用户界面展示
用户交互处理
HTTP API 调用
状态管理

关键组件:

components: Vue 组件
api: API 调用封装
stores: 状态管理
composables: 组合式函数

5. HTTP API 设计

5.1 API 基础配置

基础 URL（开发三件套 / Host 模式）: http://localhost:5173/api（或 https://localhost:7175/api）
基础 URL（MAUI 内嵌模式）: {HostUrl}/api（HostUrl 来自 appsettings.json: WebServer.HostUrl，默认 http://localhost:5057）
数据格式: JSON
认证方式: 以实际端点为准（如云同步相关端点可能需要认证）
跨域配置: 允许本地跨域请求

5.2 API 端点设计

任务管理 API

GET    /api/task                          # 获取任务列表（默认：全部）
GET    /api/task/active                   # 获取未完成任务
GET    /api/task/completed                # 获取已完成任务
GET    /api/task/{id}                     # 获取单个任务
POST   /api/task                          # 创建任务
PUT    /api/task                          # 更新任务（通过 Body 内的 id 定位）
DELETE /api/task/{id}                     # 删除任务
PATCH  /api/task/{id}/toggle              # 切换完成状态
GET    /api/task/{parentTaskId}/subtasks  # 获取子任务列表

云同步 API（Host 模式）

POST   /auth/bootstrap        # 初始化管理员（仅首次）
POST   /auth/login            # 登录
POST   /auth/step-up          # 二次验证（提升权限）
GET    /tasks/                # 获取云端任务（只读）
POST   /sync/                 # 推送/拉取合并同步
GET    /security/policy       # 获取安全策略
PUT    /security/policy       # 更新安全策略

6. 数据库设计

6.1 数据库表结构

Tasks 表

CREATE TABLE Tasks (
    Id INTEGER PRIMARY KEY AUTOINCREMENT,
    Title TEXT NOT NULL,
    Priority INTEGER NOT NULL DEFAULT 0,
    IsCompleted INTEGER NOT NULL DEFAULT 0,
    CreatedAt TEXT NOT NULL,
    UpdatedAt TEXT NOT NULL
);

Settings 表

CREATE TABLE Settings (
    Key TEXT PRIMARY KEY,
    Value TEXT NOT NULL,
    UpdatedAt TEXT NOT NULL
);

6.2 数据访问策略

使用 Entity Framework Core 进行数据访问
采用 Repository 模式封装数据访问
支持 LINQ 查询和异步操作
数据库迁移管理

7. 通信机制

7.1 HTTP 通信流程

C# 后端启动: MAUI 应用启动时启动本地 Kestrel 服务器
Vue 前端加载: WebView 加载 Vue 应用
API 调用: Vue 通过 Axios 调用本地 HTTP API
数据处理: C# 后端处理请求并返回 JSON 数据
界面更新: Vue 接收响应并更新界面

7.2 错误处理

统一的错误响应格式
异常中间件捕获和处理
前端错误提示和重试机制

8. 部署和打包

8.1 开发环境

后端调试: 使用 Visual Studio 调试 MAUI 应用
前端调试: 使用 Vite 开发服务器
热重载: 支持前后端热重载

8.2 生产构建

前端构建: npm run build 生成静态文件
后端打包: MAUI 发布各平台应用
静态文件嵌入: 将前端静态文件嵌入到 MAUI 应用中

8.3 平台特定配置

Windows: WebView2 运行时要求
macOS: 代码签名和公证
移动端: 应用商店发布配置
Linux: .NET MAUI 无官方 Linux 目标，需要引入独立桌面宿主（例如基于 WebKitGTK 的方案）并处理运行时依赖与打包格式

9. 性能优化

9.1 前端优化

组件懒加载
虚拟滚动（长列表）
图片懒加载
缓存策略

9.2 后端优化

数据库查询优化
响应缓存
异步处理
连接池管理

10. 安全考虑

10.1 本地安全

本地服务器仅监听 localhost
防止外部访问
数据加密存储（可选）

10.2 数据安全

数据库文件权限控制
定期备份机制
敏感数据保护

11. 测试策略

11.1 单元测试

核心业务逻辑测试
服务层测试
工具函数测试

11.2 集成测试

API 集成测试
数据库集成测试
前后端集成测试

11.3 端到端测试

跨平台功能测试
用户流程测试
性能测试

16 KiB Raw Permalink Blame History Unescape Escape

Hua.Todo 技术设计文档 v1.1.0

1. 项目概述

2. 技术栈

2.1 后端技术栈

2.2 前端技术栈

3. 项目目录结构

4. 模块设计

4.1 MAUI 主项目 (Hua.Todo.Maui)

4.2 Avalonia 项目 (Hua.Todo.Avalonia)

4.3 后端 API 项目 (Hua.Todo.Host)

4.4 核心业务层 (Hua.Todo.Core)

4.5 前端 Web 项目 (Hua.Todo.Web)

5. HTTP API 设计

5.1 API 基础配置

5.2 API 端点设计

任务管理 API

云同步 API（Host 模式）

6. 数据库设计

6.1 数据库表结构

Tasks 表

Settings 表

6.2 数据访问策略

7. 通信机制

7.1 HTTP 通信流程

7.2 错误处理

8. 部署和打包

8.1 开发环境

8.2 生产构建

8.3 平台特定配置

9. 性能优化

9.1 前端优化

9.2 后端优化

10. 安全考虑

10.1 本地安全

10.2 数据安全

11. 测试策略

11.1 单元测试

11.2 集成测试

11.3 端到端测试

16 KiB

Raw Permalink Blame History