> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rollinggo.store/llms.txt
> Use this file to discover all available pages before exploring further.

# RollingGo 酒店 MCP 升级指南-H5升级小程序多方案合集

# RollingGo 酒店 MCP 升级指南：H5 升级小程序 — 多方案合集

> **适用版本**：v2.5
> **更新日期**：2026-08-14
> **适用对象**：当前已接入 H5 方案（`bookingUrl`）的存量渠道/合作伙伴，计划升级为小程序落地形态。

***

## 1. 背景

存量渠道当前使用 H5 方案：`searchHotels` / `getHotelDetail` 返回 `bookingUrl`（H5 预订页 URL），用户在浏览器/H5 中完成预订。

v2.5 起支持按渠道配置**三种小程序落地形态**，按用户场景选择：H5 跳转小程序（`H5_TO_MINIAPP`）、APP 跳转小程序（`APP_TO_MINIAPP`）、小程序跳转小程序（`MINIAPP_TO_MINIAPP`）。本合集文档给出三种方式的完整对比、改造步骤与代码示例。

***

## 2. 形态总览与对比

| 对比项 | H5（存量） | 方案 A：H5\_TO\_MINIAPP | 方案 B：APP\_TO\_MINIAPP | 方案 C：MINIAPP\_TO\_MINIAPP |
| - | - | - | - | - |
| 适用场景 | 浏览器 / H5 | H5 页面跳转小程序 | 宿主 APP 拉起小程序 | 小程序内直接跳转 |
| 输出字段 | `bookingUrl` (string) | `miniProgramInfo` (`type`, `url`) | `miniProgramInfo` (`type`, `url`) | `miniProgramInfo` (`type`, `appId`, `path`, `query`) |
| 跳转方式 | 浏览器打开 H5 页面 | 微信内打开链接，自动拉起小程序 | iOS / Android 均直接拉起 | `wx.navigateToMiniProgram` 直跳 |
| 前置配合 | 无 | 无 | 无 | 前端实现跳转事件 |
| 改造工作量 | — | 低（仅替换字段） | 低（仅替换字段） | 中（前端实现跳转事件） |

***

## 3. 方案 A：H5\_TO\_MINIAPP（H5 跳转小程序）

### 3.1 适用场景

用户在浏览器 / H5 页面 / 网页中完成酒店浏览，预订时跳转到微信小程序内完成交易。适合 H5 分享页、公众号菜单、网页落地页等场景。

### 3.2 对接说明

* 接口返回微信加密链接（`https://wxmpurl.cn/*`），用户点击后在微信内自动拉起 RollingGo 预订小程序，无需手动搜索。
* 链接生成与维护由 RollingGo 负责，前端直接使用即可。

### 3.3 接口返回示例

```json theme={null}
{
  "success": true,
  "hotelId": 102906,
  "checkIn": "2026-08-12",
  "checkOut": "2026-08-13",
  "miniProgramInfo": {
    "type": "H5_TO_MINIAPP",
    "url": "https://wxmpurl.cn/abCDef123456"
  },
  "roomRatePlans": [ ... ],
  "message": "搜索成功"
}
```

### 3.4 改造步骤

1. 联系 RollingGo 将渠道落地形态配置为 `H5_TO_MINIAPP`。
2. 前端取值逻辑改为 `miniProgramInfo` 字段。
3. 将 `url` 作为普通链接/按钮暴露给用户；**必须由用户点击/触摸行为触发**，微信内自动拉起小程序。

### 3.5 代码示例

```javascript theme={null}
if (resp.miniProgramInfo && resp.miniProgramInfo.type === "H5_TO_MINIAPP") {
  const url = resp.miniProgramInfo.url;   // https://wxmpurl.cn/abCDef123456
  // H5 页面：直接作为链接
  // 立即预订
}
```

### 3.6 注意事项

* ⚠️ **web-view 限制**：小程序内的 web-view 无法通过 URL Link 跳转，该场景请改用方案 C（MINIAPP\_TO\_MINIAPP）。

***

## 4. 方案 B：APP\_TO\_MINIAPP（APP 跳转小程序）

### 4.1 适用场景

用户在宿主 APP（iOS / Android）内浏览酒店，预订时拉起微信小程序完成交易。适合旅游 APP、超级 APP 内置场景。

### 4.2 对接说明

* 接口返回微信 Scheme 链接（`weixin://dl/business/?...`），iOS / Android 均可直接拉起。

### 4.3 接口返回示例

```json theme={null}
{
  "success": true,
  "hotelId": 102906,
  "checkIn": "2026-08-12",
  "checkOut": "2026-08-13",
  "miniProgramInfo": {
    "type": "APP_TO_MINIAPP",
    "url": "weixin://dl/business/?appid=wx_SAMPLE_APP_ID&path=pages/hotel/detail/index&query=id%3D102906%26checkInDate%3D2026-08-12%26checkOutDate%3D2026-08-13%26roomCount%3D1%26adultCount%3D1%26childCount%3D0%26childAgeDetails%3D%26utm_source%3DfusionAI-2026"
  },
  "roomRatePlans": [ ... ],
  "message": "搜索成功"
}
```

### 4.4 改造步骤

1. 联系 RollingGo 将渠道落地形态配置为 `APP_TO_MINIAPP`（其余微信侧配置由 RollingGo 完成）。
2. 前端取值 `miniProgramInfo.url`。
3. 直接调用系统打开 scheme 即可拉起小程序。

### 4.5 代码示例

```javascript theme={null}
// 直接打开 scheme 拉起微信小程序
window.location.href = resp.miniProgramInfo.url;
```

### 4.6 注意事项

