@skyroc/scripts 2.5.0

package/templates/admin-shell/notification/notification-store.ts

@@ -0,0 +1,438 @@
+import { PriorityQueue, nanoid } from '@skyroc/utils';
+
+import type {
+  AddNotificationInput,
+  NotificationConfig,
+  NotificationItem,
+  NotificationPriority,
+  NotificationShortcutOptions,
+  NotificationSnapshot,
+  NotificationStoreOptions
+} from './types';
+
+/** 默认的通知运行时配置。 */
+export const DEFAULT_NOTIFICATION_CONFIG: NotificationConfig = {
+  browserNotificationEnabled: true,
+  doNotDisturb: false,
+  maxNotifications: 99,
+  soundEnabled: true
+};
+
+/** 排序权重，越小越靠前。没标优先级的按 normal 算。 */
+const PRIORITY_WEIGHT: Record<NotificationPriority, number> = {
+  high: 1,
+  low: 3,
+  normal: 2,
+  urgent: 0
+};
+
+/**
+ * 队列里额外挂的入队序号。
+ *
+ * Timestamp 是毫秒，一轮循环推进来的多条会撞成同一个值，只按它排的话顺序由 sort 的实现决定。 序号单调递增，做最后一道 tie-breaker。
+ */
+type QueuedNotification = NotificationItem & { seq: number };
+
+/** 把优先级换算成排序权重。未标优先级的按 normal 算，让 compareNotifications 不用到处判空。 */
+function getWeight(priority: NotificationPriority | undefined): number {
+  return PRIORITY_WEIGHT[priority ?? 'normal'];
+}
+
+/** 先按优先级，再按时间倒序（新的在前），最后按入队序号倒序。已读与否不参与排序：否则点一下已读整个列表会跳动。 */
+function compareNotifications(a: QueuedNotification, b: QueuedNotification): number {
+  return getWeight(a.priority) - getWeight(b.priority) || b.timestamp - a.timestamp || b.seq - a.seq;
+}
+
+/**
+ * 取当前本地时间的 HH:mm 文本。
+ *
+ * 免打扰配置里的 start / end 就是这个格式，统一成字符串后可以直接比大小，不用先解析成分钟数。
+ */
+function getCurrentTimeText(): string {
+  const now = new Date();
+  const hour = now.getHours().toString().padStart(2, '0');
+  const minute = now.getMinutes().toString().padStart(2, '0');
+
+  return `${hour}:${minute}`;
+}
+
+/** 判断时间是否处于指定范围内，同时支持跨午夜的时间段。 */
+function isWithinTimeRange(currentTime: string, start: string, end: string): boolean {
+  if (start <= end) {
+    return currentTime >= start && currentTime <= end;
+  }
+
+  return currentTime >= start || currentTime <= end;
+}
+
+/**
+ * 通知中心的状态与副作用，不依赖 React。
+ *
+ * 只管三件事：维护去重排序后的通知队列、维护运行时配置、按配置播音效和弹浏览器通知。 消息从哪来（WebSocket、SSE、HTTP 轮询、手动调用）一概不知道 —— 数据源留在宿主应用里， 否则这个包会被绑死在某一套后端协议上。
+ *
+ * React 侧用 subscribe / getSnapshot 交给 useSyncExternalStore 订阅，见 use-notification.ts。
+ */
+export class NotificationStore {
+  /** 当前运行时配置，唯一真相。 */
+  private config: NotificationConfig;
+
+  /** 变更监听器集合，快照重建后统一回调。 */
+  private readonly listeners = new Set<() => void>();
+
+  /** 宿主注入的音效地址和各类失败回调。随 Provider 每次渲染整体替换，见 setOptions。 */
+  private options: NotificationStoreOptions;
+
+  /** 浏览器原生通知的授权状态。构造时不读，见 syncPermission。 */
+  private permission: NotificationPermission = 'default';
+
+  /** Id 去重 + 优先级排序 + 容量上限都在这里，store 自己不再维护第二份列表。 */
+  private readonly queue: PriorityQueue<QueuedNotification>;
+
+  /** 入队序号，只增不减。 */
+  private seq = 0;
+
+  /** 快照缓存。useSyncExternalStore 按引用比较，每次现算会一直重渲染。 */
+  private snapshot: NotificationSnapshot;
+
+  /** 缓存的音频实例，全部通知共用一个。每条通知新建一个的话，连着来几条会同时响。 */
+  private sound: HTMLAudioElement | null = null;
+
+  /** 上次创建音频用的地址，用来判断 soundUrl 换了没有。 */
+  private soundUrl: string | undefined = undefined;
+
+  /** 解绑「队列变化 → 重建快照」这条链的函数。只在构造时接一次，destroy 时调它断开。 */
+  private readonly unsubscribeQueue: () => void;
+
+  /**
+   * 装配队列、合并默认配置、接上队列订阅。
+   *
+   * 这里一个浏览器 API 都不碰：读权限推到 syncPermission，建 Audio 推到第一次播放。 服务端渲染时 new 出来是安全的。
+   */
+  constructor(options: NotificationStoreOptions = {}) {
+    this.options = options;
+    this.config = { ...DEFAULT_NOTIFICATION_CONFIG, ...options.defaultConfig };
+
+    this.queue = new PriorityQueue<QueuedNotification>({
+      capacity: this.config.maxNotifications,
+      compare: compareNotifications,
+      getId: item => item.id
+    });
+
+    this.snapshot = this.buildSnapshot();
+    this.unsubscribeQueue = this.queue.subscribe(this.refresh);
+  }
+
+  // ==================== 订阅 ====================
+
+  /**
+   * 读当前快照。
+   *
+   * 写成箭头属性是因为 useSyncExternalStore 要求函数身份稳定，写成普通方法每次渲染取到的 都是同一个引用，但 this 会丢。
+   */
+  getSnapshot = (): NotificationSnapshot => this.snapshot;
+
+  /** 订阅快照变化，配合 getSnapshot 交给 useSyncExternalStore。 */
+  subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener);
+
+    return () => {
+      this.listeners.delete(listener);
+    };
+  };
+
+  /** 断开与队列的联系并清空订阅方。实例不再复用时调。 */
+  destroy = (): void => {
+    this.unsubscribeQueue();
+    this.queue.clear();
+    this.listeners.clear();
+  };
+
+  // ==================== 写入 ====================
+
+  /**
+   * 添加一条通知，返回它的 id。
+   *
+   * 没带 id 的会生成一个随机 id —— 那等于声明这条不参与去重，重复投递会重复展示。 要去重就把稳定 id 带进来（推送场景用服务端信封里的 msg_id）。
+   */
+  add = (input: AddNotificationInput): string => {
+    this.seq += 1;
+
+    const item: QueuedNotification = {
+      ...input,
+      id: input.id ?? nanoid(),
+      read: input.read ?? false,
+      seq: this.seq,
+      timestamp: input.timestamp ?? Date.now()
+    };
+
+    // 同 id 已经在队列里说明是重复投递（WebSocket 和 SSE 同时连着会把同一条推两遍），
+    // 静默丢掉：再播一次音、再弹一次浏览器通知就穿帮了
+    if (!this.queue.enqueue(item)) {
+      return item.id;
+    }
+
+    if (!item.silent) {
+      this.playSound();
+    }
+
+    if (item.showBrowserNotification !== false) {
+      this.showBrowserNotification(item);
+    }
+
+    return item.id;
+  };
+
+  // 下面五个只是把 type 填好后转给 add，行为和 add 完全一致。选哪个看这条通知要给用户什么
+  // 语义，type 决定的是面板里的图标和颜色。
+
+  /** 中性告知，用户不需要做任何处理（版本更新、任务已开始）。 */
+  addInfo = (title: string, content: string, options: NotificationShortcutOptions = {}): string =>
+    this.add({ ...options, content, title, type: 'info' });
+
+  /** 操作成功的回执（导出完成、审批通过）。 */
+  addSuccess = (title: string, content: string, options: NotificationShortcutOptions = {}): string =>
+    this.add({ ...options, content, title, type: 'success' });
+
+  /** 需要用户留意但没有中断流程（配额快用完、证书快到期）。 */
+  addWarning = (title: string, content: string, options: NotificationShortcutOptions = {}): string =>
+    this.add({ ...options, content, title, type: 'warning' });
+
+  /** 出错了，通常要用户重试或介入（同步失败、任务中断）。 */
+  addError = (title: string, content: string, options: NotificationShortcutOptions = {}): string =>
+    this.add({ ...options, content, title, type: 'error' });
+
+  /** 来自其他人的消息（站内信、@ 提醒），区别于上面四种由系统发出的状态通知。 */
+  addMessage = (title: string, content: string, options: NotificationShortcutOptions = {}): string =>
+    this.add({ ...options, content, title, type: 'message' });
+
+  /** 用户点开某条通知时调。已经是已读的原样返回，避免白重建一次快照、让整棵订阅树重渲染。 */
+  markAsRead = (id: string): void => {
+    this.queue.update(id, prev => (prev.read ? prev : { ...prev, read: true }));
+  };
+
+  /** 面板上「全部已读」按钮调。通知本身留着，只是 unreadCount 归零。 */
+  markAllAsRead = (): void => {
+    this.queue.updateBy(
+      item => !item.read,
+      item => ({ ...item, read: true })
+    );
+  };
+
+  /**
+   * 删掉某条通知，用户在面板上单条删除时调。
+   *
+   * 删掉之后这个 id 就不再参与去重，同 id 的通知再推进来会重新展示一次。
+   */
+  remove = (id: string): void => {
+    this.queue.remove(id);
+  };
+
+  /** 清空面板，已读未读一起删。用户点「清空」时调。 */
+  clearAll = (): void => {
+    this.queue.clear();
+  };
+
+  /** 只删已读、保留未读。用户想收拾面板又不想漏掉没看过的东西时用。 */
+  clearRead = (): void => {
+    this.queue.removeBy(item => item.read);
+  };
+
+  // ==================== 配置与权限 ====================
+
+  /**
+   * 更新运行时配置，未传入的字段保持不变。设置面板上改开关走这里。
+   *
+   * 队列容量跟着 maxNotifications 一起改，调小会立刻挤掉超出的那部分。
+   */
+  updateConfig = (updates: Partial<NotificationConfig>): void => {
+    this.config = { ...this.config, ...updates };
+    this.queue.setCapacity(this.config.maxNotifications);
+    this.refresh();
+  };
+
+  /**
+   * 替换宿主注入的选项。
+   *
+   * Provider 每次渲染拿到的回调都是新函数，这里整体换掉即可；只有用户操作才会触发这些回调， 那时最近一次渲染的选项早已同步进来。
+   */
+  setOptions = (options: NotificationStoreOptions): void => {
+    this.options = options;
+  };
+
+  /**
+   * 从浏览器读一次授权状态。
+   *
+   * 不放构造函数里：服务端渲染时读不到，客户端 hydrate 时读得到，两边对不上会报 mismatch。 交给 React 在 effect 里调。
+   */
+  syncPermission = (): void => {
+    if (typeof window === 'undefined' || !('Notification' in window)) {
+      return;
+    }
+
+    this.setPermission(window.Notification.permission);
+  };
+
+  /**
+   * 弹浏览器的授权框，返回用户最终是不是给了权限。
+   *
+   * 必须由用户手势触发（点按钮），页面一加载就调会被浏览器直接拒掉，而且拒过一次之后 再调也不会重新弹框。
+   */
+  requestPermission = async (): Promise<boolean> => {
+    if (typeof window === 'undefined' || !('Notification' in window)) {
+      this.options.onBrowserNotificationUnsupported?.();
+      return false;
+    }
+
+    try {
+      const permission = await window.Notification.requestPermission();
+      this.setPermission(permission);
+
+      return permission === 'granted';
+    } catch (error) {
+      this.options.onRequestPermissionError?.(error);
+      return false;
+    }
+  };
+
+  // ==================== 内部 ====================
+
+  /**
+   * 现算一个全新的快照对象，供 getSnapshot 缓存起来返回。
+   *
+   * 每次都返回新引用是故意的，useSyncExternalStore 靠引用变化判断要不要重渲染。 unreadCount 也在这里算好，省得每个消费组件各遍历一遍列表。
+   */
+  private buildSnapshot(): NotificationSnapshot {
+    const notifications = [...this.queue.toArray()];
+
+    return {
+      config: this.config,
+      notifications,
+      permission: this.permission,
+      unreadCount: notifications.reduce((count, item) => (item.read ? count : count + 1), 0)
+    };
+  }
+
+  /**
+   * 当前是不是在免打扰时段里。音效和浏览器通知都要先过这一关。
+   *
+   * 免打扰只静音，不拦截：通知照样进队列、照样算未读数，用户回来能在面板里看到全部。
+   */
+  private isDoNotDisturbTime(): boolean {
+    if (!this.config.doNotDisturb || !this.config.doNotDisturbTime) {
+      return false;
+    }
+
+    const { end, start } = this.config.doNotDisturbTime;
+
+    return isWithinTimeRange(getCurrentTimeText(), start, end);
+  }
+
+  /**
+   * 拿到可用的音频实例，没配 soundUrl 或环境里没有 Audio 就返回 null。
+   *
+   * 惰性创建：构造时不碰 Audio，服务端渲染才不会炸。宿主换了 soundUrl 会重新建一个。
+   */
+  private getSound(): HTMLAudioElement | null {
+    const { soundUrl } = this.options;
+
+    if (!soundUrl || typeof Audio === 'undefined') {
+      return null;
+    }
+
+    if (!this.sound || this.soundUrl !== soundUrl) {
+      this.sound = new Audio(soundUrl);
+      this.soundUrl = soundUrl;
+    }
+
+    return this.sound;
+  }
+
+  /**
+   * 播一次提示音。新通知进队列时由 add 调。
+   *
+   * 播放前把 currentTime 归零，上一条还没播完时也能重新触发。 用户还没和页面交互过时浏览器会拒绝 play，所以失败是常态而不是异常，交给宿主决定要不要提示。
+   */
+  private playSound(): void {
+    if (!this.config.soundEnabled || this.isDoNotDisturbTime()) {
+      return;
+    }
+
+    const sound = this.getSound();
+
+    if (!sound) {
+      return;
+    }
+
+    try {
+      sound.currentTime = 0;
+      sound.play().catch(error => {
+        this.options.onPlaySoundError?.(error);
+      });
+    } catch (error) {
+      this.options.onPlaySoundError?.(error);
+    }
+  }
+
+  /** 重建快照并通知所有订阅方。队列变化会自动走到这里，改配置和权限要手动调。 */
+  private refresh = (): void => {
+    this.snapshot = this.buildSnapshot();
+
+    for (const listener of this.listeners) {
+      listener();
+    }
+  };
+
+  /** 写入授权状态。值没变就早退，否则每次 syncPermission 都会白刷一遍快照。 */
+  private setPermission(permission: NotificationPermission): void {
+    if (this.permission === permission) return;
+
+    this.permission = permission;
+    this.refresh();
+  }
+
+  /**
+   * 弹一条浏览器原生通知（页面切到后台也能看到）。新通知进队列时由 add 调。
+   *
+   * 开头四道闸门任意一道不过就安静跳过，面板里那条通知不受影响。 点击后聚焦回本页；带 link 的优先交给宿主的 onNavigate 走前端路由，没注入才硬跳。
+   */
+  private showBrowserNotification(notification: NotificationItem): void {
+    if (!this.config.browserNotificationEnabled || this.isDoNotDisturbTime()) {
+      return;
+    }
+
+    if (this.permission !== 'granted') {
+      return;
+    }
+
+    if (notification.silent || notification.showBrowserNotification === false) {
+      return;
+    }
+
+    if (typeof window === 'undefined' || !('Notification' in window)) {
+      return;
+    }
+
+    try {
+      const browserNotification = new window.Notification(notification.title, {
+        body: notification.content,
+        icon: notification.icon
+      });
+
+      browserNotification.addEventListener('click', () => {
+        window.focus();
+
+        if (notification.link) {
+          if (this.options.onNavigate) {
+            this.options.onNavigate(notification.link, notification);
+          } else {
+            window.location.href = notification.link;
+          }
+        }
+
+        browserNotification.close();
+      });
+    } catch (error) {
+      this.options.onBrowserNotificationError?.(error);
+    }
+  }
+}

