game_server/积分余额接口文档.md

用户积分余额接口文档

接口概述

获取当前登录用户的积分余额信息，通过JWT token自动识别用户身份。

---

接口详情

基本信息

• 接口路径: /api/admin/accounts/me/points-balance
• 请求方法: GET
• 接口描述: 根据token解析用户ID并获取当前用户的积分余额
• 认证方式: JWT Bearer Token

---

请求参数

Headers

参数名	类型	必填	说明
Authorization	string	是	Bearer {token}，JWT认证令牌

请求示例

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)

{
    "userId": 12345,
    "username": "agent001",
    "userType": "AGENT",
    "pointsBalance": 15000
}

响应字段说明

字段名	类型	说明
userId	Long	用户ID
username	String	用户名
userType	String	用户类型，ADMIN（管理员）或 AGENT（代理）
pointsBalance	Long	积分余额（单位：积分点数）

---

错误响应

401 未授权

{
    "error": "Unauthorized",
    "message": "Authorization header is required"
}

400 请求错误

{
    "error": "Bad Request",
    "message": "Invalid token: userId not found"
}

404 用户不存在

{
    "error": "Not Found",
    "message": "用户不存在"
}

---

调用示例

JavaScript (fetch)

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

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)

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	服务器内部错误