From 65cee2000635dbae4a6a9acc3771c6c7f27620f8 Mon Sep 17 00:00:00 2001 From: ShaoHua <345265198@qqcom> Date: Tue, 16 Jun 2026 01:46:46 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E9=87=8D=E7=BB=84=20docs/manual/=20?= =?UTF-8?q?=E6=8C=87=E5=8D=97=E7=BB=93=E6=9E=84=EF=BC=8C=E5=8C=BA=E5=88=86?= =?UTF-8?q?=E6=99=AE=E9=80=9A=E7=94=A8=E6=88=B7=E4=B8=8E=E5=BC=80=E5=8F=91?= =?UTF-8?q?=E8=80=85=E5=8F=8C=E5=85=A5=E5=8F=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 00-目录与导读.md 双入口导航 - 用户面(01-04)：项目介绍、安装指南、版本记录、其他信息 - 开发者面(05-10)：技术栈、构建、架构、云同步、代码规范、MCP - 拆分旧01为 01(用户)+05(开发者)；旧02为 02(用户)+06(开发者) - 合并旧08+09 MCP文档为 10-MCP服务集成 - 同步更新 README.md 与 .trae/rules/项目/ 交叉引用 --- .trae/rules/项目/01-项目架构.md | 2 +- .trae/rules/项目/02-业务命名规范.md | 2 +- .trae/rules/项目/03-数据模型与迁移约束.md | 4 +- .trae/rules/项目/04-即时状态记忆.md | 9 +- README.md | 22 +- docs/manual/00-目录与导读.md | 44 ++ docs/manual/01-技术设计文档.md | 414 ------------------ docs/manual/01-项目介绍.md | 51 +++ docs/manual/02-安装指南.md | 108 +++++ docs/manual/03-技术栈与模块.md | 46 -- .../manual/{06-版本记录.md => 03-版本记录.md} | 45 +- .../manual/{07-其他信息.md => 04-其他信息.md} | 6 +- docs/manual/05-技术栈与项目结构.md | 124 ++++++ docs/manual/05-部署文档.md | 128 ------ docs/manual/06-开发环境与构建.md | 100 +++++ docs/manual/07-技术架构设计.md | 389 ++++++++++++++++ docs/manual/08-MCP服务接口文档.md | 389 ---------------- .../{02-任务同步规则.md => 08-云同步规则.md} | 4 +- docs/manual/09-MCP前端集成指南.md | 210 --------- .../{04-代码规范文档.md => 09-代码规范.md} | 12 +- docs/manual/10-MCP服务集成.md | 311 +++++++++++++ .../09-CloudSync-同步策略改进方案.md | 2 +- 22 files changed, 1190 insertions(+), 1232 deletions(-) create mode 100644 docs/manual/00-目录与导读.md delete mode 100644 docs/manual/01-技术设计文档.md create mode 100644 docs/manual/01-项目介绍.md create mode 100644 docs/manual/02-安装指南.md delete mode 100644 docs/manual/03-技术栈与模块.md rename docs/manual/{06-版本记录.md => 03-版本记录.md} (64%) rename docs/manual/{07-其他信息.md => 04-其他信息.md} (89%) create mode 100644 docs/manual/05-技术栈与项目结构.md delete mode 100644 docs/manual/05-部署文档.md create mode 100644 docs/manual/06-开发环境与构建.md create mode 100644 docs/manual/07-技术架构设计.md delete mode 100644 docs/manual/08-MCP服务接口文档.md rename docs/manual/{02-任务同步规则.md => 08-云同步规则.md} (98%) delete mode 100644 docs/manual/09-MCP前端集成指南.md rename docs/manual/{04-代码规范文档.md => 09-代码规范.md} (98%) create mode 100644 docs/manual/10-MCP服务集成.md diff --git a/.trae/rules/项目/01-项目架构.md b/.trae/rules/项目/01-项目架构.md index 4f8b772..079e5cf 100644 --- a/.trae/rules/项目/01-项目架构.md +++ b/.trae/rules/项目/01-项目架构.md @@ -3,7 +3,7 @@ > 适用范围：本规则属于 **项目规则**（仅 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/） diff --git a/.trae/rules/项目/02-业务命名规范.md b/.trae/rules/项目/02-业务命名规范.md index 25ecb31..88669f0 100644 --- a/.trae/rules/项目/02-业务命名规范.md +++ b/.trae/rules/项目/02-业务命名规范.md @@ -31,7 +31,7 @@ ### 2.3 HTTP API 路由 - 本地动态 API：`/api/task`、`/api/task/{parentTaskId}/subtasks`（由 `Hua.Todo.Application/DynamicApi` 自动暴露） - 云端：`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 数据库表 - `Tasks`、`Users`、`UserSessions`、`SecurityPolicies`、`AuditLogs` diff --git a/.trae/rules/项目/03-数据模型与迁移约束.md b/.trae/rules/项目/03-数据模型与迁移约束.md index d53320e..a9a3f2d 100644 --- a/.trae/rules/项目/03-数据模型与迁移约束.md +++ b/.trae/rules/项目/03-数据模型与迁移约束.md @@ -94,6 +94,6 @@ 1. [ ] 是否新增了 EF Core 迁移（而非手改快照）？ 2. [ ] 迁移名称是否以 `AddXxx`/`UpdateXxx`/`RemoveXxx` 开头？ -3. [ ] 是否在 [docs/manual/01-技术设计文档.md](../../../docs/manual/01-技术设计文档.md) 中同步更新数据模型描述？ -4. [ ] 是否在 [docs/manual/06-版本记录.md](../../../docs/manual/06-版本记录.md) 中追加非琐碎变更条目？ +3. [ ] 是否在 [docs/manual/07-技术架构设计.md](../../../docs/manual/07-技术架构设计.md) 中同步更新数据模型描述？ +4. [ ] 是否在 [docs/manual/03-版本记录.md](../../../docs/manual/03-版本记录.md) 中追加非琐碎变更条目？ 5. [ ] 是否在嵌入式宿主上验证了启动时 Migrate 不报错？ diff --git a/.trae/rules/项目/04-即时状态记忆.md b/.trae/rules/项目/04-即时状态记忆.md index 34c4f1d..ea85bef 100644 --- a/.trae/rules/项目/04-即时状态记忆.md +++ b/.trae/rules/项目/04-即时状态记忆.md @@ -37,7 +37,7 @@ | 子工单 | 实现状态 | 验证状态 | 简要说明 | |---|---|---|---| | 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-01 - 会议数据模型与 API | 待开始 | 待验证 | TaskType 枚举、MeetingNotes/AudioDuration 字段、MeetingController | | 03-02 - 音频录制与转写 | 待开始 | 待验证 | 前端 MediaRecorder 录音 + 后端 STT 转写 | @@ -60,6 +60,8 @@ - [ ] Linux Flatpak/AppImage 自包含产物在干净环境的实测验证（v1.2.0 验收 Linux 部分仍为"待验证"） - [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）： @@ -70,6 +72,11 @@ - **`.trae` 子目录文件序号化**（2026-06）： - `.trae/rules/全局/`、`.trae/rules/项目/`、`.trae/coordination/`、`.trae/memory/` 下所有文件加 `NN-` 序号前缀 - `.trae/索引.md` 不带序号（入口文件） +- **`docs/manual/` 指南重组**（2026-06-16）： + - 新增 `00-目录与导读.md` 双入口导航（普通用户 / 开发者） + - 拆分用户面与开发者面：01-02 为用户安装使用；05-10 为开发者架构/构建/规范 + - 合并重叠与过时内容，精简用户文档篇幅 + - 同步更新 README.md 与 `.trae/rules/项目/` 中的交叉引用 --- diff --git a/README.md b/README.md index 278081f..7007421 100644 --- a/README.md +++ b/README.md @@ -83,7 +83,7 @@ Hua.Todo/ - **QQ 交流群**：2167048911 (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) -- [版本更新历史](docs/manual/版本记录.md) -- [技术设计文档](docs/manual/技术设计文档.md) -- [代码规范文档](docs/manual/代码规范文档.md) -- [其他信息 (贡献、许可证、联系方式)](docs/manual/其他信息.md) +### 普通用户 +- [00-目录与导读](docs/manual/00-目录与导读.md) — 文档入口 +- [01-项目介绍](docs/manual/01-项目介绍.md) +- [02-安装指南](docs/manual/02-安装指南.md) +- [03-版本记录](docs/manual/03-版本记录.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) diff --git a/docs/manual/00-目录与导读.md b/docs/manual/00-目录与导读.md new file mode 100644 index 0000000..332ceb4 --- /dev/null +++ b/docs/manual/00-目录与导读.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) diff --git a/docs/manual/01-技术设计文档.md b/docs/manual/01-技术设计文档.md deleted file mode 100644 index ea97012..0000000 --- a/docs/manual/01-技术设计文档.md +++ /dev/null @@ -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 端到端测试 -- 跨平台功能测试 -- 用户流程测试 -- 性能测试 diff --git a/docs/manual/01-项目介绍.md b/docs/manual/01-项目介绍.md new file mode 100644 index 0000000..613a1c9 --- /dev/null +++ b/docs/manual/01-项目介绍.md @@ -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)（开发者） diff --git a/docs/manual/02-安装指南.md b/docs/manual/02-安装指南.md new file mode 100644 index 0000000..8a36040 --- /dev/null +++ b/docs/manual/02-安装指南.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)。 diff --git a/docs/manual/03-技术栈与模块.md b/docs/manual/03-技术栈与模块.md deleted file mode 100644 index 24f2bb0..0000000 --- a/docs/manual/03-技术栈与模块.md +++ /dev/null @@ -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。 diff --git a/docs/manual/06-版本记录.md b/docs/manual/03-版本记录.md similarity index 64% rename from docs/manual/06-版本记录.md rename to docs/manual/03-版本记录.md index 8eb0590..5f3b2f4 100644 --- a/docs/manual/06-版本记录.md +++ b/docs/manual/03-版本记录.md @@ -1,17 +1,24 @@ # 版本更新历史 -## 🔄 版本更新 +## 版本更新 ### 版本策略 - 采用语义化版本号：`MAJOR.MINOR.PATCH` - v1.0.0：初始 WPF 版本 - 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) -- **文档**：新增 [任务同步规则.md](./02-任务同步规则.md)，汇总 Todo 待办项云同步的架构、API 契约、认证鉴权、同步工作流、安全策略与可控落盘等完整规则。 +- **文档**：新增 [云同步规则](./08-云同步规则.md)，汇总 Todo 待办项云同步的架构、API 契约、认证鉴权、同步工作流、安全策略与可控落盘等完整规则。 ### v1.2.8 (2026-04-13) @@ -25,30 +32,29 @@ - **Linux 官方支持**：新增 `Hua.Todo.Avalonia` 项目，正式适配 Linux 平台，同时支持 Windows 和 macOS。 - **Avalonia 桌面交互**：增加托盘菜单（显示/退出）、关闭隐藏到托盘、Windows 全局热键唤起主窗口、热键配置本地持久化；并对齐 Avalonia 的 appsettings 默认值。 -- **关键词检索**：主界面增加搜索框，按任务标题实时过滤；采用“命中即显示（含上下文）”策略；支持 Esc 清空；英文大小写不敏感。 -- **云同步（基础可用）**：新增“云同步设置”弹窗，支持手动配置服务端地址（格式校验 + 保存时可达性/风险提示）；登录成功后拉取云端任务并刷新主界面（v1.2.0 为只读展示）；401/403 时会自动清会话并弹出登录入口。 +- **关键词检索**：主界面增加搜索框，按任务标题实时过滤；采用"命中即显示（含上下文）"策略；支持 Esc 清空；英文大小写不敏感。 +- **云同步（基础可用）**：新增"云同步设置"弹窗，支持手动配置服务端地址（格式校验 + 保存时可达性/风险提示）；登录成功后拉取云端任务并刷新主界面（v1.2.0 为只读展示）；401/403 时会自动清会话并弹出登录入口。 - **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`）。 - **MAUI Android 调试配置修复**：在 `Hua.Todo.Maui.csproj` 中显式启用 `AndroidApplication`，并将调试架构配置从 `AndroidSupportedAbis` 切换为 `RuntimeIdentifiers=android-x64`，减少 Visual Studio 启动 Android 调试时的项目识别与模拟器架构问题。 -- **Swagger 输出补齐 Dynamic API**：任务管理等 Dynamic API 端点会出现在 `swagger.json` 中，避免“接口缺失”导致联调困难。 -- **SQLite DateTime 兼容修复**：新增 `LenientUtcDateTimeStringConverter`，本地数据库中若存在历史遗留的 DateTime “ticks/时间戳字符串”脏数据，读取时将被兼容解析，避免 `/api/task` 等查询因单条坏数据整体失败。 -- **SPA 路由回落行为修复**：当 Release/非 Debug 未启用 Swagger 时，`/swagger` 不再被当作“后端专用路径”排除，访问会按 SPA 路由规则回落到 `/index.html`，避免直接 404。 +- **Swagger 输出补齐 Dynamic API**：任务管理等 Dynamic API 端点会出现在 `swagger.json` 中，避免"接口缺失"导致联调困难。 +- **SQLite DateTime 兼容修复**：新增 `LenientUtcDateTimeStringConverter`，本地数据库中若存在历史遗留的 DateTime "ticks/时间戳字符串"脏数据，读取时将被兼容解析，避免 `/api/task` 等查询因单条坏数据整体失败。 +- **SPA 路由回落行为修复**：当 Release/非 Debug 未启用 Swagger 时，`/swagger` 不再被当作"后端专用路径"排除，访问会按 SPA 路由规则回落到 `/index.html`，避免直接 404。 - **MAUI 多平台构建开关**：在 Windows 开发机上默认仅构建 Android + Windows 目标，避免 iOS/MacCatalyst 目标在非 macOS 环境触发运行时包缺失（NETSDK1082）；在 macOS 上仍会包含 iOS/MacCatalyst 目标。 - **发布脚本整理**：拆分/对齐各平台发布入口，新增 `publish.ps1` 作为统一入口（默认发布 Windows + Linux），Windows 发布脚本支持开关打包与版本自增，发布产物会落盘到 `artifacts/`。 - **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 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` 代理配置。 -- **文档与部署指南**：新增 `docs/manual/05-部署文档.md`，详细说明开发环境搭建、多平台发布流程（Windows/Linux/Docker）以及关键配置项；并在技术设计文档中建立链接。 -- **用户文档完善**：在规划中新增了 `docs/manual/08-新手指南.md` 和 `docs/manual/09-用户指南.md`。 -27→ -28→### v1.1.1 (2026-04-06) +- **文档与部署指南**：新增部署文档，详细说明开发环境搭建、多平台发布流程（Windows/Linux/Docker）以及关键配置项。 + +### v1.1.1 (2026-04-06) - **文档规范增强**：新增文档同步规则，强制代码变更与文档更新保持同步。 - **项目结构说明校准**：修正 README.md 和技术文档中对 `Hua.Todo.Host`、`Hua.Todo.Application` 等模块的路径与职责描述。 - **端口配置校准**：修正文档中关于前端与后端 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 更新内容 @@ -59,11 +65,6 @@ - 使用 SQLite 作为本地数据库 - 实现子任务支持 -### v1.2.0 规划内容 (即将推出) +### v1.0.0 初始版本 -- **Linux 官方支持**：正式适配 Linux 平台。 -- **Linux 打包与交付**：新增 `.tar.gz` 发布脚本与 Flatpak（manifest/desktop entry/AppStream）基础结构。 -- **关键词检索**：支持按任务标题关键词搜索。 -- **标签系统**：引入多标签支持，提升任务组织效率。 -- **暗色模式**：全平台适配暗色/深色主题。 -- **数据导出导入（后续）**：支持 JSON 格式数据备份与迁移（延期到后续版本）。 +- 初始 WPF 版本。 diff --git a/docs/manual/07-其他信息.md b/docs/manual/04-其他信息.md similarity index 89% rename from docs/manual/07-其他信息.md rename to docs/manual/04-其他信息.md index a352a04..db3f4fa 100644 --- a/docs/manual/07-其他信息.md +++ b/docs/manual/04-其他信息.md @@ -1,6 +1,6 @@ # 其他信息 -## 🤝 贡献指南 +## 贡献指南 1. Fork 项目 2. 创建特性分支 (`git checkout -b feature/AmazingFeature`) @@ -8,11 +8,11 @@ 4. 推送到分支 (`git push origin feature/AmazingFeature`) 5. 打开 Pull Request -## 📄 许可证 +## 许可证 本项目采用 AGPL-3.0 许可证 - 查看 [LICENSE](LICENSE) (英文) 或 [LICENSE.zh-CN](LICENSE.zh-CN) (中文) 文件了解详情 -## 📞 联系方式 +## 联系方式 - 项目作者：ShaoHua - 项目地址：https://git.we965.cn/Tools/Hua.Todo diff --git a/docs/manual/05-技术栈与项目结构.md b/docs/manual/05-技术栈与项目结构.md new file mode 100644 index 0000000..2914f3c --- /dev/null +++ b/docs/manual/05-技术栈与项目结构.md @@ -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) diff --git a/docs/manual/05-部署文档.md b/docs/manual/05-部署文档.md deleted file mode 100644 index df918e3..0000000 --- a/docs/manual/05-部署文档.md +++ /dev/null @@ -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` 给主程序执行权限。 - diff --git a/docs/manual/06-开发环境与构建.md b/docs/manual/06-开发环境与构建.md new file mode 100644 index 0000000..8db26b0 --- /dev/null +++ b/docs/manual/06-开发环境与构建.md @@ -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) diff --git a/docs/manual/07-技术架构设计.md b/docs/manual/07-技术架构设计.md new file mode 100644 index 0000000..82903d9 --- /dev/null +++ b/docs/manual/07-技术架构设计.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 端到端测试 +- 跨平台功能测试 +- 用户流程测试 +- 性能测试 diff --git a/docs/manual/08-MCP服务接口文档.md b/docs/manual/08-MCP服务接口文档.md deleted file mode 100644 index d1ad917..0000000 --- a/docs/manual/08-MCP服务接口文档.md +++ /dev/null @@ -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 diff --git a/docs/manual/02-任务同步规则.md b/docs/manual/08-云同步规则.md similarity index 98% rename from docs/manual/02-任务同步规则.md rename to docs/manual/08-云同步规则.md index 5e01a74..95e812a 100644 --- a/docs/manual/02-任务同步规则.md +++ b/docs/manual/08-云同步规则.md @@ -1,6 +1,6 @@ # Todo 待办项云同步规则 -> 本文档汇总 Hua.Todo 项目的 Todo 待办项云同步完整规则，涵盖架构、API 契约、认证鉴权、同步工作流、安全策略与可控落盘等。 +> 本文档面向开发者，汇总 Hua.Todo 项目的云同步完整规则，涵盖架构、API 契约、认证鉴权、同步工作流、安全策略与可控落盘等。 > > 术语：本文中"任务 / Todo 待办项"均为业务实体（对应代码 `Task` / `SubTask` / `TaskEntity`），与编码侧的"研发工单"无关。 @@ -509,4 +509,4 @@ Hua.Todo.Application (共享层) > - 安全与可控落盘：[06-CloudSync-安全与可控落盘.md](../project/研发工单-v1.2.0/06-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) -> - 技术设计文档：[技术设计文档.md](./01-技术设计文档.md) +> - 技术架构设计：[07-技术架构设计](./07-技术架构设计.md) diff --git a/docs/manual/09-MCP前端集成指南.md b/docs/manual/09-MCP前端集成指南.md deleted file mode 100644 index 28f8176..0000000 --- a/docs/manual/09-MCP前端集成指南.md +++ /dev/null @@ -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://: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 { - 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 { - 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()` diff --git a/docs/manual/04-代码规范文档.md b/docs/manual/09-代码规范.md similarity index 98% rename from docs/manual/04-代码规范文档.md rename to docs/manual/09-代码规范.md index ca68d24..b60dd3b 100644 --- a/docs/manual/04-代码规范文档.md +++ b/docs/manual/09-代码规范.md @@ -1,4 +1,6 @@ -# Hua.Todo 代码规范文档 v1.2.8 +# 代码规范 + +> 本文档面向开发者，定义 Hua.Todo 项目的编码规范。 ## 1. 概述 本文档定义 Hua.Todo 项目的代码规范，包括 C#、JavaScript/TypeScript、Vue.js 和其他相关技术的编码标准。遵循这些规范有助于提高代码质量、可读性和可维护性。 @@ -29,7 +31,7 @@ ### 3.1 跨平台逻辑规范 - **禁止混写 `#if`**：禁止在同一文件内混写多个平台的大段 `#if` 实现。 - **优先使用 partial/接口**：应优先使用 `partial` 类、接口与平台目录分离。 -- **说明平台差异**：平台分离后的公共入口处必须说明“平台差异在哪里、默认实现是什么、为什么这么做”。 +- **说明平台差异**：平台分离后的公共入口处必须说明"平台差异在哪里、默认实现是什么、为什么这么做"。 ### 3.2 异步/后台任务 - **必须说明启动时机、错误处理策略、是否需要 UI 线程、以及是否可并发/可重入**。 @@ -78,7 +80,7 @@ public void CreateTask(string title, TaskPriority priority) public const int MaxTaskTitleLength = 200; ``` -### 3.2 代码组织 +### 3.3 代码组织 #### 文件结构 ```csharp @@ -124,7 +126,7 @@ public class TaskService : ITaskService - 命名空间结构应与目录结构一致 - 使用 `.` 分隔层级 -### 3.3 编码规范 +### 3.4 编码规范 #### 异步编程 ```csharp @@ -191,7 +193,7 @@ var query = from task in tasks select task; ``` -### 3.4 文档注释 +### 3.5 文档注释 ```csharp /// /// 获取指定 ID 的任务 diff --git a/docs/manual/10-MCP服务集成.md b/docs/manual/10-MCP服务集成.md new file mode 100644 index 0000000..74a51cd --- /dev/null +++ b/docs/manual/10-MCP服务集成.md @@ -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://: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 { + 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 { + 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 工具注册部分。 diff --git a/docs/project/研发工单-v1.2.0/09-CloudSync-同步策略改进方案.md b/docs/project/研发工单-v1.2.0/09-CloudSync-同步策略改进方案.md index 389520d..2ebb82d 100644 --- a/docs/project/研发工单-v1.2.0/09-CloudSync-同步策略改进方案.md +++ b/docs/project/研发工单-v1.2.0/09-CloudSync-同步策略改进方案.md @@ -711,7 +711,7 @@ foreach (var id in request.Deletes) | `src/Hua.Todo.Web/src/api/cloudSync.ts` | API 响应类型对齐 | 否 | | `src/Hua.Todo.Web/src/stores/taskStore.ts` | pendingUpserts/pendingDeletes 类型修正 | 否 | | `src/Hua.Todo.Web/src/utils/guid.ts` | **新增 Guid 工具函数** | 否 | -| `docs/manual/02-任务同步规则.md` | 文档修正（字段命名） | 是（文档） | +| `docs/manual/04-云同步规则.md` | 文档修正（字段命名） | 是（文档） | | `.trae/rules/项目/03-数据模型与迁移约束.md` | 实体清单更新 | 是（规则） | ---