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