From 89a08e4e508ae137aa5452ae83cb70140a473606 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Sun, 23 Aug 2026 13:35:27 +0000 Subject: [PATCH] =?UTF-8?q?changelog(mp):=20AI=E6=8E=A8=E8=8D=90=E4=BA=A7?= =?UTF-8?q?=E5=93=81=E5=A4=9A=E7=BB=B4=E7=AD=9B=E9=80=89=E5=BC=80=E6=94=BE?= =?UTF-8?q?=E6=8E=A5=E5=8F=A3=20(#6207)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增 GET /mp/product/ai-recommend 免登录开放接口，供 AI 推荐 调用。支持多维筛选（关键词/目的地/天数/季节/标签/报价/出发 日期/人数/资源类型等），排除私人定制 CUSTOM。 Co-Authored-By: Claude --- ...荐产品多维筛选开放接口-新增接口-小程序端.md | 234 ++++++++++++++++++ 1 file changed, 234 insertions(+) create mode 100644 changelogs-v2-mp/2026-08/23_6207_AI推荐产品多维筛选开放接口-新增接口-小程序端.md diff --git a/changelogs-v2-mp/2026-08/23_6207_AI推荐产品多维筛选开放接口-新增接口-小程序端.md b/changelogs-v2-mp/2026-08/23_6207_AI推荐产品多维筛选开放接口-新增接口-小程序端.md new file mode 100644 index 00000000..4a661e13 --- /dev/null +++ b/changelogs-v2-mp/2026-08/23_6207_AI推荐产品多维筛选开放接口-新增接口-小程序端.md @@ -0,0 +1,234 @@ +--- +schema: "hl-changelog/v2" +ticket: "6207" +title: "AI 推荐产品多维筛选开放接口（免登录，排除私人定制）" +consumer: "mp" +author: "wx(GIT)" +change_type: "新增接口" +backend_status: "deployed" +gateway_status: "verified" +frontend_status: "pending" +frontend_owner: "mmg" +frontend_ref: "" +target_release: "" +verified_at: "2026-08-23" +status_note: "GET /mp/product/ai-recommend 免登录开放接口，AI 推荐用。默认返回 PUBLISHED + CORE/GROUP（排除 CUSTOM 私人定制），支持多维筛选。后端/网关已测试服验证，前端待消费。" +updated_at: "2026-08-23" +base: "dev-v3" +--- + +# 【新增接口·小程序端】AI 推荐产品多维筛选开放接口（#6207） + +> **PR**: #6220 | **服务**: hl-mp-service / hl-product-service-v2 / hl-gateway | **作者**: wx | **更新时间**: 2026-08-23 + +> 免登录开放接口，供 AI 做产品推荐调用。**除私人定制(CUSTOM)以外的全部已上架(PUBLISHED)产品**，多维筛选，全部条件可选可组合。 + +--- + +## 一、背景 + +AI 做产品推荐需要一个查询接口：能筛选除私人定制以外的全部已上架产品，条件越多越好（目的地、天数、报价范围、团期、包含资源、人数、季节等），**不需要登录**。 + +--- + +## 二、变更接口清单 + +| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | +|---|------|------|------|----------|------| +| 1 | AI推荐产品查询 | GET | `/mp/product/ai-recommend` | 🆕 新增 | 免登录，多维筛选，分页 | + +> 网关白名单已放行（`JwtAuthFilter` SKIP_URLS），无 token 可直接调用。 + +--- + +## 三、接口详情 + +### 1. AI推荐产品查询 `GET /mp/product/ai-recommend` + +BFF 透传至 product-service `GET /internal/mp/product/ai-query`。pageSize 最大 50。 + +**数据范围（硬性）**： +- `product.status = PUBLISHED`（已上架） +- `product_type IN (CORE, GROUP)`（**排除 CUSTOM 私人定制**） + +#### 入参（全部可选，可任意组合） + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| keyword | Query | String | 否 | ≤100 字符 | 关键词/目的地（匹配产品名/副标题） | +| productType | Query | String | 否 | CORE/GROUP | 产品类型（默认 CORE+GROUP，传单一值可收窄） | +| category | Query | String | 否 | family/honeymoon/photography/experience/driving | 产品分类 | +| lineId | Query | Long | 否 | - | 产品线ID | +| minDays | Query | Integer | 否 | ≥1 | 最短天数 | +| maxDays | Query | Integer | 否 | ≥1 | 最长天数 | +| seasons | Query | String | 否 | spring/summer/autumn/winter，逗号分隔多值 | 季节 | +| tags | Query | String | 否 | 逗号分隔多值 | 产品标签 | +| minPrice | Query | BigDecimal | 否 | - | 最低起步价 | +| maxPrice | Query | BigDecimal | 否 | - | 最高起步价 | +| startDate | Query | String | 否 | yyyy-MM-dd | 出发日期起始 | +| endDate | Query | String | 否 | yyyy-MM-dd | 出发日期结束 | +| partySize | Query | Integer | 否 | ≥1 | 人数（仅与 startDate+endDate 组合时生效，过滤「订不下」的产品） | +| resourceType | Query | String | 否 | SCENIC/ACTIVITY/RESTAURANT/SERVICE/CUSTOM | 包含资源类型 | +| resourceKeyword | Query | String | 否 | - | 包含资源关键词 | +| orderBy | Query | String | 否 | sort/price_asc/price_desc/newest | 排序 | +| page | Query | Integer | 否 | 默认1，≥1 | 页码 | +| pageSize | Query | Integer | 否 | 默认10，1~50 | 每页条数（**最大 50**，>50 返 400） | + +> **seasons/tags 传法**：逗号分隔多值，如 `seasons=summer,winter`、`tags=亲子,摄影`。 + +#### 出参 `Result>` + +| 字段 | 类型 | 说明 | +|------|------|------| +| records[].productId | String | 产品ID（雪花，字符串防精度丢失） | +| records[].productNo | String | 产品编号 | +| records[].productType | String | CORE/GROUP | +| records[].name | String | 产品名称 | +| records[].subtitle | String | 副标题 | +| records[].introduction | String | 产品简介 | +| records[].category | String | 产品分类 | +| records[].tripDays / tripNights | Integer | 天数 / 晚数 | +| records[].coverImageUrl | String | 封面图 | +| records[].carouselImages | String[] | 轮播图 | +| records[].tags / seasons | String[] | 标签 / 季节 | +| records[].lineId | String | 产品线ID | +| records[].lineName | String | 产品线名称 | +| records[].startPrice | String | 起步价（字符串） | +| records[].startPriceLabel | String | `¥3980起/人` | +| records[].paymentType | String | FULL / DEPOSIT | +| records[].status | String | PUBLISHED | +| records[].sortOrder | Integer | 排序号 | +| records[].earliestBookingDate | String | 最早可订日期 yyyy-MM-dd | +| records[].availableDateSummary | String | 可订日期摘要（如 `2026-09-11 起`） | +| records[].availabilitySummary | String | 余位摘要（GROUP: `8个班期可报名，余位充足（2026-09-11 ~ 2026-10-30）`；CORE: `9天可订（2026-08-23 ~ 2026-08-31）`） | +| records[].matchedDestinations | String[] | 匹配到的目的地/途经点摘要 | +| total | Integer | 总条数 | +| page / pageSize | Integer | 页码 / 每页条数 | + +#### 请求示例 + +``` +GET /mp/product/ai-recommend?productType=GROUP&seasons=summer&minPrice=0&maxPrice=20000&page=1&pageSize=5 +``` + +#### 响应示例（测试服实测） + +```json +{ + "code": 200, + "message": "成功", + "data": { + "records": [ + { + "productId": "2056947670512971778", + "productNo": "G260423004", + "productType": "GROUP", + "name": "测试小蒙马-多档-固定金额", + "subtitle": "", + "introduction": "测试产品简介", + "category": "photography", + "tripDays": 5, + "tripNights": 4, + "coverImageUrl": "https://hlgl-test.oss-cn-beijing.aliyuncs.com/...", + "tags": ["小蒙马"], + "seasons": ["summer"], + "lineId": "2001", + "lineName": "测试产品线", + "startPrice": "8800.00", + "startPriceLabel": "¥8800起/人", + "paymentType": "FULL", + "status": "PUBLISHED", + "sortOrder": 0, + "earliestBookingDate": "2026-09-11", + "availableDateSummary": "2026-09-11 起", + "availabilitySummary": "8个班期可报名，余位充足（2026-09-11 ~ 2026-10-30）" + } + ], + "total": 5, + "page": 1, + "pageSize": 5 + }, + "success": true +} +``` + +#### 空数据响应（无匹配条件） + +```json +{ + "code": 200, + "message": "成功", + "data": { "records": [], "total": 0, "page": 1, "pageSize": 5 }, + "success": true +} +``` + +#### 错误响应（参数防御） + +```json +{ + "code": 400, + "message": "每页条数不能大于50", + "data": null, + "success": false +} +``` + +--- + +## 四、契约约束与正确调用方式 + +### 筛选语义（后端为准） + +- **所有条件 AND 组合**：同时传多个条件时，返回同时满足全部条件的产品。 +- **seasons / tags 多值取 OR**：`seasons=summer,winter` 表示「夏季 **或** 冬季」。 +- **报价范围按起步价过滤**：起步价 = GROUP 未来班期最低成人价 或 CORE 价格日历未来最低价，`minPrice/maxPrice` 作用于该值。 +- **人数（partySize）过滤语义**：**仅当同时传了出发日期范围（startDate/endDate 至少一个）+ partySize 才生效**——过滤「订不下」的产品： + - GROUP：看日期范围内是否有余位 ≥ partySize 的可报名班期（ENROLLING/NEARLY_FULL） + - CORE：看日期范围内是否有库存（dailyStock - sold）≥ partySize 的日期 + - **只传 partySize 不传日期 → 不触发人数过滤**。 +- **目的地关键词**：匹配产品名/副标题 **或** 途经点名称 **或** 行程节点名称（任一处命中即算）。 +- **日期倒置自动修正**：startDate 晚于 endDate 时后端自动交换，不报错。 + +### ✅ 正确 / ⚠️ 注意 + +| 场景 | 行为 | +|------|------| +| ✅ 无条件调用 | 返回全部在售（CORE+GROUP 且 PUBLISHED）分页 | +| ✅ `seasons=summer,winter` | 夏季或冬季的产品 | +| ✅ `minPrice=1000&maxPrice=5000` | 起步价在区间内的产品 | +| ✅ `startDate=2026-09-01&endDate=2026-10-01&partySize=2` | 该日期范围内能订下 2 人的产品 | +| ⚠️ `pageSize=999` | 400 拒绝（上限 50） | +| ⚠️ 只传 `partySize` 不传日期 | 人数条件不生效 | + +--- + +## 五、测试环境已验证（2026-08-23） + +``` +GET /mp/product/ai-recommend?page=1&pageSize=5 → 200 total=22 ✓ +GET /mp/product/ai-recommend?keyword=草原&page=1&pageSize=5 → 200 total=13 ✓ +GET /mp/product/ai-recommend?productType=GROUP&page=1&pageSize=3 → 200 total=6 ✓ +GET /mp/product/ai-recommend?category=family&page=1&pageSize=5 → 200 total=12 ✓ +GET /mp/product/ai-recommend?seasons=summer,winter&page=1&pageSize=5 → 200 total=19 ✓ +GET /mp/product/ai-recommend?minPrice=1000&maxPrice=5000&page=1&pageSize=3 → 200 ✓ +GET /mp/product/ai-recommend?orderBy=price_asc&page=1&pageSize=5 → 200 ✓（第一条约 2980 便宜档） +GET /mp/product/ai-recommend?productType=GROUP&seasons=summer&minPrice=0&maxPrice=20000 → 200 total=5 ✓ +GET /mp/product/ai-recommend?startDate=2026-08-24&endDate=2026-10-22 → 200 total=14 ✓ +GET /mp/product/ai-recommend?pageSize=999 → 400 每页条数不能大于50 ✓ +GET /mp/product/ai-recommend?category=driving&seasons=winter&keyword=不存在xyz → 200 empty ✓ +``` + +免登录（无 token）经网关调用全部返回 200。 + +--- + +## 六、相关历史 + +- 关联 Issue: [wx/HL#6207](https://git.1814.love:8443/wx/HL/issues/6207) +- 关联 PR: [wx/HL#6220](https://git.1814.love:8443/wx/HL/pulls/6220) + +### 联系人 + +- **后端负责人**: @wx +- **前端负责人**: @mmg \ No newline at end of file