spatie/eloquent-sortable 已归档且不支持 Laravel 10+，应手动实现排序逻辑：添加非空 sort_order 字段、建索引、用事务批量更新序号。
composer require spatie/eloquent-sortable 失败或报错
常见现象是执行 composer require spatie/eloquent-sortable 后提示版本冲突、找不到包，或 Laravel 版本不兼容。根本原因是该包已停止维护（2023 年起归档），最新版只支持到 Laravel 9，且不再适配 PHP 8.2+ 的严格类型变化。
实操建议：
- 确认当前 Laravel 版本：运行
php artisan --version，若为 Laravel 10 或 11，直接放弃该包——它不会正常工作 - 改用活跃维护的替代方案：
spatie/laravel-eloquent-sortable是旧包重命名后的官方新仓库，但注意：它只是镜像迁移，实际仍不支持 Laravel 10+ - 真正可用的现代方案是
renatomarinho/laravel-page-speed？不对——那是压缩插件。正确答案是：staudenmeir/laravel-adjacency-list（适合树形排序）或更通用的cviebrock/eloquent-sluggable？也不对。最轻量、无依赖、Laravel 10+ 友好的做法是手写排序逻辑 +orderBy('sort_order')，配合模型事件自动维护序号
想让模型支持拖拽排序，但 migration 没加 sort_order 字段
几乎所有排序逻辑都依赖一个整数字段（如 sort_order）来记录顺序。漏掉这步，后续所有操作都会“看起来生效，实际无效”——比如调用 $model->moveBefore($other) 却没反应，或者数据库里全是 NULL。
实操建议：
- 新建 migration：
php artisan make:migration add_sort_order_to_posts_table - 在
up()方法中添加：$table->unsignedInteger('sort_order')->default(0)；别用nullable()，否则排序时NULL值会排在最前，打乱预期 - 如果表已有数据，记得补默认值：
DB::table('posts')->update(['sort_order' => DB::raw('id')])（假设按创建顺序排） - 索引很重要：加
$table->index('sort_order')，否则大量数据拖拽时orderBy会变慢
用 $model->moveAfter() / moveBefore() 但顺序没变
函数调用看似成功，日志也没报错，但查数据库发现 sort_order 没更新。大概率是模型没启用排序行为，或事务/缓存干扰了写入。
Workflow Decomposer
下载
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
实操建议：
- 确保模型用了
use \Spatie\EloquentSortable\Sortable;和use \Spatie\EloquentSortable\SortableTrait;——但再次强调：Laravel 10+ 下这些 trait 会因 Eloquent 内部方法签名变更而静默失效 - 检查是否在事务里调用：如果包裹在
DB::transaction()中，且后续抛异常回滚，sort_order更新就白做了 - 更可靠的做法是绕过 trait，手动更新：
DB::table('posts')->where('id', $targetId)->update(['sort_order' => $newOrder])，再批量调整其他行（例如所有sort_order >= $newOrder的行 +1） - 避免用
save()触发模型事件来更新顺序——容易和监听器循环调用冲突
前端拖拽后，API 返回 500 但没报错信息
常见于用 Axios 提交排序请求时，后端没做防重复提交或并发保护，两个拖拽请求几乎同时到达，导致两行被设成同一个 sort_order，触发唯一约束失败，但 Laravel 默认隐藏了底层 SQL 错误。
实操建议：
- 打开调试模式看真实错误：
APP_DEBUG=true，你会看到类似SQLSTATE[23000]: Integrity constraint violation: 1062 Duplicate entry '5' for key 'posts.sort_order_unique' - 不要依赖数据库唯一索引强制校验——它会让用户体验断崖式下跌。应在业务层做重排：收到新顺序列表后，用
DB::transaction()批量更新全部sort_order，按数组下标赋值（[0,1,2,3]） - 前端传参建议用 ID 数组：
['id1','id2','id3']，后端按索引设置sort_order，比单次移动更健壮
真正麻烦的是跨页排序和软删除共存时的序号空洞问题——这时候连手写逻辑都要额外判断 deleted_at IS NULL，不是加个包就能解决的。
