Initial commit: skills library

- 70 skills with code and documentation - Add .gitignore (ignore __pycache__, output/, temp/, venv/) - Clean up test intermediates and caches
2026-04-26 19:27:40 +08:00
commit 04db423416
861 changed files with 210414 additions and 0 deletions
@@ -0,0 +1,239 @@
+# 备份与恢复 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
+```