@jctrans-materials/shared 1.0.41-beta.5 → 1.0.41-beta.7

package/README.md

@@ -12,6 +12,8 @@ JCTrans 前端共享工具库，为 JCTrans 系列项目提供认证、请求、
 | 统一类型 | `api/searchTypes` | 搜索模块共享类型定义 |
 | 认证 API | `api/auth` | 登录、注册、第三方登录、密码找回、Session 管理 |
 | 业务 API | `api/common` + `api/applyData` | 验证码、字典、IP 查询、数据上报 |
+| 反查回显 | `api/reverseLookup` | 按英文展示名反查实体详情 |
+| DW-SDK | `dw-sdk/` | 数据仓库 GraphQL SDK 统一入口 |
 | 请求封装 | `utils/request` | Axios/Fetch 双适配器 + 拦截器 |
 | Token 管理 | `utils/storage` | Cookie 凭证存取（Access Token / Refresh Token） |
 | 加密 | `utils/crypto` | AES 加解密（ECB，与后端对齐） |
@@ -75,8 +77,55 @@ createRequest("axios");
 
 // 切换为 Fetch（可传入自定义实现，如 Nuxt 的 $fetch）
 createRequest("fetch", { fetch: $fetch });
+
+// 切换为 Custom（小程序等非浏览器环境，完全透传）
+createRequest("custom", {
+  baseURL: "https://cloudapi-sit2.jctrans.net.cn",
+  fetch: async ({ url, method, data, params, headers }) => {
+    // 用户自己的请求实现，header/token/返回值完全由你控制
+    return new Promise((resolve, reject) => {
+      wx.request({
+        url,
+        method: method as any,
+        data,
+        header: headers,
+        success: (res: any) => resolve(res.data),
+        fail: reject,
+      });
+    });
+  },
+});
 ```
 
+#### ClientId 插件
+
+自动在所有请求 header 中注入客户端唯一标识（`client-uid`），用于无埋点追踪和用户行为分析。
+
+```typescript
+import {
+  installClientIdPlugin,
+  installFetchClientIdPlugin,
+  getOrCreateClientId,
+  createRequest,
+} from "@jctrans-materials/shared";
+
+// Axios 环境：直接安装插件
+installClientIdPlugin(axiosInstance, {
+  headerName: "client-uid", // 可选，默认 'client-uid'
+});
+
+// Fetch 环境：先创建请求实例再安装
+const request = createRequest("fetch", { fetch: customFetch });
+installFetchClientIdPlugin({
+  headerName: "client-uid", // 可选，默认 'client-uid'
+});
+
+// 手动获取 clientId
+const cid = getOrCreateClientId(); // 首次调用自动生成并持久化
+```
+
+> **原理**：使用 `nanoid` 生成，完全 SSR 兼容（无 `window`/`document` 依赖）。ClientId 存储在 `localStorage` 中，跨页面共享。
+
 ### 3. 地理位置搜索
 
 #### V2 接口（推荐）
@@ -240,6 +289,14 @@ import { tracker, normalizeClickPageAttrs, GIO_EVENT_CLICK_PAGE } from "@jctrans
 tracker.init("account-id", "datasource-id", {
   debug: true,
   trackPage: true,
+  // 性能采集（默认开启首屏加载监控和错误监控，默认关闭网络监控）
+  performance: {
+    monitor: true,     // 首屏加载监控，默认 true
+    exception: true,   // 错误监控，默认 true
+    network: {         // 网络监控，不配置则默认关闭
+      exclude: /api\.example\.com/,  // 排除指定域名的请求
+    },
+  },
 });
 
 // 设置用户 ID
@@ -304,6 +361,62 @@ await reportNewTypeDataApi({
 });
 ```
 
