AI_OJ_FRONTEND/docs/auth-api.md

# AIOJ 认证服务 API 文档

## 概述

AIOJ认证服务提供JWT（JSON Web Token）为基础的用户认证和授权功能。该服务负责用户登录、令牌生成、令牌刷新和令牌验证。

**基础信息:**
- 服务名称: auth-service
- 基础路径: `/api`
- API版本: v1
- 认证方式: JWT Bearer Token
- 数据格式: JSON

## JWT认证机制

### 访问令牌 (Access Token)
- 有效期: 15分钟
- 用途: 访问受保护的API接口
- 格式: Bearer Token

### 刷新令牌 (Refresh Token)
- 有效期: 7天
- 用途: 获取新的Access Token
- 存储位置: Redis

### 请求头格式
```
Authorization: Bearer {access_token}
```

## API接口

### 1. 用户登录
用户通过用户名和密码进行登录认证。

**接口信息:**
- URL: `POST /api/v1/auth/login`
- 描述: 用户登录获取访问令牌
- 认证要求: 无需认证

**请求参数:**
```json
{
  "userAccount": "string",  // 用户账号
  "userPassword": "string"  // 用户密码
}
```

**请求示例:**
```bash
curl -X POST http://localhost:10011/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "userAccount": "admin",
    "userPassword": "password123"
  }'
```

**响应示例:**
```json
{
  "success": true,
  "message": "操作成功",
  "data": {
    "id": 1,
    "userAccount": "admin",
    "unionId": null,
    "accessToken": "eyJhbGciOiJIUzI1NiJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiJ9...",
    "expire": null
  }
}
```

### 2. 令牌刷新
使用刷新令牌获取新的访问令牌。

**接口信息:**
- URL: `POST /api/v1/auth/refresh`
- 描述: 刷新访问令牌
- 认证要求: 无需认证

**请求参数:**
```
refreshToken=string  // 刷新令牌
```

**请求示例:**
```bash
curl -X POST "http://localhost:10011/api/v1/auth/refresh?refreshToken=eyJhbGciOiJIUzI1NiJ9..."
```

**响应示例:**
```json
{
  "success": true,
  "message": "操作成功",
  "data": {
    "id": null,
    "userAccount": null,
    "unionId": null,
    "accessToken": "eyJhbGciOiJIUzI1NiJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiJ9...",
    "expire": null
  }
}
```

### 3. 获取访问令牌
简化版的登录接口，仅返回访问令牌。

**接口信息:**
- URL: `POST /api/v1/auth/auth`
- 描述: 获取访问令牌（简化版登录）
- 认证要求: 无需认证

**请求参数:**
```json
{
  "userAccount": "string",  // 用户账号
  "userPassword": "string"  // 用户密码
}
```

**请求示例:**
```bash
curl -X POST http://localhost:10011/api/v1/auth/auth \
  -H "Content-Type: application/json" \
  -d '{
    "userAccount": "admin",
    "userPassword": "password123"
  }'
```

**响应示例:**
```json
{
  "success": true,
  "message": "操作成功",
  "data": "eyJhbGciOiJIUzI1NiJ9..."
}
```

### 4. 令牌验证
验证访问令牌的有效性。

**接口信息:**
- URL: `POST /api/v1/auth/validate`
- 描述: 验证访问令牌
- 认证要求: 可选的Authorization头

**请求头:**
```
Authorization: Bearer {access_token}  // 可选
```

**请求示例:**
```bash
curl -X POST http://localhost:10011/api/v1/auth/validate \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..."
```

**响应示例:**
```json
{
  "success": true,
  "message": "操作成功",
  "data": true
}
```

## 状态码说明

| 状态码 | 说明 | 描述 |
|--------|------|------|
| 200 | OK | 请求成功 |
| 400 | Bad Request | 请求参数错误 |
| 401 | Unauthorized | 未授权访问或令牌无效 |
| 403 | Forbidden | 禁止访问 |
| 500 | Internal Server Error | 服务器内部错误 |

## 错误响应格式

```json
{
  "success": false,
  "message": "错误描述",
  "data": null
}
```

## 常见错误码

| 错误信息 | 可能原因 | 解决方案 |
|----------|----------|----------|
| "用户不存在或密码错误" | 用户账号或密码不正确 | 检查用户名和密码 |
| "Refresh Token 已过期" | 刷新令牌已过期 | 重新登录获取新令牌 |
| "Refresh Token 已失效" | 刷新令牌在Redis中不存在或已失效 | 重新登录获取新令牌 |
| "系统错误" | 服务间调用失败或系统异常 | 检查服务状态和网络连接 |

## 配置信息

### JWT配置
```yaml
jwt:
  secret: "12345678901234567890123456789012"  # 32字节密钥
  access-expire: 900000        # 15分钟（毫秒）
  refresh-expire: 604800000    # 7天（毫秒）
```

### 服务配置
```yaml
spring:
  application:
    name: auth-service
server:
  port: 10011
  servlet:
    context-path: /api
```

## 安全注意事项

1. **令牌存储**: Access Token应存储在内存或HttpOnly Cookie中
2. **HTTPS传输**: 生产环境必须使用HTTPS协议
3. **密钥管理**: JWT密钥应定期轮换，使用强密钥
4. **令牌过期**: 合理设置令牌过期时间，平衡安全性和用户体验
5. **错误处理**: 不要在错误信息中泄露敏感信息

## 使用流程

1. **用户登录**: 调用`/login`接口获取Access Token和Refresh Token
2. **API访问**: 在请求头中携带Access Token访问受保护接口
3. **令牌刷新**: Access Token过期时使用Refresh Token获取新的Access Token
4. **令牌验证**: 可使用`/validate`接口验证Token有效性

## 联系信息

如有问题或建议，请联系开发团队。

---
*文档版本: v1.0*
*更新时间: 2025-12-14*