feat(h5): 新增收银台小程序引导页 /cm/:orderNo 并按UA分流钱包内提示

- 移动端/PC 端新增 cashier-mini 引导页(useMiniGuideEnv 支持 cashier scope, 仅展示微信) - cashier.json 补齐 10 语种 miniScan/miniInWallet 文案 - 路由注册 CASHIER_MINI(与 /am/ 引导页同构)
2026-08-07 13:55:44 +08:00 · 2026-07-31 19:19:05 +08:00
parent fb234182d3
commit 28d2f9dc4c
16 changed files with 364 additions and 19 deletions
--- a/src/mobile/router/modules.ts
+++ b/src/mobile/router/modules.ts
@@ -47,6 +47,15 @@ const routeModuleList: Array<RouteRecordRaw> = [
      },
    ],
  },
+  // 收银台小程序引导页（跨端：浏览器直接打开 /cm/:orderNo 时展示扫码提示，不发起支付）
+  {
+    path: RoutePath.CASHIER_MINI,
+    name: 'CashierMiniGuide',
+    component: () => import('@/mobile/views/cashier-mini/index.vue'),
+    meta: {
+      title: 'route.cashier', // 收银台
+    },
+  },
  // 聚合扫码：入口 + 非宿主提示 + 各宿主环境页 统一在 Aggregate 父级下作为子路由
  // 让 App.vue 顶层 transition key（matched[0].name）在 entry → 环境页跳转时保持不变（都是 Aggregate），
  // 避免整页 remount 与 Entry.vue 的 onBeforeMount router.replace 竞争导致白屏
--- a/src/mobile/views/cashier-mini/index.vue
+++ b/src/mobile/views/cashier-mini/index.vue
@@ -0,0 +1,127 @@
+<script lang="ts" setup>
+/**
+ * 统一收银台小程序引导页（/cm/:orderNo）
+ * 浏览器直接打开时展示扫码提示；微信普通链接二维码正常命中小程序时不会进入此页。
+ */
+import { useI18n } from 'vue-i18n'
+import { useRoute } from 'vue-router'
+import { closeWebview } from '@/shared/pay/close-webview'
+import { useMiniGuideEnv } from '@/shared/pay/use-mini-guide-env'
+
+defineOptions({ name: 'CashierMiniGuidePage' })
+
+const { t } = useI18n()
+const route = useRoute()
+// 订单号来自路由参数
+const orderNo = (route.params.orderNo as string) || ''
+// 收银台小程序引导文案
+const { icons, titleKey, descKey } = useMiniGuideEnv('cashier')
+</script>
+
+<template>
+  <div class="cashier-mini">
+    <!-- 品牌顶栏，与 H5 收银台保持一致 -->
+    <div class="cashier-mini__brand" />
+
+    <div class="cashier-mini__panel">
+      <!-- 钱包图标 -->
+      <div class="cashier-mini__wallets">
+        <img
+          v-for="item in icons"
+          :key="item.altKey"
+          class="cashier-mini__wallet-img"
+          :src="item.src"
+          :alt="t(item.altKey)"
+          width="40"
+          height="40"
+        >
+      </div>
+
+      <!-- 引导文案 -->
+      <h1 class="cashier-mini__title">
+        {{ t(titleKey) }}
+      </h1>
+      <p class="cashier-mini__desc">
+        {{ t(descKey) }}
+      </p>
+
+      <!-- 订单号弱展示 -->
+      <p v-if="orderNo" class="cashier-mini__order">
+        {{ t('cashier.orderNo') }} {{ orderNo }}
+      </p>
+
+      <!-- 关闭页面 -->
+      <van-button class="cashier-mini__close" round block type="primary" @click="closeWebview">
+        {{ t('cashier.closePage') }}
+      </van-button>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.cashier-mini {
+  min-height: 100%;
+  padding-bottom: 40px;
+  box-sizing: border-box;
+  background: var(--h5-bg-page);
+}
+
+.cashier-mini__brand {
+  height: 120px;
+  background: linear-gradient(135deg, var(--h5-brand-cashier), var(--h5-brand-cashier-deep));
+}
+
+.cashier-mini__panel {
+  margin: -48px 16px 0;
+  padding: 28px 20px 24px;
+  position: relative;
+  z-index: 1;
+  border-radius: 20px;
+  background: var(--h5-bg-card);
+  box-shadow: 0 8px 24px rgb(0 0 0 / 8%);
+  text-align: center;
+}
+
+.cashier-mini__wallets {
+  display: flex;
+  justify-content: center;
+  gap: 16px;
+}
+
+.cashier-mini__wallet-img {
+  display: block;
+  width: 40px;
+  height: 40px;
+}
+
+.cashier-mini__title {
+  margin: 24px 0 0;
+  color: var(--h5-text-primary);
+  font-size: 22px;
+  line-height: 1.4;
+  font-weight: 600;
+}
+
+.cashier-mini__desc {
+  margin: 12px 0 0;
+  color: var(--h5-text-secondary);
+  font-size: 14px;
+  line-height: 1.7;
+}
+
+.cashier-mini__order {
+  margin: 16px 0 0;
+  color: var(--h5-text-tertiary);
+  font-size: 12px;
+  line-height: 1.5;
+  word-break: break-all;
+}
+
+.cashier-mini__close {
+  margin-top: 20px;
+  --van-button-primary-background: var(--h5-brand-cashier);
+  --van-button-primary-border-color: var(--h5-brand-cashier);
+  color: #fff;
+  font-weight: 600;
+}
+</style>
--- a/src/pc/router/index.ts
+++ b/src/pc/router/index.ts
@@ -27,6 +27,13 @@ const routes: RouteRecordRaw[] = [
    component: () => import('@/pc/views/cashier/index.vue'),
    meta: { title: 'route.cashier' }, // 收银台
  },
