@ohos-cpf/3rdloop 0.0.1

package/vendor/Server/Skills/rnoh-cptf-api-test/references/DEMO_GENERATION_GUIDE.md

@@ -0,0 +1,358 @@
+# Demo 生成指南
+
+> Phase 2-3 的详细操作手册。核心是平台兼容性分析、可测试性设计、Demo 代码生成规范。
+
+---
+
+## 1. 平台兼容性分析
+
+### 1.1 Platform.OS 分支分析
+
+搜索入口文件中的平台分支：
+
+```bash
+grep -n "Platform.OS" {projectRoot}/node_modules/{harmonyPkgName}/index.js
+grep -n "Platform.OS" {projectRoot}/node_modules/{harmonyPkgName}/src/**/*.ts
+```
+
+分析结果分类：
+
+| 分类 | 特征 | 处理 |
+|------|------|------|
+| harmony 可用 | `Platform.OS === 'harmony'` 分支内定义 | 生成 Demo + Test |
+| iOS/Android 专属 | 仅在其他分支定义 | 跳过，不生成 |
+| 无平台分支 | TurboModule 原生适配，全部可用 | 全部生成 |
+| 条件导出 | `if (Platform.OS === 'harmony')` 包裹整个导出 | 按实际导出处理 |
+
+### 1.2 方法实现状态确认
+
+探查 ArkTS 实现文件，排除未实现方法：
+
+```bash
+grep -r "throw new Error('not implemented')" {projectRoot}/harmony/
+```
+
+| 状态 | 处理 |
+|------|------|
+| 已实现 | 正常生成 Demo + Test |
+| `throw new Error('not implemented')` | 跳过，不生成 |
+| 部分实现 | 标注，生成但测试中放宽断言 |
+
+### 1.3 权限需求分析
+
+```bash
+cat {projectRoot}/harmony/entry/src/main/module.json5 | grep -A5 "requestPermissions"
+```
+
+常见权限映射：
+
+| 功能 | 权限 | Demo 处理 |
+|------|------|-----------|
+| 麦克风 | ohos.permission.MICROPHONE | 调用前请求权限 |
+| 相机 | ohos.permission.CAMERA | 调用前请求权限 |
+| 定位 | ohos.permission.LOCATION | 调用前请求权限 |
+| 文件读写 | ohos.permission.FILE_READ/WRITE | 调用前请求权限 |
+| 网络 | ohos.permission.INTERNET | 通常自动授予 |
+
+### 1.4 MCP 工具辅助
+
+调用 `script_rn_scan_exports` 交叉验证：
+
+- `dir`：`{projectRoot}/node_modules/{harmonyPkgName}`
+- `compare`：false
+- 单目录扫描模式，提取 exports/interface/TurboModule 方法签名
+
+调用 `kb_search` 查询鸿蒙平台特定约束：
+- `HarmonyOS 权限 {功能}`
+- `RNOH TurboModule 适配`
+
+---
+
+## 2. 可测试性设计规则
+
+> ⚠️ 这是本技能与 `rnoh-lib-demo-create` 的核心差异。Demo 必须为 CPTF 自动化测试而设计。
+
+### 2.1 testID 规则
+
+| 元素 | testID 格式 | 示例 |
+|------|------------|------|
+| 触发按钮 | `{apiName}-btn` | `methodA-btn` |
+| 结果文本 | `{apiName}-result` | `methodA-result` |
+| 状态指示 | `{apiName}-status` | `recording-status` |
+
+```tsx
+<Button testID="methodA-btn" title="调用 methodA" onPress={...} />
+<Text testID="methodA-result">methodA结果：{result}</Text>
+```
+
+### 2.2 固定文本前缀规则
+
+所有动态值必须附加固定前缀，格式：`{API名}结果：{值}`
+
+| 场景 | 前缀格式 | 示例 |
+|------|----------|------|
+| 正常结果 | `{API名}结果：{值}` | `methodA结果：success` |
+| 错误信息 | `错误信息：{error}` | `错误信息：TypeError` |
+| 状态值 | `{API名}状态：{值}` | `录音状态：recording` |
+| 数组结果 | `{API名}结果：{JSON}` | `getList结果：[1,2,3]` |
+| 布尔值 | `{API名}结果：{true/false}` | `isEnabled结果：true` |
+
+> ⚠️ 冒号统一使用**全角** `：`（中文冒号），与 testerino demo 常见风格一致。CPTF 的 `waitForText` 是子串精确匹配，断言时可省略冒号（如 `methodA结果`）以兼容两种冒号。
+
+### 2.3 确定性输出规则
+
+| 数据类型 | 处理方式 | 示例 |
+|----------|----------|------|
+| 随机数 | 附加范围标注 | `随机数结果：{value}（范围：0-100）` |
+| 时间戳 | 转为可读格式 | `时间结果：{HH:MM:SS}` |
+| UUID | 仅验证格式 | `UUID结果：{uuid}（格式校验）` |
+| 大数据 | 截断显示 | `数据结果：{前100字符}...` |
+| null/undefined | 显示字面量 | `结果：null` |
+
+### 2.4 按钮唯一标识规则
+
+每个按钮 title 必须包含 API 名，保证 `textContains` 全局唯一：
+
+```tsx
+// 正确：title 含 API 名，唯一
+<Button title="调用 methodA(参数1)" />
+<Button title="调用 methodB" />
+
+// 错误：title 重复或不唯一
+<Button title="执行" />
+<Button title="测试" />
+```
+
+---
+
+## 3. Demo 页面代码规范
+
+### 3.1 目录结构
+
+```
+{exampleDir}/cptf/
+├── index.tsx                  # 主入口
+└── demo/
+    ├── 001_{apiCategory1}Page.tsx   # 按 API 分类拆分页面
+    ├── 002_{apiCategory2}Page.tsx
+    └── ...
+```
+
+文件命名规则：
+- 前缀序号：`001_`、`002_`，按 API 分类顺序
+- 分类名：kebab-case，如 `turbo-module-methods`、`component-props`、`events`
+- 示例：`001_turbo-module-methods.tsx`、`002_component-props.tsx`、`003_events.tsx`
+
+### 3.2 页面代码核心规则
+
+| 规则 | 说明 | 原因 |
+|------|------|------|
+| 根组件用 `View` | 禁止 `ScrollView` 作为根 | Tester 已有 ScrollView，嵌套导致高度塌陷 |
+| 不用 `SafeAreaView`/`StatusBar` | Tester 框架不需要 | 避免冗余 |
+| 不用 `Slider` | HarmonyOS 不支持 | 用按钮组替代 |
+| 不用 `console.error()` | 会触发系统弹窗 | 用 `console.warn()` 替代 |
+| 每个按钮设 `testID` | CPTF 优先 testID 定位 | 可测试性设计核心 |
+| 结果 Text 固定前缀 | CPTF `waitForText` 可靠匹配 | 可测试性设计核心 |
+| 无裸值渲染 | 所有动态值附加固定前缀 | 消除快照差集需求 |
+| 平台兼容性 | 只用 harmony 分支 API | 基于 Phase 2.1 |
+| 权限请求 | 敏感操作前请求权限 | HarmonyOS 权限模型 |
+| 异步处理 | `async/await` + `try/catch` | 不用 `.then()/.catch()` 链 |
+| 无注释 | 代码中不使用 `//` 或 `/* */` | 代码规范 |
+| Hook 顶层调用 | 不在事件回调中调用 Hook | React Hooks 规则 |
+| type 导入 | `import { type Xxx }` inline 语法 | 避免类型进入打包 |
+| Provider 子组件拆分 | 依赖 Context 的 Hook/组件拆分 | 确保 Context 有值 |
+| 废弃接口验证 | 使用 `===` 引用相等性比较 | 比功能对比更可靠 |
+
+### 3.3 各 API 类型的 Demo 页面设计
+
+#### 3.3.1 TurboModule 同步方法
+
+```tsx
+<View>
+  <Button testID="syncMethod-btn" title="调用 syncMethod(param)" onPress={() => {
+    try {
+      const result = NativeModule.syncMethod('param');
+      setResult(`syncMethod结果：${result}`);
+    } catch (e) {
+      setResult(`错误信息：${e}`);
+    }
+  }} />
+  <Text testID="syncMethod-result">{result}</Text>
+</View>
+```
+
+#### 3.3.2 TurboModule 异步方法
+
+```tsx
+<View>
+  <Button testID="asyncMethod-btn" title="调用 asyncMethod(param)" onPress={async () => {
+    setLoading(true);
+    try {
+      const result = await NativeModule.asyncMethod('param');
+      setResult(`asyncMethod结果：${JSON.stringify(result)}`);
+    } catch (e) {
+      setResult(`错误信息：${e}`);
+    } finally {
+      setLoading(false);
+    }
+  }} />
+  <Text testID="asyncMethod-result">{loading ? '加载中...' : result}</Text>
+</View>
+```
+
+#### 3.3.3 事件回调
+
+```tsx
+<View>
+  <Button testID="startListen-btn" title="开始监听 onEvent" onPress={() => {
+    const sub = DeviceEventEmitter.addListener('onEvent', (data) => {
+      setEventResult(`onEvent结果：${JSON.stringify(data)}`);
+    });
+    setSubscription(sub);
+  }} />
+  <Button testID="stopListen-btn" title="停止监听 onEvent" onPress={() => {
+    subscription?.remove();
+    setEventResult('onEvent状态：已停止');
+  }} />
+  <Text testID="onEvent-result">{eventResult}</Text>
+</View>
+```
+
+#### 3.3.4 组件属性
+
+```tsx
+<View>
+  <Button testID="toggleProp-btn" title="切换 prop1 值" onPress={() => setProp1(!prop1)} />
+  <Text testID="componentProp-result">组件属性prop1：{String(prop1)}</Text>
+  <ComponentA prop1={prop1} />
+</View>
+```
+
+#### 3.3.5 常量/枚举
+
+```tsx
+<View>
+  <Text testID="constant-result">常量CONSTANT_A：{NativeModule.CONSTANT_A}</Text>
+</View>
+```
+
+### 3.4 权限请求模板
+
+```tsx
+import { Permissions } from 'react-native';
+
+const requestPermission = async (permission: string): Promise<boolean> => {
+  try {
+    const granted = await Permissions.request(permission);
+    return granted === 'granted';
+  } catch (e) {
+    console.warn(`权限请求失败: ${e}`);
+    return false;
+  }
+};
+```
+
+---
+
+## 4. 主入口文件与注册
+
+### 4.1 index.tsx 结构
+
+```tsx
+import { Tester, TestSuite, TestCase } from '@rnoh/testerino';
+import React from 'react';
+import { TurboModuleMethodsPage } from './demo/001_turbo-module-methods';
+import { ComponentPropsPage } from './demo/002_component-props';
+import { EventsPage } from './demo/003_events';
+
+function {LibName}Tester() {
+  return (
+    <Tester>
+      <TestSuite name="{libName}">
+        <TestCase itShould="TurboModule 方法测试" tags={['C_API']}>
+          <TurboModuleMethodsPage />
+        </TestCase>
+        <TestCase itShould="组件属性测试" tags={['C_API']}>
+          <ComponentPropsPage />
+        </TestCase>
+        <TestCase itShould="事件回调测试" tags={['C_API']}>
+          <EventsPage />
+        </TestCase>
+      </TestSuite>
+    </Tester>
+  );
+}
+
+export default {LibName}Tester;
+export const displayName = '{libName}';
+export const framework = 'react';
+export const category = '{category}';
+export const title = '{libName}';
+export const description = '{libName} 接口规格驱动 Demo';
+export const examples = [
+  { title: 'TurboModule 方法', description: '...' },
+  { title: '组件属性', description: '...' },
+  { title: '事件回调', description: '...' },
+];
+```
+
+### 4.2 Demo 入口切换
+
+> 本技能不修改现有 `registerFile`（如 `RNTesterList.ts`），而是直接修改 `{exampleDir}/index.js`，将 App 入口指向 CPTF Demo：
+
+```js
+// {exampleDir}/index.js — 修改前
+import App from './src/index';
+// 修改后
+import App from './cptf/index';
+```
+
+这样 CPTF 测试运行时 App 直接加载 CPTF Demo 页面，无需在现有 Demo 注册体系中追加。
+
+### 4.3 入口切换说明
+
+本技能采用**直接修改 `index.js`** 的方式切换 Demo 入口，而非在现有 `registerFile`（如 `RNTesterList.ts`）中追加注册。原因：
+
+1. CPTF 测试需要 App 启动即加载 CPTF Demo 页面（含 testerino Tester 框架），不经过现有 Demo 选择器
+2. 不污染现有 Demo 注册体系，交付后可轻松恢复（将 `index.js` 改回 `./src/index`）
+3. 无需识别 registerFile 的注册模式（A/B/C）
+
+> ⚠️ 修改 `index.js` 后必须重新构建 HAP（`npm run dev` + `devecocli build`），否则设备上的 `bundle.harmony.js` 不含新入口。
+
+---
+
+## 5. 常见陷阱
+
+### 5.1 全角/半角冒号
+
+Demo 代码中结果文本的冒号必须统一使用全角 `：`，CPTF 测试的 `waitForText` 参数也必须逐字符匹配。
+
+如果 Demo 代码中混用了半角 `:`，CPTF 测试将无法匹配，导致步骤超时。
+
+### 5.2 异步渲染时序
+
+异步方法调用后，结果 Text 可能需要一段时间才渲染。Demo 代码应：
+- 异步执行期间显示 `加载中...` 文本
+- CPTF 测试的 `waitForText` 应轮询等待（timeout 8000ms）
+
+### 5.3 事件监听清理
+
+Demo 中注册的事件监听器必须在组件卸载时清理：
+
+```tsx
+useEffect(() => {
+  return () => {
+    subscription?.remove();
+  };
+}, [subscription]);
+```
+
+否则 CPTF 测试重复进入页面时可能出现内存泄漏。
+
+### 5.4 无平台分支库
+
+部分库（如 `react-native-safe-area-context`）没有 `Platform.OS === 'harmony'` 分支，而是通过 TurboModule 原生适配。探查时需区分此类库，无需过滤 iOS/Android 专属属性，JS 层所有导出在 HarmonyOS 上全部可用。
+
+### 5.5 废弃接口
+
+部分库包含 `@deprecated` 废弃别名接口。废弃接口在 HarmonyOS 平台仍正常可用，需生成 Demo 验证其兼容性，并使用引用相等性比较（`===`）验证别名关系。

