@pnt-team/pnt-component-frontend 0.0.73 → 0.0.74

package/README.md

@@ -22,11 +22,23 @@ yarn add @pnt-team/pnt-component-frontend
 
 ## 快速开始
 
+使用前需在应用根入口用 `PntProvider` 注入 http 实例（消费方已配置好的 axios）：
+
+```tsx
+import { PntProvider } from '@pnt-team/pnt-component-frontend';
+import http from '你的项目中的 axios 实例';
+
+<PntProvider value={{ http }}>
+  <App />
+</PntProvider>;
+```
+
 ```tsx
 import {
   // L1 基础展示组件
   PntImagePreview,
   // L2 业务复合组件
+  PntBusinessSelect,
   PntSecureBox,
   // L3 布局组件
   PntGeneralLayout,
@@ -67,9 +79,45 @@ import {
 
 ### L2 业务复合组件
 
+#### PntBusinessSelect — 业务选择器组件
+
+统一业务下拉选择器，内置对接后端通用接口 `/api/business/select/list`，支持远程搜索、滚动分页加载、多选、场景化禁用。
+
+**Props：**
+
+| 属性          | 类型                                                        | 必填 | 默认值      | 说明           |
+| ------------- | ----------------------------------------------------------- | :--: | ----------- | -------------- |
+| `value`       | `SelectValue`                                               |  ❌  | -           | 当前选中值     |
+| `onChange`    | `TdSelectProps['onChange']`                                 |  ❌  | -           | 值变化回调     |
+| `multiple`    | `boolean`                                                   |  ❌  | `false`     | 是否多选       |
+| `scene`       | `'default' \| 'sdk' \| 'compliance_age' \| 'custom_region'` |  ❌  | `'default'` | 下拉场景       |
+| `statuses`    | `number[]`                                                  |  ❌  | -           | 业务状态筛选   |
+| `labelFormat` | `'name' \| 'name_en' \| 'name_id' \| 'name_en_id'`          |  ❌  | `'name'`    | 标签格式       |
+| `filterable`  | `boolean`                                                   |  ❌  | `true`      | 是否可远程搜索 |
+| `pagination`  | `boolean`                                                   |  ❌  | `true`      | 是否分页       |
+| `placeholder` | `string`                                                    |  ❌  | -           | 占位提示文案   |
+| `disabled`    | `boolean`                                                   |  ❌  | `false`     | 是否禁用       |
+| `popupProps`  | `Partial<TdSelectProps['popupProps']>`                      |  ❌  | -           | 弹层属性透传   |
+
+**示例：**
+
+```tsx
+import { PntBusinessSelect } from '@pnt-team/pnt-component-frontend';
+
+<PntBusinessSelect
+  scene="compliance_age"
+  labelFormat="name_id"
+  placeholder="请选择业务"
+  value={gameId}
+  onChange={(v) => setGameId(v as string)}
+/>;
+```
+
+---
+
 #### PntSecureBox — 高敏信息展示组件
 
-统一处理和展示高敏信息，支持脱敏显示和按需获取真实数据。通过外部注入 `fetcher` 请求函数解锁敏感数据，零内部依赖。
+统一处理和展示高敏信息，支持脱敏显示和按需获取真实数据。通过 `PntProvider` 注入的 http 实例请求解锁敏感数据。
 
 **Props：**
 
@@ -80,26 +128,19 @@ import {
 | `env`       | `string \| number`                     | ✅   | 环境标识（如 dev / test / production） |
 | `gameId`    | `string \| number`                     | ✅   | 游戏 ID                                |
 | `renderDom` | `(content: string) => React.ReactNode` | ✅   | 自定义渲染函数                         |
-| `fetcher`   | `HighSecurityFetcher`                  | ✅   | 高敏数据请求函数（外部注入）           |
 | `viewText`  | `string`                               | ❌   | 查看按钮文案，默认 `'View'`            |
 | `pageId`    | `string`                               | ❌   | 页面 ID（用于操作日志和权限验证）      |
 
 **示例：**
 
 ```tsx
-import http from '@/utils/request';
 import { PntSecureBox } from '@pnt-team/pnt-component-frontend';
 
 <PntSecureBox
   dataKey="userPhone"
-  dataValue="138****8888"
-  env="production"
+  dataValue="_high_security_:AAAA...:6542"
+  env={2}
   gameId={12345}
-  fetcher={(params) =>
-    http
-      .post('/api/v3/business/game_info/high-security-decrypt', params)
-      .then((r) => r.data)
-  }
   renderDom={(content) => <span>{content}</span>}
   viewText="查看"
 />;

package/lib/esm/api/index.js

@@ -1,10 +1,13 @@
-// src/api/index.ts
-var businessSelectList = (axios, data) => axios.post("/business/select/list?audience=/player-network", data);
-var businessGameInfoHighSecurityDecrypt = (axios, data) => axios.post(
-  "/v3/business/game_info/high-security-decrypt?audience=/laas-pnt",
-  data
-);
-export {
-  businessGameInfoHighSecurityDecrypt,
-  businessSelectList
-};
+/**
+ * 业务下拉选择列表
+ * @param http 由 PntProvider 注入的 axios 实例
+ * @param data 请求参数
+ */
+export const businessSelectList = (axios, data) => axios.post('/business/select/list?audience=/player-network', data);
+
+/**
+ * 高敏信息解锁
+ * @param http 由 PntProvider 注入的 axios 实例
+ * @param data 请求参数
+ */
+export const businessGameInfoHighSecurityDecrypt = (axios, data) => axios.post('/v3/business/game_info/high-security-decrypt?audience=/laas-pnt', data);

package/lib/esm/api/types/index.js

@@ -0,0 +1 @@
+export {};

package/lib/esm/components/PntBusinessSelect/index.js

@@ -1,26 +1,71 @@
-// src/components/PntBusinessSelect/index.tsx
 import { businessSelectList } from "../../api";
 import { usePntConfig } from "../../config";
