# 文档学习 backlog

> **状态：0.3 基线快照（历史）。** 文中的规则数量、版本计划和“未覆盖”结论已过时；
> 当前 0.7.0 的能力与规则数见 README、`dwguard_rules list` 和 `docs/0.7.0-plan.md`。

记录「官方文档还没学什么、值不值得学、什么时候学」。规则库只收**有官方出处 + 可证伪验证方式**的条目；没学透的内容先放这里，不硬塞进 `must` 判据。

## 现状

| 已吸收 | 规模 | 落到哪 |
| --- | --- | --- |
| 华为 UX 设计文档（llms 索引的 `.md` 原文） | 28 篇 / ~500 KB | 热区、对比度、字号、间距/圆角、色彩、转场、深色、折叠屏、图标、焦点 |
| OpenHarmony 应用开发文档（sparse clone，commit `f41b934`） | 675 篇 / 10.6 MB | 状态观察范围、LazyForEach、无障碍属性、性能分析/优化、ArkTS 适配、字体缩放 |
| AGC 提审常见拒因 | Top 20 | 隐私、权限、IAP、日志、后台任务、包体等 12 条映射 |

规则库现状：**41 条规则，32 条带官方 citation**；扫描规则 8 条。  
已修正案例：`STATE-002`（数组 push 不触发刷新）被官方 `arkts-state.md` 推翻，改为 `STATE-NESTED-01`（嵌套属性赋值不触发）。

## 未覆盖清单

| 未学内容 | 价值 | 成本 | 计划 | 具体产出 |
| --- | --- | --- | --- | --- |
| **无障碍深水区**：读屏、焦点顺序、无障碍树/uitest、动态字体 | 高（直接喂 A11Y 维度） | 中 | 0.4 | 4–6 条 `must` 判据 + `hdc uitest dumpLayout` / 无障碍树取证步骤 |
| **ArkUI V2 状态管理**：`@ObservedV2` / `@Trace` / `@Local` 语义与 V1 边界 | 高（现在只查"混用"，没审 V2 用法） | 中 | 0.4 | 3–4 条 `must` 判据 + 扫描规则（V2 误用/V1 混用边界） |
| **性能工具链**：Profiler 采集、冷启动分段、帧率/内存基线 | 高（P-* 判据的取证方法） | 中 | 0.4 | 取证手册（命令 + 截图口径 + 基线表），补进 `hmos-audit-playbook` |
| **Design 组件级规格**（约 50 个组件页，目前只取了按钮/徽标/半模态等少量） | 中（审美与交互判据更细） | 中 | 0.4 起按高频组件分批 | 10 个高频组件的尺寸/状态/间距规格，落 `should` 判据 |
| **AGC 官方审核标准原文 + 签名/上架流程** | 中（发布合规） | 小 | 0.5 | 上架前检查清单 + 取证项 |
| **隐私/安全设计指南**（权限最小化、数据分级） | 中 | 小 | 0.5 | 权限最小化与数据分级判据（可与 AGC 合并） |
| **API Reference**（`reference/`，数千页） | 低（按需查，不进规则库） | 很大 | 按需 | 只做 `dwguard_rules search` 入口，不建规则 |
| **多设备**：手表/智慧屏/PC 专用规范 | 低（手机项目用不上） | 中 | 按需 | 单独 skill/文档，不混入主规则 |
| **ArkTS 1.2 / 静态化**（HarmonyOS 6+ 方向） | 观察 | 大 | 观察 | 等生态稳定后再评估 |

## 本轮进展（0.3.0，不升版本）

已从 backlog 落成规则（75 条 / 66 条带 citation）：

| 领域 | 已落 | 还差 |
| --- | --- | --- |
| 无障碍深水区 | `A11Y-09` 分组播报、`A11Y-10` 无障碍层级、`A11Y-11` 提示分离、`A11Y-12` 键盘可达、`A11Y-13` 2x 字体；`scripts/a11y-walkthrough.md`；`dwguard_deveco a11y` 快照（布局树 + accessibilityId + 静态扫描） | 完整无障碍树（`ui layout`/`uitest` 不含 accessibilityText/Level，列 research） |
| ArkUI V2 | `STATE-02` @ObservedV2+@Trace、`STATE-03` V1/V2 混用、`STATE-04` @Local 边界、`STATE-05` @Param+@Event、`STATE-06` @Monitor、`STATE-07` @Computed、`STATE-08` @Provider/@Consumer、`STATE-09` V1→V2 迁移 | V1→V2 迁移案例文档（规则已覆盖，示例待补） |
| 性能工具链 | `PERF-10` 冷启动五阶段、`PERF-11` 超长帧；`docs/perf-baseline.md` 机型矩阵 + Profiler 模板 | 首个项目实测后回填基线 |
| AGC + 隐私 | `AGC-01~09`（签名/不可调试、隐私政策、权限拒绝、敏感权限目的、应用信息、测试账号、双清单、热更新、广告法）；`docs/agc-publishing.md` | 特殊行业资质按项目补 |
| Design 组件 | `AES-12` 按钮、`AES-13~21` 列表/文本框/弹出框/标题栏/底部页签/开关/进度条/Symbol 图标/卡片式列表 | 更细的组件状态与动效（0.4.x） |

未开始：API Reference（按需检索）、多设备、ArkTS 1.2（观察）。

## 0.4 优先顺序

1. **无障碍深水区**——四维里最容易被"看着能点"糊弄的一维，收益最高；
2. **ArkUI V2**——新项目会越来越多，V1 经验不能直接套；
3. **性能工具链**——把 P-* 判据从"贴个截图"变成"可复现的采集步骤 + 基线"；
4. **组件规格（高频 10 个）**——审美判据从"token 对"走向"组件状态对"。

## 收录原则

- 只有**官方引用 + 可证伪验证方式**都齐全的，才进 `must`；
- 学不透的先写 `should` 或文档，不硬塞规则；
- 每条新规则必须写清 `verify`（命令/截图/测量），否则不写；
- 抓不到原文的，标 `source: DwGuard 验收规则`，不伪造 citation。