feat:云同步,部分功能生效

2026-06-12 00:49:03 +08:00
parent c54f2e2ecc
commit a7ba814833
34 changed files with 1532 additions and 471 deletions
@@ -1,30 +1,27 @@
 # Hua.Todo 跨平台代办管理应用 v1.2.8

-一个基于 WebView 容器（MAUI / Avalonia）+ 嵌入式 ASP.NET Core WebServer 架构开发的跨平台代办管理应用，支持 Windows、macOS、Android、iOS 和 Linux 平台。通过 HTTP API 实现前后端通信，提供轻量、高效的任务管理体验。
+一个基于 **WebView 容器（MAUI / Avalonia）+ 嵌入式 ASP.NET Core WebServer** 架构开发的跨平台代办管理应用，支持 **Windows、macOS、Android、iOS 和 Linux** 平台。通过 HTTP API 实现前后端通信，提供轻量、高效的任务管理体验。

 ## 🚀 功能特点

 ### 核心功能
- **跨平台支持**：基于 MAUI / Avalonia + WebView 架构，支持 Windows、macOS、Android、iOS 和 Linux。
- **任务管理**：支持创建、编辑、删除、完成状态切换、子任务管理。
- **云同步 (CloudSync)**：支持手动配置服务端地址并登录后拉取云端任务，支持安全策略（SecurityPolicy）配置。
- **关键词检索**：支持按任务标题实时过滤，支持 Esc 清空，大小写不敏感。
- **本地数据持久化**：使用 SQLite 数据库保存数据，支持 DateTime 兼容性解析。
- **动态 API**：后端自动生成 RESTful API 并集成 Swagger UI，便于联调与调试。
+- **跨平台支持**：基于 MAUI + Avalonia + WebView 架构，覆盖 Windows、macOS、Android、iOS 和 Linux 五大平台
+- **任务管理**：支持任务创建、编辑、删除、完成状态切换，以及子任务管理
+- **云同步 (CloudSync)**：支持手动配置服务端地址并登录后拉取云端任务，支持安全策略配置
+- **关键词检索**：支持按任务标题实时过滤，支持 Esc 清空，大小写不敏感
+- **本地数据持久化**：使用 SQLite 数据库保存数据，支持 DateTime 兼容性解析
+- **动态 API**：后端自动生成 RESTful API 并集成 Swagger UI，便于联调与调试
+- **全局快捷键**：支持系统级快捷键快速唤起应用

 ## 📦 安装与使用

 ### 环境要求
- **后端**：
-  - .NET 10 SDK
-  - Visual Studio 2022 或更高版本
- **前端**：
-  - Node.js 18+ 
-  - npm 或 yarn
+- **后端**：.NET 10 SDK + Visual Studio 2022 或更高版本
+- **前端**：Node.js 18+ + npm 或 yarn

 ### 快速开始

-#### 1. 克隆或下载项目
+#### 1. 克隆项目
 ```bash
 git clone <仓库地址>
 cd Hua.Todo
@@ -36,8 +33,8 @@ cd src/Hua.Todo.Host
 dotnet restore
 dotnet run
 ```
-API 将在 `http://localhost:5173` 启动
-开发环境（`ASPNETCORE_ENVIRONMENT=Development`）下提供 Swagger UI：`http://localhost:5173/swagger`（或 `https://localhost:7175/swagger`）
+API 将在 `http://localhost:5173` 启动  
+开发环境下提供 Swagger UI：`http://localhost:5173/swagger`

 #### 3. 启动前端 Web
 ```bash
@@ -45,31 +42,38 @@ cd src/Hua.Todo.Web
 npm install
 npm run dev
 ```
-前端将在 `http://localhost:5174` 启动，并自动代理 `/api` 请求到 `http://localhost:5173`
+前端将在 `http://localhost:5174` 启动，并自动代理 `/api` 请求到后端

 #### 4. 启动 MAUI 客户端（Windows 三件套开发）
- 推荐：在 Visual Studio 中将启动项目设置为 `Hua.Todo.Maui`，并确保 `Hua.Todo.Host(5173)` 与 `Hua.Todo.Web(5174)` 已启动，然后按 F5 运行。
- 也可使用脚本一键拉起 Host + Vite（并可选启动 MAUI）：
-
+推荐使用脚本一键启动：
 ```powershell
 .\start-dev.ps1
 ```

