doc

sprint2/sprint2.md

@@ -0,0 +1,120 @@
+## 一、本轮迭代目标
+
+本 Sprint 主要目标是完成 **基于浏览器端的手势控制系统雏形**，实现如下基础功能：
+
+- 搭建前端 Web 应用结构与 UI 页面
+- 集成 MediaPipe 手势识别模型，完成实时手势检测
+- 映射部分手势为系统控制行为（鼠标移动、点击等）
+- 搭建基础手势处理逻辑与组件封装结构
+- 支持语音识别指令发送流程（准备后端对接）
+
+------
+
+## 二、本轮主要完成内容
+
+| 类别     | 工作内容                                                     |
+| -------- | ------------------------------------------------------------ |
+| 前端搭建 | 基于 Vite + Vue 3 + TypeScript 完成项目结构、模块划分、页面初始化 |
+| 手势识别 | 集成 Google MediaPipe WASM 模型，完成实时检测与渲染          |
+| 控制逻辑 | 封装 `GestureHandler`、`TriggerAction`，实现手势到系统操作的映射 |
+| UI设计   | 完成仪表盘式主界面设计，支持响应式、自定义手势预览等         |
+| 模型结构 | 初步梳理 `Detector` 识别流程，统一封装初始化与推理逻辑       |
+| 后端准备 | 初始化 Python 接口 WebSocket 构建，支持语音识别交互          |
+
+
+
+------
+
+## 三、系统结构设计
+
+```
+[用户摄像头]
+     ↓
+[VideoDetector.vue] → 捕捉视频帧，传入检测器
+     ↓
+[Detector.ts] → 调用 MediaPipe 识别手势
+     ↓
+[GestureHandler.ts] → 映射行为（鼠标/键盘/语音）
+     ↓
+[TriggerAction.ts] → 向后端/系统发出控制指令
+     ↓
+[Python 后端]（语音识别/扩展指令） ← WebSocket 接入
+```
+
+------
+
+## 四、核心技术栈与理由
+
+| 技术             | 用途                 | 原因                                       |
+| ---------------- | -------------------- | ------------------------------------------ |
+| Vue 3 + Vite     | 前端框架 + 构建工具  | 快速开发，热更新快，Composition API 更灵活 |
+| TypeScript       | 增强类型约束         | 减少运行时错误，提升可维护性               |
+| MediaPipe Tasks  | 手势识别模型         | 体积小，支持浏览器部署，准确率高           |
+| WebSocket        | 前后端实时通信       | 保持实时交互流畅                           |
+| Python + FastAPI | 后端扩展接口（语音） | 快速搭建接口，后续支持 Py 模型运行         |
+
+
+
+------
+
+## 五、主要功能点与说明
+
+### 1. Detector 类封装
+
+- 初始化 WASM 模型与识别器
+- 封装 `detect()` 每帧调用逻辑
+- 支持获取 `landmarks`, `gestures`, `handedness`
+
+### 2. 手势识别与映射
+
+- 仅识别食指 → 鼠标移动
+- 食指 + 中指 → 鼠标点击
+- 食指 + 拇指捏合 → 滚动
+- 四指竖起 → 发送快捷键
+- 小指+拇指 → 启动语音识别（前端 WebSocket）
+
+### 3. UI 界面模块
+
+- 实时视频预览窗口
+- 子窗口：手势反馈 / 执行动作提示
+- 配置面板：开关检测 / 配置行为映射
+
+------
+
+## 六、识别代码示例（关键手势）
+
+```ts
+if (gesture === HandGesture.ONLY_INDEX_UP) {
+  this.triggerAction.moveMouse(x, y)
+}
+if (gesture === HandGesture.INDEX_AND_THUMB_UP) {
+  this.triggerAction.scrollUp()
+}
+```
+
+- 每种手势匹配后，调用封装的 WebSocket + 系统接口发送动作
+- `TriggerAction` 支持复用
+
+------
+
+## 七、问题与解决方案
+
+| 问题描述                          | 解决方法                                             |
+| --------------------------------- | ---------------------------------------------------- |
+| WebSocket 连接后反复断开          | 增加连接状态判断 `readyState !== OPEN`，避免提前发送 |
+| Tauri 插件调用 `invoke undefined` | 使用 `npm run tauri dev` 启动，而非普通浏览器启动    |
+| 页面刷新后路由丢失（404）         | Vue Router 改为 `createWebHashHistory()` 模式        |
+| 模型未加载或报错提示              | 增加 loading 控制，捕捉初始化异常                    |
+
+
+
+------
+
+## 八、未来规划（Sprint 2 预告）
+
+| 方向              | 说明                                                |
+| ----------------- | --------------------------------------------------- |
+| 多手势拓展        | 三指滚动、多指触发多功能、多手联合判断              |
+| 自定义 .task 模型 | 支持用户采集数据，自定义模型替换现有 MediaPipe 模型 |
+| 后端语音指令集成  | Vosk 模型识别语音，触发系统控制                     |
+| 设置项管理        | 实现用户自定义快捷键、手势配置界面                  |