@tmsfe/tms-core 0.0.92 → 0.0.95

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tmsfe/tms-core",
-  "version": "0.0.92",
+  "version": "0.0.95",
   "description": "tms运行时框架",
   "repository": {
     "type": "git",
@@ -8,7 +8,9 @@
   },
   "scripts": {
     "dev": "rimraf dist &&  rollup -wc --environment TARGET:tms-core,INTER_ENV:public",
-    "build": "rimraf dist && rollup -c --environment TARGET:tms-core,INTER_ENV:public"
+    "build": "rimraf dist && rollup -c --environment TARGET:tms-core,INTER_ENV:public",
+    "tsc": "npx tsc",
+    "docs": "npx tsc && npx jsdocmd exec -c ./tmsdoc.config.js"
   },
   "main": "src/index",
   "miniprogram": "src",
@@ -35,7 +37,9 @@
     "rollup": "^2.6.1",
     "rollup-plugin-node-resolve": "^5.2.0",
     "rollup-plugin-terser": "^6.1.0",
-    "rollup-plugin-typescript2": "0.27.0"
+    "rollup-plugin-typescript2": "0.27.0",
+    "typescript": "^4.5.4",
+    "@tmsfe/jsdocmd": "0.0.2"
   },
   "author": "tms·web",
   "gitHead": "72bf52451594b49a1c9f78edbad5956d414a66ca"

package/src/cloudService.js

