@ohos-cpf/3rdloop 0.0.1

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

@@ -0,0 +1,203 @@
+# 配置扩展机制详解
+
+> **rn-ohos-xts-generator** - 配置系统使用指南
+> **版本**: 1.0.0
+> **更新日期**: 2026-03-31
+
+## 目录
+
+- [一、配置系统概述](#一配置系统概述)
+- [二、配置文件结构](#二配置文件结构)
+- [三、配置优先级](#三配置优先级)
+- [四、创建新三方库配置](#四创建新三方库配置)
+- [五、配置最佳实践](#五配置最佳实践)
+
+---
+
+## 一、配置系统概述
+
+rn-ohos-xts-generator 采用**分层配置系统**，支持从通用到特化的多级配置继承。
+
+### 1.1 设计理念
+
+- **通用配置**：所有 RN 三方库共享的基础规范
+- **三方库配置**：特定三方库的专有规则和 API 信息
+- **用户配置**：使用时指定的临时配置
+
+### 1.2 配置继承关系
+
+```
+┌─────────────────────────────────────────┐
+│         通用配置 (_common.md)           │
+│    - 编号规范、命名规范、断言规则        │
+└─────────────────┬───────────────────────┘
+                  │ 继承
+┌─────────────────▼───────────────────────┐
+│    三方库配置 ({library}/_common.md)     │
+│    - API 列表、特殊规则、已知问题        │
+└─────────────────────────────────────────┘
+```
+
+---
+
+## 二、配置文件结构
+
+### 2.1 目录结构
+
+```
+references/
+├── COMMON_CONFIG.md                    # 通用配置（所有三方库共享）
+└── {library-name}_CONFIG.md            # 特定三方库的配置
+```
+
+### 2.2 通用配置文件
+
+位置：`references/COMMON_CONFIG.md`
+
+包含所有三方库共享的规范，详见该文件内容。
+
+---
+
+## 三、配置优先级
+
+```
+用户自定义配置 > 三方库配置 > 通用配置
+```
+
+**特殊规则**：通用配置中的核心强制规范不可被任何层级覆盖。
+
+---
+
+## 四、创建新三方库配置
+
+### 4.1 创建步骤
+
+1. 在 `references/` 下创建以 `{library-name}_CONFIG.md` 命名的配置文件
+2. 按照模板填写配置信息
+
+### 4.2 配置模板
+
+```markdown
+# [库名] XTS 测试配置
+
+## 基础信息
+
+- 库名：@react-native-ohos/[库名]
+- 库名简写：[简写]
+- 版本：[版本号]
+- 源码路径：[oh_modules 路径]
+
+## API 分类
+
+### TurboModule 方法
+
+| 方法名 | 参数 | 返回值 | 类型 | 实现状态 |
+|--------|------|--------|------|---------|
+| ... | ... | ... | 同步/异步 | ✅/❌ |
+
+### 事件列表
+
+| 事件名 | 回调参数 | 实现状态 |
+|--------|---------|---------|
+| ... | ... | ✅/⚠️ |
+
+### 常量列表
+
+| 常量名 | 类型 | HarmonyOS 可用 |
+|--------|------|---------------|
+| ... | ... | ✅/❌ |
+
+## 特殊规则
+
+- [规则1]
+- [规则2]
+
+## 已知问题
+
+- [问题1]
+- [问题2]
+
+## 权限需求
+
+| 权限名 | 涉及 API |
+|--------|---------|
+| ... | ... |
+```
+
+### 4.3 配置示例
+
+```markdown
+# react-native-audio XTS 测试配置
+
+## 基础信息
+
+- 库名：@react-native-ohos/react-native-audio
+- 库名简写：AUDIO
+- 版本：1.0.0
+- 源码路径：oh_modules/@react-native-ohos/react-native-audio
+
+## API 分类
+
+### TurboModule 方法
+
+| 方法名 | 参数 | 返回值 | 类型 | 实现状态 |
+|--------|------|--------|------|---------|
+| prepareRecordingAtPath | path: string, options: RecordingOptions | boolean | 同步 | ✅ |
+| startRecording | 无 | void | 同步 | ✅ |
+| stopRecording | 无 | void | 同步 | ✅ |
+| pauseRecording | 无 | void | 同步 | ✅ |
+| resumeRecording | 无 | void | 同步 | ✅ |
+| isRecording | 无 | boolean | 同步 | ✅ |
+| requestAuthorization | 无 | Promise<boolean> | 异步 | ✅ |
+| checkAuthorizationStatus | 无 | Promise<boolean> | 异步 | ❌ |
+
+### 事件列表
+
+| 事件名 | 回调参数 | 实现状态 |
+|--------|---------|---------|
+| onProgress | { currentTime: number, currentMetering: number } | ⚠️ 可能不稳定 |
+| onFinishRecording | { status: string, audioFileURL: string } | ⚠️ 可能不稳定 |
+
+### 常量列表
+
+| 常量名 | 类型 | HarmonyOS 可用 |
+|--------|------|---------------|
+| FilesDirectoryPath | string | ✅ |
+| CachesDirectoryPath | string | ✅ |
+| TempsDirectoryPath | string | ✅ |
+| MainBundlePath | string | ❌ |
+| DocumentDirectoryPath | string | ❌ |
+| LibraryDirectoryPath | string | ❌ |
+
+## 特殊规则
+
+- onProgress 事件可能不稳定，测试需设置 10 秒超时
+- 使用 FilesDirectoryPath 而非 DocumentDirectoryPath
+
+## 已知问题
+
+- checkAuthorizationStatus 在 HarmonyOS 端未实现
+- emitDeviceEvent 可能不触发
+
+## 权限需求
+
+| 权限名 | 涉及 API |
+|--------|---------|
+| ohos.permission.MICROPHONE | startRecording |
+```
+
+---
+
+## 五、配置最佳实践
+
+### 5.1 何时创建三方库配置
+
+- 当三方库有特殊的测试规则时
+- 当三方库有已知的 API 限制时
+- 当三方库需要特殊的权限配置时
+
+### 5.2 配置维护
+
+- 三方库版本更新时，同步更新配置
+- 发现新的已知问题时，及时补充
+- API 实现状态变化时，及时更新

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

@@ -0,0 +1,147 @@
+# 测试覆盖率分析器
+
+---
+
+## 一、模块概述
+
+测试覆盖率分析器用于分析现有 XTS 测试文件，识别已覆盖和未覆盖的 API，为补充测试用例提供依据。
+
+---
+
+## 二、分析目标
+
+### 2.1 测试套件信息
+
+- describe 块名称
+- 测试函数（it）列表
+- 测试级别分布
+
+### 2.2 API 覆盖信息
+
+- 已测试的方法列表
+- 已测试的参数组合
+- 已测试的事件
+- 已测试的错误码
+- 已测试的边界值
+
+### 2.3 测试模式识别
+
+- TurboModule 方法测试
+- NativeEventEmitter 事件测试
+- NativeComponent 组件测试
+- 权限相关测试
+
+---
+
+## 三、分析步骤
+
+### 3.1 定位测试文件
+
+```bash
+# RN 三方库 XTS Jest 测试文件通常位于
+{RN_TEST_PROJECT}/__tests__/
+# 或用户指定的测试目录
+```
+
+### 3.2 提取测试用例信息
+
+搜索测试文件中的模式：
+
+```bash
+# 搜索所有 describe 块
+grep -r "describe(" __tests__/ --include="*.test.ts"
+
+# 搜索所有 it 函数
+grep -r "it(" __tests__/ --include="*.test.ts"
+
+# 搜索所有 @tc.number
+grep -r "@tc.number" __tests__/ --include="*.test.ts"
+```
+
+### 3.3 与 API 清单对比
+
+将提取的测试用例与源码解析阶段输出的 API 清单进行对比：
+
+```
+=== 覆盖率分析报告 ===
+
+[总 API 数] 10
+[已覆盖] 6 (60%)
+[未覆盖] 4 (40%)
+
+[已覆盖 API]
+✅ prepareRecordingAtPath - 3 个测试用例
+✅ startRecording - 2 个测试用例
+✅ stopRecording - 2 个测试用例
+✅ isRecording - 1 个测试用例
+✅ requestAuthorization - 1 个测试用例
+✅ AudioUtils.FilesDirectoryPath - 1 个测试用例
+
+[未覆盖 API]
+❌ pauseRecording - 无测试用例
+❌ resumeRecording - 无测试用例
+❌ onProgress 事件 - 无测试用例
+❌ onFinishRecording 事件 - 无测试用例
+
+[测试级别分布]
+LEVEL0: 1 个
+LEVEL1: 5 个
+LEVEL2: 3 个
+LEVEL3: 1 个
+```
+
+---
+
+## 四、覆盖率驱动模式
+
+### 4.1 触发条件
+
+当用户提供覆盖率报告或要求补充测试时，使用覆盖率驱动模式。
+
+### 4.2 处理流程
+
+```
+1. 读取覆盖率报告（或执行覆盖分析）
+2. 提取未覆盖的 API 列表
+3. 按优先级排序未覆盖项
+4. 为每个未覆盖项生成测试用例
+5. 输出补充测试文件
+```
+
+### 4.3 优先级排序
+
+| 优先级 | 未覆盖项类型 | 说明 |
+|--------|------------|------|
+| P0 | 核心方法 | 库的主要功能方法 |
+| P1 | 状态查询方法 | 返回状态信息的方法 |
+| P1 | 权限方法 | 涉及权限的方法 |
+| P2 | 事件回调 | NativeEventEmitter 事件 |
+| P2 | 辅助方法 | pause/resume 等 |
+| P3 | 常量验证 | 路径常量等 |
+
+---
+
+## 五、输出格式
+
+### 5.1 覆盖率报告
+
+```
+=== @react-native-ohos/react-native-audio 覆盖率报告 ===
+
+总 API 数: 10
+已覆盖: 6 (60%)
+未覆盖: 4 (40%)
+
+建议补充的测试用例:
+1. [P0] pauseRecording - 正常暂停流程
+2. [P0] resumeRecording - 正常恢复流程
+3. [P1] onProgress 事件 - 录音进度回调
+4. [P1] onFinishRecording 事件 - 录音完成回调
+```
+
+### 5.2 补充测试建议
+
+根据覆盖率分析结果，生成具体的补充测试建议，包括：
+- 需要补充的测试用例名称
+- 建议的测试级别
+- 建议的测试类型（PARAM/ERROR/RETURN/EVENT）

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

@@ -0,0 +1,148 @@
+# 测试设计文档生成器
+
+---
+
+## 一、模块概述
+
+测试设计文档生成器负责在生成测试用例的同时，同步生成结构化的测试设计文档，确保测试用例和测试设计文档的一致性和完整性。
+
+---
+
+## 二、生成模式
+
+| 模式 | 描述 | 适用场景 |
+|------|------|---------|
+| **完整模式** | 包含所有章节的完整测试设计文档 | 重要 API、新功能开发 |
+| **简化模式** | 核心章节的简化测试设计文档 | 快速迭代、辅助功能 |
+
+---
+
+## 三、测试设计文档模板
+
+### 3.1 完整模式模板
+
+```markdown
+# [库名] XTS 测试设计文档
+
+## 1. 测试概述
+
+### 1.1 测试目标
+为 @react-native-ohos/[库名] 生成 XTS 测试用例，覆盖以下功能：
+- [功能1]
+- [功能2]
+- [功能3]
+
+### 1.2 测试范围
+- 测试平台：HarmonyOS
+- 测试框架：Jest
+- 被测库版本：[版本号]
+- 被测库路径：[oh_modules 路径或接口规格说明文档路径]
+
+### 1.3 测试环境
+- OH_ROOT：[路径]
+- RN_TEST_PROJECT：[路径]
+
+## 2. API 清单
+
+### 2.1 TurboModule 方法
+
+| 方法名 | 参数 | 返回值 | 类型 | 实现状态 |
+|--------|------|--------|------|---------|
+| method1 | param1: string | boolean | 同步 | ✅ 已实现 |
+| method2 | 无 | Promise\<void\> | 异步 | ✅ 已实现 |
+| method3 | data: Object | void | 同步 | ❌ 未实现 |
+
+### 2.2 事件列表
+
+| 事件名 | 回调参数 | 实现状态 |
+|--------|---------|---------|
+| onEvent1 | { data: string } | ✅ 已实现 |
+| onEvent2 | { status: number } | ⚠️ 可能不稳定 |
+
+### 2.3 常量列表
+
+| 常量名 | 类型 | 说明 |
+|--------|------|------|
+| CONSTANT1 | string | 描述 |
+| CONSTANT2 | number | 描述 |
+
+## 3. 测试用例设计
+
+### 3.1 [API名称] 测试
+
+#### 3.1.1 正常参数测试
+
+| 用例编号 | 用例名称 | 输入 | 预期输出 | 级别 |
+|---------|---------|------|---------|------|
+| SUB_RNOH_XXX_METHOD_PARAM_0001 | testMethodNormal001 | 正常参数 | 返回 true | LEVEL1 |
+| SUB_RNOH_XXX_METHOD_PARAM_0002 | testMethodEmptyParam001 | 空参数 | 抛出异常 | LEVEL2 |
+
+#### 3.1.2 错误码测试
+
+| 用例编号 | 用例名称 | 输入 | 预期错误码 | 级别 |
+|---------|---------|------|-----------|------|
+| SUB_RNOH_XXX_METHOD_ERROR_401_0001 | testMethodError401001 | 无效参数 | 401 | LEVEL3 |
+
+### 3.2 [事件名称] 测试
+
+| 用例编号 | 用例名称 | 触发条件 | 预期结果 | 级别 |
+|---------|---------|---------|---------|------|
+| SUB_RNOH_XXX_EVENT_EVENT_0001 | testEventCallback001 | 正常触发 | 回调被调用 | LEVEL1 |
+
+## 4. 平台兼容性说明
+
+### 4.1 HarmonyOS 可用 API
+- [API 列表]
+
+### 4.2 HarmonyOS 不可用 API（不测试）
+- [API 列表及原因]
+
+### 4.3 需要特殊处理的 API
+- [API 列表及处理方式]
+
+## 5. 权限需求
+
+| 权限名 | 涉及 API | 说明 |
+|--------|---------|------|
+| ohos.permission.MICROPHONE | startRecording | 录音功能 |
+
+## 6. 已知限制
+
+1. [限制1说明]
+2. [限制2说明]
+```
+
+### 3.2 简化模式模板
+
+```markdown
+# [库名] XTS 测试设计文档（简化版）
+
+## API 清单
+[API 列表表格]
+
+## 测试用例
+[测试用例列表表格]
+
+## 平台兼容性
+[可用/不可用 API 列表]
+```
+
+---
+
+## 四、命名规范
+
+```
+格式: [测试文件名].design.md
+示例:
+  - AudioRecorderTest.test.ts → AudioRecorderTest.test.design.md
+  - AudioUtilsTest.test.ts → AudioUtilsTest.test.design.md
+```
+
+---
+
+## 五、同步生成原则
+
+- **一一对应**：每个测试用例都有对应的测试设计文档场景
+- **内容一致**：设计文档内容必须与测试用例实现保持一致
+- **版本同步**：测试用例修改时，设计文档必须同步更新
+- **完整覆盖**：设计文档必须涵盖所有测试场景

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

@@ -0,0 +1,165 @@
+# RN 三方库测试用例生成流程
+
+---
+
+## 一、概述
+
+本文档定义了从 RN 三方库源码到生成 XTS 测试用例的完整流程。
+
+---
+
+## 二、完整生成流程
+
+```
+步骤1：源码探查
+   ├─ 1.1 定位三方库源码（oh_modules / node_modules）
+   ├─ 1.2 解析 JS/TS 入口文件
+   │   ├─ 提取导出的 API
+   │   ├─ 识别 Platform.OS === 'harmony' 分支
+   │   └─ 提取 NativeEventEmitter 事件名称
+   ├─ 1.3 解析 TurboModule Spec
+   │   ├─ 方法签名、参数类型、返回值类型
+   │   ├─ 同步方法 vs 异步方法（Promise）
+   │   └─ 类型定义
+   ├─ 1.4 探查 HarmonyOS ArkTS 实现
+   │   ├─ 确认实际实现的方法
+   │   ├─ 排除 throw new Error('not implemented')
+   │   └─ 确认 emitDeviceEvent 的事件名称
+   └─ 1.5 探查 NativeComponent（如有）
+       ├─ Index.ets 中的 export struct
+       └─ 组件属性和事件
+   ↓
+步骤2：平台兼容性分析
+   ├─ 对比各平台 API 差异
+   ├─ 标记 HarmonyOS 可用/不可用 API
+   └─ 识别需要特殊处理的 API
+   ↓
+步骤3：覆盖率分析（如有现有测试）
+   ├─ 扫描现有 XTS 测试文件
+   ├─ 识别已覆盖的 API
+   └─ 输出覆盖率报告
+   ↓
+步骤4：测试用例规划
+   ├─ 按 API 类型分类（TurboModule/Event/Component/Constant）
+   ├─ 按测试类型分类（PARAM/ERROR/RETURN/EVENT/PERM）
+   ├─ 按优先级排序（P0-P3）
+   └─ 估算测试用例数量
+   ↓
+步骤5：测试用例生成
+   ├─ 5.1 TurboModule 方法测试
+   │   ├─ 正常参数测试（PARAM）
+   │   ├─ 错误码测试（ERROR）
+   │   ├─ 返回值测试（RETURN）
+   │   └─ 边界值测试（BOUNDARY）
+   ├─ 5.2 事件回调测试（EVENT）
+   │   ├─ 事件触发验证
+   │   └─ 事件参数验证
+   ├─ 5.3 NativeComponent 测试（如有）
+   │   ├─ 属性测试
+   │   └─ 事件测试
+   ├─ 5.4 常量/枚举测试
+   └─ 5.5 权限测试（PERM）
+   ↓
+步骤6：测试设计文档生成
+   └─ 同步生成 {测试文件名}.design.md
+   ↓
+步骤7：格式化和验证
+   ├─ @tc 注释块完整性
+   ├─ jest.mock() 导入语句正确性
+   ├─ 测试用例命名规范（should...when...）
+   ├─ 断言方法正确性（Jest 断言）
+   └─ describe/it 结构正确性
+   ↓
+步骤8：输出文件
+   ├─ 测试文件：{输出目录}/__tests__/
+   ├─ Mock 文件：{输出目录}/__mocks__/
+   ├─ 配置文件：{输出目录}/jest.config.js, jest.setup.js
+   └─ 设计文档：{输出目录}/[库名].test.design.md
+```
+
+---
+
+## 三、详细步骤说明
+
+### 步骤1：源码探查
+
+详见 [源码解析器](SOURCE_PARSER.md) 和 [HarmonyOS 实现探查器](HARMONY_SCANNER.md)
+
+### 步骤2：平台兼容性分析
+
+详见 [平台兼容性分析器](PLATFORM_COMPAT.md)
+
+### 步骤3：覆盖率分析
+
+详见 [覆盖率分析器](COVERAGE_ANALYZER.md)
+
+### 步骤4：测试用例规划
+
+根据源码探查和兼容性分析结果，规划测试用例：
+
+1. **过滤不可用 API**：移除 HarmonyOS 不支持的 API
+2. **过滤未实现 API**：移除 `throw new Error('not implemented')` 的方法
+3. **按类型分类**：TurboModule 方法、事件、组件、常量
+4. **按优先级排序**：核心功能 > 辅助功能 > 边界情况
+5. **估算数量**：根据 API 复杂度估算测试用例数
+
+### 步骤5：测试用例生成
+
+根据 [测试生成策略](GENERATION_STRATEGY.md) 中的策略和 [测试文件模板](../assets/TEST_FILE_TEMPLATES.md) 中的模板生成测试用例。
+
+**生成顺序**：
+1. TurboModule 核心方法测试（P0）
+2. TurboModule 正常参数测试（P1）
+3. 权限测试（P1）
+4. 事件回调测试（P2）
+5. TurboModule 边界值测试（P2）
+6. TurboModule 错误码测试（P3）
+7. 常量/枚举测试（P3）
+
+### 步骤6：测试设计文档生成
+
+详见 [设计文档指南](DESIGN_DOC_GUIDE.md)
+
+### 步骤7：格式化和验证
+
+**必须检查的项目**：
+
+| 检查项 | 规范 | 错误示例 |
+|--------|------|---------|
+| @tc.name | should...when... 格式，与 it() 一致 | `@tc.name Test_Method_001` |
+| @tc.number | `SUB_RNOH_[库名]_[API]_[类型]_[序号]` | `SUB_UTILS_...` |
+| @tc.desc | 以 `. ` 结尾 | `测试方法` |
+| it() 命名 | should...when... 格式 | `testMethod001` |
+| 导入合并 | 同包名合并 | 分散导入 |
+| 断言方法 | 从 Jest 断言列表中选择 | `assertNotNull` |
+| Mock 位置 | jest.mock() 在 import 之前 | import 在 mock 之前 |
+| Mock 清理 | beforeEach 中 jest.clearAllMocks() | 无清理 |
+
+---
+
+## 四、输出文件规范
+
+### 4.1 文件命名
+
+```
+[库名简写][功能模块].test.ts
+```
+
+### 4.2 文件组织
+
+```
+{输出目录}/
+├── __tests__/
+│   ├── [库名简写]Test.test.ts       # 主测试文件（TurboModule 方法）
+│   ├── [库名简写]EventTest.test.ts  # 事件测试文件
+│   ├── [库名简写]PermTest.test.ts   # 权限测试文件
+│   └── [库名简写]UtilsTest.test.ts  # 工具类/常量测试文件
+├── __mocks__/
+│   └── @react-native-ohos/
+│       └── [库名]/
+│           └── index.ts             # Mock 模块文件
+├── jest.config.js                   # Jest 配置
+├── jest.setup.js                    # Jest setup 文件
+├── package.json                     # npm 配置
+└── [库名].test.design.md            # 测试设计文档
+```