Hua.Todo/README.md

Hua.Todo 跨平台代办管理应用 v1.2.8

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

🚀 功能特点

核心功能

• 跨平台支持：基于 MAUI + Avalonia + WebView 架构，覆盖 Windows、macOS、Android、iOS 和 Linux 五大平台
• 任务管理：支持任务创建、编辑、删除、完成状态切换，以及子任务管理
• 任务排序：支持按创建时间、完成时间、优先级排序，可切换升序/降序
• 云同步 (CloudSync)：支持手动配置服务端地址并登录后拉取/推送云端任务，支持安全策略配置（内存模式、同步开关、二次认证、受信任设备限制）
• 用户管理与权限：支持多用户管理、RBAC 细粒度权限控制（6 个权限点）、管理员密码加盐存储、首次登录强制修改密码
• 审计日志：记录所有安全事件（登录/注销/密码修改/引导等），支持管理员查询
• 会话管理：Bearer Token 认证，支持二次认证（step-up）提升权限，Token 即时失效
• 关键词检索：支持按任务标题实时过滤，支持 Esc 清空，大小写不敏感
• 本地数据持久化：使用 SQLite 数据库保存数据（WAL 模式优化），支持 DateTime 兼容性解析
• 离线模式：支持完全离线使用，数据优先保存于本地；安全策略禁止时可切换为内存模式不落盘
• 动态 API：后端自动生成 RESTful API 并集成 Swagger UI，便于联调与调试
• 全局快捷键：支持系统级快捷键快速唤起应用，修饰键与主键均可配置
• 系统托盘：支持最小化到系统托盘，关闭窗口隐藏到托盘，托盘菜单快捷操作

📦 安装与使用

环境要求

• 后端：.NET 10 SDK + Visual Studio 2022 或更高版本
• 前端：Node.js 18+ + npm 或 yarn

快速开始

1. 克隆项目

git clone <仓库地址>
cd Hua.Todo

2. 启动后端 API

cd src/Hua.Todo.Host
dotnet restore
dotnet run

API 将在 http://localhost:5173 启动
开发环境下提供 Swagger UI：http://localhost:5173/swagger

3. 启动前端 Web

cd src/Hua.Todo.Web
npm install
npm run dev

前端将在 http://localhost:5174 启动，并自动代理 /api 请求到后端

4. 启动 MAUI 客户端（Windows 三件套开发）

推荐使用脚本一键启动：

.\start-dev.ps1

构建与发布

Windows 交付产物

# 生成 Windows 安装包（Inno Setup）
.\publish-windows.ps1

输出：src/Hua.Todo.Maui/Output/Hua.Todo_Setup_vX.Y.Z.exe

Linux 交付产物

# 生成 Linux 发布包
.\publish-linux.ps1

或使用统一发布脚本：

# 默认发布 Windows + Linux
.\publish.ps1
# 仅发布 Windows
.\publish.ps1 -Windows

使用说明

• 添加任务：在前端界面输入任务内容，设置优先级，点击添加按钮
• 管理任务：查看任务列表，支持按状态过滤（全部/进行中/已完成）
• 完成任务：点击任务前的复选框切换完成状态
• 删除任务：点击删除按钮移除任务

🔧 开发指南

项目结构

Hua.Todo/
├── pack/                          # 打包与交付产物（Linux/安装包等）
├── docs/                          # 文档目录
│   ├── manual/                    # 用户/开发者手册
│   └── project/                   # 项目进度/需求文档
├── 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)
├── .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	获取子任务列表

云同步（Host 模式）

方法	端点	说明
POST	/auth/bootstrap	初始化管理员（仅首次）
POST	/auth/login	用户登录
POST	/auth/logout	用户注销
POST	/auth/step-up	二次验证（提升权限）
POST	/auth/change-password	修改密码
GET	/tasks/	获取云端任务（只读）
POST	/sync/	推送/拉取合并同步
GET	/security/policy	获取安全策略
PUT	/security/policy	更新安全策略
POST	/cloud-sync/probe	服务端可达性探测
GET	/admin/users	获取用户列表
POST	/admin/users	创建用户
POST	/admin/users/{userId}/reset-password	重置用户密码
DELETE	/admin/users/{userId}	删除用户
GET	/admin/sessions	获取活跃会话列表
DELETE	/admin/sessions/{sessionId}	强制终止会话
GET	/admin/audit-logs	获取审计日志
GET	/admin	管理后台入口

📊 模块说明

• 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
• 贡献指南：欢迎提交 Pull Request

📄 开源协议

本项目采用 AGPL-3.0 许可证。详细内容请参阅 LICENSE 文件。

📚 更多文档

用户与开发者手册

• 技术栈与模块说明
• 版本更新历史
• 技术设计文档
• 代码规范文档
• 部署文档
• 其他信息

项目进度与需求

• 产品需求文档
• v1.2.0 研发工单总览
• 实现对比文档

---

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