小如重构

2026-02-09 18:24:51 +08:00
1 parent 2849fdbcb0
commit f91b8587da
@@ -0,0 +1,341 @@
+# 获取贩卖机信息精简列表（根据用户绑定过滤）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