@ohos-cpf/3rdloop 0.0.1 → 0.0.3

package/vendor/Server/Skills/arkts-code-check/references/CODE_CHECK_GUIDE.md

@@ -1,160 +1,211 @@
-# Phase 3：代码检视详细检查清单
-
-本文档包含 ArkTS 代码深度检视的完整检查项。
-
----
-
-## 3.1 非兼容变更（Breaking Changes）
-
-**判断依据**：改动前的接口若有外部调用方，则为破坏性变更。
-
-检查项：
-- [ ] 是否删除或重命名了公开 API / 导出符号 / 接口方法
-- [ ] 是否修改了函数签名（参数数量、类型、顺序、返回类型）
-- [ ] 是否修改了数据结构的字段类型或字段名
-- [ ] 是否修改了错误码或返回值语义
-- [ ] 是否修改了配置文件格式（`oh-package.json5`、`module.json5`）
-
----
-
-## 3.2 ArkTS 语言约束（严格模式合规性）
-
-- [ ] 无 `any` 类型使用（ArkTS 禁止 `as any`、隐式 any）
-- [ ] 无 `eval()`、`Function()` 动态代码执行
-- [ ] 无 `with` 语句
-- [ ] 无 `prototype` 动态修改
-- [ ] 无动态属性访问（`obj[dynamicKey]`）替代类型化接口
-- [ ] 接口声明使用 `interface` / `class`，非对象字面量类型构造函数
-- [ ] 枚举值使用 `enum`，非字符串字面量联合
-- [ ] 装饰器使用正确（`@Component`、`@State`、`@Prop`、`@Link`、`@Builder`、`@Observed` 等）
-- [ ] 泛型类型参数明确，避免推导歧义
-- [ ] 是否使用已废弃的 API（`@deprecated` 标注的接口）
-
----
-
-## 3.3 OpenHarmony API 兼容性
-
-- [ ] 新增 API 使用是否超出工程 `minAPIVersion`（通常 API 12+）
-- [ ] 是否使用了 OHOS 专有 API 但未做平台判断（`deviceInfo.deviceType` 等）
-- [ ] 权限申请是否正确（`requestPermissionsFromUser`）
-- [ ] `OH_*` 系列 C API 的返回值是否有检查（Native 模块场景）
-
----
-
-## 3.4 异步处理
-
-- [ ] 所有 `await` 调用不遗漏（BLE、网络、存储等异步 API）
-- [ ] try/catch 覆盖所有 `await` 调用，catch 块有实质性错误处理（非空 catch）
-- [ ] 嵌套 async 函数调用链中，返回的 Promise 均被正确 await
-- [ ] 未处理的 Promise rejection（`.catch()` 或 `try/catch` 必须存在）
-- [ ] 并行异步操作使用 `Promise.all`，避免不必要的顺序 await（性能）
-
----
-
-## 3.5 事件监听器管理（on/off 对称性）
-
-### 通用检查项
-
-- [ ] 每个 `on('eventName', handler)` 有对应 `off('eventName', handler)` 或 `off('eventName')`
-- [ ] 监听器在组件/连接销毁时（`aboutToDisappear`、设备断开、`close` 前）被移除
-- [ ] 重连场景中同一事件多次调用 `on` 不会造成监听器堆积
-- [ ] 新增的事件监听类型在 `close` / `disconnect` 前有对应 `off`
-
-### BLE / 蓝牙特有检视点
-
-- [ ] `GattClientDevice` 对象不跨连接复用（重连时创建新实例）
-- [ ] 连接失败路径中所有注册的监听器均被清除
-- [ ] 多设备并发时，Map key 使用设备地址（`remoteId`）而非类成员变量
-- [ ] 状态变更回调使用正确的设备标识（`key`），而非可能过期的实例变量
-
----
-
-## 3.6 索引变量与边界问题
-
-**索引变量误用示例**：
-```typescript
-// ❌ 错误
-for (let i = 0; i < services.length; i++) {
-  for (let j = 0; j < includeServices.length; j++) {
-    if (includeServices[i].uuid === target) { ... } // 应为 j
-  }
-}
-```
-
-检查项：
-- [ ] 嵌套循环中内层循环使用正确的索引变量
-- [ ] 查找逻辑中 null/undefined 判断方向正确（`== null` vs `!= null`）
-- [ ] 数组访问是否有越界风险（空数组判断）
-
----
-
-## 3.7 错误处理
-
-- [ ] 错误信息包含错误码（`e.code`）和错误描述（`e.message`）
-- [ ] `result.error()` / `result.success()` 调用后有 `return`，避免后续代码继续执行
-- [ ] switch-case 中每个 case 末尾有 `break`（避免 fall-through）
-- [ ] 提前 `return` / `break` 不会跳过必要的资源清理
-
----
-
-## 3.8 内存与资源管理
-
-- [ ] 事件监听器在适当时机 `off`（组件销毁、设备断开等）
-- [ ] 定时器（`setInterval`/`setTimeout`）有对应 `clearInterval`/`clearTimeout`
-- [ ] `ArrayBuffer` / `Uint8Array` 大数据用完后无强引用持有
-- [ ] Map / Set 数据结构在不再需要时及时 `delete` / `clear`
-
----
-
-## 3.9 并发与线程安全
-
-- [ ] 是否在非 UI 线程访问 UI 组件（需通过 `TaskPool`/`Worker` 隔离）
-- [ ] async/await 使用正确，无遗漏 await 导致的竞态条件
-- [ ] 多设备并发连接场景下，变量为实例级而非全局/类级共享
-
----
-
-## 3.10 性能问题
-
-- [ ] 列表渲染是否使用 `LazyForEach` + `@Reusable` 优化（大列表场景）
-- [ ] 是否有同步阻塞主线程的操作（应改用 `TaskPool`/`Worker`）
-- [ ] 是否存在不必要的全局变量或重复对象创建
-- [ ] 图片资源是否合理使用缓存，避免重复加载
-
----
-
-## 3.11 安全性
-
-- [ ] 无硬编码的密钥、Token、密码、MAC 地址等敏感信息
-- [ ] 网络请求是否校验 HTTPS 证书（禁止忽略证书错误）
-- [ ] 用户输入是否有校验和过滤（防注入）
-- [ ] 文件路径是否有安全校验（防路径穿越）
-- [ ] 敏感数据是否在日志中输出（蓝牙配对码、账户信息等）
-
----
-
-## 3.12 依赖与配置
-
-- [ ] `oh-package.json5` 新增依赖是否合理，来源是否可信
-- [ ] 版本号是否符合语义化版本规范（`^x.y.z`）
-- [ ] `minAPIVersion` / `targetAPIVersion` 变更是否合理
-- [ ] 是否存在不必要的依赖或版本锁定过死
-
----
-
-## 3.13 代码规范
-
-- [ ] 命名遵循驼峰命名规则（变量/方法小驼峰，类/接口大驼峰）
-- [ ] 无冗余的 `console.log` 调试代码遗留
-- [ ] 公共 API 有完整 JSDoc 注释
-- [ ] 文件头版权声明完整
-
----
-
-## 问题严重程度分级
-
-| 级别 | 标识 | 说明 |
-|------|------|------|
-| Blocker | 🔴 | 必须修复，会导致功能异常、崩溃、安全漏洞或破坏向后兼容性 |
-| Major | 🟡 | 强烈建议修复，存在潜在风险或明显质量问题 |
+# Phase 3：代码检视详细检查清单
+
+本文档包含 ArkTS 代码深度检视的完整检查项。
+
+---
+
+## 3.1 非兼容变更（Breaking Changes）
+
+**判断依据**：改动前的接口若有外部调用方，则为破坏性变更。
+
+检查项：
+- [ ] 是否删除或重命名了公开 API / 导出符号 / 接口方法
+- [ ] 是否修改了函数签名（参数数量、类型、顺序、返回类型）
+- [ ] 是否修改了数据结构的字段类型或字段名
+- [ ] 是否修改了错误码或返回值语义
+- [ ] 是否修改了配置文件格式（`oh-package.json5`、`module.json5`）
+
+---
+
+## 3.2 ArkTS 语言约束（严格模式合规性）
+
+- [ ] 无 `any` 类型使用（ArkTS 禁止 `as any`、隐式 any）
+- [ ] 无 `eval()`、`Function()` 动态代码执行
+- [ ] 无 `with` 语句
+- [ ] 无 `prototype` 动态修改
+- [ ] 无动态属性访问（`obj[dynamicKey]`）替代类型化接口
+- [ ] 接口声明使用 `interface` / `class`，非对象字面量类型构造函数
+- [ ] 枚举值使用 `enum`，非字符串字面量联合
+- [ ] 装饰器使用正确（`@Component`、`@State`、`@Prop`、`@Link`、`@Builder`、`@Observed` 等）
+- [ ] 泛型类型参数明确，避免推导歧义
+- [ ] 是否使用已废弃的 API（`@deprecated` 标注的接口）
+
+---
+
+## 3.3 OpenHarmony API 兼容性
+
+- [ ] 新增 API 使用是否超出工程 `minAPIVersion`（通常 API 12+）
+- [ ] 是否使用了 OHOS 专有 API 但未做平台判断（`deviceInfo.deviceType` 等）
+- [ ] 权限申请是否正确（`requestPermissionsFromUser`）
+- [ ] `OH_*` 系列 C API 的返回值是否有检查（Native 模块场景）
+
+---
+
+## 3.4 异步处理
+
+- [ ] 所有 `await` 调用不遗漏（BLE、网络、存储等异步 API）
+- [ ] try/catch 覆盖所有 `await` 调用，catch 块有实质性错误处理（非空 catch）
+- [ ] 嵌套 async 函数调用链中，返回的 Promise 均被正确 await
+- [ ] 未处理的 Promise rejection（`.catch()` 或 `try/catch` 必须存在）
+- [ ] 并行异步操作使用 `Promise.all`，避免不必要的顺序 await（性能）
+
+---
+
+## 3.5 事件监听器管理（on/off 对称性）
+
+### 通用检查项
+
+- [ ] 每个 `on('eventName', handler)` 有对应 `off('eventName', handler)` 或 `off('eventName')`
+- [ ] 监听器在组件/连接销毁时（`aboutToDisappear`、设备断开、`close` 前）被移除
+- [ ] 重连场景中同一事件多次调用 `on` 不会造成监听器堆积
+- [ ] 新增的事件监听类型在 `close` / `disconnect` 前有对应 `off`
+
+### BLE / 蓝牙特有检视点
+
+- [ ] `GattClientDevice` 对象不跨连接复用（重连时创建新实例）
+- [ ] 连接失败路径中所有注册的监听器均被清除
+- [ ] 多设备并发时，Map key 使用设备地址（`remoteId`）而非类成员变量
+- [ ] 状态变更回调使用正确的设备标识（`key`），而非可能过期的实例变量
+
+---
+
+## 3.6 索引变量与边界问题
+
+**索引变量误用示例**：
+```typescript
+// ❌ 错误
+for (let i = 0; i < services.length; i++) {
+  for (let j = 0; j < includeServices.length; j++) {
+    if (includeServices[i].uuid === target) { ... } // 应为 j
+  }
+}
+```
+
+检查项：
+- [ ] 嵌套循环中内层循环使用正确的索引变量
+- [ ] 查找逻辑中 null/undefined 判断方向正确（`== null` vs `!= null`）
+- [ ] 数组访问是否有越界风险（空数组判断）
+
+---
+
+## 3.7 错误处理
+
+- [ ] 错误信息包含错误码（`e.code`）和错误描述（`e.message`）
+- [ ] `result.error()` / `result.success()` 调用后有 `return`，避免后续代码继续执行
+- [ ] switch-case 中每个 case 末尾有 `break`（避免 fall-through）
+- [ ] 提前 `return` / `break` 不会跳过必要的资源清理
+
+---
+
+## 3.8 内存与资源管理
+
+- [ ] 事件监听器在适当时机 `off`（组件销毁、设备断开等）
+- [ ] 定时器（`setInterval`/`setTimeout`）有对应 `clearInterval`/`clearTimeout`
+- [ ] `ArrayBuffer` / `Uint8Array` 大数据用完后无强引用持有
+- [ ] Map / Set 数据结构在不再需要时及时 `delete` / `clear`
+
+---
+
+## 3.9 并发与线程安全
+
+- [ ] 是否在非 UI 线程访问 UI 组件（需通过 `TaskPool`/`Worker` 隔离）
+- [ ] async/await 使用正确，无遗漏 await 导致的竞态条件
+- [ ] 多设备并发连接场景下，变量为实例级而非全局/类级共享
+
+---
+
+## 3.10 性能问题
+
+- [ ] 列表渲染是否使用 `LazyForEach` + `@Reusable` 优化（大列表场景）
+- [ ] 是否有同步阻塞主线程的操作（应改用 `TaskPool`/`Worker`）
+- [ ] 是否存在不必要的全局变量或重复对象创建
+- [ ] 图片资源是否合理使用缓存，避免重复加载
+
+---
+
+## 3.11 安全性
+
+- [ ] 无硬编码的密钥、Token、密码、MAC 地址等敏感信息
+- [ ] 网络请求是否校验 HTTPS 证书（禁止忽略证书错误）
+- [ ] 用户输入是否有校验和过滤（防注入）
+- [ ] 文件路径是否有安全校验（防路径穿越）
+- [ ] 敏感数据是否在日志中输出（蓝牙配对码、账户信息等）
+
+---
+
+## 3.12 依赖与配置
+
+- [ ] `oh-package.json5` 新增依赖是否合理，来源是否可信
+- [ ] 版本号是否符合语义化版本规范（`^x.y.z`）
+- [ ] `minAPIVersion` / `targetAPIVersion` 变更是否合理
+- [ ] 是否存在不必要的依赖或版本锁定过死
+
+---
+
+## 3.13 代码规范
+
+- [ ] 命名遵循驼峰命名规则（变量/方法小驼峰，类/接口大驼峰）
+- [ ] 无冗余的 `console.log` 调试代码遗留
+- [ ] 公共 API 有完整 JSDoc 注释
+- [ ] 文件头版权声明完整
+
+---
+
+## 3.14 静态检查工具使用规范（arkts_check）
+
+> ⚠️ 使用独立 arkts_check 工具对 PR 文件做静态检查时必须遵守以下规范，避免假阴性与误报污染检视结论。
+
+### 3.14.1 必须使用绝对路径调用
+
+- 以**相对路径**（如 `entry/src/ohosTest/...`）批量调用 arkts_check 会产生**假阴性**：工具返回 "No errors found"，但改用绝对路径复查同一文件立即报出真实错误（含 `arkts-no-any-unknown` 违规）
+- 相对路径批量调用静默漏检，若直接采信会得出"零静态检查问题"的错误结论，直接影响合入分级
+- 必要时用一个"已知有问题的文件"做**阳性对照**，验证工具确实在检查
+
+### 3.14.2 环境误报甄别（不计入问题统计）
+
+- `Cannot find module '@ohos/*'` 类错误：独立 linter 无法解析 ohpm 本地依赖（`@ohos/xxx` → `file:../library`）产生的环境限制误报，**不计入问题统计**
+- 批量调用可能实际检查目录内全部文件（含 master 既有文件），输出混入非目标文件错误；需对工具保存的完整输出**按目标文件名 grep 过滤**后再统计，或单文件逐个检查（更可控）
+
+### 3.14.3 基线对照法（区分 PR 引入 vs 历史存量）
+
+对 master 既有文件（本 PR 未修改的文件）运行同样的静态检查作为**基线**：
+
+- 既有文件的违规基数 = 历史存量，与本 PR 无关
+- PR 新增文件的报错需与基线对照后，仅将**超出基线的新增违规**计入 PR 问题
+- 实际案例：mp3agic PR #53 中 master 既有测试文件基线为 125+ 错误（大量历史存量 `arkts-no-any-unknown`），而 PR 新增代码仅 1 处真实违规，显著优于仓库基线
+
+---
+
+## 3.15 测试型 PR 检查清单
+
+> 纯测试补充型 PR（不修改库源码）的检视核心是**验证测试本身正确**。此类 PR 的问题通常集中在合规与代码卫生而非功能，分级时应避免因"零功能风险"直接放行 PASS。
+
+### 三层交叉验证
+
+1. **导入符号核验**
+   - 深路径导入（`@ohos/xxx/src/main/ets/...`）逐一确认目标文件存在
+   - 根入口导入确认符号在 `library/index.ets` 导出面中
+   - 深路径导入若为仓库既有模式（grep 既有测试确认），不作为问题上报
+
+2. **构造函数签名比对**
+   - 测试调用与库源码构造签名逐一比对（参数数量、类型、顺序）
+
+3. **夹具数据解码核验**
+   - 对 base64 内嵌夹具本地解码（python3 + base64），核验文件头/长度/关键 offset/关键字节与测试断言值吻合
+
+### 配套检查项
+
+- [ ] **测试脚手架与库内部契约链路**：测试 setup 依赖的库未文档化行为（如 `GlobalContext` 键名的写入/读取）必须到库源码中确认精确对应，否则测试在其他环境可能静默失败
+- [ ] **未使用导入检测**：对测试文件按 import 符号 grep 计数（出现 ≤1 次即未使用）
+- [ ] **新文件 License 头一致性**：对照仓库既有测试文件的头格式，缺失即报合规问题（OAT 扫描风险）——测试型 PR 极易遗漏此项
+- [ ] **测试文件头注释与实现一致性**：夹具机制注释与实际实现不符会误导维护者，应抽查（如注释写"从 rawfile 复制"而实现是 base64 内嵌解码）
+
+---
+
+## 问题严重程度分级
+
+| 级别 | 标识 | 说明 |
+|------|------|------|
+| Blocker | 🔴 | 必须修复，会导致功能异常、崩溃、安全漏洞或破坏向后兼容性 |
+| Major | 🟡 | 强烈建议修复，存在潜在风险或明显质量问题 |
 | Minor | 🔵 | 优化建议，不影响功能，属于代码质量/可读性改进 |