+  // 收银台小程序引导页（跨端：浏览器直接打开 /cm/:orderNo 时展示扫码提示，不发起支付）
+  {
+    path: RoutePath.CASHIER_MINI,
+    name: 'PcCashierMini',
+    component: () => import('@/pc/views/cashier-mini/index.vue'),
+    meta: { title: 'route.cashier' }, // 收银台
+  },
  // 聚合「非宿主」提示：须在 /aggregate/:orderNo 之前注册，避免 path 段 "unsupported" 被当成 orderNo 查单
  {
    path: RoutePath.AGGREGATE_UNSUPPORTED,
--- a/src/pc/views/cashier-mini/index.vue
+++ b/src/pc/views/cashier-mini/index.vue
@@ -0,0 +1,150 @@
+<script lang="ts" setup>
+/**
+ * PC 统一收银台小程序引导页（/cm/:orderNo）
+ * PC 浏览器直接打开时展示扫码提示，不发起收银台支付。
+ */
+import { useI18n } from 'vue-i18n'
+import { useRoute } from 'vue-router'
+import { closeWebview } from '@/shared/pay/close-webview'
+import { useMiniGuideEnv } from '@/shared/pay/use-mini-guide-env'
+
+defineOptions({ name: 'PcCashierMiniGuidePage' })
+
+const { t } = useI18n()
+const route = useRoute()
+// 订单号来自路由参数
+const orderNo = (route.params.orderNo as string) || ''
+// 收银台小程序引导文案
+const { icons, titleKey, descKey } = useMiniGuideEnv('cashier')
+</script>
+
+<template>
+  <div class="cashier-mini">
+    <!-- 品牌顶栏 -->
+    <div class="cashier-mini__brand" />
+
+    <div class="cashier-mini__panel">
+      <!-- 钱包图标 -->
+      <div class="cashier-mini__wallets">
+        <img
+          v-for="item in icons"
+          :key="item.altKey"
+          class="cashier-mini__wallet-img"
+          :src="item.src"
+          :alt="t(item.altKey)"
+          width="40"
+          height="40"
+        >
+      </div>
+
+      <!-- 引导文案 -->
+      <h1 class="cashier-mini__title">
+        {{ t(titleKey) }}
+      </h1>
+      <p class="cashier-mini__desc">
+        {{ t(descKey) }}
+      </p>
+
+      <!-- 订单号弱展示 -->
+      <p v-if="orderNo" class="cashier-mini__order">
+        {{ t('cashier.orderNo') }} {{ orderNo }}
+      </p>
+
+      <!-- 关闭页面 -->
+      <button class="cashier-mini__close" type="button" @click="closeWebview">
+        {{ t('cashier.closePage') }}
+      </button>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.cashier-mini {
+  min-height: 100vh;
+  padding-bottom: 40px;
+  box-sizing: border-box;
+  background: var(--h5-bg-page);
+}
+
+.cashier-mini__brand {
+  height: 180px;
+  background: linear-gradient(135deg, var(--h5-brand-cashier), var(--h5-brand-cashier-deep));
+}
+
+.cashier-mini__panel {
+  width: min(520px, calc(100% - 48px));
+  margin: -72px auto 0;
+  padding: 40px 48px 36px;
+  position: relative;
+  z-index: 1;
+  box-sizing: border-box;
+  border-radius: 24px;
+  background: var(--h5-bg-card);
+  box-shadow: 0 12px 32px rgb(0 0 0 / 8%);
+  text-align: center;
+}
+
+.cashier-mini__wallets {
+  display: flex;
+  justify-content: center;
+  gap: 20px;
+}
+
+.cashier-mini__wallet-img {
+  display: block;
+  width: 40px;
+  height: 40px;
+}
+
+.cashier-mini__title {
+  margin: 28px 0 0;
+  color: var(--h5-text-primary);
+  font-size: 28px;
+  line-height: 1.4;
+  font-weight: 600;
+}
+
+.cashier-mini__desc {
+  margin: 16px 0 0;
+  color: var(--h5-text-secondary);
+  font-size: 16px;
+  line-height: 1.7;
+}
+
+.cashier-mini__order {
+  margin: 20px 0 0;
+  color: var(--h5-text-tertiary);
+  font-size: 13px;
+  line-height: 1.5;
+  word-break: break-all;
+}
+
+.cashier-mini__close {
+  width: 280px;
+  max-width: 100%;
+  height: 44px;
+  margin-top: 24px;
+  border: none;
+  border-radius: 22px;
+  background: linear-gradient(135deg, var(--h5-brand-cashier), var(--h5-brand-cashier-deep));
+  color: #fff;
+  font-size: 15px;
+  font-weight: 600;
+  cursor: pointer;
+}
+
+.cashier-mini__close:hover {
+  opacity: 0.9;
+}
+
+@media (max-width: 640px) {
+  .cashier-mini__panel {
+    width: calc(100% - 32px);
+    padding: 32px 24px 28px;
+  }
+
+  .cashier-mini__title {
+    font-size: 24px;
+  }
+}
+</style>
--- a/src/shared/locales/en-US/cashier.json
+++ b/src/shared/locales/en-US/cashier.json
@@ -41,5 +41,9 @@
  "paidTip": "Payment completed. Thank you",
  "autoRedirectTip": "Auto-return to merchant in {n}s",
  "backToMerchant": "Return to merchant",
-  "payTime": "Payment time"
+  "payTime": "Payment time",
+  "miniScanTitle": "Scan to open the cashier mini-program",
+  "miniScanDesc": "Scan the QR code with WeChat to open the cashier and complete payment",
+  "miniInWalletTitle": "Cashier mini-program unavailable",
+  "miniInWalletDesc": "Please confirm the cashier mini-program is published and its normal-link QR rule is configured"
 }
