@ohos-cpf/3rdloop 0.0.1

package/vendor/Server/Skills/rnoh-lib-rnt-search/references/PORT_VERIFICATION.md

@@ -0,0 +1,269 @@
+# 迁移验证与边界情况
+
+> 本文档列出 demo 迁移的验证检查清单与常见边界情况的处理策略。
+
+---
+
+## 1. 迁移验证检查清单
+
+迁移完成后，**逐项**确认以下检查通过。未通过项列入报告「待人工确认」。
+
+### 1.1 文件完整性
+
+| # | 检查项 | 命令 | 通过标准 |
+|---|--------|------|---------|
+| 1.1.1 | demo 新增文件全部迁移 | `diff <(cd <demoPath> && find . -type f -not -path './node_modules/*' -not -path './build/*' | sort) <(cd <targetExampleSrc> && find . -type f -not -path './node_modules/*' -not -path './build/*' | sort)` | **本次新增文件**全部到位（冲突文件保留目标版本，不计入缺失） |
+| 1.1.2 | 入口文件存在 | `find <targetExampleSrc> -name "App.tsx" -o -name "index.tsx"` | 两个文件都存在（可在嵌套子目录中） |
+| 1.1.3 | testerino 注册存在 | `find <targetExampleSrc> -path "*/Test/index.tsx" -o -path "*/tests/index.tsx"` | 退出码 0（路径可为嵌套） |
+| 1.1.4 | 无排除项残留 | `ls <targetExampleSrc>/node_modules 2>/dev/null` | 无输出（应被排除） |
+| 1.1.5 | index.tsx 引用 demo 入口 | `grep -r "testCase/App\|demo/App\|./App" <targetExampleSrc>/index.tsx` | index.tsx 已接入 demo 入口（若为已有文件未接入，标注待人工确认） |
+
+### 1.2 路径正确性
+
+| # | 检查项 | 命令 | 通过标准 |
+|---|--------|------|---------|
+| 1.2.1 | 子目录下无错误相对路径 | `grep -rn "from '\./" <targetExampleSrc>/testCase/Test/ <targetExampleSrc>/tests/` | 无同级引用应为 `../` 的情况 |
+| 1.2.2 | 所有 import 路径可解析 | 静态分析（Agent 读取每个 .tsx 文件） | 无 `Cannot find module` 风险 |
+
+### 1.3 引用一致性
+
+| # | 检查项 | 命令 | 通过标准 |
+|---|--------|------|---------|
+| 1.3.1 | 目标库引用方式一致 | `grep -rn "import.*from.*'<alias>\|<packageName>'" <targetExampleSrc>/` | 引用方式统一（全部用 alias 或全部用 packageName），仅检查本次新增文件 |
+| 1.3.2 | displayName 存在 | `grep -rn "displayName" <targetExampleSrc>/` | 存在且与 demo 名称一致 |
+| 1.3.3 | 无硬编码其他库标题 | `grep -rn "RN.*Tester" <targetExampleSrc>/` | 本次新增文件无遗留的其他库名称（Phase 6.5 已修正）；已有文件中的硬编码标题标注为待人工处理 |
+
+### 1.4 依赖完整性
+
+| # | 检查项 | 方法 | 通过标准 |
+|---|--------|------|---------|
+| 1.4.1 | 所有外部依赖已列出 | 对比 `analyze-demo-deps.cjs` 输出与报告「依赖增量」章节 | 全部列出 |
+| 1.4.2 | 无未识别的 require | `grep -rn "require(" <targetExampleSrc>/` | 所有 require 参数是字符串字面量且已分类 |
+| 1.4.3 | **外部依赖已在 example/package.json 声明** | 对比 `externalDeps` 与 `example/package.json` 的 dependencies/devDependencies | 所有外部依赖已声明；未声明的在报告中标注为高优先级缺失项（Phase 4.1） |
+
+### 1.5 Demo 可访问性
+
+| # | 检查项 | 方法 | 通过标准 |
+|---|--------|------|---------|
+| 1.5.1 | **无孤立文件** | 对比迁移文件列表与 `index.tsx` 的 `demos` 数组 | 所有有 `export` 的 `.tsx`/`.ts` 文件都被入口直接/间接引用（Phase 6.6） |
+| 1.5.2 | **菜单可滚动** | 检查 `demos` 条目数与菜单容器类型 | 条目 > 5 时菜单容器为 `<ScrollView>`（Phase 6.7） |
+| 1.5.3 | **原有 App.tsx 可访问** | 检查 `index.tsx` 是否包含原有 `App.tsx` 的菜单项 | 原有 demo 入口未丢失（Phase 6.8） |
+| 1.5.4 | **入口链路完整** | 追踪 `index.js` → `src/index.tsx` → `demos` → 各组件 → `./demo/` | 全链路可导入，无断裂（Phase 6.9） |
+
+### 1.6 构建前置
+
+| # | 检查项 | 方法 | 通过标准 |
+|---|--------|------|---------|
+| 1.6.1 | **build-profile 无越界路径** | 检查 `modules[].srcPath` 是否以 `../` 开头 | 所有路径在 `example/harmony/` 工程内（Phase 5.1） |
+| 1.6.2 | **.har 文件路径有效** | 逐一 `ls -la` 验证 `oh-package.json5` 中的 `file:` 引用 | 所有 `.har` 文件存在于指定路径（Phase 5.2） |
+
+### 1.7 版本一致性
+
+| # | 检查项 | 方法 | 通过标准 |
+|---|--------|------|---------|
+| 1.5.1 | 库与 rnt 版本一致 | `detect-rnoh-version.cjs` 输出对比 | 版本号相同 |
+| 1.5.2 | example/package.json 版本匹配 | 检查 react-native / react-native-harmony 版本 | 与目标 RNOH 版本一致 |
+
+---
+
+## 2. 边界情况与处理策略
+
+### 2.1 目标 example/ 不存在
+
+**场景**：`libPath/example/` 目录不存在。
+
+**处理**：
+1. 终止本 SKILL
+2. 输出提示：「目标 RN 工程 `example/` 目录不存在，请先执行 `rn-lib-add-example` 创建模板」
+3. 在报告中记录阻塞原因
+
+> 本 SKILL 不创建 example 模板，职责边界清晰。
+
+### 2.2 rnt 工程无 rn-tester/examples/
+
+**场景**：`{rnt-root}/*/rn-tester/examples/` 路径不存在。
+
+**处理**：
+1. 检查 rnt 根路径是否正确
+2. 列出 `{rnt-root}` 下的子目录，提示用户确认 rnt 根路径
+3. 询问是否换一个 rnt 工程根路径
+
+### 2.3 demo 与已有 example/src 内容冲突
+
+**场景**：迁移时发现 `targetExampleSrc` 已有同名文件。
+
+**处理**：
+- **默认（无 --clean）**：**增量添加，不覆盖**。列出冲突文件清单，**保留目标版本**，demo 版本不写入（`rsync --ignore-existing`），在报告中标注冲突项供人工确认是否合并
+- **--clean 启用**：直接清空目标，但**必须**用户明确同意
+
+**通用组件保留**：
+- `components/Navigation.tsx` 等 example 模板通用组件，若 demo 仍引用，**保留**
+- 脚本默认 `--clean` 时不清除 `components/Navigation.tsx`，可通过 `--clean-all` 强制全清
+
+**冲突文件后续处理**：
+- Agent 在报告中列出冲突文件清单
+- 询问用户是否需要手动合并（demo 版本 vs 目标版本的差异）
+- 若用户不需要合并，保持目标版本即可
+
+### 2.4 demo 引用目标库内部路径
+
+**场景**：demo 中出现 `import { X } from 'react-native-camera-kit/src/internal'`。
+
+**处理**：
+1. 列入报告「待人工确认」清单
+2. 不自动改写（内部路径可能依赖库源码结构）
+3. 提示用户：可能需要调整 demo 改用公开导出，或调整 example 配置
+
+### 2.5 demo 含原生代码
+
+**场景**：demo 目录含 `.ets` / `.cpp` / `.h` 文件。
+
+**处理**：
+1. JS/TS 文件正常迁移到 `example/src/`
+2. 原生文件**不迁移**到 `example/src/`（应放到 `example/harmony/` 下，由 `rn-lib-add-example` 壳层适配处理）
+3. 在报告中标注：「demo 含原生代码 <文件列表>，需由 `rn-lib-add-example` 处理壳层适配」
+
+### 2.6 rnt 工程路径跨盘/网络挂载
+
+**场景**：rnt 工程在 NFS / SMB / iCloud 等网络挂载盘上，`rsync` / `find` 较慢。
+
+**处理**：
+1. 检测路径是否为网络挂载（`mount | grep <rntPath>`）
+2. 若是，提示用户：「rnt 工程在网络挂载盘上，扫描/迁移可能较慢，建议本地拷贝后执行」
+3. 不强制终止，由用户决定
+
+### 2.7 候选名匹配到多个不同库
+
+**场景**：`searchNames` 中的短名匹配到多个不同库的 demo（如 `react-native-svg` 匹配 `react-native-svg-uri`、`react-native-svg-transformer`）。
+
+**处理**：
+1. `find-rnt-demo.sh` 退出码 2（多个命中）
+2. 列出所有命中路径与对应的库候选名
+3. 自动选择第一个命中项，在报告中标注全部命中路径
+4. 用户可通过 `--demo-path` 参数指定其他 demo
+
+### 2.8 demo 入口文件缺失
+
+**场景**：demo 目录无 `App.tsx` 或 `index.tsx`。
+
+**处理**：
+1. 检查是否有其他入口文件（`Main.tsx`、`Demo.tsx`、`index.js`）
+2. 若有，在报告中标注实际入口文件
+3. 若无任何入口文件，列入「待人工确认」，提示用户检查 demo 完整性
+
+### 2.9 demo 引用 rnt 工程特有的全局变量/组件
+
+**场景**：demo 中引用了 rnt 工程全局注入的组件（如 `__rntTesterGlobals`、特殊的 `Navigation`）。
+
+**处理**：
+1. 通过 `analyze-demo-deps.cjs` 的 `libReferences` 分析识别非标准引用
+2. 列入报告「待人工确认」
+3. 提示用户：可能需要移除或替换为 example 工程的等价物
+
+### 2.10 大量 demo 文件导致迁移耗时
+
+**场景**：demo 文件数 > 100，`rsync` 耗时较长。
+
+**处理**：
+1. 报告文件数与预估耗时
+2. 正常执行（`rsync` 通常足够快，秒级完成）
+3. 若超过 30 秒，检查是否有意外的大文件或排除项失效
+
+### 2.11 demo 引用 rnt 特有外部依赖（如 @rnoh/testerino）
+
+**场景**：demo 引用了 `@rnoh/testerino` 等 rnt 工程特有的包，但 `example/package.json` 未声明。
+
+**影响**：所有使用该依赖的组件（如 `Tester`、`TestCase`、`TestSuite`）运行时崩溃，白屏。
+
+**处理**：
+1. Phase 4.1 检测到缺失依赖后，从 rnt 工程的 `package.json` 中提取版本与引用方式
+2. 将 rnt 工程中的 tgz 文件复制到 example 目录
+3. 在报告依赖增量清单中给出建议写入值（如 `"@rnoh/testerino": "file:./rnoh-testerino-0.0.12.tgz"`）
+4. 由 `rn-lib-add-example` 或 Agent 写入 `example/package.json`
+
+### 2.12 build-profile.json5 模块路径越界
+
+**场景**：`build-profile.json5` 中 `modules[].srcPath` 为 `../../harmony/safe_area` 等越界路径。
+
+**影响**：hvigor 报错 `Path escapes project root`，编译失败。
+
+**处理**：
+1. Phase 5.1 检测到越界路径
+2. 物理复制模块目录到 `example/harmony/` 下
+3. 修改 `srcPath` 为工程内路径（如 `./safe_area`）
+4. 同步修正被复制模块的 `oh-package.json5` 中的 `.har` 路径
+5. ⚠️ 符号链接不可行（hvigor 不跟随 symlink）
+
+### 2.13 oh-package.json5 中 .har 路径错误
+
+**场景**：模块的 `oh-package.json5` 中 `file:` 引用的 `.har` 路径多/少一层子目录。
+
+**影响**：`ohpm install` 静默跳过该依赖，编译时报 `Cannot find module`。
+
+**处理**：
+1. Phase 5.2 逐一验证 `.har` 文件存在性
+2. 修正 `oh-package.json5` 中的路径，使其指向实际 `.har` 文件位置
+
+### 2.14 迁移的独立 demo 文件未被入口引用
+
+**场景**：`demo03.tsx`、`demo05.tsx` 等文件已迁移到 `example/src/`，但未被 `index.tsx` 的 `demos` 数组引用。
+
+**影响**：用户无法通过菜单导航访问这些 demo，文件虽存在但运行时不加载。
+
+**处理**：
+1. Phase 6.6 检测孤立文件
+2. 将组件加入 `demos` 数组，确保用户可导航到
+
+### 2.15 菜单条目过多无法滚动
+
+**场景**：`demos` 数组条目 > 5，菜单容器为 `<View>`（不支持滚动）。
+
+**影响**：底部 demo 条目不可见、不可点击，用户无法访问。
+
+**处理**：
+1. Phase 6.7 检测条目数与容器类型
+2. 将 `<View>` 改为 `<ScrollView>`
+
+### 2.16 替换入口丢失原有 App.tsx demo
+
+**场景**：`index.js` 从 `./src/App` 改为 `./src/index` 后，原有 `App.tsx` 的 demo 不可访问。
+
+**影响**：原有 demo（如 SafeAreaView、Hooks、Listener 等）完全丢失。
+
+**处理**：
+1. Phase 6.8 检查原有 `App.tsx` 是否仍可访问
+2. 将原有 `App.tsx` 作为菜单项接入 `index.tsx` 的 `demos` 数组
+
+---
+
+## 3. 验证失败处理
+
+| 失败项 | 处理 |
+|--------|------|
+| 文件完整性失败 | 重新执行 `port-demo.sh`，检查排除项配置（冲突文件保留目标版本属正常，不计入失败） |
+| 路径错误 | Agent 用 `Edit` 工具逐个修正（仅本次新增文件） |
+| 引用不一致 | 在报告中标注，由 `rn-lib-add-example` 配置 alias 时统一 |
+| 依赖未列出 | 重新运行 `analyze-demo-deps.cjs`，检查 demo 新增的 import |
+| displayName 冲突 | 询问用户保留哪个 |
+| 冲突文件需合并 | 列出 demo 版本与目标版本差异，由用户决策是否手动合并 |
+
+---
+
+## 4. 报告必含字段
+
+迁移报告**必须**包含以下字段，缺失则视为迁移未完成：
+
+| 字段 | 说明 |
+|------|------|
+| demo 来源路径 | rnt 工程路径 + demo 子目录 |
+| 命中候选名 | `searchNames` 中实际匹配到的名称 |
+| 迁移文件清单 | 相对路径列表 + 文件总数（区分「本次新增」与「冲突保留」） |
+| 冲突文件清单 | demo 与目标同名文件列表，标注「目标版本已保留，demo 版本未写入」 |
+| 依赖增量清单 | 分类列表（目标库 / RNOH / RN 通用 / 待确认）；**标注 example/package.json 中缺失的依赖及建议写入值** |
+| 路径修正记录 | 修正的文件 + 改动内容（仅本次新增文件） |
+| 入口文件信息 | App.tsx / index.tsx 路径 + displayName |
+| **构建前置检查结果** | build-profile 路径越界检查、.har 路径验证、外部依赖缺失清单、入口链路验证结果 |
+| **Demo 可访问性验证** | 孤立文件检测、菜单 ScrollView 适配、原有 App.tsx 保留、入口链路端到端验证 |
+| 待人工确认项 | 业务无关依赖、冲突文件合并、入口文件接入、原生代码、特殊引用 |
+| 验证检查结果 | 1.1-1.6 各项通过/失败状态 |
+| 后续步骤建议 | 引导执行 `rn-lib-add-example` 完成壳层适配；执行 `npm i` → `ohpm install` → `npm run dev` → `devecocli build` 编译验证 |

