@ohos-cpf/3rdloop 0.0.1

package/vendor/Server/Skills/rn-library-consistency-check/references/CHECKLIST.md

@@ -0,0 +1,157 @@
+# RN 一致性检视清单
+
+本文档列出 RN 三方库鸿蒙化代码一致性检视的详细检查项，供检视人员参考。
+
+> ⚠️ **核心定位**：本清单**仅检查鸿蒙化实现代码与上游 RN 原库 Android/iOS 原生模块的一致性**，不关注非鸿蒙化部分。
+
+---
+
+## 0. 代码定位与范围识别
+
+### 0.1 鸿蒙化代码定位
+
+| 检查项 | 检查内容 | 结果判定 | 处理方式 |
+|--------|----------|----------|----------|
+| `source/ohos/` 目录存在性 | 是否存在鸿蒙化目录 | 不存在 → 搜索其他位置 | 智能搜索定位 |
+| `*.ets` 文件 | ArkTS/ETS 代码文件 | 无 → 搜索 @ohos 特征 | 代码特征搜索 |
+| `@ohos.*` 导入 | 鸿蒙 API 调用 | 无 → 搜索 napi_ | NAPI 层搜索 |
+| `napi_*` 函数 | C++ Native 绑定 | 无 → 无鸿蒙化代码 | 评分 0 分 |
+
+### 0.2 上游原库代码定位
+
+| 检查项 | 检查内容 | 结果判定 | 处理方式 |
+|--------|----------|----------|----------|
+| `source/RN/android/` 目录 | Android 原生模块 | 不存在 → 标注 | "缺少 Android 参考实现" |
+| `source/RN/ios/` 目录 | iOS 原生模块 | 不存在 → 标注 | "缺少 iOS 参考实现" |
+| `source/RN/src/` 目录 | JS/TS 接口定义 | 不存在 → 检查根目录 | 搜索 NativeModules 引用 |
+| TurboModule Spec | Codegen 生成的接口定义 | 不存在 → 检查旧架构 | 检查 NativeModules 模式 |
+
+---
+
+## 1. API 契约一致性检查
+
+### 1.1 方法签名一致性（15分）
+
+| 检查项 | 对比对象 | 扣分规则 | 致命度 |
+|--------|----------|----------|--------|
+| 方法名匹配 | JS Spec / NativeModules 方法名 vs OHOS 方法名 | 不匹配扣 5 分 | 中等 |
+| 参数数量匹配 | JS 调用参数数量 vs OHOS 接收参数数量 | **不匹配扣 8 分** | 致命 |
+| 参数顺序一致 | 参数位置是否完全对应 | 顺序错误扣 6 分 | 严重 |
+| 方法存在性 | JS 接口方法是否在 OHOS 实现 | **缺失扣 10 分** | 致命 |
+| Stub 方法检测 | OHOS 方法是否返回固定值无操作 | **Stub 扣 8 分** | 致命 |
+| 错误返回检测 | OHOS 方法是否返回错误而非实现 | **返回错误扣 10 分** | 致命 |
+
+### 1.2 参数类型一致性（20分）⚠️ 最易出错维度
+
+| 检查项 | JS/Android 类型 | OHOS 解析类型 | 扣分规则 | 致命度 |
+|--------|----------------|-------------|----------|--------|
+| boolean 解析 | boolean/bool | boolean | **解析为 string 扣 15 分** | 致命 |
+| number 解析 | number/int/double | number | 精度丢失扣 5 分 | 中等 |
+| string 解析 | string/String | string | 编码问题扣 2 分 | 轻微 |
+| Array 解析 | Array<T>/List<T> | Array<T> | 元素类型不一致扣 8 分 | 严重 |
+| Object 解析 | Object/Map/ReadableMap | Record/Object | 键值类型不一致扣 8 分 | 严重 |
+| 空值处理 | T \| null / T? | T \| null | 不处理 null 扣 8 分 | 严重 |
+
+**致命类型错误示例**：
+
+```typescript
+// ❌ 致命：boolean 被解析为 string
+// JS Spec: startScan({force: boolean})
+// OHOS:
+const force = call.arguments['force'] as string;
+// 结果：string "false" 在条件判断中仍为 truthy，功能完全失效！
+
+// ✅ 正确：
+const force = call.arguments['force'] as boolean;
+```
+
+### 1.3 返回值一致性（15分）
+
+| 检查项 | 对比对象 | 扣分规则 | 致命度 |
+|--------|----------|----------|--------|
+| 返回值类型 | JS Spec 期望类型 vs OHOS 实际返回 | **类型错误扣 10 分** | 致命 |
+| 返回值语义 | 返回内容是否符合接口语义 | **语义错误扣 8 分** | 严重 |
+| Promise 处理 | 异步方法是否正确返回 Promise | 不正确扣 6 分 | 严重 |
+| 错误返回格式 | 错误格式与 Android/iOS 一致性 | 格式不一致扣 5 分 | 中等 |
+
+### 1.4 事件/回调一致性（10分）
+
+| 检查项 | 对比对象 | 扣分规则 | 致命度 |
+|--------|----------|----------|--------|
+| 事件名一致 | Android/iOS 事件名 vs OHOS 事件名 | 不一致扣 5 分 | 中等 |
+| 事件数据格式 | 事件 payload 结构 | 结构不一致扣 6 分 | 严重 |
+| 回调触发时机 | 回调触发条件对比 | 时机不一致扣 5 分 | 中等 |
+| 常量导出 | getConstants() 对比 | 缺失常量扣 3 分 | 轻微 |
+
+---
+
+## 2. 平台实现一致性检查
+
+### 2.1 Android vs OHOS 函数级功能对比（25分）
+
+| 功能类别 | 检查项 | 扣分规则 | 致命度 |
+|----------|--------|----------|--------|
+| 核心方法缺失 | Android @ReactMethod 在 OHOS 不存在 | **缺失扣 15 分** | 致命 |
+| 方法行为不一致 | 同一方法核心逻辑差异 | **行为不一致扣 12 分** | 严重 |
+| 边界处理不一致 | 同一方法边界情况处理差异 | 不一致扣 8 分 | 中等 |
+| 错误处理不一致 | 同一方法错误处理差异 | 不一致扣 6 分 | 中等 |
+| 默认值不一致 | 方法配置默认值差异 | 不一致扣 4 分 | 轻微 |
+
+### 2.2 iOS vs OHOS 函数级功能对比（10分）
+
+| 功能类别 | 检查项 | 扣分规则 | 致命度 |
+|----------|--------|----------|--------|
+| 核心方法缺失 | iOS RCT_EXPORT_METHOD 在 OHOS 不存在 | **缺失扣 12 分** | 致命 |
+| 平台限制一致 | OHOS 是否有与 iOS 类似限制 | 不一致扣 5 分 | 中等 |
+| 行为一致性 | 同一方法行为对比 | 不一致扣 8 分 | 严重 |
+
+### 2.3 平台差异处理（5分）
+
+| 检查项 | 检查内容 | 扣分规则 |
+|--------|----------|----------|
+| OHOS 限制标注 | 特有限制是否文档化 | 未标注扣 3 分 |
+| 平台检测机制 | 是否有 Platform.OS 判断 | 缺失扣 2 分 |
+| 平台差异文档 | 是否有 README 说明差异 | 未文档化扣 2 分 |
+
+---
+
+## 3. RN 架构一致性检查
+
+### 3.1 TurboModule 架构（适用于新架构库）
+
+| 检查项 | 对比对象 | 扣分规则 |
+|--------|----------|----------|
+| Spec 接口实现 | Codegen Spec vs OHOS 实现 | 不一致扣 10 分 |
+| TurboModule 注册 | Android TurboModule 注册 vs OHOS 注册 | 不规范扣 8 分 |
+| 方法签名匹配 | Spec 定义 vs OHOS 方法签名 | 不匹配扣 6 分 |
+
+### 3.2 NativeModule 架构（适用于旧架构库）
+
+| 检查项 | 对比对象 | 扣分规则 |
+|--------|----------|----------|
+| 模块名注册 | getName() vs OHOS 模块名 | 不一致扣 5 分 |
+| 方法导出 | @ReactMethod vs OHOS 导出方法 | 缺失扣 8 分 |
+| 事件发送 | sendEvent vs OHOS 事件 | 不一致扣 5 分 |
+
+### 3.3 NAPI/C++ 桥接层一致性
+
+| 检查项 | 对比对象 | 扣分规则 |
+|--------|----------|----------|
+| NAPI 函数注册 | C++ 导出函数 vs JS 期望方法 | 注册缺失扣 8 分 |
+| NAPI 类型转换 | napi_value 类型与 JS 期望 | 转换错误扣 10 分 |
+| NAPI 回调 | napi_call_threadsafe_function vs 原库回调 | 回调不一致扣 6 分 |
+
+---
+
+## 4. 特殊场景检查
+
+### 4.1 常见 RN 鸿蒙化问题模式
+
+| 问题模式 | 检查方式 | 扣分规则 |
+|----------|----------|----------|
+| Promise 未 resolve/reject | 检查所有 Promise 方法 | 遗漏扣 8 分 |
+| 回调参数丢失 | 对比 Android/iOS callback 参数 | 丢失扣 5 分 |
+| 事件名拼写错误 | 对比 NativeEventEmitter 事件名 | 拼写错误扣 5 分 |
+| 线程模型差异 | Android Handler/MainThread vs OHOS 事件分发 | 未适配扣 6 分 |
+| 权限模型差异 | Android Manifest 权限 vs OHOS 权限 | 未映射扣 4 分 |
+| 生命周期差异 | Android Activity 生命周期 vs OHOS Ability | 未适配扣 6 分 |