--- a/src/shared/locales/id-ID/cashier.json
+++ b/src/shared/locales/id-ID/cashier.json
@@ -41,5 +41,9 @@
  "paidTip": "Pembayaran selesai. Terima kasih",
  "autoRedirectTip": "Kembali ke merchant otomatis dalam {n} detik",
  "backToMerchant": "Kembali ke merchant",
-  "payTime": "Waktu pembayaran"
+  "payTime": "Waktu pembayaran",
+  "miniScanTitle": "Pindai untuk membuka mini-program kasir",
+  "miniScanDesc": "Pindai kode QR dengan WeChat untuk membuka kasir dan menyelesaikan pembayaran",
+  "miniInWalletTitle": "Mini-program kasir tidak tersedia",
+  "miniInWalletDesc": "Pastikan mini-program kasir telah diterbitkan dan aturan QR tautan biasa telah dikonfigurasi"
 }
--- a/src/shared/locales/ja-JP/cashier.json
+++ b/src/shared/locales/ja-JP/cashier.json
@@ -41,5 +41,9 @@
  "paidTip": "支払いが完了しました。ありがとうございます",
  "autoRedirectTip": "{n} 秒後に自動的に店舗に戻ります",
  "backToMerchant": "店舗に戻る",
-  "payTime": "支払い日時"
+  "payTime": "支払い日時",
+  "miniScanTitle": "スキャンして決済ミニプログラムを開く",
+  "miniScanDesc": "WeChatでQRコードをスキャンして決済ミニプログラムを開き、支払いを完了してください",
+  "miniInWalletTitle": "決済ミニプログラムは現在利用できません",
+  "miniInWalletDesc": "決済ミニプログラムが公開され、通常リンクQRコードが設定されていることを確認してください"
 }