-import {
-  useCallback,
-  useEffect,
-  useMemo,
-  useRef,
-  useState
-} from "react";
-import { Loading, Select, Tooltip } from "tdesign-react";
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { Loading, Select, Tooltip } from 'tdesign-react';
 import "./index.scss";
-import { jsx } from "react/jsx-runtime";
-var PntBusinessSelect = (props) => {
+
+// ==========================================
+// 类型定义
+// ==========================================
+
+/** 下拉场景 */
+
+/** 标签格式 */
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * 业务选择器组件
+ * @description 统一业务下拉选择器，内置对接后端通用接口 `/api/business/select/list`，
+ * 支持远程搜索、滚动分页加载、多选、场景化禁用（合规场景 creatable 字段）。
+ *
+ * @param {PntBusinessSelectProps} props - 组件属性
+ *
+ * @example
+ * ```tsx
+ * import { PntBusinessSelect } from '@pnt-team/pnt-component-frontend';
+ *
+ * // 最简用法
+ * <PntBusinessSelect
+ *   value={gameId}
+ *   onChange={(v) => setGameId(v as string)}
+ * />
+ *
+ * // SDK 定制场景 + 名称带 ID
+ * <PntBusinessSelect
+ *   scene="sdk"
+ *   labelFormat="name_id"
+ *   value={gameId}
+ *   onChange={(v) => setGameId(v as string)}
+ * />
+ *
+ * // 合规年龄场景（自动禁用 creatable=false 的业务）
+ * <PntBusinessSelect
+ *   scene="compliance_age"
+ *   value={gameId}
+ *   onChange={(v) => setGameId(v as string)}
+ * />
+ *
+ * // 多选 + 状态过滤
+ * <PntBusinessSelect
+ *   multiple
+ *   statuses={[3, 4]}
+ *   labelFormat="name_id"
+ *   value={gameIds}
+ *   onChange={(v) => setGameIds(v as string[])}
+ * />
+ * ```
+ *
+ * @returns {ReactElement} 业务选择器组件
+ */
+const PntBusinessSelect = props => {
   const {
     value,
     onChange,
     multiple = false,
-    scene = "default",
+    scene = 'default',
     statuses,
     businessTypes,
     businessAccessMethod,
-    labelFormat = "name",
+    labelFormat = 'name',
     labelField,
     optionLabel,
     pagination = true,
@@ -37,152 +82,149 @@ var PntBusinessSelect = (props) => {
     fields,
     optionDisabled,
     optionTooltip,
-    tooltipPlacement = "top",
+    tooltipPlacement = 'top',
     className,
     style
   } = props;
-  const { http } = usePntConfig();
-  const requestFn = useCallback(
-    (params) => businessSelectList(http, params),
-    [http]
-  );
-  const [options, setOptions] = useState(
-    []
-  );
+
+  // ---- 内置请求函数（通过 PntProvider 注入的 http 实例） ----
+  const {
+    http
+  } = usePntConfig();
+  const requestFn = useCallback(params => businessSelectList(http, params), [http]);
+
+  // ---- 状态 ----
+  const [options, setOptions] = useState([]);
   const [loading, setLoading] = useState(false);
-  const [keyword, setKeyword] = useState("");
+  const [keyword, setKeyword] = useState('');
   const [pageNum, setPageNum] = useState(1);
   const [total, setTotal] = useState(0);
+
+  // ---- Refs ----
   const debounceRef = useRef();
   const loadingRef = useRef(false);
-  const selectedItemsRef = useRef(/* @__PURE__ */ new Map());
-  const buildParams = useCallback(
-    (kw, page) => ({
-      keyword: kw || void 0,
-      pageNum: pagination ? page : 1,
-      pageSize: pagination ? pageSize : 0,
-      scene,
-      statuses,
-      business_types: businessTypes,
-      business_access_method: businessAccessMethod,
-      fields
-    }),
-    [
-      scene,
-      statuses,
-      businessTypes,
-      businessAccessMethod,
-      pageSize,
-      fields,
-      pagination
-    ]
-  );
-  const fetchData = useCallback(
-    async (kw, page, append) => {
-      var _a;
-      if (loadingRef.current)
-        return;
-      loadingRef.current = true;
-      setLoading(true);
-      try {
-        const res = await requestFn(buildParams(kw, page));
-        if (res.code === 0 && res.data) {
-          const newList = res.data.list || [];
-          setOptions((prev) => append ? [...prev, ...newList] : newList);
-          setTotal(((_a = res.data.pagination) == null ? void 0 : _a.total) || 0);
-          setPageNum(page);
-        }
-      } finally {
-        loadingRef.current = false;
-        setLoading(false);
+  /** 已选中项的完整数据缓存，确保搜索后选项仍能展示 label */
+  const selectedItemsRef = useRef(new Map());
+
+  // ---- 构建请求参数 ----
+  const buildParams = useCallback((kw, page) => ({
+    keyword: kw || undefined,
+    pageNum: pagination ? page : 1,
+    pageSize: pagination ? pageSize : 0,
+    scene,
+    statuses,
+    business_types: businessTypes,
+    business_access_method: businessAccessMethod,
+    fields
+  }), [scene, statuses, businessTypes, businessAccessMethod, pageSize, fields, pagination]);
+
+  // ---- 获取数据 ----
+  const fetchData = useCallback(async (kw, page, append) => {
+    if (loadingRef.current) return;
+    loadingRef.current = true;
+    setLoading(true);
+    try {
+      const res = await requestFn(buildParams(kw, page));
+      // 适配 commonEesType：code === 0 视为成功
+      if (res.code === 0 && res.data) {
+        const newList = res.data.list || [];
+        setOptions(prev => append ? [...prev, ...newList] : newList);
+        setTotal(res.data.pagination?.total || 0);
+        setPageNum(page);
       }
-    },
-    [requestFn, buildParams]
-  );
-  const handleSearch = useCallback(
-    (val) => {
-      setKeyword(val);
-      if (debounceRef.current)
-        clearTimeout(debounceRef.current);
-      debounceRef.current = setTimeout(() => {
-        fetchData(val, 1, false);
-      }, searchDebounce);
-    },
-    [fetchData, searchDebounce]
-  );
+    } finally {
+      loadingRef.current = false;
+      setLoading(false);
+    }
+  }, [requestFn, buildParams]);
+
+  // ---- 远程搜索（防抖） ----
+  const handleSearch = useCallback(val => {
+    setKeyword(val);
+    if (debounceRef.current) clearTimeout(debounceRef.current);
+    debounceRef.current = setTimeout(() => {
+      fetchData(val, 1, false);
+    }, searchDebounce);
+  }, [fetchData, searchDebounce]);
+
+  // ---- 滚动触底加载下一页 ----
   const handleScrollToBottom = useCallback(() => {
     if (!loadingRef.current && options.length < total) {
       fetchData(keyword, pageNum + 1, true);
     }
   }, [options.length, total, keyword, pageNum, fetchData]);
-  const handlePopupVisibleChange = useCallback(
-    (visible) => {
-      if (!visible && keyword) {
-        setKeyword("");
-        fetchData("", 1, false);
-      }
-    },
-    [keyword, fetchData]
-  );
+
+  // ---- 弹窗关闭时重置搜索 ----
+  const handlePopupVisibleChange = useCallback(visible => {
+    if (!visible && keyword) {
+      setKeyword('');
+      fetchData('', 1, false);
+    }
+  }, [keyword, fetchData]);
+
+  // ---- 初始加载 + 筛选条件变化时重新加载 ----
   useEffect(() => {
-    fetchData("", 1, false);
+    fetchData('', 1, false);
   }, [fetchData]);
+
+  // ---- 缓存已选中项（确保搜索后仍能展示 label） ----
   useEffect(() => {
     const selectedValues = Array.isArray(value) ? value : value ? [value] : [];
-    options.forEach((item) => {
+    options.forEach(item => {
       if (item.game_id && selectedValues.includes(item.game_id)) {
         selectedItemsRef.current.set(item.game_id, item);
       }
     });
   }, [options, value]);
+
+  // ---- 组件卸载时清理防抖 ----
   useEffect(() => {
     return () => {
-      if (debounceRef.current)
-        clearTimeout(debounceRef.current);
+      if (debounceRef.current) clearTimeout(debounceRef.current);
     };
   }, []);
-  const formatLabel = useCallback(
-    (item) => {
-      if (optionLabel)
-        return optionLabel(item);
-      if (labelField) {
-        return item[labelField] || item.name || "";
-      }
-      const name = item.name || "";
-      const nameEn = item.name_en || "";
-      const gameId = item.game_id || "";
-      switch (labelFormat) {
-        case "name_en":
-          return nameEn || name;
-        case "name_id":
-          return `${name}（${gameId}）`;
-        case "name_en_id":
-          return `${nameEn}（${gameId}）`;
-        default:
-          return name;
-      }
-    },
-    [labelFormat, labelField, optionLabel]
-  );
-  const isOptionDisabled = useCallback(
-    (item) => {
-      if (scene === "compliance_age" || scene === "custom_region") {
-        if (item.creatable === false)
-          return true;
-      }
-      return optionDisabled ? optionDisabled(item) : false;
-    },
-    [scene, optionDisabled]
-  );
-  const getOptionTooltip = useCallback(
-    (item) => {
-      return optionTooltip ? optionTooltip(item) : "";
-    },
-    [optionTooltip]
-  );
+
+  // ---- 格式化标签 ----
+  const formatLabel = useCallback(item => {
+    // 优先级：optionLabel > labelField > labelFormat
+    if (optionLabel) return optionLabel(item);
+    if (labelField) {
+      return item[labelField] || item.name || '';
+    }
+    const name = item.name || '';
+    const nameEn = item.name_en || '';
+    const gameId = item.game_id || '';
+    switch (labelFormat) {
+      case 'name_en':
+        return nameEn || name;
+      case 'name_id':
+        return `${name}（${gameId}）`;
+      case 'name_en_id':
+        return `${nameEn}（${gameId}）`;
+      default:
+        return name;
+    }
+  }, [labelFormat, labelField, optionLabel]);
+
+  // ---- 判断选项是否禁用（合规场景 creatable + 自定义 optionDisabled 叠加） ----
+  const isOptionDisabled = useCallback(item => {
+    if (scene === 'compliance_age' || scene === 'custom_region') {
+      if (item.creatable === false) return true;
+    }
+    return optionDisabled ? optionDisabled(item) : false;
+  }, [scene, optionDisabled]);
+
+  // ---- 计算选项 tooltip 内容 ----
+  const getOptionTooltip = useCallback(item => {
+    return optionTooltip ? optionTooltip(item) : '';
+  }, [optionTooltip]);
+
+  // ---- 构建最终选项（当前页 + 已选中项补充） ----
   const selectOptions = useMemo(() => {
-    const map = /* @__PURE__ */ new Map();
-    options.forEach((item) => {
+    const map = new Map();
+
+    // 当前页选项
+    options.forEach(item => {
       if (item.game_id) {
         map.set(item.game_id, {
           label: formatLabel(item),
@@ -195,8 +237,10 @@ var PntBusinessSelect = (props) => {
         });
       }
     });
+
+    // 已选中项（搜索结果不含时补充，确保 label 始终可展示）
     const selectedValues = Array.isArray(value) ? value : value ? [value] : [];
-    selectedValues.forEach((id) => {
+    selectedValues.forEach(id => {
       if (!map.has(id)) {
         const item = selectedItemsRef.current.get(id);
         if (item) {
@@ -210,75 +254,86 @@ var PntBusinessSelect = (props) => {
             rawItem: item
           });
         } else {
-          map.set(id, { label: id, value: id, disabled: false });
+          // 降级：无完整数据时显示原始 ID
+          map.set(id, {
+            label: id,
+            value: id,
+            disabled: false
+          });
         }
       }
     });
     return Array.from(map.values());
   }, [options, value, formatLabel, isOptionDisabled]);
-  const localFilter = useCallback(
-    (filterWord, option) => {
-      if (!filterWord)
-        return true;
-      const kw = filterWord.toLowerCase();
-      const opt = option;
-      const item = opt == null ? void 0 : opt.rawItem;
-      if (item) {
-        return Object.values(item).some(
-          (v) => typeof v === "string" && v.toLowerCase().includes(kw)
-        );
-      }
-      return ((opt == null ? void 0 : opt.name) || "").toLowerCase().includes(kw) || ((opt == null ? void 0 : opt.name_en) || "").toLowerCase().includes(kw) || ((opt == null ? void 0 : opt.game_id) || "").includes(kw);
-    },
-    []
-  );
-  const { Option } = Select;
+
+  // ---- 本地过滤（与后端 keyword 逻辑一致：name / name_en / game_id） ----
+  const localFilter = useCallback((filterWord, option) => {
+    if (!filterWord) return true;
+    const kw = filterWord.toLowerCase();
+    const opt = option;
+    // 优先按 rawItem 的所有字符串字段匹配（含 labelField 指定字段）
+    const item = opt?.rawItem;
+    if (item) {
+      return Object.values(item).some(v => typeof v === 'string' && v.toLowerCase().includes(kw));
+    }
+    return (opt?.name || '').toLowerCase().includes(kw) || (opt?.name_en || '').toLowerCase().includes(kw) || (opt?.game_id || '').includes(kw);
+  }, []);
+  const {
+    Option
+  } = Select;
+
+  // 是否启用 tooltip（仅当 optionTooltip 传入时生效）
   const hasTooltip = !!optionTooltip;
+
+  // 一次性加载模式：仅本地过滤，不触发远程搜索；不分页时禁用滚动触底
   const enableRemoteSearch = filterable && pagination;
   const enableScrollBottom = pagination;
-  return /* @__PURE__ */ jsx(
-    Select,
-    {
-      value,
-      onChange,
-      filterable,
-      filter: filterable ? localFilter : void 0,
-      onSearch: enableRemoteSearch ? handleSearch : void 0,
-      loading: loading && options.length === 0,
-      multiple,
-      max,
-      clearable,
-      disabled,
-      placeholder,
-      minCollapsedNum,
-      collapsedItems,
-      onPopupVisibleChange: handlePopupVisibleChange,
-      panelBottomContent: options.length > 0 && loading ? /* @__PURE__ */ jsx(Loading, { loading: true, size: "small" }) : null,
-      popupProps: {
-        ...popupProps,
-        onScrollToBottom: enableScrollBottom ? handleScrollToBottom : void 0
-      },
-      className: className ? `pnt-business-select ${className}` : "pnt-business-select",
-      style,
-      children: selectOptions.map((opt) => {
-        const item = opt.rawItem;
-        const tip = hasTooltip && item ? getOptionTooltip(item) : "";
-        const labelText = typeof opt.label === "string" ? opt.label : String(opt.label ?? "");
-        return /* @__PURE__ */ jsx(
-          Option,
-          {
-            value: opt.value,
-            label: labelText,
-            disabled: opt.disabled,
-            children: tip ? /* @__PURE__ */ jsx(Tooltip, { content: tip, placement: tooltipPlacement, children: /* @__PURE__ */ jsx("span", { className: "pnt-business-select-option-label", children: opt.label }) }) : opt.label
-          },
-          opt.value
-        );
-      })
-    }
-  );
-};
-var PntBusinessSelect_default = PntBusinessSelect;
-export {
-  PntBusinessSelect_default as default
+  return /*#__PURE__*/_jsx(Select, {
+    value: value,
+    onChange: onChange,
+    filterable: filterable,
+    filter: filterable ? localFilter : undefined,
+    onSearch: enableRemoteSearch ? handleSearch : undefined,
+    loading: loading && options.length === 0,
+    multiple: multiple,
+    max: max,
+    clearable: clearable,
+    disabled: disabled,
+    placeholder: placeholder,
+    minCollapsedNum: minCollapsedNum,
+    collapsedItems: collapsedItems,
+    onPopupVisibleChange: handlePopupVisibleChange,
+    panelBottomContent: options.length > 0 && loading ? /*#__PURE__*/_jsx(Loading, {
+      loading: true,
+      size: "small"
+    }) : null,
+    popupProps: {
+      ...popupProps,
+      onScrollToBottom: enableScrollBottom ? handleScrollToBottom : undefined
+    },
+    className: className ? `pnt-business-select ${className}` : 'pnt-business-select',
+    style: style,
+    children: selectOptions.map(opt => {
+      const item = opt.rawItem;
+      const tip = hasTooltip && item ? getOptionTooltip(item) : '';
+      // label 仅用纯文本字符串（用于 tag 显示与过滤匹配），复杂渲染走 children
+      const labelText = typeof opt.label === 'string' ? opt.label : String(opt.label ?? '');
+      // Tooltip 必须放在 Option 内部：Select 通过直接子节点识别 Option，
+      // 外层包裹会破坏选项注册；且禁用项的 hover 事件由内部元素接收才稳定
+      return /*#__PURE__*/_jsx(Option, {
+        value: opt.value,
+        label: labelText,
+        disabled: opt.disabled,
+        children: tip ? /*#__PURE__*/_jsx(Tooltip, {
+          content: tip,
+          placement: tooltipPlacement,
+          children: /*#__PURE__*/_jsx("span", {
+            className: "pnt-business-select-option-label",
+            children: opt.label
+          })
+        }) : opt.label
+      }, opt.value);
+    })
+  });
 };
+export default PntBusinessSelect;

package/lib/esm/components/PntGeneralLayout/index.js

@@ -1,9 +1,41 @@
-// src/components/PntGeneralLayout/index.tsx
-import { ArrowLeftIcon } from "tdesign-icons-react";
-import { Layout } from "tdesign-react";
+import React from 'react';
+import { ArrowLeftIcon } from 'tdesign-icons-react';
+import { Layout } from 'tdesign-react';
 import "./index.scss";
-import { jsx, jsxs } from "react/jsx-runtime";
-var PntGeneralLayout = (prop) => {
+import { jsx as _jsx } from "react/jsx-runtime";
+import { jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * 通用页面布局组件（L3 布局组件）
+ * @description 提供标准的「头部 + 子头部 + 内容区 + 底部」页面布局结构，
+ * 基于 TDesign Layout 封装，适用于后台管理系统的详情页、表单页等场景。
+ *
+ * @example
+ * ```tsx
+ * // 基础用法：仅内容区
+ * <PntGeneralLayout>
+ *   <div>页面内容</div>
+ * </PntGeneralLayout>
+ *
+ * // 带标题和操作按钮
+ * <PntGeneralLayout
+ *   headerTitle="页面标题"
+ *   operation={<><Button>保存</Button><Button>取消</Button></>}
+ * >
+ *   <Form />
+ * </PntGeneralLayout>
+ *
+ * // 带返回按钮和底部
+ * <PntGeneralLayout
+ *   headerTitle="详情页"
+ *   showBackButton
+ *   onBackButtonClick={() => history.back()}
+ *   footer={<><Button>提交</Button><Button>重置</Button></>}
+ * >
+ *   <Detail />
+ * </PntGeneralLayout>
+ * ```
+ */
+const PntGeneralLayout = prop => {
   const {
     className,
     headerTitle,
@@ -16,39 +48,41 @@ var PntGeneralLayout = (prop) => {
     bodyStyle,
     footer
   } = prop;
-  const { Header, Footer } = Layout;
-  return /* @__PURE__ */ jsxs(Layout, { className: `pnt-general-layout${className ? " " + className : ""}`, children: [
-    headerTitle && /* @__PURE__ */ jsxs(Header, { children: [
-      /* @__PURE__ */ jsxs("span", { className: "header-title", children: [
-        showBackButton && /* @__PURE__ */ jsx(
-          ArrowLeftIcon,
-          {
-            className: "goback-icon",
-            size: "24px",
-            onClick: onBackButtonClick
-          }
-        ),
-        /* @__PURE__ */ jsx("span", { className: "title", children: headerTitle })
-      ] }),
-      operation && /* @__PURE__ */ jsx("span", { className: "header-operation", children: operation })
-    ] }),
-    subHeaderContent && /* @__PURE__ */ jsx("div", { className: "general-layout-sub-header", children: subHeaderContent }),
-    /* @__PURE__ */ jsx(
-      "div",
-      {
-        className: "general-layout-body",
-        ref: bodyRef,
-        style: {
-          height: `calc(100%${headerTitle && " - 72px"}${footer && " - 72px"})`,
-          ...bodyStyle
-        },
-        children
-      }
-    ),
-    footer && /* @__PURE__ */ jsx(Footer, { children: footer })
-  ] });
-};
-var PntGeneralLayout_default = PntGeneralLayout;
-export {
-  PntGeneralLayout_default as default
+  const {
+    Header,
+    Footer
+  } = Layout;
+  return /*#__PURE__*/_jsxs(Layout, {
+    className: `pnt-general-layout${className ? ' ' + className : ''}`,
+    children: [headerTitle && /*#__PURE__*/_jsxs(Header, {
+      children: [/*#__PURE__*/_jsxs("span", {
+        className: "header-title",
+        children: [showBackButton && /*#__PURE__*/_jsx(ArrowLeftIcon, {
+          className: "goback-icon",
+          size: "24px",
+          onClick: onBackButtonClick
+        }), /*#__PURE__*/_jsx("span", {
+          className: "title",
+          children: headerTitle
+        })]
+      }), operation && /*#__PURE__*/_jsx("span", {
+        className: "header-operation",
+        children: operation
+      })]
+    }), subHeaderContent && /*#__PURE__*/_jsx("div", {
+      className: "general-layout-sub-header",
+      children: subHeaderContent
+    }), /*#__PURE__*/_jsx("div", {
+      className: "general-layout-body",
+      ref: bodyRef,
+      style: {
+        height: `calc(100%${headerTitle && ' - 72px'}${footer && ' - 72px'})`,
+        ...bodyStyle
+      },
+      children: children
+    }), footer && /*#__PURE__*/_jsx(Footer, {
+      children: footer
+    })]
+  });
 };
+export default PntGeneralLayout;

package/lib/esm/components/PntImagePreview/index.js

@@ -1,68 +1,120 @@
-// src/components/PntImagePreview/index.tsx
 import uploadImg from "../../assets/images/uploadImg.png";
-import { BrowseIcon, DeleteIcon, LoadingIcon } from "tdesign-icons-react";
-import { Image, ImageViewer } from "tdesign-react";
+import React from 'react';
+import { BrowseIcon, DeleteIcon, LoadingIcon } from 'tdesign-icons-react';
+import { Image, ImageViewer } from 'tdesign-react';
 import "./index.scss";
-import { Fragment, jsx, jsxs } from "react/jsx-runtime";
-var PntImagePreview = ({
+import { jsx as _jsx } from "react/jsx-runtime";
+import { jsxs as _jsxs } from "react/jsx-runtime";
+import { Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * 上传图片查看器组件
+ * @description 用于展示上传的图片，支持预览、删除功能和上传状态显示
+ * @param {PntImagePreviewProps} props - 组件属性
+ * @param {string | undefined} props.iconUrl - 当前图片组件 URL
+ * @param {boolean} props.loading - 上传加载状态
+ * @param {string} [props.defaultImg] - 默认图片
+ * @param {object} [props.params] - 自定义扩展参数
+ * @param {function} [props.onRemove] - 删除回调函数
+ *
+ * @example
+ * ```tsx
+ * // 基础用法
+ * <UploadImageViewer
+ *   iconUrl={imageUrl}
+ *   loading={uploading}
+ *   onRemove={handleRemove}
+ * />
+ *
+ * // 带默认图片
+ * <UploadImageViewer
+ *   iconUrl={imageUrl}
+ *   loading={false}
+ *   defaultImg="/path/to/default.png"
+ *   onRemove={handleRemove}
+ * />
+ *
+ * // 自定义样式
+ * <UploadImageViewer
+ *   iconUrl={imageUrl}
+ *   loading={uploading}
+ *   params={{ style: { width: '200px', height: '200px' } }}
+ *   onRemove={handleRemove}
+ * />
+ * ```
+ *
+ * @returns {ReactElement} 上传图片查看器组件
+ */
+const PntImagePreview = ({
   iconUrl,
   loading,
   defaultImg,
   params,
   onRemove
 }) => {
-  const src = (iconUrl == null ? void 0 : iconUrl.length) ? iconUrl : defaultImg || uploadImg;
-  const LoadingContent = (isImageLoading) => /* @__PURE__ */ jsx(
-    "div",
-    {
-      className: isImageLoading ? "pnt-image-preview-progress" : "pnt-image-preview-upload-progress",
-      style: params == null ? void 0 : params.style,
-      children: /* @__PURE__ */ jsxs("div", { className: "pnt-image-preview-loading", children: [
-        /* @__PURE__ */ jsx(LoadingIcon, { size: "18px", name: "loading" }),
-        /* @__PURE__ */ jsx("p", { children: "上传中" })
-      ] })
-    }
-  );
-  return /* @__PURE__ */ jsx(
-    "div",
-    {
-      className: "pnt-image-preview-wrapper",
-      onClick: (e) => {
-        if ((iconUrl == null ? void 0 : iconUrl.length) || loading) {
-          e.stopPropagation();
-        }
-      },
-      children: loading ? LoadingContent(false) : /* @__PURE__ */ jsx(
-        ImageViewer,
-        {
-          images: [src],
-          closeOnOverlay: true,
-          trigger: ({ open }) => {
-            const mask = /* @__PURE__ */ jsxs("div", { className: "pnt-image-preview-mask", children: [
-              /* @__PURE__ */ jsx("span", { children: /* @__PURE__ */ jsx(BrowseIcon, { onClick: open, size: "16px", name: "browse" }) }),
-              /* @__PURE__ */ jsx("span", { className: "pnt-image-preview-divider" }),
-              /* @__PURE__ */ jsx("span", { children: /* @__PURE__ */ jsx(DeleteIcon, { onClick: onRemove, size: "16px", name: "delete" }) })
-            ] });
-            return /* @__PURE__ */ jsx(
-              Image,
-              {
-                alt: "",
-                src,
-                loading: LoadingContent(true),
-                overlayContent: iconUrl ? mask : /* @__PURE__ */ jsx(Fragment, {}),
-                overlayTrigger: "hover",
-                fit: "contain",
-                className: "pnt-image-preview",
-                style: params == null ? void 0 : params.style
-              }
-            );
-          }
-        }
-      )
-    }
-  );
-};
-var PntImagePreview_default = PntImagePreview;
-export {
-  PntImagePreview_default as default
+  const src = iconUrl?.length ? iconUrl : defaultImg || uploadImg;
+
+  /**
+   * 加载中组件
+   * @param isImageLoading - 是否为图片加载状态
+   * @description 统一使用一种loading效果，避免两种加载风格
+   * @returns 加载状态的 JSX 元素
+   */
+  const LoadingContent = isImageLoading => /*#__PURE__*/_jsx("div", {
+    className: isImageLoading ? 'pnt-image-preview-progress' : 'pnt-image-preview-upload-progress',
+    style: params?.style,
+    children: /*#__PURE__*/_jsxs("div", {
+      className: "pnt-image-preview-loading",
+      children: [/*#__PURE__*/_jsx(LoadingIcon, {
+        size: "18px",
+        name: 'loading'
+      }), /*#__PURE__*/_jsx("p", {
+        children: "\u4E0A\u4F20\u4E2D"
+      })]
+    })
+  });
+  return /*#__PURE__*/_jsx("div", {
+    className: "pnt-image-preview-wrapper",
+    onClick: e => {
+      if (iconUrl?.length || loading) {
+        e.stopPropagation(); // 图片已上传 或 加载中 阻止上传行为
+      }
+    },
+    children: loading ? LoadingContent(false) : /*#__PURE__*/_jsx(ImageViewer, {
+      images: [src],
+      closeOnOverlay: true,
+      trigger: ({
+        open
+      }) => {
+        const mask = /*#__PURE__*/_jsxs("div", {
+          className: "pnt-image-preview-mask",
+          children: [/*#__PURE__*/_jsx("span", {
+            children: /*#__PURE__*/_jsx(BrowseIcon, {
+              onClick: open,
+              size: "16px",
+              name: 'browse'
+            })
+          }), /*#__PURE__*/_jsx("span", {
+            className: "pnt-image-preview-divider"
+          }), /*#__PURE__*/_jsx("span", {
+            children: /*#__PURE__*/_jsx(DeleteIcon, {
+              onClick: onRemove,
+              size: "16px",
+              name: 'delete'
+            })
+          })]
+        });
+        return /*#__PURE__*/_jsx(Image, {
+          alt: '',
+          src: src,
+          loading: LoadingContent(true),
+          overlayContent: iconUrl ? mask : /*#__PURE__*/_jsx(_Fragment, {}),
+          overlayTrigger: "hover",
+          fit: "contain",
+          className: "pnt-image-preview",
+          style: params?.style
+        });
+      }
+    })
+  });
 };
+export default PntImagePreview;

package/lib/esm/components/PntSecureBox/index.js

@@ -1,38 +1,75 @@
-// src/components/PntSecureBox/index.tsx
 import { useHighSecurity } from "../../hooks/useHighSecurity";
 import { isSecurityData } from "../../utils";
+import React from 'react';
 import "./index.scss";
-import { Fragment, jsx, jsxs } from "react/jsx-runtime";
-var PntSecureBox = (prop) => {
-  const { dataKey, dataValue, env, gameId, renderDom, viewText, pageId } = prop;
-  const { securityData, requestSecurityData } = useHighSecurity();
-  return /* @__PURE__ */ jsx("div", { className: "pnt-secure-box", children: /* @__PURE__ */ jsxs(Fragment, { children: [
-    renderDom(
-      isSecurityData(dataValue) ? securityData[dataKey] || "******" : dataValue
-    ),
-    isSecurityData(dataValue) && !securityData.hasOwnProperty(dataKey) && /* @__PURE__ */ jsx(
-      "span",
-      {
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Fragment as _Fragment } from "react/jsx-runtime";
+import { jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * 高敏信息展示统一组件
+ * @description 用于统一处理和展示高敏信息，支持脱敏显示和按需获取真实数据。
+ * 通过 PntProvider 注入 http 实例，对接 `/api/v3/business/game_info/high-security-decrypt`。
+ *
+ * @param {PntSecureBoxProps} props - 组件属性
+ * @param {string} props.dataKey - 高敏信息的唯一标识 key
+ * @param {string} props.dataValue - 高敏信息的实际值
+ * @param {string | number} props.env - 环境标识
+ * @param {string | number} props.gameId - 游戏 ID
+ * @param {(content: string) => React.ReactNode} props.renderDom - 自定义渲染函数
+ * @param {string} [props.viewText] - 自定义查看按钮文案
+ * @param {string} [props.pageId] - 页面 ID
+ *
+ * @example
+ * ```tsx
+ * import { PntSecureBox } from '@pnt-team/pnt-component-frontend';
+ *
+ * <PntSecureBox
+ *   dataKey="userPhone"
+ *   dataValue="_high_security_:AAAA...:6542"
+ *   env={2}
+ *   gameId={12345}
+ *   renderDom={(content) => <span>{content}</span>}
+ *   viewText="查看"
+ * />
+ * ```
+ *
+ * @returns {ReactElement} 高敏信息展示组件
+ */
+const PntSecureBox = prop => {
+  const {
+    dataKey,
+    dataValue,
+    env,
+    gameId,
+    renderDom,
+    viewText,
+    pageId
+  } = prop;
+
+  // 通过 PntProvider 注入的 http 实例请求高敏数据
+  const {
+    securityData,
+    requestSecurityData
+  } = useHighSecurity();
+  return /*#__PURE__*/_jsx("div", {
+    className: "pnt-secure-box",
+    children: /*#__PURE__*/_jsxs(_Fragment, {
+      children: [renderDom(isSecurityData(dataValue) ? securityData[dataKey] || '******' : dataValue), isSecurityData(dataValue) && !securityData.hasOwnProperty(dataKey) && /*#__PURE__*/_jsx("span", {
         className: "view-icon",
         onClick: () => {
           requestSecurityData({
             env,
             gameId,
             pageId,
-            param: [
-              {
-                key: dataKey,
-                value: dataValue
-              }
-            ]
+            param: [{
+              key: dataKey,
+              value: dataValue
+            }]
           });
         },
-        children: viewText || "View"
-      }
-    )
-  ] }) });
-};
-var PntSecureBox_default = PntSecureBox;
-export {
-  PntSecureBox_default as default
+        children: viewText || 'View'
+      })]
+    })
+  });
 };
+export default PntSecureBox;

package/lib/esm/config.js

@@ -1,17 +1,37 @@
-// src/config.tsx
-import { createContext, useContext } from "react";
-var PntContext = createContext(null);
-var PntProvider = PntContext.Provider;
-var usePntConfig = () => {
+import { createContext, useContext } from 'react';
+
+/**
+ * 统一响应结构（与后端 commonEesType 对齐）
+ */
+
+/**
+ * 组件库运行时配置：由消费方通过 PntProvider 注入
+ */
+
+const PntContext = /*#__PURE__*/createContext(null);
+
+/**
+ * 配置 Provider：消费方在应用根入口包裹一次即可
+ * @example
+ * ```tsx
+ * import { PntProvider } from '@pnt-team/pnt-component-frontend';
+ * import http from './utils/request';
+ *
+ * <PntProvider value={{ http }}>
+ *   <App />
+ * </PntProvider>
+ * ```
+ */
+export const PntProvider = PntContext.Provider;
+
+/**
+ * 获取组件库运行时配置（内部使用）
+ * @internal
+ */
+export const usePntConfig = () => {
   const cfg = useContext(PntContext);
   if (!cfg) {
-    throw new Error(
-      "[pnt-component-frontend] 未注入配置：请在应用根入口用 <PntProvider value={{ http }}> 包裹"
-    );
+    throw new Error('[pnt-component-frontend] 未注入配置：请在应用根入口用 <PntProvider value={{ http }}> 包裹');
   }
   return cfg;
-};
-export {
-  PntProvider,
-  usePntConfig
-};
+};

package/lib/esm/hooks/useHighSecurity.js

@@ -1,40 +1,47 @@
-// src/hooks/useHighSecurity.ts
 import { businessGameInfoHighSecurityDecrypt } from "../api";
 import { usePntConfig } from "../config";
-import { useState } from "react";
-var securityCache = /* @__PURE__ */ new Map();
-var useHighSecurity = () => {
-  const { http } = usePntConfig();
-  const [securityData, setSecurityData] = useState(
-    () => {
-      const cached = {};
-      securityCache.forEach((value, key) => {
-        cached[key] = value;
-      });
-      return cached;
-    }
-  );
+import { useState } from 'react';
+
+/** 高敏数据请求参数（组件层友好命名） */
+
+const securityCache = new Map();
+
+/**
+ * 高敏数据解锁 Hook（PntSecureBox 内部依赖）
+ * @internal 不对外导出,归 PntSecureBox 组件内部使用
+ */
+export const useHighSecurity = () => {
+  const {
+    http
+  } = usePntConfig();
+  const [securityData, setSecurityData] = useState(() => {
+    const cached = {};
+    securityCache.forEach((value, key) => {
+      cached[key] = value;
+    });
+    return cached;
+  });
   const requestSecurityData = async ({
     gameId,
     param,
     env,
     pageId
   }) => {
+    // 适配后端 BusinessGameInfoHighSecurityDecryptBody 结构
     const body = {
       game_id: Number(gameId),
       env: Number(env),
       page_id: pageId || location.pathname,
-      param: param.map(
-        (i) => ({
-          key: i.key,
-          value: i.value
-        })
-      )
+      param: param.map(i => ({
+        key: i.key,
+        value: i.value
+      }))
     };
     const result = await businessGameInfoHighSecurityDecrypt(http, body);
+    // 适配 commonEesType：code === 0 视为成功
     if (result.code === 0 && result.data) {
       const data = result.data;
-      data.forEach((item) => {
+      data.forEach(item => {
         securityCache.set(item.key, item.value);
       });
       setSecurityData(Object.fromEntries(securityCache));
@@ -44,7 +51,4 @@ var useHighSecurity = () => {
     securityData,
     requestSecurityData
   };
-};
-export {
-  useHighSecurity
-};
+};

package/lib/esm/index.js

@@ -1,17 +1,18 @@
-// src/index.ts
-import {
-  PntProvider,
-  usePntConfig
-} from "./config";
-import { default as default2 } from "./components/PntImagePreview";
-import { default as default3 } from "./components/PntBusinessSelect";
-import { default as default4 } from "./components/PntSecureBox";
-import { default as default5 } from "./components/PntGeneralLayout";
-export {
-  default3 as PntBusinessSelect,
-  default5 as PntGeneralLayout,
-  default2 as PntImagePreview,
-  PntProvider,
-  default4 as PntSecureBox,
-  usePntConfig
-};
+// ==========================================
+// pnt-component-frontend 统一出口
+// 只保留业务语义组件：有视觉、有交互、有业务含义
+// hooks / 纯工具 / API wrapper 归各项目自己维护
+// ==========================================
+
+// ---------- 配置 Provider（消费方根入口注入 http 实例） ----------
+export { PntProvider, usePntConfig } from "./config";
+
+// ---------- L1 基础展示组件 ----------
+export { default as PntImagePreview } from "./components/PntImagePreview";
+
+// ---------- L2 业务复合组件 ----------
+export { default as PntBusinessSelect } from "./components/PntBusinessSelect";
+export { default as PntSecureBox } from "./components/PntSecureBox";
+
+// ---------- L3 布局组件 ----------
+export { default as PntGeneralLayout } from "./components/PntGeneralLayout";

package/lib/esm/utils/const.js

@@ -1,16 +1,17 @@
-// src/utils/const.ts
-var SUB_APP_PATHNAME = {
-  ACCOUNT: "/laas",
-  SDK: "/intlsdk",
-  NOTICE: "/notice",
-  CONFIGFROM: "/configform",
-  CONFIGTHEME: "/configtheme",
-  REVIEWLIST: "/approvalservices",
-  INTERNALTOOLS: "/internaltools",
-  REPORTS: "/reports"
+// 子系统页面的路由
+export const SUB_APP_PATHNAME = {
+  ACCOUNT: '/laas',
+  SDK: '/intlsdk',
+  NOTICE: '/notice',
+  CONFIGFROM: '/configform',
+  CONFIGTHEME: '/configtheme',
+  REVIEWLIST: '/approvalservices',
+  INTERNALTOOLS: '/internaltools',
+  REPORTS: '/reports'
 };
-var audienceSuffix = "-pnt";
-var AUDIENCE_MAPPING = {
+const audienceSuffix = '-pnt';
+// 子系统的audienceMapping
+export const AUDIENCE_MAPPING = {
   [SUB_APP_PATHNAME.ACCOUNT]: `/laas${audienceSuffix}`,
   [SUB_APP_PATHNAME.SDK]: `/intl-sdk${audienceSuffix}`,
   [SUB_APP_PATHNAME.NOTICE]: `/notice${audienceSuffix}`,
@@ -19,8 +20,4 @@ var AUDIENCE_MAPPING = {
   [SUB_APP_PATHNAME.REVIEWLIST]: `/approval-services${audienceSuffix}`,
   [SUB_APP_PATHNAME.INTERNALTOOLS]: `/internaltools${audienceSuffix}`,
   [SUB_APP_PATHNAME.REPORTS]: `/reports${audienceSuffix}`
-};
-export {
-  AUDIENCE_MAPPING,
-  SUB_APP_PATHNAME
-};
+};

package/lib/esm/utils/index.js

@@ -1,19 +1,22 @@
-// src/utils/index.ts
-var isSecurityData = (val) => {
+/**
+ * 判断是否是高敏信息逻辑
+ * @param {*} val
+ * @returns
+ */
+export const isSecurityData = val => {
   const str = String(val);
-  if (!str.includes("_high_security_:"))
-    return false;
-  const rsp = str.split(":");
-  const calcStr = rsp.slice(0, -1).join(":");
+  if (!str.includes('_high_security_:')) return false;
+
+  // 符合加密条件 开始解密
+  const rsp = str.split(':');
+  const calcStr = rsp.slice(0, -1).join(':');
   const calcNum = parseInt(rsp[rsp.length - 1], 10);
-  if (isNaN(calcNum))
-    return false;
+
+  // 错误处理
+  if (isNaN(calcNum)) return false;
   let num = 0;
   for (const item of calcStr) {
     num += item.charCodeAt(0);
   }
   return num === calcNum;
-};
-export {
-  isSecurityData
-};
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pnt-team/pnt-component-frontend",
-  "version": "0.0.73",
+  "version": "0.0.74",
   "description": "A react library developed with dumi",
   "license": "MIT",
   "exports": {