package/vendor/Server/Skills/rnoh-cptf-api-test/references/QUALITY_CHECKLIST.md

@@ -0,0 +1,114 @@
+# 质量检查清单
+
+> Phase 6 的完整校验清单。生成完成后逐项检查。
+
+---
+
+## 1. 接口规格解析检查
+
+| # | 检查项 | 规则 | 通过条件 |
+|---|--------|------|----------|
+| 1.1 | 规格文档已读取 | specDoc 文件存在且可解析 | ✅ |
+| 1.2 | API 清单完整 | 所有 API 类别（方法/组件/事件/常量）已提取 | ✅ |
+| 1.3 | API 信息完整 | 每个 API 含名称、类型、参数、返回值、平台 | ✅ |
+| 1.4 | 工程目录已探查 | exampleDir 已确定 | ✅ |
+| 1.5 | 注册入口已探查 | registerFile 已确定，注册模式已识别 | ✅ |
+| 1.6 | 构建信息已提取 | bundleId、hapPath 已提取 | ✅ 或标注缺失 |
+| 1.7 | 依赖已确认 | package.json 含 harmonyPkgName | ✅ |
+
+---
+
+## 2. 平台兼容性检查
+
+| # | 检查项 | 规则 | 通过条件 |
+|---|--------|------|----------|
+| 2.1 | Platform.OS 分支已分析 | 已识别 harmony 可用/不可用 API | ✅ |
+| 2.2 | 无平台分支库已识别 | TurboModule 适配库全部可用 | ✅ 或标注不适用 |
+| 2.3 | 未实现方法已排除 | `throw new Error('not implemented')` 方法已跳过 | ✅ |
+| 2.4 | 权限需求已标注 | 敏感权限 API 已标注 | ✅ |
+| 2.5 | 映射表已构建 | 每个 API 有 Demo 步骤和 Test 步骤对应 | ✅ |
+
+---
+
+## 3. Demo 代码检查
+
+| # | 检查项 | 规则 | 通过条件 |
+|---|--------|------|----------|
+| 3.1 | 目录结构 | `{exampleDir}/cptf/demo/00X_*.tsx` | ✅ |
+| 3.2 | 根组件 | 用 `View`，非 `ScrollView` | ✅ |
+| 3.3 | testID 设置 | 每个可交互按钮设 `testID="{apiName}-btn"` | ✅ |
+| 3.4 | 固定文本前缀 | 结果 Text 用 `{API名}结果：{值}` 格式 | ✅ |
+| 3.5 | 无裸值渲染 | 所有动态值附加固定前缀 | ✅ |
+| 3.6 | 全角冒号 | 结果文本冒号统一全角 `：` | ✅ |
+| 3.7 | 按钮唯一标识 | title 含 API 名，全局唯一 | ✅ |
+| 3.8 | 无 Slider | 未使用 `Slider` 组件 | ✅ |
+| 3.9 | 无 console.error | 未使用 `console.error()` | ✅ |
+| 3.10 | 无注释 | 代码中无 `//` 或 `/* */` | ✅ |
+| 3.11 | 异步处理 | 用 `async/await` + `try/catch` | ✅ |
+| 3.12 | 权限请求 | 敏感操作前有权限请求 | ✅ 或标注不适用 |
+| 3.13 | 平台兼容性 | 未使用 iOS/Android 专属属性 | ✅ |
+| 3.14 | Hook 顶层调用 | Hook 不在事件回调中调用 | ✅ 或标注不适用 |
+| 3.15 | 入口文件 | `{exampleDir}/cptf/index.tsx` 含 Tester 集成 + 元数据导出 | ✅ |
+| 3.16 | Demo 入口切换 | `{exampleDir}/index.js` 已修改指向 `./cptf/index` | ✅ |
+
+---
+
+## 4. CPTF 测试工程检查
+
+| # | 检查项 | 规则 | 通过条件 |
+|---|--------|------|----------|
+| 4.1 | cptf.config.json | 存在且含 bundleId / casesDir / timezone / platforms.harmony.appPath / devices | ✅ |
+| 4.2 | appPath 绝对路径 | platforms.harmony.appPath 以 `/` 开头 | ✅ |
+| 4.3 | tsconfig.json | 存在且**不含** `experimentalDecorators` / `emitDecoratorMetadata` | ✅ |
+| 4.4 | package.json link | 声明 `@cptf/framework` link + `reflect-metadata` link | ✅ |
+| 4.5 | node_modules | @cptf/framework + reflect-metadata 已建立 | ✅ |
+
+---
+
+## 5. CPTF 测试文件检查
+
+| # | 检查项 | 规则 | 通过条件 |
+|---|--------|------|----------|
+| 5.1 | 首行 import | `import 'reflect-metadata'` | ✅ |
+| 5.2 | stepTimeout | 每个 @Step 显式设置 `stepTimeout: 30000` | ✅ |
+| 5.3 | testCaseExecutor | 文件末尾导出 `testCaseExecutor` | ✅ |
+| 5.4 | 多文件拆分 | 按 API 分类拆分，每个文件一个 `@Test`（非全部放一个文件） | ✅ |
+| 5.5 | 导航策略 | 注册 `single-page` 导航策略 | ✅ |
+| 5.6 | @Test 装饰器 | 含 id / name / module / platform / navigationStrategy | ✅ |
+| 5.7 | 辅助方法 | 含 scrollAndClick / waitForText / report | ✅ |
+| 5.8 | testID 定位 | 优先用 testID 定位（Demo 已设置） | ✅ |
+| 5.9 | 回调类 API 容错 | `(Module as any)` 调用的 API 使用容错断言 | ✅ 或标注不适用 |
+| 5.10 | 全角冒号风险 | waitForText 参数含半角冒号的行（警告） | ⚠️ 或 ✅ |
+
+---
+
+## 6. Demo-Test 对齐检查
+
+| # | 检查项 | 规则 | 通过条件 |
+|---|--------|------|----------|
+| 6.1 | API 覆盖一致 | Demo 中的 API 数量 = Test 中的 @Step 数量 | ✅ |
+| 6.2 | testID 一致 | Demo 的 testID = Test 的 scrollAndClickByTestId 参数 | ✅ |
+| 6.3 | 断言文本前缀匹配 | Demo 的 Text 前缀 = Test 的 waitForText 参数 | ✅ |
+| 6.4 | 按钮定位一致 | Demo 的按钮 title = Test 的 textContains 关键字 | ✅ |
+
+---
+
+## 7. 渐进式披露检查
+
+| # | 检查项 | 规则 | 通过条件 |
+|---|--------|------|----------|
+| 7.1 | SKILL.md body 行数 | < 500 行 | ✅ |
+| 7.2 | references 一层深度 | 无嵌套子目录 | ✅ |
+| 7.3 | 文件引用相对路径 | 无绝对路径引用 | ✅ |
+
+---
+
+## 8. 自动化校验
+
+运行校验脚本执行上述检查：
+
+```bash
+bash {skillDir}/scripts/validate-rnoh-cptf-api-test.sh '{"workspaceDir":"<绝对路径>","demoDir":"<绝对路径>"}'
+```
+
+脚本输出 `ALL CHECKS PASSED` 表示全部通过，否则列出失败项。