@tmsfe/tms-core 0.0.63 → 0.0.64

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tmsfe/tms-core",
-  "version": "0.0.63",
+  "version": "0.0.64",
   "description": "tms运行时框架",
   "repository": {
     "type": "git",

package/src/report/README.md

@@ -0,0 +1,201 @@
+# 埋点
+
+### 目前支持的数据能力
+<img width="700" src="https://tai-static-1251316161.cos.ap-chengdu.myqcloud.com/reportcos/tms-data.png"/>
+
+### 埋点展示网站：https://tmsgo.testsite.woa.com/reportManage/list
+
+### 目录结构
+```
+┌─ proxy        # 全埋点逻辑
+│  ├─ clone     # 负责对象的克隆
+│  ├─ component # 负责组件的全埋点
+│  ├─ helper    # 全埋点辅助类
+│  ├─ index     # 负责页面和组件的全埋点初始化
+│  ├─ page      # 负责页面的全埋点
+│  └─ types     # 全埋点ts类型定义
+│
+├─ formatV1     # 格式化旧埋点
+├─ formatV2     # 格式化新埋点
+├─ helper       # 埋点辅助函数
+├─ index        # 埋点入口
+├─ sender       # 负责发送埋点
+└─ types        # ts类型定义
+```
+
+### 埋点的基础字段有哪些？
+不管是全埋点还是手动埋点，都会携带相同的基础字段，具体请查看```formatV2.ts```代码
+
+### 手动添加埋点
+```coffeescript
+1. const reporter = getApp().tms.getReporter();
+   // 点击登录按钮|用户名
+2. reporter.report2('login_btn_click', this.data.username);
+```
+#### 说明：
+1. 新埋点函数名为```report2()```，旧埋点函数名为```report()```，不建议再用旧埋点
+2. 埋点上方一定要写注释说明埋点每个参数的定义，用"|"隔开
+3. 构建平台在每次构建时会调用工具分析代码提取出埋点列表更新到展示网站数据库
+4. 埋点函数第一个参数为事件名，必须为string，其他参数为该事件附带数据，可以是基础类型，也可以是json对象
+
+#### 问题
+1. 代码中已有的旧埋点怎么办？可以保留，但是不建议再新增旧埋点
+2. 埋点发送机制是怎么样的？普通埋点采用合并上报的方式，通常3s上报一次，如果小程序关闭则会立即上报
+3. 如果有埋点需要立即上报该怎么办？可以把```report2()```改为调用```fastReport2()```
+4. ```report2()```与```fastReport2()```的区别是什么？```fastReport2()```上报时携带的"省"、"市"等需要异步请求的基础字段会从缓存中读取，如果无缓存则为空，```report2()```则一定会携带这些字段
+
+### 全埋点
+#### 页面自动上报事件
+##### 一、必须上报的生命周期事件：
+1. onLoad: 页面加载
+2. onShow: 页面显示
+3. onReady: 页面初次渲染完成
+4. onHide: 页面隐藏
+5. onUnload: 页面卸载
+
+##### 二、可能会上报的生命周期事件（取决于页面是否实现该函数）：
+1. onPullDownRefresh: 用户下拉动作
+2. onReachBottom: 页面上拉触底
+3. onShareAppMessage: 用户点击右上角转发
+4. onShareTimeline: 用户点击右上角转发到朋友圈
+5. onAddToFavorites: 用户点击右上角收藏
+6. onReportPageTouch: 用户触摸页面 - 如果页面wxml有view节点则会注入该事件
+
+##### 三、页面的其他bind事件，通过分析wxml得出
+#### 组件自动上报事件
+1. ready: 组件加载（会携带组件data）
+2. 组件的其他bind事件，通过分析wxml得出（会携带组件data）
+
+#### 其他自动上报事件
+1. App_onLaunch: 小程序启动
+2. wx_navigateTo_before: 页面即将跳转
+3. wx_redirectTo_before: 页面即将重定向
+4. wx_reLaunch_before: 小程序即将重启
+
+#### 注意事项
+1. bind事件函数上方要写注释，工具提取该事件时会把注释也提取出来，用作该事件说明
+2. Page或者Component的data要写注释，工具会提取data代码附到埋点说明中
+3. 某个事件触发很频繁觉得上报没意义，在函数注释中加上```ignoreReport```这个单词就不会上报该函数
+```coffeescript
+/**
+ * 拖动组件
+ * ignoreReport
+ */
+onTouchMove(e) {
+  ...
+}
+or
+// ignoreReport
+onTouchMove(e) {
+  ...
+}
+```
+
+#### 哪种bind事件的写法会使全埋点上报时把最新的data也带上？
+ps：tms-core会先执行事件函数，然后判断返回值是否promise，如果时则会等promise.then或catch之后再上报，非promise则直接上报
+1. 函数中直接setData
+```coffeescript
+/**
+ * 点击关闭按钮
+ */
+onCloseBtnTap() {
+  this.setData({ show: false });
+}
+```
+2. 函数返回promise的
+```coffeescript
+/**
+ * 点击登录按钮
+ */
+onLoginBtnTap() {
+  return tms.login().then((res) => {
+    this.setData({ userName: res.userName });
+  });
+}
+or
+/**
+ * 点击登录按钮
+ */
+async onLoginBtnTap() {
+  const res = await tms.login();
+  this.setData({ userName: res.userName });
+}
+```
+
+#### 哪种bind事件的写法会使全埋点上报时不把最新的data也带上？
+1. 函数中异步setData但是没有返回promise的
+```coffeescript
+/**
+ * 点击登录按钮
+ */
+onLoginBtnTap() {
+  tms.login().then((res) => {
+    this.setData({ userName: res.userName });
+  });
+}
+```
+
+#### 如何在开发过程中开启全埋点？
+1. 切到新脚手架的小程序目录下
+  ```
+  cd miniprogram/programs/sinan/dist
+  ```
+2. 运行工具
+  ```
+  node ../../../../tools/tms-prebuild/main.js
+  ```
+3. 等待工具跑完
+
+
+#### 如何判断全埋点是否满足产品需求？
+1. 目标事件是页面生命周期函数触发时上报，且不需要带data
+2. 目标事件是组件挂载(ready)，并且需要携带的参数在组件data中
+3. 目标事件是页面或者组件的bind事件，并且需要携带的参数在data或者函数的首个参数中(event的dataset、mark、detail)
+
+#### 埋点提取工具AST匹配规则
+```coffeescript
+/**
+ * 提取旧埋点
+ * @param content {string}
+ * @param rootAst {GoGoAST}
+ * @returns {DataInfo[]}
+ */
+function extractV1(content, rootAst) {
+  const paramsKey = '$$$0';
+  const selector = [
+    `report({ ${paramsKey} })`,
+    `Report({ ${paramsKey} })`,
+    `reportLog({ ${paramsKey} })`,
+    `fastReport({ ${paramsKey} })`,
+    `$_$1.report({ ${paramsKey} })`,
+    `$_$1.Report({ ${paramsKey} })`,
+    `$_$1.reportLog({ ${paramsKey} })`,
+    `$_$1.fastReport({ ${paramsKey} })`,
+  ];
+  const ast = rootAst.find(selector);
+  const result = [];
+  ast.each((node) => { 处理逻辑... });
+  return result;
+}
+
+
+/**
+ * 提取新埋点
+ * @param content
+ * @param rootAst {GoGoAST}
+ * @returns {DataInfo[]}
+ */
+function extractV2(content, rootAst) {
+  const paramsKey = '$$$0';
+  const selector = [
+    `report2(${paramsKey})`,
+    `fastReport2(${paramsKey})`,
+    `$_$1.report2(${paramsKey})`,
+    `$_$1.fastReport2(${paramsKey})`,
+  ];
+  const ast = rootAst.find(selector);
+  const result = [];
+  ast.each((node) => { 处理逻辑... });
+  return result;
+}
+```

package/src/report/proxy/component.ts

@@ -12,9 +12,12 @@ let originalComponent: any = null;
 // 劫持Component的生命周期
 function proxyLifeMethod(componentName: string, componentOptions: any, methodName: string): void {
   /* eslint-disable */
-  componentOptions.lifetimes = componentOptions.lifetimes || {};
-  let original = helper.emptyFunc;
-  const proxyMethod = function (...args: any[]): any {
+  let obj = componentOptions;
+  if (componentOptions.lifetimes?.hasOwnProperty(methodName)) {
+    obj = componentOptions.lifetimes;
+  }
+  let original = obj[methodName] || helper.emptyFunc;
+  obj[methodName] = function (...args: any[]): any {
     // 生命周期函数先发埋点，避免次过程用户退出而丢失埋点
     const data = clone.deepClone(this.data);
     const eventName = `Component_${componentName}_${methodName}`;
@@ -22,15 +25,6 @@ function proxyLifeMethod(componentName: string, componentOptions: any, methodNam
     // 执行原函数
     return helper.executeFunc(this, original, args, helper.emptyFunc);
   }
-  if (componentOptions.lifetimes[methodName]) {
-    original = componentOptions.lifetimes[methodName];
-    componentOptions.lifetimes[methodName] = proxyMethod;
-  } else if (componentOptions[methodName]) {
-    original = componentOptions[methodName];
-    componentOptions[methodName] = proxyMethod;
-  } else {
-    componentOptions.lifetimes[methodName] = proxyMethod;
-  }
   /* eslint-enable */
 }
 

package/src/report/proxy/helper.ts

@@ -1,5 +1,5 @@
 /**
- * 自动埋点辅助类
+ * 全埋点辅助类
  */
 
 // / <reference path='./types.ts'/>

package/src/report/proxy/page.ts

@@ -29,9 +29,8 @@ function proxyLifeMethod(pageOptions: any, methodName: string): void {
   // eslint-disable-next-line no-param-reassign
   pageOptions[methodName] = function (...args: any[]): any {
     // 生命周期函数先发埋点，避免次过程用户退出而丢失埋点
-    const options = methodName === 'onLoad' ? clone.deepClone(args[0], 0, 1) : null;
     const extra = getPageLifeExtra(this, methodName, args);
-    helper.reportData(`Page_${methodName}`, extra, options);
+    helper.reportData(`Page_${methodName}`, extra);
 
     // 执行原函数
     return helper.executeFunc(this, original, args, helper.emptyFunc);
@@ -126,11 +125,11 @@ function proxyNavigateApi(api: string): void {
     enumerable: true,
     configurable: true,
     value(...args: any) {
-      originalApi.apply(this, args);
-
       const { url = '' } = args[0] || {};
       const [path, params = ''] = url.split('?');
-      helper.reportData('wx_navigate_before', api, path, params);
+      helper.reportData(`wx_${api}_before`, path, params);
+
+      originalApi.apply(this, args);
     },
   });
 }
@@ -139,8 +138,8 @@ function proxyNavigateApi(api: string): void {
 function init(): void {
   proxyPage();
   proxyNavigateApi('navigateTo');
-  proxyNavigateApi('reLaunch');
   proxyNavigateApi('redirectTo');
+  proxyNavigateApi('reLaunch');
 }
 
 export default {

package/src/stringUtils.js

@@ -125,19 +125,21 @@ const isValidPlate = (plate) => {
  * @returns {string} 返回四舍五入后的字符串，异常情况下返回空字符串''
  */
 const roundStr = (x, n = 2, removeTrailingZero = false) => {
-  let xNum = Number(x); // x转换为数字
   const nNum = Math.floor(Number(n)); // n转换为数字，且只保留整数部分
+  let xNum = Number(x); // x转换为数字
 
   // 异常情况，返回''
-  if (isNaN(xNum) || isNaN(nNum) || nNum < 0) return '';
+  if (isNaN(xNum) || isNaN(nNum) || nNum < 0) {
+    return '';
+  }
 
   // 仅保留整数的情况
-  if (nNum === 0) return Math.round(xNum);
+  if (nNum === 0) {
+    return Math.round(xNum).toString();
+  }
 
-  // 保留n位小数的情况
-  const xStr = xNum.toString();
   const rexExp = new RegExp(`\\.\\d{${nNum}}5`);
-
+  // 保留n位小数的情况
   // 1. 大部分情况下，四舍五入使用Number.toFixed即可
   // 2. 然而，Number.toFixed方法在某些情况下对第n+1位是5的四舍五入存在问题，如1.325保留2小数时结果为1.32（期望为1.33）
   //    对此种情况下，有两种处理方式：
@@ -146,18 +148,21 @@ const roundStr = (x, n = 2, removeTrailingZero = false) => {
   //    2.2 Number.toFixed是四舍6入，对于第n+1位是5的情况，增加2*10^(-n-1)，保证满足第n+1位>6
   //        增加2*10^(-n-1)而不是增加1*10^(-n-1)是因为后者不能保证第n+1位>=6，例如1.325+0.001=1.32599999...第n+1位仍然为5
   // 此处，采用2.2方式，解决Number.toFixed的问题，又能避免2.1方式中数字超过Infinity的问题
-  if (rexExp.test(xStr)) { // 情况2，处理方式2.1：如果小数部分第n+1位是5，增加2*10^(-n-1)
+  // 情况2，处理方式2.1：如果小数部分第n+1位是5，增加2*10^(-n-1)
+  if (rexExp.test(xNum.toString())) {
     xNum += 2 * (10 ** (-nNum - 1));
   }
 
   const str = xNum.toFixed(nNum);
-  if (!removeTrailingZero) return str;
+  if (!removeTrailingZero) {
+    return str;
+  }
 
   // 去除末尾的0
   if (/^\d+\.0*$/.test(str)) { // 小数部分全是0
     return str.replace(/^(\d+)(\.0*)$/, (_m, s1) => s1);
   }
-  return str.replace(/^(\d+\.\d*[1-9]{1})(0*)$/, (_m, s1) => s1);
+  return str.replace(/^(\d+\.\d*[1-9])(0*)$/, (_m, s1) => s1);
 };
 
 export {

package/src/timeUtils.js

@@ -233,6 +233,9 @@ const parseDateTime = (str) => {
 
   const date = new Date();
   date.setFullYear(year);
+  // 解决js setMonth bug，在setMonth前先将day设置为1号，保证setMonth结果正确
+  // https://www.google.com/search?q=js+setmonth+bug&oq=js+setMonth&aqs=chrome.1.69i57j0i512j0i8i30j0i5i30j69i61.4323j0j4&sourceid=chrome&ie=UTF-8
+  date.setDate(1);
   date.setMonth(month - 1);
   date.setDate(day);
   date.setHours(hour);

package/src/timeUtils.test.js

@@ -1,7 +1,7 @@
 import { formatTimeDuration, formatTime, formatTimeWithDetails, parseDateTime } from './timeUtils';
 
 describe('timeUtils', () => {
-  describe.only('formatTimeDuration test cases', () => {
+  describe('formatTimeDuration test cases', () => {
     test.each([
       [0.001, undefined, undefined, undefined, '1秒内'],
       [0.01, 'year', 'second', 2, '0.01秒'],
@@ -120,6 +120,8 @@ describe('timeUtils', () => {
       ['2022/03/24', 1648051200000],
       ['2022/03/24 20:2', 1648123320000],
       ['2022年03月24日20时02分', 1648123320000],
+      ['2022年4月1日20时02分', 1648814520000],
+      ['2022年6月1日', 1654012800000],
     ])('parseDateTime(%s) => Date(%d)', (str, timeStamp) => {
       const date = parseDateTime(str);
       expect(date).not.toBe(null);