mobile-platform-offline-validate

LWC 移动端离线审查

对 Lightning Web Component 执行结构化的离线预加载合规检查，生成问题报告和代码级修复建议，帮助组件符合 Komaci 对 Salesforce Mobile App Plus 和 Field Service Mobile App 的静态分析要求。

适用场景

• 用户要求对特定 LWC 进行“移动端离线审查”“Komaci 检查”或“离线预加载审计”。
• 准备让组件在 Salesforce Mobile App Plus 或 Field Service Mobile App 离线模式下发布。
• 调查离线分析器报告的预加载失败问题。

请勿将此技能用于：

• 构建使用原生移动功能（条码扫描器、生物识别、位置等）的 LWC — 请使用 mobile-platform-native-capabilities-integrate。
• 通用 LWC 代码审查 — 请使用相应的领域技能 (reviewing-lws-security、reviewing-lwc-rtl、accessibility-code-review)。

前置条件

• 组件路径（modules/… 下的 LWC bundle）。
• 可访问组件的 JS/TS 和 HTML 模板。
• 本地 Node + npm；能够通过 npx eslint 运行 @salesforce/eslint-plugin-lwc-graph-analyzer 插件。

知识库

移动端离线原理说明解释了三类违规及其阻止离线预加载的原因。开始评估前请先阅读。以下各审查员参考文档是规则和修复方法的权威来源：

• 内联 GraphQL wire 配置：内联 GraphQL 审查员
• lwc:if 条件渲染兼容性：lwc:if 审查员
• Komaci ESLint 静态分析：Komaci ESLint 审查员

工作流

步骤 1 — 确定审查范围

确定组件 bundle：.html、.js/.ts。CSS 和 meta 文件不属于离线预加载审查范围。如果 bundle 包含多个 HTML 模板，则全部审查。

步骤 2 — 阅读原理说明和各审查员参考文档

在评估之前，完整阅读移动端离线原理说明和三份审查员参考文档。输出每条发现时都要注明具体的审查员，以便审计报告。

步骤 3 — lwc:if / lwc:elseif / lwc:else（HTML）

遍历 bundle 中的每个 .html 文件，并应用 lwc:if 审查员中的规则。对于每处 lwc:if={…}、lwc:elseif={…} 或 lwc:else，都输出一条发现，并给出准确的 if:true / if:false 改写方案 — 包括保留 lwc:elseif 和 lwc:else 语义所需的嵌套结构。

步骤 4 — @wire 中的内联 GraphQL（JS）

遍历 bundle 中的每个 .js/.ts 文件，并应用 内联 GraphQL 审查员中的规则。对于每个直接引用 gql 模板字面量（或通过顶层常量引用它）的 @wire，都输出一条发现，指出一个具体的 getter，并展示改写后的 @wire 配置。

步骤 5 — Komaci ESLint 检查（JS）

使用随附脚本，对 bundle 的 JS 文件运行 Komaci ESLint 分析器。该脚本启用 bundleAnalyzer 处理器，并应用 @salesforce/eslint-plugin-lwc-graph-analyzer 推荐规则集。

scripts/run-komaci.sh path/to/component.js

脚本要求 @salesforce/eslint-plugin-lwc-graph-analyzer 可从工作目录解析，并且组件的同级 HTML 模板必须与 JS 文件位于同一目录（插件的 bundleAnalyzer 处理器会使用这些模板解析离线数据图）。输出为 stdout 上的 ESLint --format json 格式。

对于输出中的每个 messages[*] 条目，按 ruleId 分组，并在 Komaci ESLint 审查员中查找对应规则的修复方法。针对每个（规则，行）组合输出一条发现，并使用参考文档中的准确修复文本；不要自行编造建议。如果运行环境无法使用该脚本，请参阅参考文档中的手动 npx eslint ... 调用方式。

步骤 6 — 生成报告

按以下格式输出报告：

## Mobile Offline (Komaci priming)
- <reviewer> — <file>:<startLine>:<startColumn>-<endLine>:<endColumn> — <type>
  Description: <verbatim from the reviewer reference>
  Intent analysis: <verbatim from the reviewer reference>
  Suggested action: <verbatim from the reviewer reference>
  Code: |
    <source snippet from startLine through endLine, optional but
     recommended when the violation spans multiple lines>
  Applied: yes/no

## Summary
- <n> issues found; <m> fixed; <k> deferred (with reason)

对于 Komaci ESLint 发现的问题，从 ESLint 消息的 line/column/endLine/endColumn 中提取 startLine/startColumn/endLine/endColumn。 对于 Inline GraphQL 和 lwc:if 发现的问题，提供你在源代码中观察到的行/列范围。如果某个问题没有 endLine/endColumn，则回退为 <file>:<startLine>，并省略末尾的范围。

每个问题都要注明审查者（Inline GraphQL / lwc:if / Komaci ESLint 规则 ID）。

步骤 7 — 应用修复

用户要求修复时，直接应用补救措施。如果某项补救措施与组件在离线场景之外的行为冲突（例如，开发者为了提高可读性而使用 lwc:elseif，且用户尚未准备在移动端离线环境中发布），则应将冲突列入延期清单，而不是悄悄重写。

验证清单

• 每个 lwc:if / lwc:elseif / lwc:else 是否都已标记或不存在。
• 是否检查了每个引用 gql 的 @wire；内联查询是否已提取到 getter 中。
• 是否确实运行了 Komaci ESLint 分析器；发现的问题是否引用了真实规则 ID，而非杜撰的 ID。
• 每个问题是否都注明了对应的审查者或规则 ID。
• 是否没有涉及上述三个类别之外的补救措施（其他问题应交由其他技能处理）。

故障排查

• npx eslint 找不到插件 — 在工作区中安装 @salesforce/eslint-plugin-lwc-graph-analyzer，或使用固定的本地安装路径。该插件是 Komaci 规则的权威来源。
• 与 bundleAnalyzer 相关的错误 — 推荐配置会驱动 bundle 处理器；不要移除它。该处理器需要能够找到同级 HTML 文件。如果在精简版 JS 文件上运行，请在临时目录中提供匹配的 HTML 文件。
• 预期会报错的组件没有发现问题 — 确认已应用推荐规则集（而非仅使用规则为空的 bundleAnalyzer）。部分规则要求 HTML 文件与 JS 文件放在一起。
• 专用审查者报告的 lwc:if 问题重复出现 — Komaci 插件不检查模板；lwc:if 检查仅针对 HTML，来自步骤 3。步骤 5 的发现仅针对 JS。