-### Windows 交付产物（安装包）
+### 构建与发布

- 运行 `publish-windows.ps1` 默认使用 `Release` 配置生成 Inno Setup 安装包：`src/Hua.Todo.Maui/Output/Hua.Todo_Setup_vX.Y.Z.exe`（版本号来自 `Hua.Todo.Maui.csproj` 的 `<Version>`；根目录 `Directory.Build.targets` 会对 `Hua.Todo.Maui` 按 TargetFramework 条件配置 `UseMonoRuntime`：仅 Android 启用，其它目标关闭；同时会复制到 `artifacts/windows/<RID>/installer/`）
- 运行 `publish.ps1` 默认会同时发布 Windows + Linux（仅发布 Windows：`publish.ps1 -Windows`），且均默认使用 `Release` 配置。
- 安装后主程序为：`Hua.Todo.Maui.exe`（快捷方式/安装后启动均指向该文件）
- 发布产物默认使用静态资源：`src/Hua.Todo.Maui/appsettings.json` 中 `WebServer.IsUsingStatic=true`
- 前端构建产物会输出到 `src/Hua.Todo.Maui/wwwroot`，并随 Windows 发布复制到发布目录（嵌入式服务器从 `AppContext.BaseDirectory/wwwroot` 提供静态文件）
+#### Windows 交付产物
+```powershell
+# 生成 Windows 安装包（Inno Setup）
+.\publish-windows.ps1
+```
+输出：`src/Hua.Todo.Maui/Output/Hua.Todo_Setup_vX.Y.Z.exe`

-### Linux 交付产物（v1.2.0）
-
- `.tar.gz` 发布脚本：`publish-linux.ps1`（或使用 `publish.ps1 -Linux`）
- Flatpak 基础结构（manifest/desktop entry/AppStream）：`pack/linux/`
+#### Linux 交付产物
+```powershell
+# 生成 Linux 发布包
+.\publish-linux.ps1
+```
+或使用统一发布脚本：
+```powershell
+# 默认发布 Windows + Linux
+.\publish.ps1
+# 仅发布 Windows
+.\publish.ps1 -Windows
+```

 ### 使用说明
- **添加任务**：在前端界面中输入任务内容，设置优先级，点击添加按钮
+- **添加任务**：在前端界面输入任务内容，设置优先级，点击添加按钮
 - **管理任务**：查看任务列表，支持按状态过滤（全部/进行中/已完成）
 - **完成任务**：点击任务前的复选框切换完成状态
 - **删除任务**：点击删除按钮移除任务
@@ -86,31 +90,70 @@ Hua.Todo/
 ├── src/                           # 源代码目录
 │   ├── Hua.Todo.Core/              # 领域实体与基础接口
 │   ├── Hua.Todo.Application/       # 业务逻辑与应用层实现
+│   │   ├── CloudSync/             # 云同步模块
+│   │   ├── Data/                  # 数据访问层
+│   │   └── DynamicApi/            # 动态 API 生成
 │   ├── Hua.Todo.Host/              # 后端 API 宿主项目 (Kestrel)
 │   ├── Hua.Todo.Web/               # 前端 Web 项目 (Vue.js 3 + Vite)
