@harmonyos-arkts/d2h 0.1.11 → 0.1.13

package/skills/d2h-hypium-forge/references/pitfalls.md

@@ -1,98 +1,98 @@
-# Hypium 高频踩坑清单（7 项目实证 + 官方文档修正）
-
-来源：agc-template-market 7 个项目（DailySchedule/CarBeautyCare/Recipes/HomeDecoration/WebShortDrama/Recycling/DigitalNewspaper）白盒开发全记录。完整数据见 TestDemo 仓库 `reports/HYPIUM-DEV-COST-ANALYSIS.md`。
-
-## 框架/API 层
-
-### 1. `swipe` distance 是百分比（4/7 项目首踩）
-`driver.swipe(direction, distance)` 的 distance 是**滑动区域总长的 1%-100%**，非像素。按像素写 250 会越界报 invalid/负坐标。direction 用常量 `UiParam.LEFT/RIGHT/UP/DOWN`。精确滑动用 `slide(start, end)`；长滑抽屉类（swipeAction 露出按钮）要 ~40% 屏宽。
-
-### 2. `BY.text` 默认全匹配（5/7 项目）
-模板文案（`${used}看过`）、mock 长标题（"非常好吃上头的的可乐鸡翅~~"）全匹配必失败。**修正**：`MatchPattern.CONTAINS`（官方支持，无需自写子串遍历——早期项目自写了 find_text_contains，其实框架原生支持）。还支持 STARTS_WITH/ENDS_WITH/REGEXP/REGEXP_ICASE。
-
-### 3. `press_back()` 语义不唯一（RCY 6 次失败中 3 次）
-收软键盘与 pop 页面不区分：编辑页上收键盘会把整页 pop 掉。**绕法**：点击页面标题空白处失焦收键盘。框架暂无 dismiss_keyboard()。
-
-### 4. 系统子窗口对组件树不可见（6/7 项目）
-Toast（promptAction）、系统权限弹窗、输入法窗口、MapKit 级联面板均拿不到。**对策**：Toast 断言改界面持久变化；权限弹窗用 `hdc shell atm` 预授权或 setup 处理一次；输入法遮挡按钮→先收键盘再点。**A 线（LLM 截图）反而能读 Toast**——融合分工点。
-
-### 5. 视口外控件（2/7 项目）
-不需要手工滑动！`touch(BY.text("xx"), scroll_target=BY.type("Scroll"))` 与 `check_component_exist(..., scroll_target=...)` 原生支持滚动查找。仅当控件被布局裁剪出屏（如 CBC_008 `height('100%')` 缺陷）才完全不可达→登记应用缺陷+降级断言。
-
-### 6. DatePicker/滚轮无列级 API（2/7）
-几何坐标模拟：取 DatePicker bounds 右侧 15% 处为日列中心，小距离 swipe 后**读取高亮值校验，过冲则反向回滑一格**（闭环纠偏）。
-
-### 7. Rect/bounds 便捷方法缺失（3/7）
-无 get_left 等；用 get_center()/get_size() 或直接 r.left/r.right 字段。`.id()` 不一定暴露（应用没写 test id 时）；Span 拼接文本拿不到完整串→用父 Text CONTAINS。
-
-### 8. `input_text` 行为细节
-默认**先清空再输入**；中文走剪贴板一次粘贴；英文 <200 字符逐键。粘贴板输入后软键盘可能不弹出——某些校验依赖输入事件的表单要留意。
-
-## 应用/数据层
-
-### 9. PersistenceV2 登录态跨用例残留（RCY 6 次失败的另一半）
-"not in logout state" 类失败的根因。**标准解**：setup 里 `driver.clear_app_data(PACKAGE)`（官方 API）或 `hdc shell bm clean -n <pkg> -d`，然后重新 mock_login。
-
-### 10. 纯内存数据不可跨用例继承
-VM 里普通数组（如地址列表）每次启动为空——同用例 setup 内造数，勿依赖其他用例。
-
-### 11. 华为账号 Kit 模拟器必失败
-模板 app 普遍有模拟登录降级：一键登录失败 → 弹"是否先模拟登录成功？/温馨提示" → 点确认 → isLogin=true。common 库封装 `mock_login()`，注意有的要先勾协议 Checkbox（软键盘可能遮挡它——先收键盘）。
-
-### 12. press_back 的另一面：Web 页面 go_back 被 Web 历史消费
-详情页是 Web 组件时，press_back 先退 Web 历史；EMBEDDED sheet 返回首页后不自动关闭会遮挡底栏——回首页后显式关 sheet。
-
-### 13. 异步导航延迟（WSD-014 flaky）
-登录成功后 app 数秒后自动跳首页，会把校验通过的页面"带走"。**标准解**：每步操作前 `ensure_page()` 自愈式重进。
-
-### 14. 同名控件歧义
-订单状态 Tab 与卡片状态文案同名→按 y 最小取顶部；弹窗"取消"与顶栏"取消"→按 y 区分或用 within/inWindow 缩范围。
-
-### 15. mock 数据语义陷阱
-搜索可能是 `name 子串 || labels 精确`（热词"华为手机"零命中，"手机"命中 labels）；列表最新在前；首条地址自动设默认。**读 mock/VM 源码是唯一可靠途径**。
-
-## 执行器层（harmonyrun）
-
-### 16. 全量模式 xdevice bug
-`harmonyrun hypium run .`（不带 --case）报 "Test source 'testcases' does not exist"——即使 cwd 正确。只能 `--case XXX_001` 逐条，每条 ~40s 框架开销（安装/报告），15 条多花 ~7min。
-
-### 17. 必须先 cd 到 hypium 项目目录
-相对路径解析依赖 cwd；后台命令的 cd 不影响后续 shell——写 run.sh 固定 cwd。
-
-### 18. 报告位置
-xdevice 报告在 `<项目>/reports/<时间戳>/`，summary_report.html / report_data.json（逐条耗时在 report_data.json）。控制台管道 tail 会截日志，排障去报告目录取全量日志。
-
-## SchoolLife 对照实验新增（2026-09-16，N1~N10）
-
-### 19. isAfter/isBefore 是"整体在上方/下方"，非同行左右
-表单同行布局（label 左、输入框右）用 isAfter 定位会命中下一行的框。同行控件用 y 区间过滤或 within(容器)；xpath `//TextInput[n]` 序号 >1 不可用。
-
-### 20. 组件树包含被 sheet/弹窗遮挡的背景控件
-sheet 打开时背景页控件仍可被 find 命中，点击打在遮挡层上。弹窗内操作前先断言弹窗标题存在，或校验目标 bounds 是否被遮挡。
-
-### 21. AlertDialog 文本命中返回整窗容器
-点容器中心未必命中按钮。用 find_all 取容器内 Button 子控件再点。
-
-### 22. 坐标是 px 不是 vp（vp×3.5）
-源码 vp 尺寸直接当坐标用会全偏。common 库封装 vp→px 换算；无文字图标按钮先几何过滤再算中心。
-
-### 23. BY.text 的 MatchPattern 必须位置传参
-`BY.text(match_pattern=MatchPattern.CONTAINS)` 关键字传参被拒，必须 `BY.text(s, MatchPattern.CONTAINS)`。
-
-### 24. input_text 偶发不生效
-封装"输入后 getText 回读校验 + 重试"。
-
-### 25. 用例间业务数据冲突
-带唯一性/重叠校验的功能（如课程时段），每条用例分配互斥数据；全套重跑前卸载重装或 clear_app_data。
-
-### 26. 功能被登录态门控但用例集未体现
-control-facts 阶段必须查每个功能入口的 isLogin 分支（SchoolLife 签到需"模拟关联"后才能用）。
-
-### 27. 模拟器锁屏/崩溃无预案会报废整轮
-每次 setup 先亮屏（press_key POWER / 检查 display 状态），崩溃后重试；atm perm 预授权在部分镜像不存在，勿依赖。
-
-### 28b. 权限弹窗保护规则（用户指令 2026-09-16）
-执行中出现任何权限确认弹窗（位置/相机/麦克风/相册/通知，"允许/仅本次允许/禁止"），**一律点击同意/允许继续**——除非该用例明确设计为"无权限状态下的测试"（如验证拒绝后的降级 UI/引导页）。落法：common 库 launch/setup 加弹窗处理循环（检测弹窗文案→点允许→重检到无弹窗）。注意系统权限弹窗是系统子窗口、组件树可能不可见（见 #4），不可见时用坐标点击或 `hdc shell atm` 预授权兜底。
-
-### 28. key 定位现状：模板 app 几乎无 .id()
-实测 8 项目 .id() 密度 0~9 处（集中在个别安全组件）。遇到有 id 的模块优先 BY.key（SchoolLife 签到 4 条一次通过即证据）；脚本生成时输出"可测性改造建议"（给关键控件打语义化 .id()）作为交付物之一。
+# Hypium 高频踩坑清单（7 项目实证 + 官方文档修正）
+
+来源：agc-template-market 7 个项目（DailySchedule/CarBeautyCare/Recipes/HomeDecoration/WebShortDrama/Recycling/DigitalNewspaper）白盒开发全记录。完整数据见 TestDemo 仓库 `reports/HYPIUM-DEV-COST-ANALYSIS.md`。
+
+## 框架/API 层
+
+### 1. `swipe` distance 是百分比（4/7 项目首踩）
+`driver.swipe(direction, distance)` 的 distance 是**滑动区域总长的 1%-100%**，非像素。按像素写 250 会越界报 invalid/负坐标。direction 用常量 `UiParam.LEFT/RIGHT/UP/DOWN`。精确滑动用 `slide(start, end)`；长滑抽屉类（swipeAction 露出按钮）要 ~40% 屏宽。
+
+### 2. `BY.text` 默认全匹配（5/7 项目）
+模板文案（`${used}看过`）、mock 长标题（"非常好吃上头的的可乐鸡翅~~"）全匹配必失败。**修正**：`MatchPattern.CONTAINS`（官方支持，无需自写子串遍历——早期项目自写了 find_text_contains，其实框架原生支持）。还支持 STARTS_WITH/ENDS_WITH/REGEXP/REGEXP_ICASE。
+
+### 3. `press_back()` 语义不唯一（RCY 6 次失败中 3 次）
+收软键盘与 pop 页面不区分：编辑页上收键盘会把整页 pop 掉。**绕法**：点击页面标题空白处失焦收键盘。框架暂无 dismiss_keyboard()。
+
+### 4. 系统子窗口对组件树不可见（6/7 项目）
+Toast（promptAction）、系统权限弹窗、输入法窗口、MapKit 级联面板均拿不到。**对策**：Toast 断言改界面持久变化；权限弹窗用 `hdc shell atm` 预授权或 setup 处理一次；输入法遮挡按钮→先收键盘再点。**A 线（LLM 截图）反而能读 Toast**——融合分工点。
+
+### 5. 视口外控件（2/7 项目）
+不需要手工滑动！`touch(BY.text("xx"), scroll_target=BY.type("Scroll"))` 与 `check_component_exist(..., scroll_target=...)` 原生支持滚动查找。仅当控件被布局裁剪出屏（如 CBC_008 `height('100%')` 缺陷）才完全不可达→登记应用缺陷+降级断言。
+
+### 6. DatePicker/滚轮无列级 API（2/7）
+几何坐标模拟：取 DatePicker bounds 右侧 15% 处为日列中心，小距离 swipe 后**读取高亮值校验，过冲则反向回滑一格**（闭环纠偏）。
+
+### 7. Rect/bounds 便捷方法缺失（3/7）
+无 get_left 等；用 get_center()/get_size() 或直接 r.left/r.right 字段。`.id()` 不一定暴露（应用没写 test id 时）；Span 拼接文本拿不到完整串→用父 Text CONTAINS。
+
+### 8. `input_text` 行为细节
+默认**先清空再输入**；中文走剪贴板一次粘贴；英文 <200 字符逐键。粘贴板输入后软键盘可能不弹出——某些校验依赖输入事件的表单要留意。
+
+## 应用/数据层
+
+### 9. PersistenceV2 登录态跨用例残留（RCY 6 次失败的另一半）
+"not in logout state" 类失败的根因。**标准解**：setup 里 `driver.clear_app_data(PACKAGE)`（官方 API）或 `hdc shell bm clean -n <pkg> -d`，然后重新 mock_login。
+
+### 10. 纯内存数据不可跨用例继承
+VM 里普通数组（如地址列表）每次启动为空——同用例 setup 内造数，勿依赖其他用例。
+
+### 11. 华为账号 Kit 模拟器必失败
+模板 app 普遍有模拟登录降级：一键登录失败 → 弹"是否先模拟登录成功？/温馨提示" → 点确认 → isLogin=true。common 库封装 `mock_login()`，注意有的要先勾协议 Checkbox（软键盘可能遮挡它——先收键盘）。
+
+### 12. press_back 的另一面：Web 页面 go_back 被 Web 历史消费
+详情页是 Web 组件时，press_back 先退 Web 历史；EMBEDDED sheet 返回首页后不自动关闭会遮挡底栏——回首页后显式关 sheet。
+
+### 13. 异步导航延迟（WSD-014 flaky）
+登录成功后 app 数秒后自动跳首页，会把校验通过的页面"带走"。**标准解**：每步操作前 `ensure_page()` 自愈式重进。
+
+### 14. 同名控件歧义
+订单状态 Tab 与卡片状态文案同名→按 y 最小取顶部；弹窗"取消"与顶栏"取消"→按 y 区分或用 within/inWindow 缩范围。
+
+### 15. mock 数据语义陷阱
+搜索可能是 `name 子串 || labels 精确`（热词"华为手机"零命中，"手机"命中 labels）；列表最新在前；首条地址自动设默认。**读 mock/VM 源码是唯一可靠途径**。
+
+## 执行器层（harmonyrun）
+
+### 16. 全量模式 xdevice bug
+`harmonyrun hypium run .`（不带 --case）报 "Test source 'testcases' does not exist"——即使 cwd 正确。只能 `--case XXX_001` 逐条，每条 ~40s 框架开销（安装/报告），15 条多花 ~7min。
+
+### 17. 必须先 cd 到 hypium 项目目录
+相对路径解析依赖 cwd；后台命令的 cd 不影响后续 shell——写 run.sh 固定 cwd。
+
+### 18. 报告位置
+xdevice 报告在 `<项目>/reports/<时间戳>/`，summary_report.html / report_data.json（逐条耗时在 report_data.json）。控制台管道 tail 会截日志，排障去报告目录取全量日志。
+
+## SchoolLife 对照实验新增（2026-09-16，N1~N10）
+
+### 19. isAfter/isBefore 是"整体在上方/下方"，非同行左右
+表单同行布局（label 左、输入框右）用 isAfter 定位会命中下一行的框。同行控件用 y 区间过滤或 within(容器)；xpath `//TextInput[n]` 序号 >1 不可用。
+
+### 20. 组件树包含被 sheet/弹窗遮挡的背景控件
+sheet 打开时背景页控件仍可被 find 命中，点击打在遮挡层上。弹窗内操作前先断言弹窗标题存在，或校验目标 bounds 是否被遮挡。
+
+### 21. AlertDialog 文本命中返回整窗容器
+点容器中心未必命中按钮。用 find_all 取容器内 Button 子控件再点。
+
+### 22. 坐标是 px 不是 vp（vp×3.5）
+源码 vp 尺寸直接当坐标用会全偏。common 库封装 vp→px 换算；无文字图标按钮先几何过滤再算中心。
+
+### 23. BY.text 的 MatchPattern 必须位置传参
+`BY.text(match_pattern=MatchPattern.CONTAINS)` 关键字传参被拒，必须 `BY.text(s, MatchPattern.CONTAINS)`。
+
+### 24. input_text 偶发不生效
+封装"输入后 getText 回读校验 + 重试"。
+
+### 25. 用例间业务数据冲突
+带唯一性/重叠校验的功能（如课程时段），每条用例分配互斥数据；全套重跑前卸载重装或 clear_app_data。
+
+### 26. 功能被登录态门控但用例集未体现
+control-facts 阶段必须查每个功能入口的 isLogin 分支（SchoolLife 签到需"模拟关联"后才能用）。
+
+### 27. 模拟器锁屏/崩溃无预案会报废整轮
+每次 setup 先亮屏（press_key POWER / 检查 display 状态），崩溃后重试；atm perm 预授权在部分镜像不存在，勿依赖。
+
+### 28b. 权限弹窗保护规则（用户指令 2026-09-16）
+执行中出现任何权限确认弹窗（位置/相机/麦克风/相册/通知，"允许/仅本次允许/禁止"），**一律点击同意/允许继续**——除非该用例明确设计为"无权限状态下的测试"（如验证拒绝后的降级 UI/引导页）。落法：common 库 launch/setup 加弹窗处理循环（检测弹窗文案→点允许→重检到无弹窗）。注意系统权限弹窗是系统子窗口、组件树可能不可见（见 #4），不可见时用坐标点击或 `hdc shell atm` 预授权兜底。
+
+### 28. key 定位现状：模板 app 几乎无 .id()
+实测 8 项目 .id() 密度 0~9 处（集中在个别安全组件）。遇到有 id 的模块优先 BY.key（SchoolLife 签到 4 条一次通过即证据）；脚本生成时输出"可测性改造建议"（给关键控件打语义化 .id()）作为交付物之一。

