refactor(framework): native-bridge 内部命名现代化(外部契约保留)

外部契约逐字不变(与原生 app 零改动对接):
- handler 名白名单 14 个字符串(getVideoinfo/sharelogin/...)
- window.WVJBCallbacks / WebViewJavascriptBridgeReady 事件名
- window.settings.getothername API
- 回调签名 (data, responseCallback) 与数据结构

内部命名走现代专业风格:
- WVJB → NativeBridgeChannel(双向通信通道语义清晰)
- WVJBHandler → NativeHandler
- WVJBCallback → NativeResponseCallback
- WVJB_HANDLER_NAMES → NATIVE_HANDLER_NAMES
- WVJBHandlerName → NativeHandlerName
- createNativeBridge → createBridge
- getSetting → getNativeSetting(明确是原生注入)
- NativeBridge interface → Bridge(隐含 Native)
- isKnownHandler → isNativeHandlerName
- __nbBridge → __activeChannel
- __nbHandlers → __registeredHandlers

144/144 tests pass, typecheck exit 0。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

cocoscreator_projects/YouleNexus/assets/framework/platform/native-bridge.ts

@@ -1,45 +1,57 @@
 /**
- * 原生↔H5 异步桥(WebViewJavascriptBridge,WVJB)+ window.settings 同步取值。
+ * 原生↔H5 异步桥（WebViewJavascriptBridge,WVJB）+ window.settings 同步取值。
  *
- * 严格对齐原 gameabc 项目(05_Func.js:2627 起)的接口名、数据格式、回调约定,
- * 让原生侧零改动即可对接。
+ * 严格对齐原 gameabc 项目（05_Func.js:2627 起）的外部契约：
+ * - 14 个 handler 名白名单（与原生 app 逐字对齐）
+ * - `window.WVJBCallbacks` / `WebViewJavascriptBridgeReady` 事件名
+ * - `window.settings.getothername(name)` 同步取值 API
+ * - 回调签名 `(data, responseCallback)` 与数据结构
  *
- * 架构边界:本模块只暴露受限 facade,不允许 framework 业务代码直接读 window/bridge 内部。
+ * 内部命名（接口/函数/常量）走现代专业风格，与上述外部契约清晰隔离。
+ *
+ * 架构边界：本模块只暴露受限 facade，不允许 framework 业务代码直接读
+ * window/bridge 内部。
  */
 
-/** window 上的原生注入对象(05_Func.js:2467-2471 同步取值)。) */
+/** window 上的原生注入对象（05_Func.js:2467-2471 同步取值）。 */
 declare global {
   interface Window {
     settings?: {
-      /** 同步取一个原生配置项,无则返回空串 */
+      /** 同步取一个原生配置项，无则返回空串 */
       getothername(name: string): string;
     };
-    /** WVJB 启动前的全局回调队列 */
-    WVJBCallbacks?: Array<(bridge: WVJB) => void>;
-    /** WebView 注入 WVJB 的事件名 */
+    /** WVJB 启动前的全局回调队列（外部契约，不能改名） */
+    WVJBCallbacks?: Array<(bridge: NativeBridgeChannel) => void>;
+    /** WebView 注入 WVJB 的事件名（外部契约） */
     WebViewJavascriptBridgeReady?: Array<() => void>;
   }
 }
 
