ShaoHua
4fe0b5a963
本次提交完成了项目核心基础架构升级： 1. 新增动态API中间件与权限控制系统，支持匿名/鉴权接口分离 2. 搭建云同步服务体系，包含认证、任务同步、安全策略等核心模块 3. 实现语音控制全链路，从STT/意图解析到命令执行 4. 新增任务类型、附件实体与相关仓储接口 5. 重构前端配置与代理规则，统一后端端口为5057 6. 新增多平台测试项目与CI脚本优化 7. 完善项目文档与代码注释规范 移除了旧版迁移文件与冗余代理配置，调整项目结构适配跨平台部署需求。
6.4 KiB
6.4 KiB
项目架构（Hua.Todo 专属）
适用范围：本规则属于 项目规则（仅 Hua.Todo 项目生效）。
描述当前仓库的项目划分、依赖方向、运行模式与跨平台策略，供智能体在做改动时快速对齐架构边界。 完整设计参见 docs/manual/05-技术栈与项目结构.md 与 docs/manual/07-技术架构设计.md。
一、项目清单（src/）
| 项目 | 类型 | 职责 | 平台 |
|---|---|---|---|
| Hua.Todo.Core | 类库 | 领域实体、仓储接口（TaskEntity、UserEntity、SecurityPolicyEntity、AuditLogEntity、ITaskRepository 等） |
netstandard / net |
| Hua.Todo.Application | 类库（共享层） | EF Core TodoDbContext、TaskService/TaskRepository、动态 API（DynamicApi/）、云同步（CloudSync/）、迁移 |
net |
| Hua.Todo.Host | ASP.NET 服务端 | 独立服务端宿主，承载本地动态 API + 云同步端点 + Admin 管理后台静态资源 | Windows/Linux 等服务器 |
| Hua.Todo.Maui | MAUI 客户端 | Windows / macOS / iOS / Android 入口；内嵌 WebServer + WebView 承载 Vue 前端 | 多端 |
| Hua.Todo.Avalonia | Avalonia 客户端 | Linux / Windows 桌面入口；内嵌 WebServer + WebView.Avalonia 承载 Vue 前端 |
桌面（含 Linux） |
| 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。
三、两种运行模式
模式 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 |
| 云同步 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
七、测试项目架构
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.{模块名} - 文件组织：每个模块新建子目录，模块级共用测试放根目录