ShaoHua
65cee20006
- 新增 00-目录与导读.md 双入口导航 - 用户面(01-04)：项目介绍、安装指南、版本记录、其他信息 - 开发者面(05-10)：技术栈、构建、架构、云同步、代码规范、MCP - 拆分旧01为 01(用户)+05(开发者)；旧02为 02(用户)+06(开发者) - 合并旧08+09 MCP文档为 10-MCP服务集成 - 同步更新 README.md 与 .trae/rules/项目/ 交叉引用
76 lines
5.1 KiB
Markdown
76 lines
5.1 KiB
Markdown
# 项目架构（Hua.Todo 专属）
|
||
|
||
> 适用范围：本规则属于 **项目规则**（仅 Hua.Todo 项目生效）。
|
||
>
|
||
> 描述当前仓库的项目划分、依赖方向、运行模式与跨平台策略，供智能体在做改动时快速对齐架构边界。
|
||
> 完整设计参见 [docs/manual/05-技术栈与项目结构.md](../../../docs/manual/05-技术栈与项目结构.md) 与 [docs/manual/07-技术架构设计.md](../../../docs/manual/07-技术架构设计.md)。
|
||
|
||
## 一、项目清单（src/）
|
||
|
||
| 项目 | 类型 | 职责 | 平台 |
|
||
|---|---|---|---|
|
||
| [Hua.Todo.Core](file:///d:/Proj/6.Hua.Todo/src/Hua.Todo.Core) | 类库 | 领域实体、仓储接口（`TaskEntity`、`UserEntity`、`SecurityPolicyEntity`、`AuditLogEntity`、`ITaskRepository` 等） | netstandard / net |
|
||
| [Hua.Todo.Application](file:///d:/Proj/6.Hua.Todo/src/Hua.Todo.Application) | 类库（共享层） | EF Core `TodoDbContext`、`TaskService`/`TaskRepository`、动态 API（`DynamicApi/`）、云同步（`CloudSync/`）、迁移 | net |
|
||
| [Hua.Todo.Host](file:///d:/Proj/6.Hua.Todo/src/Hua.Todo.Host) | ASP.NET 服务端 | 独立服务端宿主，承载本地动态 API + 云同步端点 + Admin 管理后台静态资源 | Windows/Linux 等服务器 |
|
||
| [Hua.Todo.Maui](file:///d:/Proj/6.Hua.Todo/src/Hua.Todo.Maui) | MAUI 客户端 | Windows / macOS / iOS / Android 入口；内嵌 WebServer + WebView 承载 Vue 前端 | 多端 |
|
||
| [Hua.Todo.Avalonia](file:///d:/Proj/6.Hua.Todo/src/Hua.Todo.Avalonia) | Avalonia 客户端 | Linux / Windows 桌面入口；内嵌 WebServer + `WebView.Avalonia` 承载 Vue 前端 | 桌面（含 Linux） |
|
||
| [Hua.Todo.Web](file:///d:/Proj/6.Hua.Todo/src/Hua.Todo.Web) | Vite + Vue 3 前端 | 同一份前端构建产物，被多个宿主以静态资源形式承载 | 浏览器/WebView |
|
||
|
||
## 二、依赖方向（必须保持单向）
|
||
|
||
```
|
||
Hua.Todo.Core
|
||
↑
|
||
Hua.Todo.Application
|
||
↑
|
||
├── Hua.Todo.Host (服务端注册 AddCloudSyncServer + 动态 API)
|
||
├── Hua.Todo.Maui (客户端，仅注册 AddApplicationServices)
|
||
└── Hua.Todo.Avalonia (客户端，仅注册 AddApplicationServices)
|
||
|
||
Hua.Todo.Web (无 .NET 依赖；通过 HTTP/同源调用上述任一宿主)
|
||
```
|
||
|
||
- **禁止反向依赖**：Core 不得引用 Application；Application 不得引用任何宿主项目。
|
||
- **客户端不暴露云同步端点**：MAUI / Avalonia 只调用 `AddApplicationServices()`，不调用 `AddCloudSyncServer()`，详见 [docs/project/研发工单-v1.2.0/08-cloud_sync_refactor_plan.md](../../../docs/project/研发工单-v1.2.0/08-cloud_sync_refactor_plan.md)。
|
||
|
||
## 三、两种运行模式
|
||
|
||
### 模式 A：嵌入式（MAUI / Avalonia + WebView）
|
||
- 启动内嵌 Kestrel WebServer（默认端口 5057），托管 Vue 前端的静态产物（`wwwroot/`）+ 本地 `/api/*`
|
||
- WebView 加载 `HostUrl`（生产）或 `ForEndUrl`（开发，例如 Vite dev server）
|
||
- 注入：`window.__API_BASE_URL__ = "${HostUrl}/api"`、`window.mauiInterop`
|
||
- 默认 SQLite 路径：`LocalApplicationData/Hua.Todo/Hua.Todo.db`（避免安装目录无写权限）
|
||
- 不暴露云同步端点；登录/同步走外部 Host
|
||
|
||
### 模式 B：独立服务端（Hua.Todo.Host）
|
||
- 独立部署的 ASP.NET 应用，端口 `:5173`（Vite proxy 目标）
|
||
- 同时注册 `AddApplicationServices()` + `AddCloudSyncServer()`，对外提供：
|
||
- `/api/*`：本地任务 API（动态 API）
|
||
- `/auth/*`、`/tasks/*`、`/sync`、`/security/policy`、`/cloud-sync/probe`：云同步端点
|
||
- `/admin/*`：管理后台前端静态资源
|
||
- 数据库：`src/Hua.Todo.Host/Hua.Todo.db`（开发/测试用）
|
||
|
||
## 四、跨平台原则
|
||
|
||
- **业务逻辑统一在 Application 层**，宿主项目只做 DI 装配与平台桥接
|
||
- **平台差异通过接口 + 平台目录**实现（例：`IGlobalHotKeyService` 在 MAUI 与 Avalonia 各有自己的 `Platforms/` 子目录实现）
|
||
- **前端只有一份**：Vue 项目通过不同的 `.env.*` 文件区分模式（`.env.development` / `.env.maui` / `.env.production`）
|
||
|
||
## 五、关键扩展点
|
||
|
||
| 扩展点 | 位置 |
|
||
|---|---|
|
||
| DI 注册总入口 | [Hua.Todo.Application/ServiceCollectionExtensions.cs](file:///d:/Proj/6.Hua.Todo/src/Hua.Todo.Application/ServiceCollectionExtensions.cs) |
|
||
| 云同步 DI | `Hua.Todo.Application/CloudSync/CloudSyncServiceCollectionExtensions.cs` |
|
||
| 云同步端点 | `Hua.Todo.Application/CloudSync/CloudSyncEndpointExtensions.cs` |
|
||
| 动态 API 中间件 | `Hua.Todo.Application/DynamicApi/DynamicApiMiddleware.cs` |
|
||
| 嵌入式 WebServer | `Hua.Todo.{Maui,Avalonia}/Services/EmbeddedWebServerService.cs` |
|
||
| 全局快捷键平台实现 | `Hua.Todo.{Maui,Avalonia}/Services/Platforms/*GlobalHotKeyService.cs` |
|
||
|
||
## 六、版本统一策略
|
||
|
||
- 全局版本号通过根目录 `Directory.Build.props` 集中管理（当前 `1.2.3`）
|
||
- Inno Setup 安装包：`src/Hua.Todo.Maui/setup.iss`、`src/Hua.Todo.Avalonia/setup.iss`
|
||
- Linux：`publish-linux.ps1` 产出 `.tar.gz`；`pack/linux/` 含 Flatpak 基础结构
|
||
- 详见 [docs/project/研发工单-v1.2.0/02.1-版本统一与打包方案.md](../../../docs/project/研发工单-v1.2.0/02.1-版本统一与打包方案.md)
|