+### 10. 反查回显
+
+通过英文展示名（nameEnShow）反查实体详情，用于从外部链接或 URL 参数回显数据。
+
+```typescript
+import {
+  getAirportByNameEnShow,
+  getCountryByNameEnShow,
+  getCityByNameEnShow,
+  getSeaportByNameEnShow,
+} from "@jctrans-materials/shared";
+
+// 按英文展示名查询机场详情
+const airport = await getAirportByNameEnShow("Shanghai Pudong International Airport");
+
+// 按英文展示名查询国家详情
+const country = await getCountryByNameEnShow("China");
+
+// 按英文展示名查询城市详情
+const city = await getCityByNameEnShow("Shanghai");
+
+// 按英文展示名查询港口详情
+const seaport = await getSeaportByNameEnShow("Shanghai Port");
+```
+
+### 11. DW-SDK（数据仓库 GraphQL SDK）
+
+对 `@jctrans/dw-sdk` 的零配置封装，自动注入 baseUrl 和 Authorization Token。
+
+```typescript
+import {
+  queryOpportunityBoard,
+  GraphQLClientError,
+} from "@jctrans-materials/shared";
+import type {
+  OpportunityBoardParams,
+  BoardQueryResult,
+  DateType,
+} from "@jctrans-materials/shared";
+
+// 查询商机有效看板数据
+const result = await queryOpportunityBoard({
+  compId: 12345,
+  dateType: "QUARTER",
+  dateValue: "2026-Q2",
+});
+
+if (result.success) {
+  console.log(result.data.records);
+} else {
+  console.error(result.error);
+}
+```
+
+> **原理**：每次调用内部新建 `createDwSdk()` 实例，调用后即销毁，无状态污染。`baseUrl` 自动从 `initSharedConfig` 的 `prefixPath + '/data'` 拼接。
+
 ## 核心 API 参考
 
 ### 配置
@@ -363,6 +476,23 @@ await reportNewTypeDataApi({
 | `setAuthSessionItems` / `getAuthSessionItems` / `resetAuthSessionItems` | Auth Session 管理 |
 | `setGioSessionItems` / `getGioSessionItems` / `resetGioSessionItems` | GIO Session 管理 |
 
+### 反查回显
+
+| 方法 | 说明 |
+|------|------|
+| `getAirportByNameEnShow` | 按英文展示名查询机场 |
+| `getCountryByNameEnShow` | 按英文展示名查询国家 |
+| `getCityByNameEnShow` | 按英文展示名查询城市 |
+| `getSeaportByNameEnShow` | 按英文展示名查询港口 |
+
+### DW-SDK
+
+| 方法 | 说明 |
+|------|------|
+| `queryOpportunityBoard` | 查询商机有效看板（分页） |
+
+导出类型：`OpportunityBoardParams`, `BoardQueryResult`, `DateType`, `GraphQLClientError`。
+
 ### Token & Cookie
 
 | 方法 | 说明 |
@@ -377,13 +507,15 @@ await reportNewTypeDataApi({
 
 | 方法 | 说明 |
 |------|------|
-| `isEmpty` | 判断值是否为空（支持 string/array/object/Map/Set） |
+| `isEmpty` | 判断值是否为空（null/undefined/空字符串/空数组/空对象/空 Map/空 Set）。数字、布尔值等原始类型返回 `false` |
 | `isIpAddress` / `getFirstDomain` | 域名工具 |
 | `getAppId` / `getProjectId` | 跨环境 ID 获取 |
 | `getLanguage` | 获取当前语言 |
 | `getSessionHeaderValue` / `toSafeHeaderValue` | HTTP Header 安全工具 |
 | `encrypt` / `decrypt` | AES 加解密 |
 | `generateClientId` / `getOrCreateClientId` | 客户端唯一标识 |
+| `installClientIdPlugin` | 为 Axios 实例注入 client-uid header |
+| `installFetchClientIdPlugin` | 为 Fetch 请求注入 client-uid header |
 
 ## 类型定义
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jctrans-materials/shared",
-  "version": "1.0.41-beta.5",
+  "version": "1.0.41-beta.7",
   "private": false,
   "description": "Shared utilities including auth, request, crypto, and GrowingIO analytics.",
   "main": "dist/index.cjs.js",