--- a/src/shared/locales/ko-KR/cashier.json
+++ b/src/shared/locales/ko-KR/cashier.json
@@ -41,5 +41,9 @@
  "paidTip": "결제가 완료되었습니다. 감사합니다",
  "autoRedirectTip": "{n}초 후 자동으로 가맹점으로 돌아갑니다",
  "backToMerchant": "가맹점으로 돌아가기",
-  "payTime": "결제 시간"
+  "payTime": "결제 시간",
+  "miniScanTitle": "스캔하여 결제 미니프로그램 열기",
+  "miniScanDesc": "WeChat으로 QR 코드를 스캔하여 결제 미니프로그램을 열고 결제를 완료하세요",
+  "miniInWalletTitle": "결제 미니프로그램을 사용할 수 없습니다",
+  "miniInWalletDesc": "결제 미니프로그램이 게시되고 일반 링크 QR 규칙이 설정되었는지 확인하세요"
 }
--- a/src/shared/locales/ms-MY/cashier.json
+++ b/src/shared/locales/ms-MY/cashier.json
@@ -41,5 +41,9 @@
  "paidTip": "Pembayaran selesai. Terima kasih",
  "autoRedirectTip": "Kembali ke merchant automatik dalam {n} saat",
  "backToMerchant": "Kembali ke merchant",
-  "payTime": "Masa pembayaran"
+  "payTime": "Masa pembayaran",
+  "miniScanTitle": "Imbas untuk membuka mini-program kaunter",
+  "miniScanDesc": "Sila imbas kod QR dengan WeChat untuk membuka kaunter dan melengkapkan bayaran",
+  "miniInWalletTitle": "Mini-program kaunter tidak tersedia",
+  "miniInWalletDesc": "Sahkan mini-program kaunter telah diterbitkan dan peraturan QR pautan biasa telah dikonfigurasi"
 }
--- a/src/shared/locales/th-TH/cashier.json
+++ b/src/shared/locales/th-TH/cashier.json
@@ -41,5 +41,9 @@
  "paidTip": "ชำระเงินสำเร็จ ขอบคุณที่ใช้บริการ",
  "autoRedirectTip": "กลับสู่ร้านค้าอัตโนมัติใน {n} วินาที",
  "backToMerchant": "กลับสู่ร้านค้า",
