@ohos-cpf/3rdloop 0.0.1

package/vendor/Server/Skills/rn-ohos-xts-generator/references/SOURCE_PARSER.md

@@ -0,0 +1,235 @@
+# RN 三方库源码解析器
+
+---
+
+## 一、模块概述
+
+RN 三方库源码解析器负责从 `@react-native-ohos/*` 库的源码中提取 API 信息，包括 JS/TS 入口文件、TurboModule Spec 定义、NativeEventEmitter 事件等。
+
+---
+
+## 二、源码定位
+
+### 2.1 定位优先级
+
+```
+1. oh_modules/@react-native-ohos/[库名]/  （推荐，最准确）
+2. node_modules/@react-native-ohos/[库名]/  （备选）
+```
+
+### 2.2 定位方法
+
+从 `.oh-xts-config.json` 中读取 `RN_TEST_PROJECT` 路径，然后：
+
+```bash
+# 探查 oh_modules（推荐）
+ls {RN_TEST_PROJECT}/oh_modules/@react-native-ohos/[库名]/
+
+# 探查 node_modules（备选）
+ls {RN_TEST_PROJECT}/node_modules/@react-native-ohos/[库名]/
+```
+
+---
+
+## 三、JS/TS 入口文件解析
+
+### 3.1 定位入口文件
+
+入口文件通常为以下之一：
+- `index.js`
+- `index.ts`
+- `index.tsx`
+- `src/index.ts`
+- `src/index.js`
+
+### 3.2 提取导出的 API
+
+从入口文件中提取以下信息：
+
+| 提取项 | 搜索模式 | 输出 |
+|--------|---------|------|
+| 导出的类 | `export class`, `export default class` | 类名列表 |
+| 导出的方法 | `export function`, `export const.*=.*=>` | 方法名列表 |
+| 导出的常量 | `export const.*=.*[^>]` | 常量名和值 |
+| 导出的枚举 | `export enum` | 枚举名和成员 |
+| NativeEventEmitter 事件 | `addEventListener`, `.on(`, `NativeEventEmitter` | 事件名列表 |
+| Platform 分支 | `Platform.OS ===` | 各平台 API 差异 |
+
+### 3.3 解析示例
+
+```javascript
+// react-native-audio 的入口文件
+import { Platform } from 'react-native';
+import { NativeModules } from 'react-native';
+
+const AudioRecorder = NativeModules.AudioRecorder;
+
+let AudioUtils: AudioUtilsType;
+if (Platform.OS === 'ios') {
+  AudioUtils = {
+    MainBundlePath: '',
+    DocumentDirectoryPath: '',
+    CachesDirectoryPath: '',
+    LibraryDirectoryPath: '',
+  };
+} else if (Platform.OS === 'harmony') {
+  AudioUtils = {
+    FilesDirectoryPath: '/data/app/...',
+    CachesDirectoryPath: '/data/app/...',
+    TempsDirectoryPath: '/data/app/...',
+  };
+}
+
+export { AudioRecorder, AudioUtils };
+```
+
+**解析输出**：
+- 导出类：无（使用 NativeModules）
+- 导出对象：`AudioRecorder`, `AudioUtils`
+- HarmonyOS 可用 API：`AudioRecorder`（所有方法）, `AudioUtils.FilesDirectoryPath`, `AudioUtils.CachesDirectoryPath`, `AudioUtils.TempsDirectoryPath`
+- HarmonyOS 不可用 API：`AudioUtils.MainBundlePath`, `AudioUtils.DocumentDirectoryPath`, `AudioUtils.LibraryDirectoryPath`
+
+---
+
+## 四、TurboModule Spec 解析
+
+### 4.1 定位 TurboModule Spec
+
+TurboModule Spec 文件通常位于：
+- `src/Native[库名].ts`
+- `src/Native[库名].js`
+- `Native[库名].ts`
+- CodeGen 生成的文件
+
+### 4.2 提取方法签名
+
+从 Spec 文件中提取：
+
+```typescript
+// NativeAudioRecorder.ts
+export interface Spec extends TurboModule {
+  prepareRecordingAtPath(path: string, options: RecordingOptions): boolean;
+  startRecording(): void;
+  stopRecording(): void;
+  pauseRecording(): void;
+  resumeRecording(): void;
+  checkAuthorizationStatus(): Promise<boolean>;
+  requestAuthorization(): Promise<boolean>;
+  isRecording(): boolean;
+  onProgress: ?(data: ProgressData) => void;
+  onFinishRecording: ?(data: Record<string, Object>) => void;
+}
+```
+
+**解析输出**：
+
+| 方法名 | 参数 | 返回值 | 类型 |
+|--------|------|--------|------|
+| prepareRecordingAtPath | path: string, options: RecordingOptions | boolean | 同步 |
+| startRecording | 无 | void | 同步 |
+| stopRecording | 无 | void | 同步 |
+| pauseRecording | 无 | void | 同步 |
+| resumeRecording | 无 | void | 同步 |
+| checkAuthorizationStatus | 无 | Promise\<boolean\> | 异步 |
+| requestAuthorization | 无 | Promise\<boolean\> | 异步 |
+| isRecording | 无 | boolean | 同步 |
+| onProgress | data: ProgressData | void | 事件回调 |
+| onFinishRecording | data: Record\<string, Object\> | void | 事件回调 |
+
+### 4.3 提取类型定义
+
+```typescript
+// 提取 RecordingOptions 接口
+export interface RecordingOptions {
+  SampleRate?: number;
+  Channels?: number;
+  AudioQuality?: string;
+  AudioEncoding?: string;
+  OutputFormat?: string;
+  MeteringEnabled?: boolean;
+  AudioEncodingBitRate?: number;
+}
+
+// 提取 ProgressData 接口
+export interface ProgressData {
+  currentTime: number;
+  currentMetering: number;
+}
+```
+
+---
+
+## 五、NativeEventEmitter 事件解析
+
+### 5.1 事件发现方法
+
+在源码中搜索以下模式：
+
+```javascript
+// 模式1：直接赋值回调
+AudioRecorder.onProgress = (data) => { ... };
+AudioRecorder.onFinishRecording = (data) => { ... };
+
+// 模式2：addEventListener
+NativeEventEmitter.addListener('recordingProgress', callback);
+NativeEventEmitter.addListener('recordingFinished', callback);
+
+// 模式3：DeviceEventEmitter
+DeviceEventEmitter.addListener('recordingProgress', callback);
+
+// 模式4：直接导出事件名常量
+export const RECORDING_PROGRESS_EVENT = 'recordingProgress';
+```
+
+### 5.2 事件信息提取
+
+| 事件名 | 触发时机 | 回调参数 | 说明 |
+|--------|---------|---------|------|
+| recordingProgress | 录音进行中 | { currentTime, currentMetering } | 进度事件 |
+| recordingFinished | 录音完成 | { status, audioFileURL } | 完成事件 |
+
+---
+
+## 六、解析输出格式
+
+### 6.1 API 清单
+
+解析完成后，输出结构化的 API 清单：
+
+```
+=== @react-native-ohos/react-native-audio API 清单 ===
+
+[导出对象]
+- AudioRecorder (NativeModule)
+  - 同步方法: prepareRecordingAtPath, startRecording, stopRecording, pauseRecording, resumeRecording, isRecording
+  - 异步方法: checkAuthorizationStatus, requestAuthorization
+  - 事件回调: onProgress, onFinishRecording
+
+- AudioUtils (常量对象)
+  - HarmonyOS 可用: FilesDirectoryPath, CachesDirectoryPath, TempsDirectoryPath
+  - HarmonyOS 不可用: MainBundlePath, DocumentDirectoryPath, LibraryDirectoryPath
+
+[类型定义]
+- RecordingOptions: { SampleRate?, Channels?, AudioQuality?, AudioEncoding?, OutputFormat?, MeteringEnabled?, AudioEncodingBitRate? }
+- ProgressData: { currentTime, currentMetering }
+
+[事件列表]
+- onProgress: 录音进度事件
+- onFinishRecording: 录音完成事件
+
+[权限需求]
+- ohos.permission.MICROPHONE (录音功能)
+```
+
+### 6.2 测试优先级建议
+
+根据 API 的重要性和使用频率，建议测试优先级：
+
+| 优先级 | API | 理由 |
+|--------|-----|------|
+| P0 | 核心流程方法 | prepareRecordingAtPath + startRecording + stopRecording |
+| P1 | 状态查询方法 | isRecording, checkAuthorizationStatus |
+| P1 | 权限方法 | requestAuthorization |
+| P2 | 事件回调 | onProgress, onFinishRecording |
+| P2 | 辅助方法 | pauseRecording, resumeRecording |
+| P3 | 常量验证 | AudioUtils 各路径常量 |

