@miot-rn/common-component 1.0.3 → 1.0.4

package/dist/service/specs/index.js

@@ -19,10 +19,11 @@ import { Device } from 'miot';
 import Subject from "./subject";
 import { getEventGenerator } from "./utils";
 import { encodeProp } from "../../utils/spec";
-import { OK, PLUGIN_NULL_ERROR } from "./error-code";
+import { OK, PLUGIN_NULL_ERROR, PROP_NOT_FOUND } from "./error-code";
 import * as spec from "./spec";
 import specCache, { CACHE_SOURCE } from "./specCache";
 import { copy } from "../../utils/objects";
+import { reportSubLog } from "../../utils/subscribe-log";
 // 事件主题 management
 const specSubject = new Subject(getEventGenerator('spec_subject', encodeProp));
 export { CACHE_SOURCE };
@@ -38,6 +39,29 @@ export function isCacheEnabled() {
 
 // Type definitions
 
+/**
+ * 对齐 native 层返回的结果数组。
+ *
+ * native 层在遇到未识别的 siid/piid 时可能整体丢弃返回项，导致返回数组比入参数组短，
+ * 或对应位置为 undefined。这里按 props 长度做对齐，未命中位置补 PROP_NOT_FOUND 占位，
+ * 避免上层 `results.forEach(r => r.code)` 抛 TypeError。
+ */
+function alignResultsToProps(props, rawResults) {
+  const arr = Array.isArray(rawResults) ? rawResults : [];
+  return props.map((p, i) => {
+    const r = arr[i];
+    if (r && typeof r === 'object') {
+      return r;
+    }
+    return {
+      siid: p.siid,
+      piid: p.piid,
+      code: PROP_NOT_FOUND,
+      message: 'native returned no result'
+    };
+  });
+}
+
 /**
  * 读取属性值
  *
@@ -108,43 +132,31 @@ export function getProps(props, options = {}) {
 
   // 从源获取数据并更新缓存
   const fetchFromSourceAndUpdateCache = cachedData => {
-    // 如果强制刷新或缓存未命中，从源获取
-    if (forceRefresh || !cachedData || !useCache) {
-      return spec.getProps(props).then(results => {
-        // 更新缓存
-        return ensureCache().then(() => {
-          results.forEach(result => {
-            if (result.code === OK && result.value !== undefined) {
-              const key = specCache.getCacheKey(result);
-              specCache.put(key, result.value, result.updateTime || Math.floor(Date.now() / 1000), CACHE_SOURCE.GET);
-            }
-          });
-          return results.map(r => ({
-            ...r,
-            specDataSource: r.specDataSource || CACHE_SOURCE.GET
-          }));
+    const runFetch = () => spec.getProps(props).then(rawResults => {
+      // 与入参对齐，缺失位置补 PROP_NOT_FOUND 占位，避免 undefined 传导到上层
+      const results = alignResultsToProps(props, rawResults);
+      return ensureCache().then(() => {
+        results.forEach(result => {
+          if (result && result.code === OK && result.value !== undefined) {
+            const key = specCache.getCacheKey(result);
+            specCache.put(key, result.value, result.updateTime || Math.floor(Date.now() / 1000), CACHE_SOURCE.GET);
+          }
         });
+        return results.map(r => ({
+          ...r,
+          specDataSource: r.specDataSource || CACHE_SOURCE.GET
+        }));
       });
+    });
+
+    // 如果强制刷新或缓存未命中，从源获取
+    if (forceRefresh || !cachedData || !useCache) {
+      return runFetch();
     }
 
     // 如果缓存中有数据，且fromSourceIfNeed为true，仍然从源获取并更新
     if (fromSourceIfNeed && cachedData) {
-      return spec.getProps(props).then(results => {
-        // 更新缓存
-        return ensureCache().then(() => {
-          results.forEach(result => {
-            if (result.code === OK && result.value !== undefined) {
-              const key = specCache.getCacheKey(result);
-              specCache.put(key, result.value, result.updateTime || Math.floor(Date.now() / 1000), CACHE_SOURCE.GET);
-            }
-          });
-          // 返回设备最新数据，缓存仅作为提前通知使用
-          return results.map(r => ({
-            ...r,
-            specDataSource: r.specDataSource || CACHE_SOURCE.GET
-          }));
-        });
-      });
+      return runFetch();
     }
 
     // 直接返回缓存数据
@@ -338,6 +350,10 @@ export function subscribe(props, listener, options = {}) {
     // 受全局开关控制
     updateCache = cacheEnabled // 受全局开关控制
   } = options;
+  const subT0 = Date.now();
+  const subStage = (name, extra = '') => {
+    reportSubLog(`[SPEC-SUB][specs.subscribe][${name}][${new Date().toISOString()}] propCount=${props.length}, cost=${Date.now() - subT0}ms, publishImmediately=${publishImmediately}${extra}`);
+  };
 
   // 确保缓存已初始化
   const ensureCache = () => {
@@ -347,9 +363,12 @@ export function subscribe(props, listener, options = {}) {
   // 如果需要立即发布当前值，从缓存读取并通知
   const publishFromCache = () => {
     if (!publishImmediately) {
+      subStage('cache-skip');
       return Promise.resolve();
     }
+    subStage('cache-init-enter');
     return ensureCache().then(() => {
+      subStage('cache-init-done');
       // 从缓存读取并通知
       props.forEach(prop => {
         const key = specCache.getCacheKey(prop);
@@ -391,21 +410,33 @@ export function subscribe(props, listener, options = {}) {
 
   // 执行订阅
   const executeSubscribe = () => {
+    subStage('exec-subscribe-enter');
     return spec.subscribe(props, wrappedListener);
   };
 
+  // 看门狗：整条链路若长时间不 settle（例如 specCache.init / Host.storage.get 一直 pending），
+  // 成功和失败两个分支都不会执行，日志表现为彻底静默。这里用超时把"卡住"这种状态显式打出来。
+  const stuckTimer = setTimeout(() => {
+    subStage('STUCK', ', 订阅流程超过 8s 未完成，疑似 specCache.init/Host.storage.get 未 settle');
+  }, 8000);
+
   // 执行流程
   return publishFromCache().then(() => executeSubscribe()).then(result => {
+    clearTimeout(stuckTimer);
+    subStage('success', `, subscribedPropCount=${result?.props?.length}`);
     // 返回订阅对象，包含取消订阅方法
     return {
       props: result.props,
       unsubscribe: () => {
+        reportSubLog(`[SPEC-SUB][specs.unsubscribe][${new Date().toISOString()}] 取消订阅, propCount=${props.length}`);
         if (result && result.unsubscribe) {
           result.unsubscribe();
         }
       }
     };
   }).catch(e => {
+    clearTimeout(stuckTimer);
+    subStage('fail', `, code=${e?.code}, message=${e?.message}, raw=${JSON.stringify(e)}`);
     console.log('subscribe error:', props, e);
     return Promise.reject(e);
   });

package/dist/service/specs/spec.js

@@ -18,6 +18,7 @@ import { reduceResults } from "./utils";
 import { isSuccess } from "./error-code";
 // 引入std-spec
 import * as stdSpec from "./std-spec";
+import { reportSubLog } from "../../utils/subscribe-log";
 export const ServiceSourceType = {
   WIFI: 1,
   BLE: 2,
@@ -91,9 +92,14 @@ export function subscribe(props, listener) {
   const specSubscribeProps = current(props);
   const ps = specs.map((spec, index) => spec.subscribe(specSubscribeProps[index], listener));
   return Promise.all(ps).then(arr => {
+    // arr[0].props 为 undefined 说明底层订阅走了失败分支（被 mapError 转成了 resolve）
+    if (!arr[0] || !arr[0].props) {
+      reportSubLog(`[SPEC-SUB][spec.subscribe][fail][${new Date().toISOString()}] 底层返回结构异常, propCount=${props.length}, raw=${JSON.stringify(arr[0])}`);
+    }
     const result = {
       props: arr[0].props,
       unsubscribe: () => {
+        reportSubLog(`[SPEC-SUB][spec.unsubscribe][${new Date().toISOString()}] 取消订阅, subCount=${arr.length}, propCount=${props.length}`);
         subscriptions.delete(result);
         arr.forEach(sub => {
           if (sub && sub.unsubscribe) {

package/dist/service/specs/std-spec.js

@@ -3,6 +3,7 @@ import Subject from "./subject";
 import { genError, getEventGenerator, mapError } from "./utils";
 import { isTypeOf } from "../../utils/types";
 import { encodeProp, decodeProp, specsToSubscribeKeys, specAccess } from "../../utils/spec";
+import { reportSubLog } from "../../utils/subscribe-log";
 import { OK } from "./error-code";
 const specSubject = new Subject(getEventGenerator('std_spec_subject', encodeProp));
 let receivedMessagesSubscription = null;
@@ -209,6 +210,8 @@ export function subscribe(props, listener) {
   }
   props = fillInfo(props);
   const keys = specsToSubscribeKeys(props);
+  const t0 = Date.now();
+  reportSubLog(`[SPEC-SUB][std-spec.subscribe][enter][${new Date().toISOString()}] 即将调用原生 listenMessages, keyCount=${keys.length}, keys=${JSON.stringify(keys)}`);
   // return Device.getDeviceWifi().subscribeMessages(...keys).then(() => {
   return Device.getDeviceWifi().listenMessages(...keys).then(() => {
     const subscription = specSubject.subscribe(props, listener);
@@ -218,11 +221,17 @@ export function subscribe(props, listener) {
         code: OK
       };
     });
+    reportSubLog(`[SPEC-SUB][std-spec.subscribe][success][${new Date().toISOString()}] 原生 listenMessages 成功, cost=${Date.now() - t0}ms, keyCount=${keys.length}`);
     return {
       props: subscribed,
       unsubscribe: () => {
+        reportSubLog(`[SPEC-SUB][std-spec.unsubscribe][${new Date().toISOString()}] 取消本地监听, keyCount=${keys.length}, keys=${JSON.stringify(keys)}`);
         subscription && subscription.unsubscribe && subscription.unsubscribe();
       }
     };
-  }).catch(mapError(props));
+  }).catch(e => {
+    // 注意：这里沿用 mapError 的既有行为（返回值而非 rethrow，Promise 仍会 resolve），仅补充失败日志
+    reportSubLog(`[SPEC-SUB][std-spec.subscribe][fail][${new Date().toISOString()}] 原生 listenMessages 失败, cost=${Date.now() - t0}ms, keyCount=${keys.length}, code=${e?.code}, message=${e?.message}, raw=${JSON.stringify(e)}`);
+    return mapError(props)(e);
+  });
 }

package/dist/service/specs/subscribe-logging.test.d.ts

@@ -0,0 +1,17 @@
+declare let mockListenMessagesImpl: (...keys: string[]) => Promise<any>;
+declare let mockStorageGetImpl: (key: string) => Promise<any>;
+declare const mockListenMessagesCalls: string[][];
+declare const mockReportLogCalls: Array<{
+    model: string;
+    line: string;
+}>;
+declare const SPECS: {
+    siid: number;
+    piid: number;
+    access: string[];
+}[];
+declare let logs: string[];
+declare const collect: (...args: unknown[]) => void;
+declare const specSubLogs: (stage: string) => string[];
+declare const isDoubleWritten: (line: string) => boolean;
+declare const expectAllSpecSubReported: () => void;

package/dist/service/specs/subscribe-logging.test.js

@@ -0,0 +1,217 @@
+/// <reference types="jest" />
+
+/**
+ * 复现 spec 订阅的两类静默失败，并验证 [SPEC-SUB] 日志能把它们打出来
+ *
+ * 1. listenMessages 失败：被 std-spec 的 mapError 转成 resolve，上层看到的是"假成功"
+ * 2. Host.storage.get 不 settle：publishFromCache 永不完成，listenMessages 根本不会被调用
+ *    （对应线上 6 次进插件里 2 次原生零 manageSub 的现象）
+ *
+ * 注：变量必须带 mock 前缀，否则 jest.mock 的 factory 不允许引用。
+ */
+
+/* 每个用例都要 resetModules 后拿到全新的模块实例（模块级 cacheEnabled / receivedMessagesSubscription
+   都是单例状态），因此必须用惰性 require 而非顶层 import。 */
+/* eslint-disable global-require, @typescript-eslint/no-var-requires */
+
+let mockListenMessagesImpl = () => Promise.resolve();
+let mockStorageGetImpl = () => Promise.resolve({});
+const mockListenMessagesCalls = [];
+/* 反馈日志上报的入参记录：console 只有连着调试工具才看得见，
+   订阅链路必须同时落到 reportLog 才能被测试同学上传回来。 */
+const mockReportLogCalls = [];
+jest.mock('miot', () => ({
+  Device: {
+    deviceID: 'test-did',
+    model: 'micar.car.kunlun',
+    getDeviceWifi: () => ({
+      listenMessages: (...keys) => {
+        mockListenMessagesCalls.push(keys);
+        return mockListenMessagesImpl(...keys);
+      }
+    })
+  },
+  DeviceEvent: {
+    deviceReceivedMessages: {
+      addListener: () => ({
+        remove: () => {}
+      })
+    }
+  },
+  // specCache 在模块加载期就读 Service.account.ID 拼 STORAGE_KEY，必须提供
+  Service: {
+    account: {
+      ID: 'test-account'
+    },
+    smarthome: {
+      reportLog: (model, line) => {
+        mockReportLogCalls.push({
+          model,
+          line
+        });
+      }
+    }
+  },
+  Host: {
+    storage: {
+      get: key => mockStorageGetImpl(key),
+      set: () => Promise.resolve()
+    }
+  }
+}), {
+  virtual: true
+});
+const SPECS = [{
+  siid: 6,
+  piid: 1,
+  access: ['read', 'notify']
+}, {
+  siid: 6,
+  piid: 8,
+  access: ['read', 'notify']
+}];
+let logs = [];
+const collect = (...args) => {
+  logs.push(args.map(a => typeof a === 'string' ? a : JSON.stringify(a)).join(' '));
+};
+const specSubLogs = stage => logs.filter(l => l.includes('[SPEC-SUB]') && l.includes(stage));
+
+/* reportSubLog 自身的降级提示是 console-only 的，不参与双写校验 */
+const isDoubleWritten = line => line.includes('[SPEC-SUB]') && !line.includes('[reportSubLog]');
+
+/**
+ * 断言订阅链路日志确实双写到了反馈日志。
+ *
+ * console 只有连着调试工具才看得见，测试同学复现后捞不到；只有 reportLog 才会落到
+ * 可上传的反馈日志里。这里不逐个枚举阶段名，而是校验"凡是打到 console 的
+ * [SPEC-SUB] 都必须同时出现在 reportLog 中"——将来新增日志点若漏接 reportSubLog，
+ * 会直接被这条断言拦住。
+ */
+const expectAllSpecSubReported = () => {
+  const consoleLines = logs.filter(isDoubleWritten);
+  const reportedLines = mockReportLogCalls.map(c => c.line);
+  expect(consoleLines.length).toBeGreaterThan(0);
+  consoleLines.forEach(line => expect(reportedLines).toContain(line));
+  // 反馈日志里的 model 必须是设备 model，否则日志归不到设备上
+  mockReportLogCalls.forEach(c => expect(c.model).toBe('micar.car.kunlun'));
+};
+beforeEach(() => {
+  jest.resetModules();
+  logs = [];
+  mockListenMessagesCalls.length = 0;
+  mockReportLogCalls.length = 0;
+  mockListenMessagesImpl = () => Promise.resolve();
+  mockStorageGetImpl = () => Promise.resolve({});
+  jest.spyOn(console, 'log').mockImplementation(collect);
+  jest.spyOn(console, 'error').mockImplementation(collect);
+  jest.spyOn(console, 'warn').mockImplementation(() => {});
+});
+afterEach(() => {
+  jest.restoreAllMocks();
+  jest.useRealTimers();
+});
+describe('订阅成功路径', () => {
+  it('打出 cache-init / listenMessages / success 全链路日志，取消订阅也有日志', async () => {
+    const {
+      subscribe
+    } = require("./index");
+    const result = await subscribe(SPECS, () => {}, {
+      publishImmediately: true
+    });
+
+    // 原生确实被调到，且两个 notify 属性都进了订阅 key
+    expect(mockListenMessagesCalls).toHaveLength(1);
+    expect(mockListenMessagesCalls[0]).toHaveLength(2);
+    expect(mockListenMessagesCalls[0].every(k => k.startsWith('prop.'))).toBe(true);
+    expect(specSubLogs('[cache-init-enter]')).toHaveLength(1);
+    expect(specSubLogs('[cache-init-done]')).toHaveLength(1);
+    expect(specSubLogs('[exec-subscribe-enter]')).toHaveLength(1);
+    expect(specSubLogs('[std-spec.subscribe][enter]')).toHaveLength(1);
+    expect(specSubLogs('[std-spec.subscribe][success]')).toHaveLength(1);
+    expect(specSubLogs('[specs.subscribe][success]')).toHaveLength(1);
+    // 成功路径不应出现任何 fail
+    expect(specSubLogs('[fail]')).toHaveLength(0);
+
+    // 订阅链路的日志必须同时进反馈日志，否则测试同学复现后捞不到
+    expectAllSpecSubReported();
+
+    // 取消订阅：三层各一条
+    logs = [];
+    result.unsubscribe();
+    expect(specSubLogs('[specs.unsubscribe]')).toHaveLength(1);
+    expect(specSubLogs('[spec.unsubscribe]')).toHaveLength(1);
+    expect(specSubLogs('[std-spec.unsubscribe]')).toHaveLength(1);
+
+    // 取消订阅这三条同样要能被上传回来
+    expectAllSpecSubReported();
+  });
+});
+describe('失败形态 1：listenMessages 失败被 mapError 吞掉', () => {
+  it('Promise 仍 resolve 成"假成功"，但 fail 日志已能定位', async () => {
+    mockListenMessagesImpl = () => Promise.reject(Object.assign(new Error('listen timeout'), {
+      code: -70012
+    }));
+    const {
+      subscribe
+    } = require("./index");
+    const result = await subscribe(SPECS, () => {}, {
+      publishImmediately: true
+    });
+
+    // 复现核心：整条链路没有 reject，调用方拿到的是"成功"
+    expect(result).toBeDefined();
+    expect(result.props).toBeUndefined(); // 结构已损坏——真正的证据
+
+    // 新日志把失败点钉在 std-spec，并在 spec 层标出结构异常
+    const stdFail = specSubLogs('[std-spec.subscribe][fail]');
+    expect(stdFail).toHaveLength(1);
+    expect(stdFail[0]).toContain('code=-70012');
+    expect(stdFail[0]).toContain('listen timeout');
+    expect(specSubLogs('[spec.subscribe][fail]')).toHaveLength(1);
+
+    // index 层仍误报 success（既有行为，日志里 subscribedPropCount=undefined 可辨识）
+    const idxSuccess = specSubLogs('[specs.subscribe][success]');
+    expect(idxSuccess).toHaveLength(1);
+    expect(idxSuccess[0]).toContain('subscribedPropCount=undefined');
+
+    // 失败分支尤其要能上传回来——这是定位「偶现收不到推送」的唯一现场
+    expectAllSpecSubReported();
+    expect(mockReportLogCalls.map(c => c.line).join('\n')).toContain('[std-spec.subscribe][fail]');
+  });
+});
+describe('失败形态 2：Host.storage.get 不 settle', () => {
+  it('listenMessages 永不调用，STUCK 看门狗把静默卡死打出来', async () => {
+    jest.useFakeTimers();
+    mockStorageGetImpl = () => new Promise(() => {}); // 永不 settle
+
+    const {
+      subscribe
+    } = require("./index");
+    let settled = false;
+    subscribe(SPECS, () => {}, {
+      publishImmediately: true
+    }).then(() => {
+      settled = true;
+    }, () => {
+      settled = true;
+    });
+    await Promise.resolve();
+    jest.advanceTimersByTime(8000);
+
+    // 复现线上现象：原生零调用、Promise 不 settle、成功和失败分支都不执行
+    expect(mockListenMessagesCalls).toHaveLength(0);
+    expect(settled).toBe(false);
+    expect(specSubLogs('[specs.subscribe][success]')).toHaveLength(0);
+    expect(specSubLogs('[specs.subscribe][fail]')).toHaveLength(0);
+
+    // 唯一能说明问题的就是看门狗
+    const stuck = specSubLogs('[STUCK]');
+    expect(stuck).toHaveLength(1);
+    expect(stuck[0]).toContain('specCache.init/Host.storage.get');
+
+    // 卡在 cache-init，没有进到 exec-subscribe
+    expect(specSubLogs('[cache-init-enter]')).toHaveLength(1);
+    expect(specSubLogs('[cache-init-done]')).toHaveLength(0);
+    expect(specSubLogs('[exec-subscribe-enter]')).toHaveLength(0);
+  });
+});

package/dist/service/track/TrackFlatList.d.ts

@@ -0,0 +1,3 @@
+import React from 'react';
+import { FlatListProps } from 'react-native';
+export declare function TrackFlatList<ItemT>(props: FlatListProps<ItemT>): React.JSX.Element;

package/dist/service/track/TrackFlatList.js

@@ -0,0 +1,19 @@
+function _extends() { return _extends = Object.assign ? Object.assign.bind() : function (n) { for (var e = 1; e < arguments.length; e++) { var t = arguments[e]; for (var r in t) ({}).hasOwnProperty.call(t, r) && (n[r] = t[r]); } return n; }, _extends.apply(null, arguments); }
+import React from 'react';
+import { FlatList } from 'react-native';
+import { useTrackScrollProvider } from "./useTrackScrollProvider";
+
+/**
+ * RN FlatList 的 ergonomic wrapper：内部建立 TrackScrollContext。
+ *
+ * 后续可改用官方 onViewableItemsChanged + viewabilityConfig，绕过 measureInWindow，
+ * 性能更好；本期先走统一路径降低复杂度。
+ */
+export function TrackFlatList(props) {
+  const tracker = useTrackScrollProvider({
+    onScroll: props.onScroll,
+    onLayout: props.onLayout,
+    onMomentumScrollEnd: props.onMomentumScrollEnd
+  });
+  return /*#__PURE__*/React.createElement(tracker.Provider, null, /*#__PURE__*/React.createElement(FlatList, _extends({}, props, tracker.scrollProps)));
+}

package/dist/service/track/TrackScrollContext.d.ts

@@ -0,0 +1,10 @@
+import { RefObject } from 'react';
+export type ScrollListener = () => void;
+export interface MeasurableNode {
+    measureInWindow: (cb: (x: number, y: number, width: number, height: number) => void) => void;
+}
+export interface TrackScrollContextValue {
+    containerRef: RefObject<MeasurableNode | null>;
+    subscribe: (cb: ScrollListener) => () => void;
+}
+export declare const TrackScrollContext: import("react").Context<TrackScrollContextValue | null>;

package/dist/service/track/TrackScrollContext.js

@@ -0,0 +1,2 @@
+import { createContext } from 'react';
+export const TrackScrollContext = /*#__PURE__*/createContext(null);

package/dist/service/track/TrackScrollView.d.ts

@@ -0,0 +1,3 @@
+import React from 'react';
+import { ScrollViewProps } from 'react-native';
+export declare function TrackScrollView(props: ScrollViewProps): React.JSX.Element;

package/dist/service/track/TrackScrollView.js

@@ -0,0 +1,20 @@
+function _extends() { return _extends = Object.assign ? Object.assign.bind() : function (n) { for (var e = 1; e < arguments.length; e++) { var t = arguments[e]; for (var r in t) ({}).hasOwnProperty.call(t, r) && (n[r] = t[r]); } return n; }, _extends.apply(null, arguments); }
+import React from 'react';
+import { ScrollView } from 'react-native';
+import { useTrackScrollProvider } from "./useTrackScrollProvider";
+
+/**
+ * 直接消费 RN ScrollView 的 ergonomic wrapper：内部建立 TrackScrollContext，
+ * 业务用法与原生 <ScrollView> 完全一致。
+ *
+ * 包装层 / SDK 容器（SubpageLayout / PageLayout）不要用本组件——
+ * 改用 useTrackScrollProvider 取 scrollProps，把 ref/onScroll 透传到容器暴露的接缝。
+ */
+export function TrackScrollView(props) {
+  const tracker = useTrackScrollProvider({
+    onScroll: props.onScroll,
+    onLayout: props.onLayout,
+    onMomentumScrollEnd: props.onMomentumScrollEnd
+  });
+  return /*#__PURE__*/React.createElement(tracker.Provider, null, /*#__PURE__*/React.createElement(ScrollView, _extends({}, props, tracker.scrollProps)));
+}

package/dist/service/track/TrackService.d.ts

@@ -0,0 +1,10 @@
+import type { TrackEventType, TrackParams, TrackServiceConfig } from './types';
+export declare function initTrackService(config: TrackServiceConfig): void;
+export declare function getCommonParams(): Record<string, unknown>;
+export declare function setPageRef(ref: string, subRef?: string): void;
+export declare function reportTrack(eventTypes: TrackEventType[], params?: TrackParams): void;
+export declare function getTrackLog(): {
+    time: number;
+    event: string;
+    params: Record<string, unknown>;
+}[];

package/dist/service/track/TrackService.js

@@ -0,0 +1,104 @@
+import { Service } from 'miot';
+import { Platform } from 'react-native';
+let _config = null;
+let _currentRef = '';
+let _currentSubRef = '';
+const _debugLog = [];
+
+/** 初始化，插件入口调用一次 */
+export function initTrackService(config) {
+  _config = config;
+}
+
+/**
+ * 读取已注册的埋点公参。
+ *
+ * 给自带上报通道的第三方组件用（如 miot/ui/smartScene 的 trackParams）：那些组件不经过本文件的
+ * reportTrack，公参必须由调用方拼进它们的载荷，从这里取可保证与 reportTrack 同一来源、不会漂移。
+ * 未 init 时返回空对象，调用方无需判空。
+ */
+export function getCommonParams() {
+  return _config ? _config.getCommonParams() : {};
+}
+
+/**
+ * 设置当前页面 ref（同步到 Native），并驱动 Android 的页面 view。
+ *
+ * 双端差异（与已上线的 stdcamera / 门铃 / miot.plugin.spec 完全一致）：
+ *   - Android：页面 view 由 Native「内部 view 机制」自主产出、SDK 计算 duration，只依赖插件
+ *     通过 updatePluginPageRef 设置的 ref/subRef，且**必须携带插件公参**
+ *     (package_name/package_id/plugin_id/plugin_version/did/device_model...)，否则 Native
+ *     不知道当前是哪个插件页、无法产出该页 view。只要每次进入/切换页面都用带公参的
+ *     updatePluginPageRef 设置新 ref，Native 就会在下一次 ref 变化（或插件退出）时结算并上报
+ *     上一页的 view（含 from_ref 来源链）。
+ *   - iOS：不依赖公参，view 由 reportTrack 显式经 reportEventRefChannel('view') 上报。
+ *
+ * 同值去重：Native 端每次调用都会把 old current_ref 当作下一条事件的 from_ref，同 (ref,subRef)
+ * 重复调用会让 from_ref 串档为自己。这里在 JS 侧短路。
+ */
+export function setPageRef(ref, subRef) {
+  const sub = subRef || ref;
+  if (ref === _currentRef && sub === _currentSubRef) {
+    return;
+  }
+  _currentRef = ref;
+  _currentSubRef = sub;
+  // Native updatePluginPageRef 的 JSDoc 要求 key 为 ref / subRef(驼峰)；同时带 sub_ref(下划线)
+  // 兼容事件 schema。
+  // Android 的页面 view 由 Native 依据这里的 refParams 自主产出（见下文平台差异说明），
+  // 必须把 item_type 一并塞进来，否则 Native 生成的 view 事件缺 item_type（MIIO-130722）。
+  const refParams = {
+    ref,
+    subRef: sub,
+    sub_ref: sub,
+    item_type: 'ref'
+  };
+  // Android 的 view 机制强依赖此处携带的插件公参（见上方说明）；iOS 无需。
+  if (Platform.OS === 'android' && _config) {
+    Object.assign(refParams, _config.getCommonParams());
+  }
+  Service.smarthome.updatePluginPageRef?.(refParams);
+}
+
+/**
+ * 核心上报方法
+ * 底层 SDK reportEventRefChannel 接受单个事件类型，
+ * 遍历 eventTypes 逐个上报，确保每条事件独立发送。
+ */
+export function reportTrack(eventTypes, params = {}) {
+  if (!_config) return;
+  const finalParams = {
+    ref: _currentRef,
+    sub_ref: _currentSubRef,
+    ..._config.getCommonParams(),
+    ...params
+  };
+  for (const eventType of eventTypes) {
+    if (_config.debug) {
+      // eslint-disable-next-line no-console
+      console.log('[Track]', eventType, finalParams);
+      _debugLog.push({
+        time: Date.now(),
+        event: eventType,
+        params: {
+          ...finalParams
+        }
+      });
+      if (_debugLog.length > 200) _debugLog.shift();
+    }
+    // 页面 view 的双端差异（与 stdcamera / 门铃 / miot.plugin.spec 一致）：
+    //   - Android：view 由 Native 内部机制依据 updatePluginPageRef(带公参) 自主产出、SDK 计算
+    //     duration，**不能**经 reportEventRefChannel(平台侧不消费、且会与内部机制冲突)。此处跳过——
+    //     Android view 已由 setPageRef 在每次页面切换时驱动。
+    //   - iOS：view 必须显式经 reportEventRefChannel('view') 上报，SDK 使用 JS 计算的 duration。
+    if (eventType === 'view' && Platform.OS === 'android') {
+      continue;
+    }
+    Service.smarthome.reportEventRefChannel?.(eventType, finalParams);
+  }
+}
+
+/** 调试用：获取最近上报记录 */
+export function getTrackLog() {
+  return _debugLog;
+}

package/dist/service/track/index.d.ts

@@ -0,0 +1,12 @@
+export { initTrackService, setPageRef, reportTrack, getTrackLog, getCommonParams } from './TrackService';
+export { usePageTrack } from './usePageTrack';
+export { useCardTrack } from './useCardTrack';
+export { useTrack } from './useTrack';
+export { useExposeOnVisible } from './useExposeOnVisible';
+export { TrackScrollView } from './TrackScrollView';
+export { TrackFlatList } from './TrackFlatList';
+export { useTrackScrollProvider } from './useTrackScrollProvider';
+export { TrackScrollContext } from './TrackScrollContext';
+export type { TrackScrollContextValue, ScrollListener, MeasurableNode } from './TrackScrollContext';
+export type { TrackEventType, TrackItemType, TrackParams, TrackServiceConfig } from './types';
+export type { Frame } from './intersect';

package/dist/service/track/index.js

@@ -0,0 +1,9 @@
+export { initTrackService, setPageRef, reportTrack, getTrackLog, getCommonParams } from "./TrackService";
+export { usePageTrack } from "./usePageTrack";
+export { useCardTrack } from "./useCardTrack";
+export { useTrack } from "./useTrack";
+export { useExposeOnVisible } from "./useExposeOnVisible";
+export { TrackScrollView } from "./TrackScrollView";
+export { TrackFlatList } from "./TrackFlatList";
+export { useTrackScrollProvider } from "./useTrackScrollProvider";
+export { TrackScrollContext } from "./TrackScrollContext";