package/templates/admin-shell/notification/notification.css

@@ -0,0 +1,60 @@
+.admin-notification-button-unread {
+  animation: admin-notification-swing 2s ease-in-out infinite;
+  animation-delay: 0.5s;
+}
+
+@keyframes admin-notification-swing {
+  0%,
+  100% {
+    transform: rotate(0deg);
+  }
+
+  5%,
+  15% {
+    transform: rotate(15deg);
+  }
+
+  10%,
+  20% {
+    transform: rotate(-10deg);
+  }
+
+  25%,
+  35% {
+    transform: rotate(8deg);
+  }
+
+  30%,
+  40% {
+    transform: rotate(-6deg);
+  }
+
+  45% {
+    transform: rotate(4deg);
+  }
+
+  50% {
+    transform: rotate(-2deg);
+  }
+
+  55% {
+    transform: rotate(0deg);
+  }
+}
+
+.admin-notification-panel-scroll::-webkit-scrollbar {
+  width: 6px;
+}
+
+.admin-notification-panel-scroll::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+.admin-notification-panel-scroll::-webkit-scrollbar-thumb {
+  background: var(--ant-color-border);
+  border-radius: 3px;
+}
+
+.admin-notification-panel-scroll::-webkit-scrollbar-thumb:hover {
+  background: var(--ant-color-border-secondary);
+}