package/vendor/Server/Skills/rn-ohos-xts-generator/references/TEST_CONVENTIONS.md

@@ -0,0 +1,245 @@
+# 测试约定和命名规范
+
+---
+
+## 一、测试用例编号规范
+
+### 1.1 编号格式
+
+```
+SUB_RNOH_[库名简写]_[API]_[类型]_[序号]
+```
+
+### 1.2 库名简写规则
+
+| 原始库名 | 简写 | 说明 |
+|---------|------|------|
+| @react-native-ohos/react-native-audio | AUDIO | 取最后一段 |
+| @react-native-ohos/react-native-webview | WEBVIEW | 取最后一段 |
+| @react-native-ohos/react-native-camera | CAMERA | 取最后一段 |
+| @react-native-ohos/react-native-ble-plx | BLE | 取核心功能词 |
+| @react-native-ohos/react-native-vlc-media-player | VLC | 取核心标识 |
+
+### 1.3 类型标识
+
+| 标识 | 说明 | 示例 |
+|------|------|------|
+| PARAM | 参数测试 | SUB_RNOH_AUDIO_PREPARE_PARAM_0001 |
+| ERROR | 错误码测试 | SUB_RNOH_AUDIO_PREPARE_ERROR_401_0001 |
+| RETURN | 返回值测试 | SUB_RNOH_AUDIO_GETAUTH_RETURN_0001 |
+| BOUNDARY | 边界值测试 | SUB_RNOH_AUDIO_PREPARE_BOUNDARY_0001 |
+| EVENT | 事件测试 | SUB_RNOH_AUDIO_PROGRESS_EVENT_0001 |
+| PERM | 权限测试 | SUB_RNOH_AUDIO_MIC_PERM_0001 |
+
+---
+
+## 二、测试用例命名规范
+
+### 2.1 测试函数命名
+
+```typescript
+// 格式: should [expected behavior] when [condition]
+it('should prepare recording with valid path and options', () => {});
+it('should reject when path is empty', () => {});
+it('should invoke onProgress callback with correct data', () => {});
+it('should request microphone authorization successfully', () => {});
+```
+
+### 2.2 测试套件命名
+
+```typescript
+// TurboModule 方法测试
+describe('AudioRecorderPrepareTest', () => {});
+describe('AudioRecorderStartStopTest', () => {});
+describe('AudioRecorderAuthorizationTest', () => {});
+
+// 事件测试
+describe('AudioRecorderProgressEventTest', () => {});
+describe('AudioRecorderFinishEventTest', () => {});
+
+// 常量/工具类测试
+describe('AudioUtilsConstantsTest', () => {});
+
+// NativeComponent 组件测试
+describe('WebViewSourcePropertyTest', () => {});
+describe('WebViewOnLoadEventTest', () => {});
+```
+
+---
+
+## 三、JSDoc 注释规范
+
+### 3.1 标准注释模板
+
+```typescript
+/**
+ * @tc.name should prepare recording with valid path and options
+ * @tc.number SUB_RNOH_AUDIO_PREPARE_PARAM_0001
+ * @tc.desc 测试 AudioRecorder 的 prepareRecordingAtPath 方法 - 正常参数场景.
+ * @tc.type FUNCTION
+ * @tc.size MEDIUMTEST
+ * @tc.level LEVEL1
+ */
+it('should prepare recording with valid path and options', () => {
+  // ...
+});
+```
+
+### 3.2 注释字段说明
+
+| 字段 | 说明 | 规范 |
+|------|------|------|
+| @tc.name | 测试用例名称 | 必须与 it() 第一个参数完全一致 |
+| @tc.number | 测试用例编号 | SUB_RNOH_[库名]_[API]_[类型]_[序号] |
+| @tc.desc | 测试描述 | 格式：`测试 [对象] 的 [方法] - [场景].`，必须以 `. ` 结尾 |
+| @tc.type | 测试类型 | FUNCTION / EVENT |
+| @tc.size | 测试规模 | SMALLTEST / MEDIUMTEST / LARGETEST |
+| @tc.level | 测试级别 | LEVEL0 / LEVEL1 / LEVEL2 / LEVEL3 / LEVEL4 |
+
+---
+
+## 四、测试文件组织规范
+
+### 4.1 文件命名
+
+```
+[库名简写][功能模块].test.ts
+```
+
+示例：
+```
+AudioRecorderTest.test.ts          # 主测试文件
+AudioUtilsTest.test.ts             # 工具类测试文件
+AudioEventTest.test.ts             # 事件测试文件
+AudioPermTest.test.ts              # 权限测试文件
+```
+
+### 4.2 文件结构
+
+```typescript
+/**
+ * Copyright (c) 2025 Huawei Device Co., Ltd.
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * ...
+ */
+
+jest.mock('@react-native-ohos/react-native-audio', () => ({
+  AudioRecorder: {
+    prepareRecordingAtPath: jest.fn().mockReturnValue(true),
+    startRecording: jest.fn(),
+    stopRecording: jest.fn(),
+    pauseRecording: jest.fn(),
+    resumeRecording: jest.fn(),
+    requestAuthorization: jest.fn().mockResolvedValue(true),
+    isRecording: jest.fn().mockReturnValue(false),
+  },
+  AudioUtils: {
+    FilesDirectoryPath: '/data/app/files',
+    CachesDirectoryPath: '/data/app/cache',
+    MainBundlePath: '/data/app/bundle',
+  },
+}));
+
+import { AudioRecorder, AudioUtils } from '@react-native-ohos/react-native-audio';
+
+describe('AudioRecorderPrepareTest', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  // 测试用例
+});
+```
+
+### 4.3 测试级别分配
+
+| 级别 | 适用场景 | 示例 |
+|------|---------|------|
+| LEVEL0 | 冒烟测试、核心功能 | 基本录音流程 |
+| LEVEL1 | 正常参数、核心返回值 | 正常参数、权限请求 |
+| LEVEL2 | 边界值、异常参数 | 空路径、null 参数 |
+| LEVEL3 | 错误码、特殊场景 | 错误码 401、超时场景 |
+| LEVEL4 | 兼容性、性能 | 大文件、并发操作 |
+
+---
+
+## 五、RN 三方库测试特有约定
+
+### 5.1 测试文件输出路径
+
+```
+{RN_TEST_PROJECT}/__tests__/
+├── [库名简写]Test.test.ts
+├── [库名简写]EventTest.test.ts
+├── [库名简写]PermTest.test.ts
+└── [库名简写]UtilsTest.test.ts
+```
+
+### 5.2 Mock 文件输出路径
+
+```
+{RN_TEST_PROJECT}/__mocks__/
+└── @react-native-ohos/
+    └── [库名]/
+        └── index.ts
+```
+
+### 5.3 测试设计文档命名
+
+```
+格式: [库名].test.design.md
+示例:
+  - react-native-audio.test.design.md
+```
+
+### 5.4 describe 嵌套规范
+
+```typescript
+describe('AudioRecorderTest', () => {
+  // 第一层：按 API 分组
+  describe('prepareRecordingAtPath', () => {
+    // 第二层：按场景分组（可选）
+    it('should prepare with valid parameters', () => {});
+    it('should reject when path is empty', () => {});
+  });
+
+  describe('startRecording', () => {
+    it('should start recording successfully', () => {});
+  });
+});
+```
+
+### 5.5 异步测试规范
+
+```typescript
+// 异步方法测试必须使用 async/await
+it('should resolve authorization to true', async () => {
+  (AudioRecorder.requestAuthorization as jest.Mock).mockResolvedValue(true);
+  const result = await AudioRecorder.requestAuthorization();
+  expect(result).toBe(true);
+});
+
+// 异步错误测试
+it('should reject when authorization denied', async () => {
+  (AudioRecorder.requestAuthorization as jest.Mock).mockRejectedValue(
+    new Error('Authorization denied')
+  );
+  await expect(AudioRecorder.requestAuthorization()).rejects.toThrow('Authorization denied');
+});
+```
+
+### 5.6 Mock 清理规范
+
+```typescript
+describe('SomeTestSuite', () => {
+  beforeEach(() => {
+    // 每个测试前清理所有 Mock 状态
+    jest.clearAllMocks();
+  });
+
+  afterEach(() => {
+    // 每个测试后恢复所有 Mock（可选）
+    jest.restoreAllMocks();
+  });
+});
+```