package/vendor/Server/Skills/rnoh-lib-rnt-search/references/RNT_PROJECT_STRUCTURE.md

@@ -0,0 +1,173 @@
+# rnt 工程结构参考
+
+> 本文档说明 rnt（React Native Tester）工程的目录布局、demo 子目录约定与扫描规则。
+
+---
+
+## 1. rnt 工程总览
+
+rnt 是 RN 鸿蒙化团队的 demo 集合工程，**根目录下并列多个子工程**，每个子工程内含 `rn-tester/examples/` 目录，存放各三方库的 demo。
+
+```
+{rnt-root}/                          ← rnt 工程根（用户传入 --rnt-path）
+├── react_native_openharmony/        ← RNOH 框架本体子工程
+│   └── rn-tester/
+│       └── examples/
+│           ├── react-native-camera-kit/
+│           ├── react-native-svg/
+│           └── ...
+├── rnoh_testerino/                  ← testerino 测试框架子工程
+│   └── rn-tester/
+│       └── examples/
+│           └── ...
+├── <其他子工程>/
+│   └── rn-tester/
+│       └── examples/
+│           └── <library-demo>/
+└── ...
+```
+
+**关键约定**：
+- demo 目录**总在** `{rnt-root}/*/rn-tester/examples/{库候选名}/` 路径下
+- 不同子工程的 `examples/` 可能收录不同库的 demo
+- 同一库的 demo **通常只在一个子工程下**，但**也可能存在多个**（版本一致时自动选择第一个）
+
+---
+
+## 2. demo 目录典型结构
+
+rnt demo 的目录结构有多种变体，`analyze-demo-deps.cjs` 会自动检测入口文件位置。以下是三种常见结构：
+
+### 2.1 结构 A：根级入口（经典结构）
+
+```
+{library-demo}/
+├── App.tsx                # demo 入口组件，含 displayName / title
+├── index.tsx              # 导出 demo，供 testerino 注册
+├── tests/
+│   └── index.tsx          # testerino 测试用例注册表
+├── camera/                # demo 功能子目录
+│   ├── CameraDemo.tsx
+│   └── CameraControls.tsx
+├── components/            # demo 复用组件
+│   ├── Navigation.tsx     # 通用导航（迁移时保留）
+│   └── Button.tsx
+└── assets/                # 静态资源
+```
+
+### 2.2 结构 B：testCase 嵌套结构（常见于较新 demo）
+
+```
+{library-demo}/
+├── testCase/
+│   ├── App.tsx            # testerino 入口，导出 displayName / title / examples
+│   ├── Navigation.tsx     # 通用导航（含硬编码标题，需修正）
+│   ├── Palette.tsx        # 颜色常量
+│   └── Test/
+│       ├── index.tsx      # testerino 测试用例注册表
+│       ├── PdfApitest.tsx
+│       └── ...
+├── demo/
+│   └── PdfExample.tsx     # 独立 demo 示例
+└── assets/                # 静态资源
+```
+
+> 结构 B 的入口在 `testCase/App.tsx`，不是根级 `App.tsx`。`index.tsx`（根级）可能是独立的简单示例，需要接入到 `testCase/App.tsx`（Phase 6.4）。
+
+### 2.3 结构 C：混合结构
+
+部分 demo 同时包含根级 `App.tsx` 和 `tests/` 目录，也可能有 `demo/` 子目录存放额外示例。
+
+### 2.4 入口检测规则
+
+`analyze-demo-deps.cjs` 按以下规则自动检测入口：
+
+| 检测项 | 规则 |
+|--------|------|
+| App 入口 | 递归扫描，取第一个 basename 为 `App.tsx`/`App.ts`/`App.jsx`/`App.js` 的文件 |
+| index 入口 | 递归扫描，取第一个 basename 为 `index.tsx`/`index.ts` 的文件 |
+| displayName | 匹配 `displayName = 'xxx'` 或 `export const displayName = 'xxx'` |
+| title | 匹配 `title = 'xxx'` 或 `title: 'xxx'` 或 `export const title = 'xxx'` |
+| Navigation.tsx | 递归扫描，列出所有 basename 为 `Navigation.tsx` 的文件 |
+| 硬编码标题 | 匹配 `RN <Xxx> (Capi )?Tester` 模式的文本 |
+
+---
+
+## 3. 候选搜索名生成
+
+`read-lib-meta.cjs` 从目标库 `package.json` 生成候选名数组 `searchNames`，按以下顺序去重：
+
+| 顺序 | 来源 | 示例（react-native-camera-kit） |
+|------|------|-------------------------------|
+| 1 | `harmony.alias` | `react-native-camera-kit` |
+| 2 | `packageName` 去 scope | `react-native-camera-kit`（`@scope/react-native-camera-kit` → `react-native-camera-kit`） |
+| 3 | `dirBase`（目录名） | `react-native-camera-kit` |
+| 4 | `packageName`（完整） | `@scope/react-native-camera-kit` |
+
+> scope 去除规则：`packageName.includes('/')` 时取 `split('/').pop()`，否则取原值。
+
+---
+
+## 4. 扫描规则详解
+
+`find-rnt-demo.sh` 执行流程：
+
+```
+1. 调用 read-lib-meta.cjs 获取 searchNames
+2. 遍历 {rnt-root}/*/rn-tester/examples/
+   ├─ 对每个候选名，检查 {examples-root}/{候选名}/ 是否存在
+   │   └─ 命中 → 加入 matches
+   └─ 大小写不敏感兜底：
+      遍历 {examples-root} 下所有子目录
+      对每个子目录名与候选名做 tr '[:upper:]' '[:lower:]' 比较
+      命中 → 加入 matches
+3. 去重 matches
+4. 输出每个 demo 绝对路径一行
+5. 退出码：
+   - 0: 唯一命中
+   - 1: 未命中
+   - 2: 多个命中（自动选择第一个，用户可通过 --demo-path 指定其他）
+```
+
+### 4.1 多命中的典型情况
+
+- 同一库在不同 rnt 子工程下都有 demo（新旧版本共存）
+- 候选名匹配到多个不同库（如 `react-native-svg` 匹配到 `react-native-svg-uri`）
+- 大小写兜底匹配到名称相近的目录
+
+> 多命中时自动选择第一个，在报告中标注全部命中路径。用户可通过 `--demo-path` 参数指定其他。
+
+### 4.2 未命中的排查
+
+| 原因 | 排查方法 |
+|------|---------|
+| rnt 工程路径错误 | 检查 `{rnt-root}` 是否存在、是否有 `*/rn-tester/examples/` 子目录 |
+| 库 demo 不在 rnt 中 | 询问用户该库是否有 demo、demo 是否在别处 |
+| 候选名不匹配 | 手动浏览 `{rnt-root}/*/rn-tester/examples/` 目录列表，找名称相近的 |
+| demo 目录名特殊 | 用户提供 `--demo-path` 直接跳过扫描 |
+
+---
+
+## 5. rnt 工程路径示例
+
+| 环境 | 典型路径 |
+|------|---------|
+| 本机默认 | `/path/to/rnt`（用户自定义） |
+| 团队共享 | `/workspace/rnt` |
+| 克隆临时 | `/tmp/rnt-clone` |
+
+> **路径不写死在脚本中**，由用户通过 `--rnt-path` 传入。脚本仅做存在性校验。
+
+---
+
+## 6. 与 example 工程的差异
+
+| 维度 | rnt demo | example/src（迁移后） |
+|------|---------|---------------------|
+| 用途 | 团队共享的 demo 集合 | 单个库的独立测试工程 |
+| 依赖管理 | rnt 工程统一 `package.json` | example 自己的 `package.json` |
+| 目标库引用 | `import { X } from 'react-native-camera-kit'`（npm 包） | 同样用 alias 引用，但通过 `metro.config.js` 映射到 `node_modules/<ohPackageName>` |
+| 入口注册 | testerino 全局注册 | `App.tsx` + `index.tsx` 独立入口 |
+| 原生壳层 | rnt 工程统一提供 | example 自己的 `harmony/` 壳层（由 `rn-lib-add-example` 配置） |
+
+> 迁移的本质：从 rnt 的「集合 demo」中取出一个，放到 example 的「独立工程」中，并补齐 example 缺失的壳层与依赖。