* 微信侧配置由 RollingGo 完成，如发现拉起异常请联系 RollingGo 排查。

***

## 5. 方案 C：MINIAPP\_TO\_MINIAPP（小程序跳转小程序）★ 推荐小程序场景

### 5.1 适用场景

用户在你的微信小程序内浏览酒店，预订时通过 `wx.navigateToMiniProgram` 直接拉起 RollingGo 预订小程序。**小程序内首选方案**（web-view 无法走 URL Link，必须用本方案）。

### 5.2 对接说明

* 接口返回结构化参数：`appId`（RollingGo 小程序 AppID）+ `path`（页面路径）+ `query`（参数串）。
* 由前端调用 `wx.navigateToMiniProgram` 发起跳转，拼接格式为 `path?query`。

### 5.3 接口返回示例

```json theme={null}
{
  "success": true,
  "hotelId": 102906,
  "checkIn": "2026-08-12",
  "checkOut": "2026-08-13",
  "miniProgramInfo": {
    "type": "MINIAPP_TO_MINIAPP",
    "appId": "wx_SAMPLE_APP_ID",
    "path": "pages/hotel/detail/index",
    "query": "id=102906&checkInDate=2026-08-12&checkOutDate=2026-08-13&roomCount=1&adultCount=1&childCount=0&childAgeDetails=&utm_source=fusionAI-2026"
  },
  "roomRatePlans": [ ... ],
  "message": "搜索成功"
}
```

### 5.4 改造步骤

1. 联系 RollingGo 将渠道落地形态配置为 `MINIAPP_TO_MINIAPP`。
2. 前端取值 `miniProgramInfo`，保存跳转参数。
3. 绑定用户点击事件，调用 `wx.navigateToMiniProgram`（**必须用户点击触发，禁止在接口回调中直接调用**）。
4. （可选）预订完成后回跳贵方小程序，在 `onShow` 中处理回跳参数。

### 5.5 代码示例

```javascript theme={null}
// 用户点击"立即预订"按钮
onBookingTap() {
  const { appId, path, query } = this.miniProgramInfo;
  wx.navigateToMiniProgram({
    appId,
    path: query ? `${path}?${query}` : path,
    extraData: {},
    success() { /* 跳转成功 */ },
    fail(err) { wx.showToast({ title: "拉起预订小程序失败，请重试", icon: "none" }); }
  });
}
```

### 5.6 注意事项

* `path` 为页面路径，动态参数全部在 `query`，请勿拆分或截断。
* 拉起失败时接口无自动兜底，需前端自行提示引导用户。
* 跳转前微信会弹窗确认，属平台行为。

***

## 6. 方案选择建议

```text theme={null}
[用户入口在哪里？]
   │
   ├─ 小程序内（web-view 或原生页）───────► 方案 C：MINIAPP_TO_MINIAPP（推荐）
   │
   ├─ 宿主 APP ─────────────────────────► 方案 B：APP_TO_MINIAPP（直接拉起）
   │
   └─ 浏览器 / H5 / 公众号网页 ──────────► 方案 A：H5_TO_MINIAPP（微信内自动拉起）
```

| 决策因素 | 推荐 |
| - | - |
| 入口在微信小程序内 | **方案 C**（web-view 场景唯一选择） |
| 入口在宿主 APP | **方案 B**（iOS / Android 均直接拉起） |
| 入口在浏览器/H5/公众号 | **方案 A**（唯一能在 H5 场景拉起小程序的形态） |
| 有多个入口 | 需与 RollingGo 确认当前支持的配置方式 |

***

## 7. 通用注意事项（三方案适用）

1. **互斥性**：升级后响应返回 `miniProgramInfo`，不再返回 `bookingUrl`；两字段绝不同时出现。
2. **参数完整性**：`id` / `checkInDate` / `checkOutDate` / `roomCount` / `adultCount` / `childCount` / `childAgeDetails` 全量透传，请勿手动改动参数内容。
3. **无自动兜底**：小程序拉起失败不回退 H5，由渠道端自行提示引导。
4. **入参无变化**：现有接口入参与调用方式保持不变，仅响应新增落地字段。

***

## 8. 验收清单

| # | 验收项 | 预期结果 |
| - | - | - |
| 1 | 配置生效 | 对应接口返回 `miniProgramInfo`，且 `type` 与配置形态一致 |
| 2 | 互斥校验 | 响应中无 `bookingUrl` 残留 |
| 3 | 参数完整 | `path` 为页面路径；`query` / `url` 含全部业务参数 |
| 4 | 跳转成功 | 对应端（微信 / iOS / Android / 小程序内）正确拉起 RollingGo 预订小程序 |
| 5 | 目标页落位 | 目标页展示对应酒店、日期、人数（无参数丢失） |

***

## 9. FAQ

**Q1：一个渠道可以同时使用多种方案吗？**
不可以。一个渠道同一时间只能配置一种落地形态，请根据主要用户入口选择最合适的方案。

**Q2：方案 B 如何拉起小程序？**
iOS / Android 均可通过返回的 Scheme 链接直接拉起微信小程序。

**Q3：方案 C 的 path 为什么不能带参？**
RollingGo 统一将落地参数拆分为 `path`（页面路径）+ `query`（参数串），`wx.navigateToMiniProgram` 拼接时用 `path?query` 格式。

**Q4：升级影响现有接口入参吗？**
不影响。现有接口入参与调用方式保持不变，仅响应新增落地字段。

**Q5：小程序拉起失败会回退 H5 吗？**
不会。拉起失败无自动兜底，由渠道端自行提示引导用户。

***

*文档版本：v2.5（H5 升级小程序多方案合集）*\
*更新日期：2026-08-14*


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.