package/skills/d2h-hypium-forge/references/testability-template.md

@@ -1,71 +1,71 @@
-# 可测试性需求（Design for Testability）— 模板与累积清单
-
-> 调测中发现的「让 hypium 测试变慢/不准」的工程特征，反哺为对应用开发的需求。
-> 每条格式：现象（实测） → 根因 → 可测试性需求（对开发的要求） → 收益。
-
-## 累积清单（按工程验证时追加）
-
-### DFT-001 控件必须预置稳定 ID
-- 现象：无 .id() 控件用 BY.text 定位，文案随数据变化 → 脚本重试多轮、不稳定（实测：首个转化工程首轮全部超时）。
-- 根因：ArkTS 开发普遍省略 .id()，uitest 只能按 text/type 匹配。
-- 需求：**所有可交互控件（Button/Toggle/TextInput/入口 Image）必须写 .id()**，命名 `<语义>_<页面>`（如 btn_settings_index）。
-- 收益：脚本零重试定位；用例与实现解耦（文案改了脚本不断）。
-
-### DFT-002 条件渲染控件需可达路径
-- 现象：`if(testMode)` 内控件默认态不存在，存在性断言误报失败（实测 START TEST 按钮）。
-- 需求：条件功能的入口开关应在**入口页可达**（≤2 步操作），或提供 deeplink/want 参数直达。
-- 收益：状态覆盖用例可自动执行，不依赖复杂前置链。
-
-### DFT-003 运行时权限在模拟器的可预授性
-- 现象：首启权限弹窗阻塞 BFS/用例执行（实测 RaiseToAnswer 电话权限）。
-- 需求：应用不应在首帧同步弹多个权限弹窗；权限申请延后到功能触发点。
-- 收益：precondition 批量预授后用例零弹窗干扰。
-
-### DFT-004 登录需提供测试通道
-- 现象：真实登录页在模拟器无法自动完成 → 登录后功能全部 BLOCKED。
-- 需求：提供 mock 登录开关（want 参数/环境开关）或测试账号常量。
-- 收益：登录态用例可全自动执行。
-
-### DFT-005 首启弹窗需可编程处置
-- 现象：隐私协议/引导页弹窗文案各异，逐个适配成本高。
-- 需求：首启弹窗按钮文案使用标准词（同意并继续/跳过/我知道了）；提供"不再提醒"。
-- 收益：统一 dismiss 片段即可覆盖。
-
-（新工程验证时按编号追加，注明来源工程与实测数据）
-
-### DFT-006 HAP 更新必须卸载重装（模拟器缓存怪癖）
-- 现象：`install -r` 同版本号替换后，注入的 .id 运行时全部丢失（abc 缓存不失效，实测 News 工程）。
-- 需求/skill 规则：**注入 ID 重打包后一律 `hdc uninstall <bundle> && hdc install <hap>`**。
-
-### DFT-007 部分 HAR 模块 .id 运行时丢弃（待官方解释）
-- 现象：同一 HAP 内 commons/features-home 的 .id 生效，features-mine 的全部不生效（abc 字节串在、属性指令无效，跨 4 种注入位置复现）。
-- 需求：**smart_check/smart_click 必须带 orig_target 文本兜底**（key 失败转文本/类型断言）。
-- 来源：News 工程（2026-09-23 实测）。
-
-### DFT-008 同控件多次注入会叠 id（仅首个生效）
-- 现象：多条用例引用同一控件时注入器产生 `.id(a).id(b)`，运行时仅第一个可查。
-- 需求/skill 规则：**用例引用统一到首注入 ID（`_1` 后缀规约）**；注入器应检测已有 tc_ id 并复用。
-
-### DFT-009 Tab 切换的可靠路径
-- 现象：BY.text 精确/模糊点击 Tab 均可能点到正文同名文本；比例坐标受 Tab 数量与手势条影响。
-- 需求/skill 规则：**click_tab 用 find_all_components 取「最靠下的同名文本」的 bounds 中心 touch**（News/SchoolLife/CoolMall 2/3/4-Tab 全验证通过）。
-
-### DFT-010 资源化文案使静态覆盖度失准
-- 现象：CoolMall（70k 行）源码文案全部 `$r()` 资源化，scan 的交互点与运行时文本不匹配 → 静态覆盖度 0%。
-- 需求/skill 规则：大型工程覆盖度评估降级为**运行时可达性口径**（用例通过率 + dump 文本对照）；源码覆盖度仅对硬编码文案工程有效。
-
-### DFT-011 用例间需间歇（teardown 冷启动时序）
-- 现象：批量连跑时下一条 setup 的 start_app 未完成即断言（TC01 偶发失败）。
-- skill 规则：批量执行循环 **sleep 3s** + launch 等待 2.5s 起步。
-
-### DFT-012 输入法首用向导是隐藏前置（CoolMall 实测）
-- 现象：input_text 前拉起「小艺输入法」声明弹窗 + 键盘布局向导（多步），挡住输入与提交按钮；向导期间点登录无效。
-- skill 规则：precondition 增加 IME 预置步骤——检测并依次点掉「同意/下一步/完成」；输入后 **press_back 收键盘再点提交按钮**（否则按钮被键盘遮挡）。
-
-### DFT-013 输入框定位用 BY.hint 不用 BY.text
-- 现象：`BY.text('请输入手机号')` 匹配到的是 hint 展示文本节点而非 TextInput 本体，input_text 无效且无报错。
-- skill 规则：**带占位符的输入框一律 `BY.hint('<placeholder>')` 定位**（hypium 专属匹配器）。
-
-### DFT-014 设备访问 PC mock 需 rport（fport 是反向）
-- 现象：`hdc fport` 是 PC→设备方向；设备 App 访问 127.0.0.1:8787 的 PC mock 必须用 `hdc rport tcp:8787 tcp:8787`（CoolMall BASE_URL 已预指 mock）。
-- 附：mock 重启后 App 需 aa force-stop 冷启动才重新拉数据（失败态有缓存）。
+# 可测试性需求（Design for Testability）— 模板与累积清单
+
+> 调测中发现的「让 hypium 测试变慢/不准」的工程特征，反哺为对应用开发的需求。
+> 每条格式：现象（实测） → 根因 → 可测试性需求（对开发的要求） → 收益。
+
+## 累积清单（按工程验证时追加）
+
+### DFT-001 控件必须预置稳定 ID
+- 现象：无 .id() 控件用 BY.text 定位，文案随数据变化 → 脚本重试多轮、不稳定（实测：首个转化工程首轮全部超时）。
+- 根因：ArkTS 开发普遍省略 .id()，uitest 只能按 text/type 匹配。
+- 需求：**所有可交互控件（Button/Toggle/TextInput/入口 Image）必须写 .id()**，命名 `<语义>_<页面>`（如 btn_settings_index）。
+- 收益：脚本零重试定位；用例与实现解耦（文案改了脚本不断）。
+
+### DFT-002 条件渲染控件需可达路径
+- 现象：`if(testMode)` 内控件默认态不存在，存在性断言误报失败（实测 START TEST 按钮）。
+- 需求：条件功能的入口开关应在**入口页可达**（≤2 步操作），或提供 deeplink/want 参数直达。
+- 收益：状态覆盖用例可自动执行，不依赖复杂前置链。
+
+### DFT-003 运行时权限在模拟器的可预授性
+- 现象：首启权限弹窗阻塞 BFS/用例执行（实测 RaiseToAnswer 电话权限）。
+- 需求：应用不应在首帧同步弹多个权限弹窗；权限申请延后到功能触发点。
+- 收益：precondition 批量预授后用例零弹窗干扰。
+
+### DFT-004 登录需提供测试通道
+- 现象：真实登录页在模拟器无法自动完成 → 登录后功能全部 BLOCKED。
+- 需求：提供 mock 登录开关（want 参数/环境开关）或测试账号常量。
+- 收益：登录态用例可全自动执行。
+
+### DFT-005 首启弹窗需可编程处置
+- 现象：隐私协议/引导页弹窗文案各异，逐个适配成本高。
+- 需求：首启弹窗按钮文案使用标准词（同意并继续/跳过/我知道了）；提供"不再提醒"。
+- 收益：统一 dismiss 片段即可覆盖。
+
+（新工程验证时按编号追加，注明来源工程与实测数据）
+
+### DFT-006 HAP 更新必须卸载重装（模拟器缓存怪癖）
+- 现象：`install -r` 同版本号替换后，注入的 .id 运行时全部丢失（abc 缓存不失效，实测 News 工程）。
+- 需求/skill 规则：**注入 ID 重打包后一律 `hdc uninstall <bundle> && hdc install <hap>`**。
+
+### DFT-007 部分 HAR 模块 .id 运行时丢弃（待官方解释）
+- 现象：同一 HAP 内 commons/features-home 的 .id 生效，features-mine 的全部不生效（abc 字节串在、属性指令无效，跨 4 种注入位置复现）。
+- 需求：**smart_check/smart_click 必须带 orig_target 文本兜底**（key 失败转文本/类型断言）。
+- 来源：News 工程（2026-09-23 实测）。
+
+### DFT-008 同控件多次注入会叠 id（仅首个生效）
+- 现象：多条用例引用同一控件时注入器产生 `.id(a).id(b)`，运行时仅第一个可查。
+- 需求/skill 规则：**用例引用统一到首注入 ID（`_1` 后缀规约）**；注入器应检测已有 tc_ id 并复用。
+
+### DFT-009 Tab 切换的可靠路径
+- 现象：BY.text 精确/模糊点击 Tab 均可能点到正文同名文本；比例坐标受 Tab 数量与手势条影响。
+- 需求/skill 规则：**click_tab 用 find_all_components 取「最靠下的同名文本」的 bounds 中心 touch**（News/SchoolLife/CoolMall 2/3/4-Tab 全验证通过）。
+
+### DFT-010 资源化文案使静态覆盖度失准
+- 现象：CoolMall（70k 行）源码文案全部 `$r()` 资源化，scan 的交互点与运行时文本不匹配 → 静态覆盖度 0%。
+- 需求/skill 规则：大型工程覆盖度评估降级为**运行时可达性口径**（用例通过率 + dump 文本对照）；源码覆盖度仅对硬编码文案工程有效。
+
+### DFT-011 用例间需间歇（teardown 冷启动时序）
+- 现象：批量连跑时下一条 setup 的 start_app 未完成即断言（TC01 偶发失败）。
+- skill 规则：批量执行循环 **sleep 3s** + launch 等待 2.5s 起步。
+
+### DFT-012 输入法首用向导是隐藏前置（CoolMall 实测）
+- 现象：input_text 前拉起「小艺输入法」声明弹窗 + 键盘布局向导（多步），挡住输入与提交按钮；向导期间点登录无效。
+- skill 规则：precondition 增加 IME 预置步骤——检测并依次点掉「同意/下一步/完成」；输入后 **press_back 收键盘再点提交按钮**（否则按钮被键盘遮挡）。
+
+### DFT-013 输入框定位用 BY.hint 不用 BY.text
+- 现象：`BY.text('请输入手机号')` 匹配到的是 hint 展示文本节点而非 TextInput 本体，input_text 无效且无报错。
+- skill 规则：**带占位符的输入框一律 `BY.hint('<placeholder>')` 定位**（hypium 专属匹配器）。
+
+### DFT-014 设备访问 PC mock 需 rport（fport 是反向）
+- 现象：`hdc fport` 是 PC→设备方向；设备 App 访问 127.0.0.1:8787 的 PC mock 必须用 `hdc rport tcp:8787 tcp:8787`（CoolMall BASE_URL 已预指 mock）。
+- 附：mock 重启后 App 需 aa force-stop 冷启动才重新拉数据（失败态有缓存）。