Files

T

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

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

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

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

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

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

- 同步更新 README.md 与 .trae/rules/项目/ 交叉引用

2026-06-16 01:46:46 +08:00

4.8 KiB

Raw Blame History

技术栈与项目结构

本文档面向开发者，介绍 Hua.Todo 的技术选型、项目划分、模块职责与依赖关系。

1. 技术栈

1.1 后端

技术	版本/说明
开发语言	C# 13
框架	.NET 10
UI 框架	MAUI（移动端/部分桌面）+ Avalonia（桌面端）
Web 服务器	Kestrel（ASP.NET Core 内置）
API 框架	ASP.NET Core Web API（含动态 API 生成）
ORM	Entity Framework Core 10.0
数据库	SQLite（本地存储）
依赖注入	Microsoft.Extensions.DependencyInjection
日志	Serilog

1.2 前端

技术	版本/说明
开发语言	TypeScript 5+
框架	Vue.js 3
构建工具	Vite 5+
HTTP 客户端	Axios
状态管理	Pinia
UI 组件库	Element Plus / Vant（移动端）
CSS 预处理器	SCSS

2. 项目结构

Hua.Todo/
├── src/
│   ├── Hua.Todo.Core/          # 领域实体、枚举、仓储接口
│   ├── Hua.Todo.Application/   # 业务逻辑、EF Core、动态 API、云同步
│   ├── Hua.Todo.Host/          # 独立服务端宿主（ASP.NET）
│   ├── Hua.Todo.Maui/          # MAUI 客户端（Windows/macOS/Android/iOS）
│   ├── Hua.Todo.Avalonia/      # Avalonia 客户端（Linux/Windows 桌面）
│   ├── Hua.Todo.Web/           # Vue 3 前端（Vite）
│   └── Hua.Todo.Tests/         # 单元测试与集成测试
├── docs/
│   ├── manual/                 # 项目手册
│   ├── project/                # 产品需求文档与研发工单
│   └── AI沟通记录/             # AI 对话记录
└── .trae/                      # 智能体规则与记忆

3. 核心模块说明

3.1 Hua.Todo.Core

领域实体层，定义核心实体与接口：

实体：TaskEntity、UserEntity、SecurityPolicyEntity、AuditLogEntity
枚举：TaskPriority
仓储接口：ITaskRepository
语音控制接口：IVoiceInputService、IVoiceOutputService、IVoiceIntentParser

3.2 Hua.Todo.Application

应用层实现，所有业务逻辑的集中地：

TaskService：待办项 CRUD 业务逻辑
动态 API（DynamicApi/）：基于接口自动生成 RESTful API
云同步（CloudSync/）：认证服务、同步服务、安全策略管理
语音控制（Voice/）：LLM 客户端、双策略意图解析器、指令执行器
MCP 服务（Mcp/）：自动扫描并暴露 MCP 工具
数据访问：TodoDbContext + EF Core 迁移

3.3 Hua.Todo.Host

独立服务端宿主，同时注册业务服务与云同步端点：

AddApplicationServices()：待办项 CRUD + 动态 API
AddCloudSyncServer()：认证、同步、安全策略端点
AddMcpServerServices()：MCP 协议端点（/mcp）
AddVoiceServices()：语音控制端点

3.4 Hua.Todo.Maui

跨平台客户端，内嵌 Kestrel WebServer + WebView 承载前端：

仅注册 AddApplicationServices()，不暴露云同步端点
平台特定服务（快捷键、通知等）

3.5 Hua.Todo.Avalonia

桌面客户端（Avalonia + WebView），提供 Linux/Windows 桌面形态：

同样通过嵌入式 WebServer + WebView 承载前端
托盘菜单、全局热键等桌面交互功能

3.6 Hua.Todo.Web

Vue 3 前端项目，同一份构建产物被多个宿主以静态资源形式承载：

组件：TaskList、TaskItem、TaskEditDialog、CloudSyncSettings 等
状态管理：Pinia stores
API 层：api/tasks.ts、api/cloudSync.ts、api/mcp.ts

4. 依赖方向

Hua.Todo.Core
   ↑
Hua.Todo.Application
   ↑
   ├── Hua.Todo.Host       （服务端：全部能力）
   ├── Hua.Todo.Maui       （客户端：仅业务服务）
   └── Hua.Todo.Avalonia   （客户端：仅业务服务）

Hua.Todo.Web （无 .NET 依赖；通过 HTTP 调用上述任一宿主）

禁止反向依赖：Core 不得引用 Application；Application 不得引用任何宿主项目
客户端不暴露云同步端点：MAUI / Avalonia 只调用 AddApplicationServices()

5. 关键扩展点

扩展点	位置
DI 注册总入口	`Hua.Todo.Application/ServiceCollectionExtensions.cs`
云同步 DI	`Hua.Todo.Application/CloudSync/CloudSyncServiceCollectionExtensions.cs`
动态 API 中间件	`Hua.Todo.Application/DynamicApi/DynamicApiMiddleware.cs`
MCP 工具注册	`Hua.Todo.Application/Mcp/DynamicMcpToolExtensions.cs`
语音意图解析	`Hua.Todo.Application/Voice/HybridVoiceIntentParser.cs`
嵌入式 WebServer	`Hua.Todo.{Maui,Avalonia}/Services/EmbeddedWebServerService.cs`

6. 下一步

搭建开发环境 → 06-开发环境与构建
深入架构设计 → 07-技术架构设计

4.8 KiB Raw Blame History Unescape Escape