@ohos-cpf/3rdloop 0.0.2 → 0.0.4

package/vendor/Server/Skills/flutter-library-test-coverage-check/references/SCORING_RULES.md

@@ -1,265 +1,265 @@
-# 评分规则详解
-
-> 本文档详细说明 Flutter 三方库用例覆盖度检视的评分体系、扣分规则和一票否决规则。
-
----
-
-## 1. 评分体系总览
-
-**初始分数：100 分**，采用扣分制计算最终得分。
-
-| 维度 | 满分 | 扣分上限 | 核心检查内容 |
-|------|------|----------|--------------|
-| 测试结构完整性 | 15 | -15 | 测试目录、文件结构、框架使用 |
-| 公开接口覆盖率 | 40 | -40 | **核心：测试/demo 对接口的覆盖比例** |
-| 测试场景覆盖 | 25 | -25 | 正常、异常、边界、并发场景 |
-| 测试代码质量 | 20 | -20 | 命名、独立性、可重复性、清理 |
-| **总计** | **100** | **-100** | - |
-
----
-
-## 2. 一票否决规则（优先检查）
-
-以下任一条件触发时，**直接判定 0 分**，不再进行正常评分：
-
-| 条件 | 说明 |
-|------|------|
-| 无任何测试文件 | `test/` 目录不存在或无 `_test.dart` 文件 |
-| **接口覆盖率未达 100%** | 测试覆盖率 < 100% **且** Demo 覆盖率 < 100%（两者之一达 100% 即可豁免） |
-| 累计扣分 > 60 分 | 正常评分流程中累计扣分超过 60 |
-
-### 一票否决判定流程
-
-```
-1. 检查测试文件是否存在
-   → 无测试文件 → ❌ 直接 0 分
-
-2. 从脚本报告读取覆盖率
-   - XTS 覆盖率（来自 flutter-analyze-xts-coverage.cjs 报告）
-   - Demo 覆盖率（来自 flutter-analyze-demo-coverage.cjs 报告）
-
-3. 判定接口覆盖率一票否决
-   - XTS 覆盖率 = 100% → ✅ 豁免
-   - Demo 覆盖率 = 100% → ✅ 豁免
-   - 两者均 < 100% → ❌ 直接 0 分
-
-4. 若一票否决未触发，进入正常评分
-   → 累计扣分 > 60 → ❌ 直接 0 分
-```
-
-> ⚠️ **覆盖率数据来源**：XTS 覆盖率和 Demo 覆盖率直接从脚本生成的 Markdown 报告中读取"方法级覆盖率"数值。脚本排除 constant/enumValue/constructor 类型，只计算 method/property/field/function/type/variable 的覆盖率。
-
----
-
-## 3. 维度一：测试结构完整性（满分 15 分）
-
-### 3.1 测试目录检查
-
-| 检查项 | 规范要求 | 扣分规则 |
-|--------|----------|----------|
-| 测试目录存在 | 至少存在一个测试目录 | **缺失扣 15 分（致命）** |
-| 测试文件数量 | ≥1 个测试文件 | **缺失扣 10 分** |
-| 测试文件命名 | 以 `_test.dart` 结尾 | 不规范扣 3 分/文件 |
-| 测试目录组织 | 有合理的子目录结构 | 无组织扣 2 分 |
-
-### 3.2 测试框架使用检查
-
-| 检查项 | 规范要求 | 扣分规则 |
-|--------|----------|----------|
-| flutter_test 使用 | pubspec.yaml 配置 flutter_test | **缺失扣 5 分** |
-| mock 框架使用 | 使用 mockito 或 fake | 未使用扣 3 分 |
-| 测试覆盖率工具 | 配置 test_coverage 或 coverage | 未配置扣 2 分 |
-
-### 3.3 example 目录检查
-
-| 检查项 | 规范要求 | 扣分规则 |
-|--------|----------|----------|
-| example 目录存在 | 有示例应用目录 | 缺失扣 5 分 |
-| demo 调用核心接口 | demo 调用了 Dart 公开接口 | 未调用核心接口扣 3 分 |
-| demo 代码可运行 | example 应用可正常编译运行 | 不可运行扣 2 分 |
-
----
-
-## 4. 维度二：公开接口覆盖率（满分 40 分，核心维度）
-
-### 4.1 覆盖率数据来源
-
-覆盖率数据**直接从脚本报告读取**，无需手动计算：
-
-| 数据项 | 来源 | 报告位置 |
-|--------|------|----------|
-| 测试覆盖率 | `flutter-analyze-xts-coverage.cjs` 报告 | "方法级覆盖率"行 |
-| Demo 覆盖率 | `flutter-analyze-demo-coverage.cjs` 报告 | "方法级覆盖率"行 |
-| 类级覆盖率明细 | 两个报告的"类级覆盖率"表 | 每个类的覆盖数/未覆盖数/覆盖率 |
-| 未覆盖接口清单 | 两个报告的"未覆盖接口详情"章节 | 按类分组的未覆盖接口 |
-
-### 4.2 测试覆盖率扣分规则
-
-> 仅在一票否决规则未触发时适用（即测试覆盖率或 Demo 覆盖率至少一个达 100%）。
-
-| 覆盖率范围 | 扣分值 | 说明 |
-|------------|--------|------|
-| 100% | 0 分 | 完全覆盖 |
-| ≥ 80% | -4 分 | 覆盖率较高 |
-| 60%-79% | -8 分 | 中等缺失 |
-| 40%-59% | -16 分 | 严重缺失 |
-| 20%-39% | -24 分 | 严重缺失 |
-| 10%-19% | -32 分 | 非常严重缺失 |
-| 5%-9% | -38 分 | 几乎无测试 |
-| < 5% | **直接 0 分** | 致命缺失 |
-
-### 4.3 Demo 补充覆盖抵扣规则
-
-```
-若某接口未在 test/ 中被测试，但在 example/ 的 demo 中被调用：
-- 视为"有使用验证"，可抵扣 50% 的该接口缺失扣分
-- 但总抵扣上限为 5 分（demo 不能完全替代正式测试）
-
-示例：
-- 接口 A 未测试，扣 2 分，但 demo 调用了 → 实际扣 1 分
-- 接口 B 未测试，扣 3 分，但 demo 调用了 → 实际扣 1.5 分
-- 总抵扣不超过 5 分
-```
-
-### 4.4 综合覆盖率计算
-
-```
-综合覆盖率 = 测试覆盖率 + Demo 补充覆盖率（权重 0.3）
-
-最终扣分 = 基于综合覆盖率计算（规则同 4.2），但允许 demo 补充抵扣（上限 5 分）
-```
-
-### 4.5 覆盖率不足原因分析（不减免扣分）
-
-| 原因类型 | 典型场景 | 扣分处理 |
-|----------|----------|----------|
-| **平台通道限制** | BLE/硬件依赖 MethodChannel | **不减免**，应通过 mock 测试 |
-| Mock 机制缺失 | 未创建 MethodChannel mock | **严苛扣分**，测试设计缺陷 |
-| 测试设计遗漏 | 纯 Dart 逻辑未测试（如 Guid） | **严苛扣分**，无借口 |
-| 代码复杂度高 | 接口逻辑复杂 | **不减免**，复杂更需测试 |
-| 开发者懒惰 | 未重视测试 | **严苛扣分** |
-
-> ⚠️ **重要**：Flutter 提供了完整的测试支持（`MethodChannel.setMockMethodCallHandler`），即使是依赖平台通道的接口也应通过 mock 进行测试验证。**不应以"平台依赖"为借口减免扣分**。
-
----
-
-## 5. 维度三：测试场景覆盖（满分 25 分）
-
-### 5.1 测试场景分类检查
-
-| 场景类型 | 检查内容 | 扣分规则 |
-|----------|----------|----------|
-| **正常场景** | 测试正常输入和预期输出 | 缺失扣 5 分 |
-| **异常场景** | 测试异常输入、错误处理、超时 | **缺失扣 8 分** |
-| **边界场景** | 测试空值、极值、边界条件 | 缺失扣 5 分 |
-| **并发场景** | 测试并发调用、多设备连接 | 缺失扣 7 分 |
-
-### 5.2 异常场景细化检查
-
-| 异常类型 | 检查项 | 扣分规则 |
-|----------|--------|----------|
-| 参数异常 | 无效参数、null 参数测试 | 缺失扣 3 分 |
-| 状态异常 | 设备断开、适配器关闭测试 | **缺失扣 4 分** |
-| 超时异常 | 操作超时处理测试 | 缺失扣 3 分 |
-| 权限异常 | 权限缺失场景测试 | 缺失扣 2 分 |
-
----
-
-## 6. 维度四：测试代码质量（满分 20 分）
-
-### 6.1 测试命名规范
-
-| 检查项 | 规范要求 | 扣分规则 |
-|--------|----------|----------|
-| 测试组命名 | 使用 `group()` 组织测试 | 未使用扣 3 分 |
-| 测试描述清晰 | 描述测试目的和行为 | 不清晰扣 2 分/测试 |
-| BDD 风格 | 使用 should/when/then 模式 | 未使用扣 1 分 |
-
-### 6.2 测试独立性
-
-| 检查项 | 规范要求 | 扣分规则 |
-|--------|----------|----------|
-| 无顺序依赖 | 测试可任意顺序运行 | **有依赖扣 5 分** |
-| 无共享状态 | 测试间不共享可变状态 | 有共享扣 4 分 |
-| 正确清理 | setUp/tearDown 正确使用 | **未使用扣 6 分** |
-| 无外部依赖 | 不依赖网络/外部服务（或 mock） | **有依赖扣 5 分** |
-
-### 6.3 测试可重复性
-
-| 检查项 | 规范要求 | 扣分规则 |
-|--------|----------|----------|
-| 结果一致 | 多次运行结果相同 | 不一致扣 4 分 |
-| 无随机数据 | 使用固定测试数据 | 有随机扣 3 分 |
-| 无时间依赖 | 不依赖当前时间（或 mock） | 有依赖扣 2 分 |
-
----
-
-## 7. 最终评分计算
-
-```
-初始分数 = 100 分
-
-【一票否决判定】（优先检查）：
-1. 无任何测试文件 → 直接 0 分
-2. 测试覆盖率 < 100% 且 Demo 覆盖率 < 100% → 直接 0 分
-   （test/ 或 example/ 任意一个达到 100% 覆盖即可豁免）
-3. 累计扣分 > 60 → 直接 0 分
-
-【正常评分】（一票否决未触发时）：
-各维度扣分：
-- 测试结构扣分：max(-15, 实际扣分)
-- 公开接口覆盖率扣分：max(-40, 实际扣分)  ← 核心维度
-- 测试场景覆盖扣分：max(-25, 实际扣分)
-- 测试代码质量扣分：max(-20, 实际扣分)
-
-最终得分 = max(0, 100 - 总扣分)
-```
-
----
-
-## 8. 正确的 Mock 测试示例
-
-```dart
-// ✅ 正确：通过 mock MethodChannel 测试平台依赖接口
-test('connect should call method channel and update state', () async {
-  // 设置 mock handler
-  MethodChannel.setMockMethodCallHandler(
-    FlutterBluePlus.methodChannel,
-    (MethodCall call) async {
-      if (call.method == 'connect') {
-        return {'status': 'connected'};
-      }
-      return null;
-    },
-  );
-
-  // 测试 Dart 层接口
-  final device = BluetoothDevice.fromId('test-device-id');
-  await device.connect(timeout: Duration(seconds: 10));
-
-  // 验证状态更新
-  expect(device.isConnected, true);
-});
-
-// ✅ 正确：测试异常场景
-test('connect should throw on timeout', () async {
-  MethodChannel.setMockMethodCallHandler(
-    FlutterBluePlus.methodChannel,
-    (MethodCall call) async {
-      if (call.method == 'connect') {
-        await Future.delayed(Duration(seconds: 20));
-        return null;
-      }
-      return null;
-    },
-  );
-
-  final device = BluetoothDevice.fromId('test-id');
-  expect(
-    () => device.connect(timeout: Duration(seconds: 5)),
-    throwsA(isA<TimeoutException>()),
-  );
-});
-```
-
-> 即使底层是鸿蒙/Android/iOS 实现，Dart 层接口也应该通过 mock 进行测试验证。
+# 评分规则详解
+
+> 本文档详细说明 Flutter 三方库用例覆盖度检视的评分体系、扣分规则和一票否决规则。
+
+---
+
+## 1. 评分体系总览
+
+**初始分数：100 分**，采用扣分制计算最终得分。
+
+| 维度 | 满分 | 扣分上限 | 核心检查内容 |
+|------|------|----------|--------------|
+| 测试结构完整性 | 15 | -15 | 测试目录、文件结构、框架使用 |
+| 公开接口覆盖率 | 40 | -40 | **核心：测试/demo 对接口的覆盖比例** |
+| 测试场景覆盖 | 25 | -25 | 正常、异常、边界、并发场景 |
+| 测试代码质量 | 20 | -20 | 命名、独立性、可重复性、清理 |
+| **总计** | **100** | **-100** | - |
+
+---
+
+## 2. 一票否决规则（优先检查）
+
+以下任一条件触发时，**直接判定 0 分**，不再进行正常评分：
+
+| 条件 | 说明 |
+|------|------|
+| 无任何测试文件 | `test/` 目录不存在或无 `_test.dart` 文件 |
+| **接口覆盖率未达 100%** | 测试覆盖率 < 100% **且** Demo 覆盖率 < 100%（两者之一达 100% 即可豁免） |
+| 累计扣分 > 60 分 | 正常评分流程中累计扣分超过 60 |
+
+### 一票否决判定流程
+
+```
+1. 检查测试文件是否存在
+   → 无测试文件 → ❌ 直接 0 分
+
+2. 从脚本报告读取覆盖率
+   - XTS 覆盖率（来自 flutter-analyze-xts-coverage.cjs 报告）
+   - Demo 覆盖率（来自 flutter-analyze-demo-coverage.cjs 报告）
+
+3. 判定接口覆盖率一票否决
+   - XTS 覆盖率 = 100% → ✅ 豁免
+   - Demo 覆盖率 = 100% → ✅ 豁免
+   - 两者均 < 100% → ❌ 直接 0 分
+
+4. 若一票否决未触发，进入正常评分
+   → 累计扣分 > 60 → ❌ 直接 0 分
+```
+
+> ⚠️ **覆盖率数据来源**：XTS 覆盖率和 Demo 覆盖率直接从脚本生成的 Markdown 报告中读取"方法级覆盖率"数值。脚本排除 constant/enumValue/constructor 类型，只计算 method/property/field/function/type/variable 的覆盖率。
+
+---
+
+## 3. 维度一：测试结构完整性（满分 15 分）
+
+### 3.1 测试目录检查
+
+| 检查项 | 规范要求 | 扣分规则 |
+|--------|----------|----------|
+| 测试目录存在 | 至少存在一个测试目录 | **缺失扣 15 分（致命）** |
+| 测试文件数量 | ≥1 个测试文件 | **缺失扣 10 分** |
+| 测试文件命名 | 以 `_test.dart` 结尾 | 不规范扣 3 分/文件 |
+| 测试目录组织 | 有合理的子目录结构 | 无组织扣 2 分 |
+
+### 3.2 测试框架使用检查
+
+| 检查项 | 规范要求 | 扣分规则 |
+|--------|----------|----------|
+| flutter_test 使用 | pubspec.yaml 配置 flutter_test | **缺失扣 5 分** |
+| mock 框架使用 | 使用 mockito 或 fake | 未使用扣 3 分 |
+| 测试覆盖率工具 | 配置 test_coverage 或 coverage | 未配置扣 2 分 |
+
+### 3.3 example 目录检查
+
+| 检查项 | 规范要求 | 扣分规则 |
+|--------|----------|----------|
+| example 目录存在 | 有示例应用目录 | 缺失扣 5 分 |
+| demo 调用核心接口 | demo 调用了 Dart 公开接口 | 未调用核心接口扣 3 分 |
+| demo 代码可运行 | example 应用可正常编译运行 | 不可运行扣 2 分 |
+
+---
+
+## 4. 维度二：公开接口覆盖率（满分 40 分，核心维度）
+
+### 4.1 覆盖率数据来源
+
+覆盖率数据**直接从脚本报告读取**，无需手动计算：
+
+| 数据项 | 来源 | 报告位置 |
+|--------|------|----------|
+| 测试覆盖率 | `flutter-analyze-xts-coverage.cjs` 报告 | "方法级覆盖率"行 |
+| Demo 覆盖率 | `flutter-analyze-demo-coverage.cjs` 报告 | "方法级覆盖率"行 |
+| 类级覆盖率明细 | 两个报告的"类级覆盖率"表 | 每个类的覆盖数/未覆盖数/覆盖率 |
+| 未覆盖接口清单 | 两个报告的"未覆盖接口详情"章节 | 按类分组的未覆盖接口 |
+
+### 4.2 测试覆盖率扣分规则
+
+> 仅在一票否决规则未触发时适用（即测试覆盖率或 Demo 覆盖率至少一个达 100%）。
+
+| 覆盖率范围 | 扣分值 | 说明 |
+|------------|--------|------|
+| 100% | 0 分 | 完全覆盖 |
+| ≥ 80% | -4 分 | 覆盖率较高 |
+| 60%-79% | -8 分 | 中等缺失 |
+| 40%-59% | -16 分 | 严重缺失 |
+| 20%-39% | -24 分 | 严重缺失 |
+| 10%-19% | -32 分 | 非常严重缺失 |
+| 5%-9% | -38 分 | 几乎无测试 |
+| < 5% | **直接 0 分** | 致命缺失 |
+
+### 4.3 Demo 补充覆盖抵扣规则
+
+```
+若某接口未在 test/ 中被测试，但在 example/ 的 demo 中被调用：
+- 视为"有使用验证"，可抵扣 50% 的该接口缺失扣分
+- 但总抵扣上限为 5 分（demo 不能完全替代正式测试）
+
+示例：
+- 接口 A 未测试，扣 2 分，但 demo 调用了 → 实际扣 1 分
+- 接口 B 未测试，扣 3 分，但 demo 调用了 → 实际扣 1.5 分
+- 总抵扣不超过 5 分
+```
+
+### 4.4 综合覆盖率计算
+
+```
+综合覆盖率 = 测试覆盖率 + Demo 补充覆盖率（权重 0.3）
+
+最终扣分 = 基于综合覆盖率计算（规则同 4.2），但允许 demo 补充抵扣（上限 5 分）
+```
+
+### 4.5 覆盖率不足原因分析（不减免扣分）
+
+| 原因类型 | 典型场景 | 扣分处理 |
+|----------|----------|----------|
+| **平台通道限制** | BLE/硬件依赖 MethodChannel | **不减免**，应通过 mock 测试 |
+| Mock 机制缺失 | 未创建 MethodChannel mock | **严苛扣分**，测试设计缺陷 |
+| 测试设计遗漏 | 纯 Dart 逻辑未测试（如 Guid） | **严苛扣分**，无借口 |
+| 代码复杂度高 | 接口逻辑复杂 | **不减免**，复杂更需测试 |
+| 开发者懒惰 | 未重视测试 | **严苛扣分** |
+
+> ⚠️ **重要**：Flutter 提供了完整的测试支持（`MethodChannel.setMockMethodCallHandler`），即使是依赖平台通道的接口也应通过 mock 进行测试验证。**不应以"平台依赖"为借口减免扣分**。
+
+---
+
+## 5. 维度三：测试场景覆盖（满分 25 分）
+
+### 5.1 测试场景分类检查
+
+| 场景类型 | 检查内容 | 扣分规则 |
+|----------|----------|----------|
+| **正常场景** | 测试正常输入和预期输出 | 缺失扣 5 分 |
+| **异常场景** | 测试异常输入、错误处理、超时 | **缺失扣 8 分** |
+| **边界场景** | 测试空值、极值、边界条件 | 缺失扣 5 分 |
+| **并发场景** | 测试并发调用、多设备连接 | 缺失扣 7 分 |
+
+### 5.2 异常场景细化检查
+
+| 异常类型 | 检查项 | 扣分规则 |
+|----------|--------|----------|
+| 参数异常 | 无效参数、null 参数测试 | 缺失扣 3 分 |
+| 状态异常 | 设备断开、适配器关闭测试 | **缺失扣 4 分** |
+| 超时异常 | 操作超时处理测试 | 缺失扣 3 分 |
+| 权限异常 | 权限缺失场景测试 | 缺失扣 2 分 |
+
+---
+
+## 6. 维度四：测试代码质量（满分 20 分）
+
+### 6.1 测试命名规范
+
+| 检查项 | 规范要求 | 扣分规则 |
+|--------|----------|----------|
+| 测试组命名 | 使用 `group()` 组织测试 | 未使用扣 3 分 |
+| 测试描述清晰 | 描述测试目的和行为 | 不清晰扣 2 分/测试 |
+| BDD 风格 | 使用 should/when/then 模式 | 未使用扣 1 分 |
+
+### 6.2 测试独立性
+
+| 检查项 | 规范要求 | 扣分规则 |
+|--------|----------|----------|
+| 无顺序依赖 | 测试可任意顺序运行 | **有依赖扣 5 分** |
+| 无共享状态 | 测试间不共享可变状态 | 有共享扣 4 分 |
+| 正确清理 | setUp/tearDown 正确使用 | **未使用扣 6 分** |
+| 无外部依赖 | 不依赖网络/外部服务（或 mock） | **有依赖扣 5 分** |
+
+### 6.3 测试可重复性
+
+| 检查项 | 规范要求 | 扣分规则 |
+|--------|----------|----------|
+| 结果一致 | 多次运行结果相同 | 不一致扣 4 分 |
+| 无随机数据 | 使用固定测试数据 | 有随机扣 3 分 |
+| 无时间依赖 | 不依赖当前时间（或 mock） | 有依赖扣 2 分 |
+
+---
+
+## 7. 最终评分计算
+
+```
+初始分数 = 100 分
+
+【一票否决判定】（优先检查）：
+1. 无任何测试文件 → 直接 0 分
+2. 测试覆盖率 < 100% 且 Demo 覆盖率 < 100% → 直接 0 分
+   （test/ 或 example/ 任意一个达到 100% 覆盖即可豁免）
+3. 累计扣分 > 60 → 直接 0 分
+
+【正常评分】（一票否决未触发时）：
+各维度扣分：
+- 测试结构扣分：max(-15, 实际扣分)
+- 公开接口覆盖率扣分：max(-40, 实际扣分)  ← 核心维度
+- 测试场景覆盖扣分：max(-25, 实际扣分)
+- 测试代码质量扣分：max(-20, 实际扣分)
+
+最终得分 = max(0, 100 - 总扣分)
+```
+
+---
+
+## 8. 正确的 Mock 测试示例
+
+```dart
+// ✅ 正确：通过 mock MethodChannel 测试平台依赖接口
+test('connect should call method channel and update state', () async {
+  // 设置 mock handler
+  MethodChannel.setMockMethodCallHandler(
+    FlutterBluePlus.methodChannel,
+    (MethodCall call) async {
+      if (call.method == 'connect') {
+        return {'status': 'connected'};
+      }
+      return null;
+    },
+  );
+
+  // 测试 Dart 层接口
+  final device = BluetoothDevice.fromId('test-device-id');
+  await device.connect(timeout: Duration(seconds: 10));
+
+  // 验证状态更新
+  expect(device.isConnected, true);
+});
+
+// ✅ 正确：测试异常场景
+test('connect should throw on timeout', () async {
+  MethodChannel.setMockMethodCallHandler(
+    FlutterBluePlus.methodChannel,
+    (MethodCall call) async {
+      if (call.method == 'connect') {
+        await Future.delayed(Duration(seconds: 20));
+        return null;
+      }
+      return null;
+    },
+  );
+
+  final device = BluetoothDevice.fromId('test-id');
+  expect(
+    () => device.connect(timeout: Duration(seconds: 5)),
+    throwsA(isA<TimeoutException>()),
+  );
+});
+```
+
+> 即使底层是鸿蒙/Android/iOS 实现，Dart 层接口也应该通过 mock 进行测试验证。