ShaoHua
4fe0b5a963
本次提交完成了项目核心基础架构升级： 1. 新增动态API中间件与权限控制系统，支持匿名/鉴权接口分离 2. 搭建云同步服务体系，包含认证、任务同步、安全策略等核心模块 3. 实现语音控制全链路，从STT/意图解析到命令执行 4. 新增任务类型、附件实体与相关仓储接口 5. 重构前端配置与代理规则，统一后端端口为5057 6. 新增多平台测试项目与CI脚本优化 7. 完善项目文档与代码注释规范 移除了旧版迁移文件与冗余代理配置，调整项目结构适配跨平台部署需求。
105 lines
6.4 KiB
Markdown
105 lines
6.4 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)
|
||
|
||
## 七、测试项目架构
|
||
|
||
### 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.{模块名}`
|
||
- 文件组织：每个模块新建子目录，模块级共用测试放根目录
|