docs(v3): 补充选产品接口字段映射 + 热销/发团日期缺字段说明 (#3142)

changelogs-v2/2026-05/28_3142_新建订单选主题接口-下单选品接通真实接口_PR3155.md

@@ -48,18 +48,42 @@ GET /admin/product/line/order-picker
 - `skuCount` / `fromPrice` / `hot` → 同名直取
 - 顶部统计「在售主题数」= 列表长度；「SKU总数」= Σ`skuCount`；「最低人均」= min(`fromPrice`)
 
-### 2. 第 2 步「选产品」— 用已有接口（无新增）
+### 2. 第 2 步「选产品」— 用已有接口（无新增），已在测试服实测返回结构
 
 ```
 GET /admin/product/item/list?lineId={lineId}&status=PUBLISHED
 ```
-- 选定主题后传其 `lineId`，只取已上架产品；返回 `ProductListRespVO` 分页
+- 选定主题后传其 `lineId`，只取已上架产品；返回 `PageResult<ProductListRespVO>`（`data.records[]` + `data.total`）
-- 已含选品所需全部字段：`productId` / `name` / `subtitle` / `tripDays` / `tripNights` / `tags` / `coverImageUrl` / `startPrice` / `tierPrices[]`
+- 数据权限同上（带 @DataScope，超管全部 / CORE·GROUP 全员 / CUSTOM 仅本人）
-- `tierPrices[]` 每项含 `tierSeq` / `tierName` / `tierDescription` / `startPrice` —— 下单提交需要的 `tierSeq` 从这里取
+- 下单提交需要的 `productId + tierSeq` 都从这里取（雪花 `productId` 按字符串透传，勿 Number()）
-- 数据权限同上（带 @DataScope）
 
-mock 里每张「SKU 卡」= 一个产品的一个档位；真实是一个产品(`productId`)含多个档位(`tierPrices`)。前端可按产品卡 + 档位选择，或按产品×档位平铺，提交时带 `productId + tierSeq`。
+返回 `records[]` 实测字段（与 Step2 SKU 卡片显示元素的映射）：
-（mock 的 `depDates` 发团日期文案无单一对应字段，可省略或后续走班期接口。）
+```jsonc
+{
+  "productId": 2043595351268519937,  // 产品ID(字符串透传)
+  "name": "6天5晚旷野版",              // 卡片大标题
+  "subtitle": "装甲车穿越·帐篷营地…",   // 副标题
+  "tags": ["亲子","露营"],            // 标签行(· tag · tag)
+  "tripDays": 6, "tripNights": 5,    // "6天5晚 起"
+  "coverImageUrl": "https://...",
+  "startPrice": 10.00,               // 产品级最低起价(可能 null)
+  "tierCount": 2,
+  "tierPrices": [                    // 档位数组(档次过滤 chips = 去重 tierName)
+    {"tierSeq":1, "tierName":"舒适", "tierDescription":"…", "startPrice":10.00},
+    {"tierSeq":2, "tierName":"豪华", "tierDescription":"…", "startPrice":null}  // 该档未设价
+  ]
+}
+```
+
+**SKU 卡渲染**：mock 里每张卡=一个产品的一个档位；真实是一个产品(`productId`)含多档位(`tierPrices[]`)。
+建议按「产品 × 档位」平铺成卡（每个 `tierPrices[i]` 一张卡），卡上：
+- 档位标签 ← `tierPrices[i].tierName`（"尊享档/挑战档"）
+- 价格 ← `tierPrices[i].startPrice`（**为 null 时显示 ¥-- / 灰**，别显示 0）
+- 提交带 `productId` + `tierPrices[i].tierSeq`
+
+**⚠️ 两个 mock 元素后端暂无对应字段（同「地区」性质，需前端确认怎么处理）：**
+- **「热销」徽标（每个 SKU）**：`/item/list` 无产品/档位级热门字段（热门目前只做到了主题级，在选主题接口的 `hot`）。→ 选产品卡片**先不显示热销徽标**；若确实要按"该产品下单较多"标热，需后端再加一个产品级下单量字段（同主题 hot 的做法，可另开工单）。
+- **「发团日期」（如 5-10 月）**：`/item/list` 无此字段，它是班期/价格日历的可售日期，不是单一文案。→ **先省略**；若要展示，需后端补"可售日期范围"或前端另调班期/价格日历接口。
 
 ### 3. 提交（不变）
 `POST /v3/admin/order`，入参 `productId` + `tierSeq` 等，已就绪。