# Web端设备绑定指南

## 🎉 **简化的绑定流程**

不需要语音绑定码！直接在Web界面输入MAC地址即可。

---

## 🚀 **快速开始**

### **步骤1：启动服务器**

```powershell
cd d:\esp32-music-server\Meow\MeowEmbeddedMusicServer
go run .
```

### **步骤2：登录Web界面**

访问：`http://localhost:2233`

登录账号：
- 用户名：`test`
- 密码：`123456`

### **步骤3：打开设备绑定页面**

访问：`http://localhost:2233/device-bind`

或者在登录后，点击导航菜单中的"设备管理"。

### **步骤4：查看ESP32的MAC地址**

ESP32启动时会在串口日志中显示MAC地址：

```
I (1024) wifi:mode : sta (80:b5:4e:d4:fa:80)
                          ↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑
                          这就是MAC地址！
```

在您的日志中找到这一行：
```
I (1024) wifi:mode : sta (80:b5:4e:d4:fa:80)
```

MAC地址是：`80:b5:4e:d4:fa:80`

### **步骤5：在Web界面输入MAC地址**

1. 在"MAC地址"输入框中输入：`80:b5:4e:d4:fa:80`
2. （可选）在"设备名称"输入框中输入设备名称，例如：`客厅音响`
3. 点击"绑定设备"按钮

### **步骤6：完成！**

绑定成功后，页面会显示：
```
✅ 设备绑定成功！
```

已绑定设备列表会自动刷新，显示您的设备。

---

## 📱 **设备管理功能**

### **查看已绑定设备**

在设备绑定页面下方，会显示所有已绑定的设备：

```
┌──────────────────────────────────────┐
│ 客厅音响                             │
│ MAC: 80:b5:4e:d4:fa:80               │
│ 🟢 在线          [解绑]              │
└──────────────────────────────────────┘
```

### **解绑设备**

点击设备卡片右侧的"解绑"按钮，确认后即可解绑。

### **刷新设备列表**

点击"刷新设备列表"按钮，更新设备状态。

---

## 🆚 **新旧方案对比**

### **旧方案（语音绑定码）**

```
1. Web端生成绑定码 → 123456
2. 对ESP32说："小智，绑定设备，绑定码123456"
3. ESP32识别语音 → 调用MCP工具 → 发送请求
4. 完成绑定
```

**缺点**：
- ❌ 语音识别可能出错
- ❌ 绑定码需要记忆5分钟
- ❌ 流程复杂，容易失败

### **新方案（Web直接绑定）**

```
1. 查看ESP32串口日志 → 复制MAC地址
2. 在Web界面粘贴MAC地址
3. 点击绑定按钮
4. 完成！
```

**优点**：
- ✅ 一次复制粘贴搞定
- ✅ 不需要语音识别
- ✅ 操作简单明了
- ✅ 立即生效，无需等待

---

## 📋 **API文档**

### **1. 直接绑定设备**

```
POST /api/device/bind-direct
Authorization: 需要登录
Content-Type: application/json
```

**请求体**：
```json
{
  "mac": "80:b5:4e:d4:fa:80",
  "device_name": "客厅音响"
}
```

**响应**：
```json
{
  "success": true,
  "message": "设备绑定成功",
  "device": {
    "mac": "80:b5:4e:d4:fa:80",
    "device_name": "客厅音响",
    "bind_time": "2025-11-24T17:00:00Z"
  }
}
```

### **2. 列出用户设备**

```
GET /api/device/list
Authorization: 需要登录
```

**响应**：
```json
{
  "success": true,
  "devices": [
    {
      "mac": "80:b5:4e:d4:fa:80",
      "username": "test",
      "device_name": "客厅音响",
      "token": "a1b2c3...",
      "bind_time": "2025-11-24T17:00:00Z",
      "last_seen": "2025-11-24T17:30:00Z",
      "is_active": true
    }
  ]
}
```

