# 获取贩卖机信息精简列表（根据用户绑定过滤）API 文档

## 接口信息

- **接口路径**：`GET /product/device/list-simple-by-user`
- **接口描述**：获得贩卖机信息精简列表（根据用户绑定过滤，超级管理员返回全部）
- **权限要求**：`product:device:query`
- **认证方式**：Bearer Token（需要在请求头中携带 `Authorization: Bearer {token}`）

---

## 请求说明

### 请求方法
`GET`

### 请求路径
```
/product/device/list-simple-by-user
```

### 请求头
```
Authorization: Bearer {token}
Content-Type: application/json
```

### 请求参数
**无请求参数**（此接口不需要任何查询参数或请求体）

---

## 响应说明

### 响应格式

所有接口都遵循统一的响应格式：

```typescript
interface CommonResult<T> {
  code: number;        // 响应码，0 表示成功
  data: T;            // 响应数据
  msg: string;        // 响应消息（成功时通常为空字符串）
}
```

### 响应数据结构

**成功响应（code = 0）**：

```typescript
interface DeviceSimpleRespVO {
  id: number;          // 设备编号（主键）
  name: string;        // 设备名称
  deviceId: string;    // 设备IMEI（设备唯一标识）
}

// 完整响应结构
CommonResult<DeviceSimpleRespVO[]>
```

### 响应示例

**成功响应**：

```json
{
  "code": 0,
  "data": [
    {
      "id": 1,
      "name": "贩卖机001",
      "deviceId": "123456789012345"
    },
    {
      "id": 2,
      "name": "贩卖机002",
      "deviceId": "123456789012346"
    }
  ],
  "msg": ""
}
```

**用户未绑定设备时**：

```json
{
  "code": 0,
  "data": [],
  "msg": ""
}
```

**权限不足时**：

```json
{
  "code": 403,
  "data": null,
  "msg": "权限不足"
}
```

---

## 业务逻辑说明

### 权限过滤逻辑

1. **超级管理员（super_admin 角色）**
   - 返回系统中**所有设备**的列表
   - 按设备编号（id）降序排列

2. **普通用户**
   - 只返回**当前登录用户绑定的设备**列表
   - 如果用户未绑定任何设备，返回空数组 `[]`
   - 按设备编号（id）降序排列

3. **未登录用户**
   - 返回空数组 `[]`

### 数据来源

- 设备数据来自 `product_device` 表
- 用户设备绑定关系通过 `admin_user` 表的 `device_id` 字段或关联表维护
- 超级管理员判断通过用户角色 `super_admin` 进行判断

---

## 使用场景

### 典型使用场景

1. **设备下拉选择框**
   - 前端需要展示用户可操作的设备列表
   - 超级管理员看到所有设备，普通用户只看到自己绑定的设备

2. **设备筛选**
   - 在商品管理、货道管理等页面，需要根据用户权限过滤设备

3. **权限控制**
   - 确保用户只能操作自己绑定的设备

---

## 前端调用示例

### JavaScript / TypeScript

```typescript
// 使用 fetch
async function getDeviceSimpleListByUser() {
  const response = await fetch('/product/device/list-simple-by-user', {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    }
  });
  
  const result: CommonResult<DeviceSimpleRespVO[]> = await response.json();
  
  if (result.code === 0) {
    console.log('设备列表:', result.data);
    return result.data;
  } else {
    console.error('获取失败:', result.msg);
    throw new Error(result.msg);
  }
}
```

### Axios

```typescript
import axios from 'axios';

interface DeviceSimpleRespVO {
  id: number;
  name: string;
  deviceId: string;
}

interface CommonResult<T> {
  code: number;
  data: T;
  msg: string;
}

async function getDeviceSimpleListByUser(): Promise<DeviceSimpleRespVO[]> {
  const response = await axios.get<CommonResult<DeviceSimpleRespVO[]>>(
    '/product/device/list-simple-by-user',
    {
      headers: {
        'Authorization': `Bearer ${token}`
      }
    }
  );
  
  if (response.data.code === 0) {
    return response.data.data;
  } else {
    throw new Error(response.data.msg);
  }
}
```

### Vue 3 Composition API

```typescript
import { ref, onMounted } from 'vue';
import axios from 'axios';

interface DeviceSimpleRespVO {
  id: number;
  name: string;
  deviceId: string;
}

export function useDeviceList() {
  const deviceList = ref<DeviceSimpleRespVO[]>([]);
  const loading = ref(false);
  
  const fetchDeviceList = async () => {
    loading.value = true;
    try {
      const response = await axios.get<CommonResult<DeviceSimpleRespVO[]>>(
        '/product/device/list-simple-by-user'
      );
      
      if (response.data.code === 0) {
        deviceList.value = response.data.data;
      } else {
        console.error('获取设备列表失败:', response.data.msg);
      }
    } catch (error) {
      console.error('请求失败:', error);
    } finally {
      loading.value = false;
    }
  };
  
  onMounted(() => {
    fetchDeviceList();
  });
  
  return {
    deviceList,
    loading,
    fetchDeviceList
  };
}
```

### React Hooks

```typescript
import { useState, useEffect } from 'react';
import axios from 'axios';

interface DeviceSimpleRespVO {
  id: number;
  name: string;
  deviceId: string;
}

export function useDeviceList() {
  const [deviceList, setDeviceList] = useState<DeviceSimpleRespVO[]>([]);
  const [loading, setLoading] = useState(false);
  
  useEffect(() => {
    const fetchDeviceList = async () => {
      setLoading(true);
      try {
        const response = await axios.get<CommonResult<DeviceSimpleRespVO[]>>(
          '/product/device/list-simple-by-user'
        );
        
        if (response.data.code === 0) {
          setDeviceList(response.data.data);
        } else {
          console.error('获取设备列表失败:', response.data.msg);
        }
      } catch (error) {
        console.error('请求失败:', error);
      } finally {
        setLoading(false);
      }
    };
    
    fetchDeviceList();
  }, []);
  
  return { deviceList, loading };
}
```

---

## 错误码说明

| 错误码 | 说明 | 解决方案 |
|--------|------|----------|
| 0 | 成功 | - |
| 401 | 未授权（未登录或 token 过期） | 重新登录获取 token |
| 403 | 权限不足 | 检查用户是否有 `product:device:query` 权限 |
| 500 | 服务器内部错误 | 联系后端开发人员 |

---

## 注意事项

1. **权限要求**
   - 调用此接口需要用户已登录
   - 需要 `product:device:query` 权限

2. **数据过滤**
   - 超级管理员会看到所有设备
   - 普通用户只能看到自己绑定的设备
   - 如果用户未绑定设备，返回空数组（不会报错）

3. **排序规则**
   - 返回的设备列表按 `id` 降序排列（最新的设备在前）

4. **性能考虑**
   - 此接口返回的是精简数据（只有 id、name、deviceId），适合下拉选择等场景
   - 如果需要完整设备信息，请使用其他接口

---

## 相关接口

- **获取设备完整列表**：`GET /product/device/list-simple`（返回所有设备，不过滤用户绑定）
- **获取设备详情**：`GET /product/device/get?id={id}`
- **分页查询设备**：`GET /product/device/page`

---

**文档版本**：v1.0  
**最后更新**：2025-01-27