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

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

## 2. 技术栈

### 2.1 后端技术栈
- **开发语言**: C# 10
- **框架**: .NET 10
- **UI 框架**: MAUI (Multi-platform App UI)
- **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/                              # 文档目录
│   ├── PRD.md                         # 产品需求文档
│   ├── PRD-1.1.0.md                   # v1.1.0 产品需求文档
│   ├── TechnicalDesign.md             # 技术设计文档（本文件）
│   └── CodeStandards.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.Api/                  # 后端 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
│   │   │   ├── Repositories/
│   │   │   │   ├── ITaskRepository.cs
│   │   │   │   └── TaskRepository.cs
│   │   │   └── Migrations/            # 数据库迁移
│   │   ├── Middleware/                # 中间件
│   │   │   └── ExceptionMiddleware.cs
│   │   ├── Extensions/                # 扩展方法
│   │   │   └── ServiceCollectionExtensions.cs
│   │   ├── Program.cs                 # API 入口
│   │   ├── appsettings.json           # 配置文件
│   │   └── Hua.Todo.Api.csproj        # API 项目文件
│   │
│   ├── 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/                    # 静态资源
│   │   │   └── index.html
│   │   ├── 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 服务器启动

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

### 4.2 后端 API 项目 (Hua.Todo.Api)
**职责**:
- 提供 RESTful API 接口
- 业务逻辑处理
- 数据访问和持久化
- 本地 HTTP 服务器托管

**关键组件**:
- `Controllers`: API 端点实现
- `Services`: 业务逻辑服务
- `Data`: 数据访问层和数据库上下文
- `Program.cs`: API 服务器配置和启动

### 4.3 核心业务层 (Hua.Todo.Core)
**职责**:
- 定义领域模型和业务规则
- 提供核心业务接口
- 实现领域驱动设计模式

**关键组件**:
- `Entities`: 领域实体
- `Interfaces`: 业务接口定义
- `ValueObjects`: 值对象
- `Specifications`: 业务规范

### 4.4 前端 Web 项目 (Hua.Todo.Web)
**职责**:
- 用户界面展示
- 用户交互处理
- HTTP API 调用
- 状态管理

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

## 5. HTTP API 设计

### 5.1 API 基础配置
- **基础 URL**: `http://localhost:5000/api`
- **数据格式**: JSON
- **认证方式**: 暂无（本地应用）
- **跨域配置**: 允许本地跨域请求

### 5.2 API 端点设计

#### 任务管理 API
```
GET    /api/tasks              # 获取任务列表
GET    /api/tasks/{id}         # 获取单个任务
POST   /api/tasks              # 创建任务
PUT    /api/tasks/{id}         # 更新任务
DELETE /api/tasks/{id}         # 删除任务
PATCH  /api/tasks/{id}/complete # 标记任务完成
```

#### 设置管理 API
```
GET    /api/settings          # 获取设置
PUT    /api/settings          # 更新设置
```

#### 同步 API
```
POST   /api/sync/pull         # 拉取远程数据
POST   /api/sync/push         # 推送本地数据
```

## 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**: 代码签名和公证
- **移动端**: 应用商店发布配置

## 9. 性能优化

### 9.1 前端优化
- 组件懒加载
- 虚拟滚动（长列表）
- 图片懒加载
- 缓存策略

### 9.2 后端优化
- 数据库查询优化
- 响应缓存
- 异步处理
- 连接池管理

## 10. 安全考虑

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

### 10.2 数据安全
- 数据库文件权限控制
- 定期备份机制
- 敏感数据保护

## 11. 测试策略

### 11.1 单元测试
- 核心业务逻辑测试
- 服务层测试
- 工具函数测试

### 11.2 集成测试
- API 集成测试
- 数据库集成测试
- 前后端集成测试

### 11.3 端到端测试
- 跨平台功能测试
- 用户流程测试
- 性能测试