ShaoHua
4fe0b5a963
本次提交完成了项目核心基础架构升级： 1. 新增动态API中间件与权限控制系统，支持匿名/鉴权接口分离 2. 搭建云同步服务体系，包含认证、任务同步、安全策略等核心模块 3. 实现语音控制全链路，从STT/意图解析到命令执行 4. 新增任务类型、附件实体与相关仓储接口 5. 重构前端配置与代理规则，统一后端端口为5057 6. 新增多平台测试项目与CI脚本优化 7. 完善项目文档与代码注释规范 移除了旧版迁移文件与冗余代理配置，调整项目结构适配跨平台部署需求。
391 lines
12 KiB
Markdown
391 lines
12 KiB
Markdown
# 技术架构设计
|
||
|
||
> 本文档面向开发者，描述 Hua.Todo 的详细技术架构，包括目录结构、模块设计、API 端点、数据库设计与通信机制。
|
||
|
||
## 1. 项目目录结构
|
||
|
||
```
|
||
Hua.Todo/
|
||
├── docs/ # 文档目录
|
||
│ ├── manual/ # 用户/开发者手册
|
||
│ │ ├── 00-目录与导读.md
|
||
│ │ ├── 01-项目介绍.md
|
||
│ │ ├── 02-安装指南.md
|
||
│ │ ├── 03-版本记录.md
|
||
│ │ ├── 04-其他信息.md
|
||
│ │ ├── 05-技术栈与项目结构.md
|
||
│ │ ├── 06-开发环境与构建.md
|
||
│ │ ├── 07-技术架构设计.md（本文件）
|
||
│ │ ├── 08-云同步规则.md
|
||
│ │ ├── 09-代码规范.md
|
||
│ │ └── 10-MCP服务集成.md
|
||
│ └── project/ # 项目进度/需求文档
|
||
│
|
||
├── src/ # 源代码目录
|
||
│ ├── Hua.Todo.Maui/ # MAUI 主项目（跨平台入口）
|
||
│ │ ├── Platforms/ # 平台特定代码
|
||
│ │ │ ├── Windows/ # Windows 平台代码
|
||
│ │ │ │ ├── App.xaml
|
||
│ │ │ │ └── Services/
|
||
│ │ │ │ └── HotKeyService.cs
|
||
│ │ │ ├── MacCatalyst/ # macOS 平台代码
|
||
│ │ │ ├── Android/ # Android 平台代码
|
||
│ │ │ └── iOS/ # iOS 平台代码
|
||
│ │ ├── Resources/ # 资源文件
|
||
│ │ ├── Controls/ # 自定义控件
|
||
│ │ │ └── WebViewContainer.xaml
|
||
│ │ ├── Services/ # 服务层
|
||
│ │ │ ├── IHotKeyService.cs
|
||
│ │ │ ├── IPlatformService.cs
|
||
│ │ │ └── AppLifecycleService.cs
|
||
│ │ ├── App.xaml / App.xaml.cs
|
||
│ │ ├── MauiProgram.cs
|
||
│ │ └── Hua.Todo.Maui.csproj
|
||
│ │
|
||
│ ├── Hua.Todo.Avalonia/ # Avalonia 项目（Linux 支持）
|
||
│ │ ├── Services/
|
||
│ │ │ ├── EmbeddedWebServerServiceFactory.cs
|
||
│ │ │ ├── GlobalHotKeyServiceFactory.cs
|
||
│ │ │ └── Platforms/
|
||
│ │ ├── Views/
|
||
│ │ │ ├── MainView.axaml / MainView.axaml.cs
|
||
│ │ │ └── MainWindow.axaml / MainWindow.axaml.cs
|
||
│ │ ├── App.axaml / App.axaml.cs
|
||
│ │ ├── Program.cs
|
||
│ │ ├── appsettings.json
|
||
│ │ ├── setup.iss
|
||
│ │ ├── wwwroot/
|
||
│ │ └── Hua.Todo.Avalonia.csproj
|
||
│ │
|
||
│ ├── Hua.Todo.Host/ # 独立服务端
|
||
│ │ ├── Program.cs # API 入口
|
||
│ │ ├── appsettings.json
|
||
│ │ └── Hua.Todo.Host.csproj
|
||
│ │
|
||
│ ├── Hua.Todo.Application/ # 应用层
|
||
│ │ ├── Data/
|
||
│ │ │ ├── TodoDbContext.cs
|
||
│ │ │ └── Migrations/
|
||
│ │ ├── DynamicApi/
|
||
│ │ ├── CloudSync/
|
||
│ │ ├── Voice/
|
||
│ │ ├── Mcp/
|
||
│ │ └── Hua.Todo.Application.csproj
|
||
│ │
|
||
│ ├── Hua.Todo.Core/ # 核心业务逻辑层
|
||
│ │ ├── Entities/
|
||
│ │ │ ├── TaskEntity.cs
|
||
│ │ │ ├── UserEntity.cs
|
||
│ │ │ ├── SecurityPolicyEntity.cs
|
||
│ │ │ └── AuditLogEntity.cs
|
||
│ │ ├── Interfaces/
|
||
│ │ └── Hua.Todo.Core.csproj
|
||
│ │
|
||
│ ├── Hua.Todo.Web/ # 前端 Web 项目 (Vue.js)
|
||
│ │ ├── src/
|
||
│ │ │ ├── api/ # API 调用
|
||
│ │ │ │ ├── client.ts
|
||
│ │ │ │ ├── tasks.ts
|
||
│ │ │ │ ├── cloudSync.ts
|
||
│ │ │ │ └── mcp.ts
|
||
│ │ │ ├── components/ # Vue 组件
|
||
│ │ │ │ ├── TaskList.vue
|
||
│ │ │ │ ├── TaskItem.vue
|
||
│ │ │ │ └── TaskEditDialog.vue
|
||
│ │ │ ├── composables/ # 组合式函数
|
||
│ │ │ ├── stores/ # 状态管理 (Pinia)
|
||
│ │ │ ├── types/ # TypeScript 类型定义
|
||
│ │ │ ├── utils/ # 工具函数
|
||
│ │ │ ├── App.vue
|
||
│ │ │ └── main.ts
|
||
│ │ ├── package.json
|
||
│ │ ├── vite.config.ts
|
||
│ │ ├── tsconfig.json
|
||
│ │ └── index.html
|
||
│ │
|
||
│ └── test/ # 测试项目
|
||
│ ├── Hua.Todo.Host.Tests/ # Host 服务端测试
|
||
│ ├── Hua.Todo.Maui.Tests/ # MAUI 客户端测试
|
||
│ └── Hua.Todo.Avalonia.Tests/ # Avalonia 客户端测试
|
||
│
|
||
├── publish.ps1 / publish-windows.ps1 / publish-linux.ps1
|
||
├── Directory.Build.props
|
||
├── Hua.Todo.sln
|
||
└── README.md
|
||
```
|
||
|
||
## 2. 模块设计
|
||
|
||
### 2.1 Hua.Todo.Maui（跨平台客户端）
|
||
|
||
**职责**：
|
||
- 应用程序入口和生命周期管理
|
||
- 平台特定功能封装
|
||
- WebView 容器管理
|
||
- 本地 HTTP 服务器启动
|
||
|
||
**关键组件**：
|
||
- `MauiProgram.cs`：配置 MAUI 应用和依赖注入
|
||
- `App.xaml.cs`：应用程序主入口
|
||
- `WebViewContainer`：封装 WebView 控件
|
||
- 平台特定服务：快捷键、通知等
|
||
|
||
### 2.2 Hua.Todo.Avalonia（桌面客户端）
|
||
|
||
**职责**：
|
||
- Linux 平台支持
|
||
- 桌面交互功能（托盘菜单、全局热键等）
|
||
- WebView 容器管理
|
||
- 本地 HTTP 服务器启动
|
||
|
||
**关键组件**：
|
||
- `Program.cs`：配置 Avalonia 应用和依赖注入
|
||
- `App.axaml.cs`：应用程序主入口
|
||
- `MainWindow.axaml.cs`：主窗口管理
|
||
- `GlobalHotKeyServiceFactory`：全局热键服务工厂
|
||
- `EmbeddedWebServerServiceFactory`：内嵌 Web 服务器服务工厂
|
||
|
||
### 2.3 Hua.Todo.Host（独立服务端）
|
||
|
||
**职责**：
|
||
- 提供 RESTful API 接口
|
||
- 云同步端点（认证、同步、安全策略）
|
||
- MCP 协议端点
|
||
- 语音控制端点
|
||
|
||
**接口文档**：
|
||
- 开发环境下提供 Swagger UI：`http://localhost:5173/swagger`
|
||
|
||
**关键组件**：
|
||
- `CloudSync`：云同步 Minimal APIs（`/auth`、`/tasks`、`/sync`、`/security`）
|
||
- `DynamicApiMiddleware`：业务接口通过 Dynamic API（`/api/{service}/...`）对外暴露
|
||
- `MCP`：MCP 协议端点（`/mcp`）
|
||
- `Program.cs`：API 服务器配置和启动
|
||
|
||
### 2.4 Hua.Todo.Core（核心业务层）
|
||
|
||
**职责**：
|
||
- 定义领域模型和业务规则
|
||
- 提供核心业务接口
|
||
- 实现领域驱动设计模式
|
||
|
||
**关键组件**：
|
||
- `Entities`：领域实体（TaskEntity、UserEntity、SecurityPolicyEntity、AuditLogEntity）
|
||
- `Interfaces`：业务接口定义
|
||
- `Voice`：语音控制相关接口与枚举
|
||
|
||
### 2.5 Hua.Todo.Application（应用层）
|
||
|
||
**职责**：
|
||
- 业务逻辑实现
|
||
- EF Core 数据访问与迁移
|
||
- 动态 API 生成
|
||
- 云同步服务
|
||
- 语音控制服务
|
||
- MCP 工具注册
|
||
|
||
### 2.6 Hua.Todo.Web（前端）
|
||
|
||
**职责**：
|
||
- 用户界面展示
|
||
- 用户交互处理
|
||
- HTTP API 调用
|
||
- 状态管理
|
||
|
||
## 3. HTTP API 设计
|
||
|
||
### 3.1 API 基础配置
|
||
|
||
| 模式 | 基础 URL |
|
||
|---|---|
|
||
| 开发 / Host 模式 | `http://localhost:5173/api` |
|
||
| MAUI 内嵌模式 | `{HostUrl}/api`（默认 `http://localhost:5057/api`） |
|
||
|
||
- 数据格式：JSON
|
||
- 认证方式：云同步端点需要 Bearer Token，本地端点无需认证
|
||
|
||
### 3.2 任务管理 API（Dynamic API）
|
||
|
||
```
|
||
GET /api/task # 获取任务列表
|
||
GET /api/task/active # 获取未完成任务
|
||
GET /api/task/completed # 获取已完成任务
|
||
GET /api/task/{id} # 获取单个任务
|
||
POST /api/task # 创建任务
|
||
PUT /api/task # 更新任务
|
||
DELETE /api/task/{id} # 删除任务
|
||
PATCH /api/task/{id}/toggle # 切换完成状态
|
||
GET /api/task/{parentTaskId}/subtasks # 获取子任务列表
|
||
```
|
||
|
||
### 3.3 云同步 API（Host 模式）
|
||
|
||
```
|
||
POST /auth/bootstrap # 初始化管理员（仅首次）
|
||
POST /auth/login # 登录
|
||
POST /auth/step-up # 二次验证
|
||
GET /tasks/ # 获取云端任务
|
||
POST /sync/ # 推送/拉取合并同步
|
||
GET /security/policy # 获取安全策略
|
||
PUT /security/policy # 更新安全策略
|
||
```
|
||
|
||
### 3.4 MCP 端点
|
||
|
||
```
|
||
POST /mcp # MCP JSON-RPC 2.0 端点
|
||
```
|
||
|
||
## 4. 数据库设计
|
||
|
||
### 4.1 核心表结构
|
||
|
||
#### Tasks 表
|
||
```sql
|
||
CREATE TABLE T_Tasks (
|
||
Id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||
UserId TEXT NOT NULL,
|
||
Title TEXT NOT NULL,
|
||
Priority INTEGER NOT NULL DEFAULT 0,
|
||
IsCompleted INTEGER NOT NULL DEFAULT 0,
|
||
ParentTaskId INTEGER,
|
||
CreatedAt TEXT NOT NULL,
|
||
UpdatedAt TEXT NOT NULL
|
||
);
|
||
```
|
||
|
||
#### Users 表
|
||
```sql
|
||
CREATE TABLE T_Users (
|
||
Id TEXT PRIMARY KEY,
|
||
UserName TEXT NOT NULL UNIQUE,
|
||
PasswordHash TEXT NOT NULL,
|
||
PasswordSalt TEXT NOT NULL,
|
||
Role TEXT NOT NULL,
|
||
MustChangePassword INTEGER NOT NULL DEFAULT 0
|
||
);
|
||
```
|
||
|
||
#### SecurityPolicies 表
|
||
```sql
|
||
CREATE TABLE T_SecurityPolicies (
|
||
Id TEXT PRIMARY KEY,
|
||
UserId TEXT NOT NULL,
|
||
AllowPersist INTEGER NOT NULL DEFAULT 1,
|
||
AllowSync INTEGER NOT NULL DEFAULT 1,
|
||
SecondFactorExpiryMinutes INTEGER DEFAULT 0,
|
||
IsTrustedDeviceOnly INTEGER NOT NULL DEFAULT 0
|
||
);
|
||
```
|
||
|
||
#### AuditLogs 表
|
||
```sql
|
||
CREATE TABLE T_AuditLogs (
|
||
Id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||
UserId TEXT,
|
||
Action TEXT NOT NULL,
|
||
OccurredAtUtc TEXT NOT NULL,
|
||
Details TEXT
|
||
);
|
||
```
|
||
|
||
### 4.2 数据访问策略
|
||
|
||
- 使用 Entity Framework Core 进行数据访问
|
||
- 采用 Repository 模式封装数据访问
|
||
- 支持 LINQ 查询和异步操作
|
||
- EF Core 迁移管理（见 `Hua.Todo.Application/Migrations/`）
|
||
- 表名遵循 ABP 规范：`T_{实体名}s`
|
||
|
||
## 5. 通信机制
|
||
|
||
### 5.1 HTTP 通信流程
|
||
|
||
1. **C# 后端启动**：MAUI/Avalonia 应用启动时启动本地 Kestrel 服务器
|
||
2. **Vue 前端加载**：WebView 加载 Vue 应用
|
||
3. **API 调用**：Vue 通过 Axios 调用本地 HTTP API
|
||
4. **数据处理**：C# 后端处理请求并返回 JSON 数据
|
||
5. **界面更新**：Vue 接收响应并更新界面
|
||
|
||
### 5.2 错误处理
|
||
|
||
- 统一的错误响应格式
|
||
- 异常中间件捕获和处理
|
||
- 前端错误提示和重试机制
|
||
|
||
### 5.3 WebView 注入
|
||
|
||
前端通过 `window` 对象接收宿主注入的信息：
|
||
- `window.__API_BASE_URL__`：API 基础路径
|
||
- `window.mauiInterop`：MAUI 平台互操作对象
|
||
|
||
## 6. 部署和打包
|
||
|
||
### 6.1 开发环境
|
||
|
||
- **后端调试**：使用 Visual Studio 调试 MAUI/Avalonia 应用
|
||
- **前端调试**：使用 Vite 开发服务器
|
||
- **热重载**：支持前后端热重载
|
||
|
||
### 6.2 生产构建
|
||
|
||
- **前端构建**：`npm run build` 生成静态文件
|
||
- **后端打包**：各平台发布脚本产出可分发包
|
||
- **静态文件嵌入**：将前端静态文件嵌入到桌面应用中
|
||
|
||
详细构建流程见 [06-开发环境与构建](./06-开发环境与构建.md)。
|
||
|
||
### 6.3 平台特定配置
|
||
|
||
- **Windows**：WebView2 运行时要求
|
||
- **macOS**：代码签名和公证
|
||
- **移动端**：应用商店发布配置
|
||
- **Linux**：需要 GTK + WebKitGTK 运行时依赖
|
||
|
||
## 7. 性能优化
|
||
|
||
### 7.1 前端优化
|
||
- 组件懒加载
|
||
- 虚拟滚动（长列表）
|
||
- 图片懒加载
|
||
- 缓存策略
|
||
|
||
### 7.2 后端优化
|
||
- 数据库查询优化（含索引策略）
|
||
- 响应缓存
|
||
- 异步处理
|
||
- SQLite WAL 模式（嵌入式宿主自动开启）
|
||
|
||
## 8. 安全考虑
|
||
|
||
### 8.1 本地安全
|
||
- 本地服务器仅监听 localhost
|
||
- 防止外部访问
|
||
- 数据加密存储（可选）
|
||
|
||
### 8.2 数据安全
|
||
- 数据库文件权限控制
|
||
- 定期备份机制
|
||
- 敏感数据保护
|
||
|
||
### 8.3 云同步安全
|
||
|
||
详见 [08-云同步规则](./08-云同步规则.md)。
|
||
|
||
## 9. 测试策略
|
||
|
||
### 9.1 单元测试
|
||
- 核心业务逻辑测试
|
||
- 服务层测试
|
||
- 工具函数测试
|
||
|
||
### 9.2 集成测试
|
||
- API 集成测试
|
||
- 数据库集成测试
|
||
- 前后端集成测试
|
||
|
||
### 9.3 端到端测试
|
||
- 跨平台功能测试
|
||
- 用户流程测试
|
||
- 性能测试
|