Hua/Hua.Todo
1
0
Fork 0
Code Issues Wiki Activity

docs: 重组 docs/manual/ 指南结构，区分普通用户与开发者双入口

Browse Source 
- 新增 00-目录与导读.md 双入口导航

- 用户面(01-04)：项目介绍、安装指南、版本记录、其他信息

- 开发者面(05-10)：技术栈、构建、架构、云同步、代码规范、MCP

- 拆分旧01为 01(用户)+05(开发者)；旧02为 02(用户)+06(开发者)

- 合并旧08+09 MCP文档为 10-MCP服务集成

- 同步更新 README.md 与 .trae/rules/项目/ 交叉引用
This commit is contained in:
ShaoHua
2026-06-16 01:46:46 +08:00
parent 9223ceca50
commit 65cee20006
22 changed files with 1190 additions and 1232 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/manual/07-技术架构设计.md
+389
View File
@@ -0,0 +1,389 @@
# 技术架构设计
> 本文档面向开发者，描述 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
│ │
│ └── Hua.Todo.Tests/ # 测试项目
│ ├── Unit/
│ └── Integration/
│
├── 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 端到端测试
- 跨平台功能测试
- 用户流程测试
- 性能测试