package/templates/admin-shell/notification/types.ts

@@ -0,0 +1,104 @@
+import type { NotificationStore } from './notification-store';
+
+/** 通知的视觉分类。 */
+export type NotificationType = 'error' | 'info' | 'message' | 'success' | 'warning';
+
+/** 通知在面板中展示的优先级。 */
+export type NotificationPriority = 'high' | 'low' | 'normal' | 'urgent';
+
+/** 由通知 Provider 管理的通知项。 */
+export interface NotificationItem {
+  /** 在通知面板中展示的主要内容。 */
+  content: string;
+  /** 浏览器原生通知使用的图标地址。 */
+  icon?: string;
+  /** 通知的稳定唯一标识。 */
+  id: string;
+  /** 点击浏览器通知后跳转的目标地址。 */
+  link?: string;
+  /** 由调用方自定义的扩展元数据。 */
+  meta?: Record<string, unknown>;
+  /** 在面板标签中展示的优先级提示。 */
+  priority?: NotificationPriority;
+  /** 当前通知是否已读。 */
+  read: boolean;
+  /** 是否同时创建浏览器原生通知。 */
+  showBrowserNotification?: boolean;
+  /** 是否跳过通知音效。 */
+  silent?: boolean;
+  /** 通知创建时间，使用毫秒时间戳。 */
+  timestamp: number;
+  /** 通知标题。 */
+  title: string;
+  /** 用于确定图标和颜色的视觉分类。 */
+  type: NotificationType;
+}
+
+/** 通知运行时配置。 */
+export interface NotificationConfig {
+  /** 是否启用浏览器原生通知。 */
+  browserNotificationEnabled: boolean;
+  /** 是否启用免打扰模式。 */
+  doNotDisturb: boolean;
+  /** 免打扰模式使用的本地时间范围。 */
+  doNotDisturbTime?: {
+    /** 结束时间，格式为 HH:mm。 */
+    end: string;
+    /** 开始时间，格式为 HH:mm。 */
+    start: string;
+  };
+  /** 最多保留的通知数量。 */
+  maxNotifications: number;
+  /** 是否启用通知音效。 */
+  soundEnabled: boolean;
+}
+
+/** 创建新通知时使用的输入类型。 */
+export type AddNotificationInput = Omit<NotificationItem, 'id' | 'read' | 'timestamp'> &
+  Partial<Pick<NotificationItem, 'id' | 'read' | 'timestamp'>>;
+
+/** 各类快捷通知创建函数共用的可选参数。 */
+export type NotificationShortcutOptions = Partial<
+  Omit<NotificationItem, 'content' | 'id' | 'read' | 'timestamp' | 'title' | 'type'>
+> &
+  Partial<Pick<NotificationItem, 'id' | 'read' | 'timestamp'>>;
+
+/** 通知仓库的构造选项，全是宿主应用要注入的东西：音效地址和各种失败回调。 */
+export interface NotificationStoreOptions {
+  /** 初始配置，会与包内默认配置合并。仅构造时生效，之后改配置走 updateConfig。 */
+  defaultConfig?: Partial<NotificationConfig>;
+  /** 浏览器通知无法显示时触发的回调。 */
+  onBrowserNotificationError?: (error: unknown) => void;
+  /** 当前浏览器不支持 Notification API 时触发的回调。 */
+  onBrowserNotificationUnsupported?: () => void;
+  /** 点击浏览器通知并需要打开链接时触发的回调。 */
+  onNavigate?: (link: string, notification: NotificationItem) => void;
+  /** 通知音效无法播放时触发的回调。 */
+  onPlaySoundError?: (error: unknown) => void;
+  /** 请求浏览器通知权限失败时触发的回调。 */
+  onRequestPermissionError?: (error: unknown) => void;
+  /** 宿主应用提供的可选通知音效地址。 */
+  soundUrl?: string;
+}
+
+/** 通知状态 Hook 使用的配置项。 */
+export interface UseNotificationOptions extends NotificationStoreOptions {
+  /**
+   * 复用外部已有的通知仓库，不传则 Hook 自己建一个。
+   *
+   * 需要在 React 树之外投递通知（WebSocket、SSE 这类连接回调）时传：宿主自己持有单例，推送 那一侧直接调 store.add，不用再绕 Context 拿 addNotification。
+   */
+  store?: NotificationStore;
+}
+
+/** UseSyncExternalStore 读到的快照，写操作时整体重建一次，读的时候直接返回缓存。 */
+export interface NotificationSnapshot {
+  /** 当前生效的运行时配置。 */
+  config: NotificationConfig;
+  /** 按优先级排好序的通知列表。 */
+  notifications: NotificationItem[];
+  /** 浏览器原生通知的授权状态。 */
+  permission: NotificationPermission;
+  /** 未读通知数量。 */
+  unreadCount: number;
+}

