新增积分余额显示功能，优化积分格式化逻辑，完善积分获取接口文档

2025-08-29 23:24:26 +08:00
parent ccc022f5d1
commit 9ff0e7aa2d
4 changed files with 240 additions and 2 deletions
--- a/docs/代理商积分获取接口.md
+++ b/docs/代理商积分获取接口.md
@@ -0,0 +1,155 @@
+# 用户积分余额接口文档
+
+## 接口概述
+
+获取当前登录用户的积分余额信息，通过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 | 服务器内部错误 |