# 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 表
```sql
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 表
```sql
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 通信流程
1. **C# 后端启动**: MAUI 应用启动时启动本地 Kestrel 服务器
2. **Vue 前端加载**: WebView 加载 Vue 应用
3. **API 调用**: Vue 通过 Axios 调用本地 HTTP API
4. **数据处理**: C# 后端处理请求并返回 JSON 数据
5. **界面更新**: 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 端到端测试
- 跨平台功能测试
- 用户流程测试
- 性能测试