# 用户操作手册

本文档面向普通用户，描述用户管理系统的使用方法。

---

## 1. 注册与登录

### 1.1 注册账号

**路径**：`POST /api/v1/auth/register`

```json
{
  "username": "yourname",
  "password": "SecurePass123!",
  "email": "you@example.com"
}
```

**密码要求**：
- 最少 8 位
- 必须包含大写字母
- 必须包含小写字母
- 必须包含数字
- 必须包含特殊字符（`!@#$%^&*` 等）

### 1.2 登录

**路径**：`POST /api/v1/auth/login`

```json
{
  "account": "yourname",
  "password": "SecurePass123!",
  "device_id": "your-device-id"
}
```

返回的响应中包含：
- `access_token` — API 访问令牌（内存存储，不要持久化）
- `refresh_token` — 刷新令牌（用于续期 access_token）
- `expires_in` — access_token 有效期（秒）

### 1.3 登录安全验证

如果账户开启了 TOTP 两步验证，登录后会返回：

```json
{
  "requires_totp": true,
  "temp_token": "xxx",
  "user_id": 123
}
```

此时需要完成 TOTP 验证：

**路径**：`POST /api/v1/auth/login/totp-verify`

```json
{
  "user_id": 123,
  "code": "123456",
  "device_id": "your-device-id",
  "temp_token": "xxx"
}
```

---

## 2. 账户安全

### 2.1 修改密码

**路径**：`PUT /api/v1/auth/password`

```json
{
  "old_password": "OldPass123!",
  "new_password": "NewPass456!"
}
```

**注意**：修改密码会使除当前设备外的所有会话失效。

### 2.2 忘记密码

**路径**：`POST /api/v1/auth/password/forgot`

```json
{
  "email": "you@example.com"
}
```

系统会向邮箱发送重置链接。

### 2.3 设置 TOTP 两步验证

**步骤 1**：请求 TOTP 绑定信息
**路径**：`POST /api/v1/auth/totp/setup`

返回二维码和密钥。使用 Google Authenticator 或其他 TOTP 应用扫描。

**步骤 2**：启用 TOTP
**路径**：`POST /api/v1/auth/totp/enable`

```json
{
  "code": "123456"
}
```

启用后，下次登录需要输入 TOTP 验证码。

### 2.4 禁用 TOTP

**路径**：`POST /api/v1/auth/totp/disable`

```json
{
  "code": "123456"
}
```

### 2.5 恢复码

首次启用 TOPT 时，系统会提供一组恢复码。

**用途**：当 TOTP 设备丢失时，使用恢复码恢复登录。

**保存建议**：将恢复码打印或手写保存到安全位置，切勿截图或保存到云端。

---

## 3. 设备管理

### 3.1 查看我的设备

**路径**：`GET /api/v1/devices`

返回当前账户下所有已登录设备列表。

### 3.2 查看信任设备

**路径**：`GET /api/v1/devices/trusted`

返回已标记为信任的设备列表。信任设备在有效期内免 TOTP 验证。

### 3.3 信任当前设备

**路径**：`POST /api/v1/devices/trust`

将当前设备标记为信任设备。

**注意**：需要在设备详情中查看设备 ID。

### 3.4 取消设备信任

**路径**：`DELETE /api/v1/devices/:id/trust`

### 3.5 登出其他设备

**路径**：`POST /api/v1/devices/logout-others`

将除当前设备外的所有其他设备登出。

Header 中需要指定当前设备：`X-Device-ID: your-device-id`

---

## 4. 个人资料

### 4.1 查看个人资料

**路径**：`GET /api/v1/auth/userinfo`

### 4.2 更新个人资料

**路径**：`PUT /api/v1/users/profile`

```json
{
  "nickname": "Your Name",
  "phone": "13800138000"
}
```

### 4.3 上传头像

**路径**：`POST /api/v1/users/:id/avatar`

支持的格式：JPEG、PNG、GIF、WebP
最大文件大小：5MB

---

## 5. Token 刷新

Access Token 有效期较短，过期后需要使用 Refresh Token 续期：

**路径**：`POST /api/v1/auth/refresh`

```json
{
  "refresh_token": "your_refresh_token"
}
```

返回新的 access_token 和 refresh_token。

---

## 6. 账户注销

**路径**：`DELETE /api/v1/users/account`

注销后所有数据将被永久删除，不可恢复。

---

## 7. API 认证

所有需要认证的 API，在请求 Header 中添加：

```
Authorization: Bearer <access_token>
```

示例：

```bash
curl http://localhost:8080/api/v1/auth/userinfo \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

---

## 8. 错误代码

| 代码 | 说明 |
|------|------|
| 400 | 请求参数错误 |
| 401 | 未认证或 Token 已过期 |
| 403 | 无权限 |
| 404 | 资源不存在 |
| 429 | 请求过于频繁（触发限流） |
| 500 | 服务器内部错误 |

---

*最后更新：2026-05-10*