coder-common-thin-backend/api/authentication/登录认证API.md

# 登录认证API

## 概述

登录认证模块提供用户登录、退出、注册等功能，使用Sa-Token进行身份认证和会话管理。

## 接口列表

### 1. 用户登录

**接口地址**: `POST /auth/login`

**接口描述**: 用户使用账号密码登录系统

**是否需要认证**: 否

**请求参数**:

```json
{
  "loginName": "admin",
  "password": "123456",
  "codeKey": "uuid-key",
  "securityCode": "1234",
  "rememberMe": false
}
```

**请求参数说明**:

| 参数名 | 类型 | 必填 | 说明 | 校验规则 |
|--------|------|------|------|----------|
| loginName | String | 是 | 登录账号 | 长度3-16位，只能包含字母和数字 |
| password | String | 是 | 登录密码 | 不能为空 |
| codeKey | String | 是 | 验证码UUID | 不能为空 |
| securityCode | String | 是 | 验证码 | 不能为空 |
| rememberMe | Boolean | 否 | 记住登录 | 默认false |

**响应示例**:

```json
{
  "status": 200,
  "msg": "SUCCESS",
  "data": {
    "tokenName": "Authorization",
    "tokenValue": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
  },
  "traceId": "trace-123456"
}
```

**响应参数说明**:

| 参数名 | 类型 | 说明 |
|--------|------|------|
| tokenName | String | Token名称 |
| tokenValue | String | Token值 |

**错误码**:

| 状态码 | 错误信息 | 说明 |
|--------|----------|------|
| 400 | 账号长度为 3-16 位 | 登录账号长度不符合要求 |
| 400 | 账号格式为数字以及字母 | 登录账号格式不正确 |
| 400 | 请输入登录名 | 登录名为空 |
| 400 | 请输入密码 | 密码为空 |
| 400 | 验证码已失效 | 验证码Key无效 |
| 400 | 请输入验证码 | 验证码为空 |
| 400 | 验证码错误 | 验证码不正确 |
| 400 | 用户不存在 | 用户账号不存在 |
| 400 | 密码错误 | 密码不正确 |
| 400 | 账号已被停用 | 用户账号被禁用 |
| 400 | 账号已被锁定 | 用户账号被锁定 |

**调用示例**:

```bash
curl -X POST \
  http://localhost:18099/auth/login \
  -H 'Content-Type: application/json' \
  -d '{
    "loginName": "admin",
    "password": "123456",
    "codeKey": "550e8400-e29b-41d4-a716-446655440000",
    "securityCode": "1234",
    "rememberMe": false
  }'
```

---

### 2. 用户退出

**接口地址**: `GET /auth/logout`

**接口描述**: 用户退出登录，清除会话信息

**是否需要认证**: 是

**请求头**:

```
Authorization: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
```

**请求参数**: 无

**响应示例**:

```json
{
  "status": 200,
  "msg": "SUCCESS",
  "data": "退出成功",
  "traceId": "trace-123456"
}
```

**错误码**:

| 状态码 | 错误信息 | 说明 |
|--------|----------|------|
| 401 | 当前会话未登录 | 用户未登录或Token无效 |

**调用示例**:

```bash
curl -X GET \
  http://localhost:18099/auth/logout \
  -H 'Authorization: your-token-value'
```

---

### 3. 用户注册

**接口地址**: `POST /auth/register`

**接口描述**: 新用户注册账号

**是否需要认证**: 否

**请求参数**:

```json
{
  "loginName": "newuser",
  "password": "123456",
  "userName": "新用户",
  "codeKey": "uuid-key",
  "securityCode": "1234"
}
```

**请求参数说明**:

| 参数名 | 类型 | 必填 | 说明 | 校验规则 |
|--------|------|------|------|----------|
| loginName | String | 是 | 登录账号 | 长度3-16位，只能包含字母和数字 |
| password | String | 是 | 登录密码 | 不能为空 |
| userName | String | 是 | 用户姓名 | 不能为空 |
| codeKey | String | 是 | 验证码UUID | 不能为空 |
| securityCode | String | 是 | 验证码 | 不能为空 |

**响应示例**:

```json
{
  "status": 200,
  "msg": "SUCCESS",
  "data": "注册成功",
  "traceId": "trace-123456"
}
```

**错误码**:

| 状态码 | 错误信息 | 说明 |
|--------|----------|------|
| 400 | 账号长度为 3-16 位 | 登录账号长度不符合要求 |
| 400 | 账号格式为数字以及字母 | 登录账号格式不正确 |
| 400 | 请输入登录名 | 登录名为空 |
| 400 | 请输入密码 | 密码为空 |
| 400 | 请输入用户姓名 | 用户姓名为空 |
| 400 | 验证码已失效 | 验证码Key无效 |
| 400 | 请输入验证码 | 验证码为空 |
| 400 | 验证码错误 | 验证码不正确 |
| 400 | 账号已存在 | 登录账号已被注册 |

**调用示例**:

```bash
curl -X POST \
  http://localhost:18099/auth/register \
  -H 'Content-Type: application/json' \
  -d '{
    "loginName": "newuser",
    "password": "123456",
    "userName": "新用户",
    "codeKey": "550e8400-e29b-41d4-a716-446655440000",
    "securityCode": "1234"
  }'
```

---

## 认证流程说明

### 1. 登录流程

1. 用户获取验证码（调用验证码接口）
2. 用户输入账号、密码、验证码
3. 系统验证验证码有效性
4. 系统验证用户账号和密码
5. 系统检查用户状态（是否禁用/锁定）
6. 生成Token并返回给用户
7. 用户后续请求携带Token

### 2. Token使用

- Token需要在请求头中携带：`Authorization: token-value`
- Token有过期时间，过期后需要重新登录
- 系统支持多设备登录
- 管理员可以强制用户下线

### 3. 权限验证

- 登录后系统会根据用户角色加载权限
- 每个接口都会验证用户是否有相应权限
- 超级管理员拥有所有权限

### 4. 会话管理

- 用户登录信息存储在Redis中
- 支持会话延长
- 支持记住登录功能
- 系统会记录用户登录日志

## 安全特性

1. **密码加密**: 使用盐值加密存储密码
2. **验证码保护**: 防止暴力破解
3. **账号锁定**: 连续错误3次自动锁定
4. **IP限制**: 可配置IP白名单/黑名单
5. **会话安全**: Token有效期管理
6. **日志记录**: 记录所有登录操作

## 注意事项

1. 验证码有效期为5分钟
2. Token默认有效期为30天
3. 账号锁定时间为10分钟
4. 注册功能可通过配置开启/关闭
5. 建议在生产环境中启用HTTPS