# 项目架构（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)

## 七、测试项目架构

### 7.1 目录结构

```
test/                                     ← 项目根目录下的顶层测试目录
├── Hua.Todo.Host.Tests/                  ← 服务端/Application 层集成测试
│   ├── CloudSync/                        ← 云同步模块
│   ├── Meeting/                          ← 会议模块
│   └── Attachments/                      ← 附件模块
├── Hua.Todo.Maui.Tests/                  ← MAUI 平台测试（骨架）
└── Hua.Todo.Avalonia.Tests/              ← Avalonia 平台测试（骨架）
```

### 7.2 分层规则（严禁跨层）

| 测试项目 | 可引用的被测项目 | 不得引用 |
|---|---|---|
| `Hua.Todo.Host.Tests` | `Hua.Todo.Host` / `Application` / `Core` | MAUI / Avalonia 宿主 |
| `Hua.Todo.Maui.Tests` | `Hua.Todo.Maui` / `Application` / `Core` | Avalonia 宿主 |
| `Hua.Todo.Avalonia.Tests` | `Hua.Todo.Avalonia` / `Application` / `Core` | MAUI 宿主 |

### 7.3 技术栈与规范

- 框架：xUnit 2.9+，SQLite In-Memory 模拟 DB
- 测试层次：直接测 Application 服务层（DI 测试），必要时用 `WebApplicationFactory`
- 命名：类 `{被测类}Tests`、方法 `{方法名}_{场景}_{预期结果}`、命名空间 `Hua.Todo.Host.Tests.{模块名}`
- 文件组织：每个模块新建子目录，模块级共用测试放根目录