## 一、本轮迭代目标

本 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 模型识别语音，触发系统控制                     |
| 设置项管理        | 实现用户自定义快捷键、手势配置界面                  |