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
parent 9223ceca50
commit 65cee20006
22 changed files with 1190 additions and 1232 deletions
@@ -0,0 +1,124 @@
+# 技术栈与项目结构
+
+> 本文档面向开发者，介绍 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)