Hua/Hua.Todo
1
0
Fork 0
Code Issues Wiki Activity
Files
d81aa06681d233a09ae22979f3b38ba28df23ed1
Hua.Todo/README.md
T
ShaoHua d81aa06681 refactor: 重构文档结构与环境配置，统一研发工单命名 
1. 更新 .env 配置文件，替换原有云同步变量为 API 目标配置
2. 调整 publish-linux.ps1 中的文档路径，使用研发工单目录
3. 重构项目文档目录：将原 v1.2.0-tasks 迁移为研发工单-v1.2.0 目录，统一术语为"研发工单"替代"任务"
4. 更新 README.md 与各 PRD 文档的术语对照表，明确业务实体与研发工作项的区分
5. 新增多个研发工单文档，覆盖搜索、云同步、Linux 打包等模块
6. 删除旧的任务拆分文档，统一使用新的研发工单体系
2026-06-14 00:58:26 +08:00

196 lines
7.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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. 克隆项目
```bash
git clone <仓库地址>
cd Hua.Todo
```
#### 2. 启动后端 API
```bash
cd src/Hua.Todo.Host
dotnet restore
dotnet run
```
API 将在 `http://localhost:5173` 启动
开发环境下提供 Swagger UI：`http://localhost:5173/swagger`
#### 3. 启动前端 Web
```bash
cd src/Hua.Todo.Web
npm install
npm run dev
```
前端将在 `http://localhost:5174` 启动，并自动代理 `/api` 请求到后端
#### 4. 启动 MAUI 客户端（Windows 三件套开发）
推荐使用脚本一键启动：
```powershell
.\start-dev.ps1
```
### 构建与发布
#### Windows 交付产物
```powershell
# 生成 Windows 安装包（Inno Setup）
.\publish-windows.ps1
```
输出：`src/Hua.Todo.Maui/Output/Hua.Todo_Setup_vX.Y.Z.exe`
#### Linux 交付产物
```powershell
# 生成 Linux 发布包
.\publish-linux.ps1
```
或使用统一发布脚本：
```powershell
# 默认发布 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](https://git.we965.cn/Tools/Hua.Todo)
- **贡献指南**：欢迎提交 Pull Request
## 📄 开源协议
本项目采用 **AGPL-3.0** 许可证。详细内容请参阅 [LICENSE](LICENSE) 文件。
## 📚 更多文档
### 用户与开发者手册
- [技术栈与模块说明](docs/manual/技术栈与模块.md)
- [版本更新历史](docs/manual/版本记录.md)
- [技术设计文档](docs/manual/技术设计文档.md)
- [代码规范文档](docs/manual/代码规范文档.md)
- [部署文档](docs/manual/部署文档.md)
- [其他信息](docs/manual/其他信息.md)
### 项目进度与需求
- [产品需求文档](docs/project/产品需求文档.md)
- [v1.2.0 研发工单总览](docs/project/研发工单-v1.2.0/00-工单总览.md)
- [实现对比文档](docs/project/实现对比文档.md)
---
**Hua.Todo** - 跨平台任务管理，让效率无处不在！
Reference in New Issue View Git Blame Copy Permalink