APP 下载引导与订场二维码接口文档

约定

测试/生产网关前缀按环境配置；本文仅列服务路径。
所有业务响应使用 code=200 表示成功；code=600 表示登录 Token 已失效。
除标记“无需登录”外，均在请求头携带：Authorization: Bearer {token}。
二维码中保存的是 HTTPS 短链接，例如 https://{guide-domain}/q/Ab3X9k；App 不应从 URL 中自行解析业务 ID。

1. App 扫码解析

GET /api/qr/resolve?code={shortCode}

用于玩湃 App 的扫一扫。扫码得到链接后，取路径末段作为 shortCode，调用该接口，再按返回的 route 和参数跳转。

示例响应：

{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "type": "SITE_BOOKING",
    "storeId": 100,
    "siteId": 200,
    "bookingId": null,
    "route": "/pages/site/booking"
  }
}

type 可为：

SITE_BOOKING：跳转场地订场页，使用 storeId、siteId。
BOOKING_ENTRY：跳转“我的预约/进场码”页，使用 bookingId。进入页面后仍须调用订单详情接口校验订单状态。

二维码无效、停用或到期时，接口返回 code=500。

2. 获取个人订场进场二维码

GET /api/site/entryQr?bookingId={bookingId}

仅预约本人可调用。服务端会生成或复用在预约结束时间失效的 BOOKING_ENTRY 短码。

示例响应：

{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "shortCode": "Ab3X9k",
    "url": "https://online.daowepark.com/other/q/Ab3X9k",
    "expiresAt": "2026-09-05 22:00:00"
  }
}

App 将 url 生成二维码展示给用户。原有 POST /api/site/queryMySiteById 仍用于获取预约详情；不要再使用其中的明文 codeType/dataId 作为新二维码内容。

3. 兼容说明：外部 App 扫码下载引导

外部相机、微信或浏览器扫描 HTTPS 短链接时会打开 H5 下载页：GET /q/{shortCode}，H5 再调用以下接口取得页面内容。

GET /public/app-guide/config?code={shortCode}（无需登录）

响应的关键字段：

{
  "code": 200,
  "data": {
    "appName": "玩湃生活",
    "appScheme": "playpai",
    "androidPackage": "com.example.playpai",
    "iosStoreUrl": "https://apps.apple.com/...",
    "androidDefaultUrl": "https://...",
    "apkUrl": "https://...apk",
    "androidMarketUrls": {"huawei": "https://..."},
    "banners": [{"imageUrl": "https://...", "title": "..."}],
    "target": {"type": "SITE_BOOKING", "storeId": 100, "siteId": 200, "route": "/pages/site/booking"}
  }
}

App 侧必须注册 appScheme、Android App Links 与 iOS Universal Links。H5 对未成功拉起的情况才跳转应用市场或 APK；微信内 APK 下载可能受微信安全策略限制，应显示“在浏览器打开”的提示。

4. App 跳转要求

/pages/site/booking：接收 storeId、siteId，打开指定场地的订场页。
/pages/site/my-booking：接收 bookingId，打开订单详情/进场二维码页。
跳转前要校验参数存在；订单类页面必须重新调用现有详情接口，不信任二维码中的展示数据。