Files

T

ShaoHua 4fe0b5a963 feat: 完成云同步、语音控制与多平台扩展基础架构搭建

本次提交完成了项目核心基础架构升级：
1. 新增动态API中间件与权限控制系统，支持匿名/鉴权接口分离
2. 搭建云同步服务体系，包含认证、任务同步、安全策略等核心模块
3. 实现语音控制全链路，从STT/意图解析到命令执行
4. 新增任务类型、附件实体与相关仓储接口
5. 重构前端配置与代理规则，统一后端端口为5057
6. 新增多平台测试项目与CI脚本优化
7. 完善项目文档与代码注释规范

移除了旧版迁移文件与冗余代理配置，调整项目结构适配跨平台部署需求。

2026-06-21 03:26:04 +08:00

12 KiB

Raw Permalink Blame History

技术架构设计

本文档面向开发者，描述 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 表

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 表

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 表

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 表

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 通信流程

C# 后端启动：MAUI/Avalonia 应用启动时启动本地 Kestrel 服务器
Vue 前端加载：WebView 加载 Vue 应用
API 调用：Vue 通过 Axios 调用本地 HTTP API
数据处理：C# 后端处理请求并返回 JSON 数据
界面更新：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-开发环境与构建。

6.3 平台特定配置

Windows：WebView2 运行时要求
macOS：代码签名和公证
移动端：应用商店发布配置
Linux：需要 GTK + WebKitGTK 运行时依赖

7. 性能优化

7.1 前端优化

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

7.2 后端优化

数据库查询优化（含索引策略）
响应缓存
异步处理
SQLite WAL 模式（嵌入式宿主自动开启）

8. 安全考虑

8.1 本地安全

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

8.2 数据安全

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

8.3 云同步安全

详见 08-云同步规则。

9. 测试策略

9.1 单元测试

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

9.2 集成测试

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

9.3 端到端测试

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

12 KiB Raw Permalink Blame History Unescape Escape

技术架构设计

1. 项目目录结构

2. 模块设计

2.1 Hua.Todo.Maui（跨平台客户端）

2.2 Hua.Todo.Avalonia（桌面客户端）

2.3 Hua.Todo.Host（独立服务端）

2.4 Hua.Todo.Core（核心业务层）

2.5 Hua.Todo.Application（应用层）

2.6 Hua.Todo.Web（前端）

3. HTTP API 设计

3.1 API 基础配置

3.2 任务管理 API（Dynamic API）

3.3 云同步 API（Host 模式）

3.4 MCP 端点

4. 数据库设计

4.1 核心表结构

Tasks 表

Users 表

SecurityPolicies 表

AuditLogs 表

4.2 数据访问策略

5. 通信机制

5.1 HTTP 通信流程

5.2 错误处理

5.3 WebView 注入

6. 部署和打包

6.1 开发环境

6.2 生产构建

6.3 平台特定配置

7. 性能优化

7.1 前端优化

7.2 后端优化

8. 安全考虑

8.1 本地安全

8.2 数据安全

8.3 云同步安全

9. 测试策略

9.1 单元测试

9.2 集成测试

9.3 端到端测试

12 KiB

Raw Permalink Blame History