ShaoHua
65cee20006
- 新增 00-目录与导读.md 双入口导航 - 用户面(01-04)：项目介绍、安装指南、版本记录、其他信息 - 开发者面(05-10)：技术栈、构建、架构、云同步、代码规范、MCP - 拆分旧01为 01(用户)+05(开发者)；旧02为 02(用户)+06(开发者) - 合并旧08+09 MCP文档为 10-MCP服务集成 - 同步更新 README.md 与 .trae/rules/项目/ 交叉引用
5.1 KiB
5.1 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