package/vendor/Server/Skills/arkts-code-check/references/FILE_TYPE_GUIDE.md

@@ -1,29 +1,29 @@
-# 文件类型识别指南
-
-本文档说明如何识别和分类 PR 中修改的文件类型。
-
----
-
-## 文件类型分类
-
-| 扩展名 | 类型 | 检视重点 |
-|--------|------|----------|
-| `.ets` | ArkTS 源文件 | 语言约束、装饰器、UI 逻辑 |
-| `.ts` | TypeScript | 类型安全、异步、事件监听 |
-| `CMakeLists.txt` / `*.cmake` | 构建系统 | Native 模块构建依赖 |
-| `build-profile.json5` | 工程配置 | API Level、签名 |
-| `oh-package.json5` | 包依赖 | 依赖版本、新增依赖合理性 |
-| `module.json5` / `app.json5` | 模块配置 | 权限申请、minAPIVersion |
-
----
-
-## 改动性质分类
-
-| 性质 | 说明 |
-|------|------|
-| 新增功能 | 新增 API、组件、模块 |
-| 功能修复 | Bug 修复、逻辑修正 |
-| 功能优化 | 性能优化、重构 |
-| 配置更新 | 依赖、版本、权限变更 |
-| 文档更新 | 注释、README、文档 |
+# 文件类型识别指南
+
+本文档说明如何识别和分类 PR 中修改的文件类型。
+
+---
+
+## 文件类型分类
+
+| 扩展名 | 类型 | 检视重点 |
+|--------|------|----------|
+| `.ets` | ArkTS 源文件 | 语言约束、装饰器、UI 逻辑 |
+| `.ts` | TypeScript | 类型安全、异步、事件监听 |
+| `CMakeLists.txt` / `*.cmake` | 构建系统 | Native 模块构建依赖 |
+| `build-profile.json5` | 工程配置 | API Level、签名 |
+| `oh-package.json5` | 包依赖 | 依赖版本、新增依赖合理性 |
+| `module.json5` / `app.json5` | 模块配置 | 权限申请、minAPIVersion |
+
+---
+
+## 改动性质分类
+
+| 性质 | 说明 |
+|------|------|
+| 新增功能 | 新增 API、组件、模块 |
+| 功能修复 | Bug 修复、逻辑修正 |
+| 功能优化 | 性能优化、重构 |
+| 配置更新 | 依赖、版本、权限变更 |
+| 文档更新 | 注释、README、文档 |
 | 测试补充 | 单元测试、集成测试 |