### **3. 解绑设备**

```
POST /api/device/unbind
Authorization: 需要登录
Content-Type: application/json
```

**请求体**：
```json
{
  "mac": "80:b5:4e:d4:fa:80"
}
```

**响应**：
```json
{
  "success": true,
  "message": "设备已解绑"
}
```

---

## 🔍 **如何查看ESP32的MAC地址**

### **方法1：串口监视器（推荐）**

使用ESP-IDF监视器：
```bash
idf.py monitor
```

或者任何串口工具（PuTTY、Arduino Serial Monitor等），波特率115200。

启动日志中会显示：
```
I (1024) wifi:mode : sta (80:b5:4e:d4:fa:80)
```

### **方法2：Web API查询**

如果ESP32已连接到网络，可以通过API查询（需要先知道IP）：
```
http://ESP32的IP地址/api/system/info
```

### **方法3：标签贴纸**

在ESP32开发板上贴一个标签，写上MAC地址，方便以后查找。

---

## 💡 **常见问题**

### **Q1：MAC地址格式错误**

**A**：MAC地址应该是6组2位十六进制数，用冒号分隔，例如：
- ✅ 正确：`80:b5:4e:d4:fa:80`
- ✅ 正确：`80:B5:4E:D4:FA:80` （大小写都可以）
- ❌ 错误：`80b54ed4fa80` （缺少冒号）
- ❌ 错误：`80-b5-4e-d4-fa-80` （使用了连字符）

Web界面会自动格式化MAC地址。

### **Q2：提示"设备已绑定"**

**A**：这个MAC地址已经绑定到某个账号了。

解决方法：
1. 登录原账号，解绑设备
2. 或者在设备管理页面删除旧绑定
3. 然后重新绑定

### **Q3：未登录提示**

**A**：请先登录系统，然后访问设备绑定页面。

### **Q4：设备显示离线**

**A**：
- 检查ESP32是否开机
- 检查WiFi连接
- 查看ESP32串口日志是否有错误

---

## 🎨 **页面截图说明**

### **绑定页面**

```
┌────────────────────────────────────────────┐
│         🎵 设备绑定                        │
│    将您的ESP32音乐播放器绑定到账号          │
├────────────────────────────────────────────┤
│                                            │
│  MAC地址 *                                 │
│  ┌──────────────────────────────────────┐ │
│  │ 例如: AA:BB:CC:DD:EE:FF              │ │
│  └──────────────────────────────────────┘ │
│  💡 在ESP32串口日志中查找                  │
│                                            │
│  设备名称（可选）                          │
│  ┌──────────────────────────────────────┐ │
│  │ 例如: 客厅音响                        │ │
│  └──────────────────────────────────────┘ │
│  给设备起个名字，方便识别                  │
│                                            │
│  ┌──────────────────────────────────────┐ │
│  │          绑定设备                    │ │
│  └──────────────────────────────────────┘ │
│                                            │
│  ┌──────────────────────────────────────┐ │
│  │        刷新设备列表                   │ │
│  └──────────────────────────────────────┘ │
│                                            │
├────────────────────────────────────────────┤
│  已绑定设备                                │
│                                            │
│  ┌──────────────────────────────────────┐ │
│  │ 客厅音响                              │ │
│  │ MAC: 80:b5:4e:d4:fa:80                │ │
│  │ 🟢 在线          [解绑]              │ │
│  └──────────────────────────────────────┘ │
│                                            │
│         ← 返回首页                         │
└────────────────────────────────────────────┘
```

---

## ✅ **总结**

**新的Web绑定方式让设备管理变得超级简单！**

1. 📋 复制ESP32的MAC地址
2. 🖱️ 在Web界面粘贴
3. ✅ 点击绑定
4. 🎉 完成！

不需要语音，不需要绑定码，一次复制粘贴搞定！

---

**喵波音律QQ交流群：865754861** 🎵