@ohos-cpf/3rdloop 0.0.7 → 0.0.9

package/vendor/Archive/data/docs/experiences/rn-upstream-version-diff-pitfalls.md

@@ -0,0 +1,17 @@
+## RN 上游版本 diff 操作踩坑集（grep 二进制 / CHANGELOG 来源 / patch 噪音 / 平台并行文件）
+
+### 问题现象
+对比上游两个 npm tgz 版本生成 patch 与检索 release notes 时的操作性坑：
+1. 全量 patch 中 `grep "^diff"` 报 "Binary file matches"
+2. CHANGELOG.md 不在 npm tgz 内，无法从源码包获取上游 release notes
+3. 脚本生成的 patch 仍包含 android/ios 原生平台代码与 .DS_Store 噪音（280KB 中大部分是原生变更）
+4. 上游共享实现（如 `Camera.tsx`）与平台特化文件（`.android.tsx` / `.ios.tsx`）是三份并行文件，只 diff 入口 index.ts 会漏掉平台文件变更（实测：共享版无变更但平台版有 props 默认值注入变更）
+
+### 解决方案
+1. patch 含二进制文件（.DS_Store/gradle 等）时用 `grep -a` 强制文本模式
+2. release notes 从 GitHub Releases 页面获取（webfetch releases 页可行；raw CHANGELOG.md 可能超时）
+3. 两阶段 diff 是必要的：Phase 1 全量 → Phase 2 按相关文件清单筛选精简，不能信任脚本的默认排除已覆盖 patch 本身
+4. diff 时显式覆盖共享实现与平台特化文件（`.tsx` / `.android.tsx` / `.ios.tsx` 三份并行），不能只看入口文件
+
+### 结果
+Phase 2 精简后 patch 从 280KB 缩至 9.3KB（7 文件），平台文件的 props 默认值注入变更未被遗漏，patch 可直接用于后续适配。

package/vendor/Archive/data/docs/experiences/rn-version-gap-risk-rating-rules.md

@@ -0,0 +1,13 @@
+## RN 库版本差距双口径记录与风险评级规则
+
+### 问题现象
+版本差距报告只记录单一口径（至任务指定版本或至 npm latest 之一）会误导升级决策；同时 major 版本号跨度容易被直接当作 breaking change 信号，导致风险高估或低估。
+
+### 解决方案
+1. **双口径记录**：同时给出「至任务指定版本」与「至 npm latest」两档差距，并在升级建议中提示可顺带对齐 latest patch。实测：camera-kit npm dist-tags.latest 为 18.0.1，任务指定对比 18.0.0，18.0.1 仅含 iOS 修复。
+2. **major ≠ breaking change**：major 版本号不等于 breaking change，须逐条核对 CHANGELOG 的 breaking 项是否触及 JS 层接口契约：
+   - camera-kit 18.0.0 官方明确声明「No known breaking changes were done」，major 仅为预防性标记（新增人脸检测）
+   - 17.0.0 的 breaking（移除 `iOsSleepBeforeStarting`）是原生侧 only 属性，16.1.3 的 JS Spec 中本就不存在，对 JS 接口契约无影响，可降级处理
+
+### 结果
+风险评级基于「breaking 项是否触及 JS 层契约」逐条核对而非版本号跨度，评级更准确；双口径让升级决策同时看到至指定版本与至最新版的差距。

package/vendor/Archive/data/docs/experiences/rn-view-lib-native-contract-diff-fabric-spec.md

@@ -0,0 +1,16 @@
+## RN View 型库的原生接口契约必须同时覆盖 Fabric 组件 Spec
+
+### 问题现象
+对 RN 三方库做版本差异分析时，diff 脚本（rn-scan-exports.cjs / generate-diff.js）自动判定为「✅ 无需原生适配 — 接口未变更」，但对 react-native-camera-kit（16.1.3 → 18.0.0）实测该结论是**假阴性**：上游 `src/specs/CameraNativeComponent.ts`（Fabric 组件 Spec，`codegenNativeComponent` 输入）新增了 4 个 props（faceDetectionEnabled / faceDetectionThrottleMs / allowedBarcodeTypes / iOsDeferredStart）+ 2 个事件（onFaceDetected / onFaceDetectionInstallStatus）。Fabric 组件 Spec 是 codegen 的直接输入，其变更意味着鸿蒙侧必须：① 同步更新组件 Spec 文件 → ② 重跑 codegen（generated/ ETS+C++ 产物变化）→ ③ ETS 原生层实现新 props/事件（人脸检测为全新原生能力）。
+
+### 解决方案
+RN 库的原生接口契约 = **TurboModule Spec + Fabric Component Spec 两部分**，只检查前者会漏掉 View 型库的主要原生变更面：
+
+- 脚本的「TurboModule Spec 变更」检查只覆盖 `src/specs/Native*Module.ts`，不覆盖组件 Spec 文件
+- 脚本判定后，务必**人工 diff** `src/specs/*Component*.ts`（或所有 `codegenNativeComponent` 输入文件），重点检查：
+  - `NativeProps` / 组件 interface 的 props 增删
+  - `DirectEventHandler` / `BubblingEventHandler` 事件增删
+- 判定矩阵：**TurboModule Spec 变更 OR 组件 Spec 变更 → 需要原生适配（codegen + 原生实现）**
+
+### 结果
+camera-kit 正确结论为「需要原生适配（类型 A）」，人工复核推翻了脚本假阴性结论。相机/播放器/地图/WebView 等 View 型库尤其常见组件 Spec 变更，是脚本自动判定的重灾区；分析报告中应显式记录对自动结论的修正及原因，避免下游直接采信脚本结论。

