skills/piano-practice-sys/references/backup_api.md

# 备份与恢复 API 详细文档

## 概述

系统内置备份功能，支持数据备份、查看、恢复，以及操作日志查看。

## 备份目录结构

```
bk/
├── backup_20260419_143000/     # 备份文件夹
│   ├── meta.json               # 备份元信息
│   ├── classes.json            # 班级数据
│   ├── students.json           # 学员数据
│   ├── problems/               # 问题配置文件
│   │   ├── 01_手小.md
│   │   ├── 04_压手腕.md
│   │   └── ...
│   └── api_config.json         # API配置
├── backup_20260420_100000/     # 另一个备份
├── logs/
│   ├── 2026-04-19.jsonl        # 操作日志
│   └── 2026-04-20.jsonl
```

## API 接口

### 1. 创建备份

**接口**: `POST /api/backup`

**权限**: 管理员

**请求体**:
```json
{
  "description": "修改压手腕问题前"
}
```

**响应**:
```json
{
  "message": "备份成功",
  "backup_id": "backup_20260419_143000",
  "includes": ["classes", "students", "problems", "config"]
}
```

**示例**:
```bash
curl -X POST http://localhost:5000/api/backup \
  -H "Content-Type: application/json" \
  -d '{"description": "修改压手腕问题前"}'
```

---

### 2. 查看备份列表

**接口**: `GET /api/backup`

**权限**: 登录用户

**响应**:
```json
[
  {
    "id": "backup_20260419_143000",
    "created_at": "2026-04-19T14:30:00",
    "operator": "admin",
    "description": "修改压手腕问题前",
    "includes": ["classes", "students", "problems", "config"]
  }
]
```

**示例**:
```bash
curl http://localhost:5000/api/backup
```

---

### 3. 查看备份详情

**接口**: `GET /api/backup/<backup_id>`

**权限**: 登录用户

**响应**:
```json
{
  "meta": {
    "backup_id": "backup_20260419_143000",
    "created_at": "2026-04-19T14:30:00",
    "operator": "admin",
    "description": "修改压手腕问题前",
    "includes": ["classes", "students", "problems", "config"]
  },
  "classes": [...],
  "students": [...],
  "problems": ["01_手小.md", "04_压手腕.md", ...]
}
```

**示例**:
```bash
curl http://localhost:5000/api/backup/backup_20260419_143000
```

---

### 4. 恢复备份

**接口**: `POST /api/backup/<backup_id>/restore`

**权限**: 管理员

**请求体**:
```json
{
  "confirm": "确认恢复"
}
```

**⚠️ 安全要求**: 必须输入 exactly `确认恢复` 才能执行

**响应**:
```json
{
  "message": "恢复成功",
  "restored": ["classes", "students", "problems"],
  "auto_backup": "auto_before_restore_20260419_150000"
}
```

**注意**: 恢复前会自动创建当前数据的备份（auto_before_restore_xxx）

**示例**:
```bash
curl -X POST http://localhost:5000/api/backup/backup_20260419_143000/restore \
  -H "Content-Type: application/json" \
  -d '{"confirm": "确认恢复"}'
```

---

### 5. 查看操作日志

**接口**: `GET /api/logs`

**参数**:
- `date`: 日期，格式 `YYYY-MM-DD`（默认今天）

**权限**: 管理员

**响应**:
```json
[
  {
    "timestamp": "2026-04-19T14:30:00",
    "action": "backup_create",
    "operator": "admin",
    "target_type": "system",
    "target_id": "backup_20260419_143000",
    "detail": "创建备份: 修改压手腕问题前",
    "ip": "127.0.0.1"
  },
  {
    "timestamp": "2026-04-19T15:00:00",
    "action": "problem_update",
    "operator": "admin",
    "target_type": "problem",
    "target_id": "04",
    "detail": "更新问题: 压手腕",
    "ip": "127.0.0.1"
  }
]
```

**示例**:
```bash
# 查看今天的日志
curl http://localhost:5000/api/logs

# 查看指定日期的日志
curl "http://localhost:5000/api/logs?date=2026-04-19"
```

---

## 安全机制

| 机制 | 说明 |
|------|------|
| 权限控制 | 备份/恢复/日志需要管理员权限 |
| 二次确认 | 恢复必须输入"确认恢复" |
| 自动备份 | 恢复前自动备份当前数据 |
| 操作日志 | 所有操作记录可追溯 |

## 工作流程示例

### 场景：修改问题配置

```bash
# 1. 先看看当前的问题配置
curl http://localhost:5000/api/settings/problems

# 2. 讨论后确认要修改"压手腕"问题

# 3. 修改前创建备份
curl -X POST http://localhost:5000/api/backup \
  -d '{"description": "修改压手腕问题前"}'

# 4. 执行修改（通过Web界面或API）

# 5. 验证修改结果
curl http://localhost:5000/api/settings/problems/04
```

### 场景：数据恢复

```bash
# 发现修改出问题，想要恢复

# 1. 查看备份列表
curl http://localhost:5000/api/backup

# 2. 查看想要恢复的备份内容
curl http://localhost:5000/api/backup/backup_20260419_143000

# 3. 恢复备份（需要确认）
curl -X POST http://localhost:5000/api/backup/backup_20260419_143000/restore \
  -d '{"confirm": "确认恢复"}'

# 4. 验证恢复结果
curl http://localhost:5000/api/students
```