feat(product-v2): 主题下版本拖拽排序接口 changelog (#3218, 工单 #3215)

changelogs/2026-05/28_feat_admin_product_reorder.md

@@ -0,0 +1,74 @@
+# 【前端·后台】主题下版本(产品)拖拽排序 — 新增批量重排接口
+
+> **类型**: 新增后端接口(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 均已验证;测试数据已恢复原序）
+```
+
+如对入参格式、错误提示文案有调整需求,告诉后端即可改。