package/vendor/Archive/data/docs/experiences/rnoh-adapter-package-version-field-semantics.md

@@ -0,0 +1,18 @@
+## RNOH 鸿蒙适配包版本字段双层语义（re-export 架构）
+
+### 问题现象
+验收/核验 RNOH 三方库升级时，按字面直读 `packages/{lib}/package.json` 的 `version` 字段会误判核验失败。典型案例：react-native-mmkv 升级到上游 4.3.2 后，`@react-native-ohos/react-native-mmkv` 包的 `version` 仍为 4.0.0，且与交付物 tgz 文件名 `react-native-ohos-react-native-mmkv-4.0.0.tgz` 一致——这并非升级不到位。
+
+### 解决方案
+鸿蒙适配包采用 re-export 架构（JS 层仅 re-export 上游 npm 包）时，版本字段具有双层语义：
+- `version` 字段 = 鸿蒙适配包**自身**的版本号（历史沿袭，可能与上游版本完全不同步），与交付物 tgz 文件名对应；
+- `dependencies` 中的上游源库条目（如 `"react-native-mmkv": "4.3.2"`）= 实际生效的上游版本，上游升级即依赖升级。
+
+核验步骤：
+1. 先读版本差异分析报告，确认包架构（re-export / 源内复制 / fork）——不同架构下"上游版本"所在字段不同；
+2. re-export 架构 → 检查 `dependencies` 中上游源库条目；源内复制 → 检查 `version` 或源码内版本标注；
+3. 与交付物 tgz 文件名交叉确认适配包自身版本；
+4. 在核验记录中显式写明该语义说明，避免后续循环再次踩坑。
+
+### 结果
+react-native-mmkv（上游 4.3.1→4.3.2）核验实测：`version: 4.0.0` 为适配包自身版本（升级全程未变），`dependencies.react-native-mmkv: 4.3.2` 为上游版本，判定核验通过。可复用结论：RNOH 三方库（@react-native-ohos/*）核验版本时，永远同时看 `version`（适配包自身）与 `dependencies`（上游源库）两个字段，并与 tgz 文件名交叉确认。

package/vendor/Archive/data/docs/experiences/rnoh-arkts-sqlite-rows-array-format.md

@@ -0,0 +1,18 @@
+## RNOH sqlite 库 ArkTS 层 SELECT 返回 rows 为数组，与上游 iOS/Android 形态不一致
+
+### 问题现象
+
+react-native-sqlite-storage 的鸿蒙实现中，SELECT 查询返回 `{rowsAffected, rows: [...]}`（**rows 为数组**，见 SQLitePluginTurboModule.ts 的 `queryResultcall = { 'rowsAffected': 0, 'rows': results }`），而上游 iOS/Android 返回 RS 对象（`{length, item(i)}`）。照搬上游示例的取值代码（如 `rows.item(0)` 或 `rows.length`）在鸿蒙侧行为异常。
+
+### 解决方案
+
+Demo/测试代码必须兼容两种形态：
+
+```typescript
+const row = Array.isArray(rows) ? rows[0] : rows.item(0);
+const count = Array.isArray(rows) ? rows.length : rows.length;
+```
+
+### 结果
+
+同一份 Demo 代码在鸿蒙与 iOS/Android 形态下均可正常取值。**鸿蒙化库写 Demo 时不能照搬上游示例的返回值取用代码**，必须先查证鸿蒙侧 TurboModule 的实际返回结构（读 `harmony/` 模块源码中 methodMap 对应实现）。

package/vendor/Archive/data/docs/experiences/rnoh-dependency-residue-scan-strategy.md

@@ -0,0 +1,18 @@
+## RNOH 依赖残留分层判定与大仓库扫描安全策略
+
+### 问题现象
+1. 三方库升级后扫描"旧版本依赖残留"时，`grep -rn '"pkg": "0.82...' example packages` 在含 node_modules（example npm install 后数百 MB）的仓库上 120s 超时被强制终止。
+2. 扫描发现 devDependencies 中存在旧版本工具链（如 `@react-native/eslint-config: 0.82.0`）时，直接判"核验失败"或隐藏不报都是错误处置。
+
+### 解决方案
+**扫描执行安全**（解决超时与误报）：
+- 用 `rg` 替代 `grep` 全量扫描，并叠加排除参数：`-g '!node_modules' -g '!oh_modules' -g '!package-lock.json' -g '!*.har' -g '!*.hap' -g '!\.git'`
+- 只扫依赖清单白名单文件：根/example 的 package.json、oh-package.json5、nitro.json、overrides/resolutions
+- 只匹配 RNOH 框架相关包名的版本号模式（react-native / react-native-harmony / @rnoh/react-native-openharmony / nitro-modules / harmony-cli）
+
+**残留分层判定**（二分法）：
+- **框架/运行时/编译链依赖（阻断项）**：属于 RNOH 框架依赖、参与编译链（HAR→tgz→codegen→JS Bundle→ohpm→devecocli build）或参与运行时的旧版本引用 → 判核验失败；
+- **开发工具依赖滞后（记录项）**：如 ESLint 配置等代码风格工具，不参与编译链与运行时 → 非阻断。定性时做三对照：上游基线版本（diff-output 中上游 package.json）+ example 侧同款版本 + 编译链涉及范围。
+
+### 结果
+实测 30s 内完成扫描、零误报；`@react-native/eslint-config: 0.82.0` 判定为低风险 devDep 遗留（上游 4.3.2 基线用 0.85.3，example 侧同款已升 0.84.1）。处置原则：如实写入核验记录"遗留记录"节 + 给出风险定性（低风险）+ 不阻断验收。隐藏不报或直接判失败都是错误的。

package/vendor/Archive/data/docs/experiences/rnoh-example-local-lib-dep-use-tgz.md

@@ -0,0 +1,53 @@
+## RNOH example 本地库依赖必须用 npm pack tgz，禁止 file: 目录形式
+
+### 问题现象
+
+为 RN 鸿蒙三方库创建 example 工程时，在 `example/package.json` 中用目录形式的本地依赖（如 `"@react-native-ohos/xxx": "file:.."` 指向库根目录），`npm install` 后 node_modules 中该包为**符号链接**（`lrwxr-xr-x ... -> ../../..`，链接目标在 example 工程目录之外）。执行 `npm run dev` 报错：
+
+```
+Unable to resolve module @react-native-ohos/... could not be found within the project
+```
+
+原因：npm（实测 11.6.2）对目录型 `file:` 依赖默认以 symlink 方式安装，Metro/watchman 文件解析不跟随工程目录外的符号链接。
+
+### 解决方案
+
+1. 库根先在 `.npmignore` 中排除 `example`（否则整个 example 工程会被打进库包）
+2. 库根执行 `npm pack` 生成 `react-native-ohos-{包名去scope横线}-{版本}.tgz`
+3. example 依赖改为 `file:../{tgz文件名}`（如 `"file:../react-native-ohos-netinfo-12.0.1.tgz"`）
+4. 删除 node_modules 中旧符号链接后重新 `npm install` → node_modules 中变为实体目录
+
+同步的库根工程卫生：
+- `.gitignore` 追加 `harmony/{module}/oh_modules`、`harmony/{module}/oh-package-lock.json5`（ohpm --all 会在库源码模块内产生构建产物）
+- tgz 产物留在库根是 CPF-RN 系列仓库（netinfo、async-storage 等）的既定惯例
+
+### 结果
+
+node_modules 中库包为实体目录，Metro 解析正常，`npm run dev` 与鸿蒙编译全链路通过。CPF-RN 系列仓库的 example 均采用 tgz 方式，这是既定惯例，不要用 `file:..` 目录形式。
+
+---
+
+### 补充：node_modules 布局变更后必须清 Metro/watchman 缓存
+
+### 问题现象
+
+将 symlink 依赖替换为实体 tgz 目录后重跑构建，报错：
+
+```
+TreeFS: Could not add directory node_modules/@react-native-ohos/xxx ... already exists in the file map as a file
+```
+
+原因：Metro 文件映射缓存仍记录旧路径（该路径曾被记录为文件）。
+
+### 解决方案
+
+```bash
+rm -rf node_modules/.cache
+watchman watch-del-all
+```
+
+（或至少 `watchman watch-del` 当前工程）后重跑构建。
+
+### 结果
+
+构建成功。经验法则：**任何 node_modules 结构调整（symlink↔实体、删除重装）后都要清缓存再构建**。

package/vendor/Archive/data/docs/experiences/rnoh-example-prereserve-rntesterlist.md

@@ -0,0 +1,17 @@
+## 创建 RNOH example 壳层时必须预置 RNTesterList.ts 注册入口
+
+### 问题现象
+
+下游技能（rnoh-lib-demo-create / rnoh-cptf-api-test）探查 Demo 注册入口的**第一优先级是 `{projectRoot}/**/RNTesterList.ts`**（模式 A：`{key, category, module: require(...)}` 数组），而 example 模板原生只有 `App.tsx + tests/index.tsx` 模式、不含 RNTesterList——两者存在断层，导致后续 Demo 生成步骤探查不到注册入口。
+
+### 解决方案
+
+创建 example 壳层时在 `src/RNTesterList.ts` **预置模式 A 注册入口**：
+
+- 首项指向 `{exampleDir}/{libName}` 的 index.tsx（结构：`{key: '{libName}', category: '{category}', module: require('./{libName}')}`）
+- `App.tsx` 消费该列表渲染 Navigation 页面
+- 同时预置 1 个冒烟 Demo（如 sqlite 库的 openDatabase→executeSql→close 全链路）验证注册链路与原生桥通，保证不是空壳
+
+### 结果
+
+后续 Demo 生成步骤只需向 RNTesterList.ts 数组追加 `{key, category, module}` 条目即完成注册，与下游技能（rnoh-lib-demo-create 等）的探查逻辑（RNTesterList.ts 第一优先级）无缝衔接。

package/vendor/Archive/data/docs/experiences/rnoh-example-template-compatiblesdkversion-upgrade.md

@@ -0,0 +1,29 @@
+## RNOH example 模板 compatibleSdkVersion 必须手动升级
+
+### 问题现象
+从 RN3rdTemplate 模板仓库获取的 example 工程默认 `compatibleSdkVersion: '5.0.0(12)'`（API 12），但 RNOH 0.84 的 HAR 包元数据声明最低需要 API 17。构建时报错：
+```
+Error Message: The project's compatibleSdkVersion: 12 cannot be lower than the minimum compatible version 17 required by the dependencies: @react-native-ohos/netinfo.
+```
+此错误属于 `Specification Limit Violation`，构建直接失败。
+
+### 解决方案
+从 RN3rdTemplate 获取 example 模板后，必须手动升级 `example/harmony/build-profile.json5` 中的 `compatibleSdkVersion`：
+
+```json5
+// 修改前（模板默认）
+"compatibleSdkVersion": "5.0.0(12)"
+
+// 修改后（RNOH 0.84 要求）
+"compatibleSdkVersion": "5.0.5(17)"
+```
+
+**API 版本对应表**：
+| RNOH 版本 | 最低 API 版本 | compatibleSdkVersion |
+|-----------|-------------|---------------------|
+| 0.77 | 14 | 5.0.2(14) |
+| 0.82 | 15 | 5.0.3(15) |
+| 0.84 | 17 | 5.0.5(17) |
+
+### 结果
+升级 compatibleSdkVersion 后，`devecocli build` 不再报 `Specification Limit Violation` 错误，构建正常通过。此步骤是从模板创建 example 工程后的必做操作。

package/vendor/Archive/data/docs/experiences/rnoh-example-turbomodule-shell-adaptation-checklist.md

@@ -0,0 +1,41 @@
+## RNOH TurboModule 库 example 壳层适配清单与渐进式验证链
+
+### 问题现象
+
+基于 RNOH 模板为 TurboModule 三方库创建 example 壳层工程时，模板不能直接编译目标库，需适配多个 JS/Harmony 侧文件；且一次性做鸿蒙编译排查问题成本高。
+
+### 解决方案
+
+**壳层适配必查清单**（已在 sqlite-storage 库全量验证）：
+
+| 文件 | 适配内容 |
+|------|----------|
+| `harmony/entry/oh-package.json5` | 库 HAR 走 `file:../../node_modules/{ohPkg}/harmony/{module}.har` |
+| `harmony/entry/src/main/cpp/CMakeLists.txt` | `add_subdirectory` 指向 **node_modules**（严禁 oh_modules，HAR 无 cpp 源码）：`${NODE_MODULES}/{ohPkg}/{sourceModulePath}/src/main/cpp` |
+| `harmony/entry/src/main/cpp/PackageProvider.cpp` | include + make_shared `<cppPackageClassName>` |
+| `harmony/entry/src/main/ets/RNPackagesFactory.ets` | import 自 `<ohPkg>/ts`，new `<etsPackageClassName>`(ctx) |
+| `harmony/entry/src/main/ets/pages/Index.ets` | 纯 TurboModule 库：buildCustomRNComponent 保持空、arkTsComponentNames 为空数组 |
+| `harmony/build-profile.template.json5` | modules 追加库源码模块 `{name: '{harmonyModuleName}', srcPath: '../../harmony/{module}'}`；删除 `useNormalizedOHMUrl`；改 template 而非 build-profile.json5（postinstall 会覆盖） |
+| `module.json5` | 权限最小化（如 sqlite 仅 INTERNET；模板残留的 CAMERA/MICROPHONE 应删除） |
+| `metro.config.js` / `tsconfig.json` | `<alias>` → `node_modules/<ohPkg>` 映射 |
+
+**渐进式验证链**（全部通过的标准动作）：
+
+```
+1. cd example && npm install --legacy-peer-deps        # postinstall 生成 build-profile.json5
+2. npm run dev                                          # codegen + bundle-harmony → rawfile/bundle.harmony.js
+3. cd harmony && ohpm install --all                     # HAR 从 node_modules 经 file: 解析
+4. hvigorw assembleHap --no-daemon                      # CMake/Ninja + HAP 打包
+5. nm -gU .../librnoh_app.so | grep <cppPackageClassName>  # 确认库 C++ 包符号已链入
+```
+
+### 结果
+
+全链路 BUILD SUCCESSFUL。要点：
+
+- 第 2 步（npm run dev）就能暴露 alias/依赖问题，**成本最低，不要跳过直接做鸿蒙编译**
+- bundle 产物可 grep 校验：应含 Demo 特征字符串（如 `smoke_test.db`）、不应含模板残留（如 `camera`）
+- 未配置 signingConfigs 时产出 **unsigned HAP 属预期**（模板不携带签名证书），不是构建失败；真机部署前在 build-profile.json5 补签名即可
+- hvigor 调用方式：`/Applications/DevEco-Studio.app/Contents/tools/node/bin/node /Applications/DevEco-Studio.app/Contents/tools/hvigor/bin/hvigorw.js assembleHap --no-daemon`（用 DevEco 自带 node）
+- RNOH **0.82** 的 `compatibleSdkVersion: '5.0.0(12)'` 可直接使用；知识库中"必须升级 API 17"的经验仅适用于 0.84
+- 创建 example 前先读库元数据（package.json 的 harmony.autolinking 字段），所有壳层文件的类名/路径/链接目标均由它派生，不要手抄

package/vendor/Archive/data/docs/experiences/rnoh-mcp-build-project-tool-risk.md

@@ -0,0 +1,18 @@
+## MCP deveco-mcp_build_project 工具可能构建错误项目
+
+### 问题现象
+使用 MCP `deveco-mcp_build_project` 工具对鸿蒙工程执行构建时，返回 `BUILD SUCCESSFUL` 但实际并未构建工作目录中的目标工程。该工具似乎使用 DevEco Studio 当前打开的项目，而非命令行指定的工作目录中的项目。如果仅依赖 MCP 工具的构建结果，会误认为编译通过而实际未通过。
+
+### 解决方案
+不要使用 MCP `deveco-mcp_build_project` 工具进行编译验证，改用 `devecocli build` 命令在项目目录中执行构建：
+
+```bash
+# 在 example/harmony 目录下执行
+cd example/harmony
+devecocli build --product default --build-mode debug
+```
+
+`devecocli build` 会自动解析模块依赖并在当前目录的工程上下文中执行构建，确保构建的是正确的项目。
+
+### 结果
+使用 `devecocli build` 后，构建结果准确反映当前工作目录工程的编译状态。避免了因 MCP 工具构建了错误项目而误判编译通过的陷阱。此问题在多任务并行开发时尤为危险——可能构建了另一个任务的工程而误认为当前任务编译通过。

package/vendor/Archive/data/docs/experiences/rnoh-npm-devdependencies-version-precheck.md

@@ -0,0 +1,29 @@
+## RN 框架升级时 npm devDependencies 版本可用性预检
+
+### 问题现象
+升级 RN 框架版本时（如 0.82→0.84），更新 package.json 中的 devDependencies 版本后执行 `npm install`，部分包因目标版本在 npm registry 中不存在而导致安装失败：
+- `@types/react-test-renderer@^19.2.0` — npm registry 中最高仅 19.1.0（无 19.2.x）
+- `react-native-macos@^0.84.1` — npm registry 中最高仅 0.81.9（尚未发布 0.84 对应版本）
+
+### 解决方案
+在更新 devDependencies 版本前，先使用 `npm view` 命令检查目标版本是否存在：
+
+```bash
+# 检查包的所有可用版本
+npm view <package> versions --json
+
+# 检查最新版本
+npm view <package> version
+```
+
+对于可能没有对应版本发布的包，使用兼容范围版本而非精确版本：
+- `@types/react-test-renderer` → 使用 `^19.0.0`（实际最高 19.1.0）
+- `react-native-macos` → 使用 `^0.81.9`（实际最高 0.81.9）
+
+**需特别关注的包**（可能滞后于 RN 主版本发布）：
+- `react-native-macos` — macOS 平台适配，通常滞后
+- `@types/react-test-renderer` — 类型定义包，可能滞后于 React 版本
+- 其他平台特定包（@types/*, react-native-windows 等）
+
+### 结果
+使用兼容范围版本后，`npm install --legacy-peer-deps` 成功完成，无版本解析失败错误。通过预检可以避免因版本不存在导致的安装失败，减少反复修改 package.json 的工作量。

package/vendor/Archive/data/docs/experiences/rnoh-repo-baseline-version-verification.md

@@ -0,0 +1,13 @@
+## 鸿蒙化仓库基线版本核验：任务指定的分支-基线组合可能不符
+
+### 问题现象
+任务指定「br_rnoh0.77 分支鸿蒙化基线版本 16.1.3」，实际核验发现 br_rnoh0.77 分支的 package.json 版本为 15.1.2（README.OpenSource 上游基线 15.1.0），而 16.1.3 基线（commit ca7aa46，含 82 项框架适配）实际在 **master 分支**。直接按任务描述假设分支-基线组合会导致 diff 基线选错。
+
+### 解决方案
+对任务指定的「分支-基线」组合一律先核验（可靠性从高到低）：
+1. `README.OpenSource` 的 `Version Number` 字段 — **最可靠**，是鸿蒙化仓库的权威声明
+2. `git log --all --grep="<版本号>"` + `git branch -a --contains <commit>` 定位版本提交所在分支
+3. `git show origin/<branch>:package.json` 交叉验证各分支的 package.json 版本
+
+### 结果
+核验后输出各分支版本矩阵（分支 × package.json 版本 × README.OpenSource 上游基线），在报告开篇显式澄清实际基线所在分支，避免下游基于错误基线做 diff 或升级。

package/vendor/Archive/data/docs/experiences/rnoh-repo-upstream-directory-mapping.md

@@ -0,0 +1,18 @@
+## 鸿蒙化仓库与上游的 JS 层目录结构存在系统性映射差异
+
+### 问题现象
+鸿蒙化仓库并非原样保留上游 src/ 结构，直接按上游路径合并 patch 时文件定位失败。以 react-native-camera-kit 为例的系统性映射差异：
+
+| 上游路径 | 鸿蒙仓库对应 |
+|----------|-------------|
+| `src/specs/CameraNativeComponent.ts` | `src/CameraKitNativeComponent.ts`（重命名+扩展） |
+| `src/types.ts` | `types/types.ts` |
+| `src/CameraProps.ts` | `types/CameraProps.ts` |
+| `src/Camera.android.tsx` / `Camera.ios.tsx` | `src/Camera.tsx`（自有实现，DeviceEventEmitter 桥接） |
+| `src/specs/NativeCameraKitModule.ts` | `src/NativeCameraKit.tsx` |
+
+### 解决方案
+合并 patch 前先建立「上游→鸿蒙」目录映射表（覆盖 Spec 文件、types、平台实现文件、codegen 脚本入口的对应关系），再按映射表转写文件变更，**不得假设鸿蒙仓库保留上游目录结构**。另注意 codegen 入口不同：鸿蒙侧使用自有脚本（如 camera-kit 的 `scripts/codegen-lib.js`，调用 react-native-harmony-cli 的 `commandCodegenLibHarmony`，指定 cpp/arkts 双输出）。
+
+### 结果
+按映射表转写后，Phase 2 精简 patch 从 280KB 缩至 9.3KB / 7 个相关文件；映射表可直接供后续 code-adapt 适配阶段引用，避免二次人工摸索路径。

package/vendor/Archive/data/docs/experiences/rnoh-stateless-library-zero-leak-verification.md

@@ -0,0 +1,31 @@
+# RNOH 无状态库"零泄露面"穷尽验证模式集
+
+### 问题现象
+
+RN 三方库鸿蒙化为纯 TurboModule 形态（无 NativeComponent），业务能力全部映射到鸿蒙系统静态一次性 API（如 `WebCookieManager` 的 fetchCookie/configCookieSync 等）时，整个实现呈现"零状态"特征：无事件监听（无 on/off、无 NativeEventEmitter/DeviceEventEmitter）、无 Map/Set/缓存容器、无实例字段、C++ 层为纯无捕获静态 host function 转发（零 NAPI 调用、零 new/malloc）。对这类库，内存检视重点应从"释放是否完整"转向"是否真的不存在隐藏的持有"，需要穷尽验证后才能下"零泄露面"结论。
+
+### 解决方案
+
+用以下 rg 模式集做穷尽验证（全库 0 命中即可确认零泄露面）：
+
+```bash
+# 1. 生命周期/监听/订阅
+rg -n "__onDestroy__|onDestroy|aboutToDisappear|onDropViewInstance|addListener|removeListener|EventEmitter|addEventListener" <ets/cpp/js 目录>
+# 2. 鸿蒙 on/off 订阅对
+rg -n "\.on\(|\.off\(" <ets 目录>
+# 3. 容器与静态状态
+rg -n "Map<|Set<|static |private " <ets 目录> --glob '*.ts' --glob '*.ets'
+# 4. C++ 内存与 NAPI（仅手写文件）
+rg -n "new |malloc|napi_|delete |free\(" <cpp 目录> -g '<手写文件 pattern>'
+# 5. 定时器
+rg -n "setInterval|setTimeout" <ets 目录>
+```
+
+要点：
+- C++ 检查必须区分手写文件与 `generated/` 目录（用 `-g` 限定只查手写文件），避免 codegen 产物干扰统计。
+- codegen 生成的空壳文件（EventEmitters/Props/ShadowNodes 等）单独确认"空实现无资源"即可，不逐文件深查。
+- codegen 组件空壳快速判定：无 NativeComponent 的库 codegen 仍会生成组件文件，看 Package 头文件（如 `BaseReactNativeXXXPackage.h`）中 `createComponentDescriptorProviders()`/`createComponentJSIBinderByName()` 返回值是否为空集合、`supportedComponentNames/supportedEventNames` 是否为空 vector——是则整组组件文件按空壳处理，NativeComponent 维度记"不适用"而非"通过"。
+
+### 结果
+
+rntpc_cookies（@react-native-ohos/cookies）实测六组模式全部 0 命中，确认零泄露面，内存检视评分 95/100（仅 1 处死代码单例轻微扣 5 分）。该验证模式集可作为所有 RNOH 鸿蒙化库无状态判定的标准流程，避免遗漏隐藏持有。

package/vendor/Archive/data/docs/experiences/rnoh-template-npmrc-credential-removal.md

@@ -0,0 +1,15 @@
+## RNOH 模板拷贝后必须立即删除含凭据的 .npmrc
+
+### 问题现象
+
+从模板创建 RNOH example 工程时，模板目录可能自带 `.npmrc`，其中内嵌私有 registry（如 swmansion）的 GitHub PAT **明文 `_authToken`**，且拷贝脚本默认不排除该文件，凭据会随交付物扩散。
+
+### 解决方案
+
+1. 拷贝模板后**第一件事**：检查并删除 `.npmrc`
+2. RNOH 0.82 全部依赖（`@react-native-oh/react-native-harmony` 0.82.30+ 等）可从公共 registry（npmmirror）解析，无需私有源
+3. 建议拷贝模板脚本显式排除 `.npmrc`；若需保留 registry 配置，改用不含 token 的镜像地址
+
+### 结果
+
+交付物中无凭据泄露。**任何含凭据的文件（.npmrc token、签名私钥等）严禁带入交付物**。

package/vendor/Archive/data/docs/experiences/rnoh-turbomodule-codegen-wiring-verification.md

@@ -0,0 +1,19 @@
+# RNOH 手写/codegen 双轨 TurboModule 接线验证方法
+
+### 问题现象
+
+RN 鸿蒙化库中经常同时存在手写 C++ TurboModule 类（如 `RTNCookiesTurboModule`）与 codegen 生成的同名 TurboModule（`generated/RNOH/generated/turbo_modules/RTNCookies.cpp`），两套实现方法数还不一致。仅看文件是否存在无法判断哪个真正生效，会把未接线的手写死代码当作实际实现来分析，得出错误结论。
+
+### 解决方案
+
+判断 C++ TurboModule 哪个真正生效，**不要看文件是否存在，而要看 Package 工厂链路中实际创建的类名**：
+
+1. 打开库的 Package 头文件（如 `BaseReactNativeCookiesPackage.h`，通常由 codegen 生成）
+2. 查看 `createTurboModule()` / 工厂方法中 `std::make_shared<XXX>` 实际实例化的类名
+3. `std::make_shared` 指向 codegen 生成类 → 手写类为未接线死代码；指向手写类 → codegen 类仅是接口壳
+
+若手写类未接线：它是死代码，运行期零分配零调用，内存上无泄露影响。此类发现应在检视报告中记为"观察项（0 分）"，注明无内存影响、建议归属编码质量/一致性检视阶段处理，不应计入内存扣分。
+
+### 结果
+
+rntpc_cookies 实测：`BaseReactNativeCookiesPackage.h:15-21` 只实例化 codegen 生成的 `RTNCookies`（5 方法），手写 `RTNCookiesTurboModule`（7 方法）为未接线死代码，按观察项（0 分）记录，未影响内存评分（95/100）。该方法适用于所有 RNOH 鸿蒙化库的 C++ 层分析。

package/vendor/Archive/data/docs/experiences/rnoh-turbomodule-cpp-methodmap-compatibility-check.md

@@ -0,0 +1,20 @@
+## RNOH TurboModule C++/ArkTS methodMap_ 兼容性预检方法
+
+### 问题现象
+升级 RNOH 框架版本时（如 0.82→0.84），上游三方库可能引入新的 TurboModule Spec 文件（如 `NativeRNCNetInfo.ts`）和 `__turboModuleProxy` 加载逻辑。需要判断鸿蒙侧 C++ methodMap_ 和 ArkTS TurboModule 是否需要对应修改，还是仅需通过 npm 依赖升级自动同步。
+
+### 解决方案
+在执行代码适配前，先对比上游 TurboModule Spec 中定义的方法签名与鸿蒙侧 C++ methodMap_ 和 ArkTS TurboModule 实现的方法列表：
+
+1. 读取上游 Spec 文件（`*Native*.ts`），提取所有方法签名
+2. 读取鸿蒙侧 C++ 代码中的 `methodMap_` 数组，提取已注册的方法名
+3. 读取鸿蒙侧 ArkTS TurboModule 实现，提取方法列表
+4. 对比三者的方法名和参数签名
+
+**判断规则**：
+- 如果上游 Spec 定义的方法与鸿蒙侧 C++ methodMap_ 和 ArkTS 实现完全匹配 → **无需任何 C++/ArkTS 代码修改**，仅需通过 npm 依赖升级自动同步 JS 层变更
+- 如果上游新增方法 → 需在鸿蒙侧 C++ 和 ArkTS 中新增对应实现
+- 如果上游删除/重命名方法 → 需清理鸿蒙侧旧实现
+
+### 结果
+以 rntpc_react-native-netinfo 0.82→0.84 升级为例：上游 v11.4.1→v12.0.1 引入了 `NativeRNCNetInfo.ts` Spec，定义了 4 个方法（configure/getCurrentState/addListener/removeListeners）。鸿蒙侧 C++ methodMap_ 和 ArkTS TurboModule 已包含完全相同的 4 个方法，因此无需任何 C++/ArkTS 代码修改，仅通过 npm 依赖升级即自动同步 JS 层变更。此预检可大幅减少不必要的工作量。

package/vendor/Archive/data/docs/experiences/scenario-doc-vs-source-signature-diff-four-patterns.md

@@ -0,0 +1,24 @@
+## 三方库 Demo 生成：场景文档与库源码签名差异四类模式与核对策略
+
+### 问题现象
+
+基于 Demo 场景描述文档生成 ArkTS 代码时，场景文档中的接口签名与库源码实际签名存在系统性差异（mp3agic 案例：6 处差异，全部通过"逐接口 read_file 源码核实"拦截，未凭文档字面值编码）。差异可归纳为四类：
+
+1. **容器类型不一致**：文档写 `Array<T>`，源码实为 `JList<T>`（如 setChapters/setChapterTOC/getChapters/getChapterTOC）
+2. **参数形态不一致**：文档写数组传参 `arrays: any[]`，源码为 rest 参数 `...arrays`（如 BufferTools.mergeArrayBuffer），调用必须展开为多参数
+3. **声明返回类型与实际不符**：源码声明 `number` 实际返回数组（如 unsynchroniseBuffer），源于库 `.ts` 文件带 `@ts-nocheck`，编译器不校验
+4. **接口行为与文档预期相反**：方法无条件抛异常（如 ID3v2ObseleteFrame.packFrame 无条件抛 NotSupportedException）或内部缺陷（如 ID3v24Tag.setGenreDescription 缺 `this.` 前缀，运行时抛 ReferenceError）
+
+另有符号约定陷阱：`BufferTools.setBit(0, 7, true)` 返回 Int8 有符号值 -128 而非 128。
+
+### 解决方案
+
+- 生成前对**容器参数类型、rest 参数、返回类型、无条件抛异常方法**四类差异做专项核对（比全量核对更聚焦）
+- 每个接口必须 read_file 库源码确认签名，**以源码为准**，禁止按场景文档字面值编码
+- **声明返回类型与实际不符的容错展示**：库源码带 @ts-nocheck 时，按声明类型接值（编译通过），用 `String(result)` 展示实际内容并在代码注释说明差异，避免 `as` 二次强转引入新编译错误
+- **行为与文档相反的接口演示策略**：无条件抛异常的接口按真实行为 try/catch 捕获展示异常名与消息，验证点注释标注"源码真实行为"，不捏造成功路径
+- 按源码参数序精确构造对象，可选参数用 undefined 占位（如 `ID3v2ChapterTOCFrameData(false, undefined, true, true, 'toc01', undefined)` 后再 setChilds）
+
+### 结果
+
+mp3agic Demo 生成中 6 处差异全部在编码前拦截，未产生签名相关编译循环。三方库 `.ts` 源码普遍带 `@ts-nocheck`，场景文档签名不可尽信，专项核对策略可复用于其他三方库 Demo 生成任务。

package/vendor/Archive/data/docs/experiences/static-analysis-grep-cross-validation.md

@@ -0,0 +1,29 @@
+# 静态分析工具输出的 grep 盘点交叉验证方法
+
+### 问题现象
+
+基于 AST/正则的 XTS 覆盖率分析脚本对 mp3agic 库输出 8/271（2.95%），而人工核验的真实覆盖为 100/271（36.90%），偏差 12 倍以上。脚本全程无报错、无降级提示（静默失败），失真结果险些被写入正式报告。
+
+### 解决方案
+
+**"人工 grep 盘点 + 逐类对账"验证法**：
+
+```bash
+# 盘点实例方法调用（变量名.方法名 形式，变量名按目标库测试代码整理）
+grep -ohE "(iD3v2[A-Za-z]*|encodedText|jList|bean[0-9]?)\.[a-zA-Z_]+\(" *.ets | sort | uniq -c | sort -rn
+# 盘点静态方法调用（类名.方法名 形式）
+grep -ohE "\b(BufferTools|ID3v2Frame|...)\.[a-zA-Z_]+\(" *.ets | sort | uniq -c
+```
+
+将 grep 结果按类聚合并与脚本输出的类级覆盖率表逐行核对。
+
+**三条可疑信号**（任一命中即应触发排查）：
+1. 覆盖率异常低（<5%）但测试文件体量大（2000+ 行）→ 必然有匹配缺陷
+2. 某个内容充实的测试文件覆盖数为 0 → 该文件 import 风格未被识别
+3. 类级覆盖率表中"仅静态/工具类有覆盖、所有实例方法类为 0" → 模块解析失败、类型推断失效的典型特征
+
+### 结果
+
+该方法一次性发现并证实了脚本全部 3 处匹配缺陷（深层路径 import 不识别、大小写不敏感文件系统模块解析失败、ESObject 声明变量追踪失效），修复后结果与人工盘点逐类一致。
+
+通用结论：**任何基于静态分析的工具输出，在写入正式报告前都应用轻量级动态手段（grep/wc）做一次 sanity check**——静态工具的静默失败模式远比报错危险。补丁验证应在临时目录的脚本副本上进行，验证通过后再合入共享脚本，避免影响后续任务且便于回归。