-│   ├── Hua.Todo.Maui/              # 跨平台客户端项目 (Windows/Android/iOS/macOS)
-│   ├── Hua.Todo.Avalonia/           # 桌面客户端项目 (Windows/macOS/Linux)
-│   └── Hua.Todo.slnx           # 解决方案文件
+│   ├── Hua.Todo.Maui/              # 跨平台客户端 (Windows/Android/iOS/macOS)
+│   └── Hua.Todo.Avalonia/          # 桌面客户端 (Windows/macOS/Linux)
 ├── .gitignore                     # Git 忽略文件
 └── README.md                      # 项目说明文档
 ```

+### 技术栈
+
+| 分类 | 技术 |
+|------|------|
+| 后端语言 | C# 13 (.NET 10) |
+| UI 框架 | MAUI + Avalonia |
+| 服务器 | Kestrel (ASP.NET Core) |
+| 数据访问 | Entity Framework Core 10 |
+| 数据库 | SQLite |
+| 前端框架 | Vue.js 3 + TypeScript |
+| 构建工具 | Vite 5+ |
+| HTTP 客户端 | Axios |
+
 ### API 端点
- `GET /api/task` - 获取任务列表（默认：全部）
- `GET /api/task/active` - 获取未完成任务
- `GET /api/task/completed` - 获取已完成任务
- `GET /api/task/{id}` - 获取单个任务
- `POST /api/task` - 创建任务
- `PUT /api/task` - 更新任务（通过 Body 内的 id 定位）
- `PATCH /api/task/{id}/toggle` - 切换完成状态
- `DELETE /api/task/{id}` - 删除任务
- `GET /api/task/{parentTaskId}/subtasks` - 获取子任务列表
+
+#### 任务管理
+| 方法 | 端点 | 说明 |
+|------|------|------|
+| GET | `/api/task` | 获取任务列表（默认：全部） |
+| GET | `/api/task/active` | 获取未完成任务 |
+| GET | `/api/task/completed` | 获取已完成任务 |
+| GET | `/api/task/{id}` | 获取单个任务 |
+| POST | `/api/task` | 创建任务 |
+| PUT | `/api/task` | 更新任务（通过 Body 内的 id 定位） |
+| PATCH | `/api/task/{id}/toggle` | 切换完成状态 |
+| DELETE | `/api/task/{id}` | 删除任务 |
+| GET | `/api/task/{parentTaskId}/subtasks` | 获取子任务列表 |
+
+#### 云同步（Host 模式）
+| 方法 | 端点 | 说明 |
+|------|------|------|
+| POST | `/auth/bootstrap` | 初始化管理员（仅首次） |
+| POST | `/auth/login` | 用户登录 |
+| POST | `/auth/step-up` | 二次验证（提升权限） |
+| GET | `/tasks/` | 获取云端任务（只读） |
+| POST | `/sync/` | 推送/拉取合并同步 |
+| GET | `/security/policy` | 获取安全策略 |
+| PUT | `/security/policy` | 更新安全策略 |
+
+## 📊 模块说明
+
+- **Hua.Todo.Core**：领域实体层，定义核心实体、枚举及仓储接口
+- **Hua.Todo.Application**：应用层，包含业务逻辑、动态 API 生成、云同步服务
+- **Hua.Todo.Host**：后端 API 宿主，提供独立运行时环境
+- **Hua.Todo.Web**：前端 Web 项目，基于 Vue.js 3 + TypeScript + Vite
+- **Hua.Todo.Maui**：跨平台客户端，支持 Windows、Android、iOS 和 macOS
+- **Hua.Todo.Avalonia**：桌面客户端，专注 Linux 平台支持，同时兼容 Windows/macOS

 ## 🤝 交流与贡献

 - **QQ 交流群**：2167048911 (Hua.Todo 交流群)
 - **项目地址**：[Hua.Todo](https://git.we965.cn/Tools/Hua.Todo)
- **贡献指南**：欢迎提交 Pull Request，详见 [其他信息](docs/manual/其他信息.md)
+- **贡献指南**：欢迎提交 Pull Request

 ## 📄 开源协议

@@ -123,12 +166,14 @@ Hua.Todo/
 - [版本更新历史](docs/manual/版本记录.md)
 - [技术设计文档](docs/manual/技术设计文档.md)
 - [代码规范文档](docs/manual/代码规范文档.md)
- [其他信息 (贡献、许可证、联系方式)](docs/manual/其他信息.md)
+- [部署文档](docs/manual/部署文档.md)
+- [其他信息](docs/manual/其他信息.md)

 ### 项目进度与需求
 - [产品需求文档](docs/project/产品需求文档.md)
- [Android 离线排查计划](docs/project/Android_NotFound_排查计划.md)
+- [v1.2.0 任务清单](docs/project/v1.2.0-tasks/00-任务总览.md)
 - [实现对比文档](docs/project/实现对比文档.md)

 ---
-**Hua.Todo** - 跨平台任务管理，让效率无处不在！
+
+**Hua.Todo** - 跨平台任务管理，让效率无处不在！