soul-yongping/开发文档/章节拖拽排序-后台说明.md

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

一、后台已实现

1. 接口

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

请求体（拖拽排序时）：

{
  "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 会报错。

检查：

SHOW COLUMNS FROM chapters LIKE 'sort_order';

若不存在，执行迁移：

cd e:\Gongsi\Mycontent
node .cursor/scripts/db-exec/run.js -f soul-api/scripts/add-sort-order-to-chapters.sql

或手动执行：

ALTER TABLE chapters ADD COLUMN sort_order INT DEFAULT 0;

2. 现有数据处理

若已有数据且 sort_order 为 NULL 或未设置，可先按当前顺序初始化：

SET @i = 0;
UPDATE chapters SET sort_order = (@i := @i + 1) ORDER BY id;

---

三、排查“无法拖拽”

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

---

四、快速验证

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