-/** WVJB bridge 实例的最小契约(只用到 framework 需要的子集) */
-export interface WVJB {
+/**
+ * 原生桥通道契约 —— WVJB bridge 实例的最小子集。
+ * 内部命名为 "Channel" 以避免缩写、明确"双向通信通道"语义。
+ */
+export interface NativeBridgeChannel {
   /** H5 注册供原生侧调用的 handler */
-  registerHandler(name: string, handler: WVJBHandler): void;
+  registerHandler(name: string, handler: NativeHandler): void;
   /** H5 主动调用原生侧 */
   callHandler(name: string, data: unknown, responseCallback?: (resp: unknown) => void): void;
 }
 
-/** handler 函数:H5 注册供原生调用时,函数返回 Promise 化值 */
-export type WVJBHandler = (data: unknown, responseCallback: WVJBCallback) => unknown;
+/** H5 注册供原生调用的 handler 函数签名（外部 WVJB 协议约定） */
+export type NativeHandler = (data: unknown, responseCallback: NativeResponseCallback) => unknown;
 
-/** 响应回调:原生侧通过此把结果回传给 H5 */
-export type WVJBCallback = (responseData: unknown) => void;
+/** 响应回调：原生侧通过此把结果回传给 H5 */
+export type NativeResponseCallback = (responseData: unknown) => void;
 
 /**
- * 13+ 已注册 handler 名白名单(05_Func.js:2651+ 原项目实装)。
- * 字面量联合类型:registerHandler/callHandler 入参必须在此集合内,否则显式抛错(第二准则:不静默吞包)。
+ * 14 个已注册 handler 名白名单（05_Func.js:2651+ 原项目实装）。
+ * 与原生 app 端逐字对齐 —— app 按这些名字调，改名 app 也要改。
+ *
+ * 字面量联合类型：registerHandler/callHandler 入参必须在此集合内，
+ * 拼写错误编译期就发现，集合外名字运行时显式抛错（第二准则：不静默兜底）。
  */
-export const WVJB_HANDLER_NAMES = [
+export const NATIVE_HANDLER_NAMES = [
   'getVideoinfo',
   'sharelogin',
   'sharesuccess',
@@ -56,83 +68,84 @@ export const WVJB_HANDLER_NAMES = [
   'shakeEnd',
 ] as const;
 
-export type WVJBHandlerName = (typeof WVJB_HANDLER_NAMES)[number];
+export type NativeHandlerName = (typeof NATIVE_HANDLER_NAMES)[number];
 
-function isKnownHandler(name: string): name is WVJBHandlerName {
-  return (WVJB_HANDLER_NAMES as readonly string[]).includes(name);
+function isNativeHandlerName(name: string): name is NativeHandlerName {
+  return (NATIVE_HANDLER_NAMES as readonly string[]).includes(name);
 }
 
-/** createNativeBridge 初始化选项 */
-export interface NativeBridgeOptions {
-  /** bridge 就绪回调 */
-  onReady(bridge: WVJB): void;
+/** createBridge 初始化选项 */
+export interface BridgeOptions {
+  /** 通道就绪回调（原生侧 WebView bridgeReady 时触发一次） */
+  onReady(channel: NativeBridgeChannel): void;
   /**
-   * bridge 初始化失败的兜底(可省略)。
-   * 原生侧可能永不触发 WebViewJavascriptBridgeReady,业务可能想超时降级。
+   * 初始化超时的兜底（可省略）。
+   * 原生侧可能永不触发 WebViewJavascriptBridgeReady，业务可在此降级。
    */
   onTimeout?(reason: string): void;
 }
 
 /**
- * 受限 NativeBridge facade。
+ * 受限 Bridge facade —— 框架业务访问原生能力的唯一入口。
  *
- * 创建后立即尝试初始化:
- * 1. 若 window.WVJBCallbacks 已存在 → push 入队(Cocos/原生侧约定的初始化入口)
- * 2. 否则保留空方法,业务侧可调用 isReady() 查询状态
+ * 创建后立即尝试初始化：
+ * 1. 把 setup 回调 push 到 window.WVJBCallbacks（原生侧约定的入口）
+ * 2. 原生侧 WebView bridgeReady 时遍历 WVJBCallbacks 调用每个 cb → onReady 被触发
  *
- * 一旦 bridge 就绪,onReady 被调用一次。
+ * 一旦通道就绪，onReady 被调用一次。
  */
-export interface NativeBridge {
-  /** 当前是否已就绪 */
+export interface Bridge {
+  /** 当前通道是否已就绪 */
   isReady(): boolean;
-  /** H5 注册供原生侧调用(白名单校验) */
-  registerHandler(name: WVJBHandlerName, handler: WVJBHandler): void;
-  /** H5 调用原生侧(白名单校验) */
-  callHandler(name: WVJBHandlerName, data: unknown, cb?: WVJBCallback): void;
+  /** H5 注册供原生侧调用（白名单校验） */
+  registerHandler(name: NativeHandlerName, handler: NativeHandler): void;
+  /** H5 调用原生侧（白名单校验） */
+  callHandler(name: NativeHandlerName, data: unknown, cb?: NativeResponseCallback): void;
 }
 
-export function createNativeBridge(opts: NativeBridgeOptions): NativeBridge {
+export function createBridge(opts: BridgeOptions): Bridge {
   const g = globalThis as any;
-  // 原生侧约定的初始化入口:把 setup cb push 到 window.WVJBCallbacks
+  // 外部契约：把 setup cb push 到 window.WVJBCallbacks
   if (!g.WVJBCallbacks) g.WVJBCallbacks = [];
   let ready = false;
-  g.WVJBCallbacks.push((bridge: WVJB) => {
+  g.WVJBCallbacks.push((channel: NativeBridgeChannel) => {
     ready = true;
-    // 存到 globalThis 供 callHandler 委托
-    g.__nbBridge = bridge;
-    opts.onReady(bridge);
+    // 缓存通道供 callHandler 委托（避免 onReady 闭包外传）
+    g.__activeChannel = channel;
+    opts.onReady(channel);
   });
 
   return {
     isReady() { return ready; },
     registerHandler(name, handler) {
-      if (!isKnownHandler(name)) {
-        throw new Error(`registerHandler: handler "${name}" 不在白名单(第二准则:不静默兜底)`);
+      if (!isNativeHandlerName(name)) {
+        throw new Error(`registerHandler: handler "${name}" 不在白名单（第二准则：不静默兜底）`);
       }
-      if (!ready) throw new Error('NativeBridge not ready: bridge 未初始化');
-      g.__nbBridge.registerHandler(name, handler);
+      if (!ready) throw new Error('NativeBridge not ready: 通道未初始化，请先等 onReady 回调');
+      g.__activeChannel.registerHandler(name, handler);
     },
     callHandler(name, data, cb) {
-      if (!isKnownHandler(name)) {
-        throw new Error(`callHandler: handler "${name}" 不在白名单(第二准则:不静默兜底)`);
+      if (!isNativeHandlerName(name)) {
+        throw new Error(`callHandler: handler "${name}" 不在白名单（第二准则：不静默兜底）`);
       }
-      if (!ready) throw new Error('NativeBridge not ready: bridge 未初始化');
-      g.__nbBridge.callHandler(name, data, cb);
+      if (!ready) throw new Error('NativeBridge not ready: 通道未初始化，请先等 onReady 回调');
+      g.__activeChannel.callHandler(name, data, cb);
     },
   };
 }
 
 /**
- * 从 window 取原生注入的配置项(05_Func.js:2467-2471 的 getothername)。
+ * 从 window 取原生注入的配置项（05_Func.js:2467-2471 的 getothername）。
  *
- * @param name 配置项名(渠道/包信息/gameserver 覆盖等)
- * @returns 原生侧返回值;缺失时返回空串(对齐原项目:无则空字符串而非 undefined)
+ * @param name 配置项名（渠道/包信息/gameserver 覆盖等）
+ * @returns 原生侧返回值；缺失时返回空串（对齐原项目：无则空字符串而非 undefined）
+ * @throws 原生侧未注入 window.settings 时显式抛错（不静默返回空串——避免下游误用）
  */
-export function getSetting(name: string): string {
+export function getNativeSetting(name: string): string {
   const settings = (globalThis as any).window?.settings;
   if (!settings || typeof settings.getothername !== 'function') {
     throw new Error(
-      `getSetting("${name}"): window.settings 未注入(原生侧未加载或非 WebView 环境)`,
+      `getNativeSetting("${name}"): window.settings 未注入（原生侧未加载或非 WebView 环境）`,
     );
   }
   return settings.getothername(name);