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

权限: 管理员

请求体:

{
  "description": "修改压手腕问题前"
}

响应:

{
  "message": "备份成功",
  "backup_id": "backup_20260419_143000",
  "includes": ["classes", "students", "problems", "config"]
}

示例:

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

---

2. 查看备份列表

接口: GET /api/backup

权限: 登录用户

响应:

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

示例:

curl http://localhost:5000/api/backup

---

3. 查看备份详情

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

权限: 登录用户

响应:

{
  "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", ...]
}

示例:

curl http://localhost:5000/api/backup/backup_20260419_143000

---

4. 恢复备份

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

权限: 管理员

请求体:

{
  "confirm": "确认恢复"
}

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

响应:

{
  "message": "恢复成功",
  "restored": ["classes", "students", "problems"],
  "auto_backup": "auto_before_restore_20260419_150000"
}

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

示例:

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（默认今天）

权限: 管理员

响应:

[
  {
    "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"
  }
]

示例:

# 查看今天的日志
curl http://localhost:5000/api/logs

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

---

安全机制

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

工作流程示例

场景：修改问题配置

# 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

场景：数据恢复

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

# 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