# 结伴客后端API文档

## 1. 认证相关接口

### 用户注册

**请求方法**: POST
**请求路径**: `/api/v1/auth/register`
**请求体**: 
```json
{
  "username": "string", // 用户名（必需）
  "password": "string", // 密码（必需，至少6位）
  "nickname": "string", // 昵称（可选）
  "email": "string", // 邮箱（可选）
  "phone": "string" // 手机号（可选）
}
```
**响应**: 
```json
{
  "success": true,
  "data": {
    "user": { // 用户信息（不含敏感信息）
      "id": 1,
      "username": "testuser",
      "nickname": "测试用户",
      "email": "test@jiebanke.com",
      "phone": "13800000000",
      // 其他用户字段...
    },
    "token": "string"
  },
  "message": "注册成功"
}
```
**错误响应**: 
- 400: 用户名已存在 / 邮箱已存在 / 手机号已存在 / 密码长度不能少于6位
- 500: 服务器内部错误

### 用户登录

**请求方法**: POST
**请求路径**: `/api/v1/auth/login`
**请求体**: 
```json
{
  "username": "string", // 用户名/邮箱/手机号（必需）
  "password": "string" // 密码（必需）
}
```
**响应**: 
```json
{
  "success": true,
  "data": {
    "user": { // 用户信息（不含敏感信息）
      "id": 1,
      "username": "testuser",
      "nickname": "测试用户",
      "email": "test@jiebanke.com",
      "phone": "13800000000",
      // 其他用户字段...
    },
    "token": "string"
  },
  "message": "登录成功"
}
```
**错误响应**: 
- 400: 用户名和密码不能为空
- 401: 密码错误
- 403: 账户已被禁用
- 404: 用户不存在
- 500: 服务器内部错误

## 2. 用户管理接口

### 获取当前用户信息

**请求方法**: GET
**请求路径**: `/api/v1/users/profile`
**请求头**: `Authorization: Bearer {token}`
**响应**: 
```json
{
  "success": true,
  "data": {
    "user": { // 用户信息（不含敏感信息）
      "id": 1,
      "username": "testuser",
      "nickname": "测试用户",
      "email": "test@jiebanke.com",
      "phone": "13800000000",
      // 其他用户字段...
    }
  }
}
```
**错误响应**: 
- 401: 未提供认证token / 无效的认证token / token已过期 / 用户不存在
- 403: 账户已被禁用
- 500: 服务器内部错误

### 更新用户个人信息

**请求方法**: PUT
**请求路径**: `/api/v1/users/profile`
**请求头**: `Authorization: Bearer {token}`
**请求体**: 
```json
{
  "nickname": "string", // 昵称（可选）
  "avatar": "string", // 头像URL（可选）
  "gender": "string", // 性别（可选，可选值：male, female, other）
  "birthday": "string", // 生日（可选，格式：YYYY-MM-DD）
  "phone": "string", // 手机号（可选）
  "email": "string" // 邮箱（可选）
}
```
**响应**: 
```json
{
  "success": true,
  "data": {
    "user": { // 更新后的用户信息（不含敏感信息）
      "id": 1,
      "username": "testuser",
      "nickname": "新昵称",
      "email": "new@email.com",
      "phone": "13900000000",
      // 其他用户字段...
    },
    "message": "个人信息更新成功"
  }
}
```
**错误响应**: 
- 400: 没有有效的更新字段 / 邮箱已被其他用户使用 / 手机号已被其他用户使用
- 401: 未提供认证token / 无效的认证token / token已过期 / 用户不存在
- 403: 账户已被禁用
- 500: 更新用户信息失败 / 服务器内部错误

## 3. 管理员接口

### 搜索用户

**请求方法**: GET
**请求路径**: `/api/v1/admin/users/search`
**请求头**: `Authorization: Bearer {token}`
**请求参数**: 
- keyword: 搜索关键词（可选，模糊匹配用户名、昵称、邮箱、手机号）
- userType: 用户类型（可选）
- page: 当前页码（可选，默认：1）
- pageSize: 每页记录数（可选，默认：10）

