155 lines
3.4 KiB
Markdown
155 lines
3.4 KiB
Markdown
# 用户积分余额接口文档
|
||
|
||
## 接口概述
|
||
|
||
获取当前登录用户的积分余额信息，通过JWT token自动识别用户身份。
|
||
|
||
---
|
||
|
||
## 接口详情
|
||
|
||
### 基本信息
|
||
- **接口路径**: `/api/admin/accounts/me/points-balance`
|
||
- **请求方法**: `GET`
|
||
- **接口描述**: 根据token解析用户ID并获取当前用户的积分余额
|
||
- **认证方式**: JWT Bearer Token
|
||
|
||
---
|
||
|
||
## 请求参数
|
||
|
||
### Headers
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| Authorization | string | 是 | Bearer {token}，JWT认证令牌 |
|
||
|
||
### 请求示例
|
||
```http
|
||
GET /api/admin/accounts/me/points-balance HTTP/1.1
|
||
Host: localhost:8080
|
||
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
|
||
Content-Type: application/json
|
||
```
|
||
|
||
---
|
||
|
||
## 响应结果
|
||
|
||
### 成功响应 (200 OK)
|
||
|
||
```json
|
||
{
|
||
"userId": 12345,
|
||
"username": "agent001",
|
||
"userType": "AGENT",
|
||
"pointsBalance": 15000
|
||
}
|
||
```
|
||
|
||
### 响应字段说明
|
||
| 字段名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| userId | Long | 用户ID |
|
||
| username | String | 用户名 |
|
||
| userType | String | 用户类型，ADMIN（管理员）或 AGENT（代理） |
|
||
| pointsBalance | Long | 积分余额（单位：积分点数） |
|
||
|
||
---
|
||
|
||
## 错误响应
|
||
|
||
### 401 未授权
|
||
```json
|
||
{
|
||
"error": "Unauthorized",
|
||
"message": "Authorization header is required"
|
||
}
|
||
```
|
||
|
||
### 400 请求错误
|
||
```json
|
||
{
|
||
"error": "Bad Request",
|
||
"message": "Invalid token: userId not found"
|
||
}
|
||
```
|
||
|
||
### 404 用户不存在
|
||
```json
|
||
{
|
||
"error": "Not Found",
|
||
"message": "用户不存在"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 调用示例
|
||
|
||
### JavaScript (fetch)
|
||
```javascript
|
||
const token = 'your-jwt-token-here';
|
||
|
||
fetch('/api/admin/accounts/me/points-balance', {
|
||
method: 'GET',
|
||
headers: {
|
||
'Authorization': `Bearer ${token}`,
|
||
'Content-Type': 'application/json'
|
||
}
|
||
})
|
||
.then(response => response.json())
|
||
.then(data => {
|
||
console.log('用户积分余额:', data.pointsBalance);
|
||
console.log('用户信息:', data);
|
||
})
|
||
.catch(error => {
|
||
console.error('获取积分余额失败:', error);
|
||
});
|
||
```
|
||
|
||
### curl
|
||
```bash
|
||
curl -X GET "http://localhost:8080/api/admin/accounts/me/points-balance" \
|
||
-H "Authorization: Bearer your-jwt-token-here" \
|
||
-H "Content-Type: application/json"
|
||
```
|
||
|
||
### Java (Spring WebFlux)
|
||
```java
|
||
WebClient webClient = WebClient.create("http://localhost:8080");
|
||
|
||
Mono<PointsBalanceResponse> response = webClient
|
||
.get()
|
||
.uri("/api/admin/accounts/me/points-balance")
|
||
.header("Authorization", "Bearer " + jwtToken)
|
||
.retrieve()
|
||
.bodyToMono(PointsBalanceResponse.class);
|
||
|
||
response.subscribe(
|
||
pointsBalance -> System.out.println("积分余额: " + pointsBalance.getPointsBalance()),
|
||
error -> System.err.println("请求失败: " + error.getMessage())
|
||
);
|
||
```
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. **Token有效性**: JWT token必须有效且未过期
|
||
2. **用户类型**:
|
||
- ADMIN用户的积分余额通常为0
|
||
- AGENT用户才有实际的积分余额
|
||
3. **权限控制**: 只能查询当前登录用户自己的积分余额
|
||
4. **数据格式**: 积分余额以长整型返回，单位为积分点数
|
||
|
||
---
|
||
|
||
## 状态码说明
|
||
|
||
| 状态码 | 说明 |
|
||
|--------|------|
|
||
| 200 | 请求成功，返回积分余额信息 |
|
||
| 400 | 请求参数错误或token无效 |
|
||
| 401 | 未提供认证信息或认证失败 |
|
||
| 404 | 用户不存在 |
|
||
| 500 | 服务器内部错误 | |