# 用户认证 API 文档

## 📋 概述

本文档描述云酒馆项目前台用户认证系统的所有 API 接口。

## 🔗 基础信息

- **Base URL**: `http://localhost:8888/app`（开发环境）
- **认证方式**: JWT Bearer Token
- **Content-Type**: `application/json`

## 📌 API 接口列表

### 1. 用户注册

**接口**: `POST /app/auth/register`

**描述**: 新用户注册

**请求头**: 无需认证

**请求体**:
```json
{
  "username": "testuser",
  "password": "123456",
  "nickName": "测试用户",
  "email": "test@example.com",
  "phone": "13800138000"
}
```

**字段说明**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| username | string | 是 | 用户名，3-32字符 |
| password | string | 是 | 密码，6-32字符 |
| nickName | string | 否 | 昵称，最多50字符 |
| email | string | 否 | 邮箱地址 |
| phone | string | 否 | 手机号 |

**成功响应**:
```json
{
  "code": 0,
  "msg": "注册成功"
}
```

**错误响应**:
```json
{
  "code": 7,
  "msg": "用户名已存在"
}
```

---

### 2. 用户登录

**接口**: `POST /app/auth/login`

**描述**: 用户登录获取 Token

**请求头**: 无需认证

**请求体**:
```json
{
  "username": "testuser",
  "password": "123456"
}
```

**成功响应**:
```json
{
  "code": 0,
  "data": {
    "user": {
      "id": 1,
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "username": "testuser",
      "nickName": "测试用户",
      "email": "test@example.com",
      "phone": "13800138000",
      "avatar": "",
      "status": "active",
      "enable": true,
      "lastLoginAt": "2026-02-10T09:00:00Z",
      "chatCount": 0,
      "messageCount": 0,
      "aiSettings": null,
      "preferences": null,
      "createdAt": "2026-02-10T08:00:00Z"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresAt": 1707552000
  },
  "msg": "登录成功"
}
```

**错误响应**:
```json
{
  "code": 7,
  "msg": "用户名或密码错误"
}
```

---

### 3. 刷新 Token

**接口**: `POST /app/auth/refresh`

**描述**: 使用 RefreshToken 获取新的 Token

**请求头**: 无需认证

**请求体**:
```json
{
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

**成功响应**: 同登录接口

---

### 4. 用户登出

**接口**: `POST /app/auth/logout`

**描述**: 用户登出（清除会话）

**请求头**: 
```
x-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```
或
```
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

**请求体**: 无

**成功响应**:
```json
{
  "code": 0,
  "msg": "登出成功"
}
```

---

### 5. 获取用户信息

**接口**: `GET /app/auth/userinfo`

**描述**: 获取当前登录用户信息

**请求头**: 需要认证（JWT Token）

**成功响应**:
```json
{
  "code": 0,
  "data": {
    "id": 1,
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "username": "testuser",
    "nickName": "测试用户",
    "email": "test@example.com",
    "phone": "13800138000",
    "avatar": "",
    "status": "active",
    "enable": true,
    "lastLoginAt": "2026-02-10T09:00:00Z",
    "chatCount": 5,
    "messageCount": 120,
    "aiSettings": {},
    "preferences": {},
    "createdAt": "2026-02-10T08:00:00Z"
  }
}
```

---

### 6. 更新用户信息

**接口**: `PUT /app/user/profile`

**描述**: 更新当前用户的个人信息

**请求头**: 需要认证（JWT Token）

**请求体**:
```json
{
  "nickName": "新昵称",
  "email": "newemail@example.com",
  "phone": "13900139000",
  "avatar": "https://example.com/avatar.jpg",
  "preferences": "{\"theme\":\"dark\"}",
  "aiSettings": "{\"defaultModel\":\"gpt-4\"}"
}
```

**字段说明**: 所有字段均为可选

**成功响应**:
```json
{
  "code": 0,
  "msg": "更新成功"
}
```

---

### 7. 修改密码

**接口**: `POST /app/user/change-password`

**描述**: 修改当前用户密码

**请求头**: 需要认证（JWT Token）

**请求体**:
```json
{
  "oldPassword": "123456",
  "newPassword": "new123456"
}
```

**成功响应**:
```json
{
  "code": 0,
  "msg": "修改成功"
}
```

**错误响应**:
```json
{
  "code": 7,
  "msg": "原密码错误"
}
```

---

## 🔐 认证说明

### Token 使用方式

认证接口需要在请求头中携带 Token，支持两种方式：

**方式 1**: `x-token` 头
```http
x-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

**方式 2**: `Authorization` 头（Bearer Token）
```http
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

**方式 3**: Query 参数（不推荐，仅用于特殊场景）
```http
GET /app/auth/userinfo?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

### Token 有效期

- **Access Token**: 配置文件中的 `jwt.expiresTime` 设置（默认 7200 秒 = 2 小时）
- **Refresh Token**: 固定 7 天

### Token 刷新流程

1. Access Token 过期后，使用 Refresh Token 调用 `/app/auth/refresh` 接口
2. 获取新的 Access Token 和 Refresh Token
3. 使用新的 Token 继续访问 API

---

## 🧪 测试用例

### 使用 curl 测试

**1. 注册新用户**:
```bash
curl -X POST http://localhost:8888/app/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "password": "123456",
    "nickName": "测试用户"
  }'
```

**2. 登录**:
```bash
curl -X POST http://localhost:8888/app/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "password": "123456"
  }'
```

**3. 获取用户信息**（需替换 TOKEN）:
```bash
TOKEN="your_token_here"
curl -X GET http://localhost:8888/app/auth/userinfo \
  -H "x-token: $TOKEN"
```

**4. 更新用户信息**:
```bash
curl -X PUT http://localhost:8888/app/user/profile \
  -H "x-token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "nickName": "新昵称",
    "avatar": "https://example.com/avatar.jpg"
  }'
```

**5. 修改密码**:
```bash
curl -X POST http://localhost:8888/app/user/change-password \
  -H "x-token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "oldPassword": "123456",
    "newPassword": "new123456"
  }'
```

---

## ❗ 常见错误码

| 错误码 | 说明 |
|-------|------|
| 0 | 成功 |
| 7 | 业务错误（如用户名已存在、密码错误等） |
| 401 | 未认证或 Token 无效 |
| 403 | 账户被禁用或状态异常 |
| 500 | 服务器内部错误 |

---

## 📝 注意事项

1. **密码安全**: 所有密码均使用 bcrypt 加密存储，不可逆
2. **用户状态**: 只有 `status=active` 且 `enable=true` 的用户才能登录
3. **用户名唯一性**: 用户名和邮箱必须唯一
4. **会话管理**: 登出后会删除对应的会话记录，但 Token 在过期前仍然有效
5. **跨域配置**: 如需前端调用，请在 `initialize/router.go` 中启用 CORS 中间件

---

## 🔄 下一步开发

- [ ] 邮箱验证
- [ ] 手机号验证
- [ ] 找回密码
- [ ] 第三方登录（OAuth）
- [ ] 多设备登录管理
- [ ] 用户在线状态