@dg-elements/js-sdk 0.0.5

package/README.md

@@ -0,0 +1,248 @@
+# 收银台 js sdk
+## 简介
+收银台 SDK，是基于支付托管模式，商户需开通支付托管功能。SDK 支持支付宝、微信、云闪付等多种支付方式。同时能根据需求高定制化的配置页面样式。封装收银台页面以及独立支付按钮等功能组件，通过 npm 包的形式分发和引入，帮助商户无感对接支付。降低商户接入支付的复杂性。
+
+改变原有支付托管跳转页面的接入方式，只提供支付功能的组件或按钮，允许商户侧自己定制实现收银台页面。实现页面高定制化的需求。
+
+开发者通过创建 'checkout' element 创建页面组件，然后将其渲染到页面上，同时传入 callback 方法用来接收处理事件结果。
+
+* 默认包含支付宝，微信，云闪付三种支付方式。
+
+* 根据环境展示支付方式，支付宝内只展示支付宝，微信内只展示微信，云闪付只展示云闪付。系统默认浏览器展示支付宝与微信。
+
+**H5页面效果图**
+
+![checkout-element](https://cdn.cloudpnr.com/opps/api/test/partners/devtools/doc/img/checkout-element.jpg)
+
+
+**PC页面效果图**
+
+![checkout-element-pc](https://cdn.cloudpnr.com/opps/api/test/partners/devtools/doc/img/checkout-element-pc.jpg)
+
+## 流程说明
+
+![js_sdk_process](https://cdn.cloudpnr.com/opps/api/test/partners/devtools/doc/img/js_sdk_process.jpg)
+
+* 如果是 ATU App 内浏览器访问页面。
+    * 如果是微信 app，跳转授权页面，获取 authcode 下单。发起支付。（微信内走公众号支付流程，结果页）
+    * 如果是支付宝 app，下单 A_native 正扫 方式，拉起，支付。
+    * 如果是云闪付，跳转授权页面，获取 authcode，点击支付按钮，下单，发起支付。
+* 如果是手机系统自带浏览器，
+    * 选择微信支付，跳转微信托管小程序，完成支付。H5 页面轮询获取支付结果，返回支付结果给调用方。
+    * 选择支付宝支付，跳转支付宝，下单 A_native 正扫 方式，拉起，支付。H5 页面轮询获取支付结果，返回支付结果给调用方。
+    * 不支持云闪付。
+* 如果是PC 端浏览器，展示支付方式对应的支付二维码，用户扫描二维码完成支付。支付逻辑同手机端相同。
+
+## 接入说明
+
+### 服务端对接
+支付sdk是基于支付托管模式的，商户需开通支付托管功能，并且商户服务端需对接预下单接口，并提供前端接口给前端调用。
+接口文档参见 [预下单接口](!https://paas.huifu.com/open/doc/api/#/cpjs/api_cpjs_hosting)
+
+
+
+（注意：H5/PC页面预下单选择要根据环境判断，如果是ATU app内预下单pre_order_type = 1；
+如果是在商户自己App，或者是系统默认浏览器里面是通过跳转小程序的方式完成支付的，所以如果在非ATU环境下，选择微信的话 pre_order_type=3，选支付宝 预下单 pre_order_type= 2）
+
+### 前端对接准备
+#### 1，远程下载并安装sdk
+```
+npm install @dg-elements/js-sdk
+```
+或下载sdk 包
+[1.0.0](!https://cdn.cloudpnr.com/opps/api/test/partners/devtools/doc/dg-element.min.js)
+
+#### 2，引入sdk
+```
+import { HFPay } from '@dg-elements/js-sdk';
+```
+
+#### 3，判断环境
+
+如渲染单一支付按钮组件，需先判断当前环境是否支持
+```
+/**
+ * @Description: 判断是否是微信浏览器
+ */
+function isWXJS() {
+  return navigator && navigator.userAgent.toLowerCase().indexOf('micromessenger') > 0;
+}
+
+/**
+ * @Description: 判断是否是支付宝浏览器
+ */
+function isAliPayJS() {
+  return navigator && navigator.userAgent.toLowerCase().indexOf('alipayclient') > 0;
+}
+
+/**
+ * @Description: 判断是否是银联浏览器
+ */
+function isUnionPayJS() {
+  return navigator && navigator.userAgent.toLowerCase().indexOf('unionpay') > 0;
+}
+
+/**
+ * @Description: 判断是否是web环境
+ */
+function isWebEnv() {
+  return !/Android|webOS|iPhone|iPod|Phone|Mobile|OpenHarmony|BlackBerry/i.test(navigator.userAgent);
+}
+
+```
+
+#### 4，定义预下单方法
+
+通过服务端接口获取预下单号，定义方法，供后续传入sdk，sdk 内会调用该方法获取预下单号。
+以下为代码示例，具体调用以商户侧为准，但返回数据格式需与示例一致。需包含 pre_order_id、huifu_id、req_seq_id、req_date
+
+```
+const createPreOrder = async function (selectedType) {
+  // 增加loading 弹框
+  document.getElementById('loadingMask').classList.remove('hide');
+  const requestBody = {
+    huifu_id: '6666000109133323',
+    req_seq_id: Date.now().toString(),
+    trans_amt: document.getElementById('element-amount').value,
+    time_expire: '300',
+    pre_order_type: '1',
+    goods_desc: '无线鼠标静音无声笔记本台式电脑',
+    hosting_data: {
+      project_title: 'DEMO演示-无模板',
+      project_id: 'PROJECTID2023092518673961',
+      callback_url: 'http://paas.huifutest.com/checkout/demo/h5/jsSDKDemo.html',
+    }
+  };
+
+  if (isAliPayJS() || isWXJS() || isUnionPayJS() ) {
+
+    requestBody.pre_order_type = '1';
+  } else if (selectedType === 'alipay') {
+    requestBody.pre_order_type = '2';
+    requestBody.app_data = {
+      app_schema: 'app_schema',
+    }
+  } else if (selectedType === 'wechatpay') {
+    requestBody.pre_order_type = '3';
+    requestBody.miniapp_data = {
+      need_scheme: 'Y',
+    }
+  }
+
+  try {
+    const response = await fetch(`https://checkoutbff.cloudpnr.com/v1/payment/pre/create`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json', // 建議加上 Header
+      },
+      body: JSON.stringify(requestBody),
+    });
+
+    const data = await response.json();
+    console.log('預下单结果:', data);
+    // 隐藏loading 弹框
+    document.getElementById('loadingMask').classList.add('hide');
+    loadingFlag = false;
+    return {
+      pre_order_id: data.json_data.pre_order_id,
+      req_seq_id: data.json_data.req_seq_id,
+      huifu_id: data.json_data.huifu_id,
+      req_date: data.json_data.req_date,
+    };
+  } catch (err) {
+    // 隐藏loading 弹框
+    $('#loadingMask').hide();
+    console.error('預下單失敗:', err);
+    // 將錯誤向上拋出，讓調用者也能處理
+    throw err;
+  }
+}   
+```
+
+#### 5，创建收银台 element，将组件渲染到页面上
+
+* 方法调用
+```
+const { error, hfPay } = await HFPay();
+hfPay.component(elementName,{
+        createPreOrder: createPreOrder,
+        callback:callback
+    });
+```
+* 参数说明
+|参数 | 类型       |说明 |
+|:--------|:------------|:-------------| 
+| elementName | 字符串 | element 类型，checkout|
+| createPreOrder | function | 创建预下单的方法，需返回预下单号，具体参见调用示例|
+| callback | function | 回调方法，一般处理报错信息|
+
+
+
+调用示例：
+
+```
+function callback(result) {
+    console.log('callback  返回' + JSON.stringify(result));
+    // {"type":"payment_data","data":{"transStat":"1","huifuId":"6666000109133323","reqSeqId":"1753150933645","reqDate":"20250722","respDesc":"操作成功"}}
+}
+let element = hfPay.component('checkout', 
+    {
+        createPreOrder: createPreOrder,
+        callback:callback
+    });
+if (element) {
+    element.mount('#element-container');
+} else {
+   	console.log(`App: SDK 未能創建組件`);
+}	
+```
+
+#### 6，创建单支付按钮 element，将组件渲染到页面上
+
+除了创建整个checkout组件，还可以创建单支付按钮组件，支持支付宝、微信、云闪付三种支付方式
+
+* 方法调用
+```
+const { error, hfPay } = await HFPay();
+hfPay.component(type, {
+        createPreOrder: createPreOrder,
+        callback:callback
+    });
+```
+* 参数说明
+|参数 | 类型       |说明 |
+|:--------|:------------|:-------------| 
+| elementypetName | 字符串 |  单支付按钮类型，枚举值，alipay、wechatpay、unionpay|
+| createPreOrder | function | 创建预下单的方法，需返回预下单号，具体参见调用示例|
+| callback | function | 回调方法，一般处理报错信息|
+
+
+#### 7，处理回调
+
+```
+{ 
+  "type":"payment_data",
+  "data":{
+    "transStat":"1",
+    "huifuId":"6666000109133323",
+    "reqSeqId":"1753150933645",
+    "reqDate":"20250722",
+    "respDesc":"操作成功"
+  }
+}   
+```
+### 常见问题
+
+Q1：如何给支付按钮定制样式
+
+A：可直接通过按钮class name 进行css 样式定制
+
+Q2：微信支付宝是怎么实现支付的
+
+A：如果在ATU 环境中，点击支付，页面会跳转到支付页面。如果在非ATU 环境中，点击支付，会拉起小程序进行后续支付操作。
+
+## SDK版本记录
+
+|<div style="width: 35pt">版本</div> | <div style="width: 60pt">日期</div>   | 版本说明 |
+|:--------|:------------|:-------------| 
+| v1.0.0 | 2025/8/28 | 初始版本，支持微信支付宝云闪付支付 |