Hua.Todo/.trae/rules/项目/01-项目架构.md

项目架构（Hua.Todo 专属）

适用范围：本规则属于 项目规则（仅 Hua.Todo 项目生效）。

描述当前仓库的项目划分、依赖方向、运行模式与跨平台策略，供智能体在做改动时快速对齐架构边界。 完整设计参见 docs/manual/01-技术设计文档.md 与 docs/manual/03-技术栈与模块.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