@ohos-cpf/3rdloop 0.0.1

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

@@ -0,0 +1,382 @@
+# Flutter 一致性检视清单
+
+本文档列出 Flutter 三方库鸿蒙化代码一致性检视的详细检查项，供检视人员参考。
+
+> ⚠️ **核心定位**：本清单**仅检查 ohos 目录下的代码与 Android/iOS 实现的一致性**，不关注 Flutter Dart 层或非鸿蒙化部分的代码。
+
+---
+
+## 0. 代码定位与范围识别
+
+### 0.1 鸿蒙化目录检查
+
+| 检查项 | 检查内容 | 结果判定 | 处理方式 |
+|--------|----------|----------|----------|
+| `ohos/` 目录存在性 | 是否存在鸿蒙化目录 | 不存在 → 0 分 | 报告标注"未实现鸿蒙化" |
+| `ohos/ets/` 文件数 | ArkTS/ETS 代码文件数量 | 为空 → 0 分 | 报告标注"鸿蒙化代码缺失" |
+| `ohos/src/` 文件数 | C++ Native 代码文件数量 | 为空可接受 | 仅检视 ETS 层 |
+| `android/` 目录存在性 | 是否有 Android 参考实现 | 缺失 → 标注 | "缺少对比参考实现" |
+| `ios/` 目录存在性 | 是否有 iOS 参考实现 | 缺失 → 标注 | "缺少对比参考实现" |
+
+---
+
+## 1. API 契约一致性检查
+
+### 1.1 方法签名一致性（15分）
+
+| 检查项 | 对比对象 | 扣分规则 | 致命度 |
+|--------|----------|----------|--------|
+| 方法名称匹配 | Dart MethodChannel 名称 vs ArkTS 方法名 | 不匹配扣 5 分 | 中等 |
+| 参数数量匹配 | Dart 调用参数数量 vs ArkTS 接收参数数量 | **不匹配扣 8 分** | 致命 |
+| 参数顺序一致 | 参数位置是否完全对应 | 顺序错误扣 6 分 | 严重 |
+| 方法存在性 | Dart 接口方法是否在 OHOS 实现 | **缺失扣 10 分** | 致命 |
+| Stub 方法检测 | OHOS 方法是否返回固定值无操作 | **stub 扣 8 分** | 致命 |
+| 错误返回检测 | OHOS 方法是否返回错误而非实现 | **返回错误扣 10 分** | 致命 |
+
+**Stub 方法识别特征**：
+- 方法体仅有 return 语句，返回固定值
+- 未调用任何 @ohos 模块 API
+- 未执行实际业务操作
+
+**错误返回识别特征**：
+- 返回 `{error: "not supported"}` 等错误对象
+- 返回字符串错误消息而非期望类型
+- 功能明确未实现
+
+### 1.2 参数类型一致性（20分）⚠️ 最易出错维度
+
+| 检查项 | Dart 类型 | ArkTS 解析类型 | 扣分规则 | 致命度 |
+|--------|-----------|---------------|----------|--------|
+| boolean 解析 | bool | boolean | **解析为 string 扣 15 分** | 致命 |
+| integer 解析 | int | number | 精度丢失扣 5 分 | 中等 |
+| double 解析 | double | number | 精度丢失扣 3 分 | 轻微 |
+| String 解析 | String | string | 编码问题扣 2 分 | 轻微 |
+| List 解析 | List<T> | Array<T> | 元素类型不一致扣 8 分 | 严重 |
+| Map 解析 | Map<K,V> | Record/Object | 键值类型不一致扣 8 分 | 严重 |
+| Uint8List 解析 | Uint8List | ArrayBuffer | 字节序问题扣 5 分 | 中等 |
+| 空值处理 | T? | T \| null | 不处理 null 扣 8 分 | 严重 |
+
+**致命类型错误示例**：
+
+```typescript
+// ❌ 致命：boolean 被解析为 string
+// Dart: setNotifyValue(force_indications: bool)
+// OHOS: 
+const force_indications = call.arguments['force_indications'] as string;
+// 结果：string "false" 在条件判断中仍为 truthy，功能完全失效！
+
+// ✅ 正确：
+const force_indications = call.arguments['force_indications'] as boolean;
+```
+
+**类型映射完整对照表**：
+
+| Dart 类型 | ArkTS 类型 | as 语句 | 常见错误 | 风险 |
+|-----------|------------|---------|----------|------|
+| bool | boolean | `as boolean` | `as string` → 功能失效 | **致命** |
+| int | number | `as number` | 超出 int64 范围 | 高 |
+| double | number | `as number` | 精度丢失 | 中 |
+| String | string | `as string` | UTF-8 编码 | 低 |
+| List<int> | number[] | `as number[]` | 元素类型混入 string | 高 |
+| List<String> | string[] | `as string[]` | 正确 | 低 |
+| Map<String, dynamic> | Record<string, Object> | `as Record<string, Object>` | 键类型不一致 | 高 |
+| Uint8List | ArrayBuffer | 无需 as | 字节序、长度 | 中 |
+
+### 1.3 返回值类型一致性（15分）
+
+| 检查项 | 期望类型 | 实际返回 | 扣分规则 | 致命度 |
+|--------|----------|----------|----------|--------|
+| 返回值类型匹配 | Dart 期望类型 | OHOS 实际返回 | **类型错误扣 10 分** | 致命 |
+| 返回值语义一致 | 接口定义语义 | 返回内容语义 | **语义错误扣 8 分** | 致命 |
+| void 返回处理 | void | 无返回或 null | 不正确扣 5 分 | 中等 |
+| 成功指示返回 | bool/void 成功 | boolean 或空 | 格式错误扣 6 分 | 严重 |
+| 错误返回格式 | PlatformException 格式 | OHOS 错误对象 | 格式不标准扣 4 分 | 中等 |
+
+**致命返回值错误示例**：
+
+```typescript
+// Dart: Future<void> setOptions(BluetoothOptions options)
+// ❌ 致命：返回设备列表而非 void
+return mConnectedDevices; // 返回 Map 类型，语义完全错误
+
+// ✅ 正确：
+return; // 或 return true 表示成功
+```
+
+### 1.4 异常传播一致性（10分）
+
+| 检查项 | 检查内容 | 扣分规则 | 致命度 |
+|--------|----------|----------|--------|
+| 异常类型映射 | PlatformException 类型 | 不映射扣 6 分 | 严重 |
+| 错误码一致性 | Android/iOS/OHOS 错误码对比 | 不一致扣 5 分 | 中等 |
+| 错误消息详细度 | 错误描述信息量对比 | 缺少诊断扣 4 分 | 中等 |
+| 错误码硬编码 | 是否固定值而非实际状态 | **硬编码扣 8 分** | 致命 |
+
+---
+
+## 2. 平台实现一致性检查
+
+### 2.1 Android vs OHOS 功能对比（25分）⚠️ 核心维度
+
+| 功能类别 | 检查项 | 扣分规则 | 致命度 |
+|----------|--------|----------|--------|
+| 核心功能缺失 | Android 有但 OHOS 无（适配缺陷） | **缺失扣 15 分** | 致命 |
+| 🔶 核心功能缺失 | Android 有但 OHOS 无（平台限制，鸿蒙无对应 API 且无替代路径） | **0 分（不扣分）** | 豁免 |
+| 功能行为不一致 | 同一功能行为差异 | **行为不一致扣 12 分** | 致命 |
+| 边界处理不一致 | 边界情况处理差异 | 不一致扣 8 分 | 严重 |
+| 错误处理不一致 | 同一错误处理差异 | 不一致扣 6 分 | 中等 |
+| 默认值不一致 | 配置默认值差异 | 不一致扣 4 分 | 轻微 |
+
+> 🔶 **平台限制判定规则**：详见 [PLATFORM_LIMITATION_GUIDE.md](PLATFORM_LIMITATION_GUIDE.md)。确认无法鸿蒙化的接口直接不扣分，无需检查文档化状态。
+
+**功能对比检查流程**：
+
+1. **提取 Android 方法列表**：
+   - 扫描 `android/src/main/java/` 或 `kotlin/` 目录
+   - 提取所有公开方法（public/override）
+   
+2. **逐一对比 OHOS 实现**：
+   - 检查 OHOS 是否有同名方法
+   - 检查方法是否为 stub（无实际操作）
+   - 检查方法是否返回错误消息
+
+3. **行为对比**：
+   - 对比核心功能调用链
+   - 检查参数处理逻辑
+   - 检查返回结果格式
+
+**Stub 方法检测清单**：
+
+| 检测特征 | 说明 | 扣分 |
+|----------|------|------|
+| 仅 return 固定值 | 如 `return true;` 无其他语句 | -8 分 |
+| 未调用 @ohos API | 未使用鸿蒙系统 API | -8 分 |
+| 未执行业务操作 | 无实际功能逻辑 | -8 分 |
+| 方法体为空 | 仅检查连接状态后返回 | -8 分 |
+
+**常见功能缺失项**：
+
+| 功能类型 | 常见缺失 | 扣分 |
+|----------|----------|------|
+| 设备管理 | removeBond、clearGattCache | 各 -15 分 |
+| 适配器管理 | getAdapterName、turnOff | 各 -15 分 |
+| 连接管理 | requestConnectionPriority | -12 分 |
+| 特征操作 | 缺少流控检查 | -8 分 |
+
+### 2.2 iOS vs OHOS 功能对比（15分）
+
+| 功能类别 | 检查项 | 扣分规则 | 致命度 |
+|----------|--------|----------|--------|
+| 核心功能缺失 | iOS 有但 OHOS 无（排除平台限制） | **缺失扣 12 分** | 严重 |
+| 平台限制一致 | OHOS 是否有与 iOS 类似限制 | 不一致扣 5 分 | 中等 |
+| 行为一致性 | 同一功能行为对比 | 不一致扣 8 分 | 严重 |
+
+**iOS 平台限制注意事项**：
+- MTU 协商：iOS 自动协商，无法主动请求
+- 绑定操作：iOS 有系统限制
+- 扫描过滤：iOS 需客户端过滤
+
+### 2.3 平台差异处理（10分）
+
+| 检查项 | 检查内容 | 扣分规则 | 致命度 |
+|--------|----------|----------|--------|
+| OHOS 限制标注 | OHOS 特有限制是否文档化 | 未标注扣 5 分 | 中等 |
+| 平台检测机制 | 是否有 Platform.isOHOS 检测 | 缺失扣 4 分 | 中等 |
+| 条件分支正确 | 平台特定逻辑分支 | 错误扣 6 分 | 严重 |
+| 平台差异文档 | 是否有 README 说明差异 | 未文档化扣 3 分 | 轻微 |
+
+---
+
+## 3. 命名一致性检查（15分）⚠️ 降低权重
+
+### 3.1 命名规范（10分）
+
+| 检查项 | Dart 规范 | ArkTS 规范 | 扣分规则 | 致命度 |
+|--------|-----------|------------|----------|--------|
+| 类名 PascalCase | ✅ PascalCase | ✅ PascalCase | 不规范扣 2 分 | 轻微 |
+| 方法名 camelCase | ✅ 动词开头 | ✅ 动词开头 | **大写开头扣 3 分** | 轻微 |
+| 参数名 camelCase | ✅ 语义明确 | ✅ 语义明确 | 不规范扣 1 分 | 轻微 |
+| 私有成员前缀 | _camelCase | #camelCase 或 mCamelCase | **不一致扣 2 分** | 轻微 |
+| 常量命名 | lowerCamelCase | const UPPER_CASE | 不统一扣 1 分 | 轻微 |
+
+**常见命名问题**：
+
+| 问题 | 示例 | 标准 | 扣分 |
+|------|------|------|------|
+| 方法名大写开头 | `ConnectStateChanged` | `connectStateChanged` | -3 |
+| 私有成员前缀混用 | `mConnectedDevices` vs `channel` | 统一使用 `m` 或无前缀 | -2 |
+| 回调方法大写 | `OnDiscoveredServices` | `onDiscoveredServices` | -3 |
+
+### 3.2 术语一致性（5分）
+
+| 检查项 | 检查内容 | 扣分规则 | 致命度 |
+|--------|----------|----------|--------|
+| 概念命名统一 | 同一概念所有平台相同名称 | 不一致扣 2 分 | 轻微 |
+| 缩写一致 | URL/ID/UUID 等缩写格式 | 不一致扣 1 分 | 轻微 |
+| 消息字段名 | MethodChannel 消息字段 | 不一致扣 2 分 | 轻微 |
+
+---
+
+## 4. 评分规则汇总
+
+### 4.1 严苛扣分制
+
+采用**严苛扣分制**，从 100 分开始扣减：
+
+```
+初始分数：100 分
+
+扣分类型与标准值：
+├── 致命问题：-15 分（最多扣 60 分）
+│   ├── 参数类型致命错误（bool → string 等）............. -15
+│   ├── OHOS 方法缺失（适配缺陷，非平台限制）............ -15
+│   ├── OHOS 方法为 stub（适配缺陷，非平台限制）......... -8
+│   ├── OHOS 方法返回错误而非实现......................... -10
+│   ├── 返回值类型/语义完全错误........................... -10
+│   ├── 功能行为致命不一致............................... -15
+│   └── 错误码硬编码固定值............................... -8
+│
+│   🔶 平台限制豁免（不扣分）：
+│   ├── OHOS 方法缺失（鸿蒙无对应系统 API 且无替代路径）.. 0/函数
+│   └── OHOS 方法为 stub（因平台限制无法实现）.......... 0/函数
+│
+├── 严重问题：-12 分
+│   ├── 功能行为严重不一致............................... -12
+│   ├── 异常传播不完整................................... -6
+│   ├── 核心功能部分缺失................................. -12
+│   ├── 参数数量不匹配................................... -8
+│   └── 返回值格式不标准................................. -6
+│
+├── 中等问题：-8 分
+│   ├── 边界处理不一致................................... -8
+│   ├── 错误消息缺少诊断信息............................. -4
+│   ├── 类型精度丢失..................................... -5
+│   └── 空值处理不完整................................... -8
+│
+├── 轻微问题：-3 分
+│   ├── 命名不规范....................................... -3
+│   ├── 术语不一致....................................... -2
+│   ├── 私有成员前缀不统一............................... -2
+│   └── 文档化不足....................................... -3
+
+特殊规则：
+├── 不存在 ohos 目录 → 0 分
+├── ohos 目录无代码 → 0 分
+├── 致命问题 ≥ 4 个 → 0 分
+├── 致命问题 ≥ 3 个 + 严重问题 ≥ 2 个 → 0 分
+├── 累计扣分超过 60 分 → 0 分
+
+最低分数：0 分
+```
+
+### 4.2 扣分示例计算
+
+```
+示例库评分计算：
+
+初始分数：100
+
+致命问题：
+├── force_indications 参数类型错误（bool → string）... -15
+├── removeBond 为 stub 方法............................ -8
+├── getAdapterName 返回错误............................ -10
+└── 3 个致命问题累计 -33 分
+
+严重问题：
+├── disconnect reason 硬编码........................... -8
+├── clearGattCache 🔶 平台限制（鸿蒙无 GATT 缓存 API）.. 0
+├── requestConnectionPriority 🔶 平台限制（鸿蒙无此 API）.. 0
+└── 1 个严重问题累计 -8 分
+
+中等问题：
+├── 边界处理不一致................................... -8
+├── 错误消息缺少诊断................................. -4
+└── 2 个中等问题累计 -12 分
+
+轻微问题：
+├── 方法名大写开头................................... -3
+├── 私有成员前缀不一致............................... -2
+└── 2 个轻微问题累计 -5 分
+
+总扣分：33 + 8 + 12 + 5 = 58 分
+最终得分：100 - 58 = 42 分
+
+（🔶 平台限制 2 项不扣分：clearGattCache、requestConnectionPriority）
+```
+
+---
+
+## 5. 检视流程清单
+
+### 5.1 前置准备
+
+| 步骤 | 操作 | 输出 |
+|------|------|------|
+| 1 | 检查 `ohos/` 目录存在性 | 目录状态判定 |
+| 2 | 扫描 `ohos/ets/` 文件列表 | ETS 文件清单 |
+| 3 | 扫描 `android/src/` 文件列表 | Android 方法清单 |
+| 4 | 扫描 `ios/Classes/` 文件列表 | iOS 方法清单 |
+| 5 | 读取 `接口规格说明.md` | API 接口定义 |
+
+### 5.2 API 契约检查流程
+
+| 步骤 | 检查项 | 记录内容 |
+|------|--------|----------|
+| 1 | 提取 OHOS 公开方法列表 | 方法名、参数、返回值 |
+| 2 | 对比 Dart 接口定义 | 方法签名一致性 |
+| 3 | 检查参数类型解析语句 | 类型映射正确性 |
+| 4 | 检查返回值类型 | 返回值语义正确性 |
+| 5 | 检查异常处理流程 | 异常传播完整性 |
+
+### 5.3 功能对比检查流程
+
+| 步骤 | 检查项 | 记录内容 |
+|------|--------|----------|
+| 1 | 提取 Android 公开方法列表 | 全部功能清单 |
+| 2 | 逐一检查 OHOS 实现 | 实现状态、是否 stub |
+| 3 | 对比核心功能调用链 | 行为一致性 |
+| 4 | 检查边界情况处理 | 边界处理一致性 |
+| 5 | 检查错误码映射 | 错误码一致性 |
+
+### 5.4 报告生成检查
+
+| 步骤 | 检查项 | 要求 |
+|------|--------|------|
+| 1 | 评分格式 | `**综合评分：XX/100**`（中文冒号） |
+| 2 | 扣分明细 | 每项扣分需有文件位置、代码片段 |
+| 3 | 功能对比表 | Android/iOS/OHOS 三列对比 |
+| 4 | 修复建议 | P0/P1/P2 优先级分类 |
+| 5 | 检视范围标注 | 明确标注检视和非检视目录 |
+
+---
+
+## 附录：常见问题速查
+
+### A. 参数类型错误速查
+
+| 错误类型 | 检测方法 | 典型代码 | 修复方案 |
+|----------|----------|----------|----------|
+| bool → string | 搜索 `as string` 参数解析 | `call.arguments['xxx'] as string` | 改为 `as boolean` |
+| int → string | 搜索 `as string` 数值解析 | `call.arguments['count'] as string` | 改为 `as number` |
+| List 类型混入 | 检查数组元素类型 | `as string[]` 但有 int 元素 | 使用 `as Object[]` |
+
+### B. Stub 方法速查
+
+| Stub 类型 | 检测特征 | 示例 | 正确实现 |
+|-----------|----------|------|----------|
+| 返回固定 true | `return true;` 无其他语句 | `async method() { return true; }` | 调用实际 API |
+| 仅检查连接 | 仅 `if (!connected) return false; return true;` | 缺少实际操作 | 添加业务逻辑 |
+| 返回错误消息 | 返回 `{error: "xxx"}` | `return {error: "not supported"}` | 实现或抛异常 |
+
+### C. 硬编码错误码速查
+
+| 错误类型 | 检测方法 | 典型代码 | 修复方案 |
+|----------|----------|----------|----------|
+| disconnect reason 固定 | 搜索 `code: 1` 或类似 | `{code: 1, reason: "xxx"}` | 传递实际状态码 |
+| 错误码固定值 | 搜索 `errorCode: X` | `errorCode: 100` | 使用系统错误码 |
+
+---
+
+**文档版本**：v2.0
+**更新时间**：2026-05-18
+**适用范围**：Flutter 三方库鸿蒙化一致性检视