# 【前端·后台】主题下版本(产品)拖拽排序 — 新增批量重排接口

> **类型**: 新增后端接口(feat,后端已改并部署测试服验证通过)
> **服务**: hl-product-service-v2
> **日期**: 2026-05-28
> **影响范围**: 后台「版本列表」页(主题下的版本/产品列表)
> **归属**: 后端已交付(PR #3218 → dev,#3220 同步 dev-v3)
> **状态**: 已部署测试服并验证通过
> **关联工单**: #3215

---

## 一、背景

后台「版本列表」(一个主题/产品线下挂的多个版本)需要支持人工排序。

后端核查:`product.sort_order` 字段早已存在,且**管理端列表与小程序端列表本来就按 `sort_order` 升序排序**——缺的只是「设置顺序」的入口(此前 sortOrder 恒为默认 0,无处可改)。本次补上批量重排接口,前端做拖拽 UI 即可。

## 二、新增接口

```
POST /admin/product/item/reorder
```

请求体(把拖动后的目标顺序**全量**提交):

```json
{
  "lineId": 2045004175602868226,
  "items": [
    { "productId": 1001, "sortOrder": 1 },
    { "productId": 1002, "sortOrder": 2 },
    { "productId": 1003, "sortOrder": 3 }
  ]
}
```

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| lineId | Long | 是 | 主题(产品线)ID |
| items | 数组 | 是 | 重排清单,须覆盖该主题下当前列表所见的**全部**版本 |
| items[].productId | Long | 是 | 版本(产品)ID |
| items[].sortOrder | Integer | 是 | 新排序号,**越小越靠前**;取值必须是 1..N 连续无重(N=版本数) |

成功响应:`{ "code": 200, "message": "版本排序成功" }`

## 三、前端接入要点

1. **全量提交**:用户拖完后,把该主题下当前列表里所有版本按新的可视顺序,依次赋 `sortOrder = 1, 2, 3, ... N` 一次性提交(不是只提交被移动的那一个)。
2. **生效范围**:重排后,后台「版本列表」和小程序端「该主题下产品列表」都会按新顺序展示(两端同一个 sort_order)。
3. **排序号规则**:`sortOrder` 必须是 `1..N` 连续不重复。前端按可视位置生成 1..N 即可,不要传 0、不要跳号、不要重复。
4. **数据权限**:`items` 须与当前列表接口(`GET /admin/product/item/list?lineId=...`)返回的版本集合一致(超管看全部;非超管下 CUSTOM 只看本人)。简单做法:重排清单直接取列表接口当前返回的那批 productId。
5. **防连点**:接口有 5 秒幂等窗口,同一用户 5 秒内重复提交会返回 `100502 请勿重复提交`,正常拖拽保存无影响。

## 四、错误码

| code | 含义 | 触发 |
|------|------|------|
| 430203 | 重排清单与该主题下版本不匹配,请刷新页面后重试 | items 数量/productId 集合与该主题下可见版本不一致(漏传、多传、外来或不可见 productId、重复 productId) |
| 430204 | 排序号必须为 1..N 连续无重 | sortOrder 出现重复、跳号、超出 [1,N] |
| 400 | sortOrder 必须 >= 1 | 传了 sortOrder < 1(参数校验) |
| 100502 | 请勿重复提交 | 5 秒内重复提交 |

## 五、测试服实测(主题 2056938045633904642,4 个版本)

```
POST /admin/product/item/reorder  {lineId, items:[P1->4,P2->3,P3->2,P4->1]}
→ 200 版本排序成功
GET  /admin/product/item/list?lineId=2056938045633904642
→ 列表顺序由 P1,P2,P3,P4 翻转为 P4,P3,P2,P1(sortOrder 1,2,3,4)
（异常路径 430203 / 430204 / 400 / 100502 均已验证;测试数据已恢复原序）
```

如对入参格式、错误提示文案有调整需求,告诉后端即可改。
