@bi-nova/ui-weapp 2.0.0-beta.202610211621 → 2.0.0-beta.202610211744

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bi-nova/ui-weapp",
-  "version": "2.0.0-beta.202610211621",
+  "version": "2.0.0-beta.202610211744",
   "description": "BI Nova SDK WeChat Mini Program Components",
   "miniprogram": "src",
   "license": "ISC",
@@ -14,7 +14,7 @@
     "@bi-nova/core": "^1.0.1"
   },
   "devDependencies": {
-    "@bi-nova/core": "2.0.0-beta.202610211621"
+    "@bi-nova/core": "2.0.0-beta.202610211744"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",

package/src/alipay-touch/README.md

@@ -0,0 +1,152 @@
+# bi-alipay-touch 支付宝碰一碰组件（微信原生）
+
+支付宝碰一碰取号与插件卡片组件，基于 `ad-plugin/direct-card` 插件实现，取号统一走 `@bi-nova/services` 的 `nova.alipayTouch.resolvePhone`。
+
+- 仅支持微信小程序；组件通过 `plugin://ad-plugin/direct-card` 静态引用插件，宿主必须声明插件。
+- 取号可能消费后台号码：不缓存、不预取、不自动重试，同一身份只自动取号一次。
+
+## 宿主接入
+
+### 1. 声明插件与插件导出
+
+`app.json`：
+
+```json
+{
+  "plugins": {
+    "ad-plugin": {
+      "version": "2.1.2",
+      "provider": "wx7d4e2b019582003c",
+      "export": "exportToPlugin.js"
+    }
+  }
+}
+```
+
+小程序根目录（与 `pages` 同级）必须存在 `exportToPlugin.js`，否则插件无法正常运行：
+
+```js
+module.exports = {
+  wxMiniRequest() {
+    return wx.request
+  },
+}
+```
+
+### 2. 初始化 SDK
+
+```js
+const nova = createNova({ appId: 'your-app-id', autoEnv: true })
+
+nova.use(createServices({
+  env: 'prod',
+  getAuthToken: () => getToken(),
+  // external 模式：与京东保险外部对接一致，经开放网关签名直连
+  externalEnv: 'prod',
+  externalAppId: '由对接方提供的应用标识',
+  externalAppSecret: '由对接方提供的应用密钥',
+}))
+```
+
+### 3. 注册并使用组件
+
+页面 `index.json`：
+
+```json
+{
+  "usingComponents": {
+    "bi-alipay-touch": "@bi-nova/ui-weapp/alipay-touch/index"
+  }
+}
+```
+
+集团登录态模式：
+
+```xml
+<bi-alipay-touch
+  space-code="YOUR_SPACE_CODE"
+  mode="internal"
+  display-mode="offscreen"
+  bind:ready="onReady"
+  bind:unavailable="onUnavailable"
+  bind:success="onSuccess"
+  bind:error="onError"
+/>
+```
+
+第三方开放接口模式：
+
+```xml
+<bi-alipay-touch
+  space-code="YOUR_SPACE_CODE"
+  mode="external"
+  request-options="{{ alipayTouchOptions }}"
+  display-mode="inline"
+  bind:ready="onReady"
+  bind:error="onError"
+/>
+```
+
+```js
+Page({
+  data: {
+    alipayTouchOptions: {
+      thirdPlatform: 'your-platform',
+      thirdPlatformUserId: 'user-id',
+      openid: 'user-openid-in-this-weapp',
+    },
+  },
+})
+```
+
+## 属性
+
+| 属性 | 类型 / 默认 | 说明 |
+| --- | --- | --- |
+| spaceCode | String / `''` | 插件广告位/场景编码，必填；缺失时取号前直接报配置错误 |
+| mode | `'internal'` / `'external'` / 默认 `internal` | 取号通道。internal 使用集团登录态；external 走宿主后端代理的开放接口，不自动降级 |
+| requestOptions | Object / `null` | external 模式身份参数：`thirdPlatform`、`thirdPlatformUserId`、`openid` 必填，`phone` 可选；`appid` 可显式传入但必须与当前宿主一致，冲突直接报错。internal 模式不采纳其中的自报身份 |
+| displayMode | `'inline'` / `'offscreen'` / 默认 `offscreen` | `inline` 页面内正常文档流展示；`offscreen` 保持挂载但移出可见区域。切换只改布局，不重新取号 |
+| show | Boolean / `true` | 是否允许挂载插件。初始 `false` 不自动取号，首次变 `true` 才加载；已有有效结果时重新挂载不重复取号 |
+| autoLoad | Boolean / `true` | attached 后是否自动取号一次。异步登录场景可置 `false`，登录完成后通过实例方法 `load()` 手动取号 |
+| sdkKey | String / `'biNova'` | 全局 SDK 实例在 `app` / `app.globalData` 上的挂载键 |
+| contextKey | String / `''` | 宿主账户/登录周期标识，仅用于组件结果失效；账户切换时必须更新或销毁重建组件 |
+
+## 事件
+
+所有事件 `detail` 均携带公共上下文：`mode`、`appid`、`spaceCode`、`displayMode`、`contextKey`；事件与日志不输出手机号、openid、token。
+
+| 事件 | 时机 | 额外字段 |
+| --- | --- | --- |
+| ready | 本次有效取号数据齐全（canUse=true 且 openid/phone 完整），准备挂载插件；每个有效请求周期一次 | 无 |
+| unavailable | 成功取得 canUse=false 结果，非异常 | `reason: 'notAvailable'`；后台未返回原因时不伪造详细原因 |
+| success | 插件 onSuccessEvent 回调 | `stage: 'plugin'`、插件 `code`、`message`；不承诺支付或奖励发放成功 |
+| error | 配置、取号、响应或插件错误 | `stage: 'config' / 'resolve' / 'plugin'`、`code`、`message`；SDK 错误码与插件错误码分域 |
+
+错误阶段说明：
+
+- `stage='config'`：`ALIPAY_TOUCH_UNSUPPORTED_ENV`（非微信环境）、`ALIPAY_TOUCH_SPACE_CODE_MISSING`、`ALIPAY_TOUCH_MODE_INVALID`、`ALIPAY_TOUCH_APPID_MISSING`、`ALIPAY_TOUCH_APPID_MISMATCH`、`ALIPAY_TOUCH_REQUEST_OPTIONS_MISSING`、`ALIPAY_TOUCH_SDK_NOT_READY`（SDK 未挂载或未安装 services 插件）。
+- `stage='resolve'`：`code` 为 `@bi-nova/services` 的 `AlipayTouchErrorCode` 数值错误码，或组件侧 `ALIPAY_TOUCH_INVALID_RESPONSE` / `ALIPAY_TOUCH_RESOLVE_EXCEPTION`。
+- `stage='plugin'`：`code` 为插件错误码，已知 1001/1003/1004 仅有初始文案，未知码原样透传。
+
+## 实例方法
+
+```js
+const touch = this.selectComponent('#alipayTouch')
+const result = await touch.load()
+```
+
+`load(): Promise<{ code, message, data }>` 手动发起一次取号；同一身份并发调用复用当前 Promise。取号失败后宿主显式再次 `load()` 属于新的业务尝试，需接受后台限用结果。
+
+## 状态与生命周期约定
+
+- 组件状态：`idle → resolving → unavailable / ready / error`；插件自身 success/error 是事件阶段，不把 success 当发券或奖励已完成。
+- `mode`、有效请求身份或 `contextKey` 变更：隐藏插件、清理号码、旧请求序号失效，再按 `autoLoad`/`show` 决定是否加载新上下文。
+- `spaceCode` 变更只更新插件场景，已有有效取号结果可沿用，不单独消费新号码。
+- `onShow`、`setData`、`displayMode` 切换、React 重渲染（Taro 包装）都不会自动再次取号。
+- 超时/失效响应可能已被后台消费号码：前端丢弃旧响应不等于撤销后台分配，不回池、不补偿。
+- 同一业务位置只挂载一个实例，避免多个实例同时消费号码。
+
+## 埋点说明
+
+SDK 不内置 QT 及业务埋点。宿主如需兼容旧埋点，可将 `ready` 映射原"取号就绪"事件、`success` 映射插件成功事件、`error` 映射错误事件；`offscreen` 模式下 `ready` 不代表用户可见曝光。

package/src/alipay-touch/index.js

@@ -0,0 +1,419 @@
+/**
+ * @Description: 支付宝碰一碰取号组件（微信原生）
+ * @Author: wutao
+ * @Date: 2026-10-21
+ * @LastEditors: wutao
+ * @LastEditTime: 2026-10-21
+ */
+
+/** 组件状态：空闲 / 取号中 / 不可用 / 就绪 / 错误 */
+const STATUS = {
+  IDLE: 'idle',
+  RESOLVING: 'resolving',
+  UNAVAILABLE: 'unavailable',
+  READY: 'ready',
+  ERROR: 'error'
+}
+
+/** 插件错误码初始文案，实施联调时按当前插件文档核实 */
+const PLUGIN_ERROR_MESSAGES = {
+  1001: '入参校验不通过',
+  1003: '模版校验失败',
+  1004: '无广告/无券'
+}
+
+Component({
+  properties: {
+    /** 插件广告位/场景编码，由宿主提供 */
+    spaceCode: { type: String, value: '' },
+    /** 取号通道：internal 集团登录态 / external 第三方开放接口，不自动降级 */
+    mode: { type: String, value: 'internal' },
+    /** external 模式身份参数：thirdPlatform、thirdPlatformUserId、openid、可选 phone 与 appid */
+    requestOptions: { type: Object, value: null },
+    /** 展示方式：inline 页面内 / offscreen 屏幕外加载 */
+    displayMode: { type: String, value: 'offscreen' },
+    /** 是否允许挂载插件；初始 false 不自动取号，首次变 true 才加载 */
+    show: { type: Boolean, value: true },
+    /** attached 后是否自动取号一次；异步登录场景可置 false 后手动 load */
+    autoLoad: { type: Boolean, value: true },
+    /** 宿主全局 SDK 实例挂载键 */
+    sdkKey: { type: String, value: 'biNova' },
+    /** 宿主账户/登录周期标识，仅用于组件结果失效 */
+    contextKey: { type: String, value: '' }
+  },
+
+  data: {
+    status: STATUS.IDLE,
+    openId: '',
+    phone: ''
+  },
+
+  lifetimes: {
+    created() {
+      /** 请求序号：身份变更或销毁后递增，使晚到的异步结果失效 */
+      this.requestToken = 0
+      /** 当前进行中的取号 Promise，同一身份并发 load 复用 */
+      this.activeRequest = null
+      /** 当前进行中请求的身份键 */
+      this.activeRequestKey = ''
+      /** 最近一次自动加载覆盖的身份键，防止 observer 重复触发取号 */
+      this.lastAutoLoadKey = ''
+      /** 最近一次请求使用的身份参数快照 */
+      this.lastIdentitySnapshot = ''
+    },
+    attached() {
+      this.autoLoadIfNeeded('attached')
+    },
+    detached() {
+      this.requestToken = (this.requestToken || 0) + 1
+      this.activeRequest = null
+      this.activeRequestKey = ''
+      this.setData({ status: STATUS.IDLE, openId: '', phone: '' })
+    }
+  },
+
+  observers: {
+    spaceCode() {
+      // spaceCode 只影响插件场景，不单独消费新号码；补齐后允许首次加载。
+      this.autoLoadIfNeeded('spaceCode')
+    },
+    'mode, contextKey'() {
+      // 通道或登录周期变更视为身份变更：清理结果后按配置重新加载。
+      if (this.hasIdentityChanged()) {
+        this.clearResolvedState()
+        this.autoLoadIfNeeded('identity')
+      }
+    },
+    requestOptions() {
+      if (this.properties.mode !== 'external') return
+      if (this.hasIdentityChanged()) {
+        this.clearResolvedState()
+        this.autoLoadIfNeeded('requestOptions')
+      }
+    },
+    show(nextShow) {
+      // 已有有效结果时重新挂载即可，不重复取号。
+      if (!nextShow || this.data.status === STATUS.READY) return
+      this.autoLoadIfNeeded('show')
+    }
+  },
+
+  methods: {
+    /**
+     * 获取全局 SDK 实例
+     * @returns {Record<string, any> | null}
+     */
+    getSdkInstance() {
+      const app = typeof getApp === 'function' ? getApp() : null
+
+      if (!app) return null
+
+      const sdkKey = this.properties.sdkKey || 'biNova'
+      return app[sdkKey] || app.globalData && app.globalData[sdkKey] || null
+    },
+
+    /**
+     * 获取当前小程序 appId
+     * @returns {string}
+     */
+    getMiniProgramAppId() {
+      try {
+        if (typeof wx !== 'undefined' && typeof wx.getAccountInfoSync === 'function') {
+          const accountInfo = wx.getAccountInfoSync()
+          return accountInfo && accountInfo.miniProgram && accountInfo.miniProgram.appId || ''
+        }
+      } catch (error) {
+        return ''
+      }
+
+      return ''
+    },
+
+    /**
+     * 构建事件公共上下文
+     * @returns {Record<string, any>}
+     */
+    getEventContext() {
+      return {
+        mode: this.properties.mode,
+        appid: this.getMiniProgramAppId(),
+        spaceCode: this.properties.spaceCode || '',
+        displayMode: this.properties.displayMode,
+        contextKey: this.properties.contextKey || ''
+      }
+    },
+
+    /**
+     * 触发组件错误事件
+     * @param {'config' | 'resolve' | 'plugin'} stage 错误阶段
+     * @param {string | number} code 错误码，与插件错误码分域
+     * @param {string} message 错误消息
+     * @returns {void}
+     */
+    triggerComponentError(stage, code, message) {
+      this.triggerEvent('error', {
+        ...this.getEventContext(),
+        stage,
+        code,
+        message: message || '碰一碰组件错误'
+      })
+    },
+
+    /**
+     * 构建取号参数并完成取号前校验
+     * @returns {{ error: { code: string, message: string } } | { options: Record<string, any>, key: string }}
+     */
+    buildResolveOptions() {
+      if (typeof wx === 'undefined' || typeof wx.getAccountInfoSync !== 'function') {
+        return { error: { code: 'ALIPAY_TOUCH_UNSUPPORTED_ENV', message: '当前环境不支持碰一碰组件，仅支持微信小程序' } }
+      }
+
+      if (!this.properties.spaceCode) {
+        return { error: { code: 'ALIPAY_TOUCH_SPACE_CODE_MISSING', message: '缺少插件场景编码 spaceCode' } }
+      }
+
+      const mode = this.properties.mode
+      if (mode !== 'internal' && mode !== 'external') {
+        return { error: { code: 'ALIPAY_TOUCH_MODE_INVALID', message: `不支持的取号通道：${mode}，请使用 internal 或 external` } }
+      }
+
+      const currentAppId = this.getMiniProgramAppId()
+      if (!currentAppId) {
+        return { error: { code: 'ALIPAY_TOUCH_APPID_MISSING', message: '未能取得当前微信小程序 appId' } }
+      }
+
+      const requestOptions = this.properties.requestOptions && typeof this.properties.requestOptions === 'object'
+        ? this.properties.requestOptions
+        : {}
+      const declaredAppId = String(requestOptions.appid || '').trim()
+
+      if (mode === 'external') {
+        if (declaredAppId && declaredAppId !== currentAppId) {
+          return { error: { code: 'ALIPAY_TOUCH_APPID_MISMATCH', message: `requestOptions.appid(${declaredAppId}) 与当前宿主 appId(${currentAppId}) 不一致` } }
+        }
+
+        const thirdPlatform = String(requestOptions.thirdPlatform || '').trim()
+        const thirdPlatformUserId = String(requestOptions.thirdPlatformUserId || '').trim()
+        const openid = String(requestOptions.openid || '').trim()
+
+        if (!thirdPlatform || !thirdPlatformUserId || !openid) {
+          return { error: { code: 'ALIPAY_TOUCH_REQUEST_OPTIONS_MISSING', message: 'external 模式需要在 requestOptions 提供 thirdPlatform、thirdPlatformUserId、openid' } }
+        }
+
+        const options = {
+          mode: 'external',
+          thirdPlatform,
+          thirdPlatformUserId,
+          openid,
+          appid: currentAppId
+        }
+        const phone = String(requestOptions.phone || '').trim()
+
+        if (phone) {
+          options.phone = phone
+        }
+
+        return { options, key: this.buildRequestKey(options) }
+      }
+
+      const options = { mode: 'internal', appid: currentAppId }
+
+      return { options, key: this.buildRequestKey(options) }
+    },
+
+    /**
+     * 构建取号身份键（不含 spaceCode，spaceCode 变更不消费新号码）
+     * @param {Record<string, any>} options 取号参数
+     * @returns {string}
+     */
+    buildRequestKey(options) {
+      return [
+        this.properties.contextKey || '',
+        JSON.stringify(options)
+      ].join('__')
+    },
+
+    /**
+     * 判断有效请求身份是否发生变化
+     *
+     * 配置非法（如 spaceCode 缺失）时快照为空串，
+     * 与上一次有效身份不同同样视为变更，用于清理旧结果。
+     * @returns {boolean}
+     */
+    hasIdentityChanged() {
+      const built = this.buildResolveOptions()
+      const snapshot = 'error' in built ? '' : built.key
+
+      if (snapshot === this.lastIdentitySnapshot) return false
+
+      this.lastIdentitySnapshot = snapshot
+      return true
+    },
+
+    /**
+     * 清理取号结果，使旧响应失效
+     * @returns {void}
+     */
+    clearResolvedState() {
+      this.requestToken = (this.requestToken || 0) + 1
+      this.activeRequest = null
+      this.activeRequestKey = ''
+      this.setData({ status: STATUS.IDLE, openId: '', phone: '' })
+    },
+
+    /**
+     * 按配置触发自动取号
+     * @param {string} reason 触发原因
+     * @returns {void}
+     */
+    autoLoadIfNeeded(reason) {
+      if (!this.properties.autoLoad || !this.properties.show) return
+
+      const built = this.buildResolveOptions()
+
+      if ('error' in built) return
+
+      // 同一身份只自动加载一次，observer 重复触发、displayMode 切换不再取号。
+      if (this.lastAutoLoadKey === built.key) return
+      if (this.activeRequestKey === built.key) return
+      if (this.data.status === STATUS.READY && this.lastIdentitySnapshot === built.key) return
+
+      this.lastAutoLoadKey = built.key
+      this.load().catch(() => {})
+    },
+
+    /**
+     * 手动/自动取号入口
+     *
+     * 同一身份并发调用复用当前 Promise；身份变更后的旧响应不会写回本实例。
+     * @returns {Promise<{code: number | string, message: string, data: Record<string, any> | null}>}
+     */
+    async load() {
+      const built = this.buildResolveOptions()
+
+      if ('error' in built) {
+        this.setData({ status: STATUS.ERROR })
+        this.triggerComponentError('config', built.error.code, built.error.message)
+        return { code: built.error.code, message: built.error.message, data: null }
+      }
+
+      const sdk = this.getSdkInstance()
+
+      if (!sdk || !sdk.alipayTouch || typeof sdk.alipayTouch.resolvePhone !== 'function') {
+        const code = 'ALIPAY_TOUCH_SDK_NOT_READY'
+        const message = '未获取到可用的碰一碰服务，请先安装 services 插件并注入全局 nova 实例'
+        this.setData({ status: STATUS.ERROR })
+        this.triggerComponentError('config', code, message)
+        return { code, message, data: null }
+      }
+
+      if (this.activeRequest && this.activeRequestKey === built.key) {
+        return this.activeRequest
+      }
+
+      const requestToken = (this.requestToken || 0) + 1
+      this.requestToken = requestToken
+      this.lastIdentitySnapshot = built.key
+      this.activeRequestKey = built.key
+
+      this.setData({ status: STATUS.RESOLVING, openId: '', phone: '' })
+
+      this.activeRequest = (async () => {
+        try {
+          const result = await sdk.alipayTouch.resolvePhone(built.options)
+
+          if (requestToken !== this.requestToken) return result
+
+          return this.applyResolveResult(result)
+        } catch (error) {
+          if (requestToken !== this.requestToken) {
+            return { code: 'ALIPAY_TOUCH_STALE_RESPONSE', message: '取号结果已失效', data: null }
+          }
+
+          const message = error && error.message || '碰一碰取号异常'
+          this.setData({ status: STATUS.ERROR })
+          this.triggerComponentError('resolve', 'ALIPAY_TOUCH_RESOLVE_EXCEPTION', message)
+          return { code: 'ALIPAY_TOUCH_RESOLVE_EXCEPTION', message, data: null }
+        } finally {
+          if (requestToken === this.requestToken) {
+            this.activeRequest = null
+            this.activeRequestKey = ''
+          }
+        }
+      })()
+
+      return this.activeRequest
+    },
+
+    /**
+     * 应用取号结果并派发组件事件
+     * @param {{code: number, message: string, data: Record<string, any> | null}} result 服务结果
+     * @returns {{code: number, message: string, data: Record<string, any> | null}} 原样返回服务结果
+     */
+    applyResolveResult(result) {
+      if (!result || typeof result.code !== 'number' || result.code !== 0) {
+        this.setData({ status: STATUS.ERROR })
+        this.triggerComponentError('resolve', result && result.code, result && result.message || '碰一碰取号失败')
+        return result || { code: 'ALIPAY_TOUCH_RESOLVE_FAILED', message: '碰一碰取号失败', data: null }
+      }
+
+      const data = result.data || {}
+
+      if (data.canUse === true && data.openid && data.phone) {
+        this.setData({ status: STATUS.READY, openId: data.openid, phone: data.phone })
+        this.triggerEvent('ready', this.getEventContext())
+        return result
+      }
+
+      if (data.canUse === false) {
+        this.setData({ status: STATUS.UNAVAILABLE, openId: '', phone: '' })
+        this.triggerEvent('unavailable', { ...this.getEventContext(), reason: 'notAvailable' })
+        return result
+      }
+
+      // canUse 非法或字段不完整：数据不完整不挂载插件。
+      this.setData({ status: STATUS.ERROR })
+      this.triggerComponentError('resolve', 'ALIPAY_TOUCH_INVALID_RESPONSE', '取号响应数据不完整')
+      return result
+    },
+
+    /**
+     * 插件成功回调，只转发白名单字段
+     * @param {Record<string, any>} event 插件事件
+     * @returns {void}
+     */
+    onPluginSuccess(event) {
+      const detail = event && event.detail && typeof event.detail === 'object' ? event.detail : {}
+      const code = detail.code !== undefined ? detail.code : ''
+      const message = detail.message !== undefined ? detail.message : ''
+
+      this.triggerEvent('success', {
+        ...this.getEventContext(),
+        stage: 'plugin',
+        code,
+        message
+      })
+    },
+
+    /**
+     * 插件错误回调，未知码安全读取
+     * @param {Record<string, any>} event 插件事件
+     * @returns {void}
+     */
+    onPluginError(event) {
+      const detail = event && event.detail && typeof event.detail === 'object' ? event.detail : {}
+      const code = detail.code !== undefined ? detail.code : ''
+      const knownMessage = PLUGIN_ERROR_MESSAGES[detail.code]
+      const message = detail.message !== undefined && detail.message !== null && detail.message !== ''
+        ? String(detail.message)
+        : knownMessage || `插件未知错误: ${code || ''}`
+
+      this.triggerEvent('error', {
+        ...this.getEventContext(),
+        stage: 'plugin',
+        code,
+        message
+      })
+    }
+  }
+})

package/src/alipay-touch/index.json

@@ -0,0 +1,6 @@
+{
+  "component": true,
+  "usingComponents": {
+    "direct-card": "plugin://ad-plugin/direct-card"
+  }
+}

package/src/alipay-touch/index.wxml

@@ -0,0 +1,10 @@
+<view class="bi-alipay-touch {{displayMode === 'inline' ? 'bi-alipay-touch--inline' : 'bi-alipay-touch--offscreen'}}">
+  <direct-card
+    wx:if="{{status === 'ready' && show}}"
+    spaceCode="{{spaceCode}}"
+    openId="{{openId}}"
+    phone="{{phone}}"
+    bind:onSuccessEvent="onPluginSuccess"
+    bind:onErrorEvent="onPluginError"
+  />
+</view>

package/src/alipay-touch/index.wxss

@@ -0,0 +1,16 @@
+.bi-alipay-touch {
+  width: 100%;
+}
+
+/* 页面内展示：正常文档流，不侵入插件内部样式 */
+.bi-alipay-touch--inline {
+  position: relative;
+  width: 100%;
+}
+
+/* 屏幕外加载：保持插件挂载但移出可见区域，不能用 display:none 替代 */
+.bi-alipay-touch--offscreen {
+  position: absolute;
+  left: -3000rpx;
+  z-index: -999;
+}