**响应**: 
```json
{
  "success": true,
  "data": {
    "users": [
      {
        "id": 1,
        "username": "testuser",
        "user_type": "farmer",
        "real_name": "测试用户",
        "avatar_url": "",
        "email": "test@jiebanke.com",
        "phone": "13800000000",
        "status": "active",
        "created_at": "2024-01-01T12:00:00Z",
        "updated_at": "2024-01-01T12:00:00Z"
      }
      // 更多用户...
    ],
    "total": 1,
    "page": 1,
    "pageSize": 10,
    "pages": 1
  }
}
```
**错误响应**: 
- 401: 未提供认证token / 无效的认证token / token已过期 / 管理员不存在
- 403: 管理员账号已被禁用 / 需要管理员权限 / 权限不足
- 500: 服务器内部错误

### 批量更新用户状态

**请求方法**: POST
**请求路径**: `/api/v1/admin/users/batch-status`
**请求头**: `Authorization: Bearer {token}`
**请求体**: 
```json
{
  "userIds": [1, 2, 3], // 用户ID列表（必需）
  "status": "active" // 状态（必需，可选值：active, inactive）
}
```
**响应**: 
```json
{
  "success": true,
  "data": {
    "message": "成功更新 3 个用户状态",
    "affectedRows": 3
  }
}
```
**错误响应**: 
- 400: 请选择要操作的用户 / 无效的状态值
- 401: 未提供认证token / 无效的认证token / token已过期 / 管理员不存在
- 403: 管理员账号已被禁用 / 需要管理员权限 / 权限不足
- 500: 服务器内部错误

## 4. 系统接口

### 健康检查

**请求方法**: GET
**请求路径**: `/health`
**响应**: 
```json
{
  "status": "OK",
  "timestamp": "2024-01-01T12:00:00Z",
  "uptime": 1234.56,
  "environment": "production"
}
```

### 系统统计

**请求方法**: GET
**请求路径**: `/system-stats`
**响应**: 
```json
{
  "status": "OK",
  "timestamp": "2024-01-01T12:00:00Z",
  "environment": "production",
  "nodeVersion": "v18.16.0",
  "memoryUsage": {
    "rss": 123456789,
    "heapTotal": 12345678,
    "heapUsed": 1234567,
    "external": 123456
  },
  "uptime": 1234.56,
  "cpuCount": 8,
  "platform": "linux",
  "architecture": "x64"
}
```

## 5. 错误码说明

| 错误码 | 描述 | HTTP状态码 |
|-------|------|-----------|
| 400 | 请求参数错误 | 400 |
| 401 | 未授权（无效token、token过期等） | 401 |
| 403 | 权限不足或账户被禁用 | 403 |
| 404 | 资源不存在 | 404 |
| 429 | 请求过于频繁 | 429 |
| 500 | 服务器内部错误 | 500 |
| 503 | 服务不可用（如数据库连接失败） | 503 |

## 6. 认证机制

系统使用JWT（JSON Web Token）进行认证，所有需要认证的接口都需要在请求头中包含`Authorization: Bearer {token}`。

### Token有效期
- 默认有效期为7天
- 可通过环境变量`JWT_EXPIRE`自定义

### Token安全
- 生产环境请确保设置安全的`JWT_SECRET`环境变量
- 避免在客户端存储敏感信息

## 7. 接口限制

- 接口请求频率限制：生产环境15分钟内最多100次请求，开发环境15分钟内最多1000次请求
- 请求体大小限制：10kb
- 支持的请求内容类型：application/json

## 8. Swagger文档

在开发环境或设置`ENABLE_SWAGGER=true`环境变量时，可通过以下地址访问Swagger文档：
- https://webapi.jiebanke.com/api-docs