@ohos-cpf/3rdloop 0.0.1

package/vendor/Server/Skills/rnoh-lib-demo-doc/references/DEMO_DESIGN_RULES.md

@@ -0,0 +1,413 @@
+# Demo 设计规则
+
+> 本文档详细说明 Demo 的分组原则、五要素规范、平台过滤规则、双计数器模式和 useState 强制规则。
+
+---
+
+## 1. Demo 分组原则
+
+### 原则一：一函数至少一个 Demo
+
+每个**待生成**接口（Phase 4 过滤后）必须被至少一个 Demo 覆盖。
+
+- **全量模式**：覆盖所有 HarmonyOS 平台可用的导出函数/方法/组件
+- **增量模式**：仅覆盖 Demo 覆盖率报告中未覆盖的接口
+
+### 原则二：关联接口可合并
+
+满足以下任一条件的接口可合并到同一 Demo：
+
+| 合并条件 | 示例 |
+|----------|------|
+| 存在明确的调用依赖关系 | `init()` → `execute()` → `release()` |
+| 共同完成一个完整业务场景 | "创建实例 → 配置参数 → 执行操作 → 获取结果" |
+| 属于同一主题功能簇 | 所有播放控制相关方法 |
+| 一个接口的输出是另一个接口的输入 | `scan()` 返回设备列表 → `connect(deviceId)` 使用列表中的 ID |
+| 事件注册与移除配对 | `addListener()` 与 `removeListener()` |
+
+> **增量模式特殊规则**：若未覆盖接口与已覆盖接口存在调用依赖，可将未覆盖接口合并到新 Demo 中独立描述。新 Demo 的步骤应自包含，不依赖已覆盖接口的 Demo 步骤。例如：若 `connect()` 已覆盖但 `writeData()` 未覆盖，`writeData()` 的 Demo 步骤中可包含简化的连接步骤作为前置条件，但重点是 `writeData()` 的验证。
+
+### 原则三：禁止无关合并
+
+不同功能方向、无调用关系的接口不得强行合并到同一 Demo。
+
+### 原则四：HarmonyOS 平台过滤
+
+> ⚠️ **过滤依据**：仅依据 README 文档的「HarmonyOS Support」列标注。**禁止**通过源码（`Platform.OS` 分支、TurboModule Spec、原生实现是否存在）进行过滤。源码中缺失鸿蒙实现可能是适配遗漏，需通过 Demo 验证发现。
+
+- **排除 README 标注 `no` 的接口**：README「HarmonyOS Support」列明确标注为 `no` 的接口，代表鸿蒙化维护者已确认不支持，不生成 Demo
+- **保留 README 未列出的接口**：上游新增但鸿蒙化 README 未收录的接口，视为无平台标注，默认跨平台，生成 Demo 并在描述中标注"建议验证 HarmonyOS 平台实际可用性"
+- **保留无平台标注的接口**：README 有接口但无「HarmonyOS Support」列时，默认视为跨平台，生成 Demo 但建议验证
+- **优先生成 README 标注 `yes` 的接口**：标记为 "跨平台"、"通用"、"Cross Platform"、"HarmonyOS 支持" 的接口优先生成 Demo
+- **平台差异说明**：在相关 Demo 步骤中标注 "本功能在 HarmonyOS 平台验证"
+- **适配遗漏诊断**：对于 README 未列出的接口，在预期结果中设计诊断指标（如"若回调未触发，可能为鸿蒙化适配遗漏"），通过双计数器模式诊断接口实际可用性
+
+---
+
+## 2. Demo 五要素规范
+
+### ① 测试 Demo 名称
+
+- 格式：`[功能动词/名词][操作对象][特征/场景]Demo`
+- 限制：不超过 20 字
+- 避免泛化词语（如"基础Demo"、"测试Demo"）
+
+| 场景 | 推荐名称 |
+|------|---------|
+| 单一核心功能 | `蓝牙扫描控制Demo` |
+| 生命周期管理 | `模块初始化与释放Demo` |
+| 配置类接口 | `参数配置与验证Demo` |
+| 异步 Promise | `异步数据加载Demo` |
+| 事件监听 | `原生事件订阅与回调Demo` |
+| 错误处理 | `异常捕获与错误码处理Demo` |
+| 多接口组合 | `完整业务流程Demo` |
+| React 组件 | `自定义组件渲染与交互Demo` |
+
+### ② 测试 Demo 描述
+
+模板：
+```
+{Demo名称}展示了如何使用 {接口名称} 实现 {功能描述}。
+通过本 Demo，开发者可以了解 {接口的核心用法/参数含义/返回值处理方式}。
+[可选：本 Demo 同时涵盖 {其他关联接口}，展示 {它们之间的调用关系/业务场景}。]
+[标注：本 Demo 针对 HarmonyOS 平台的特性/限制。]
+```
+
+要求：2-4 句话，说明功能、目的、覆盖接口，明确标注 HarmonyOS 平台特性。
+
+### ③ 测试 Demo 步骤
+
+步骤结构模板：
+```
+1. 创建函数式组件 Demo 页面（DemoScreen.tsx），使用 useState 声明所需状态变量
+   [状态变量列举：const [result, setResult] = useState(''); const [callCount, setCallCount] = useState(0);]，
+   使用 useEffect 处理组件挂载/卸载逻辑（事件订阅、资源初始化/释放等），
+   布局中添加 [UI组件列表：TouchableOpacity 按钮、TextInput 输入框、Text 展示区、ScrollView 列表等]。
+2. [用户操作]，触发 `{接口名称}({参数示例})` 调用，
+   在 Promise.then() / await 后 / 事件回调中执行 setXxx() 更新状态变量。
+3. 将接口返回值 / 状态变化以 <Text>{value}</Text> 形式展示在 [展示区域名称]。
+4. [下一步操作，如有]，验证 [具体行为]。
+[可选] 5. 对比 / 补充验证步骤。
+```
+
+步骤描述维度要求：
+
+| 维度 | 要求 | 示例 |
+|------|------|------|
+| 组件构建 | 说明需要哪些 RN 组件 | "使用 View 布局、TouchableOpacity 按钮、Text 显示结果" |
+| 状态声明 | 明确 useState 变量及初始值 | `const [status, setStatus] = useState('未初始化')` |
+| 交互触发 | 明确用户操作和调用时机 | "点击'开始扫描'按钮，调用 `BluetoothModule.startScan(5000)`" |
+| 参数传递 | 说明传入参数来源/示例值 | "传入 timeout=5000（毫秒）" |
+| 状态更新 | 说明如何通过 setXxx() 更新 | "在 .then() 回调中执行 `setResult(JSON.stringify(data))`" |
+| 结果展示 | 说明如何在页面显示结果 | "以 `<Text>{result}</Text>` 展示返回数据" |
+| 验证方式 | 说明如何判断成功 | "确认 Text 显示有效的设备列表，无崩溃" |
+| HarmonyOS 平台说明 | 标注特殊行为或限制 | "本功能在 HarmonyOS 平台验证" |
+
+### ④ 测试 Demo 预期结果
+
+模板：
+```
+1. [页面/UI 状态]：{可观测的界面变化描述}。
+2. [接口返回值]：{返回值类型/内容/范围} 符合预期。
+3. [功能效果]：{功能方面的可验证效果}。
+4. [异常/边界]：{无异常抛出 / 错误信息正确展示 / Promise reject 被捕获}。
+[可选] 5. [平台差异]：{HarmonyOS 平台表现说明}。
+```
+
+要求：每条预期结果可观测、可判断，特别标注 HarmonyOS 平台的预期行为。
+
+### ⑤ 对应函数接口
+
+列出该 Demo 涉及的所有函数/方法/组件名称。
+
+格式：
+- 函数：`` `funcName(paramType): ReturnType` ``
+- 组件：`` `<ComponentName prop={type} />` ``
+- 多个接口用换行分隔
+
+---
+
+## 3. HarmonyOS 可验证性前置规则（强制）
+
+在为任何接口编写步骤和预期结果之前，必须先判断：**该接口在 HarmonyOS 设备上能否产生可被用户观测到的输出？**
+
+> **判断依据**：仅依据 README 文档的「HarmonyOS Support」列标注。不通过源码判断（源码缺失实现可能是适配遗漏）。
+
+| 情况 | 处理方式 |
+|------|----------|
+| README 标注 `yes` 或跨平台 | 正常作为主步骤，预期结果描述可观测指标 |
+| README 标注 `no` | **排除**该接口，不生成 Demo |
+| README 标注 `partially` | 正常作为主步骤，预期结果中标注哪些子功能可用 |
+| README 中未列出该接口 | 正常作为主步骤，预期结果描述可观测指标 + 诊断指标（如"若回调未触发，可能为鸿蒙化适配遗漏"） |
+| README 有接口但无 Support 列 | 正常作为主步骤，预期结果描述可观测指标，建议开发者验证 |
+| 接口无任何可观测输出 | 合并到相关流程 Demo 中，通过其他接口的状态变化间接验证 |
+
+**禁止「死按钮」**：Demo 中每个按钮（每个步骤中调用的接口）必须对应至少一条 UI 上可观测的预期结果。若无法提供，该按钮/步骤必须删除或改为平台限制说明。
+
+---
+
+## 4. useState 强制规则
+
+Demo 步骤中包含「计数器（如回调次数、调用次数）」或「状态标志（如是否已初始化）」等运行时变化量时，在步骤或预期结果描述中**必须**注明：
+
+> **该变量须通过 `setXxx()` 更新**
+
+否则 React Native 不会触发重新渲染，计数器将始终显示初始值（如永远显示 0），导致 Demo 验证逻辑完全失效。
+
+正确示例：
+```
+const [checkCount, setCheckCount] = useState(0);
+// 点击按钮时：
+setCheckCount(c => c + 1);  // ✅ 通过 setter 更新
+```
+
+---
+
+## 5. 异步回调链双计数器诊断模式（强制）
+
+对任何 Demo 中涉及「调用库函数 → 等待 Promise / 监听事件回调」的异步链路，**必须**在 Demo 设计中规划双计数器：
+
+| 计数器位置 | 变量名建议 | 说明 |
+|-----------|----------|------|
+| 调用/触发前（在触发代码中） | `xxxCallCount` | 接口调用动作的执行次数（通过 `setXxxCallCount(c => c + 1)` 更新） |
+| 回调/resolve 内部 | `xxxCallbackCount` | Promise resolve 或事件回调实际触发的次数（通过 `setXxxCallbackCount(c => c + 1)` 更新） |
+
+两个计数器都必须在 Demo 页面的**验证区域**中展示（使用 `<Text>` 组件），且**必须通过 `useState` 的 setter 函数更新**。
+
+### 诊断规则
+
+| 计数器状态 | 诊断结论 |
+|-----------|----------|
+| `callCount > 0` 且 `callbackCount = 0` | 调用成功但回调未触发，问题在回调注册或原生事件链 |
+| `callCount = 0` | 触发代码未执行，问题在 Demo 的触发逻辑 |
+| `callCount = callbackCount > 0` | 链路完全正常 |
+
+### 步骤写作规范
+
+```
+步骤示例：
+1. 在组件中声明计数器：
+   const [xxxCallCount, setXxxCallCount] = useState(0);
+   const [xxxCallbackCount, setXxxCallbackCount] = useState(0);
+2. 触发按钮：setXxxCallCount(c => c + 1)，然后调用 module.doXxx()
+3. 在 .then() / await 后 / 事件回调中：setXxxCallbackCount(c => c + 1)，更新其他 UI 状态
+4. 验证区域展示：
+   <Text>调用次数: {xxxCallCount}</Text>
+   <Text>回调次数: {xxxCallbackCount}</Text>
+```
+
+---
+
+## 6. RN 常用接口调用模式速查
+
+### 6.1 接口模式分类总表
+
+RN 三方库的导出接口并非都是"按钮触发 → 函数调用 → 结果展示"模式。不同接口模式需要不同的 Demo 设计策略：
+
+| 模式 | 特征 | 调用时机 | 计数器需求 | Demo 步骤要点 |
+|------|------|----------|-----------|--------------|
+| **NativeModules 方法** | `NativeModules.Xxx.doXxx()` | 用户交互触发 | 双计数器（call + callback） | 按钮触发 → await → 展示结果 |
+| **Promise 异步** | `await func()` 返回 Promise | 用户交互触发 | 双计数器（call + callback） | 按钮触发 → await → catch 错误 → 展示 |
+| **NativeEventEmitter 事件** | `addListener('event', cb)` | useEffect 注册 | 双计数器（注册 + 回调触发） | useEffect 注册 → 触发事件 → 回调更新 |
+| **React 组件事件回调** | `<Comp onEvent={} />` | 渲染时绑定 | 双计数器（渲染 + 回调触发） | 渲染组件 → 触发事件 → 回调更新 |
+| **Hook** | `const x = useXxx()` | 组件顶层调用 | **无需双计数器**（同步返回，非异步链路） | 顶层调用 → 渲染时直接展示返回值 |
+| **Context Consumer** | `<Context.Consumer>{(val) => ...}</Context.Consumer>` | 渲染时自动消费 | **无需双计数器**（Context 传递，非异步链路） | Provider 包裹 → Consumer 子渲染函数接收值 → 展示 |
+| **HOC（高阶组件）** | `withXxx(WrappedComp)` | 模块顶层定义 | 单计数器（验证渲染次数即可） | 定义 HOC → 渲染被包装组件 → 验证注入的 props |
+| **常量/变量导出** | `export const X = ...` | 模块加载时求值 | **无需计数器**（静态值，非调用） | 直接读取 → useEffect 中展示 → 对比预期 |
+| **Context 对象引用** | `export const Ctx = createContext(...)` | 模块加载时创建 | **无需计数器**（引用比较） | `===` 引用比较 → 展示布尔结果 |
+| **废弃别名** | `export const alias = original` | 同底层接口 | 同底层接口模式 | 验证别名与原始接口行为一致 + `@deprecated` 标注 |
+
+### 6.2 Hook 模式
+
+Hook 在组件顶层调用，返回值在渲染阶段即可获取，**不是异步链路**，无需双计数器。
+
+**步骤范式**：
+```
+1. 在组件顶层调用 Hook：const value = useXxx()
+2. 将返回值直接渲染：<Text>{JSON.stringify(value)}</Text>
+3. [可选] 按钮触发状态变化验证 Hook 响应：setRefreshCount(c => c + 1)
+```
+
+**示例**：
+```typescript
+// Hook 必须在组件顶层调用，不可在事件回调中调用
+const insets = useSafeAreaInsets();
+
+return (
+  <View>
+    <Text>insets: {JSON.stringify(insets)}</Text>
+  </View>
+);
+```
+
+> ⚠️ Hook 不能放在按钮 onPress 回调中，必须在组件函数体顶层调用。
+
+### 6.3 Context Consumer 模式
+
+使用 React Context 的 Consumer 组件，通过 render props 子渲染函数接收 Context 值。**非异步链路**，无需双计数器。
+
+**步骤范式**：
+```
+1. 外层用 <Provider> 包裹确保 Context 有值
+2. 使用 <XxxConsumer>{(value) => <Text>{JSON.stringify(value)}</Text>}</XxxConsumer>
+3. 验证 Consumer 子渲染函数接收到的 value 非空
+```
+
+**示例**：
+```typescript
+<SafeAreaProvider>
+  <SafeAreaConsumer>
+    {(insets) => <Text>Consumer value: {JSON.stringify(insets)}</Text>}
+  </SafeAreaConsumer>
+</SafeAreaProvider>
+```
+
+### 6.4 HOC（高阶组件）模式
+
+高阶组件在模块顶层定义，将被包装组件包装后渲染。验证 HOC 注入的 props 是否正确传递。
+
+**步骤范式**：
+```
+1. 定义被包装组件：function InnerComp(props) { return <Text>{JSON.stringify(props.injected)}</Text> }
+2. 用 HOC 包装：const Wrapped = withXxx(InnerComp)
+3. 在 Provider 内渲染 <Wrapped />
+4. 验证 InnerComp 接收到 HOC 注入的 props
+```
+
+**示例**：
+```typescript
+function InnerComponent({ insets }: { insets: EdgeInsets }) {
+  return <Text>HOC injected insets: {JSON.stringify(insets)}</Text>;
+}
+const WrappedComponent = withSafeAreaInsets(InnerComponent);
+
+// 渲染
+<SafeAreaProvider>
+  <WrappedComponent />
+</SafeAreaProvider>
+```
+
+### 6.5 常量/变量导出模式
+
+模块加载时求值的静态导出值，直接读取即可。**非异步链路，非交互触发**，无需计数器。
+
+**步骤范式**：
+```
+1. 在 useEffect 中读取常量值（避免渲染期间副作用）
+2. 通过 setXxx() 更新状态展示
+3. 验证返回值符合预期类型和内容
+```
+
+**示例**：
+```typescript
+const [metricsText, setMetricsText] = useState('未获取');
+
+useEffect(() => {
+  setMetricsText(initialWindowMetrics ? JSON.stringify(initialWindowMetrics) : 'null');
+}, []);
+
+return <Text>initialWindowMetrics: {metricsText}</Text>;
+```
+
+### 6.6 Context 对象引用模式
+
+验证两个 Context 对象是否指向同一引用（废弃别名常见场景）。使用 `===` 严格比较。
+
+**步骤范式**：
+```
+1. 声明状态：const [isSame, setIsSame] = useState(false)
+2. 按钮触发比较：setIsSame(ContextA === ContextB)
+3. 展示布尔结果：<Text>相同引用: {isSame.toString()}</Text>
+```
+
+**示例**：
+```typescript
+const [isSameContext, setIsSameContext] = useState(false);
+
+const handleVerify = () => {
+  setIsSameContext(SafeAreaContext === SafeAreaInsetsContext);
+};
+
+return <Text>Context 相同: {isSameContext.toString()}</Text>;
+```
+
+### 6.7 废弃别名模式
+
+`@deprecated` 废弃别名接口的 Demo 设计，核心是验证别名与底层接口行为一致。
+
+**步骤范式**：
+```
+1. 同时引入废弃别名和非废弃原始接口
+2. 分别调用/使用两者
+3. 对比返回值或行为是否一致
+4. 若为对象引用（Context/变量），用 === 验证同一性
+5. 在 Demo 描述中标注"废弃接口兼容性验证"
+```
+
+**示例**：
+```typescript
+// useSafeArea 是 useSafeAreaInsets 的废弃别名
+const insetsFromAlias = useSafeArea();
+const insetsFromOriginal = useSafeAreaInsets();
+
+// 验证返回值一致
+<Text>别名返回: {JSON.stringify(insetsFromAlias)}</Text>
+<Text>原始返回: {JSON.stringify(insetsFromOriginal)}</Text>
+```
+
+### 6.8 NativeModules 调用模式
+
+```typescript
+import { NativeModules } from 'react-native';
+const { XxxModule } = NativeModules;
+
+// Promise
+const result = await XxxModule.someMethod(param);
+
+// Callback
+XxxModule.someMethod(param, (error, result) => { ... });
+```
+
+### 6.9 NativeEventEmitter 事件监听模式
+
+```typescript
+import { NativeModules, NativeEventEmitter } from 'react-native';
+const eventEmitter = new NativeEventEmitter(NativeModules.XxxModule);
+
+// 订阅事件（在 useEffect 中注册）
+const subscription = eventEmitter.addListener('eventName', (data) => {
+  setXxx(data);
+  setCallbackCount(c => c + 1);
+});
+
+// 取消订阅（在清理函数中）
+return () => subscription.remove();
+```
+
+### 6.10 async/await Promise 调用模式
+
+```typescript
+const handlePress = async () => {
+  setCallCount(c => c + 1);
+  try {
+    const result = await SomeModule.doSomething(param);
+    setResult(JSON.stringify(result));
+    setCallbackCount(c => c + 1);
+  } catch (error) {
+    setErrorMsg((error as Error).message);
+  }
+};
+```
+
+### 6.11 React 组件事件回调模式
+
+```typescript
+<SomeNativeComponent
+  prop1={value1}
+  onEvent={(data) => {
+    setCallbackCount(c => c + 1);
+    setResult(JSON.stringify(data));
+  }}
+  onError={(err) => setErrorMsg(err.message)}
+/>
+```

