ShaoHua
366 lines
14 KiB
Markdown
366 lines
14 KiB
Markdown
# 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/ # 文档目录
|
||
│ ├── manual/ # 用户/开发者手册
|
||
│ │ ├── 技术栈与模块.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.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 服务器启动
|
||
|
||
**调试与接口文档**：
|
||
- Windows Debug 模式下，内嵌 WebServer 默认提供 Swagger UI（`{HostUrl}/swagger`）与 OpenAPI JSON（`{HostUrl}/swagger/v1/swagger.json`），用于本地接口联调。
|
||
|
||
**关键组件**:
|
||
- `MauiProgram.cs`: 配置 MAUI 应用和依赖注入
|
||
- `App.xaml.cs`: 应用程序主入口
|
||
- `WebViewContainer`: 封装 WebView 控件
|
||
- 平台特定服务: 快捷键、通知等
|
||
|
||
### 4.2 后端 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.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（开发三件套 / 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 端到端测试
|
||
- 跨平台功能测试
|
||
- 用户流程测试
|
||
- 性能测试
|