@uxda/appkit 4.2.93 → 4.2.95

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uxda/appkit",
-  "version": "4.2.93",
+  "version": "4.2.95",
   "description": "小程序应用开发包",
   "main": "dist/index.js",
   "module": "dist/index.ts",
@@ -38,6 +38,7 @@
     "dayjs": "^1.11.18",
     "dsbridge": "^3.1.4",
     "lodash-es": "^4.17.21",
+    "pako": "^2.1.0",
     "validator": "^13.15.15",
     "vue": "^3.5.22"
   },

package/src/payment/api/endpoints.ts

@@ -35,6 +35,7 @@ const endpointsList: HttpEndpoints = {
       accountAuthFlag: params.accountAuthFlag || false,
       channelCode: params.channelCode || null,
       payFinishJumpUrl: params.payFinishJumpUrl || null,
+      clientInfo: params.clientInfo || null,
     }),
     transform: (data: any) => {
       let json = null

package/src/payment/components/RechargeView.vue

@@ -110,7 +110,8 @@ const onPayClick = () => {
       accountAuthFlag: false,
       channelCode: 'centergzh',
       payFinishJumpUrl: props.payFinishJumpUrl,
-      fromMini: !!params.from
+      fromMini: !!params.from,
+      clientInfo: 'H5'
     }).then(result => {
       console.log(result, '------requestBrandWCPay')
       state.buttonLoading = false

package/src/payment/types.ts

@@ -27,6 +27,7 @@ export type PaymentParams = {
   channelCode?: string
   payFinishJumpUrl?: string
   fromMini?: Boolean
+  clientInfo?: string
 }
 
 export type RechargeParams = Pick<PaymentParams, 'app' | 'tenant'>

package/src/shared/index.ts

@@ -2,6 +2,7 @@ export * from './weixin'
 export * from './components'
 export * from './composables'
 export * from './http'
+export * from './tracking'
 
 import jssdkServices from './weixin'
 

package/src/shared/tracking/README.md

@@ -0,0 +1,509 @@
+# 全埋点SDK使用指南
+
+## 概述
+
+这是一个精简版的全埋点SDK，支持自动埋点和手动埋点功能。已集成到项目中，开箱即用。
+
+## 数据结构
+
+埋点数据符合统一的 JSON 格式规范，包含以下核心字段：
+
+```typescript
+interface TrackingMainData {
+  log_id?: string // 日志ID (自动生成)
+  log_time: number // 日志时间戳 (毫秒)
+  log_type: LogType // 日志类型 (组合类型，如 "page/event/error/device/app")
+  tenant_id?: string // 租户ID
+  user_id?: string // 用户ID
+  source: SourceType // 来源 (app/H5/PC)
+  session_id: string // 会话ID
+  log_data: LogData // 日志数据
+}
+```
+
+### 日志数据子结构
+
+`log_data` 包含以下可选字段：
+
+```typescript
+interface LogData {
+  page?: PageData // 页面信息
+  event?: EventData // 事件信息
+  app?: AppData // 应用信息
+  device?: DeviceData // 设备信息
+  performance?: PerformanceData // 性能信息
+  error?: ErrorData // 错误信息
+}
+```
+
+#### 页面信息 (PageData)
+
+```typescript
+interface PageData {
+  page_name?: string // 页面名称
+  page_url?: string // 页面URL
+  page_referrer?: string // 页面来源
+  previous_page_name?: string // 上一页名称
+  page_start_time?: string // 页面开始时间 (ISO 8601格式)
+  page_duration?: number // 页面停留时长（毫秒）
+}
+```
+
+#### 事件信息 (EventData)
+
+```typescript
+interface EventData {
+  event_type?: string // 事件类型 (click/custom/page_view等)
+  event_name?: string // 事件名称
+  element_id?: string // 元素ID
+}
+```
+
+#### 应用信息 (AppData)
+
+```typescript
+interface AppData {
+  app_version?: string // 应用版本
+  package_name?: string // 包名
+  app_channel?: string // 应用渠道 (H5/WeChat/App Store)
+}
+```
+
+#### 设备信息 (DeviceData)
+
+```typescript
+interface DeviceData {
+  device_type?: string // 设备类型 (mobile/tablet/desktop)
+  os?: string // 操作系统
+  os_version?: string // 操作系统版本
+  brand?: string // 品牌
+  model?: string // 型号
+  network_type?: string // 网络类型 (wifi/2g/3g/4g/5g/none等)
+}
+```
+
+**网络类型说明**：SDK 会自动检测当前网络类型，可能的值包括：
+- `wifi` - WiFi 网络
+- `2g` - 2G 网络
+- `3g` - 3G 网络
+- `4g` - 4G 网络
+- `5g` - 5G 网络
+- `none` - 无网络连接
+- 其他平台特定值
+
+#### 性能信息 (PerformanceData)
+
+```typescript
+interface PerformanceData {
+  page_load_time?: number // 页面加载时间（毫秒）
+  response_time?: number // 响应时间（毫秒）
+  fps?: number // 帧率
+  memory_usage?: number // 内存使用率（%）
+  battery_usage?: number // 电池使用率（%）
+  network_latency?: number // 网络延迟（毫秒）
+  crash_rate?: number // 崩溃率（%）
+}
+```
+
+**性能数据说明**：
+- SDK 会在**页面访问 (PAGE_VIEW)** 时自动采集以下性能数据：
+  - `page_load_time`: 页面加载完成时间
+  - `response_time`: 页面响应时间
+  - `memory_usage`: 内存使用率
+- **跨平台支持**：
+  - H5 环境：使用浏览器原生 `window.performance` API
+  - 小程序环境：使用 `Taro.getPerformance()` API
+- 可以通过 `customData.businessData.performance` 手动传入额外的性能数据，会与自动采集的数据合并
+
+#### 错误信息 (ErrorData)
+
+```typescript
+interface ErrorData {
+  error_code?: string // 错误代码
+  error_message?: string // 错误消息
+  stack_trace?: string // 堆栈跟踪
+  error_level?: string // 错误级别 (info/warning/error)
+  error_context?: string // 错误上下文
+}
+```
+
+## 文件结构
+
+```
+utils/
+├── tracking/
+│   ├── tracking-sdk.ts          # 核心埋点SDK
+│   ├── tracking-init.ts         # 埋点初始化
+│   ├── useAutoTracking.ts       # 自动埋点组合式函数
+│   ├── directives/              # 埋点指令
+│   │   ├── index.ts            # 指令入口
+│   │   ├── track-click.ts      # 点击埋点指令
+│   │   ├── track-page.ts       # 页面访问埋点指令
+│   │   └── track-scroll.ts     # 滚动埋点指令
+│   └── examples/                # 使用示例
+│       ├── data-structure-example.ts  # 数据结构示例
+│       └── directive-tracking-example.vue  # 指令使用示例
+```
+
+## 核心功能
+
+### 1. 页面级自动埋点
+- 使用 `usePageTracking` 组合式函数
+- 自动记录页面访问和性能数据
+- 页面显示/隐藏时自动触发
+
+### 2. 手动埋点
+- 自定义事件埋点
+- 业务事件埋点
+- 页面访问埋点
+
+### 3. 埋点指令
+- 点击埋点指令 (v-track-click)
+- 页面访问埋点指令 (v-track-page)
+- 滚动埋点指令 (v-track-scroll)
+- 搜索埋点指令 (v-track-search)
+
+### 4. 状态管理
+- 埋点开关控制
+- 调试模式
+- 统计信息
+
+## 使用方法
+
+### 1. 基本使用
+
+所有埋点方法都是异步的，需要使用 `await` 关键字：
+
+```typescript
+import { trackClick, trackCustom, trackPageView } from '~/utils/tracking/tracking-sdk'
+
+// 点击事件埋点
+await trackClick('add_to_cart_btn', '加入购物车按钮')
+
+// 自定义事件埋点
+await trackCustom('purchase_complete', {
+  order_id: 'ORDER_123',
+  amount: 99.99,
+  currency: 'CNY',
+})
+
+// 页面访问埋点
+await trackPageView('商品详情页')
+```
+
+### 2. 页面级自动埋点
+
+```vue
+<template>
+  <view>
+    <!-- 页面内容 -->
+  </view>
+</template>
+
+<script setup lang="ts">
+import { usePageTracking } from '~/utils/tracking/useAutoTracking'
+
+// 启用页面级自动埋点
+const pageTracking = usePageTracking({
+  pageTitle: '页面标题',
+  customData: {
+    pageType: 'example'
+  }
+})
+</script>
+```
+
+### 3. 手动埋点
+
+```typescript
+import { trackingSDK, TrackingEventType } from '~/utils/tracking/tracking-sdk'
+
+// 自定义事件埋点
+await trackingSDK.trackCustom('button_click', {
+  buttonId: 'submit',
+  page: 'login'
+})
+
+// 业务事件埋点
+await trackingSDK.trackBusiness(TrackingEventType.CUSTOM, {
+  action: 'search',
+  keyword: 'example'
+})
+
+// 页面访问埋点
+await trackingSDK.trackPageView('首页')
+
+// 点击事件埋点
+await trackingSDK.trackClick('submit-btn', '提交按钮')
+```
+
+### 4. 组合式函数埋点
+
+```vue
+<script setup lang="ts">
+import { useAutoTracking } from '~/utils/tracking/useAutoTracking'
+
+const tracking = useAutoTracking({
+  trackPageView: true,
+  trackClicks: true,
+  trackStay: true
+})
+
+// 手动触发事件
+const handleClick = async () => {
+  await tracking.trackEvent('custom_click', {
+    buttonType: 'primary'
+  })
+}
+</script>
+```
+
+### 5. 埋点指令使用
+
+```vue
+<template>
+  <!-- 页面访问埋点 -->
+  <view v-track-page="'页面标题'">
+    <text>页面内容</text>
+  </view>
+
+  <!-- 自定义页面访问埋点 -->
+  <view v-track-page="{ pageTitle: '自定义标题', customData: { pageType: 'example' } }">
+    <text>自定义页面内容</text>
+  </view>
+
+  <!-- 基础点击埋点 -->
+  <button v-track-click="'button_click'">
+    点击按钮
+  </button>
+
+  <!-- 自定义点击埋点 -->
+  <button v-track-click="{
+    event: 'custom_click',
+    data: { buttonType: 'primary', value: 123 },
+    elementId: 'submit-btn',
+  }">
+    自定义点击按钮
+  </button>
+
+  <!-- 滚动埋点 -->
+  <view v-track-scroll="true">
+    <text>滚动到此区域会触发埋点</text>
+  </view>
+
+  <!-- 自定义滚动埋点 -->
+  <view v-track-scroll="{
+    threshold: 0.3,
+    data: { section: 'custom_scroll' },
+    trackDirection: true
+  }">
+    <text>自定义滚动埋点</text>
+  </view>
+
+  <!-- 搜索埋点 -->
+  <input v-track-search="'search'" />
+
+  <!-- 自定义搜索埋点 -->
+  <input v-track-search="{
+    event: 'product_search',
+    data: { category: 'electronics' },
+    trackInput: true,
+    trackSubmit: true,
+    debounceTime: 300,
+    minLength: 2
+  }" />
+</template>
+```
+
+
+## 配置选项
+
+### 初始化配置
+
+```typescript
+import { initTracking } from '~/utils/tracking/tracking-init'
+
+await initTracking({
+  enabled: true,                    // 是否启用埋点
+  debug: false,                     // 是否开启调试模式
+})
+```
+
+### SDK 配置
+
+```typescript
+import { trackingSDK } from '~/utils/tracking/tracking-sdk'
+
+trackingSDK.updateConfig({
+  enabled: true,                    // 是否启用埋点
+  debug: false,                     // 是否开启调试模式
+  batchSize: 30,                    // 批量发送大小
+  flushInterval: 100000,             // 刷新间隔(ms)
+  apiEndpoint: '/api/tracking',     // API端点
+})
+```
+
+### 自动埋点配置
+
+```typescript
+interface AutoTrackingConfig {
+  trackPageView?: boolean           // 是否自动跟踪页面访问
+  trackClicks?: boolean            // 是否自动跟踪点击事件
+  trackStay?: boolean              // 是否自动跟踪停留时间
+  pageTitle?: string               // 页面标题
+  customData?: Record<string, unknown> // 自定义数据
+}
+```
+
+## 事件类型
+
+```typescript
+enum TrackingEventType {
+  PAGE_VIEW = 'page_view',          // 页面访问
+  PAGE_LEAVE = 'page_leave',        // 页面离开
+  CLICK = 'click',                  // 点击事件
+  CUSTOM = 'custom'                 // 自定义事件
+}
+```
+
+## 使用示例
+
+### 基本点击事件
+
+```typescript
+import { trackClick } from '~/utils/tracking/tracking-sdk'
+
+// 点击事件埋点
+await trackClick('add_to_cart_btn', '加入购物车按钮')
+```
+
+### 自定义业务事件
+
+```typescript
+import { trackCustom } from '~/utils/tracking/tracking-sdk'
+
+// 自定义事件埋点
+await trackCustom('purchase_complete', {
+  order_id: 'ORDER_123',
+  amount: 99.99,
+  currency: 'CNY',
+})
+```
+
+### 带性能数据的埋点
+
+页面访问时会自动采集性能数据，也可以手动传入额外的性能数据：
+
+```typescript
+import { trackCustom, trackPageView } from '~/utils/tracking/tracking-sdk'
+
+// 页面访问时自动采集性能数据（page_load_time、response_time、memory_usage）
+await trackPageView('商品详情页')
+
+// 手动传入额外的性能数据
+await trackCustom('api_call', {
+  api_name: '/api/products/list',
+  performance: {
+    response_time: 1200,
+    network_latency: 350,
+  },
+})
+```
+
+### 带错误信息的埋点
+
+```typescript
+import { trackCustom } from '~/utils/tracking/tracking-sdk'
+
+// 带错误信息的埋点
+await trackCustom('error_occurred', {
+  error: {
+    error_code: 'TIMEOUT',
+    error_message: '请求超时',
+    error_level: 'error',
+    error_context: 'UserProfileService',
+  },
+})
+```
+
+更多示例请参考 `examples/data-structure-example.ts`。
+
+## 最佳实践
+
+1. **页面级埋点**：在页面组件中使用 `usePageTracking` 启用自动埋点
+2. **组件级埋点**：在需要埋点的组件中使用 `useAutoTracking`
+3. **业务埋点**：在关键业务节点使用 `trackCustom` 或 `trackBusiness`
+4. **调试模式**：开发环境开启调试模式，生产环境关闭
+5. **异步处理**：所有埋点方法都是异步的，使用 `await` 或 `.catch()` 处理错误
+
+## 注意事项
+
+1. **异步方法**：所有埋点方法都是异步的，需要使用 `await` 关键字
+2. **数据字段**：数据字段名使用下划线命名法 (snake_case) 符合后端规范
+3. **时间戳**：使用毫秒级 Unix 时间戳
+4. **自动采集**：SDK 会自动采集设备信息、应用信息等
+5. **批量发送**：埋点数据会自动批量发送，无需手动处理
+6. **网络异常**：网络异常时会自动重试发送
+7. **敏感信息**：敏感信息不要通过埋点传递
+8. **性能影响**：埋点数据量较大时注意性能影响
+9. **页面链路追踪**：SDK 会自动记录页面访问历史（最多保存 10 条），即使使用 `switchTab` 清空页面栈，也能正确追踪上一页信息
+
+## 核心特性
+
+### 1. 页面链路追踪
+
+SDK 实现了基于本地存储的页面链路追踪机制，解决了小程序 `switchTab` 导致页面栈重置的问题：
+
+**历史记录追踪**
+- 完全基于本地存储的历史记录获取上一页信息
+- 不依赖页面栈 `getCurrentPages()`，避免 `switchTab` 导致的链路中断
+
+**自动历史记录**
+- 每次页面访问都会自动保存到本地存储
+- 保留最近 10 条页面访问记录
+- 支持跨会话追踪
+
+**调试模式**
+- 开启调试模式可查看详细的页面追踪日志
+- 包含当前页、上一页、历史记录长度等信息
+
+```typescript
+// 开启调试模式查看页面追踪详情
+trackingSDK.updateConfig({ debug: true })
+```
+
+### 2. 页面关闭时数据发送
+
+SDK 实现了智能的数据发送机制，确保页面关闭时不丢失埋点数据：
+
+**自动触发场景**
+- 小程序隐藏（`onAppHide`）
+- H5 页面卸载（`beforeunload`、`pagehide`）
+- H5 页面隐藏（`visibilitychange`）
+
+**发送策略**
+- **H5 环境**：优先使用 `navigator.sendBeacon` API
+  - 专为页面卸载场景设计，不阻塞页面关闭
+  - 自动使用 pako 压缩数据，减少带宽消耗
+  - 如果 `sendBeacon` 失败，降级使用普通 HTTP 请求
+- **小程序环境**：使用普通异步请求，自动 pako 压缩
+
+```typescript
+import { trackingSDK } from '~/utils/tracking/tracking-sdk'
+
+// 手动触发立即发送
+trackingSDK.flushNow()
+```
+
+**优势**
+- 不会丢失页面关闭前的埋点数据
+- 不阻塞页面关闭流程
+- 跨平台支持，自动选择最优发送方式
+
+## 故障排除
+
+1. **埋点不生效**：检查是否启用了埋点功能
+2. **数据未发送**：检查网络连接和API配置
+3. **调试信息**：开启调试模式查看详细日志
+4. **性能问题**：适当调整批量发送大小和间隔
+5. **页面链路不准确**：开启调试模式查看页面追踪日志，确认历史记录是否正常保存

package/src/shared/tracking/directives/index.ts

@@ -0,0 +1,40 @@
+/**
+ * 埋点指令入口文件
+ * 统一导出所有埋点指令
+ */
+
+import type { App } from 'vue'
+import { installTrackClickDirective } from './track-click'
+import { installTrackPageDirective } from './track-page'
+import { installTrackScrollDirective } from './track-scroll'
+import { installTrackSearchDirective } from './track-search'
+
+/**
+ * 安装所有埋点指令
+ */
+export function installTrackingDirectives(app: App) {
+  // 安装点击埋点指令
+  installTrackClickDirective(app)
+
+  // 安装页面访问埋点指令
+  installTrackPageDirective(app)
+
+  // 安装滚动埋点指令
+  installTrackScrollDirective(app)
+
+  // 安装搜索埋点指令
+  installTrackSearchDirective(app)
+
+  console.log('[TrackingDirectives] 所有埋点指令安装完成')
+}
+
+// 导出各个指令的安装函数
+export { installTrackClickDirective, installTrackPageDirective, installTrackScrollDirective, installTrackSearchDirective }
+
+// 导出指令实现
+export { default as trackClickDirective } from './track-click'
+export { default as trackPageDirective } from './track-page'
+export { default as trackScrollDirective } from './track-scroll'
+export { default as trackSearchDirective } from './track-search'
+
+export default installTrackingDirectives