-  "payTime": "เวลาที่ชำระ"
+  "payTime": "เวลาที่ชำระ",
+  "miniScanTitle": "สแกนเพื่อเปิดมินิโปรแกรมแคชเชียร์",
+  "miniScanDesc": "โปรดสแกนคิวอาร์โค้ดด้วย WeChat เพื่อเปิดแคชเชียร์และชำระเงินให้เสร็จสิ้น",
+  "miniInWalletTitle": "มินิโปรแกรมแคชเชียร์ไม่พร้อมใช้งาน",
+  "miniInWalletDesc": "โปรดยืนยันว่ามินิโปรแกรมแคชเชียร์เผยแพร่แล้วและตั้งค่ากฎ QR ลิงก์ปกติแล้ว"
 }
--- a/src/shared/locales/vi-VN/cashier.json
+++ b/src/shared/locales/vi-VN/cashier.json
@@ -41,5 +41,9 @@
  "paidTip": "Thanh toán hoàn tất. Cảm ơn bạn",
  "autoRedirectTip": "Tự động quay lại merchant sau {n} giây",
  "backToMerchant": "Quay lại merchant",
-  "payTime": "Thời gian thanh toán"
+  "payTime": "Thời gian thanh toán",
+  "miniScanTitle": "Quét để mở mini-program thu ngân",
+  "miniScanDesc": "Vui lòng quét mã QR bằng WeChat để mở thu ngân và hoàn tất thanh toán",
+  "miniInWalletTitle": "Mini-program thu ngân không khả dụng",
+  "miniInWalletDesc": "Vui lòng xác nhận mini-program thu ngân đã được phát hành và đã cấu hình quy tắc QR liên kết thường"
 }
--- a/src/shared/locales/zh-CN/cashier.json
+++ b/src/shared/locales/zh-CN/cashier.json
@@ -41,5 +41,9 @@
  "paidTip": "支付已完成,感谢使用",
  "autoRedirectTip": "{n} 秒后自动返回商户",
  "backToMerchant": "返回商户",
-  "payTime": "支付时间"
+  "payTime": "支付时间",
+  "miniScanTitle": "请扫码打开收银台小程序",
+  "miniScanDesc": "请使用微信扫描二维码进入统一收银台并完成支付",
+  "miniInWalletTitle": "收银台小程序暂不可用",
+  "miniInWalletDesc": "请确认收银台小程序已发布并配置普通链接二维码规则"
 }
--- a/src/shared/locales/zh-HK/cashier.json
+++ b/src/shared/locales/zh-HK/cashier.json
@@ -41,5 +41,9 @@
  "paidTip": "支付已完成,感謝使用",
  "autoRedirectTip": "{n} 秒後自動返回商戶",
  "backToMerchant": "返回商戶",
-  "payTime": "支付時間"
+  "payTime": "支付時間",
+  "miniScanTitle": "請掃碼開啟收銀台小程式",
+  "miniScanDesc": "請使用微信掃描二維碼進入統一收銀台並完成付款",
+  "miniInWalletTitle": "收銀台小程式暫不可用",
+  "miniInWalletDesc": "請確認收銀台小程式已發布並已設定普通連結二維碼規則"
 }
--- a/src/shared/locales/zh-TW/cashier.json
+++ b/src/shared/locales/zh-TW/cashier.json
@@ -41,5 +41,9 @@
  "paidTip": "支付已完成,感謝使用",
  "autoRedirectTip": "{n} 秒後自動返回商戶",
  "backToMerchant": "返回商戶",
-  "payTime": "支付時間"
+  "payTime": "支付時間",
+  "miniScanTitle": "請掃碼開啟收銀台小程式",
+  "miniScanDesc": "請使用微信掃描二維碼進入統一收銀台並完成付款",
+  "miniInWalletTitle": "收銀台小程式暫不可用",
+  "miniInWalletDesc": "請確認收銀台小程式已發布並已配置普通連結二維碼規則"
 }
