@uxda/appkit 4.2.94 → 4.2.95

package/PROJECT_DOCS.md

@@ -0,0 +1,142 @@
+# Appkit 项目说明文档
+
+## 1. 项目概述
+
+**Appkit** 是一个专为小程序/H5设计的业务组件包，采用 **Vue 3 + Taro** 技术栈。它封装了通用的业务逻辑和 UI 组件，支持多租户配置，旨在通过统一的接口快速接入到不同的小程序应用中。
+
+- **核心框架**: Vue 3, Taro 4.x
+- **UI 库**: NutUI (Taro版)
+- **主要功能**: 支付、用户中心、账户余额、消息通知、全埋点统计。
+- **构建工具**: Rollup
+
+## 2. 核心架构 (`src/Appkit.ts`)
+
+`Appkit` 通过 `useAppKitOptions` 提供全局配置注入，充当宿主应用与 SDK 之间的桥梁。
+
+- **AppKitOptions**: 定义了 SDK 运行所需的外部依赖，包括：
+  - `app()`, `tenant()`: 获取应用 ID 和租户 ID。
+  - `token()`, `tempToken()`: 获取认证 Token。
+  - `baseUrl()`: API 请求的基础地址。
+  - `requestPayment`, `invokeRecharge`: 调起宿主环境的支付能力。
+  - `directives`: 允许注入自定义指令。
+
+## 3. 功能模块详解
+
+项目按业务领域在 `src/` 下划分为多个独立模块，每个模块包含其专属的 API、组件和逻辑。
+
+### 3.1 余额模块 (`src/balance`)
+负责用户账户余额的展示、查询和消费规则说明。
+
+| 组件名 | 功能描述 |
+| :--- | :--- |
+| `AccountView.vue` | **账户总览**，展示用户当前余额及账户状态。 |
+| `BalanceCard.vue` | **余额卡片**，用于在首页或个人中心展示余额的卡片组件。 |
+| `BalanceReminder.vue` | **余额提醒**，当余额不足时的提示组件。 |
+| `ConsumptionFilter.vue` | **消费筛选**，用于消费记录列表的筛选条件（时间、类型等）。 |
+| `ConsumptionRules.vue` | **消费规则**，展示账户资金的使用规则说明。 |
+| `DateFilter.vue` / `DateRange.vue` | **日期选择**，辅助消费记录的时间范围筛选。 |
+| `PromoterCard.vue` | **推广员卡片**，可能涉及分销或推广收益的展示。 |
+| `SecondBalance.vue` | **二级余额**，用于展示积分、赠送金等次级资产。 |
+| `Tip.vue` | **提示组件**，余额模块通用的提示信息封装。 |
+
+### 3.2 支付模块 (`src/payment`)
+处理充值、交易记录及支付协议。
+
+| 组件名 | 功能描述 |
+| :--- | :--- |
+| `RechargeView.vue` | **充值主页**，提供充值金额选择面板和支付按钮。 |
+| `RechargeResult.vue` | **充值结果页**，展示支付成功或失败的状态。 |
+| `TradeView.vue` | **权益充值**，提供权益充值金额选择面板和支付按钮。 |
+| `AmountPicker.vue` | **金额选择器**，用于充值时选择固定金额或输入自定义金额。 |
+| `RightsPicker.vue` | **权益选择**，可能涉及购买会员权益或套餐的选择。 |
+| `UserAgreement.vue` | **用户协议**，支付前的服务协议展示与确认。 |
+
+### 3.3 消息通知模块 (`src/notice`)
+负责应用内的消息触达。
+
+| 组件名 | 功能描述 |
+| :--- | :--- |
+| `NoticeBanner.vue` | **通知横幅**，页面顶部或嵌入式的通告栏。 |
+| `NoticePopup.vue` | **通知弹窗**，强提醒类型的消息弹窗。 |
+| `NoticeList.vue` | **消息列表**，展示历史消息记录。 |
+| `NoticeList2.vue` | **新版消息列表**，展示历史消息记录。 |
+| `NoticeEntry.vue` | **消息入口**，通常带红点或未读数的消息中心入口图标。 |
+
+### 3.4 用户模块 (`src/user`)
+管理用户身份、登录及个人信息。
+
+| 组件名 | 功能描述 |
+| :--- | :--- |
+| `UserAuth.vue` | **用户授权**，处理微信登录授权逻辑。 |
+| `LoginSetting.vue` | **登录设置**，管理登录方式或账号安全设置。 |
+| `UserInfo.vue` | **用户信息**，展示头像、昵称等基础资料。 |
+| `UserHeadCrop.vue` | **头像裁剪**，用户上传头像时的图片裁剪功能。 |
+| `UserBinding.vue` | **账号绑定**，绑定手机号或第三方账号。 |
+| `UserFeedback.vue` | **用户反馈**，提交意见反馈的表单。 |
+
+### 3.5 注册模块 (`src/register`)
+| 组件名 | 功能描述 |
+| :--- | :--- |
+| `SelfRegistration.vue` | **自助注册**，引导新用户完成注册流程的组件。 |
+
+### 3.6 业务场景 (`src/scenarios`)
+特定业务逻辑的复合组件。
+| 组件名 | 功能描述 |
+| :--- | :--- |
+| `SharePoster.vue` | **分享海报**，生成包含二维码和营销信息的图片，用于朋友圈分享。 |
+| `poster-paste.vue` | **海报粘贴**，处理海报生成的底层绘制或粘贴逻辑。 |
+
+## 4. 通用基础组件 (`src/components`)
+项目内封装的通用 UI 组件，不依赖具体业务。
+
+| 组件目录 | 组件说明 |
+| :--- | :--- |
+| `dd-search` | **搜索框**，支持导航栏模式，带有搜索回调和防抖功能。 |
+| `dd-notice-bar` | **滚动通告栏**，用于显示简短的滚动消息。 |
+| `dd-skeleton` | **骨架屏**，数据加载过程中的占位显示，提升体验。 |
+| `bt-cropper` | **图片裁剪器**，基于 canvas 的高性能图片裁剪工具。 |
+| `dd-area` | **地区选择器**，省市区三级联动选择。 |
+| `dd-selector` | **通用选择器**，下拉或弹窗式的单选/多选组件。 |
+| `dd-icon` | **图标组件**，项目统一的图标封装。 |
+
+## 5. 基础设施与工具 (`src/shared`)
+
+### 5.1 全埋点系统 (`src/shared/tracking`)
+一个功能强大的埋点 SDK，支持自动和手动埋点。
+- **自动埋点**:
+  - `usePageTracking`: 自动记录页面访问、停留时间、性能数据。
+  - `useAutoTracking`: 组合式函数，用于组件级自动跟踪。
+  - **指令**: `v-track-click` (点击), `v-track-page` (页面), `v-track-scroll` (滚动), `v-track-search` (搜索)。
+- **数据发送**: 支持 H5 `sendBeacon` 和小程序异步请求，具备断网重试和页面关闭前自动发送（Flush）机制。
+
+### 5.2 常用 Hooks (`src/shared/composables`)
+提供 Vue Composition API 风格的复用逻辑：
+- `useWxAuth`: 微信授权逻辑封装。
+- `useUpload`: 文件上传逻辑。
+- `useCrypto`: 加密解密工具。
+- `useDeviceEnv`: 设备环境判断 (H5/Weapp)。
+- `useValidator`: 表单验证逻辑。
+
+### 5.3 微信能力 (`src/shared/weixin`)
+- `jssdk.ts`: 微信 JS-SDK 的封装。
+- `payment.ts`: 微信支付能力的底层调用封装。
+
+### 5.4 网络请求 (`src/shared/http`)
+- 基于配置的 HTTP 客户端，集成了 Token 注入、拦截器和错误处理。
+
+## 6. 使用示例
+
+在宿主项目中初始化 Appkit：
+
+```typescript
+// 宿主应用的入口文件
+import { useAppKitOptions } from '@uxda/appkit';
+
+const options = useAppKitOptions();
+
+// 配置 SDK
+options.baseUrl = () => 'https://api.example.com';
+options.token = () => getUserToken();
+options.app = () => 'app_id_123';
+```
+

package/dist/index.js

@@ -2628,7 +2628,8 @@ const endpointsList$2 = {
       certificateNo: params.user,
       accountAuthFlag: params.accountAuthFlag || false,
       channelCode: params.channelCode || null,
-      payFinishJumpUrl: params.payFinishJumpUrl || null
+      payFinishJumpUrl: params.payFinishJumpUrl || null,
+      clientInfo: params.clientInfo || null
     }),
     transform: (data) => {
       let json = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uxda/appkit",
-  "version": "4.2.94",
+  "version": "4.2.95",
   "description": "小程序应用开发包",
   "main": "dist/index.js",
   "module": "dist/index.ts",

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