ShaoHua
65cee20006
- 新增 00-目录与导读.md 双入口导航 - 用户面(01-04)：项目介绍、安装指南、版本记录、其他信息 - 开发者面(05-10)：技术栈、构建、架构、云同步、代码规范、MCP - 拆分旧01为 01(用户)+05(开发者)；旧02为 02(用户)+06(开发者) - 合并旧08+09 MCP文档为 10-MCP服务集成 - 同步更新 README.md 与 .trae/rules/项目/ 交叉引用
125 lines
4.8 KiB
Markdown
125 lines
4.8 KiB
Markdown
# 技术栈与项目结构
|
||
|
||
> 本文档面向开发者，介绍 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)
|