@@ -1,3 +1,7 @@
+/**
+ * @desc: 小程序调用云函数相关方法
+ */
+
 import { getEnvInfo, getAuthInfo } from './env';
 
 /**
@@ -6,6 +10,9 @@ import { getEnvInfo, getAuthInfo } from './env';
  * @param {Object} data 需要传给云函数的参数
  * @param {Boolean} withAuth 是否需要补充userId，token参数，当云函数需要调用SinanServer时，需要这些参数来完成鉴权
  * @returns {viod} 云函数
+ * @example
+ * const { tms } = getApp({ allowDefault: true });
+ * tms.callCloudFunc('user', { $url: 'user/getState', ...param }, true).then(({ result }) => result)
  */
 export const callCloudFunc = async (name = '', data = {}, withAuth = true) => {
   const { cloudEnvId, appVersion } = getEnvInfo();

package/src/compareVersion.js

@@ -0,0 +1,29 @@
+/**
+ * 版本比较函数
+ * @param {String} sourceVersion 作为基准版本号
+ * @param {String} targetVersion 目标比较版本号
+ * @returns {Number} 比较结果
+ * 返回值说明：
+ * 1 : 大于基准版本号
+ * 0 : 等于基准版本号
+ * -1: 小于基准版本号
+ */
+export const compareVersion = (sourceVersion, targetVersion) => {
+  if (typeof sourceVersion !== 'string' || typeof targetVersion !== 'string') {
+    throw new Error('版本比较参数类型有误');
+  }
+
+  const toInt = n => parseInt(n, 10); // eslint-disable-line require-jsdoc
+  const sourceArray = sourceVersion.split('.').map(toInt);
+  const targetArray = targetVersion.split('.').map(toInt);
+
+  for (let i = 0; i < sourceArray.length; i += 1) {
+    if (sourceArray[i] > targetArray[i]) {
+      return 1;
+    } if (sourceArray[i] < targetArray[i]) {
+      return -1;
+    }
+  }
+
+  return 0;
+};

package/src/config.js

@@ -1,5 +1,5 @@
 /**
- * 小程序云控配置实现
+ * @desc: 小程获取配置相关接口
  */
 import Request from './request';
 import { getEnvInfo } from './env';
@@ -27,12 +27,13 @@ const formatConfigPaths = (configPath) => {
 /**
  * getConfig 批量拉取配置
  * @description 拉取运营平台上的配置内容。关于运营平台的具体用法，参见{@link https://iwiki.woa.com/pages/viewpage.action?pageId=527948584}
- * @category 配置相关
  * @example <caption>拉取单个配置</caption>
- * const cfg = await app.tms.getConfig('/${client}/violation/subscribe', {}, { title: '当前城市不支持订阅'})
+ * const { tms } = getApp({ allowDefault: true });
+ * const cfg = await tms.getConfig('/${client}/violation/subscribe', {}, { title: '当前城市不支持订阅'})
  * console.log(cfg); // 成功则返回服务端存储的配置，失败返回默认值
  * @example <caption>批量拉取配置</caption>
-const cfgs = await app.tms.getConfig([
+const { tms } = getApp({ allowDefault: true });
+const cfgs = await tms.getConfig([
   '/${client}/home/service',
   '/${client}/home/navbar',
 ], {}, [

package/src/env.js

@@ -1,10 +1,22 @@
+/**
+ * @desc: 小程序运行环境相关接口
+ */
 
+/**
+ * @description 公共对象-环境变量env
+ * @namespace Env
+ * @param {String} wxAppId 当前运行时小程序的appId
+ * @param {String} appVersion 当前运行时所在项目的版本号
+ * @param {String} appEnv 运行环境 test - 测试、production - 正式
+ * @param {String} client 运行时项目名，sinan - 腾讯出行服务；
+ * @param {String} cloudEnvId 运行云函数的环境id
+ */
 const env = {
-  wxAppId: '', // 当前运行时小程序的appId
-  appVersion: '', // 当前运行时所在项目的版本号
-  appEnv: '', // 运行环境 test - 测试、production - 正式
-  client: '', // 运行时项目名，sinan - 腾讯出行服务； mycar - 我的车小程序
-  cloudEnvId: '', // 运行云函数的环境id
+  wxAppId: '',
+  appVersion: '',
+  appEnv: '',
+  client: '',
+  cloudEnvId: '',
 };
 
 let baseAuthInfo = undefined;
@@ -12,9 +24,17 @@ const getAuthInfoQueue = [];
 
 /**
  * @description 设置用户信息
- * @param {Object} authInfo 用户信息
- * @param {Object} err err
+ * @param {Object} authInfo 用户登录状态信息
+ * @param {Object} err 当获取用户信息失败时，设置错误信息
  * @returns {Void} 无返回值
+ * @example
+ * setAuthInfo({
+    firstLogin: 0
+    openId: "ou8xs5Uo4MHCETZ_P7IUwOAxvr-M"
+    token: "d8ffecd9317376bd1de3b49e1fa0e3bb"
+    uid: "407210826"
+    unionId: "oFghpwpqGK18ixIlNGy34Y28gCb0"
+ * })
  */
 export const setAuthInfo = (authInfo, err) => {
   baseAuthInfo = authInfo;
@@ -28,25 +48,34 @@ export const setAuthInfo = (authInfo, err) => {
   }
 };
 /**
- * 获取登录状态信息
- * @returns {Object} 当前用户状态参数
+ * @description 获取登录状态信息
+ * @returns {Object} 获取当前用户登录状态参数(见上)
+ * @example
+ * const data = await getAuthInfo()
+  {
+    firstLogin: 0 // 是否第一次登录
+    openId: "ou8xs5Uo4MHCETZ_P7IUwOAxvr-M"
+    token: "d8ffecd9317376bd1de3b49e1fa0e3bb"
+    uid: "407210826"
+    unionId: "oFghpwpqGK18ixIlNGy34Y28gCb0"
+  }
  */
 export const getAuthInfo = async () => {
-  if (baseAuthInfo !== undefined) {
+  if (baseAuthInfo !== undefined)  {
     return baseAuthInfo;
   }
   return new Promise((resolve, reject) => getAuthInfoQueue.push({ resolve, reject }));
 };
 
 /**
- * tms.getEnvInfo 用于获取运行时所在的环境信息
- * @returns {object} 运行时环境信息.
+ * @description 用于获取运行时所在的环境信息
+ * @returns {Object} 运行时环境信息 (返回值见上Env:namepace)
  */
 export const getEnvInfo = () => env;
 /**
  * 设置环境变量
- * @param {object} envInfo 环境变量
- * @returns {undefined} 无.
+ * @param {Object} 运行时环境信息 (入参见上Env:namepace)
+ * @returns {Void} 无.
  */
 export const setEnvInfo = (envInfo) => {
   const { wxAppId, appVersion, appEnv, client, cloudEnvId } = envInfo;

package/src/eventDispatcher.js

@@ -1,11 +1,7 @@
 /* eslint-disable require-jsdoc */
 /**
- * Copyright 2017-present, Tencent, Inc.
- * All rights reserved.
- *
- * @desc: 自定义事件机制
+ * @desc: EventDispatcher 类 事件监听器
  * @author: kexinwu@tencent.com
- *
  */
 
 /**
@@ -93,3 +89,14 @@ export default class EventDispatcher {
     }
   }
 }
+
+/**
+ * @description 获取EventDispatcher的实例
+ * @returns {Object} [EventDispatcher实例](#class-eventdispatcher)
+ * @example
+ * const { tms } = getApp({ allowDefault: true });
+ * const events = tms.getEventDispatcher();
+ * events.bind('xxx', () => {})
+ * events.dispatch({type: 'xxx'})
+ */
+export const getEventDispatcher = () => new EventDispatcher();

package/src/index-proxy.js

@@ -10,7 +10,8 @@ import AutoReport from './report/proxy/index';
 import md5 from './md5';
 import { serialize } from './objUtils';
 import { calCoordinateDistance, formatDistance } from './distanceUtils';
-import { getNavBarConfigData, compareVersion } from './navbarUtils';
+import { getNavBarConfigData } from './navbarUtils';
+import { compareVersion } from './compareVersion';
 import * as uiUtil from './tmsuiUtils';
 import * as rpxUtil from './rpx';
 import * as stringUtils from './stringUtils';
@@ -65,7 +66,7 @@ const asyncFuncNames = [
   // 这行是tms-ui的
   'showDrawer', 'hideDrawer', 'showModal', 'hideModal',
   // 这行是runtime的
-  'getPhone', 'login', 'getLoginInfo', 'getOpenId', 'getMycarPubOpenId', 'getSinanPubOpenId',
+  'getPhone', 'registerPhone', 'login', 'getLoginInfo', 'getOpenId', 'getMycarPubOpenId', 'getSinanPubOpenId',
   // tms-core
   'setAuthInfo', 'getConfig', 'navigateToWebview', 'callCloudFunc', 'getEncryptUserInfo',
   'setUserLocation', 'getUserLocation', 'getMpOpenId', 'getOuterOpenId',
@@ -147,6 +148,8 @@ function getLocationManager() {
           cityName: '深圳市',
           latitude: 22.54286,
           longitude: 114.05956,
+          title: '深圳市民中心',
+          address: '广东省深圳市福田区福中三路',
         };
       }
       return function (...args) {

package/src/index.js

@@ -1,3 +1,7 @@
+/**
+ * @module: index
+ * @desc: tms-core入口文件
+ */
 import runtime from './runtime/index';
 import Request from './request';
 import AutoReport from './report/proxy/index';
@@ -9,11 +13,12 @@ import { getLogManager, getRealtimeLogManager } from './log';
 import { setEnvInfo, getEnvInfo, setAuthInfo, setAppPagePaths, isAppPageExist, getHomePage } from './env';
 import md5 from './md5';
 import { callCloudFunc } from './cloudService';
-import EventDispatcher from './eventDispatcher';
+import { getEventDispatcher } from './eventDispatcher';
 import { serialize } from './objUtils';
 import { calCoordinateDistance, formatDistance } from './distanceUtils';
 import { rpxToPx, pxToRpx } from './rpx';
-import { getNavBarConfigData, compareVersion } from './navbarUtils';
+import { getNavBarConfigData  } from './navbarUtils';
+import { compareVersion } from './compareVersion';
 import {
   formatPlate,
   subStr,
@@ -72,16 +77,10 @@ const createRequest = (config = {}) => new Request(config);
  * @description 埋点上报
  * @returns {Object} 包含[report方法](#report)的对象
  * @example
- * getReporter().report(reportData, reportNow);
+ * getReporter().report2('当前页面|组件的唯一标志', {});
  */
 const getReporter = () => Reporter;
 
-/**
- * @description 自定义事件机制
- * @returns {Object} [EventDispatcher实例](#class-eventdispatcher)
- */
-const getEventDispatcher = () => new EventDispatcher();
-
 /**
  * @description 获取地理位置方法的集合
  * @returns {Class} [Location类](#class-location)
@@ -97,7 +96,15 @@ const getLocationBaseClass = () => LocationBase;
 /**
  * @description init core包初始化, 小程序已在app.js中对齐初始化
  * @param {Object} options 初始化
- * @returns {undefined} 无返回值.
+ * @param {String} options.appVersion 小程序本次发版的版本号
+ * @param {String} options.wxAppId appId
+ * @param {String} options.client 小程序名
+ * @param {String} options.appEnv 环境名称 production、development、test、predist
+ * @param {Array} options.appPagePaths  小程序包含的所有页面路径
+ * @param {String} options.homePage 首页的相关配置 { path: "/page/**", isTab: false }
+ * @param {String} options.cloudEnvId 云函数的环境id
+ * @param {String} options.defaultHost 小程序请求调用接口的域名，所有请求都会走腾讯出行网关服务，腾讯出行网关在转发到相关服务
+ * @returns {void} 无返回值.
  */
 const init = (options = {}) => {
   const { appVersion, wxAppId, client, defaultHost, cloudEnvId, appEnv, appPagePaths, homePage } = options;
@@ -129,6 +136,36 @@ const getUserLocation = () => {
   return getLocInstance().getLocationDetail(false);
 };
 
+/**
+ * @namespace api
+ * @description 对外暴露的api
+ * @param {Function} init 初始化方法
+ * @param {Function} createRequest 创建Request的实例的方法
+ * @param {Function} getReporter 获取上报管理器
+ * @param {Function} getLocationManager 获取地理位置管理器
+ * @param {Function} setUserLocation 设置用户位置信息
+ * @param {Function} getUserLocation 获取用户位置信息
+ * @param {Function} cloudService... 云函数相关处理查看 [cloudService](#clouddservice)
+ * @param {Function} compareVersion... 版本比较查看 [compareVersion](#compareversion)
+ * @param {Function} config... 配置相关函数查看 [config](#config)
+ * @param {Function} env... 环境相关处理查看 [env](#env)
+ * @param {Function} eventdispatcher... 事件管理相关处理 [eventdispatcher](#eventdispatcher)
+ * @param {Function} ipxHelper... iphonex相关方法查看 [ipxHelper](#ipxhelper)
+ * @param {Function} log... 上报相关方法查看 [log](#log)
+ * @param {Function} md5... md5加密查看 [md5](#md5)
+ * @param {Function} mpInfo... 服务接入相关接口查看 [mpInfo](#mpinfo)
+ * @param {Function} navbarUtils... 获取导航高度的相关函数查看 [navbarUtils](#navbarutils)
+ * @param {Function} navigator... 小程序跳转相关方法 [navigator](#navigator)
+ * @param {Function} numUtils... 数字相关处理查看 [numUtils](#numutils)
+ * @param {Function} objUtils... 对象相关处理查看[objUtils](#objutils)
+ * @param {Function} request... 请求相关处理查看 [request](#request)
+ * @param {Function} rpx... px与rpx的相互转化查看 [rpx](#rpx)
+ * @param {Function} runtime...  集成业务通用接口查看 [runtime-index](#runtime-index)
+ * @param {Function} storage... 本地缓存查看 [storage](#storage)
+ * @param {Function} stringUtils... 字符串相关处理查看 [stringUtils](#stringutils)
+ * @param {Function} syncfnmanager... 小程序调用wx同步方法的管理查看 [syncfnmanager](#syncfnmanager)
+ * @param {Function} timeUtils... 数字相关处理查看 [timeUtils](#timeutils)
+ */
 const api = {
   init,
   createRequest,
@@ -193,11 +230,9 @@ const api = {
   /* 获取加密的用户信息 */
   getEncryptUserInfo,
 
-  /** rpx转px */
   rpxToPx,
   pxToRpx,
 
-  /** 版本比较 */
   compareVersion,
   getNavBarConfigData,
 

package/src/ipxHelper.js

@@ -1,5 +1,5 @@
 /**
- * Tencent Inc. All Rights Reserved.
+ * @desc: iPhoneX相关交接接口
  * @author: petegao@tencent.com
  * Created: 2019-01-14.
  *
@@ -12,7 +12,8 @@ let isIPXSign = false;
 let ipxClass = '';
 
 /**
- * @returns {undefined}
+ * @private
+ * @returns {Void}
  */
 function init() {
   if (isInit) {
@@ -31,7 +32,8 @@ function init() {
 }
 
 /**
- * @returns {Boolean} 判断是否是 iPhoneX
+ * @description 判断是否是 iPhoneX
+ * @returns {Boolean}
  */
 function isIPX() {
   init();
@@ -39,7 +41,8 @@ function isIPX() {
 }
 
 /**
- * @returns {String} 返回 ipxClass
+ * @description 返回 ipxClass
+ * @returns {String}
  */
 function getIpxClass() {
   init();

package/src/location/base.ts

@@ -1,3 +1,4 @@
+
 import { getSetting, updateLocStatus, getSystemInfo, getTextByReason, openSetting } from './utils';// eslint-disable-line
 import EventDispatcher from '../eventDispatcher';
 import { WxPostionType } from '../types/object'; // eslint-disable-line
@@ -34,6 +35,7 @@ let isListenerLocation = false;
 
 /**
  * @class Location
+ * @private
  * @classdesc 基于微信api，封装location相关的接口。 包括监听位置变化， 获取用户位置信息
  * 获取位置授权等等。业务无关
  */

package/src/location/index.ts

@@ -1,3 +1,7 @@
+/**
+ * @module: location
+ * @desc: 封装业务侧位置的接口。 将用户经纬度转化为城市等展示信息
+ */
 import Request from '../request';
 import EventDispatcher from '../eventDispatcher';
 import LocationBase from './base'; // eslint-disable-line
@@ -48,10 +52,22 @@ let ipLocationPromise: null | Promise<IpLocationType> = null; // ip定位请求
 
 /**
  * @class Location
- * @classdesc 基于LocationBase，封装业务侧位置的接口。 将用户经纬度转化为城市等展示信息
  */
 class Location extends LocationBase {
-  // 默认位置信息
+  /**
+  * @desc 默认位置信息
+  * @property {object} locForNoAuth 默认的位置信息
+  * @property {string} locForNoAuth.privince 省份信息
+  * @property {string} locForNoAuth.cityCode 城市编码
+  * @property {string} locForNoAuth.cityName 城市名称
+  * @property {string} locForNoAuth.district 地区名称
+  * @property {string} locForNoAuth.latitude 维度
+  * @property {string} locForNoAuth.longitude 经度
+  * @example
+  * const app = getApp({ allowDefault: true });
+  * const locationManager = app.tms.getLocationManager(); // 获取位置管理器
+  * console.log(locationManager.locForNoAuth) // 获取默认位置
+  */
   public locForNoAuth = {
     province: '广东省',
     cityCode: '440300',
@@ -69,11 +85,15 @@ class Location extends LocationBase {
   }
 
   /**
-   * 获取解析后的用户位置， 比如城市信息
+   * @description 根据经纬度获取地理位置信息， 比如城市信息
    * @param { number } lat 用户纬度信息
    * @param { number } lng 用户经度信息
-   * @param { number } getPoi 位置
+   * @param { number } getPoi 位置  0 - 不获取(不返回poi字段)， 1 - 获取(返回poi字段)
    * @returns { Promise<PostionType | void> } 获取位置信息的promise
+   * @example
+   * const app = getApp({ allowDefault: true });
+   * const locationManager = app.tms.getLocationManager(); // 获取位置管理器
+   * await locationManager.getPoiInfo('xxx', 'xxx', 1)
    */
   getPoiInfo(lat: number, lng: number, getPoi: number): Promise<PostionType | void> {
     // 优先查询缓存中是否有位置信息，如果有直接返回
@@ -128,7 +148,10 @@ class Location extends LocationBase {
    * @param       {Number}  getPoi 是否获取详细poi信息， 0 - 不获取(不返回poi字段)， 1 - 获取(返回poi字段)
    * @returns {Promise<POI|ERR>} 返回对象
    * @example
-   * <caption>POI类型示例</caption>
+   * const app = getApp({ allowDefault: true });
+   * const locationManager = app.tms.getLocationManager(); // 获取位置管理器
+   * const res = await locationManager.getLocationDetail(false, 'gcj02', '', 1);
+   * <caption>res-POI类型示例</caption>
    * {
    *   cityName: '北京市',
    *   cityCode: '100100',
@@ -143,7 +166,7 @@ class Location extends LocationBase {
    *   }
    * }
    * @example
-   * <caption>ERR类型示例</caption>
+   * <caption>res-ERR类型示例</caption>
    * {
    *   err,
    *   unAuthed: true,
@@ -248,7 +271,7 @@ class Location extends LocationBase {
   }
 
   /**
-   * @description 获取用户选择的城市位置信息 或者 用户真实的位置信息（这个方法说明有问题）
+   * @description 先获取用户手动设置的位置信息，获取不到则定位授权获取用户位置信息
    * @memberof Location
    * @param {Boolean} showModalWhenCloseAuth 没有授权时是否展示授权弹窗
    * @returns {Promise} 用户位置信息

package/src/location/utils.ts

@@ -1,3 +1,7 @@
+/**
+ * @private: true
+ */
+
 import EventDispatcher from '../eventDispatcher';
 
 const event = new EventDispatcher();
@@ -123,7 +127,7 @@ export function getTextByReason(locationEnabled: boolean, isSysAndWechatAllowedG
 export function getSystemInfo(): WechatMiniprogram.SystemInfo | undefined {
   try {
     const sys: WechatMiniprogram.SystemInfo = wx.getSystemInfoSync();
-    // 方便开发时调试
+    // @ts-ignore 方便开发时调试
     if (sys.platform === 'devtools') {
       sys.locationEnabled = true;
       sys.locationAuthorized = true;

package/src/log.js

@@ -1,5 +1,6 @@
 /**
- * 本文件主要负责在小程序中日志打印功能，包含本地日志及实时日志. 主要做了两件事:
+ * @desc: 本文件主要负责在小程序中日志打印功能，包含本地日志及实时日志.
+ * 主要做了两件事:
  * 1、参数序列化处理；支持传递任意多个参数，并对类型为对象的参数进行字符串序列化处理(避免打印出来是'[Object Object]'的格式)；
  * 2、低版本兼容；
  */
@@ -19,6 +20,9 @@ const ManagerForLowerVersionLib = {
 let logInstance = null;
 let rtLogInstance = null;
 
+/**
+ * @private
+ */
 function getLogInstance() {
   if (logInstance === null) {
     logInstance = wx.getLogManager ? wx.getLogManager() : ManagerForLowerVersionLib;
@@ -26,6 +30,9 @@ function getLogInstance() {
   return logInstance;
 }
 
+/**
+ * @private
+ */
 function getRTLogInstance() {
   if (rtLogInstance === null) {
     rtLogInstance = wx.getRealtimeLogManager ? wx.getRealtimeLogManager() : ManagerForLowerVersionLib;
@@ -34,6 +41,7 @@ function getRTLogInstance() {
 }
 
 /**
+ * @private
  * 参数中有对象类型的，将其转换为字符串类型，以便查看
  * @param {Array<Any>} params 需要格式化的数据
  * @returns {Array<String>} 字符串序列化后的数据
@@ -146,7 +154,8 @@ const RTLOG = {
  * @description 获取日志管理器对象，该对象提供的方法同wx.getLogManager()提供的方法，详见微信文档
  * @returns {Object} [LOG](#namespace-log)
  * @example
- * const logger = getLogManager();
+ * const { tms } = getApp({ allowDefault: true });
+ * const logger = tms.getLogManager();
  * logger.log(1, 'str', { a: 1 }, ...);
  * logger.info(1, 'str', { a: 1 }, ...);
  * logger.debug(1, 'str', { a: 1 }, ...);
@@ -158,7 +167,8 @@ const getLogManager = () => LOG;
  * @description 获取实时日志管理器对象，该对象提供的方法同wx.getRealtimeLogManager()提供的方法，详见微信文档
  * @returns {Object} [RTLOG](#namespace-rtlog)
  * @example
- * const logger = getRealtimeLogManager();
+ * const { tms } = getApp({ allowDefault: true });
+ * const logger = tms.getRealtimeLogManager();
  * logger.info(1, 'str', { a: 1 }, ...);
  * logger.warn(1, 'str', { a: 1 }, ...);
  * logger.error(1, 'str', { a: 1 }, ...);

package/src/md5.js

@@ -1,9 +1,6 @@
 /**
- * @copyright 2017-present, Tencent, Inc. All rights reserved.
  * @author Davis.Lu <davislu@tencent.com>
- *
- * @file crypto tools.
- *
+ * @desc: 基于md5算法对源字符串进行hash，生成hash字符串
 **/
 
 /**

package/src/mpInfo.js

@@ -1,5 +1,5 @@
 /**
- * 支持服务接入相关接口
+ * @desc: 支持服务接入相关接口
  */
 import Request from './request';
 
@@ -11,6 +11,9 @@ import Request from './request';
  * @param {String} mpId 接入服务商渠道标识
  * @param {String} userId 出行用户标识
  * @returns {Promise<String>} 返回 openId，失败时返回空
+ * @example
+ * const { tms } = getApp({ allowDefault: true });
+ * tms.getMpOpenId('xxx', '111')
  */
 async function getMpOpenId(mpId, userId) {
   const { resData } = await new Request().post('user/mpinfo', { userId, mpId });
@@ -25,6 +28,9 @@ async function getMpOpenId(mpId, userId) {
  * @category 服务接入
  * @param {String} apiKey 服务接入方渠道标识
  * @returns {Promise<String>} 返回 openId，失败时返回空
+ * @example
+ * const { tms } = getApp({ allowDefault: true });
+ * tms.getMpOpenId('xxx', '111')
  */
 async function getOuterOpenId(apiKey) {
   const { resData } = await new Request().post('user/mpinfo', { mpId: apiKey });