mantur-components 0.1.14-beta.3 → 0.1.14-beta.5

package/README.md

@@ -11,7 +11,7 @@ npm install mantur-components
 需要宿主项目提供以下 peer dependencies：
 
 ```bash
-npm install react react-dom @arco-design/web-react next-themes react-i18next
+npm install react react-dom @arco-design/web-react next-themes react-i18next posthog-js @posthog/react
 ```
 
 `next-themes` 用于组件库内置的 `ThemeSwitch`，它不是 Next.js 框架本身，普通 React/Vite 宿主也可以使用。
@@ -26,7 +26,7 @@ npm install react react-dom @arco-design/web-react next-themes react-i18next
 - 获取当前团队
 - 切换团队
 - 获取用户积分
-- 充值积分（固定套餐和自定义金额）
+- 查询充值开关，开启时展示充值积分入口（固定套餐和自定义金额）
 - 个人资料更新
 - 退出登录
 - 语言切换
@@ -149,12 +149,32 @@ Stripe publishable key 可以通过 `ManturHeader` 的 `stripePublishableKey`
 window.__MANTUR_COMPONENTS_STRIPE_PUBLISHABLE_KEY__ = "pk_test_xxx";
 ```
 
+## PostHog
+
+组件库不会单独初始化 PostHog，宿主项目需要在应用入口初始化 `posthog-js` 并挂载 `PostHogProvider`。`ManturHeader` 会通过 `@posthog/react` 复用宿主的 PostHog 实例，在 Header 内部关键交互上自动发送组件级事件，例如团队切换、用户菜单打开、充值入口点击、订单创建和 Stripe 支付成功。
+
+如果宿主没有初始化 PostHog，组件库埋点会自动跳过，不影响组件渲染和业务流程。
+
+组件库也导出 `captureManturComponentEvent()`，用于组件库外部复用同一套组件事件属性：
+
+```ts
+import { captureManturComponentEvent } from "mantur-components";
+
+captureManturComponentEvent("mantur_header_recharge_open", {
+  app_name: import.meta.env.VITE_APP_NAME,
+  entry: "custom_button",
+});
+```
+
+所有组件库事件都会自动补充 `component_library: "mantur-components"`。
+
 ## Billing API
 
 组件库按 `mantur-billing` 用户端接口导出以下 helper：
 
 ```ts
 import {
+  ensureManturBalanceEnough,
   cancelManturRechargeOrder,
   createManturRechargeOrder,
   getManturBillingAccount,
@@ -162,15 +182,21 @@ import {
   getManturBillingPackages,
   getManturPricingChargePoint,
   getManturPricingChargePoints,
+  getManturRechargeConfig,
   getManturRechargeOrder,
+  refreshManturRechargeConfig,
   MANTUR_RECHARGE_ORDER_CREATED_EVENT,
 } from "mantur-components";
 ```
 
+`ManturHeader` 挂载后会调用 `refreshManturRechargeConfig()` 拉取 `/billing/recharge/config`，并把结果保存在组件库内部状态中；只有接口返回 `enabled: true` 时，用户菜单和积分明细弹窗才展示“去充值”按钮。用户打开菜单时也会刷新一次充值开关，避免按钮状态长期停留在旧值。
+
 充值面板打开时会调用 `getManturBillingPackages()` 拉取 `/billing/packages`；点击支付时会调用 `createManturRechargeOrder()` 创建 `/billing/recharge/orders`，请求体传 `packageId` 或 `customAmount`，并固定传 `uiMode: "elements"`。请求体还会补齐 `app` 和 `redirect`：`app` 优先取 `ManturHeader` 的 `appName` prop，建议宿主传 `import.meta.env.VITE_APP_NAME`；未传时回退到 `window.__MANTUR_APP_NAME__` 或组件库内可读取的 `VITE_APP_NAME`；本地开发若没有这些配置，会用当前端口兜底识别应用（`:82` creative-agent、`:83` production-agent、`:81` traffic-engine、`:84` distribution-matrix）。`redirect` 与路由拦截器一致，只取当前页面的 `pathname + search + hash`，不拼接协议、域名或开发端口。订单创建成功后会触发浏览器事件 `mantur-recharge-order-created`，`detail` 为后端返回的订单信息。
 
 积分明细弹窗打开后会调用 `getManturBillingLedger()` 拉取 `/billing/accounts/me/ledger`，并根据“获得/消耗”、来源和日期范围筛选传递 `directions`、`bizTypes`、`fromTime`、`toTime`，分页总数使用接口返回的 `total`。
 
+业务页面在真正发起扣款前可以调用 `ensureManturBalanceEnough(deductPoints)`。该函数每次都会实时查询 `/billing/accounts/me` 获取当前余额；余额充足时返回 `enough: true`，余额不足时会刷新 `/billing/recharge/config` 并弹窗引导：充值开关开启时按钮为“去充值”，点击后打开组件库 Header 的充值弹窗；充值开关关闭时按钮为“联系管理员”。如果只需要拿校验结果不弹窗，可以传 `{ showModal: false }`。
+
 后端按 Stripe Checkout Elements 要求返回 `clientSecret` 后，`ManturHeader` 会在支付弹窗中挂载 `CheckoutElementsProvider`、`ContactDetailsElement` 和 `PaymentElement`，提交时调用 `checkout.confirm({ redirect: "if_required" })`。后端创建 Checkout Session 时必须使用 `ui_mode="elements"` 或 `ui_mode="custom"`；如果仍创建 `ui_mode="embedded"` 的 Session，Stripe 会拒绝 `initCheckoutElementsSdk`。支付成功后组件库会关闭支付弹窗并刷新积分；用户主动关闭支付弹窗时会先调用 `cancelManturRechargeOrder()` 请求 `/billing/recharge/orders/{orderNo}/cancel`，然后再关闭弹窗。组件库仍兼容旧字段名 `stripeClientSecret`，但优先读取 `clientSecret`。
 
 如果支付方式需要跳出授权，后端的 Stripe return_url 会回到 `front-main` 的 `/pay-callback?app=...&redirect=...`，`pay-callback` 会读取这两个参数并跳回原应用的 `redirect` 路由。

package/dist/api.d.ts

@@ -1,6 +1,8 @@
 import type { ManturHeaderUser, ManturPaymentMethod, ManturProfileValues, ManturTenant, ManturTenantAuthContext, ManturTenantContextDetail, ManturUserPoints } from "./types";
 export declare const MANTUR_POINTS_REFRESH_EVENT = "mantur-points-refresh";
 export declare const MANTUR_RECHARGE_ORDER_CREATED_EVENT = "mantur-recharge-order-created";
+export declare const MANTUR_RECHARGE_CONFIG_CHANGE_EVENT = "mantur-recharge-config-change";
+export declare const MANTUR_RECHARGE_REQUEST_EVENT = "mantur-recharge-request";
 export declare const MANTUR_TENANT_CONTEXT_CHANGE_EVENT = "mantur-tenant-context-change";
 export interface ManturBillingPackageDTO {
     id?: string;
@@ -55,6 +57,9 @@ export interface ManturRechargeOrderDTO {
     userNickname?: string;
     userAvatar?: string;
 }
+export interface ManturRechargeConfigDTO {
+    enabled?: boolean;
+}
 export interface ManturBillingAccountDTO {
     userId?: string;
     totalBalance?: number;
@@ -113,11 +118,18 @@ export interface ManturLedgerQuery {
     fromTime?: string;
     toTime?: string;
 }
+export interface ManturBalanceCheckResult {
+    deductPoints: number;
+    balance: number;
+    enough: boolean;
+    points: Required<ManturUserPoints>;
+}
 declare global {
     interface Window {
         __MANTUR_COMPONENTS_API_BASE__?: string;
         __MANTUR_COMPONENTS_POINTS_ENDPOINT__?: string;
         __MANTUR_COMPONENTS_STRIPE_PUBLISHABLE_KEY__?: string;
+        __MANTUR_COMPONENTS_RECHARGE_CONFIG__?: ManturRechargeConfigDTO;
         __MANTUR_COMPONENTS_TENANT_CONTEXT__?: ManturTenantContextDetail;
         __MANTUR_MAIN_PREFIX__?: string;
         __MANTUR_APP_NAME__?: string;
@@ -128,7 +140,11 @@ export declare function logoutManturUser(): Promise<void>;
 export declare function updateManturProfile(values: ManturProfileValues): Promise<ManturHeaderUser | undefined>;
 export declare function getManturUserPoints(): Promise<ManturUserPoints>;
 export declare function refreshManturUserPoints(): Promise<ManturUserPoints>;
+export declare function checkManturBalanceEnough(deductPoints: number): Promise<ManturBalanceCheckResult>;
 export declare function getManturBillingPackages(): Promise<ManturBillingPackageDTO[]>;
+export declare function getManturRechargeConfig(): Promise<{
+    enabled: boolean;
+}>;
 export declare function createManturRechargeOrder(requestBody: ManturCreateRechargeOrderRequest): Promise<ManturCreateRechargeOrderResponse | undefined>;
 export declare function getManturRechargeOrder(orderNo: string): Promise<ManturRechargeOrderDTO | undefined>;
 export declare function cancelManturRechargeOrder(orderNo: string): Promise<null | undefined>;

package/dist/billing.d.ts

@@ -0,0 +1,14 @@
+import type { ReactNode } from "react";
+import { type ManturBalanceCheckResult } from "./api";
+export interface ManturBalanceEnsureResult extends ManturBalanceCheckResult {
+    rechargeEnabled: boolean;
+}
+export interface ManturBalanceEnsureOptions {
+    showModal?: boolean;
+    title?: ReactNode;
+    content?: ReactNode;
+    onRecharge?: () => void;
+    onContactAdmin?: () => void;
+}
+export declare function openManturRechargeModal(): void;
+export declare function ensureManturBalanceEnough(deductPoints: number, options?: ManturBalanceEnsureOptions): Promise<ManturBalanceEnsureResult>;

package/dist/header/components/PointsDetailModal.d.ts

@@ -1,7 +1,8 @@
 import type { ManturHeaderLabels, ManturUserPoints } from "../../types";
-export declare function PointsDetailModal({ visible, points, text, onCancel, onRecharge, }: {
+export declare function PointsDetailModal({ visible, points, rechargeEnabled, text, onCancel, onRecharge, }: {
     visible: boolean;
     points: Required<ManturUserPoints>;
+    rechargeEnabled: boolean;
     text: ManturHeaderLabels;
     onCancel: () => void;
     onRecharge: () => void;

package/dist/header/components/UserMenu.d.ts

@@ -1,7 +1,8 @@
 import type { ManturHeaderLabels, ManturHeaderUser, ManturUserPoints } from "../../types";
-export declare function UserMenu({ user, points, text, onEditProfile, onRecharge, onPointsDetail, onLogout, }: {
+export declare function UserMenu({ user, points, rechargeEnabled, text, onEditProfile, onRecharge, onPointsDetail, onLogout, }: {
     user?: ManturHeaderUser | null;
     points: Required<ManturUserPoints>;
+    rechargeEnabled: boolean;
     text: ManturHeaderLabels;
     onEditProfile: () => void;
     onRecharge: () => void;

package/dist/index.d.ts

@@ -1,8 +1,12 @@
 export { ManturHeader } from "./header";
-export { cancelManturRechargeOrder, createManturRechargeOrder, getManturBillingAccount, getManturBillingLedger, getManturBillingPackages, getManturPricingChargePoint, getManturPricingChargePoints, getManturRechargeOrder, MANTUR_POINTS_REFRESH_EVENT, MANTUR_RECHARGE_ORDER_CREATED_EVENT, MANTUR_TENANT_CONTEXT_CHANGE_EVENT, refreshManturUserPoints, refreshManturTenantContext, } from "./api";
-export type { ManturBillingAccountDTO, ManturBillingPackageDTO, ManturChargePointWithModelsDTO, ManturCreateRechargeOrderRequest, ManturCreateRechargeOrderResponse, ManturLedgerEntryDTO, ManturLedgerQuery, ManturModelRuleDTO, ManturPageResult, ManturRechargeOrderDTO, } from "./api";
+export { ensureManturBalanceEnough, openManturRechargeModal, type ManturBalanceEnsureOptions, type ManturBalanceEnsureResult, } from "./billing";
+export { cancelManturRechargeOrder, checkManturBalanceEnough, createManturRechargeOrder, getManturBillingAccount, getManturBillingLedger, getManturBillingPackages, getManturPricingChargePoint, getManturPricingChargePoints, getManturRechargeConfig, getManturRechargeOrder, MANTUR_RECHARGE_CONFIG_CHANGE_EVENT, MANTUR_POINTS_REFRESH_EVENT, MANTUR_RECHARGE_ORDER_CREATED_EVENT, MANTUR_RECHARGE_REQUEST_EVENT, MANTUR_TENANT_CONTEXT_CHANGE_EVENT, refreshManturUserPoints, refreshManturTenantContext, } from "./api";
+export { getManturRechargeConfigSnapshot, refreshManturRechargeConfig, subscribeManturRechargeConfig, } from "./recharge-config-store";
+export type { ManturBalanceCheckResult, ManturBillingAccountDTO, ManturBillingPackageDTO, ManturChargePointWithModelsDTO, ManturCreateRechargeOrderRequest, ManturCreateRechargeOrderResponse, ManturLedgerEntryDTO, ManturLedgerQuery, ManturModelRuleDTO, ManturPageResult, ManturRechargeConfigDTO, ManturRechargeOrderDTO, } from "./api";
 export { formatDateByLang } from "./utils/date";
 export type { ManturDateFormatType, ManturDateInput } from "./utils/date";
+export { captureManturComponentEvent } from "./posthog";
+export type { ManturPostHogEvent, ManturPostHogProperties } from "./posthog";
 export { getManturRechargeRedirectContext, redirectToManturMain, redirectToManturMainHome, resolveManturMainHomeUrl, } from "./utils/url";
 export type { ManturMainRedirectOptions } from "./utils/url";
 export { isManturStripePaymentWindowMessage, MANTUR_STRIPE_PAYMENT_ROUTE, MANTUR_STRIPE_PAYMENT_WINDOW_MESSAGE_TYPE, postManturStripePaymentWindowMessage, resolveManturRechargePaymentPageUrl, resolveManturStripePaymentPageUrl, } from "./utils/stripe-payment-window";