# 章节拖拽排序 - 后台处理说明

## 一、后台已实现

### 1. 接口

- **路径**：`PUT /api/db/book`
- **鉴权**：需登录管理端（AdminAuth）

**请求体**（拖拽排序时）：
```json
{
  "action": "reorder",
  "ids": ["1.1", "2.3", "3.1", ...]
}
```

- `ids`：所有 section 的 id，按新的排序顺序排列
- 后端会依次将每条记录的 `sort_order` 更新为 0、1、2、…

### 2. 代码位置

- `soul-api/internal/handler/db_book.go`：`DBBookAction` 中 `http.MethodPut` 分支，约第 196–206 行

---

## 二、数据库必须支持

### 1. `sort_order` 列

`chapters` 表必须有 `sort_order` 列，否则 `UPDATE sort_order` 会报错。

**检查**：
```sql
SHOW COLUMNS FROM chapters LIKE 'sort_order';
```

**若不存在，执行迁移**：
```bash
cd e:\Gongsi\Mycontent
node .cursor/scripts/db-exec/run.js -f soul-api/scripts/add-sort-order-to-chapters.sql
```

或手动执行：
```sql
ALTER TABLE chapters ADD COLUMN sort_order INT DEFAULT 0;
```

### 2. 现有数据处理

若已有数据且 `sort_order` 为 NULL 或未设置，可先按当前顺序初始化：
```sql
SET @i = 0;
UPDATE chapters SET sort_order = (@i := @i + 1) ORDER BY id;
```

---

## 三、排查“无法拖拽”

| 现象 | 可能原因 | 处理方式 |
|------|----------|----------|
| 拖不起来 | 拖拽手柄太小、浏览器兼容性 | 点击左侧 ⋮⋮ 后按住再拖动 |
| 拖到目标没反应 | 未触发 drop | 确认拖到其他 section 行再松手 |
| 松手后弹“排序失败” | 1. `sort_order` 列不存在<br>2. 鉴权失败 401<br>3. 接口异常 | 1. 执行迁移脚本<br>2. 确认已登录管理端<br>3. 查看 soul-api 日志和浏览器控制台 |

---

## 四、快速验证

1. 执行迁移（若 `sort_order` 不存在）
2. 重启 soul-api
3. 在管理端登录后打开「内容管理 → 章节管理」
4. 用 ⋮⋮ 拖拽某一节到另一位置，松手后应刷新并显示新顺序