🎨 重构用户端前端为vue开发，完善基础类和角色相关接口
This commit is contained in:
382
docs/用户认证API文档.md
Normal file
382
docs/用户认证API文档.md
Normal file
@@ -0,0 +1,382 @@
|
||||
# 用户认证 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）
|
||||
- [ ] 多设备登录管理
|
||||
- [ ] 用户在线状态
|
||||
Reference in New Issue
Block a user