xrhome-api/docs/api/device-list-simple-by-user-api.md

获取贩卖机信息精简列表（根据用户绑定过滤）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

请求参数

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

---

响应说明

响应格式

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

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

响应数据结构

成功响应（code = 0）：

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

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

响应示例

成功响应：

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

用户未绑定设备时：

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

权限不足时：

{
  "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

// 使用 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

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

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

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