docs: 重组 docs/manual/ 指南结构，区分普通用户与开发者双入口
- 新增 00-目录与导读.md 双入口导航 - 用户面(01-04)：项目介绍、安装指南、版本记录、其他信息 - 开发者面(05-10)：技术栈、构建、架构、云同步、代码规范、MCP - 拆分旧01为 01(用户)+05(开发者)；旧02为 02(用户)+06(开发者) - 合并旧08+09 MCP文档为 10-MCP服务集成 - 同步更新 README.md 与 .trae/rules/项目/ 交叉引用
This commit is contained in:
ShaoHua
@@ -3,7 +3,7 @@
|
|||||||
> 适用范围：本规则属于 **项目规则**（仅 Hua.Todo 项目生效）。
|
> 适用范围：本规则属于 **项目规则**（仅 Hua.Todo 项目生效）。
|
||||||
>
|
>
|
||||||
> 描述当前仓库的项目划分、依赖方向、运行模式与跨平台策略，供智能体在做改动时快速对齐架构边界。
|
> 描述当前仓库的项目划分、依赖方向、运行模式与跨平台策略，供智能体在做改动时快速对齐架构边界。
|
||||||
> 完整设计参见 [docs/manual/01-技术设计文档.md](../../../docs/manual/01-技术设计文档.md) 与 [docs/manual/03-技术栈与模块.md](../../../docs/manual/03-技术栈与模块.md)。
|
> 完整设计参见 [docs/manual/05-技术栈与项目结构.md](../../../docs/manual/05-技术栈与项目结构.md) 与 [docs/manual/07-技术架构设计.md](../../../docs/manual/07-技术架构设计.md)。
|
||||||
|
|
||||||
## 一、项目清单（src/）
|
## 一、项目清单（src/）
|
||||||
|
|
||||||
|
|||||||
@@ -31,7 +31,7 @@
|
|||||||
### 2.3 HTTP API 路由
|
### 2.3 HTTP API 路由
|
||||||
- 本地动态 API：`/api/task`、`/api/task/{parentTaskId}/subtasks`（由 `Hua.Todo.Application/DynamicApi` 自动暴露）
|
- 本地动态 API：`/api/task`、`/api/task/{parentTaskId}/subtasks`（由 `Hua.Todo.Application/DynamicApi` 自动暴露）
|
||||||
- 云端：`GET /tasks`、`POST /sync`、`POST /cloud-sync/probe`
|
- 云端：`GET /tasks`、`POST /sync`、`POST /cloud-sync/probe`
|
||||||
- 见 [docs/manual/01-技术设计文档.md](../../../docs/manual/01-技术设计文档.md)、[docs/project/研发工单-v1.2.0/04-CloudSync-服务端基础能力.md](../../../docs/project/研发工单-v1.2.0/04-CloudSync-服务端基础能力.md)
|
- 见 [docs/manual/05-技术栈与项目结构.md](../../../docs/manual/05-技术栈与项目结构.md)、[docs/project/研发工单-v1.2.0/04-CloudSync-服务端基础能力.md](../../../docs/project/研发工单-v1.2.0/04-CloudSync-服务端基础能力.md)
|
||||||
|
|
||||||
### 2.4 数据库表
|
### 2.4 数据库表
|
||||||
- `Tasks`、`Users`、`UserSessions`、`SecurityPolicies`、`AuditLogs`
|
- `Tasks`、`Users`、`UserSessions`、`SecurityPolicies`、`AuditLogs`
|
||||||
|
|||||||
@@ -94,6 +94,6 @@
|
|||||||
|
|
||||||
1. [ ] 是否新增了 EF Core 迁移（而非手改快照）？
|
1. [ ] 是否新增了 EF Core 迁移（而非手改快照）？
|
||||||
2. [ ] 迁移名称是否以 `AddXxx`/`UpdateXxx`/`RemoveXxx` 开头？
|
2. [ ] 迁移名称是否以 `AddXxx`/`UpdateXxx`/`RemoveXxx` 开头？
|
||||||
3. [ ] 是否在 [docs/manual/01-技术设计文档.md](../../../docs/manual/01-技术设计文档.md) 中同步更新数据模型描述？
|
3. [ ] 是否在 [docs/manual/07-技术架构设计.md](../../../docs/manual/07-技术架构设计.md) 中同步更新数据模型描述？
|
||||||
4. [ ] 是否在 [docs/manual/06-版本记录.md](../../../docs/manual/06-版本记录.md) 中追加非琐碎变更条目？
|
4. [ ] 是否在 [docs/manual/03-版本记录.md](../../../docs/manual/03-版本记录.md) 中追加非琐碎变更条目？
|
||||||
5. [ ] 是否在嵌入式宿主上验证了启动时 Migrate 不报错？
|
5. [ ] 是否在嵌入式宿主上验证了启动时 Migrate 不报错？
|
||||||
|
|||||||
@@ -37,7 +37,7 @@
|
|||||||
| 子工单 | 实现状态 | 验证状态 | 简要说明 |
|
| 子工单 | 实现状态 | 验证状态 | 简要说明 |
|
||||||
|---|---|---|---|
|
|---|---|---|---|
|
||||||
| 01 - HTTP 服务转换 MCP 服务 | 进行中 | 待验证 | 将现有 HTTP API 映射为 MCP 工具描述符 |
|
| 01 - HTTP 服务转换 MCP 服务 | 进行中 | 待验证 | 将现有 HTTP API 映射为 MCP 工具描述符 |
|
||||||
| 02 - 语音控制与 AI 辅助 | 待开始 | 待验证 | STT/TTS + 语音指令解析 + AI 辅助任务拆分 |
|
| 02 - 语音控制与 AI 辅助 | 已完成（核心基础设施） | 待验证 | Core 接口（IVoiceInputService/IVoiceOutputService/IVoiceIntentParser）、VoiceIntent 枚举与 DTO、LLM 客户端（LlmClientService）、双策略意图解析器（LlmIntentParser + RuleIntentParser + HybridVoiceIntentParser）、VoiceCommandExecutor、AiBreakdownService、VoiceService（Dynamic API）、DI 注册；26 个单元测试通过；平台 STT/TTS 实现待补 |
|
||||||
| 03 - 会议任务拆分 | 待开始 | 待验证 | 会议类型入口 + 录音/文字输入 + AI 拆分建议 + 确认批量创建 |
|
| 03 - 会议任务拆分 | 待开始 | 待验证 | 会议类型入口 + 录音/文字输入 + AI 拆分建议 + 确认批量创建 |
|
||||||
| 03-01 - 会议数据模型与 API | 待开始 | 待验证 | TaskType 枚举、MeetingNotes/AudioDuration 字段、MeetingController |
|
| 03-01 - 会议数据模型与 API | 待开始 | 待验证 | TaskType 枚举、MeetingNotes/AudioDuration 字段、MeetingController |
|
||||||
| 03-02 - 音频录制与转写 | 待开始 | 待验证 | 前端 MediaRecorder 录音 + 后端 STT 转写 |
|
| 03-02 - 音频录制与转写 | 待开始 | 待验证 | 前端 MediaRecorder 录音 + 后端 STT 转写 |
|
||||||
@@ -60,6 +60,8 @@
|
|||||||
- [ ] Linux Flatpak/AppImage 自包含产物在干净环境的实测验证（v1.2.0 验收 Linux 部分仍为"待验证"）
|
- [ ] Linux Flatpak/AppImage 自包含产物在干净环境的实测验证（v1.2.0 验收 Linux 部分仍为"待验证"）
|
||||||
- [x] CloudSync UNIQUE 约束修复（2026-06-14）：修复了 `existingTasks` 查询在事务外导致并发重同步时 `T_Tasks.Id` UNIQUE 约束冲突；新增 7 个测试（含 5 个 SQLite 集成测试）
|
- [x] CloudSync UNIQUE 约束修复（2026-06-14）：修复了 `existingTasks` 查询在事务外导致并发重同步时 `T_Tasks.Id` UNIQUE 约束冲突；新增 7 个测试（含 5 个 SQLite 集成测试）
|
||||||
|
|
||||||
|
- [x] v1.3.0 工单01 - MCP 服务转换已完成（2026-06-16）：DynamicMcpToolExtensions 自动扫描所有 IDynamicApiService 接口并生成 MCP 工具；当前覆盖 ITaskService（9 个工具）+ IVoiceService（4 个工具）= 13 个 MCP 工具；新增 4 个测试（描述验证、InputSchema 验证、服务调用、工具调用端到端），共计 17 个测试全部通过；CloudSync 服务因未实现 IDynamicApiService 暂未覆盖，记录为已知缺口
|
||||||
|
|
||||||
## 六、最近一次重大重构（如有）
|
## 六、最近一次重大重构（如有）
|
||||||
|
|
||||||
- **术语统一与目录中文化**（2026-06）：
|
- **术语统一与目录中文化**（2026-06）：
|
||||||
@@ -70,6 +72,11 @@
|
|||||||
- **`.trae` 子目录文件序号化**（2026-06）：
|
- **`.trae` 子目录文件序号化**（2026-06）：
|
||||||
- `.trae/rules/全局/`、`.trae/rules/项目/`、`.trae/coordination/`、`.trae/memory/` 下所有文件加 `NN-` 序号前缀
|
- `.trae/rules/全局/`、`.trae/rules/项目/`、`.trae/coordination/`、`.trae/memory/` 下所有文件加 `NN-` 序号前缀
|
||||||
- `.trae/索引.md` 不带序号（入口文件）
|
- `.trae/索引.md` 不带序号（入口文件）
|
||||||
|
- **`docs/manual/` 指南重组**（2026-06-16）：
|
||||||
|
- 新增 `00-目录与导读.md` 双入口导航（普通用户 / 开发者）
|
||||||
|
- 拆分用户面与开发者面：01-02 为用户安装使用；05-10 为开发者架构/构建/规范
|
||||||
|
- 合并重叠与过时内容，精简用户文档篇幅
|
||||||
|
- 同步更新 README.md 与 `.trae/rules/项目/` 中的交叉引用
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|||||||
@@ -83,7 +83,7 @@ Hua.Todo/
|
|||||||
|
|
||||||
- **QQ 交流群**：2167048911 (Hua.Todo 交流群)
|
- **QQ 交流群**：2167048911 (Hua.Todo 交流群)
|
||||||
- **项目地址**：[Hua.Todo](https://git.we965.cn/Tools/Hua.Todo)
|
- **项目地址**：[Hua.Todo](https://git.we965.cn/Tools/Hua.Todo)
|
||||||
- **贡献指南**：欢迎提交 Pull Request，详见 [其他信息](docs/manual/其他信息.md)
|
- **贡献指南**：欢迎提交 Pull Request，详见 [其他信息](docs/manual/04-其他信息.md)
|
||||||
|
|
||||||
## 📄 开源协议
|
## 📄 开源协议
|
||||||
|
|
||||||
@@ -91,12 +91,20 @@ Hua.Todo/
|
|||||||
|
|
||||||
## 📚 更多文档
|
## 📚 更多文档
|
||||||
|
|
||||||
### 用户与开发者手册
|
### 普通用户
|
||||||
- [技术栈与模块说明](docs/manual/技术栈与模块.md)
|
- [00-目录与导读](docs/manual/00-目录与导读.md) — 文档入口
|
||||||
- [版本更新历史](docs/manual/版本记录.md)
|
- [01-项目介绍](docs/manual/01-项目介绍.md)
|
||||||
- [技术设计文档](docs/manual/技术设计文档.md)
|
- [02-安装指南](docs/manual/02-安装指南.md)
|
||||||
- [代码规范文档](docs/manual/代码规范文档.md)
|
- [03-版本记录](docs/manual/03-版本记录.md)
|
||||||
- [其他信息 (贡献、许可证、联系方式)](docs/manual/其他信息.md)
|
- [04-其他信息](docs/manual/04-其他信息.md)
|
||||||
|
|
||||||
|
### 开发者
|
||||||
|
- [05-技术栈与项目结构](docs/manual/05-技术栈与项目结构.md)
|
||||||
|
- [06-开发环境与构建](docs/manual/06-开发环境与构建.md)
|
||||||
|
- [07-技术架构设计](docs/manual/07-技术架构设计.md)
|
||||||
|
- [08-云同步规则](docs/manual/08-云同步规则.md)
|
||||||
|
- [09-代码规范](docs/manual/09-代码规范.md)
|
||||||
|
- [10-MCP服务集成](docs/manual/10-MCP服务集成.md)
|
||||||
|
|
||||||
### 项目进度与需求
|
### 项目进度与需求
|
||||||
- [产品需求文档](docs/project/产品需求文档.md)
|
- [产品需求文档](docs/project/产品需求文档.md)
|
||||||
|
|||||||
@@ -0,0 +1,44 @@
|
|||||||
|
# Hua.Todo 文档指南
|
||||||
|
|
||||||
|
> 本文档是 Hua.Todo 项目手册的入口。根据您的身份选择对应的阅读路线。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 我是普通用户
|
||||||
|
|
||||||
|
只想安装和使用 Hua.Todo？从这里开始：
|
||||||
|
|
||||||
|
| 序号 | 文档 | 内容 |
|
||||||
|
|---|---|---|
|
||||||
|
| 01 | [项目介绍](./01-项目介绍.md) | 这是什么、能做什么、支持哪些平台 |
|
||||||
|
| 02 | [安装指南](./02-安装指南.md) | 如何安装、配置云同步、常见问题 |
|
||||||
|
| 03 | [版本记录](./03-版本记录.md) | 更新了哪些内容 |
|
||||||
|
| 04 | [其他信息](./04-其他信息.md) | 贡献指南、许可证、联系方式 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 我是开发者
|
||||||
|
|
||||||
|
需要编译源码、了解架构或参与开发？从这里开始：
|
||||||
|
|
||||||
|
| 序号 | 文档 | 内容 |
|
||||||
|
|---|---|---|
|
||||||
|
| 05 | [技术栈与项目结构](./05-技术栈与项目结构.md) | 用了哪些技术、项目如何划分、依赖关系 |
|
||||||
|
| 06 | [开发环境与构建](./06-开发环境与构建.md) | 如何搭建环境、构建、部署服务端 |
|
||||||
|
| 07 | [技术架构设计](./07-技术架构设计.md) | 目录结构、API 设计、数据库、通信机制 |
|
||||||
|
| 08 | [云同步规则](./08-云同步规则.md) | 认证鉴权、同步工作流、安全策略 |
|
||||||
|
| 09 | [代码规范](./09-代码规范.md) | C# / TypeScript / Vue 编码规范 |
|
||||||
|
| 10 | [MCP服务集成](./10-MCP服务集成.md) | MCP 接口规范与前端集成 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 项目简介
|
||||||
|
|
||||||
|
Hua.Todo 是一个跨平台待办事项管理工具，支持：
|
||||||
|
|
||||||
|
- **多平台**：Windows / macOS / Linux / Android / iOS
|
||||||
|
- **云同步**：多端数据同步，安全可控
|
||||||
|
- **语音控制**：语音指令操作待办项
|
||||||
|
- **AI 辅助**：通过 MCP 协议接入 AI 客户端
|
||||||
|
|
||||||
|
> 源码仓库：[https://git.we965.cn/Tools/Hua.Todo](https://git.we965.cn/Tools/Hua.Todo)
|
||||||
@@ -1,414 +0,0 @@
|
|||||||
# Hua.Todo 技术设计文档 v1.1.0
|
|
||||||
|
|
||||||
## 1. 项目概述
|
|
||||||
本文档描述 Hua.Todo v1.1.0 的技术设计方案，包括项目文件目录结构、模块划分、技术选型和实现细节。
|
|
||||||
|
|
||||||
## 2. 技术栈
|
|
||||||
|
|
||||||
### 2.1 后端技术栈
|
|
||||||
- **开发语言**: C# 10
|
|
||||||
- **框架**: .NET 10
|
|
||||||
- **UI 框架**: MAUI (Multi-platform App UI) + Avalonia (Linux 支持)
|
|
||||||
- **Web 服务器**: Kestrel (ASP.NET Core 内置)
|
|
||||||
- **API 框架**: ASP.NET Core Web API
|
|
||||||
- **数据访问**: Entity Framework Core
|
|
||||||
- **数据库**: SQLite (本地存储)
|
|
||||||
- **日志**: Serilog
|
|
||||||
- **依赖注入**: Microsoft.Extensions.DependencyInjection
|
|
||||||
|
|
||||||
### 2.2 前端技术栈
|
|
||||||
- **开发语言**: JavaScript/TypeScript
|
|
||||||
- **框架**: Vue.js 3
|
|
||||||
- **构建工具**: Vite
|
|
||||||
- **HTTP 客户端**: Axios
|
|
||||||
- **状态管理**: Pinia
|
|
||||||
- **UI 组件库**: Element Plus / Vant (移动端)
|
|
||||||
- **CSS 预处理器**: SCSS
|
|
||||||
|
|
||||||
## 3. 项目目录结构
|
|
||||||
|
|
||||||
```
|
|
||||||
Hua.Todo/
|
|
||||||
├── docs/ # 文档目录
|
|
||||||
│ ├── manual/ # 用户/开发者手册
|
|
||||||
│ │ ├── 03-技术栈与模块.md
|
|
||||||
│ │ ├── 06-版本记录.md
|
|
||||||
│ │ ├── 01-技术设计文档.md（本文件）
|
|
||||||
│ │ ├── 04-代码规范文档.md
|
|
||||||
│ │ └── 05-部署文档.md
|
|
||||||
│ └── project/ # 项目进度/需求文档
|
|
||||||
│ ├── 产品需求文档.md
|
|
||||||
│ └── ...
|
|
||||||
│
|
|
||||||
├── src/ # 源代码目录
|
|
||||||
│ ├── Hua.Todo.Maui/ # MAUI 主项目（跨平台入口）
|
|
||||||
│ │ ├── Platforms/ # 平台特定代码
|
|
||||||
│ │ │ ├── Windows/ # Windows 平台代码
|
|
||||||
│ │ │ │ ├── App.xaml # Windows 应用入口
|
|
||||||
│ │ │ │ └── Services/ # Windows 平台服务
|
|
||||||
│ │ │ │ └── HotKeyService.cs
|
|
||||||
│ │ │ ├── MacCatalyst/ # macOS 平台代码
|
|
||||||
│ │ │ │ ├── App.xaml
|
|
||||||
│ │ │ │ └── Services/
|
|
||||||
│ │ │ │ └── HotKeyService.cs
|
|
||||||
│ │ │ ├── Android/ # Android 平台代码
|
|
||||||
│ │ │ │ ├── MainActivity.cs
|
|
||||||
│ │ │ │ └── Services/
|
|
||||||
│ │ │ │ └── NotificationService.cs
|
|
||||||
│ │ │ └── iOS/ # iOS 平台代码
|
|
||||||
│ │ │ ├── AppDelegate.cs
|
|
||||||
│ │ │ └── Services/
|
|
||||||
│ │ │ └── NotificationService.cs
|
|
||||||
│ │ ├── Resources/ # 资源文件
|
|
||||||
│ │ │ ├── Images/ # 图片资源
|
|
||||||
│ │ │ ├── Styles/ # 样式资源
|
|
||||||
│ │ │ └── Fonts/ # 字体资源
|
|
||||||
│ │ ├── Controls/ # 自定义控件
|
|
||||||
│ │ │ └── WebViewContainer.xaml
|
|
||||||
│ │ ├── Services/ # 服务层
|
|
||||||
│ │ │ ├── IHotKeyService.cs
|
|
||||||
│ │ │ ├── IPlatformService.cs
|
|
||||||
│ │ │ └── AppLifecycleService.cs
|
|
||||||
│ │ ├── App.xaml # MAUI 应用入口
|
|
||||||
│ │ ├── App.xaml.cs
|
|
||||||
│ │ ├── MauiProgram.cs # MAUI 程序配置
|
|
||||||
│ │ └── Hua.Todo.Maui.csproj # MAUI 项目文件
|
|
||||||
│ │
|
|
||||||
│ ├── Hua.Todo.Avalonia/ # Avalonia 项目（Linux 支持）
|
|
||||||
│ │ ├── Assets/ # 资源文件
|
|
||||||
│ │ │ └── icon.ico # 应用图标
|
|
||||||
│ │ ├── Services/ # 服务层
|
|
||||||
│ │ │ ├── EmbeddedWebServerServiceFactory.cs
|
|
||||||
│ │ │ ├── GlobalHotKeyServiceFactory.cs
|
|
||||||
│ │ │ ├── NoopEmbeddedWebServerService.cs
|
|
||||||
│ │ │ └── Platforms/ # 平台特定服务
|
|
||||||
│ │ │ ├── AndroidGlobalHotKeyService.cs
|
|
||||||
│ │ │ └── LinuxGlobalHotKeyService.cs
|
|
||||||
│ │ ├── Views/ # 视图
|
|
||||||
│ │ │ ├── MainView.axaml
|
|
||||||
│ │ │ ├── MainView.axaml.cs
|
|
||||||
│ │ │ ├── MainWindow.axaml
|
|
||||||
│ │ │ └── MainWindow.axaml.cs
|
|
||||||
│ │ ├── App.axaml # Avalonia 应用入口
|
|
||||||
│ │ ├── App.axaml.cs
|
|
||||||
│ │ ├── Program.cs # Avalonia 程序配置
|
|
||||||
│ │ ├── appsettings.json # 配置文件
|
|
||||||
│ │ ├── setup.iss # 安装脚本
|
|
||||||
│ │ ├── wwwroot/ # 前端静态资源
|
|
||||||
│ │ └── Hua.Todo.Avalonia.csproj # Avalonia 项目文件
|
|
||||||
│ │
|
|
||||||
│ ├── Hua.Todo.Host/ # 后端 API 项目
|
|
||||||
│ │ ├── Controllers/ # API 控制器
|
|
||||||
│ │ │ ├── TasksController.cs
|
|
||||||
│ │ │ ├── SettingsController.cs
|
|
||||||
│ │ │ └── SyncController.cs
|
|
||||||
│ │ ├── Models/ # 数据模型
|
|
||||||
│ │ │ ├── Task.cs
|
|
||||||
│ │ │ ├── TaskDto.cs
|
|
||||||
│ │ │ └── ApiResponse.cs
|
|
||||||
│ │ ├── Services/ # 业务服务
|
|
||||||
│ │ │ ├── ITaskService.cs
|
|
||||||
│ │ │ ├── TaskService.cs
|
|
||||||
│ │ │ ├── ISyncService.cs
|
|
||||||
│ │ │ └── SyncService.cs
|
|
||||||
│ │ ├── Data/ # 数据访问层
|
|
||||||
│ │ │ ├── TodoDbContext.cs
|
|
||||||
│ │ │ ├── Converters/ # 类型转换器
|
|
||||||
│ │ │ │ └── LenientUtcDateTimeStringConverter.cs
|
|
||||||
│ │ │ ├── Repositories/
|
|
||||||
│ │ │ │ ├── ITaskRepository.cs
|
|
||||||
│ │ │ │ └── TaskRepository.cs
|
|
||||||
│ │ │ └── Migrations/ # 数据库迁移
|
|
||||||
│ │ ├── Middleware/ # 中间件
|
|
||||||
│ │ │ └── ExceptionMiddleware.cs
|
|
||||||
│ │ ├── Extensions/ # 扩展方法
|
|
||||||
│ │ │ └── ServiceCollectionExtensions.cs
|
|
||||||
│ │ ├── Program.cs # API 入口
|
|
||||||
│ │ ├── appsettings.json # 配置文件
|
|
||||||
│ │ └── Hua.Todo.Host.csproj # Host 项目文件
|
|
||||||
│ │
|
|
||||||
│ ├── Hua.Todo.Application/ # 应用层
|
|
||||||
│ │ ├── Data/ # 数据访问
|
|
||||||
│ │ │ ├── TodoDbContext.cs
|
|
||||||
│ │ │ └── Converters/ # 类型转换器
|
|
||||||
│ │ │ └── LenientUtcDateTimeStringConverter.cs
|
|
||||||
│ │ └── Hua.Todo.Application.csproj # Application 项目文件
|
|
||||||
│ │
|
|
||||||
│ ├── Hua.Todo.Core/ # 核心业务逻辑层
|
|
||||||
│ │ ├── Entities/ # 实体类
|
|
||||||
│ │ │ ├── Task.cs
|
|
||||||
│ │ │ └── TaskPriority.cs
|
|
||||||
│ │ ├── Interfaces/ # 接口定义
|
|
||||||
│ │ │ ├── ITaskRepository.cs
|
|
||||||
│ │ │ └── IUnitOfWork.cs
|
|
||||||
│ │ ├── ValueObjects/ # 值对象
|
|
||||||
│ │ │ └── TaskTitle.cs
|
|
||||||
│ │ ├── Specifications/ # 规范模式
|
|
||||||
│ │ │ └── TaskSpecifications.cs
|
|
||||||
│ │ └── Hua.Todo.Core.csproj # Core 项目文件
|
|
||||||
│ │
|
|
||||||
│ ├── Hua.Todo.Web/ # 前端 Web 项目 (Vue.js)
|
|
||||||
│ │ ├── public/ # 静态资源
|
|
||||||
│ │ │ └── favicon.svg # 网站图标
|
|
||||||
│ │ ├── src/ # 源代码
|
|
||||||
│ │ │ ├── api/ # API 调用
|
|
||||||
│ │ │ │ ├── client.ts # HTTP 客户端配置
|
|
||||||
│ │ │ │ ├── tasks.ts # 任务相关 API
|
|
||||||
│ │ │ │ └── settings.ts # 设置相关 API
|
|
||||||
│ │ │ ├── assets/ # 资源文件
|
|
||||||
│ │ │ │ ├── images/
|
|
||||||
│ │ │ │ └── styles/
|
|
||||||
│ │ │ ├── components/ # Vue 组件
|
|
||||||
│ │ │ │ ├── TaskList.vue
|
|
||||||
│ │ │ │ ├── TaskItem.vue
|
|
||||||
│ │ │ │ ├── QuickEntry.vue
|
|
||||||
│ │ │ │ └── Settings.vue
|
|
||||||
│ │ │ ├── composables/ # 组合式函数
|
|
||||||
│ │ │ │ ├── useTasks.ts
|
|
||||||
│ │ │ │ └── useHotKey.ts
|
|
||||||
│ │ │ ├── stores/ # 状态管理 (Pinia)
|
|
||||||
│ │ │ │ ├── tasks.ts
|
|
||||||
│ │ │ │ └── settings.ts
|
|
||||||
│ │ │ ├── types/ # TypeScript 类型定义
|
|
||||||
│ │ │ │ ├── task.ts
|
|
||||||
│ │ │ │ └── api.ts
|
|
||||||
│ │ │ ├── utils/ # 工具函数
|
|
||||||
│ │ │ │ ├── date.ts
|
|
||||||
│ │ │ │ └── storage.ts
|
|
||||||
│ │ │ ├── App.vue # 根组件
|
|
||||||
│ │ │ └── main.ts # 应用入口
|
|
||||||
│ │ ├── package.json # 依赖配置
|
|
||||||
│ │ ├── vite.config.ts # Vite 配置
|
|
||||||
│ │ ├── tsconfig.json # TypeScript 配置
|
|
||||||
│ │ └── index.html # HTML 模板
|
|
||||||
│ │
|
|
||||||
│ └── Hua.Todo.Tests/ # 测试项目
|
|
||||||
│ ├── Unit/ # 单元测试
|
|
||||||
│ │ ├── Services/
|
|
||||||
│ │ │ └── TaskServiceTests.cs
|
|
||||||
│ │ └── Controllers/
|
|
||||||
│ │ └── TasksControllerTests.cs
|
|
||||||
│ ├── Integration/ # 集成测试
|
|
||||||
│ │ └── ApiIntegrationTests.cs
|
|
||||||
│ └── Hua.Todo.Tests.csproj
|
|
||||||
│
|
|
||||||
├── .gitignore # Git 忽略文件
|
|
||||||
├── Hua.Todo.sln # 解决方案文件
|
|
||||||
└── README.md # 项目说明文档
|
|
||||||
```
|
|
||||||
|
|
||||||
## 4. 模块设计
|
|
||||||
|
|
||||||
### 4.1 MAUI 主项目 (Hua.Todo.Maui)
|
|
||||||
**职责**:
|
|
||||||
- 应用程序入口和生命周期管理
|
|
||||||
- 平台特定功能封装
|
|
||||||
- WebView 容器管理
|
|
||||||
- 本地 HTTP 服务器启动
|
|
||||||
|
|
||||||
**调试与接口文档**：
|
|
||||||
- Windows Debug 模式下，内嵌 WebServer 默认提供 Swagger UI（`{HostUrl}/swagger`）与 OpenAPI JSON（`{HostUrl}/swagger/v1/swagger.json`），用于本地接口联调。
|
|
||||||
|
|
||||||
**关键组件**:
|
|
||||||
- `MauiProgram.cs`: 配置 MAUI 应用和依赖注入
|
|
||||||
- `App.xaml.cs`: 应用程序主入口
|
|
||||||
- `WebViewContainer`: 封装 WebView 控件
|
|
||||||
- 平台特定服务: 快捷键、通知等
|
|
||||||
|
|
||||||
### 4.2 Avalonia 项目 (Hua.Todo.Avalonia)
|
|
||||||
**职责**:
|
|
||||||
- Linux 平台支持
|
|
||||||
- 桌面交互功能（托盘菜单、全局热键等）
|
|
||||||
- WebView 容器管理
|
|
||||||
- 本地 HTTP 服务器启动
|
|
||||||
|
|
||||||
**关键组件**:
|
|
||||||
- `Program.cs`: 配置 Avalonia 应用和依赖注入
|
|
||||||
- `App.axaml.cs`: 应用程序主入口
|
|
||||||
- `MainWindow.axaml.cs`: 主窗口管理
|
|
||||||
- `MainView.axaml.cs`: 主视图管理
|
|
||||||
- `GlobalHotKeyServiceFactory`: 全局热键服务工厂
|
|
||||||
- `EmbeddedWebServerServiceFactory`: 内嵌 Web 服务器服务工厂
|
|
||||||
- 平台特定服务: Linux 全局热键等
|
|
||||||
|
|
||||||
### 4.3 后端 API 项目 (Hua.Todo.Host)
|
|
||||||
**职责**:
|
|
||||||
- 提供 RESTful API 接口
|
|
||||||
- 业务逻辑处理
|
|
||||||
- 数据访问和持久化
|
|
||||||
- 本地 HTTP 服务器托管
|
|
||||||
|
|
||||||
**接口文档**：
|
|
||||||
- 开发环境（`ASPNETCORE_ENVIRONMENT=Development`）下提供 Swagger UI：`http://localhost:5173/swagger`（或 `https://localhost:7175/swagger`）。
|
|
||||||
|
|
||||||
**关键组件**:
|
|
||||||
- `CloudSync`: 云同步 Minimal APIs（`/auth`、`/tasks`、`/sync`、`/security`）
|
|
||||||
- `DynamicApiMiddleware`: 任务管理等业务接口通过 Dynamic API（`/api/{service}/...`）对外暴露
|
|
||||||
- `Data`: 数据访问层和数据库上下文
|
|
||||||
- `Program.cs`: API 服务器配置和启动
|
|
||||||
|
|
||||||
### 4.4 核心业务层 (Hua.Todo.Core)
|
|
||||||
**职责**:
|
|
||||||
- 定义领域模型和业务规则
|
|
||||||
- 提供核心业务接口
|
|
||||||
- 实现领域驱动设计模式
|
|
||||||
|
|
||||||
**关键组件**:
|
|
||||||
- `Entities`: 领域实体
|
|
||||||
- `Interfaces`: 业务接口定义
|
|
||||||
- `ValueObjects`: 值对象
|
|
||||||
- `Specifications`: 业务规范
|
|
||||||
|
|
||||||
### 4.5 前端 Web 项目 (Hua.Todo.Web)
|
|
||||||
**职责**:
|
|
||||||
- 用户界面展示
|
|
||||||
- 用户交互处理
|
|
||||||
- HTTP API 调用
|
|
||||||
- 状态管理
|
|
||||||
|
|
||||||
**关键组件**:
|
|
||||||
- `components`: Vue 组件
|
|
||||||
- `api`: API 调用封装
|
|
||||||
- `stores`: 状态管理
|
|
||||||
- `composables`: 组合式函数
|
|
||||||
|
|
||||||
## 5. HTTP API 设计
|
|
||||||
|
|
||||||
### 5.1 API 基础配置
|
|
||||||
- **基础 URL（开发三件套 / Host 模式）**: `http://localhost:5173/api`（或 `https://localhost:7175/api`）
|
|
||||||
- **基础 URL（MAUI 内嵌模式）**: `{HostUrl}/api`（`HostUrl` 来自 `appsettings.json: WebServer.HostUrl`，默认 `http://localhost:5057`）
|
|
||||||
- **数据格式**: JSON
|
|
||||||
- **认证方式**: 以实际端点为准（如云同步相关端点可能需要认证）
|
|
||||||
- **跨域配置**: 允许本地跨域请求
|
|
||||||
|
|
||||||
### 5.2 API 端点设计
|
|
||||||
|
|
||||||
#### 任务管理 API
|
|
||||||
```
|
|
||||||
GET /api/task # 获取任务列表（默认：全部）
|
|
||||||
GET /api/task/active # 获取未完成任务
|
|
||||||
GET /api/task/completed # 获取已完成任务
|
|
||||||
GET /api/task/{id} # 获取单个任务
|
|
||||||
POST /api/task # 创建任务
|
|
||||||
PUT /api/task # 更新任务（通过 Body 内的 id 定位）
|
|
||||||
DELETE /api/task/{id} # 删除任务
|
|
||||||
PATCH /api/task/{id}/toggle # 切换完成状态
|
|
||||||
GET /api/task/{parentTaskId}/subtasks # 获取子任务列表
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 云同步 API（Host 模式）
|
|
||||||
```
|
|
||||||
POST /auth/bootstrap # 初始化管理员（仅首次）
|
|
||||||
POST /auth/login # 登录
|
|
||||||
POST /auth/step-up # 二次验证（提升权限）
|
|
||||||
GET /tasks/ # 获取云端任务（只读）
|
|
||||||
POST /sync/ # 推送/拉取合并同步
|
|
||||||
GET /security/policy # 获取安全策略
|
|
||||||
PUT /security/policy # 更新安全策略
|
|
||||||
```
|
|
||||||
|
|
||||||
## 6. 数据库设计
|
|
||||||
|
|
||||||
### 6.1 数据库表结构
|
|
||||||
|
|
||||||
#### Tasks 表
|
|
||||||
```sql
|
|
||||||
CREATE TABLE Tasks (
|
|
||||||
Id INTEGER PRIMARY KEY AUTOINCREMENT,
|
|
||||||
Title TEXT NOT NULL,
|
|
||||||
Priority INTEGER NOT NULL DEFAULT 0,
|
|
||||||
IsCompleted INTEGER NOT NULL DEFAULT 0,
|
|
||||||
CreatedAt TEXT NOT NULL,
|
|
||||||
UpdatedAt TEXT NOT NULL
|
|
||||||
);
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Settings 表
|
|
||||||
```sql
|
|
||||||
CREATE TABLE Settings (
|
|
||||||
Key TEXT PRIMARY KEY,
|
|
||||||
Value TEXT NOT NULL,
|
|
||||||
UpdatedAt TEXT NOT NULL
|
|
||||||
);
|
|
||||||
```
|
|
||||||
|
|
||||||
### 6.2 数据访问策略
|
|
||||||
- 使用 Entity Framework Core 进行数据访问
|
|
||||||
- 采用 Repository 模式封装数据访问
|
|
||||||
- 支持 LINQ 查询和异步操作
|
|
||||||
- 数据库迁移管理
|
|
||||||
|
|
||||||
## 7. 通信机制
|
|
||||||
|
|
||||||
### 7.1 HTTP 通信流程
|
|
||||||
1. **C# 后端启动**: MAUI 应用启动时启动本地 Kestrel 服务器
|
|
||||||
2. **Vue 前端加载**: WebView 加载 Vue 应用
|
|
||||||
3. **API 调用**: Vue 通过 Axios 调用本地 HTTP API
|
|
||||||
4. **数据处理**: C# 后端处理请求并返回 JSON 数据
|
|
||||||
5. **界面更新**: Vue 接收响应并更新界面
|
|
||||||
|
|
||||||
### 7.2 错误处理
|
|
||||||
- 统一的错误响应格式
|
|
||||||
- 异常中间件捕获和处理
|
|
||||||
- 前端错误提示和重试机制
|
|
||||||
|
|
||||||
## 8. 部署和打包
|
|
||||||
|
|
||||||
### 8.1 开发环境
|
|
||||||
- **后端调试**: 使用 Visual Studio 调试 MAUI 应用
|
|
||||||
- **前端调试**: 使用 Vite 开发服务器
|
|
||||||
- **热重载**: 支持前后端热重载
|
|
||||||
|
|
||||||
### 8.2 生产构建
|
|
||||||
- **前端构建**: `npm run build` 生成静态文件
|
|
||||||
- **后端打包**: MAUI 发布各平台应用
|
|
||||||
- **静态文件嵌入**: 将前端静态文件嵌入到 MAUI 应用中
|
|
||||||
|
|
||||||
### 8.3 平台特定配置
|
|
||||||
- **Windows**: WebView2 运行时要求
|
|
||||||
- **macOS**: 代码签名和公证
|
|
||||||
- **移动端**: 应用商店发布配置
|
|
||||||
- **Linux**: .NET MAUI 无官方 Linux 目标，需要引入独立桌面宿主（例如基于 WebKitGTK 的方案）并处理运行时依赖与打包格式
|
|
||||||
|
|
||||||
## 9. 性能优化
|
|
||||||
|
|
||||||
### 9.1 前端优化
|
|
||||||
- 组件懒加载
|
|
||||||
- 虚拟滚动（长列表）
|
|
||||||
- 图片懒加载
|
|
||||||
- 缓存策略
|
|
||||||
|
|
||||||
### 9.2 后端优化
|
|
||||||
- 数据库查询优化
|
|
||||||
- 响应缓存
|
|
||||||
- 异步处理
|
|
||||||
- 连接池管理
|
|
||||||
|
|
||||||
## 10. 安全考虑
|
|
||||||
|
|
||||||
### 10.1 本地安全
|
|
||||||
- 本地服务器仅监听 localhost
|
|
||||||
- 防止外部访问
|
|
||||||
- 数据加密存储（可选）
|
|
||||||
|
|
||||||
### 10.2 数据安全
|
|
||||||
- 数据库文件权限控制
|
|
||||||
- 定期备份机制
|
|
||||||
- 敏感数据保护
|
|
||||||
|
|
||||||
## 11. 测试策略
|
|
||||||
|
|
||||||
### 11.1 单元测试
|
|
||||||
- 核心业务逻辑测试
|
|
||||||
- 服务层测试
|
|
||||||
- 工具函数测试
|
|
||||||
|
|
||||||
### 11.2 集成测试
|
|
||||||
- API 集成测试
|
|
||||||
- 数据库集成测试
|
|
||||||
- 前后端集成测试
|
|
||||||
|
|
||||||
### 11.3 端到端测试
|
|
||||||
- 跨平台功能测试
|
|
||||||
- 用户流程测试
|
|
||||||
- 性能测试
|
|
||||||
@@ -0,0 +1,51 @@
|
|||||||
|
# 项目介绍
|
||||||
|
|
||||||
|
> 本文档面向普通用户，介绍 Hua.Todo 是什么、能做什么、支持哪些平台。
|
||||||
|
|
||||||
|
## 1. 什么是 Hua.Todo
|
||||||
|
|
||||||
|
Hua.Todo 是一个**跨平台待办事项管理工具**，帮助您记录和管理日常任务。
|
||||||
|
|
||||||
|
### 核心功能
|
||||||
|
|
||||||
|
| 功能 | 说明 |
|
||||||
|
|---|---|
|
||||||
|
| 待办管理 | 创建、编辑、删除、标记完成；支持父子任务层级 |
|
||||||
|
| 多平台 | Windows、macOS、Linux、Android、iOS 均可使用 |
|
||||||
|
| 云同步 | 登录后自动同步多端数据，随时随地查看 |
|
||||||
|
| 语音控制 | 通过语音指令快速操作待办项 |
|
||||||
|
| 关键词搜索 | 主界面搜索框按标题实时过滤 |
|
||||||
|
| 托盘常驻 | 最小化到系统托盘，全局热键快速唤起 |
|
||||||
|
|
||||||
|
### 界面一览
|
||||||
|
|
||||||
|
- **主界面**：任务列表 + 搜索框 + 同步按钮 + 快速创建入口
|
||||||
|
- **云同步设置**：配置服务端地址、登录/登出、安全策略查看
|
||||||
|
- **任务编辑**：标题、优先级、父子关系、完成状态
|
||||||
|
|
||||||
|
## 2. 支持的平台
|
||||||
|
|
||||||
|
| 平台 | 说明 |
|
||||||
|
|---|---|
|
||||||
|
| Windows | 安装包（`.exe`）或绿色版，需 WebView2 Runtime |
|
||||||
|
| Linux | `.tar.gz` 压缩包，需 WebKitGTK |
|
||||||
|
| macOS | 通过 MAUI 构建（开发中） |
|
||||||
|
| Android / iOS | 通过 MAUI 构建（开发中） |
|
||||||
|
|
||||||
|
## 3. 两种使用方式
|
||||||
|
|
||||||
|
### 方式一：单机使用（默认）
|
||||||
|
|
||||||
|
下载安装后直接使用，所有数据存储在本地。无需网络、无需注册。
|
||||||
|
|
||||||
|
### 方式二：启用云同步
|
||||||
|
|
||||||
|
配置云同步服务端地址并登录后，数据自动同步到服务端，可在多台设备间共享。
|
||||||
|
|
||||||
|
> 云同步需要额外部署 Hua.Todo.Host 服务端（可自行部署或使用第三方提供的服务）。
|
||||||
|
|
||||||
|
## 4. 下一步
|
||||||
|
|
||||||
|
- 如何安装 → [02-安装指南](./02-安装指南.md)
|
||||||
|
- 更新了什么 → [03-版本记录](./03-版本记录.md)
|
||||||
|
- 了解技术细节 → [05-技术栈与项目结构](./05-技术栈与项目结构.md)（开发者）
|
||||||
@@ -0,0 +1,108 @@
|
|||||||
|
# 安装指南
|
||||||
|
|
||||||
|
> 本文档介绍如何安装和使用 Hua.Todo 客户端，以及如何部署云同步服务端。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Windows 安装
|
||||||
|
|
||||||
|
### 1.1 安装包（推荐）
|
||||||
|
|
||||||
|
1. 下载 `Hua.Todo_Setup_vX.Y.Z.exe`
|
||||||
|
2. 运行安装程序，按向导完成安装
|
||||||
|
3. 安装完成后会在桌面和开始菜单创建快捷方式
|
||||||
|
|
||||||
|
> 静默安装：`Hua.Todo_Setup_vX.Y.Z.exe /VERYSILENT /SUPPRESSMSGBOXES`
|
||||||
|
|
||||||
|
### 1.2 绿色版
|
||||||
|
|
||||||
|
1. 下载绿色版压缩包并解压
|
||||||
|
2. 确保系统已安装 [WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2/)
|
||||||
|
3. 运行 `Hua.Todo.Maui.exe`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Linux 安装
|
||||||
|
|
||||||
|
### 2.1 解压部署
|
||||||
|
|
||||||
|
```bash
|
||||||
|
tar -xzf hua.todo-{version}-linux-x64.tar.gz -C /opt/hua-todo
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2.2 环境依赖
|
||||||
|
|
||||||
|
- 确保系统安装了 `libwebkit2gtk-4.0-37`
|
||||||
|
- 如果版本未自带 .NET Runtime，需安装 .NET 10 Runtime
|
||||||
|
|
||||||
|
### 2.3 启动
|
||||||
|
|
||||||
|
```bash
|
||||||
|
chmod +x /opt/hua-todo/Hua.Todo.Avalonia
|
||||||
|
/opt/hua-todo/Hua.Todo.Avalonia
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. 云同步服务端部署
|
||||||
|
|
||||||
|
如需使用云同步功能，需要部署 `Hua.Todo.Host` 服务端。
|
||||||
|
|
||||||
|
### 3.1 Docker 部署（推荐）
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker build -t hua-todo-server -f src/Hua.Todo.Host/Dockerfile .
|
||||||
|
docker run -d \
|
||||||
|
--name hua-todo-server \
|
||||||
|
-p 5173:5173 \
|
||||||
|
-v /data/hua-todo/db:/app/data \
|
||||||
|
-e ASPNETCORE_ENVIRONMENT=Production \
|
||||||
|
hua-todo-server
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.2 直接部署
|
||||||
|
|
||||||
|
```bash
|
||||||
|
dotnet publish src/Hua.Todo.Host -c Release -o ./dist
|
||||||
|
# 将 ./dist 内容同步到服务器
|
||||||
|
# 可选：配置 Systemd 服务
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. 配置云同步
|
||||||
|
|
||||||
|
1. 打开 Hua.Todo → 点击"云同步设置"
|
||||||
|
2. 输入服务端地址（如 `http://your-server:5173`）
|
||||||
|
3. 点击"保存并探测"确认可达
|
||||||
|
4. 输入用户名和密码登录
|
||||||
|
5. 登录成功后即可使用同步功能
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. 关键配置
|
||||||
|
|
||||||
|
### 5.1 数据位置
|
||||||
|
|
||||||
|
- **客户端**：数据默认存储在用户目录 `Hua.Todo/todo.db`
|
||||||
|
- **服务端**：数据存储在容器挂载卷或数据库连接字符串指定位置
|
||||||
|
|
||||||
|
### 5.2 端口
|
||||||
|
|
||||||
|
- 客户端本地端口默认 `5057`，可在 `appsettings.json` 中修改
|
||||||
|
- 服务端端口默认 `5173`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. 常见问题
|
||||||
|
|
||||||
|
| 问题 | 解决方法 |
|
||||||
|
|---|---|
|
||||||
|
| Windows 客户端无法加载 UI | 安装 [WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2/) |
|
||||||
|
| Linux 客户端无法启动 | 安装 `libwebkit2gtk-4.0-37`；执行 `chmod +x` |
|
||||||
|
| 同步连接失败 | 确认服务端可达（访问 `/swagger`）；确认地址格式含 `http://` 或 `https://` |
|
||||||
|
| 端口被占用 | 修改 `appsettings.json` 中的 `WebServer.HostUrl` |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
> 开发者如需从源码构建，见 [06-开发环境与构建](./06-开发环境与构建.md)。
|
||||||
@@ -1,46 +0,0 @@
|
|||||||
# 技术栈与模块说明
|
|
||||||
|
|
||||||
## 🛠️ 技术栈
|
|
||||||
|
|
||||||
### 后端技术栈
|
|
||||||
- **开发语言**：C# 13 (基于 .NET 10)
|
|
||||||
- **框架**：.NET 10 (Preview/Early Adopter)
|
|
||||||
- **UI 框架**：MAUI（移动端/部分桌面） + Avalonia（桌面端）
|
|
||||||
- **Web 服务器**：Kestrel (ASP.NET Core 内置)
|
|
||||||
- **API 框架**：ASP.NET Core Web API (支持动态 API 生成)
|
|
||||||
- **数据访问**：Entity Framework Core 10.0
|
|
||||||
- **数据库**：SQLite (本地存储)
|
|
||||||
- **依赖注入**：Microsoft.Extensions.DependencyInjection
|
|
||||||
|
|
||||||
### 前端技术栈
|
|
||||||
- **开发语言**：TypeScript 5+
|
|
||||||
- **框架**：Vue.js 3
|
|
||||||
- **构建工具**：Vite 5+
|
|
||||||
- **HTTP 客户端**：Axios
|
|
||||||
- **状态管理**：Pinia
|
|
||||||
- **UI 组件库**：Element Plus / Vant (移动端)
|
|
||||||
- **CSS 预处理器**：SCSS
|
|
||||||
|
|
||||||
## 🎯 核心模块说明
|
|
||||||
|
|
||||||
### Hua.Todo.Core
|
|
||||||
领域实体层，定义核心实体（TaskEntity）、安全策略实体（SecurityPolicyEntity）、枚举（TaskPriority）以及仓储接口（ITaskRepository）。
|
|
||||||
|
|
||||||
### Hua.Todo.Application
|
|
||||||
应用层实现，包含：
|
|
||||||
- **业务逻辑**：TaskService 实现。
|
|
||||||
- **动态 API**：基于 Middleware 的动态 API 生成逻辑。
|
|
||||||
- **云同步 (CloudSync)**：包含 Auth 验证、同步服务、安全策略管理等。
|
|
||||||
- **数据访问**：EF Core 数据库上下文（TodoDbContext）与迁移。
|
|
||||||
|
|
||||||
### Hua.Todo.Host
|
|
||||||
后端 API 宿主，作为独立 Server 运行时提供运行环境和配置。
|
|
||||||
|
|
||||||
### Hua.Todo.Web
|
|
||||||
前端 Web 项目，基于 Vue.js 3 + TypeScript + Vite，提供用户界面，通过 HTTP API 与后端通信。
|
|
||||||
|
|
||||||
### Hua.Todo.Maui
|
|
||||||
跨平台客户端项目，将 Web 内容嵌入到原生容器中，支持 Windows、Android、iOS 和 macOS。
|
|
||||||
|
|
||||||
### Hua.Todo.Avalonia
|
|
||||||
桌面客户端项目（Avalonia + WebView），用于提供 Linux/Windows/macOS 桌面形态；同样通过嵌入式 WebServer + WebView 承载前端 UI。
|
|
||||||
@@ -1,17 +1,24 @@
|
|||||||
# 版本更新历史
|
# 版本更新历史
|
||||||
|
|
||||||
## 🔄 版本更新
|
## 版本更新
|
||||||
|
|
||||||
### 版本策略
|
### 版本策略
|
||||||
|
|
||||||
- 采用语义化版本号：`MAJOR.MINOR.PATCH`
|
- 采用语义化版本号：`MAJOR.MINOR.PATCH`
|
||||||
- v1.0.0：初始 WPF 版本
|
- v1.0.0：初始 WPF 版本
|
||||||
- v1.1.0：MAUI + WebView 跨平台版本
|
- v1.1.0：MAUI + WebView 跨平台版本
|
||||||
- v1.2.0 (规划中)：Linux 支持与增强功能
|
- v1.2.0：Linux 支持与增强功能
|
||||||
|
- v1.3.0（开发中）：MCP 服务与语音控制
|
||||||
|
|
||||||
|
### v1.3.0 (2026-06-16)
|
||||||
|
|
||||||
|
- **MCP 服务**：新增 MCP 协议端点（`/mcp`），DynamicMcpToolExtensions 自动扫描 IDynamicApiService 接口生成 MCP 工具；当前覆盖 ITaskService（9 个）+ IVoiceService（4 个）= 13 个 MCP 工具
|
||||||
|
- **语音控制核心**：新增 Voice 模块（Core 接口、LLM 客户端、双策略意图解析器、指令执行器、AiBreakdownService）；26 个单元测试通过
|
||||||
|
- **文档重组**：`docs/manual/` 目录按普通用户/开发者分离重组，新增双入口导航
|
||||||
|
|
||||||
### v1.2.8 (2026-06-14)
|
### v1.2.8 (2026-06-14)
|
||||||
|
|
||||||
- **文档**：新增 [任务同步规则.md](./02-任务同步规则.md)，汇总 Todo 待办项云同步的架构、API 契约、认证鉴权、同步工作流、安全策略与可控落盘等完整规则。
|
- **文档**：新增 [云同步规则](./08-云同步规则.md)，汇总 Todo 待办项云同步的架构、API 契约、认证鉴权、同步工作流、安全策略与可控落盘等完整规则。
|
||||||
|
|
||||||
### v1.2.8 (2026-04-13)
|
### v1.2.8 (2026-04-13)
|
||||||
|
|
||||||
@@ -25,30 +32,29 @@
|
|||||||
|
|
||||||
- **Linux 官方支持**：新增 `Hua.Todo.Avalonia` 项目，正式适配 Linux 平台，同时支持 Windows 和 macOS。
|
- **Linux 官方支持**：新增 `Hua.Todo.Avalonia` 项目，正式适配 Linux 平台，同时支持 Windows 和 macOS。
|
||||||
- **Avalonia 桌面交互**：增加托盘菜单（显示/退出）、关闭隐藏到托盘、Windows 全局热键唤起主窗口、热键配置本地持久化；并对齐 Avalonia 的 appsettings 默认值。
|
- **Avalonia 桌面交互**：增加托盘菜单（显示/退出）、关闭隐藏到托盘、Windows 全局热键唤起主窗口、热键配置本地持久化；并对齐 Avalonia 的 appsettings 默认值。
|
||||||
- **关键词检索**：主界面增加搜索框，按任务标题实时过滤；采用“命中即显示（含上下文）”策略；支持 Esc 清空；英文大小写不敏感。
|
- **关键词检索**：主界面增加搜索框，按任务标题实时过滤；采用"命中即显示（含上下文）"策略；支持 Esc 清空；英文大小写不敏感。
|
||||||
- **云同步（基础可用）**：新增“云同步设置”弹窗，支持手动配置服务端地址（格式校验 + 保存时可达性/风险提示）；登录成功后拉取云端任务并刷新主界面（v1.2.0 为只读展示）；401/403 时会自动清会话并弹出登录入口。
|
- **云同步（基础可用）**：新增"云同步设置"弹窗，支持手动配置服务端地址（格式校验 + 保存时可达性/风险提示）；登录成功后拉取云端任务并刷新主界面（v1.2.0 为只读展示）；401/403 时会自动清会话并弹出登录入口。
|
||||||
- **MAUI（Windows）内嵌 API 文档**：Debug 模式下，内嵌 WebServer 默认提供 Swagger UI（`{HostUrl}/swagger`）与 OpenAPI JSON（`{HostUrl}/swagger/v1/swagger.json`），便于本地接口调试。
|
- **MAUI（Windows）内嵌 API 文档**：Debug 模式下，内嵌 WebServer 默认提供 Swagger UI（`{HostUrl}/swagger`）与 OpenAPI JSON（`{HostUrl}/swagger/v1/swagger.json`），便于本地接口调试。
|
||||||
- **Android 启动稳定性修复**：在 AndroidManifest 中移除 `androidx.startup.InitializationProvider` 自动初始化入口，规避 `androidx.lifecycle.ProcessLifecycleInitializer` 缺失导致的启动崩溃（`NoClassDefFoundError`）。
|
- **Android 启动稳定性修复**：在 AndroidManifest 中移除 `androidx.startup.InitializationProvider` 自动初始化入口，规避 `androidx.lifecycle.ProcessLifecycleInitializer` 缺失导致的启动崩溃（`NoClassDefFoundError`）。
|
||||||
- **MAUI Android 调试配置修复**：在 `Hua.Todo.Maui.csproj` 中显式启用 `AndroidApplication`，并将调试架构配置从 `AndroidSupportedAbis` 切换为 `RuntimeIdentifiers=android-x64`，减少 Visual Studio 启动 Android 调试时的项目识别与模拟器架构问题。
|
- **MAUI Android 调试配置修复**：在 `Hua.Todo.Maui.csproj` 中显式启用 `AndroidApplication`，并将调试架构配置从 `AndroidSupportedAbis` 切换为 `RuntimeIdentifiers=android-x64`，减少 Visual Studio 启动 Android 调试时的项目识别与模拟器架构问题。
|
||||||
- **Swagger 输出补齐 Dynamic API**：任务管理等 Dynamic API 端点会出现在 `swagger.json` 中，避免“接口缺失”导致联调困难。
|
- **Swagger 输出补齐 Dynamic API**：任务管理等 Dynamic API 端点会出现在 `swagger.json` 中，避免"接口缺失"导致联调困难。
|
||||||
- **SQLite DateTime 兼容修复**：新增 `LenientUtcDateTimeStringConverter`，本地数据库中若存在历史遗留的 DateTime “ticks/时间戳字符串”脏数据，读取时将被兼容解析，避免 `/api/task` 等查询因单条坏数据整体失败。
|
- **SQLite DateTime 兼容修复**：新增 `LenientUtcDateTimeStringConverter`，本地数据库中若存在历史遗留的 DateTime "ticks/时间戳字符串"脏数据，读取时将被兼容解析，避免 `/api/task` 等查询因单条坏数据整体失败。
|
||||||
- **SPA 路由回落行为修复**：当 Release/非 Debug 未启用 Swagger 时，`/swagger` 不再被当作“后端专用路径”排除，访问会按 SPA 路由规则回落到 `/index.html`，避免直接 404。
|
- **SPA 路由回落行为修复**：当 Release/非 Debug 未启用 Swagger 时，`/swagger` 不再被当作"后端专用路径"排除，访问会按 SPA 路由规则回落到 `/index.html`，避免直接 404。
|
||||||
- **MAUI 多平台构建开关**：在 Windows 开发机上默认仅构建 Android + Windows 目标，避免 iOS/MacCatalyst 目标在非 macOS 环境触发运行时包缺失（NETSDK1082）；在 macOS 上仍会包含 iOS/MacCatalyst 目标。
|
- **MAUI 多平台构建开关**：在 Windows 开发机上默认仅构建 Android + Windows 目标，避免 iOS/MacCatalyst 目标在非 macOS 环境触发运行时包缺失（NETSDK1082）；在 macOS 上仍会包含 iOS/MacCatalyst 目标。
|
||||||
- **发布脚本整理**：拆分/对齐各平台发布入口，新增 `publish.ps1` 作为统一入口（默认发布 Windows + Linux），Windows 发布脚本支持开关打包与版本自增，发布产物会落盘到 `artifacts/`。
|
- **发布脚本整理**：拆分/对齐各平台发布入口，新增 `publish.ps1` 作为统一入口（默认发布 Windows + Linux），Windows 发布脚本支持开关打包与版本自增，发布产物会落盘到 `artifacts/`。
|
||||||
- **Windows 发布打包修复**：Inno Setup 安装包文件名带版本号（Hua.Todo_Setup_vX.Y.Z.exe）；安装后快捷方式/启动项指向 Hua.Todo.Maui.exe；发布产物强制 IsUsingStatic=true。
|
- **Windows 发布打包修复**：Inno Setup 安装包文件名带版本号（Hua.Todo_Setup_vX.Y.Z.exe）；安装后快捷方式/启动项指向 Hua.Todo.Maui.exe；发布产物强制 IsUsingStatic=true。
|
||||||
- **Windows WebView2 数据目录调整**：MAUI（Unpackaged）默认会在安装目录生成 `Hua.Todo.Maui.exe.WebView2`；现改为写入 `%LocalAppData%\Hua.Todo\WebView2`，避免污染安装目录。
|
- **Windows WebView2 数据目录调整**：MAUI（Unpackaged）默认会在安装目录生成 `Hua.Todo.Maui.exe.WebView2`；现改为写入 `%LocalAppData%\Hua.Todo\WebView2`，避免污染安装目录。
|
||||||
- **Windows WebView2 Runtime 误判修复**：当系统已安装 WebView2 Runtime 但发布产物缺少/裁剪 WebView2 托管程序集时，旧检测逻辑会误判为“未安装”；现改为优先从常见安装目录探测 Evergreen 版本，避免阻断主界面加载。
|
- **Windows WebView2 Runtime 误判修复**：当系统已安装 WebView2 Runtime 但发布产物缺少/裁剪 WebView2 托管程序集时，旧检测逻辑会误判为"未安装"；现改为优先从常见安装目录探测 Evergreen 版本，避免阻断主界面加载。
|
||||||
- **Windows 三件套开发体验**：新增 `start-host.ps1` / `start-dev.ps1`，并在 MAUI 中约定 `IsUsingStatic=false` 时不启动内置 WebServer，避免注入覆盖 Vite 的 `/api -> 5173` 代理配置。
|
- **Windows 三件套开发体验**：新增 `start-host.ps1` / `start-dev.ps1`，并在 MAUI 中约定 `IsUsingStatic=false` 时不启动内置 WebServer，避免注入覆盖 Vite 的 `/api -> 5173` 代理配置。
|
||||||
- **文档与部署指南**：新增 `docs/manual/05-部署文档.md`，详细说明开发环境搭建、多平台发布流程（Windows/Linux/Docker）以及关键配置项；并在技术设计文档中建立链接。
|
- **文档与部署指南**：新增部署文档，详细说明开发环境搭建、多平台发布流程（Windows/Linux/Docker）以及关键配置项。
|
||||||
- **用户文档完善**：在规划中新增了 `docs/manual/08-新手指南.md` 和 `docs/manual/09-用户指南.md`。
|
|
||||||
27→
|
### v1.1.1 (2026-04-06)
|
||||||
28→### v1.1.1 (2026-04-06)
|
|
||||||
|
|
||||||
- **文档规范增强**：新增文档同步规则，强制代码变更与文档更新保持同步。
|
- **文档规范增强**：新增文档同步规则，强制代码变更与文档更新保持同步。
|
||||||
- **项目结构说明校准**：修正 README.md 和技术文档中对 `Hua.Todo.Host`、`Hua.Todo.Application` 等模块的路径与职责描述。
|
- **项目结构说明校准**：修正 README.md 和技术文档中对 `Hua.Todo.Host`、`Hua.Todo.Application` 等模块的路径与职责描述。
|
||||||
- **端口配置校准**：修正文档中关于前端与后端 API 的端口说明（5173/5174）。
|
- **端口配置校准**：修正文档中关于前端与后端 API 的端口说明（5173/5174）。
|
||||||
- **PRD 校准**：移除 v1.2.0 PRD 中“本地迭代不支持”表述与“数据迁移（导入/导出）”小节。
|
- **PRD 校准**：移除 v1.2.0 PRD 中"本地迭代不支持"表述与"数据迁移（导入/导出）"小节。
|
||||||
- **PRD 校准**：移除 v1.2.0 PRD 中“云同步”需求。
|
- **PRD 校准**：移除 v1.2.0 PRD 中"云同步"需求。
|
||||||
|
|
||||||
### v1.1.0 更新内容
|
### v1.1.0 更新内容
|
||||||
|
|
||||||
@@ -59,11 +65,6 @@
|
|||||||
- 使用 SQLite 作为本地数据库
|
- 使用 SQLite 作为本地数据库
|
||||||
- 实现子任务支持
|
- 实现子任务支持
|
||||||
|
|
||||||
### v1.2.0 规划内容 (即将推出)
|
### v1.0.0 初始版本
|
||||||
|
|
||||||
- **Linux 官方支持**：正式适配 Linux 平台。
|
- 初始 WPF 版本。
|
||||||
- **Linux 打包与交付**：新增 `.tar.gz` 发布脚本与 Flatpak（manifest/desktop entry/AppStream）基础结构。
|
|
||||||
- **关键词检索**：支持按任务标题关键词搜索。
|
|
||||||
- **标签系统**：引入多标签支持，提升任务组织效率。
|
|
||||||
- **暗色模式**：全平台适配暗色/深色主题。
|
|
||||||
- **数据导出导入（后续）**：支持 JSON 格式数据备份与迁移（延期到后续版本）。
|
|
||||||
@@ -1,6 +1,6 @@
|
|||||||
# 其他信息
|
# 其他信息
|
||||||
|
|
||||||
## 🤝 贡献指南
|
## 贡献指南
|
||||||
|
|
||||||
1. Fork 项目
|
1. Fork 项目
|
||||||
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
|
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
|
||||||
@@ -8,11 +8,11 @@
|
|||||||
4. 推送到分支 (`git push origin feature/AmazingFeature`)
|
4. 推送到分支 (`git push origin feature/AmazingFeature`)
|
||||||
5. 打开 Pull Request
|
5. 打开 Pull Request
|
||||||
|
|
||||||
## 📄 许可证
|
## 许可证
|
||||||
|
|
||||||
本项目采用 AGPL-3.0 许可证 - 查看 [LICENSE](LICENSE) (英文) 或 [LICENSE.zh-CN](LICENSE.zh-CN) (中文) 文件了解详情
|
本项目采用 AGPL-3.0 许可证 - 查看 [LICENSE](LICENSE) (英文) 或 [LICENSE.zh-CN](LICENSE.zh-CN) (中文) 文件了解详情
|
||||||
|
|
||||||
## 📞 联系方式
|
## 联系方式
|
||||||
|
|
||||||
- 项目作者：ShaoHua
|
- 项目作者：ShaoHua
|
||||||
- 项目地址：https://git.we965.cn/Tools/Hua.Todo
|
- 项目地址：https://git.we965.cn/Tools/Hua.Todo
|
||||||
@@ -0,0 +1,124 @@
|
|||||||
|
# 技术栈与项目结构
|
||||||
|
|
||||||
|
> 本文档面向开发者，介绍 Hua.Todo 的技术选型、项目划分、模块职责与依赖关系。
|
||||||
|
|
||||||
|
## 1. 技术栈
|
||||||
|
|
||||||
|
### 1.1 后端
|
||||||
|
|
||||||
|
| 技术 | 版本/说明 |
|
||||||
|
|---|---|
|
||||||
|
| 开发语言 | C# 13 |
|
||||||
|
| 框架 | .NET 10 |
|
||||||
|
| UI 框架 | MAUI（移动端/部分桌面）+ Avalonia（桌面端） |
|
||||||
|
| Web 服务器 | Kestrel（ASP.NET Core 内置） |
|
||||||
|
| API 框架 | ASP.NET Core Web API（含动态 API 生成） |
|
||||||
|
| ORM | Entity Framework Core 10.0 |
|
||||||
|
| 数据库 | SQLite（本地存储） |
|
||||||
|
| 依赖注入 | Microsoft.Extensions.DependencyInjection |
|
||||||
|
| 日志 | Serilog |
|
||||||
|
|
||||||
|
### 1.2 前端
|
||||||
|
|
||||||
|
| 技术 | 版本/说明 |
|
||||||
|
|---|---|
|
||||||
|
| 开发语言 | TypeScript 5+ |
|
||||||
|
| 框架 | Vue.js 3 |
|
||||||
|
| 构建工具 | Vite 5+ |
|
||||||
|
| HTTP 客户端 | Axios |
|
||||||
|
| 状态管理 | Pinia |
|
||||||
|
| UI 组件库 | Element Plus / Vant（移动端） |
|
||||||
|
| CSS 预处理器 | SCSS |
|
||||||
|
|
||||||
|
## 2. 项目结构
|
||||||
|
|
||||||
|
```
|
||||||
|
Hua.Todo/
|
||||||
|
├── src/
|
||||||
|
│ ├── Hua.Todo.Core/ # 领域实体、枚举、仓储接口
|
||||||
|
│ ├── Hua.Todo.Application/ # 业务逻辑、EF Core、动态 API、云同步
|
||||||
|
│ ├── Hua.Todo.Host/ # 独立服务端宿主（ASP.NET）
|
||||||
|
│ ├── Hua.Todo.Maui/ # MAUI 客户端（Windows/macOS/Android/iOS）
|
||||||
|
│ ├── Hua.Todo.Avalonia/ # Avalonia 客户端（Linux/Windows 桌面）
|
||||||
|
│ ├── Hua.Todo.Web/ # Vue 3 前端（Vite）
|
||||||
|
│ └── Hua.Todo.Tests/ # 单元测试与集成测试
|
||||||
|
├── docs/
|
||||||
|
│ ├── manual/ # 项目手册
|
||||||
|
│ ├── project/ # 产品需求文档与研发工单
|
||||||
|
│ └── AI沟通记录/ # AI 对话记录
|
||||||
|
└── .trae/ # 智能体规则与记忆
|
||||||
|
```
|
||||||
|
|
||||||
|
## 3. 核心模块说明
|
||||||
|
|
||||||
|
### 3.1 Hua.Todo.Core
|
||||||
|
领域实体层，定义核心实体与接口：
|
||||||
|
- **实体**：`TaskEntity`、`UserEntity`、`SecurityPolicyEntity`、`AuditLogEntity`
|
||||||
|
- **枚举**：`TaskPriority`
|
||||||
|
- **仓储接口**：`ITaskRepository`
|
||||||
|
- **语音控制接口**：`IVoiceInputService`、`IVoiceOutputService`、`IVoiceIntentParser`
|
||||||
|
|
||||||
|
### 3.2 Hua.Todo.Application
|
||||||
|
应用层实现，所有业务逻辑的集中地：
|
||||||
|
- **TaskService**：待办项 CRUD 业务逻辑
|
||||||
|
- **动态 API**（`DynamicApi/`）：基于接口自动生成 RESTful API
|
||||||
|
- **云同步**（`CloudSync/`）：认证服务、同步服务、安全策略管理
|
||||||
|
- **语音控制**（`Voice/`）：LLM 客户端、双策略意图解析器、指令执行器
|
||||||
|
- **MCP 服务**（`Mcp/`）：自动扫描并暴露 MCP 工具
|
||||||
|
- **数据访问**：`TodoDbContext` + EF Core 迁移
|
||||||
|
|
||||||
|
### 3.3 Hua.Todo.Host
|
||||||
|
独立服务端宿主，同时注册业务服务与云同步端点：
|
||||||
|
- `AddApplicationServices()`：待办项 CRUD + 动态 API
|
||||||
|
- `AddCloudSyncServer()`：认证、同步、安全策略端点
|
||||||
|
- `AddMcpServerServices()`：MCP 协议端点（`/mcp`）
|
||||||
|
- `AddVoiceServices()`：语音控制端点
|
||||||
|
|
||||||
|
### 3.4 Hua.Todo.Maui
|
||||||
|
跨平台客户端，内嵌 Kestrel WebServer + WebView 承载前端：
|
||||||
|
- 仅注册 `AddApplicationServices()`，不暴露云同步端点
|
||||||
|
- 平台特定服务（快捷键、通知等）
|
||||||
|
|
||||||
|
### 3.5 Hua.Todo.Avalonia
|
||||||
|
桌面客户端（Avalonia + WebView），提供 Linux/Windows 桌面形态：
|
||||||
|
- 同样通过嵌入式 WebServer + WebView 承载前端
|
||||||
|
- 托盘菜单、全局热键等桌面交互功能
|
||||||
|
|
||||||
|
### 3.6 Hua.Todo.Web
|
||||||
|
Vue 3 前端项目，同一份构建产物被多个宿主以静态资源形式承载：
|
||||||
|
- **组件**：TaskList、TaskItem、TaskEditDialog、CloudSyncSettings 等
|
||||||
|
- **状态管理**：Pinia stores
|
||||||
|
- **API 层**：`api/tasks.ts`、`api/cloudSync.ts`、`api/mcp.ts`
|
||||||
|
|
||||||
|
## 4. 依赖方向
|
||||||
|
|
||||||
|
```
|
||||||
|
Hua.Todo.Core
|
||||||
|
↑
|
||||||
|
Hua.Todo.Application
|
||||||
|
↑
|
||||||
|
├── Hua.Todo.Host （服务端：全部能力）
|
||||||
|
├── Hua.Todo.Maui （客户端：仅业务服务）
|
||||||
|
└── Hua.Todo.Avalonia （客户端：仅业务服务）
|
||||||
|
|
||||||
|
Hua.Todo.Web （无 .NET 依赖；通过 HTTP 调用上述任一宿主）
|
||||||
|
```
|
||||||
|
|
||||||
|
- **禁止反向依赖**：Core 不得引用 Application；Application 不得引用任何宿主项目
|
||||||
|
- **客户端不暴露云同步端点**：MAUI / Avalonia 只调用 `AddApplicationServices()`
|
||||||
|
|
||||||
|
## 5. 关键扩展点
|
||||||
|
|
||||||
|
| 扩展点 | 位置 |
|
||||||
|
|---|---|
|
||||||
|
| DI 注册总入口 | `Hua.Todo.Application/ServiceCollectionExtensions.cs` |
|
||||||
|
| 云同步 DI | `Hua.Todo.Application/CloudSync/CloudSyncServiceCollectionExtensions.cs` |
|
||||||
|
| 动态 API 中间件 | `Hua.Todo.Application/DynamicApi/DynamicApiMiddleware.cs` |
|
||||||
|
| MCP 工具注册 | `Hua.Todo.Application/Mcp/DynamicMcpToolExtensions.cs` |
|
||||||
|
| 语音意图解析 | `Hua.Todo.Application/Voice/HybridVoiceIntentParser.cs` |
|
||||||
|
| 嵌入式 WebServer | `Hua.Todo.{Maui,Avalonia}/Services/EmbeddedWebServerService.cs` |
|
||||||
|
|
||||||
|
## 6. 下一步
|
||||||
|
|
||||||
|
- 搭建开发环境 → [06-开发环境与构建](./06-开发环境与构建.md)
|
||||||
|
- 深入架构设计 → [07-技术架构设计](./07-技术架构设计.md)
|
||||||
@@ -1,128 +0,0 @@
|
|||||||
# Hua.Todo 构建与部署手册
|
|
||||||
|
|
||||||
本文档提供 Hua.Todo 项目的版本构建指南与多平台部署流程，侧重于如何产出可分发的版本并将其安装或部署到目标机器。
|
|
||||||
|
|
||||||
## 1. 🏗️ 版本构建流程 (Release Build)
|
|
||||||
|
|
||||||
在进行任何部署之前，必须先通过自动化脚本构建出 Release 版本的产物。
|
|
||||||
|
|
||||||
### 1.1 前提要求
|
|
||||||
|
|
||||||
- **环境检查**：已安装 .NET 10 SDK、Node.js 18+ 以及 Inno Setup 6（仅 Windows 打包需要）。
|
|
||||||
- **脚本入口**：位于根目录的 `publish.ps1` 系列脚本。
|
|
||||||
|
|
||||||
### 1.2 执行构建
|
|
||||||
|
|
||||||
根据目标平台执行对应的构建命令：
|
|
||||||
|
|
||||||
- **全平台一键构建**：
|
|
||||||
```powershell
|
|
||||||
.\publish.ps1 -Windows -Linux
|
|
||||||
```
|
|
||||||
- **Windows 版本构建**：
|
|
||||||
```powershell
|
|
||||||
.\publish-windows.ps1
|
|
||||||
```
|
|
||||||
- **Linux 版本构建**：
|
|
||||||
```powershell
|
|
||||||
.\publish-linux.ps1 -RuntimeIdentifier linux-x64 -SelfContained
|
|
||||||
```
|
|
||||||
|
|
||||||
### 1.3 产物输出位置
|
|
||||||
|
|
||||||
所有构建产物将按平台归类在根目录的 `artifacts/` 文件夹下：
|
|
||||||
|
|
||||||
- **Windows**: `artifacts\windows\win-x64\installer\` (安装包) 与 `publish\` (解压即用版)
|
|
||||||
- **Linux**: `artifacts\linux\linux-x64\` (`.tar.gz` 压缩包)
|
|
||||||
|
|
||||||
***
|
|
||||||
|
|
||||||
## 2. 🪟 Windows 客户端部署
|
|
||||||
|
|
||||||
### 2.1 安装包分发 (Recommended)
|
|
||||||
|
|
||||||
1. **分发文件**：将 `hua.todo-{version}-win-x64-setup.exe` 提供给终端用户。
|
|
||||||
2. **安装流程**：用户运行安装程序，程序将自动：
|
|
||||||
- 安装到 `%ProgramFiles%\Hua.Todo`（或用户自定义路径）。
|
|
||||||
- 创建桌面与开始菜单快捷方式。
|
|
||||||
- 写入注册表以支持卸载。
|
|
||||||
3. **静默安装**：支持 Inno Setup 标准静默参数 `/VERYSILENT /SUPPRESSMSGBOXES`。
|
|
||||||
|
|
||||||
### 2.2 绿色版部署
|
|
||||||
|
|
||||||
1. **分发文件**：将 `artifacts\windows\win-x64\publish\` 文件夹整体打包。
|
|
||||||
2. **运行要求**：目标机器需安装 **WebView2 Runtime**。
|
|
||||||
3. **启动程序**：运行 `Hua.Todo.Maui.exe`。
|
|
||||||
|
|
||||||
***
|
|
||||||
|
|
||||||
## 3. 🐧 Linux 客户端部署
|
|
||||||
|
|
||||||
目前提供基于 Avalonia 的 Linux 交付版本，采用 `.tar.gz` 压缩包形式。
|
|
||||||
|
|
||||||
### 3.1 解压部署
|
|
||||||
|
|
||||||
1. **解压**：
|
|
||||||
```bash
|
|
||||||
tar -xzf hua.todo-{version}-linux-x64.tar.gz -C /opt/hua-todo
|
|
||||||
```
|
|
||||||
2. **运行环境**：
|
|
||||||
- 确保系统安装了 `libwebkit2gtk-4.0-37`。
|
|
||||||
- 如果构建时未开启 `-SelfContained`，则需安装 .NET 10 Runtime。
|
|
||||||
3. **权限设置**：
|
|
||||||
```bash
|
|
||||||
chmod +x /opt/hua-todo/Hua.Todo.Avalonia
|
|
||||||
```
|
|
||||||
4. **启动**：直接运行 `/opt/hua-todo/Hua.Todo.Avalonia`。
|
|
||||||
|
|
||||||
***
|
|
||||||
|
|
||||||
## 4. ☁️ 云同步服务端部署 (Server)
|
|
||||||
|
|
||||||
`Hua.Todo.Host` 可作为中心服务端部署，用于任务的云端同步。
|
|
||||||
|
|
||||||
### 4.1 Docker 部署 (Recommended)
|
|
||||||
|
|
||||||
1. **上传代码**或将 `src/Hua.Todo.Host/Dockerfile` 复制到服务器。
|
|
||||||
2. **构建与启动**：
|
|
||||||
```bash
|
|
||||||
docker build -t hua-todo-server -f src/Hua.Todo.Host/Dockerfile .
|
|
||||||
docker run -d \
|
|
||||||
--name hua-todo-server \
|
|
||||||
-p 5173:5173 \
|
|
||||||
-v /data/hua-todo/db:/app/data \
|
|
||||||
-e ASPNETCORE_ENVIRONMENT=Production \
|
|
||||||
hua-todo-server
|
|
||||||
```
|
|
||||||
|
|
||||||
### 4.2 直接部署 (Binary)
|
|
||||||
|
|
||||||
1. **构建 Host**：`dotnet publish src/Hua.Todo.Host -c Release -o ./dist`。
|
|
||||||
2. **同步产物**：将 `./dist` 内容同步到服务器。
|
|
||||||
3. **配置 Systemd 服务**（可选）：
|
|
||||||
创建一个 `hua-todo.service` 文件，指向可执行程序并设置工作目录。
|
|
||||||
|
|
||||||
***
|
|
||||||
|
|
||||||
## 5. ⚙️ 关键配置校准
|
|
||||||
|
|
||||||
### 5.1 数据持久化
|
|
||||||
|
|
||||||
- **SQLite 路径**：客户端数据默认存储在用户目录下的 `Hua.Todo/todo.db`；服务端数据存储在容器挂载卷或指定 `appsettings.json` 的连接字符串中。
|
|
||||||
- **备份建议**：定期备份 `todo.db` 文件。
|
|
||||||
|
|
||||||
### 5.2 端口与访问
|
|
||||||
|
|
||||||
- **客户端本地端口**：默认 `5057`。如果被占用，可在 `appsettings.json` 中修改 `WebServer.HostUrl`。
|
|
||||||
- **服务端访问**：确保服务端防火墙已开放对应的 API 端口（默认 5173）。
|
|
||||||
|
|
||||||
***
|
|
||||||
|
|
||||||
## 6. 🛠️ 常见问题排查
|
|
||||||
|
|
||||||
- **客户端无法加载 UI**：检查目标机器是否安装了 WebView2 Runtime（Windows）或 WebKitGTK（Linux）。
|
|
||||||
- **同步连接失败**：
|
|
||||||
1. 确认服务端 API 是否可达（访问 `/swagger` 验证）。
|
|
||||||
2. 确认客户端配置的服务端地址格式（需包含 `http://` 或 `https://`）。
|
|
||||||
- **权限问题**：在 Linux 下运行前，务必执行 `chmod +x` 给主程序执行权限。
|
|
||||||
|
|
||||||
@@ -0,0 +1,100 @@
|
|||||||
|
# 开发环境与构建
|
||||||
|
|
||||||
|
> 本文档面向开发者，介绍如何搭建开发环境、从源码构建和部署。
|
||||||
|
|
||||||
|
## 1. 开发环境搭建
|
||||||
|
|
||||||
|
### 1.1 前提要求
|
||||||
|
|
||||||
|
- .NET 10 SDK
|
||||||
|
- Node.js 18+
|
||||||
|
- Visual Studio 2022+（推荐）或 VS Code
|
||||||
|
- Inno Setup 6（仅 Windows 打包需要）
|
||||||
|
|
||||||
|
### 1.2 克隆与安装
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone https://git.we965.cn/Tools/Hua.Todo.git
|
||||||
|
cd Hua.Todo
|
||||||
|
```
|
||||||
|
|
||||||
|
前端依赖安装：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd src/Hua.Todo.Web
|
||||||
|
npm install
|
||||||
|
```
|
||||||
|
|
||||||
|
### 1.3 启动开发环境
|
||||||
|
|
||||||
|
**方式一：Windows 三件套（推荐）**
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
# 终端 1：启动 Host（API 服务端）
|
||||||
|
.\start-host.ps1
|
||||||
|
|
||||||
|
# 终端 2：启动前端开发服务器
|
||||||
|
.\start-dev.ps1
|
||||||
|
```
|
||||||
|
|
||||||
|
**方式二：MAUI 嵌入模式**
|
||||||
|
|
||||||
|
在 Visual Studio 中直接调试运行 `Hua.Todo.Maui` 项目，MAUI 会自动启动内嵌 WebServer 并加载前端。
|
||||||
|
|
||||||
|
## 2. 版本构建 (Release Build)
|
||||||
|
|
||||||
|
### 2.1 脚本入口
|
||||||
|
|
||||||
|
位于根目录的 `publish.ps1` 系列脚本：
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
# 全平台一键构建
|
||||||
|
.\publish.ps1 -Windows -Linux
|
||||||
|
|
||||||
|
# Windows 单独构建
|
||||||
|
.\publish-windows.ps1
|
||||||
|
|
||||||
|
# Linux 单独构建
|
||||||
|
.\publish-linux.ps1 -RuntimeIdentifier linux-x64 -SelfContained
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2.2 产物输出位置
|
||||||
|
|
||||||
|
| 平台 | 路径 |
|
||||||
|
|---|---|
|
||||||
|
| Windows 安装包 | `artifacts\windows\win-x64\installer\` |
|
||||||
|
| Windows 绿色版 | `artifacts\windows\win-x64\publish\` |
|
||||||
|
| Linux | `artifacts\linux\linux-x64\`（`.tar.gz`） |
|
||||||
|
|
||||||
|
## 3. 服务端部署
|
||||||
|
|
||||||
|
### 3.1 Docker 部署（推荐）
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker build -t hua-todo-server -f src/Hua.Todo.Host/Dockerfile .
|
||||||
|
docker run -d \
|
||||||
|
--name hua-todo-server \
|
||||||
|
-p 5173:5173 \
|
||||||
|
-v /data/hua-todo/db:/app/data \
|
||||||
|
-e ASPNETCORE_ENVIRONMENT=Production \
|
||||||
|
hua-todo-server
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.2 直接部署
|
||||||
|
|
||||||
|
```bash
|
||||||
|
dotnet publish src/Hua.Todo.Host -c Release -o ./dist
|
||||||
|
# 将 ./dist 同步到服务器，可选配置 Systemd 服务
|
||||||
|
```
|
||||||
|
|
||||||
|
## 4. 数据库
|
||||||
|
|
||||||
|
- **开发/测试**：SQLite，路径 `src/Hua.Todo.Host/Hua.Todo.db`
|
||||||
|
- **生产**：SQLite（默认）或切换其他 EF Core 支持的数据库
|
||||||
|
- **迁移**：嵌入式宿主启动时自动执行 `db.Database.Migrate()`
|
||||||
|
|
||||||
|
## 5. 下一步
|
||||||
|
|
||||||
|
- 了解架构细节 → [07-技术架构设计](./07-技术架构设计.md)
|
||||||
|
- 了解云同步 → [08-云同步规则](./08-云同步规则.md)
|
||||||
|
- 编码规范 → [09-代码规范](./09-代码规范.md)
|
||||||
@@ -0,0 +1,389 @@
|
|||||||
|
# 技术架构设计
|
||||||
|
|
||||||
|
> 本文档面向开发者，描述 Hua.Todo 的详细技术架构，包括目录结构、模块设计、API 端点、数据库设计与通信机制。
|
||||||
|
|
||||||
|
## 1. 项目目录结构
|
||||||
|
|
||||||
|
```
|
||||||
|
Hua.Todo/
|
||||||
|
├── docs/ # 文档目录
|
||||||
|
│ ├── manual/ # 用户/开发者手册
|
||||||
|
│ │ ├── 00-目录与导读.md
|
||||||
|
│ │ ├── 01-项目介绍.md
|
||||||
|
│ │ ├── 02-安装指南.md
|
||||||
|
│ │ ├── 03-版本记录.md
|
||||||
|
│ │ ├── 04-其他信息.md
|
||||||
|
│ │ ├── 05-技术栈与项目结构.md
|
||||||
|
│ │ ├── 06-开发环境与构建.md
|
||||||
|
│ │ ├── 07-技术架构设计.md（本文件）
|
||||||
|
│ │ ├── 08-云同步规则.md
|
||||||
|
│ │ ├── 09-代码规范.md
|
||||||
|
│ │ └── 10-MCP服务集成.md
|
||||||
|
│ └── project/ # 项目进度/需求文档
|
||||||
|
│
|
||||||
|
├── src/ # 源代码目录
|
||||||
|
│ ├── Hua.Todo.Maui/ # MAUI 主项目（跨平台入口）
|
||||||
|
│ │ ├── Platforms/ # 平台特定代码
|
||||||
|
│ │ │ ├── Windows/ # Windows 平台代码
|
||||||
|
│ │ │ │ ├── App.xaml
|
||||||
|
│ │ │ │ └── Services/
|
||||||
|
│ │ │ │ └── HotKeyService.cs
|
||||||
|
│ │ │ ├── MacCatalyst/ # macOS 平台代码
|
||||||
|
│ │ │ ├── Android/ # Android 平台代码
|
||||||
|
│ │ │ └── iOS/ # iOS 平台代码
|
||||||
|
│ │ ├── Resources/ # 资源文件
|
||||||
|
│ │ ├── Controls/ # 自定义控件
|
||||||
|
│ │ │ └── WebViewContainer.xaml
|
||||||
|
│ │ ├── Services/ # 服务层
|
||||||
|
│ │ │ ├── IHotKeyService.cs
|
||||||
|
│ │ │ ├── IPlatformService.cs
|
||||||
|
│ │ │ └── AppLifecycleService.cs
|
||||||
|
│ │ ├── App.xaml / App.xaml.cs
|
||||||
|
│ │ ├── MauiProgram.cs
|
||||||
|
│ │ └── Hua.Todo.Maui.csproj
|
||||||
|
│ │
|
||||||
|
│ ├── Hua.Todo.Avalonia/ # Avalonia 项目（Linux 支持）
|
||||||
|
│ │ ├── Services/
|
||||||
|
│ │ │ ├── EmbeddedWebServerServiceFactory.cs
|
||||||
|
│ │ │ ├── GlobalHotKeyServiceFactory.cs
|
||||||
|
│ │ │ └── Platforms/
|
||||||
|
│ │ ├── Views/
|
||||||
|
│ │ │ ├── MainView.axaml / MainView.axaml.cs
|
||||||
|
│ │ │ └── MainWindow.axaml / MainWindow.axaml.cs
|
||||||
|
│ │ ├── App.axaml / App.axaml.cs
|
||||||
|
│ │ ├── Program.cs
|
||||||
|
│ │ ├── appsettings.json
|
||||||
|
│ │ ├── setup.iss
|
||||||
|
│ │ ├── wwwroot/
|
||||||
|
│ │ └── Hua.Todo.Avalonia.csproj
|
||||||
|
│ │
|
||||||
|
│ ├── Hua.Todo.Host/ # 独立服务端
|
||||||
|
│ │ ├── Program.cs # API 入口
|
||||||
|
│ │ ├── appsettings.json
|
||||||
|
│ │ └── Hua.Todo.Host.csproj
|
||||||
|
│ │
|
||||||
|
│ ├── Hua.Todo.Application/ # 应用层
|
||||||
|
│ │ ├── Data/
|
||||||
|
│ │ │ ├── TodoDbContext.cs
|
||||||
|
│ │ │ └── Migrations/
|
||||||
|
│ │ ├── DynamicApi/
|
||||||
|
│ │ ├── CloudSync/
|
||||||
|
│ │ ├── Voice/
|
||||||
|
│ │ ├── Mcp/
|
||||||
|
│ │ └── Hua.Todo.Application.csproj
|
||||||
|
│ │
|
||||||
|
│ ├── Hua.Todo.Core/ # 核心业务逻辑层
|
||||||
|
│ │ ├── Entities/
|
||||||
|
│ │ │ ├── TaskEntity.cs
|
||||||
|
│ │ │ ├── UserEntity.cs
|
||||||
|
│ │ │ ├── SecurityPolicyEntity.cs
|
||||||
|
│ │ │ └── AuditLogEntity.cs
|
||||||
|
│ │ ├── Interfaces/
|
||||||
|
│ │ └── Hua.Todo.Core.csproj
|
||||||
|
│ │
|
||||||
|
│ ├── Hua.Todo.Web/ # 前端 Web 项目 (Vue.js)
|
||||||
|
│ │ ├── src/
|
||||||
|
│ │ │ ├── api/ # API 调用
|
||||||
|
│ │ │ │ ├── client.ts
|
||||||
|
│ │ │ │ ├── tasks.ts
|
||||||
|
│ │ │ │ ├── cloudSync.ts
|
||||||
|
│ │ │ │ └── mcp.ts
|
||||||
|
│ │ │ ├── components/ # Vue 组件
|
||||||
|
│ │ │ │ ├── TaskList.vue
|
||||||
|
│ │ │ │ ├── TaskItem.vue
|
||||||
|
│ │ │ │ └── TaskEditDialog.vue
|
||||||
|
│ │ │ ├── composables/ # 组合式函数
|
||||||
|
│ │ │ ├── stores/ # 状态管理 (Pinia)
|
||||||
|
│ │ │ ├── types/ # TypeScript 类型定义
|
||||||
|
│ │ │ ├── utils/ # 工具函数
|
||||||
|
│ │ │ ├── App.vue
|
||||||
|
│ │ │ └── main.ts
|
||||||
|
│ │ ├── package.json
|
||||||
|
│ │ ├── vite.config.ts
|
||||||
|
│ │ ├── tsconfig.json
|
||||||
|
│ │ └── index.html
|
||||||
|
│ │
|
||||||
|
│ └── Hua.Todo.Tests/ # 测试项目
|
||||||
|
│ ├── Unit/
|
||||||
|
│ └── Integration/
|
||||||
|
│
|
||||||
|
├── publish.ps1 / publish-windows.ps1 / publish-linux.ps1
|
||||||
|
├── Directory.Build.props
|
||||||
|
├── Hua.Todo.sln
|
||||||
|
└── README.md
|
||||||
|
```
|
||||||
|
|
||||||
|
## 2. 模块设计
|
||||||
|
|
||||||
|
### 2.1 Hua.Todo.Maui（跨平台客户端）
|
||||||
|
|
||||||
|
**职责**：
|
||||||
|
- 应用程序入口和生命周期管理
|
||||||
|
- 平台特定功能封装
|
||||||
|
- WebView 容器管理
|
||||||
|
- 本地 HTTP 服务器启动
|
||||||
|
|
||||||
|
**关键组件**：
|
||||||
|
- `MauiProgram.cs`：配置 MAUI 应用和依赖注入
|
||||||
|
- `App.xaml.cs`：应用程序主入口
|
||||||
|
- `WebViewContainer`：封装 WebView 控件
|
||||||
|
- 平台特定服务：快捷键、通知等
|
||||||
|
|
||||||
|
### 2.2 Hua.Todo.Avalonia（桌面客户端）
|
||||||
|
|
||||||
|
**职责**：
|
||||||
|
- Linux 平台支持
|
||||||
|
- 桌面交互功能（托盘菜单、全局热键等）
|
||||||
|
- WebView 容器管理
|
||||||
|
- 本地 HTTP 服务器启动
|
||||||
|
|
||||||
|
**关键组件**：
|
||||||
|
- `Program.cs`：配置 Avalonia 应用和依赖注入
|
||||||
|
- `App.axaml.cs`：应用程序主入口
|
||||||
|
- `MainWindow.axaml.cs`：主窗口管理
|
||||||
|
- `GlobalHotKeyServiceFactory`：全局热键服务工厂
|
||||||
|
- `EmbeddedWebServerServiceFactory`：内嵌 Web 服务器服务工厂
|
||||||
|
|
||||||
|
### 2.3 Hua.Todo.Host（独立服务端）
|
||||||
|
|
||||||
|
**职责**：
|
||||||
|
- 提供 RESTful API 接口
|
||||||
|
- 云同步端点（认证、同步、安全策略）
|
||||||
|
- MCP 协议端点
|
||||||
|
- 语音控制端点
|
||||||
|
|
||||||
|
**接口文档**：
|
||||||
|
- 开发环境下提供 Swagger UI：`http://localhost:5173/swagger`
|
||||||
|
|
||||||
|
**关键组件**：
|
||||||
|
- `CloudSync`：云同步 Minimal APIs（`/auth`、`/tasks`、`/sync`、`/security`）
|
||||||
|
- `DynamicApiMiddleware`：业务接口通过 Dynamic API（`/api/{service}/...`）对外暴露
|
||||||
|
- `MCP`：MCP 协议端点（`/mcp`）
|
||||||
|
- `Program.cs`：API 服务器配置和启动
|
||||||
|
|
||||||
|
### 2.4 Hua.Todo.Core（核心业务层）
|
||||||
|
|
||||||
|
**职责**：
|
||||||
|
- 定义领域模型和业务规则
|
||||||
|
- 提供核心业务接口
|
||||||
|
- 实现领域驱动设计模式
|
||||||
|
|
||||||
|
**关键组件**：
|
||||||
|
- `Entities`：领域实体（TaskEntity、UserEntity、SecurityPolicyEntity、AuditLogEntity）
|
||||||
|
- `Interfaces`：业务接口定义
|
||||||
|
- `Voice`：语音控制相关接口与枚举
|
||||||
|
|
||||||
|
### 2.5 Hua.Todo.Application（应用层）
|
||||||
|
|
||||||
|
**职责**：
|
||||||
|
- 业务逻辑实现
|
||||||
|
- EF Core 数据访问与迁移
|
||||||
|
- 动态 API 生成
|
||||||
|
- 云同步服务
|
||||||
|
- 语音控制服务
|
||||||
|
- MCP 工具注册
|
||||||
|
|
||||||
|
### 2.6 Hua.Todo.Web（前端）
|
||||||
|
|
||||||
|
**职责**：
|
||||||
|
- 用户界面展示
|
||||||
|
- 用户交互处理
|
||||||
|
- HTTP API 调用
|
||||||
|
- 状态管理
|
||||||
|
|
||||||
|
## 3. HTTP API 设计
|
||||||
|
|
||||||
|
### 3.1 API 基础配置
|
||||||
|
|
||||||
|
| 模式 | 基础 URL |
|
||||||
|
|---|---|
|
||||||
|
| 开发 / Host 模式 | `http://localhost:5173/api` |
|
||||||
|
| MAUI 内嵌模式 | `{HostUrl}/api`（默认 `http://localhost:5057/api`） |
|
||||||
|
|
||||||
|
- 数据格式：JSON
|
||||||
|
- 认证方式：云同步端点需要 Bearer Token，本地端点无需认证
|
||||||
|
|
||||||
|
### 3.2 任务管理 API（Dynamic API）
|
||||||
|
|
||||||
|
```
|
||||||
|
GET /api/task # 获取任务列表
|
||||||
|
GET /api/task/active # 获取未完成任务
|
||||||
|
GET /api/task/completed # 获取已完成任务
|
||||||
|
GET /api/task/{id} # 获取单个任务
|
||||||
|
POST /api/task # 创建任务
|
||||||
|
PUT /api/task # 更新任务
|
||||||
|
DELETE /api/task/{id} # 删除任务
|
||||||
|
PATCH /api/task/{id}/toggle # 切换完成状态
|
||||||
|
GET /api/task/{parentTaskId}/subtasks # 获取子任务列表
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.3 云同步 API（Host 模式）
|
||||||
|
|
||||||
|
```
|
||||||
|
POST /auth/bootstrap # 初始化管理员（仅首次）
|
||||||
|
POST /auth/login # 登录
|
||||||
|
POST /auth/step-up # 二次验证
|
||||||
|
GET /tasks/ # 获取云端任务
|
||||||
|
POST /sync/ # 推送/拉取合并同步
|
||||||
|
GET /security/policy # 获取安全策略
|
||||||
|
PUT /security/policy # 更新安全策略
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.4 MCP 端点
|
||||||
|
|
||||||
|
```
|
||||||
|
POST /mcp # MCP JSON-RPC 2.0 端点
|
||||||
|
```
|
||||||
|
|
||||||
|
## 4. 数据库设计
|
||||||
|
|
||||||
|
### 4.1 核心表结构
|
||||||
|
|
||||||
|
#### Tasks 表
|
||||||
|
```sql
|
||||||
|
CREATE TABLE T_Tasks (
|
||||||
|
Id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||||
|
UserId TEXT NOT NULL,
|
||||||
|
Title TEXT NOT NULL,
|
||||||
|
Priority INTEGER NOT NULL DEFAULT 0,
|
||||||
|
IsCompleted INTEGER NOT NULL DEFAULT 0,
|
||||||
|
ParentTaskId INTEGER,
|
||||||
|
CreatedAt TEXT NOT NULL,
|
||||||
|
UpdatedAt TEXT NOT NULL
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Users 表
|
||||||
|
```sql
|
||||||
|
CREATE TABLE T_Users (
|
||||||
|
Id TEXT PRIMARY KEY,
|
||||||
|
UserName TEXT NOT NULL UNIQUE,
|
||||||
|
PasswordHash TEXT NOT NULL,
|
||||||
|
PasswordSalt TEXT NOT NULL,
|
||||||
|
Role TEXT NOT NULL,
|
||||||
|
MustChangePassword INTEGER NOT NULL DEFAULT 0
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
#### SecurityPolicies 表
|
||||||
|
```sql
|
||||||
|
CREATE TABLE T_SecurityPolicies (
|
||||||
|
Id TEXT PRIMARY KEY,
|
||||||
|
UserId TEXT NOT NULL,
|
||||||
|
AllowPersist INTEGER NOT NULL DEFAULT 1,
|
||||||
|
AllowSync INTEGER NOT NULL DEFAULT 1,
|
||||||
|
SecondFactorExpiryMinutes INTEGER DEFAULT 0,
|
||||||
|
IsTrustedDeviceOnly INTEGER NOT NULL DEFAULT 0
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
#### AuditLogs 表
|
||||||
|
```sql
|
||||||
|
CREATE TABLE T_AuditLogs (
|
||||||
|
Id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||||
|
UserId TEXT,
|
||||||
|
Action TEXT NOT NULL,
|
||||||
|
OccurredAtUtc TEXT NOT NULL,
|
||||||
|
Details TEXT
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4.2 数据访问策略
|
||||||
|
|
||||||
|
- 使用 Entity Framework Core 进行数据访问
|
||||||
|
- 采用 Repository 模式封装数据访问
|
||||||
|
- 支持 LINQ 查询和异步操作
|
||||||
|
- EF Core 迁移管理（见 `Hua.Todo.Application/Migrations/`）
|
||||||
|
- 表名遵循 ABP 规范：`T_{实体名}s`
|
||||||
|
|
||||||
|
## 5. 通信机制
|
||||||
|
|
||||||
|
### 5.1 HTTP 通信流程
|
||||||
|
|
||||||
|
1. **C# 后端启动**：MAUI/Avalonia 应用启动时启动本地 Kestrel 服务器
|
||||||
|
2. **Vue 前端加载**：WebView 加载 Vue 应用
|
||||||
|
3. **API 调用**：Vue 通过 Axios 调用本地 HTTP API
|
||||||
|
4. **数据处理**：C# 后端处理请求并返回 JSON 数据
|
||||||
|
5. **界面更新**：Vue 接收响应并更新界面
|
||||||
|
|
||||||
|
### 5.2 错误处理
|
||||||
|
|
||||||
|
- 统一的错误响应格式
|
||||||
|
- 异常中间件捕获和处理
|
||||||
|
- 前端错误提示和重试机制
|
||||||
|
|
||||||
|
### 5.3 WebView 注入
|
||||||
|
|
||||||
|
前端通过 `window` 对象接收宿主注入的信息：
|
||||||
|
- `window.__API_BASE_URL__`：API 基础路径
|
||||||
|
- `window.mauiInterop`：MAUI 平台互操作对象
|
||||||
|
|
||||||
|
## 6. 部署和打包
|
||||||
|
|
||||||
|
### 6.1 开发环境
|
||||||
|
|
||||||
|
- **后端调试**：使用 Visual Studio 调试 MAUI/Avalonia 应用
|
||||||
|
- **前端调试**：使用 Vite 开发服务器
|
||||||
|
- **热重载**：支持前后端热重载
|
||||||
|
|
||||||
|
### 6.2 生产构建
|
||||||
|
|
||||||
|
- **前端构建**：`npm run build` 生成静态文件
|
||||||
|
- **后端打包**：各平台发布脚本产出可分发包
|
||||||
|
- **静态文件嵌入**：将前端静态文件嵌入到桌面应用中
|
||||||
|
|
||||||
|
详细构建流程见 [06-开发环境与构建](./06-开发环境与构建.md)。
|
||||||
|
|
||||||
|
### 6.3 平台特定配置
|
||||||
|
|
||||||
|
- **Windows**：WebView2 运行时要求
|
||||||
|
- **macOS**：代码签名和公证
|
||||||
|
- **移动端**：应用商店发布配置
|
||||||
|
- **Linux**：需要 GTK + WebKitGTK 运行时依赖
|
||||||
|
|
||||||
|
## 7. 性能优化
|
||||||
|
|
||||||
|
### 7.1 前端优化
|
||||||
|
- 组件懒加载
|
||||||
|
- 虚拟滚动（长列表）
|
||||||
|
- 图片懒加载
|
||||||
|
- 缓存策略
|
||||||
|
|
||||||
|
### 7.2 后端优化
|
||||||
|
- 数据库查询优化（含索引策略）
|
||||||
|
- 响应缓存
|
||||||
|
- 异步处理
|
||||||
|
- SQLite WAL 模式（嵌入式宿主自动开启）
|
||||||
|
|
||||||
|
## 8. 安全考虑
|
||||||
|
|
||||||
|
### 8.1 本地安全
|
||||||
|
- 本地服务器仅监听 localhost
|
||||||
|
- 防止外部访问
|
||||||
|
- 数据加密存储（可选）
|
||||||
|
|
||||||
|
### 8.2 数据安全
|
||||||
|
- 数据库文件权限控制
|
||||||
|
- 定期备份机制
|
||||||
|
- 敏感数据保护
|
||||||
|
|
||||||
|
### 8.3 云同步安全
|
||||||
|
|
||||||
|
详见 [08-云同步规则](./08-云同步规则.md)。
|
||||||
|
|
||||||
|
## 9. 测试策略
|
||||||
|
|
||||||
|
### 9.1 单元测试
|
||||||
|
- 核心业务逻辑测试
|
||||||
|
- 服务层测试
|
||||||
|
- 工具函数测试
|
||||||
|
|
||||||
|
### 9.2 集成测试
|
||||||
|
- API 集成测试
|
||||||
|
- 数据库集成测试
|
||||||
|
- 前后端集成测试
|
||||||
|
|
||||||
|
### 9.3 端到端测试
|
||||||
|
- 跨平台功能测试
|
||||||
|
- 用户流程测试
|
||||||
|
- 性能测试
|
||||||
@@ -1,389 +0,0 @@
|
|||||||
# MCP 服务接口文档
|
|
||||||
|
|
||||||
> Hua.Todo MCP Server 接口规范，供外部系统（AI 客户端、第三方集成）通过 MCP 协议接入 Hua.Todo 待办项管理能力。
|
|
||||||
|
|
||||||
## 1. 概述
|
|
||||||
|
|
||||||
Hua.Todo 提供了基于 **Model Context Protocol (MCP)** 的服务端，允许外部 MCP 客户端通过 Streamable HTTP 传输协议发现并调用待办项管理工具。
|
|
||||||
|
|
||||||
### 1.1 协议与传输
|
|
||||||
|
|
||||||
| 项目 | 说明 |
|
|
||||||
|---|---|
|
|
||||||
| 协议版本 | MCP 2025-03-26（Streamable HTTP） |
|
|
||||||
| 传输方式 | Streamable HTTP（无状态模式） |
|
|
||||||
| 内容格式 | JSON-RPC 2.0 |
|
|
||||||
| 端点路径 | `/mcp` |
|
|
||||||
| 认证 | 暂无（本地模式）；生产环境建议通过反向代理添加认证 |
|
|
||||||
|
|
||||||
### 1.2 服务端信息
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"name": "Hua.Todo MCP Server",
|
|
||||||
"version": "1.0.0"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### 1.3 连接地址
|
|
||||||
|
|
||||||
| 运行模式 | 默认地址 |
|
|
||||||
|---|---|
|
|
||||||
| Hua.Todo.Host（独立服务端） | `http://localhost:5173/mcp` |
|
|
||||||
| MAUI / Avalonia（嵌入式） | `http://localhost:5057/mcp` |
|
|
||||||
|
|
||||||
> 实际端口以部署配置为准。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 2. 接入方式
|
|
||||||
|
|
||||||
### 2.1 MCP 客户端配置示例
|
|
||||||
|
|
||||||
**Claude Desktop / Cursor / 其他 MCP 客户端** 配置文件（`mcp_servers.json` 或等效）：
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"mcpServers": {
|
|
||||||
"hua-todo": {
|
|
||||||
"url": "http://localhost:5173/mcp",
|
|
||||||
"transport": "streamable-http"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2.2 手动调用示例（curl）
|
|
||||||
|
|
||||||
MCP 协议基于 JSON-RPC 2.0，可通过 HTTP POST 手动调用：
|
|
||||||
|
|
||||||
#### 初始化连接
|
|
||||||
|
|
||||||
```bash
|
|
||||||
curl -X POST http://localhost:5173/mcp \
|
|
||||||
-H "Content-Type: application/json" \
|
|
||||||
-H "MCP-Protocol-Version: 2025-03-26" \
|
|
||||||
-d '{
|
|
||||||
"jsonrpc": "2.0",
|
|
||||||
"id": 1,
|
|
||||||
"method": "initialize",
|
|
||||||
"params": {
|
|
||||||
"protocolVersion": "2025-03-26",
|
|
||||||
"capabilities": {},
|
|
||||||
"clientInfo": { "name": "my-client", "version": "1.0.0" }
|
|
||||||
}
|
|
||||||
}'
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 列出可用工具
|
|
||||||
|
|
||||||
```bash
|
|
||||||
curl -X POST http://localhost:5173/mcp \
|
|
||||||
-H "Content-Type: application/json" \
|
|
||||||
-H "MCP-Protocol-Version: 2025-03-26" \
|
|
||||||
-d '{
|
|
||||||
"jsonrpc": "2.0",
|
|
||||||
"id": 2,
|
|
||||||
"method": "tools/list",
|
|
||||||
"params": {}
|
|
||||||
}'
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 调用工具
|
|
||||||
|
|
||||||
```bash
|
|
||||||
curl -X POST http://localhost:5173/mcp \
|
|
||||||
-H "Content-Type: application/json" \
|
|
||||||
-H "MCP-Protocol-Version: 2025-03-26" \
|
|
||||||
-d '{
|
|
||||||
"jsonrpc": "2.0",
|
|
||||||
"id": 3,
|
|
||||||
"method": "tools/call",
|
|
||||||
"params": {
|
|
||||||
"name": "CreateTodo",
|
|
||||||
"arguments": {
|
|
||||||
"title": "完成项目报告",
|
|
||||||
"priority": "High"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}'
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 3. 工具清单
|
|
||||||
|
|
||||||
### 3.1 查询类工具
|
|
||||||
|
|
||||||
#### ListAllTodos
|
|
||||||
|
|
||||||
获取所有待办项列表（含已完成和未完成）。
|
|
||||||
|
|
||||||
| 参数 | 类型 | 必填 | 说明 |
|
|
||||||
|---|---|---|---|
|
|
||||||
| 无 | - | - | - |
|
|
||||||
|
|
||||||
**返回示例**：
|
|
||||||
|
|
||||||
```
|
|
||||||
所有待办项（共 3 项）：
|
|
||||||
[1] 完成项目报告 | 优先级:High | 进行中
|
|
||||||
[2] 购买办公用品 | 优先级:Medium | 已完成
|
|
||||||
[3] 整理会议纪要 | 优先级:Low | 进行中
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
#### ListActiveTodos
|
|
||||||
|
|
||||||
获取未完成的待办项列表。
|
|
||||||
|
|
||||||
| 参数 | 类型 | 必填 | 说明 |
|
|
||||||
|---|---|---|---|
|
|
||||||
| 无 | - | - | - |
|
|
||||||
|
|
||||||
**返回示例**：
|
|
||||||
|
|
||||||
```
|
|
||||||
未完成待办项（共 2 项）：
|
|
||||||
[1] 完成项目报告 | 优先级:High | 进行中
|
|
||||||
[3] 整理会议纪要 | 优先级:Low | 进行中
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
#### ListCompletedTodos
|
|
||||||
|
|
||||||
获取已完成的待办项列表。
|
|
||||||
|
|
||||||
| 参数 | 类型 | 必填 | 说明 |
|
|
||||||
|---|---|---|---|
|
|
||||||
| 无 | - | - | - |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
#### GetTodoById
|
|
||||||
|
|
||||||
根据 ID 获取单个待办项详情（含子任务）。
|
|
||||||
|
|
||||||
| 参数 | 类型 | 必填 | 说明 |
|
|
||||||
|---|---|---|---|
|
|
||||||
| `id` | `int` | 是 | 待办项 ID |
|
|
||||||
|
|
||||||
**返回示例**：
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"id": 1,
|
|
||||||
"title": "完成项目报告",
|
|
||||||
"priority": "High",
|
|
||||||
"isCompleted": false,
|
|
||||||
"createdAt": "2026-06-16T08:30:00Z",
|
|
||||||
"updatedAt": "2026-06-16T08:30:00Z",
|
|
||||||
"parentTaskId": null,
|
|
||||||
"subTasks": [
|
|
||||||
{
|
|
||||||
"id": 4,
|
|
||||||
"title": "收集数据",
|
|
||||||
"priority": "Medium",
|
|
||||||
"isCompleted": true,
|
|
||||||
"createdAt": "2026-06-16T08:35:00Z",
|
|
||||||
"updatedAt": "2026-06-16T10:00:00Z",
|
|
||||||
"parentTaskId": 1,
|
|
||||||
"subTasks": []
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**未找到时**：返回文本 `"未找到 ID 为 {id} 的待办项"`
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
#### ListSubTodos
|
|
||||||
|
|
||||||
获取指定父待办项下的所有子待办项。
|
|
||||||
|
|
||||||
| 参数 | 类型 | 必填 | 说明 |
|
|
||||||
|---|---|---|---|
|
|
||||||
| `parentTaskId` | `int` | 是 | 父待办项 ID |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 3.2 写入类工具
|
|
||||||
|
|
||||||
#### CreateTodo
|
|
||||||
|
|
||||||
创建新的待办项。
|
|
||||||
|
|
||||||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
|
||||||
|---|---|---|---|---|
|
|
||||||
| `title` | `string` | 是 | - | 待办项标题 |
|
|
||||||
| `priority` | `string` | 否 | `"Medium"` | 优先级：`Low` / `Medium` / `High` |
|
|
||||||
| `parentTaskId` | `int` | 否 | `null` | 父待办项 ID（创建子任务时传入） |
|
|
||||||
|
|
||||||
**返回示例**：
|
|
||||||
|
|
||||||
```
|
|
||||||
已创建待办项：
|
|
||||||
{
|
|
||||||
"id": 5,
|
|
||||||
"title": "完成项目报告",
|
|
||||||
"priority": "High",
|
|
||||||
"isCompleted": false,
|
|
||||||
"createdAt": "2026-06-16T10:00:00Z",
|
|
||||||
"updatedAt": "2026-06-16T10:00:00Z",
|
|
||||||
"parentTaskId": null,
|
|
||||||
"subTasks": []
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**优先级无效时**：返回文本 `"无效的优先级 'xxx'，有效值为：Low、Medium、High"`
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
#### UpdateTodo
|
|
||||||
|
|
||||||
更新已有待办项的标题或优先级。
|
|
||||||
|
|
||||||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
|
||||||
|---|---|---|---|---|
|
|
||||||
| `id` | `int` | 是 | - | 待办项 ID |
|
|
||||||
| `title` | `string` | 否 | `null` | 新标题 |
|
|
||||||
| `priority` | `string` | 否 | `null` | 新优先级：`Low` / `Medium` / `High` |
|
|
||||||
|
|
||||||
**未找到时**：返回文本 `"未找到 ID 为 {id} 的待办项"`
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
#### ToggleTodoComplete
|
|
||||||
|
|
||||||
切换待办项的完成状态（已完成 ↔ 未完成）。
|
|
||||||
|
|
||||||
| 参数 | 类型 | 必填 | 说明 |
|
|
||||||
|---|---|---|---|
|
|
||||||
| `id` | `int` | 是 | 待办项 ID |
|
|
||||||
|
|
||||||
**返回示例**：
|
|
||||||
|
|
||||||
```
|
|
||||||
已切换完成状态：
|
|
||||||
{
|
|
||||||
"id": 1,
|
|
||||||
"title": "完成项目报告",
|
|
||||||
"priority": "High",
|
|
||||||
"isCompleted": true,
|
|
||||||
...
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
#### DeleteTodo
|
|
||||||
|
|
||||||
删除指定待办项。
|
|
||||||
|
|
||||||
| 参数 | 类型 | 必填 | 说明 |
|
|
||||||
|---|---|---|---|
|
|
||||||
| `id` | `int` | 是 | 待办项 ID |
|
|
||||||
|
|
||||||
**成功时**：返回文本 `"已删除待办项 {id}"`
|
|
||||||
|
|
||||||
**未找到时**：返回文本 `"未找到 ID 为 {id} 的待办项"`
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 4. 数据类型定义
|
|
||||||
|
|
||||||
### 4.1 TaskDto（待办项）
|
|
||||||
|
|
||||||
| 字段 | 类型 | 说明 |
|
|
||||||
|---|---|---|
|
|
||||||
| `id` | `int` | 唯一标识符 |
|
|
||||||
| `title` | `string` | 标题 |
|
|
||||||
| `priority` | `string` | 优先级枚举值：`"Low"` / `"Medium"` / `"High"` |
|
|
||||||
| `isCompleted` | `bool` | 是否已完成 |
|
|
||||||
| `createdAt` | `string` | 创建时间（ISO 8601 UTC） |
|
|
||||||
| `updatedAt` | `string` | 更新时间（ISO 8601 UTC） |
|
|
||||||
| `parentTaskId` | `int?` | 父待办项 ID（顶层任务为 null） |
|
|
||||||
| `subTasks` | `TaskDto[]` | 子任务列表（递归结构） |
|
|
||||||
|
|
||||||
### 4.2 优先级枚举
|
|
||||||
|
|
||||||
| 值 | 说明 |
|
|
||||||
|---|---|
|
|
||||||
| `"Low"` | 低优先级 |
|
|
||||||
| `"Medium"` | 中优先级（默认） |
|
|
||||||
| `"High"` | 高优先级 |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 5. 错误处理
|
|
||||||
|
|
||||||
MCP 工具调用中的错误通过返回文本内容表达（而非 MCP 协议级错误），常见情况：
|
|
||||||
|
|
||||||
| 场景 | 返回内容 |
|
|
||||||
|---|---|
|
|
||||||
| 待办项不存在 | `"未找到 ID 为 {id} 的待办项"` |
|
|
||||||
| 优先级值无效 | `"无效的优先级 'xxx'，有效值为：Low、Medium、High"` |
|
|
||||||
| 列表为空 | `"没有{label}"` |
|
|
||||||
|
|
||||||
MCP 协议级错误（如方法不存在、参数格式错误）遵循 JSON-RPC 2.0 标准：
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"jsonrpc": "2.0",
|
|
||||||
"id": 1,
|
|
||||||
"error": {
|
|
||||||
"code": -32600,
|
|
||||||
"message": "Invalid Request"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 6. 与 HTTP API 的对照
|
|
||||||
|
|
||||||
MCP 工具与原有 HTTP Dynamic API 的对应关系：
|
|
||||||
|
|
||||||
| MCP 工具 | HTTP API | 说明 |
|
|
||||||
|---|---|---|
|
|
||||||
| `ListAllTodos` | `GET /api/task` | 获取全部 |
|
|
||||||
| `ListActiveTodos` | `GET /api/task/active` | 获取未完成 |
|
|
||||||
| `ListCompletedTodos` | `GET /api/task/completed` | 获取已完成 |
|
|
||||||
| `GetTodoById` | `GET /api/task/{id}` | 按 ID 查询 |
|
|
||||||
| `CreateTodo` | `POST /api/task` | 创建 |
|
|
||||||
| `UpdateTodo` | `PUT /api/task` | 更新 |
|
|
||||||
| `ToggleTodoComplete` | `PATCH /api/task/{id}/toggle` | 切换完成 |
|
|
||||||
| `DeleteTodo` | `DELETE /api/task/{id}` | 删除 |
|
|
||||||
| `ListSubTodos` | `GET /api/task/{parentTaskId}/subtasks` | 子任务 |
|
|
||||||
|
|
||||||
> 两套 API 共享同一 `ITaskService` 实现，数据完全一致，可根据场景选择使用。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 7. 安全建议（生产部署）
|
|
||||||
|
|
||||||
1. **网络隔离**：MCP 端点默认无认证，建议仅在可信网络内暴露，或通过反向代理添加 API Key / Bearer Token 认证
|
|
||||||
2. **CORS 限制**：生产环境应将 CORS 策略从 `AllowAll` 改为指定来源
|
|
||||||
3. **HTTPS**：生产环境必须启用 HTTPS
|
|
||||||
4. **速率限制**：建议对 MCP 端点添加请求速率限制
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 8. 常见问题
|
|
||||||
|
|
||||||
### Q: MCP 端点和 HTTP API 可以同时使用吗？
|
|
||||||
可以。两者共享相同的数据源和服务层，不存在冲突。
|
|
||||||
|
|
||||||
### Q: Streamable HTTP 无状态模式下支持服务端通知吗？
|
|
||||||
不支持。无状态模式下服务端无法向客户端主动推送通知。如需通知能力，需改为有状态模式（`Stateless = false`），但需要会话亲和。
|
|
||||||
|
|
||||||
### Q: 如何验证 MCP 服务是否正常运行？
|
|
||||||
发送 `initialize` 请求（见 2.2 节），若返回服务端信息则表示正常。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**文档版本**：1.0.0
|
|
||||||
**最后更新**：2026-06-16
|
|
||||||
@@ -1,6 +1,6 @@
|
|||||||
# Todo 待办项云同步规则
|
# Todo 待办项云同步规则
|
||||||
|
|
||||||
> 本文档汇总 Hua.Todo 项目的 Todo 待办项云同步完整规则，涵盖架构、API 契约、认证鉴权、同步工作流、安全策略与可控落盘等。
|
> 本文档面向开发者，汇总 Hua.Todo 项目的云同步完整规则，涵盖架构、API 契约、认证鉴权、同步工作流、安全策略与可控落盘等。
|
||||||
>
|
>
|
||||||
> 术语：本文中"任务 / Todo 待办项"均为业务实体（对应代码 `Task` / `SubTask` / `TaskEntity`），与编码侧的"研发工单"无关。
|
> 术语：本文中"任务 / Todo 待办项"均为业务实体（对应代码 `Task` / `SubTask` / `TaskEntity`），与编码侧的"研发工单"无关。
|
||||||
|
|
||||||
@@ -509,4 +509,4 @@ Hua.Todo.Application (共享层)
|
|||||||
> - 安全与可控落盘：[06-CloudSync-安全与可控落盘.md](../project/研发工单-v1.2.0/06-CloudSync-安全与可控落盘.md)
|
> - 安全与可控落盘：[06-CloudSync-安全与可控落盘.md](../project/研发工单-v1.2.0/06-CloudSync-安全与可控落盘.md)
|
||||||
> - 安全设计方案：[06.1-CloudSync-服务端安全设计方案.md](../project/研发工单-v1.2.0/06.1-CloudSync-服务端安全设计方案.md)
|
> - 安全设计方案：[06.1-CloudSync-服务端安全设计方案.md](../project/研发工单-v1.2.0/06.1-CloudSync-服务端安全设计方案.md)
|
||||||
> - 同源 Host 重构：[08-cloud_sync_refactor_plan.md](../project/研发工单-v1.2.0/08-cloud_sync_refactor_plan.md)
|
> - 同源 Host 重构：[08-cloud_sync_refactor_plan.md](../project/研发工单-v1.2.0/08-cloud_sync_refactor_plan.md)
|
||||||
> - 技术设计文档：[技术设计文档.md](./01-技术设计文档.md)
|
> - 技术架构设计：[07-技术架构设计](./07-技术架构设计.md)
|
||||||
@@ -1,210 +0,0 @@
|
|||||||
# MCP 前端集成指南（Hua.Todo 内部使用）
|
|
||||||
|
|
||||||
> 适用范围：Hua.Todo 前端（Vue / TypeScript）团队，通过 MCP 协议与后端交互。
|
|
||||||
> 外部系统接入请参阅 [08-MCP服务接口文档.md](./08-MCP服务接口文档.md)。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 一、背景
|
|
||||||
|
|
||||||
v1.3.0 起，Hua.Todo 后端在原有 Dynamic API（`/api/*`）基础上，新增了 MCP（Model Context Protocol）服务端点。前端可根据场景选择：
|
|
||||||
|
|
||||||
| 通道 | 端点 | 适用场景 |
|
|
||||||
|---|---|---|
|
|
||||||
| Dynamic API | `/api/task/*` | WebView 内常规 CRUD、已有逻辑兼容 |
|
|
||||||
| MCP | `/mcp` | AI 辅助、语音指令、外部工具集成 |
|
|
||||||
|
|
||||||
两套通道共享同一 `ITaskService` 业务层，数据一致。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 二、连接方式
|
|
||||||
|
|
||||||
### 2.1 嵌入式模式（MAUI / Avalonia + WebView）
|
|
||||||
|
|
||||||
```
|
|
||||||
MCP 端点：http://localhost:5057/mcp
|
|
||||||
```
|
|
||||||
|
|
||||||
当前嵌入式宿主**仅暴露 Dynamic API**，MCP 端点在嵌入式模式下同样可用（`AddMcpServerServices` 已注册）。
|
|
||||||
|
|
||||||
### 2.2 Host 模式（独立服务端）
|
|
||||||
|
|
||||||
```
|
|
||||||
MCP 端点：http://<host>:5173/mcp
|
|
||||||
```
|
|
||||||
|
|
||||||
开发环境通过 Vite proxy 可直接访问 `/mcp`。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 三、前端 MCP 客户端选型
|
|
||||||
|
|
||||||
### 3.1 推荐方案：`@modelcontextprotocol/sdk`
|
|
||||||
|
|
||||||
官方 TypeScript MCP SDK，支持 Streamable HTTP 传输。
|
|
||||||
|
|
||||||
```bash
|
|
||||||
npm install @modelcontextprotocol/sdk
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3.2 连接示例
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
|
|
||||||
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamablehttp.js";
|
|
||||||
|
|
||||||
const transport = new StreamableHTTPClientTransport(
|
|
||||||
new URL("http://localhost:5057/mcp")
|
|
||||||
);
|
|
||||||
|
|
||||||
const client = new Client({
|
|
||||||
name: "hua-todo-frontend",
|
|
||||||
version: "1.3.0",
|
|
||||||
});
|
|
||||||
|
|
||||||
await client.connect(transport);
|
|
||||||
|
|
||||||
// 列出所有可用工具
|
|
||||||
const tools = await client.listTools();
|
|
||||||
console.log("可用工具:", tools);
|
|
||||||
|
|
||||||
// 调用工具
|
|
||||||
const result = await client.callTool({
|
|
||||||
name: "ListActiveTodos",
|
|
||||||
arguments: {},
|
|
||||||
});
|
|
||||||
console.log("未完成待办项:", result);
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3.3 封装建议
|
|
||||||
|
|
||||||
在 `src/Hua.Todo.Web/src/api/` 下新增 `mcpClient.ts`：
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
// src/api/mcpClient.ts
|
|
||||||
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
|
|
||||||
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamablehttp.js";
|
|
||||||
|
|
||||||
const MCP_BASE_URL = window.__API_BASE_URL__
|
|
||||||
? window.__API_BASE_URL__.replace("/api", "/mcp")
|
|
||||||
: "/mcp";
|
|
||||||
|
|
||||||
let client: Client | null = null;
|
|
||||||
|
|
||||||
/** 获取或创建 MCP 客户端单例 */
|
|
||||||
export async function getMcpClient(): Promise<Client> {
|
|
||||||
if (!client) {
|
|
||||||
const transport = new StreamableHTTPClientTransport(
|
|
||||||
new URL(MCP_BASE_URL, window.location.origin)
|
|
||||||
);
|
|
||||||
client = new Client({
|
|
||||||
name: "hua-todo-frontend",
|
|
||||||
version: "1.3.0",
|
|
||||||
});
|
|
||||||
await client.connect(transport);
|
|
||||||
}
|
|
||||||
return client;
|
|
||||||
}
|
|
||||||
|
|
||||||
/** 断开 MCP 连接 */
|
|
||||||
export async function disconnectMcp(): Promise<void> {
|
|
||||||
if (client) {
|
|
||||||
await client.close();
|
|
||||||
client = null;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 四、工具调用映射（MCP vs Dynamic API）
|
|
||||||
|
|
||||||
| 业务操作 | Dynamic API | MCP Tool | MCP 参数 |
|
|
||||||
|---|---|---|---|
|
|
||||||
| 获取所有待办项 | `GET /api/task` | `ListAllTodos` | 无 |
|
|
||||||
| 获取未完成待办项 | `GET /api/task/active` | `ListActiveTodos` | 无 |
|
|
||||||
| 获取已完成待办项 | `GET /api/task/completed` | `ListCompletedTodos` | 无 |
|
|
||||||
| 获取单个待办项 | `GET /api/task/{id}` | `GetTodoById` | `id: number` |
|
|
||||||
| 创建待办项 | `POST /api/task` | `CreateTodo` | `title, priority?, parentTaskId?` |
|
|
||||||
| 更新待办项 | `PUT /api/task` | `UpdateTodo` | `id, title?, priority?` |
|
|
||||||
| 切换完成状态 | `PATCH /api/task/{id}/toggle` | `ToggleTodoComplete` | `id: number` |
|
|
||||||
| 删除待办项 | `DELETE /api/task/{id}` | `DeleteTodo` | `id: number` |
|
|
||||||
| 获取子待办项 | `GET /api/task/{pid}/subtasks` | `ListSubTodos` | `parentTaskId: number` |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 五、返回格式差异
|
|
||||||
|
|
||||||
### Dynamic API 返回
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": true,
|
|
||||||
"data": [{ "id": 1, "title": "...", ... }],
|
|
||||||
"message": "",
|
|
||||||
"errors": []
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### MCP Tool 返回
|
|
||||||
|
|
||||||
MCP 工具返回 `string` 类型，分两种格式：
|
|
||||||
|
|
||||||
**列表类**（可读文本）：
|
|
||||||
```
|
|
||||||
未完成待办项（共 2 项）：
|
|
||||||
[1] 完成报告 | 优先级:High | 进行中
|
|
||||||
[3] 买菜 | 优先级:Low | 进行中 | 父ID:2
|
|
||||||
```
|
|
||||||
|
|
||||||
**单条/创建/更新类**（JSON）：
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"id": 1,
|
|
||||||
"title": "完成报告",
|
|
||||||
"priority": "High",
|
|
||||||
"isCompleted": false,
|
|
||||||
"createdAt": "2026-06-16T08:00:00Z",
|
|
||||||
"updatedAt": "2026-06-16T08:00:00Z",
|
|
||||||
"parentTaskId": null,
|
|
||||||
"subTasks": []
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
> 前端如果需要结构化数据，建议仍使用 Dynamic API；MCP 通道主要用于 AI 场景和文本交互。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 六、典型场景
|
|
||||||
|
|
||||||
### 6.1 AI 对话式操作
|
|
||||||
|
|
||||||
用户通过 AI 助手（接入 MCP 的 LLM 客户端）用自然语言操作待办项：
|
|
||||||
|
|
||||||
```
|
|
||||||
用户：帮我看看还有哪些事没做完
|
|
||||||
AI：→ 调用 ListActiveTodos
|
|
||||||
AI：您有 2 项未完成的待办：[1] 完成报告 [3] 买菜
|
|
||||||
|
|
||||||
用户：把"完成报告"标为已完成
|
|
||||||
AI：→ 调用 ToggleTodoComplete(id=1)
|
|
||||||
AI：已将"完成报告"标记为完成
|
|
||||||
```
|
|
||||||
|
|
||||||
### 6.2 语音指令
|
|
||||||
|
|
||||||
语音 → STT → 文本 → LLM 解析意图 → MCP Tool 调用 → TTS 播报结果。
|
|
||||||
|
|
||||||
### 6.3 外部工具集成
|
|
||||||
|
|
||||||
IDE 插件、自动化脚本等通过 MCP 协议直接操作待办项，无需理解 HTTP API 细节。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 七、注意事项
|
|
||||||
|
|
||||||
1. **MCP 无状态模式**：当前配置为 Stateless，不支持服务端→客户端通知；如需实时推送仍走 Dynamic API 或 WebSocket
|
|
||||||
2. **CORS**：开发环境 `AllowAll` 策略已覆盖 `/mcp`；生产环境需按需配置
|
|
||||||
3. **认证**：当前 MCP 端点未接入认证中间件；如需鉴权，需在 `MapMcpServer` 后追加 `.RequireAuthorization()`
|
|
||||||
4. **生命周期**：MCP 客户端连接为长连接，建议在组件 `onUnmounted` 时调用 `disconnectMcp()`
|
|
||||||
@@ -1,4 +1,6 @@
|
|||||||
# Hua.Todo 代码规范文档 v1.2.8
|
# 代码规范
|
||||||
|
|
||||||
|
> 本文档面向开发者，定义 Hua.Todo 项目的编码规范。
|
||||||
|
|
||||||
## 1. 概述
|
## 1. 概述
|
||||||
本文档定义 Hua.Todo 项目的代码规范，包括 C#、JavaScript/TypeScript、Vue.js 和其他相关技术的编码标准。遵循这些规范有助于提高代码质量、可读性和可维护性。
|
本文档定义 Hua.Todo 项目的代码规范，包括 C#、JavaScript/TypeScript、Vue.js 和其他相关技术的编码标准。遵循这些规范有助于提高代码质量、可读性和可维护性。
|
||||||
@@ -29,7 +31,7 @@
|
|||||||
### 3.1 跨平台逻辑规范
|
### 3.1 跨平台逻辑规范
|
||||||
- **禁止混写 `#if`**：禁止在同一文件内混写多个平台的大段 `#if` 实现。
|
- **禁止混写 `#if`**：禁止在同一文件内混写多个平台的大段 `#if` 实现。
|
||||||
- **优先使用 partial/接口**：应优先使用 `partial` 类、接口与平台目录分离。
|
- **优先使用 partial/接口**：应优先使用 `partial` 类、接口与平台目录分离。
|
||||||
- **说明平台差异**：平台分离后的公共入口处必须说明“平台差异在哪里、默认实现是什么、为什么这么做”。
|
- **说明平台差异**：平台分离后的公共入口处必须说明"平台差异在哪里、默认实现是什么、为什么这么做"。
|
||||||
|
|
||||||
### 3.2 异步/后台任务
|
### 3.2 异步/后台任务
|
||||||
- **必须说明启动时机、错误处理策略、是否需要 UI 线程、以及是否可并发/可重入**。
|
- **必须说明启动时机、错误处理策略、是否需要 UI 线程、以及是否可并发/可重入**。
|
||||||
@@ -78,7 +80,7 @@ public void CreateTask(string title, TaskPriority priority)
|
|||||||
public const int MaxTaskTitleLength = 200;
|
public const int MaxTaskTitleLength = 200;
|
||||||
```
|
```
|
||||||
|
|
||||||
### 3.2 代码组织
|
### 3.3 代码组织
|
||||||
|
|
||||||
#### 文件结构
|
#### 文件结构
|
||||||
```csharp
|
```csharp
|
||||||
@@ -124,7 +126,7 @@ public class TaskService : ITaskService
|
|||||||
- 命名空间结构应与目录结构一致
|
- 命名空间结构应与目录结构一致
|
||||||
- 使用 `.` 分隔层级
|
- 使用 `.` 分隔层级
|
||||||
|
|
||||||
### 3.3 编码规范
|
### 3.4 编码规范
|
||||||
|
|
||||||
#### 异步编程
|
#### 异步编程
|
||||||
```csharp
|
```csharp
|
||||||
@@ -191,7 +193,7 @@ var query = from task in tasks
|
|||||||
select task;
|
select task;
|
||||||
```
|
```
|
||||||
|
|
||||||
### 3.4 文档注释
|
### 3.5 文档注释
|
||||||
```csharp
|
```csharp
|
||||||
/// <summary>
|
/// <summary>
|
||||||
/// 获取指定 ID 的任务
|
/// 获取指定 ID 的任务
|
||||||
@@ -0,0 +1,311 @@
|
|||||||
|
# MCP 服务集成
|
||||||
|
|
||||||
|
> 本文档涵盖 Hua.Todo MCP 服务的两部分内容：面向外部系统的接口规范（Part A）与面向内部前端的集成指南（Part B）。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Part A：MCP 服务接口规范（外部系统接入）
|
||||||
|
|
||||||
|
### A.1 概述
|
||||||
|
|
||||||
|
Hua.Todo 提供了基于 **Model Context Protocol (MCP)** 的服务端，允许外部 MCP 客户端通过 Streamable HTTP 传输协议发现并调用待办项管理工具。
|
||||||
|
|
||||||
|
#### A.1.1 协议与传输
|
||||||
|
|
||||||
|
| 项目 | 说明 |
|
||||||
|
|---|---|
|
||||||
|
| 协议版本 | MCP 2025-03-26（Streamable HTTP） |
|
||||||
|
| 传输方式 | Streamable HTTP（无状态模式） |
|
||||||
|
| 内容格式 | JSON-RPC 2.0 |
|
||||||
|
| 端点路径 | `/mcp` |
|
||||||
|
| 认证 | 暂无（本地模式）；生产环境建议通过反向代理添加认证 |
|
||||||
|
|
||||||
|
#### A.1.2 服务端信息
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"name": "Hua.Todo MCP Server",
|
||||||
|
"version": "1.0.0"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### A.1.3 连接地址
|
||||||
|
|
||||||
|
| 运行模式 | 默认地址 |
|
||||||
|
|---|---|
|
||||||
|
| Hua.Todo.Host（独立服务端） | `http://localhost:5173/mcp` |
|
||||||
|
| MAUI / Avalonia（嵌入式） | `http://localhost:5057/mcp` |
|
||||||
|
|
||||||
|
### A.2 接入方式
|
||||||
|
|
||||||
|
#### A.2.1 MCP 客户端配置示例
|
||||||
|
|
||||||
|
**Claude Desktop / Cursor / 其他 MCP 客户端** 配置文件：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"hua-todo": {
|
||||||
|
"url": "http://localhost:5173/mcp",
|
||||||
|
"transport": "streamable-http"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### A.2.2 手动调用示例（curl）
|
||||||
|
|
||||||
|
**初始化连接**：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -X POST http://localhost:5173/mcp \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-H "MCP-Protocol-Version: 2025-03-26" \
|
||||||
|
-d '{
|
||||||
|
"jsonrpc": "2.0", "id": 1, "method": "initialize",
|
||||||
|
"params": {
|
||||||
|
"protocolVersion": "2025-03-26",
|
||||||
|
"capabilities": {},
|
||||||
|
"clientInfo": { "name": "my-client", "version": "1.0.0" }
|
||||||
|
}
|
||||||
|
}'
|
||||||
|
```
|
||||||
|
|
||||||
|
**列出可用工具**：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -X POST http://localhost:5173/mcp \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-H "MCP-Protocol-Version: 2025-03-26" \
|
||||||
|
-d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}'
|
||||||
|
```
|
||||||
|
|
||||||
|
**调用工具**：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -X POST http://localhost:5173/mcp \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-H "MCP-Protocol-Version: 2025-03-26" \
|
||||||
|
-d '{
|
||||||
|
"jsonrpc": "2.0", "id": 3, "method": "tools/call",
|
||||||
|
"params": { "name": "CreateTodo", "arguments": { "title": "完成项目报告", "priority": "High" } }
|
||||||
|
}'
|
||||||
|
```
|
||||||
|
|
||||||
|
### A.3 工具清单
|
||||||
|
|
||||||
|
#### A.3.1 查询类工具
|
||||||
|
|
||||||
|
**ListAllTodos** — 获取所有待办项列表（含已完成和未完成），无参数。
|
||||||
|
|
||||||
|
**ListActiveTodos** — 获取未完成的待办项列表，无参数。
|
||||||
|
|
||||||
|
**ListCompletedTodos** — 获取已完成的待办项列表，无参数。
|
||||||
|
|
||||||
|
**GetTodoById** — 根据 ID 获取单个待办项详情（含子任务）。
|
||||||
|
|
||||||
|
| 参数 | 类型 | 必填 | 说明 |
|
||||||
|
|---|---|---|---|
|
||||||
|
| `id` | `int` | 是 | 待办项 ID |
|
||||||
|
|
||||||
|
**返回示例**：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"id": 1, "title": "完成项目报告", "priority": "High",
|
||||||
|
"isCompleted": false, "createdAt": "2026-06-16T08:30:00Z",
|
||||||
|
"updatedAt": "2026-06-16T08:30:00Z", "parentTaskId": null,
|
||||||
|
"subTasks": [{ "id": 4, "title": "收集数据", "priority": "Medium", "isCompleted": true, "parentTaskId": 1, "subTasks": [] }]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**ListSubTodos** — 获取指定父待办项下的所有子待办项。
|
||||||
|
|
||||||
|
| 参数 | 类型 | 必填 | 说明 |
|
||||||
|
|---|---|---|---|
|
||||||
|
| `parentTaskId` | `int` | 是 | 父待办项 ID |
|
||||||
|
|
||||||
|
#### A.3.2 写入类工具
|
||||||
|
|
||||||
|
**CreateTodo** — 创建新的待办项。
|
||||||
|
|
||||||
|
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||||||
|
|---|---|---|---|---|
|
||||||
|
| `title` | `string` | 是 | - | 待办项标题 |
|
||||||
|
| `priority` | `string` | 否 | `"Medium"` | 优先级：`Low` / `Medium` / `High` |
|
||||||
|
| `parentTaskId` | `int` | 否 | `null` | 父待办项 ID |
|
||||||
|
|
||||||
|
**UpdateTodo** — 更新已有待办项的标题或优先级。
|
||||||
|
|
||||||
|
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||||||
|
|---|---|---|---|---|
|
||||||
|
| `id` | `int` | 是 | - | 待办项 ID |
|
||||||
|
| `title` | `string` | 否 | `null` | 新标题 |
|
||||||
|
| `priority` | `string` | 否 | `null` | 新优先级 |
|
||||||
|
|
||||||
|
**ToggleTodoComplete** — 切换待办项的完成状态。
|
||||||
|
|
||||||
|
| 参数 | 类型 | 必填 | 说明 |
|
||||||
|
|---|---|---|---|
|
||||||
|
| `id` | `int` | 是 | 待办项 ID |
|
||||||
|
|
||||||
|
**DeleteTodo** — 删除指定待办项。
|
||||||
|
|
||||||
|
| 参数 | 类型 | 必填 | 说明 |
|
||||||
|
|---|---|---|---|
|
||||||
|
| `id` | `int` | 是 | 待办项 ID |
|
||||||
|
|
||||||
|
### A.4 数据类型定义
|
||||||
|
|
||||||
|
#### TaskDto（待办项）
|
||||||
|
|
||||||
|
| 字段 | 类型 | 说明 |
|
||||||
|
|---|---|---|
|
||||||
|
| `id` | `int` | 唯一标识符 |
|
||||||
|
| `title` | `string` | 标题 |
|
||||||
|
| `priority` | `string` | `"Low"` / `"Medium"` / `"High"` |
|
||||||
|
| `isCompleted` | `bool` | 是否已完成 |
|
||||||
|
| `createdAt` | `string` | 创建时间（ISO 8601 UTC） |
|
||||||
|
| `updatedAt` | `string` | 更新时间（ISO 8601 UTC） |
|
||||||
|
| `parentTaskId` | `int?` | 父待办项 ID |
|
||||||
|
| `subTasks` | `TaskDto[]` | 子任务列表 |
|
||||||
|
|
||||||
|
### A.5 与 HTTP API 的对照
|
||||||
|
|
||||||
|
| MCP 工具 | HTTP API | 说明 |
|
||||||
|
|---|---|---|
|
||||||
|
| `ListAllTodos` | `GET /api/task` | 获取全部 |
|
||||||
|
| `ListActiveTodos` | `GET /api/task/active` | 获取未完成 |
|
||||||
|
| `ListCompletedTodos` | `GET /api/task/completed` | 获取已完成 |
|
||||||
|
| `GetTodoById` | `GET /api/task/{id}` | 按 ID 查询 |
|
||||||
|
| `CreateTodo` | `POST /api/task` | 创建 |
|
||||||
|
| `UpdateTodo` | `PUT /api/task` | 更新 |
|
||||||
|
| `ToggleTodoComplete` | `PATCH /api/task/{id}/toggle` | 切换完成 |
|
||||||
|
| `DeleteTodo` | `DELETE /api/task/{id}` | 删除 |
|
||||||
|
| `ListSubTodos` | `GET /api/task/{parentTaskId}/subtasks` | 子任务 |
|
||||||
|
|
||||||
|
> 两套 API 共享同一 `ITaskService` 实现，数据完全一致。
|
||||||
|
|
||||||
|
### A.6 安全建议（生产部署）
|
||||||
|
|
||||||
|
1. **网络隔离**：MCP 端点默认无认证，建议仅在可信网络内暴露，或通过反向代理添加认证
|
||||||
|
2. **CORS 限制**：生产环境应将 CORS 策略从 `AllowAll` 改为指定来源
|
||||||
|
3. **HTTPS**：生产环境必须启用 HTTPS
|
||||||
|
4. **速率限制**：建议对 MCP 端点添加请求速率限制
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Part B：MCP 前端集成指南（内部使用）
|
||||||
|
|
||||||
|
> 适用范围：Hua.Todo 前端（Vue / TypeScript）团队。
|
||||||
|
|
||||||
|
### B.1 背景
|
||||||
|
|
||||||
|
v1.3.0 起，Hua.Todo 后端在原有 Dynamic API（`/api/*`）基础上，新增了 MCP 服务端点。前端可根据场景选择：
|
||||||
|
|
||||||
|
| 通道 | 端点 | 适用场景 |
|
||||||
|
|---|---|---|
|
||||||
|
| Dynamic API | `/api/task/*` | WebView 内常规 CRUD、已有逻辑兼容 |
|
||||||
|
| MCP | `/mcp` | AI 辅助、语音指令、外部工具集成 |
|
||||||
|
|
||||||
|
两套通道共享同一 `ITaskService` 业务层，数据一致。
|
||||||
|
|
||||||
|
### B.2 连接方式
|
||||||
|
|
||||||
|
| 模式 | MCP 端点 |
|
||||||
|
|---|---|
|
||||||
|
| 嵌入式（MAUI / Avalonia） | `http://localhost:5057/mcp` |
|
||||||
|
| Host（独立服务端） | `http://<host>:5173/mcp` |
|
||||||
|
|
||||||
|
### B.3 前端 MCP 客户端
|
||||||
|
|
||||||
|
推荐使用官方 TypeScript MCP SDK：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm install @modelcontextprotocol/sdk
|
||||||
|
```
|
||||||
|
|
||||||
|
**连接示例**：
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
|
||||||
|
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamablehttp.js";
|
||||||
|
|
||||||
|
const transport = new StreamableHTTPClientTransport(
|
||||||
|
new URL("http://localhost:5057/mcp")
|
||||||
|
);
|
||||||
|
|
||||||
|
const client = new Client({ name: "hua-todo-frontend", version: "1.3.0" });
|
||||||
|
await client.connect(transport);
|
||||||
|
|
||||||
|
// 列出所有可用工具
|
||||||
|
const tools = await client.listTools();
|
||||||
|
|
||||||
|
// 调用工具
|
||||||
|
const result = await client.callTool({ name: "ListActiveTodos", arguments: {} });
|
||||||
|
```
|
||||||
|
|
||||||
|
**封装建议**（`src/api/mcpClient.ts`）：
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
|
||||||
|
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamablehttp.js";
|
||||||
|
|
||||||
|
const MCP_BASE_URL = window.__API_BASE_URL__
|
||||||
|
? window.__API_BASE_URL__.replace("/api", "/mcp")
|
||||||
|
: "/mcp";
|
||||||
|
|
||||||
|
let client: Client | null = null;
|
||||||
|
|
||||||
|
export async function getMcpClient(): Promise<Client> {
|
||||||
|
if (!client) {
|
||||||
|
const transport = new StreamableHTTPClientTransport(
|
||||||
|
new URL(MCP_BASE_URL, window.location.origin)
|
||||||
|
);
|
||||||
|
client = new Client({ name: "hua-todo-frontend", version: "1.3.0" });
|
||||||
|
await client.connect(transport);
|
||||||
|
}
|
||||||
|
return client;
|
||||||
|
}
|
||||||
|
|
||||||
|
export async function disconnectMcp(): Promise<void> {
|
||||||
|
if (client) { await client.close(); client = null; }
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### B.4 工具调用映射
|
||||||
|
|
||||||
|
| 业务操作 | Dynamic API | MCP Tool |
|
||||||
|
|---|---|---|
|
||||||
|
| 获取所有待办项 | `GET /api/task` | `ListAllTodos` |
|
||||||
|
| 获取未完成待办项 | `GET /api/task/active` | `ListActiveTodos` |
|
||||||
|
| 获取已完成待办项 | `GET /api/task/completed` | `ListCompletedTodos` |
|
||||||
|
| 获取单个待办项 | `GET /api/task/{id}` | `GetTodoById` |
|
||||||
|
| 创建待办项 | `POST /api/task` | `CreateTodo` |
|
||||||
|
| 更新待办项 | `PUT /api/task` | `UpdateTodo` |
|
||||||
|
| 切换完成状态 | `PATCH /api/task/{id}/toggle` | `ToggleTodoComplete` |
|
||||||
|
| 删除待办项 | `DELETE /api/task/{id}` | `DeleteTodo` |
|
||||||
|
| 获取子待办项 | `GET /api/task/{pid}/subtasks` | `ListSubTodos` |
|
||||||
|
|
||||||
|
### B.5 返回格式差异
|
||||||
|
|
||||||
|
- **列表类** MCP 工具返回可读文本（如 `"未完成待办项（共 2 项）：[1] 完成报告..."`）
|
||||||
|
- **单条/创建/更新类** MCP 工具返回 JSON
|
||||||
|
- 前端如需结构化数据，建议仍使用 Dynamic API；MCP 通道主要用于 AI 场景和文本交互
|
||||||
|
|
||||||
|
### B.6 典型场景
|
||||||
|
|
||||||
|
**AI 对话式操作**：用户通过 AI 助手用自然语言操作待办项 → LLM 调用 MCP 工具 → 返回结果。
|
||||||
|
|
||||||
|
**语音指令**：语音 → STT → 文本 → LLM 解析意图 → MCP Tool 调用 → TTS 播报结果。
|
||||||
|
|
||||||
|
### B.7 注意事项
|
||||||
|
|
||||||
|
1. **无状态模式**：当前不支持服务端→客户端通知
|
||||||
|
2. **CORS**：开发环境 `AllowAll` 策略已覆盖 `/mcp`
|
||||||
|
3. **认证**：当前 MCP 端点未接入认证中间件
|
||||||
|
4. **生命周期**：建议在组件 `onUnmounted` 时调用 `disconnectMcp()`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
> MCP 服务端实现细节见 [07-技术架构设计](./07-技术架构设计.md) 中 MCP 工具注册部分。
|
||||||
@@ -711,7 +711,7 @@ foreach (var id in request.Deletes)
|
|||||||
| `src/Hua.Todo.Web/src/api/cloudSync.ts` | API 响应类型对齐 | 否 |
|
| `src/Hua.Todo.Web/src/api/cloudSync.ts` | API 响应类型对齐 | 否 |
|
||||||
| `src/Hua.Todo.Web/src/stores/taskStore.ts` | pendingUpserts/pendingDeletes 类型修正 | 否 |
|
| `src/Hua.Todo.Web/src/stores/taskStore.ts` | pendingUpserts/pendingDeletes 类型修正 | 否 |
|
||||||
| `src/Hua.Todo.Web/src/utils/guid.ts` | **新增 Guid 工具函数** | 否 |
|
| `src/Hua.Todo.Web/src/utils/guid.ts` | **新增 Guid 工具函数** | 否 |
|
||||||
| `docs/manual/02-任务同步规则.md` | 文档修正（字段命名） | 是（文档） |
|
| `docs/manual/04-云同步规则.md` | 文档修正（字段命名） | 是（文档） |
|
||||||
| `.trae/rules/项目/03-数据模型与迁移约束.md` | 实体清单更新 | 是（规则） |
|
| `.trae/rules/项目/03-数据模型与迁移约束.md` | 实体清单更新 | 是（规则） |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|||||||
Reference in New Issue
Block a user