package/vendor/Server/Skills/rnoh-lib-demo-doc/references/OUTPUT_FORMAT.md

@@ -0,0 +1,269 @@
+# 输出格式规范
+
+> 本文档定义 Demo 描述文档的输出结构、表格格式和各字段填写规范。
+
+---
+
+## 1. 输出文件命名
+
+**文件名**：`{库名}RN测试demo描述.md`
+
+- 库名从 `package.json` 的 `name` 字段提取
+- 放置在 `libroot` 目录下（或 `output` 参数指定路径）
+- 示例：`react-native-bluetooth-managerRN测试demo描述.md`
+
+---
+
+## 2. 文档结构
+
+### 2.1 全量模式
+
+```markdown
+# {库名} RN 测试 Demo 描述文档（HarmonyOS 平台）
+
+## 概述
+
+本文档基于 `{库名}` 库的接口规格（`interface-spec.json`）和接口规格说明书（`{库名}接口规格说明.md`）生成，提供该库各接口在 HarmonyOS 平台可用的 React Native 测试 Demo 描述，供开发者参考实现功能验证 Demo 页面。
+
+> **平台说明**：本文档基于 RN 鸿蒙三方库的接口规格生成，仅包含该库在 HarmonyOS 平台可用的测试 Demo。已过滤 iOS/Android 平台专用接口。
+
+## Demo 总览
+
+| Demo 数量 | 覆盖接口数量 | 生成日期 |
+|----------|------------|---------|
+| N 个      | M 个        | YYYY-MM-DD |
+
+## 测试 Demo 描述列表
+
+| 序号 | 测试 Demo 名称 | 测试 Demo 描述 | 测试 Demo 步骤 | 测试 Demo 预期结果 | 对应函数接口 |
+|-----|--------------|--------------|--------------|-----------------|------------|
+| 1   | ...          | ...          | ...          | ...             | ...        |
+
+## 接口覆盖矩阵
+
+| 序号 | 接口名称 | 所在 Demo | 覆盖状态 |
+|-----|---------|----------|---------|
+| 1   | ...     | ...      | ✅ 已覆盖 |
+```
+
+### 2.2 增量模式 — 标准路径（有 interface-spec.json）
+
+```markdown
+# {库名} RN 测试 Demo 描述文档（HarmonyOS 平台）
+
+## 概述
+
+本文档基于 `{库名}` 库的接口规格和 Demo 覆盖率报告生成，提供该库各接口在 HarmonyOS 平台可用的 React Native 测试 Demo 描述，供开发者参考实现功能验证 Demo 页面。
+
+> **增量模式**：本文档仅针对 Demo 覆盖率报告中未覆盖的接口生成 Demo 描述。
+>
+> **覆盖率来源**：`{demoCoverage报告路径}`
+> **接口统计**：总接口数 {N}，已覆盖 {M}，本次生成 {待生成数}
+
+> **平台说明**：本文档仅包含 HarmonyOS 平台可用的测试 Demo。已过滤 iOS/Android 平台专用接口。
+
+## Demo 总览
+
+| Demo 数量 | 本次生成接口数量 | 生成日期 |
+|----------|----------------|---------|
+| N 个      | M 个            | YYYY-MM-DD |
+
+## 测试 Demo 描述列表
+
+| 序号 | 测试 Demo 名称 | 测试 Demo 描述 | 测试 Demo 步骤 | 测试 Demo 预期结果 | 对应函数接口 |
+|-----|--------------|--------------|--------------|-----------------|------------|
+| 1   | ...          | ...          | ...          | ...             | ...        |
+
+## 接口覆盖矩阵（本次新增）
+
+| 序号 | 接口名称 | 所在 Demo | 覆盖状态 |
+|-----|---------|----------|---------|
+| 1   | ...     | ...      | ✅ 本次新增 |
+```
+
+### 2.3 增量模式 — 快捷路径（仅覆盖率报告 + 源码分析）
+
+```markdown
+# {库名} RN 测试 Demo 描述文档（HarmonyOS 平台）
+
+## 概述
+
+本文档基于 `{库名}` 库的 Demo 覆盖率报告（`{coverageReport}`）和源码分析生成，提供该库未覆盖接口在 HarmonyOS 平台可用的 React Native 测试 Demo 描述，供开发者参考实现功能验证 Demo 页面。
+
+> **增量模式**：本文档仅针对 Demo 覆盖率报告中未覆盖的接口生成 Demo 描述。
+>
+> **覆盖率来源**：`{coverageReport}`
+> **接口统计**：总接口数 {N}，已覆盖 {M}，本次生成 {待生成数}
+
+> **平台说明**：本文档仅包含 HarmonyOS 平台可用的测试 Demo。已过滤 iOS/Android 平台专用接口。
+
+## Demo 总览
+
+| Demo 数量 | 本次生成接口数量 | 生成日期 |
+|----------|----------------|---------|
+| N 个      | M 个            | YYYY-MM-DD |
+
+## 测试 Demo 描述列表
+
+| 序号 | 测试 Demo 名称 | 测试 Demo 描述 | 测试 Demo 步骤 | 测试 Demo 预期结果 | 对应函数接口 |
+|-----|--------------|--------------|--------------|-----------------|------------|
+| 1   | ...          | ...          | ...          | ...             | ...        |
+
+## 接口覆盖矩阵（本次新增）
+
+| 序号 | 接口名称 | 所在 Demo | 覆盖状态 |
+|-----|---------|----------|---------|
+| 1   | ...     | ...      | ✅ 本次新增 |
+```
+
+> **来源声明规则**：
+> - 全量模式（2.1）：声明基于 interface-spec.json + 接口规格说明书
+> - 增量标准路径（2.2）：声明基于接口规格 + 覆盖率报告
+> - 增量快捷路径（2.3）：声明基于覆盖率报告 + 源码分析，**不得**提及 interface-spec.json 或接口规格说明书
+>
+> 增量模式下，"Demo 总览"表头为"本次生成接口数量"而非"覆盖接口数量"；接口覆盖矩阵的覆盖状态标注为"✅ 本次新增"。
+
+---
+
+## 3. 表格内容规范
+
+### 3.1 序号
+
+- 从 1 开始的自增整数
+- 全文档保持唯一且连续
+- Demo 描述列表和接口覆盖矩阵分别独立编号
+
+### 3.2 测试 Demo 名称
+
+- 简洁明了，不超过 20 字
+- 格式：`[功能动词/名词][操作对象][场景]Demo`
+- 避免泛化词语
+
+### 3.3 测试 Demo 描述
+
+- 2-4 句话
+- 说明功能、目的和覆盖接口
+- 明确标注该 Demo 针对 HarmonyOS 平台的特性
+
+### 3.4 测试 Demo 步骤
+
+- 编号列表，每步骤一行
+- 具体可执行，含接口调用位置及 `setXxx()` 更新说明
+- 以 RN 函数式组件页面为视角
+- 包含维度：组件构建、状态声明、交互触发、参数传递、状态更新、结果展示、验证方式、HarmonyOS 平台说明
+
+### 3.5 测试 Demo 预期结果
+
+- 编号列表
+- 具体可验证的观测指标
+- 特别标注 HarmonyOS 平台的预期行为
+- 对于 README 中未列出或无平台标注的接口，建议开发者验证实际可用性
+- 对于 README 中未列出的接口，须设计诊断指标（如"若回调未触发 callbackCount 保持 0，可能为鸿蒙化适配遗漏，需进一步排查"）
+
+### 3.6 对应函数接口
+
+- 列出所有相关接口的函数签名
+- 格式：`` `funcName(paramType): ReturnType` `` 或 `` `<ComponentName prop={type} />` ``
+- 多个接口用 `<br>` 分隔（表格内换行）
+
+---
+
+## 4. 接口覆盖矩阵填写规范
+
+```markdown
+| 序号 | 接口名称 | 所在 Demo | 覆盖状态 |
+|-----|---------|----------|---------|
+| 1 | `BluetoothModule.startScan(timeout: number): Promise<void>` | 蓝牙扫描与停止Demo | ✅ 已覆盖 |
+| 2 | `BluetoothModule.stopScan(): Promise<void>` | 蓝牙扫描与停止Demo | ✅ 已覆盖 |
+| 3 | `getSDKVersion(): string` | 版本信息查询Demo | ✅ 已覆盖 |
+```
+
+**规则**：
+- 矩阵中每个接口的"所在 Demo"与 Demo 描述列表中的名称严格一致
+- 全量模式：所有接口状态为 ✅ 已覆盖，不得出现未覆盖接口
+- 增量模式：仅列出本次新增的未覆盖接口，状态为 ✅ 本次新增；已覆盖接口不出现
+- 若单个接口出现在多个 Demo 中，用"/"分隔（如"Demo1 / Demo2"）
+- README 标注 `no` 的排除接口不出现在矩阵中
+- 排除接口须在文档中以独立章节列出，标注排除依据为 README 文档标注（含 README 行号），不标注源码分析依据
+
+---
+
+## 5. 表格内换行处理
+
+Markdown 表格单元格内需要换行时，使用 `<br>` 标签：
+
+```markdown
+| 1 | 扫描Demo | 描述内容 | 1. 步骤一<br>2. 步骤二<br>3. 步骤三 | 1. 预期一<br>2. 预期二 | `funcA(): void`<br>`funcB(): Promise` |
+```
+
+---
+
+## 6. 代码内联格式
+
+在表格单元格内引用代码时，使用反引号：
+
+- 函数名：`` `startScan` ``
+- 函数签名：`` `startScan(timeout?: number): Promise<void>` ``
+- 组件：`` `<CameraView onBarCodeRead={} />` ``
+- 变量：`` `callCount` ``
+- useState 声明：`` `const [result, setResult] = useState('')` ``
+
+---
+
+## 7. 排除接口详情章节规范
+
+当有接口因平台过滤被排除时，输出文档须包含独立的「未覆盖接口平台过滤详情」章节，明确记录排除依据。
+
+> ⚠️ **排除依据**：仅依据 README 文档的「HarmonyOS Support」列标注。**禁止**将源码分析（`Platform.OS` 分支、TurboModule Spec、原生实现）作为排除依据。
+
+### 7.1 章节结构
+
+```markdown
+## 未覆盖接口平台过滤详情
+
+覆盖率报告中共 {N} 个未覆盖接口，平台过滤仅依据 README.md「接口说明」章节的「HarmonyOS Support」列进行判定。
+
+### 过滤规则
+
+| README「HarmonyOS Support」标注 | 处理方式 | 接口数量 |
+|--------------------------------|----------|---------|
+| `no` | 排除，不生成 Demo | {X} |
+| 未列出 | 视为无平台标注，默认跨平台，生成 Demo | {Y} |
+
+### 已排除接口（README 标注 `no`）
+
+| # | 接口名称 | 参数 / 返回类型 | README HarmonyOS Support | README Platform | 排除原因 |
+|---|----------|----------------|--------------------------|-----------------|----------|
+| 1 | `funcName(params): void` | `(params: Type): void` | `no` | Android | README 明确标注 HarmonyOS 不支持 |
+
+### 已生成 Demo 接口（README 未列出）
+
+| # | 接口名称 | 参数 / 返回类型 | README 状态 | 上游版本 | 上游源码签名来源 |
+|---|----------|----------------|------------|---------|----------------|
+| 1 | `funcName(params): void` | `(params: Type): void` | 未列出 | 3.2.7 新增 | `.upstream-cache/.../index.d.ts:{行号}` |
+```
+
+### 7.2 排除接口记录字段
+
+| 字段 | 说明 | 必填 |
+|------|------|------|
+| 接口名称 | 被排除的接口名 | ✅ |
+| 参数 / 返回类型 | 接口签名摘要 | ✅ |
+| README HarmonyOS Support | README 中的标注值（`no`） | ✅ |
+| README Platform | README 中的 Platform 列值 | ✅ |
+| README 行号 | 标注所在行号（便于追溯） | 推荐 |
+| 排除原因 | 基于 README 文档标注排除 | ✅ |
+
+> ⚠️ 排除原因中**不得**出现"源码中无 harmony 分支"、"TurboModule Spec 未定义"、"原生层未实现"等源码分析依据。排除依据仅为 README 文档标注。
+
+### 7.3 保留接口记录字段
+
+对于 README 未列出而保留生成的接口，须记录：
+
+| 字段 | 说明 | 必填 |
+|------|------|------|
+| 接口名称 | 保留的接口名 | ✅ |
+| 参数 / 返回类型 | 接口签名摘要 | ✅ |
+| README 状态 | "未列出" | ✅ |
+| 上游版本 | 接口在上游哪个版本新增 | 推荐 |
+| 上游源码签名来源 | `.upstream-cache` 中的源码位置 | ✅ |