--- a/src/shared/pay/use-mini-guide-env.ts
+++ b/src/shared/pay/use-mini-guide-env.ts
@@ -1,11 +1,11 @@
 /**
- * 小程序入口引导页(/m/:code、/am/:orderNo)的 UA 感知文案与图标
+ * 小程序入口引导页(/m/:code、/am/:orderNo、/cm/:orderNo)的 UA 感知文案与图标
 *
 * 钱包 App 内(微信/支付宝/云闪付/抖音)扫码本应由「普通链接二维码」规则拉起
 * cashier 小程序;若规则未配/未匹配/小程序未发布,会落到本 H5 引导页。此时再显示
 * "请用微信扫码"会自相矛盾(用户就在微信里),故按 UA 分流:
 * - 钱包内:展示"收款小程序暂不可用"提示,并仅高亮当前钱包图标(聚焦)
- * - 系统浏览器/PC:保持"请扫码支付"提示 + 四钱包图标
+ * - 系统浏览器/PC:保持"请扫码支付"提示 + 钱包图标(收银台小程序仅微信)
 *
 * UA 一次扫描即定(同一会话不变),无需响应式。
 */
@@ -37,7 +37,7 @@ const ENV_ICON_MAP: Record<AggregateClientEnv, MiniGuideWalletIcon> = {
 export interface MiniGuideEnv {
  /** 是否在钱包 App 内(微信/支付宝/云闪付/抖音) */
  inWallet: boolean
-  /** 图标列表:钱包内仅当前钱包(高亮聚焦);系统浏览器为四钱包 */
+  /** 图标列表:钱包内仅当前钱包(高亮聚焦);收银台小程序仅展示微信 */
  icons: MiniGuideWalletIcon[]
  /** 标题 i18n key */
  titleKey: string
@@ -45,21 +45,27 @@ export interface MiniGuideEnv {
  descKey: string
 }

+/** 小程序映射入口所属业务 */
+export type MiniGuideScope = 'aggregate' | 'cashier'
+
 /**
 * 探测当前 UA,返回引导页所需的文案 key 与图标列表
 */
-export function useMiniGuideEnv(): MiniGuideEnv {
+export function useMiniGuideEnv(scope: MiniGuideScope = 'aggregate'): MiniGuideEnv {
  const env = detectClientEnv()
  const inWallet = isAggregateClientEnv(env)
  // inWallet 为 true 时,env 已收窄为 AggregateClientEnv(type guard)
-  const icons = inWallet
-    ? [ENV_ICON_MAP[env]]
-    : AGGREGATE_CLIENT_ENVS.map(e => ENV_ICON_MAP[e])
+  const icons = scope === 'cashier'
+    ? [ENV_ICON_MAP.wechat]
+    : inWallet
+      ? [ENV_ICON_MAP[env]]
+      : AGGREGATE_CLIENT_ENVS.map(e => ENV_ICON_MAP[e])
+  const messagePrefix = scope === 'cashier' ? 'cashier' : 'aggregate'
  return {
    inWallet,
    icons,
    // 钱包内:小程序未拉起专属文案;否则:通用扫码文案
-    titleKey: inWallet ? 'aggregate.miniInWalletTitle' : 'aggregate.miniScanTitle',
-    descKey: inWallet ? 'aggregate.miniInWalletDesc' : 'aggregate.miniScanDesc',
+    titleKey: inWallet ? `${messagePrefix}.miniInWalletTitle` : `${messagePrefix}.miniScanTitle`,
+    descKey: inWallet ? `${messagePrefix}.miniInWalletDesc` : `${messagePrefix}.miniScanDesc`,
  }
 }
--- a/src/shared/router/paths.ts
+++ b/src/shared/router/paths.ts
@@ -26,6 +26,12 @@ export const RoutePath = {
   * 与运营端 H5 配置分桶一一对应；OAuth returnPath 指向此路径
   */
  CASHIER_ENV: '/cashier/:orderNo/:clientEnv',
+  /**
+   * 收银台小程序入口（跨端；cashier 预下单返回的 miniUrl 契约）
+   * 微信/支付宝扫码后由「普通链接二维码」规则拉起收银台小程序;
+   * 浏览器直接打开时展示扫码引导提示（不发起支付）
+   */
+  CASHIER_MINI: '/cm/:orderNo',
  /**
   * 聚合扫码入口（跨端；预下单落地 URL 契约，不可改）
   * Mobile：UA 探测后 replace 到环境页；PC：单页处理