package/templates/admin-shell/notification/use-notification.ts

@@ -0,0 +1,51 @@
+import { useEffect, useRef, useSyncExternalStore } from 'react';
+
+import { NotificationStore } from './notification-store';
+import type { UseNotificationOptions } from './types';
+
+export { DEFAULT_NOTIFICATION_CONFIG } from './notification-store';
+
+/**
+ * 订阅通知中心。
+ *
+ * 状态和副作用全在 NotificationStore 里，这里只做三件事：拿到实例、订阅快照、把方法转出去。 方法都是实例上的箭头属性，引用天然稳定，不用再包 useCallback。
+ */
+export function useNotification(options: UseNotificationOptions = {}) {
+  const storeRef = useRef<NotificationStore | null>(null);
+
+  // 传了 store 就用外面那个：推送侧要在 React 树之外投递通知，得和这里读的是同一份
+  const store = options.store ?? (storeRef.current ??= new NotificationStore(options));
+
+  const snapshot = useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);
+
+  useEffect(() => {
+    store.syncPermission();
+  }, [store]);
+
+  // 不给依赖数组：Provider 每次渲染的回调都是新函数，每次都同步过去最省心。
+  // 只赋值不通知，多跑几次没有代价。
+  useEffect(() => {
+    store.setOptions(options);
+  });
+
+  return {
+    addErrorNotification: store.addError,
+    addInfoNotification: store.addInfo,
+    addMessageNotification: store.addMessage,
+    addNotification: store.add,
+    addSuccessNotification: store.addSuccess,
+    addWarningNotification: store.addWarning,
+    clearAllNotifications: store.clearAll,
+    clearReadNotifications: store.clearRead,
+    config: snapshot.config,
+    markAllAsRead: store.markAllAsRead,
+    markAsRead: store.markAsRead,
+    notificationPermission: snapshot.permission,
+    notifications: snapshot.notifications,
+    removeNotification: store.remove,
+    requestNotificationPermission: store.requestPermission,
+    store,
+    unreadCount: snapshot.unreadCount,
+    updateConfig: store.updateConfig
+  };
+}

package/templates/admin-shell/notification/useNotificationContext.ts

@@ -0,0 +1,14 @@
+import { useContext } from 'react';
+
+import { NotificationContext } from './NotificationContext';
+
+/** Read the current notification context. */
+export function useNotificationContext() {
+  const context = useContext(NotificationContext);
+
+  if (!context) {
+    throw new Error('useNotificationContext must be used within NotificationProvider');
+  }
+
+  return context;
+}