# 技术栈与项目结构

> 本文档面向开发者，介绍 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-开发环境与构建](./06-开发环境与构建.md)
- 深入架构设计 → [07-技术架构设计](./07-技术架构设计.md)