# 用户积分余额接口文档

## 接口概述

获取当前登录用户的积分余额信息，通过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 | 服务器内部错误 |