From 97608cfca6f89ce238e006007d9a52a5414cf362 Mon Sep 17 00:00:00 2001
From: API Changelog Bot <changelog@hulalv.com>
Date: Mon, 7 Sep 2026 12:34:59 +0800
Subject: [PATCH] =?UTF-8?q?docs(changelog):=20#7244=20=E9=80=89=E5=93=81?=
 =?UTF-8?q?=E6=8E=A5=E5=8F=A3=E9=80=8F=E5=87=BA=20productType=20=E4=B8=8E?=
 =?UTF-8?q?=E5=9B=A2=E6=9C=9F=E7=8F=AD=E6=9C=9F=E5=88=97=E8=A1=A8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01N7Xpgcv9nncadAXQtWhg4P
---
 ...€�出产å“�类型与团期ç�­æœŸåˆ—表-修改接å�£-管ç�†å�Žå�°.md | 428 ++++++++++++++++++
 1 file changed, 428 insertions(+)
 create mode 100644 changelogs-v2/2026-09/07_7244_选�接��出产�类型与团期�期列表-修改接�-管���.md

diff --git a/changelogs-v2/2026-09/07_7244_选�接��出产�类型与团期�期列表-修改接�-管���.md b/changelogs-v2/2026-09/07_7244_选�接��出产�类型与团期�期列表-修改接�-管���.md
new file mode 100644
index 00000000..b9efb583
--- /dev/null
+++ b/changelogs-v2/2026-09/07_7244_选�接��出产�类型与团期�期列表-修改接�-管���.md
@@ -0,0 +1,428 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7244"
+title: "订�选�接��出 productType 与团期�期列表 batches"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修改接�"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: "mmg"
+frontend_ref: ""
+target_release: ""
+verified_at: "2026-09-07"
+status_note: "PR #7259 已�入 dev-v3(9800cddde);2026-09-07 测试环境网关实测 15/15 通过(AC-1/1b/2/3/4/5/6)。�端待办:新建订�选择 GROUP 产�时必须在选�页选定�期,未选��许进入下一步——详�第八.5 节。"
+updated_at: "2026-09-07"
+base: "dev-v3"
+---
+
+# 订�选�接�: 新增 productType 与内嵌�售�期列表 batches
+
+> **�务**: hl-product-service-v2 ｜ **PR**: #7259 ｜ **Issue**: #7244 ｜ **�并�交**: `9800cddde`
+> **影�范围**: 管���「新建订� → 选择产��页
+
+---
+
+## ⚠� 关键�化
+
+**新建订�时，团期产�（`productType === "GROUP"`）必须让��选定一个�期，�选��许进入下一步。�期数�现在直接内嵌在选�接�的�个产�项里，�端�需���独请求�期接�。**
+
+�应新增两个字段：`productType`（产�类型）与 `batches`（该产�当��售�期列表）。**11 个旧字段的�称�类型�顺�一字未动**，�消费新字段的页���影�。
+
+---
+
+## 一�背景
+
+新建订�页选完产��直接让��手填出�日期，团期产�因此�能建出「没有归属�期�或「出�日与任何�期都对�上�的订�，�续团期看�认领�到该�。
+
+�在选�页当场选�期，就需�选�接�把�期带出�。原本�以�加一个「按产�查�期�的接�，但选�页是分页列表，�个产�一次请求会退化� N+1；因此改为在选�接�内嵌，一次请求把本页所有团期产�的�售�期全部带回。
+
+---
+
+## 二��更接�清�
+
+| # | 接� | 方法 | 路径 | �更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 订�选�列表 | GET | `/admin/product/item/order-picker` | **�应新增字段** | �个产�项新增 `productType` 与 `batches[]` |
+
+入��路径�错误��未�。
+
+---
+
+## 三�接�详情
+
+### 1. 订�选�列表 `GET /admin/product/item/order-picker`
+
+**VO**: `OrderPickerProductVO`（本次新增两个��嵌套类 `OrderPickerProductVO.BatchItem`�`OrderPickerProductVO.BatchTierPrice`）
+
+#### 使用场景
+
+管���「新建订���程第 1 步「选择产��页加载与翻页时调用。��按主题或关键字筛出产�，选中产��进入第 2 步选档�。本次改动�，团期产�的�售�期�产�一起返回，��在�一页选定�期，��需��独请求�期接�，也��手填出�日期。
+
+#### 入�
+
+| 字段 | �置 | 类型 | 必填 | 约� | 说明 |
+|------|------|------|------|------|------|
+| `lineId` | query | Long | � | - | 主题/线路 ID，按主题筛选产� |
+| `keyword` | query | String | � | - | 产��关键字 |
+| `page` | query | Integer | � | 默认 1 | 页� |
+| `pageSize` | query | Integer | � | 默认 10 | �页�数 |
+
+#### 出� `Result<PageResult<OrderPickerProductVO>>`
+
+`data.records[]` 的�一项：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `productId` | String | 产� ID（雪花，字符串�列化）。�空 |
+| `name` | String | 产��。�空 |
+| `subtitle` | String | 副标题。�空 |
+| `tripDays` | Integer | 行程天数。�空 |
+| `tripNights` | Integer | 行程晚数。�空 |
+| `tags` | String[] | 标签。�空 |
+| `coverImageUrl` | String | ��图。�空 |
+| `startPrice` | String | 起价（金�字符串）。�空 |
+| `tierPrices` | Object[] | 产�档�起价（`tierSeq` / `tierName` / `tierDescription` / `startPrice`）。�空 |
+| `hot` | Boolean | 是�热门。�空 |
+| `nextSaleDate` | String | 最近�售日。�空 |
+| **`productType`** | **String** | **新增**。产�类型，�六.5。�空 |
+| **`batches`** | **Object[]** | **新增**。当��售�期列表。� GROUP 产��为 `[]`（空数组，**�是 null**）。�空 |
+
+**`batches[]` �一项**
+
+| 字段 | 类型 | �空 | 说明 |
+|------|------|------|------|
+| `batchId` | String | � | �期 ID（雪花，字符串�列化）。创建订�时作为 `productBatchId` 回传 |
+| `batchNo` | String | � | �期编� |
+| `batchLabel` | String | � | 期�，如 `"7"` 表示第 7 期。**按该产�全部未删�期的出�日���置计算**，与团期看�显示的期�一致 |
+| `batchName` | String | 是 | �期�（�端已去除��空格） |
+| `departureDate` | String | � | 出�日 `yyyy-MM-dd` |
+| `endDate` | String | 是 | 返团日 `yyyy-MM-dd` |
+| `enrollmentDeadline` | String | 是 | 报�截止日 `yyyy-MM-dd` |
+| `maxRooms` | Integer | � | 房间数上�。**本接��� null**，`0` = �� |
+| `remainRooms` | Integer | 是 | 剩余房数。**`null` = ��，`0` = 已满**。���线下��房数 |
+| `maxParticipants` | Integer | 是 | 人数上�，`null` 或 `0` = �� |
+| `remainSlots` | Integer | 是 | 剩余人数。**`null` = ��，`0` = 已满** |
+| `batchStatus` | String | � | �期状�，�六.5 |
+| `batchStatusLabel` | String | � | �期状�中文文案，�直接显示 |
+| `tierPrices` | Object[] | � | 该�期的档�价，至少 1 项 |
+
+**`batches[].tierPrices[]` �一项**
+
+| 字段 | 类型 | �空 | 说明 |
+|------|------|------|------|
+| `tierSeq` | Integer | � | 档���，未�置档�时为 `1` |
+| `tierName` | String | � | 档��，未�置档�时为 `"默认档"` |
+| `adultPrice` | String | 是 | �人价（金�字符串） |
+| `childPrice` | String | 是 | 儿童价（金�字符串） |
+
+#### 请求示例
+
+```http
+GET /admin/product/item/order-picker?lineId=2044248925572919297&page=1&pageSize=20
+Authorization: Bearer {token}
+```
+
+#### �应示例
+
+测试环境实测，团期产�：
+
+```json
+{
+  "code": 200,
+  "msg": null,
+  "data": {
+    "total": 1,
+    "records": [
+      {
+        "productId": "2044306857534636034",
+        "name": "冻干粉�短信给",
+        "subtitle": "�短信给对方�定",
+        "tripDays": 3,
+        "tripNights": 2,
+        "tags": ["亲�", "研学", "露�"],
+        "coverImageUrl": "https://hlgl-test.oss-cn-beijing.aliyuncs.com/test/material/2026/03/07/ed278d1da74c3827cb06b7f0cf6091fe.jpg",
+        "startPrice": "1000.00",
+        "tierPrices": [
+          { "tierSeq": 1, "tierName": "轻奢", "tierDescription": null, "startPrice": "1000.00" }
+        ],
+        "hot": true,
+        "nextSaleDate": "2026-10-01",
+        "productType": "GROUP",
+        "batches": [
+          {
+            "batchId": "2052935476557328386",
+            "batchNo": "Q202610012052935476548939777",
+            "batchLabel": "7",
+            "batchName": "没，那你",
+            "departureDate": "2026-10-01",
+            "endDate": "2026-10-03",
+            "enrollmentDeadline": "2026-09-30",
+            "maxRooms": 80,
+            "remainRooms": 25,
+            "maxParticipants": 0,
+            "remainSlots": null,
+            "batchStatus": "ENROLLING",
+            "batchStatusLabel": "报�中",
+            "tierPrices": [
+              { "tierSeq": 1, "tierName": "轻奢", "adultPrice": "2925.00", "childPrice": "2425.00" }
+            ]
+          },
+          {
+            "batchId": "2096631555760807938",
+            "batchNo": "Q202612012096631555752419329",
+            "batchLabel": "8",
+            "batchName": "QA-7189-1201",
+            "departureDate": "2026-12-01",
+            "endDate": "2026-12-03",
+            "enrollmentDeadline": "2026-11-30",
+            "maxRooms": 4,
+            "remainRooms": 4,
+            "maxParticipants": 6,
+            "remainSlots": 6,
+            "batchStatus": "ENROLLING",
+            "batchStatusLabel": "报�中",
+            "tierPrices": [
+              { "tierSeq": 1, "tierName": "轻奢", "adultPrice": "1000.00", "childPrice": "600.00" }
+            ]
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+#### 空数� / �级�应
+
+�团期产�的 `batches` 是空数组而�是 `null`（测试环境实测）：
+
+```json
+{
+  "productId": "2049754271968047106",
+  "name": "的风格�多少",
+  "productType": "CORE",
+  "batches": []
+}
+```
+
+该产�全部�期都已返团或已�消时，`batches` �样是 `[]`，产�本身�出现在列表里。
+
+整页无匹�产�时：
+
+```json
+{ "code": 200, "msg": null, "data": { "total": 0, "records": [] } }
+```
+
+订�侧�期统计�务��用时，本接�**�失败**：该批�期按「无活跃订��计算，`remainRooms` / `remainSlots` �能�大（��显示为�订），�应结构与 `code` ��，�务端记 ERROR 日志。
+
+#### 错误�应
+
+未新增错误�，沿用既有：
+
+```json
+{
+  "code": 401,
+  "msg": "未登录或登录已过期",
+  "data": null
+}
+```
+
+```json
+{
+  "code": 403,
+  "msg": "无��访问该数�",
+  "data": null
+}
+```
+
+#### 业务边界
+
+- **鉴�**: 需登录；`@DataScope` 行级校验产�数���，越�返 403。
+- **�读**: 无任何写�作，�产生数��更，���调用。
+- **�期��性**: �返回「未�消 且 返团日未过（返团日为空视为未过）�的�期；已返团��消中�已�消�已软删的�期�出现。满员（`FULL`）的�期**�然返回**，由�端�显。
+- **期��径**: `batchLabel` 按该产�**全部未删�期**的出�日���置计算，���售过滤——所以它与数组下标�对应，与团期看�显示的期�一致。
+- **空值语义**: `remainRooms` / `remainSlots` 为 `null` 表示��，为 `0` 表示已满；`maxRooms` �� null，`0` 表示��。
+- **�级**: 订�侧统计��用时按无活跃订�计算并记 ERROR，� 500��阻断页�。
+- **兼容**: 11 个旧字段的�称�类型�顺�完全未�，�消费新字段的调用方无需改动。
+
+---
+
+## 四�契约约�与正确调用方�
+
+本接�是�读 GET，无请求体。约�体现在**怎么读�应**，下�是三�读法对照。
+
+### ✅ 正确 / � 错误 读法对照
+
+| 场景 | 读法 |
+|------|------|
+| ✅ 判断�期能�选中 | `["ENROLLING", "NEARLY_FULL"].includes(batch.batchStatus)` |
+| � 判断�期能�选中 | `batch.remainRooms > 0` → ��容�时 `remainRooms` 为 `null`，`null > 0` 为 `false`，会把��的�期误判���选 |
+| ✅ 显示剩余房数 | `batch.remainRooms ?? "��"` |
+| � 显示剩余房数 | `batch.remainRooms \|\| "��"` → `0`（已满）会被显示�「��� |
+| ✅ �期� | `batch.batchLabel` |
+| � �期� | `index + 1` → `batches` 已过滤掉已返团�期，下标与真实期�对�上 |
+| ✅ 回传�期 | `productBatchId: String(batch.batchId)` |
+| � 回传�期 | `productBatchId: Number(batch.batchId)` → 雪花 ID 超出 JS 安全整数范围，精度丢失 |
+
+### 哪些�期会出现在 `batches` 里
+
+�端已过滤，�返回「**未�消** 且 **返团日未过**（返团日为空视为未过）�的�期。已返团��消中�已�消�已软删的�期�会出现，**�端�需��过滤一次**。
+
+---
+
+## 五�数�库行为
+
+本接�为�读查询，**无任何写�作**，�产生数��更。
+
+---
+
+## 六�边界行为
+
+- 未登录 → 401（网关拦截）
+- 无该产�数��� → 403（`@DataScope` 行级校验）
+- 该产�无任何�售�期（全部已返团/已�消）→ `batches` 为 `[]`，产�本身�出现在列表里
+- � GROUP 产� → `batches` �为 `[]`，�是 `null`
+- �期未�置档� → `tierPrices` 返回一项 `tierSeq=1`�`tierName="默认档"` 的兜底档
+- 订�侧统计�务�级 → 该批�期按「无活跃订��计算，剩余数�能�大，接�� 500 �阻断页�（�务端记 ERROR 日志）
+- 本页�售�期总数超过 500 → �务端记 warn，**�截断**，�全�返回
+
+---
+
+## 六.5�枚举 / 数�字典
+
+### productType（com.hulalv.enums.ProductTypeEnum）
+
+**所属字段**: `records[].productType` ｜ **类型**: `String`
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `CORE` | 核心产� | `batches` �为 `[]` |
+| `GROUP` | �蒙马（�团期产�） | `batches` 为�售�期列表，创建订�必须选定其一 |
+| `CUSTOM` | �人定制 | `batches` �为 `[]` |
+
+（中文��自枚举定义本身，与��产�管�页的类型显示一致。）
+
+### batchStatus（com.hulalv.enums.BatchStatusEnum）
+
+**所属字段**: `records[].batches[].batchStatus` ｜ **类型**: `String`
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `ENROLLING` | 报�中 | **�选中下�**；会出现在 `batches` |
+| `NEARLY_FULL` | �将满� | **�选中下�**；会出现在 `batches` |
+| `FULL` | 已满� | ��选（�显）；�会出现在 `batches` |
+| `FINISHED` | 已结� | ��选；一般�会出现（返团日已过会被过滤） |
+| `CANCELLING` | �消中 | ��选；**�会出现**（�端已过滤） |
+| `CANCELLED` | 已�消 | ��选；**�会出现**（�端已过滤） |
+
+---
+
+## 六.6�修改��对比
+
+### 字段级对比
+
+| 字段 | 改� | 改� |
+|------|------|------|
+| `records[].productType` | �存在 | 新增，`CORE` / `GROUP` / `CUSTOM` |
+| `records[].batches` | �存在 | 新增，�售�期数组（� GROUP � `[]`） |
+| 其余 11 个字段 | 有 | **完全��**（�称�类型�顺���值�未动） |
+
+### 行为级对比
+
+| 行为 | 改� | 改� |
+|------|------|------|
+| 选�页拿�期 | 拿�到，需�外调接�或让��手填出�日 | 一次请求�产�带回 |
+| �期期� | 无 | `batchLabel`，与团期看�一致 |
+| 请求次数 | 1 次 | �是 1 次（�期用一次 `IN` 查询�回，��产�数增长） |
+
+---
+
+## 六.7�影�评估
+
+- **是�破���兼容**: �。11 个旧字段完全未动，�追加两个新字段。
+- **�端是�必须�步上线**: �（�上线则维�现状，选�页看�到�期）。但**团期订�必须选�期**这�业务�求���端�地，�八.5。
+- **�端 workaround 清�点**: 若�端此�为团期产��独请求过�期接�或让用户手填出�日，改用本接�的 `batches` ��撤除。
+
+---
+
+## 七��影�范围
+
+- **仅影�**: 管���「新建订� → 选择产��页调用的 `GET /admin/product/item/order-picker`
+- **零影�**:
+  - 订�创建接� `POST /v3/admin/order`（本次未改 order-v3 任何代�）
+  - 报价 `POST /admin/product/item/{id}/quote`�价格日历 `pricing-calendar`
+  - 团期看�全部读端点（`/v3/admin/order/group-batch` 系列）
+  - 产�侧�期管�接�（`/admin/product/item/{id}/schedule` 系列）
+  - �程� C 端全部接�
+  - 存�数�（��任何数��移，�期�的��空格�在输出时去除，�回写库）
+
+---
+
+## 八�测试环境已验�
+
+2026-09-07 测试环境（`api.test.1814.love`）网关实测 **15/15 通过**：
+
+```
+GET /admin/product/item/order-picker?lineId=2044248925572919297&page=1&pageSize=20  → 200 ✓
+  productType=GROUP，batches 14 个字段�全                                          ✓
+  �字段与 GET /admin/product/item/2044306857534636034/schedule/list �字段一致      ✓
+  6 个已返团�期被过滤，10-01 与 12-01 期在列，按 departureDate ��                 ✓
+  期� 10-01="7"�12-01="8"，与 /v3/admin/order/group-batch/board?scope=ALL �一相等 ✓
+  �期� " 没，那你" → "没，那你"（已去空格）                                        ✓
+  11 个旧字段一个�少                                                                ✓
+线下��: 容� 8 房 + �� 3 房 + 线上 0 � → remainRooms=5                          ✓
+��容�: maxRooms=0 → remainRooms=null, remainSlots=null, batchStatus=ENROLLING     ✓
+满员:     容� 1 房 + �� 1 房 → remainRooms=0, FULL, "已满�", 且�在 batches 里    ✓
+�消与软删的�期��出现在 batches                                                   ✓
+� GROUP 产� batches 为 [] 而� null                                                ✓
+```
+
+验�产�: `productId=2044306857534636034`（冻干粉�短信给，GROUP，8 期）�`productId=2049754271968047106`（的风格�多少，CORE）
+
+�元测试: `mvn -pl hl-product-service-v2 test` → `Tests run: 1574, Failures: 0, Errors: 0, Skipped: 0`
+
+---
+
+## 八.5��端�套（mmg 待办）
+
+1. **`Step1Sku.vue`**: `productType === "GROUP"` 的产��展开显示 `batches[]`，�行建议格�
+   `第{batchLabel}期 · {batchName} · {departureDate} 到 {endDate} · 剩 {remainRooms ?? "��"} 房 · {batchStatusLabel}`；
+   `batchStatus` �属于 `{ENROLLING, NEARLY_FULL}` 的�期�显��选。选中档�与�期� emit 带上 `productBatchId` 与 `batchDepartureDate`。
+2. **GROUP 未选�期��许进入第 3 步**。第 3 步的出�日直接�所选�期的 `departureDate`（��让用户手选日期），报价 `POST /admin/product/item/{id}/quote` 传 `batchId`。
+3. **创建订� payload**: `productBatchId = String(batch.batchId)`；� GROUP 产��传该字段。
+4. **深链**: 带 `?productBatchId=…` 进入时，在 `batches` 中预选该期；若该期�在列表里（已结�或已�消），给出�示而�是�默忽略。
+5. **金��显示�端报价结果**，`batches[].tierPrices` 仅用于展示�考价，��与�端算价。
+
+---
+
+## ��相关历� PR
+
+| PR | Issue | 说明 | 是��有效 |
+|----|-------|------|------------|
+| #7219 | #7189 | 团期看�以产�全�期为基底 + scope 筛选，`batchLabel` 期��径在此确立 | ✅ 有效 |
+| #7256 | #7245 | �期�去空格 + ��容� remain 统一 null + board 库存�� | ✅ 有效（本接�沿用�一�径） |
+| **本 PR #7259** | **#7244** | 选�接��出 `productType` 与 `batches` | ✅ 最新 |
+
+---
+
+## ��相关文档
+
+- 关� Issue: [wx/HL#7244](https://git.1814.love:8443/wx/HL/issues/7244)
+- 关� PR: [wx/HL#7259](https://git.1814.love:8443/wx/HL/pulls/7259)
+- 期��径��: `changelogs-v2/2026-09/07_7189_团期看�产�全�期基底与scope范围筛选-修改接�-管���.md`
+- 剩余库存�径��: `changelogs-v2/2026-09/07_7245_团期看��期�与��容��径修正-修改接�-管���.md`
+
+## 关� / �系人
+
+### 链接
+
+- **Issue**: [#7244](https://git.1814.love:8443/wx/HL/issues/7244)
+- **PR**: [#7259](https://git.1814.love:8443/wx/HL/pulls/7259)
+- **Merge commit**: [9800cddde](https://git.1814.love:8443/wx/HL/commit/9800cddde)
+
+### �系人
+
+- **�端负责人**: @wx
+- **�端负责人**: @mmg