experience-aura-lwc-migrate

将 Aura 迁移到 LWC

使用由 PRD 驱动的工作流，将现有的 Salesforce Aura 组件包迁移到 Lightning Web Component。通过八个专家视角分析 Aura 源码（静态引用、数据、API 表面、插槽、样式、默认值、未知依赖项、冗余代码清理），生成与框架无关的 PRD，再交由 LWC 编写技能处理，并依据 Aura→LWC 完整性检查清单进行验证。

适用场景

• 将 Aura 组件包（.cmp、.controller.js、.helper.js、.renderer.js、.css、.design、.evt、.intf）移植到 LWC。
• 从 Aura 源码生成与框架无关的 PRD，以便协作团队实现对应的 LWC。
• 审查 Aura 组件，找出转换为 LWC 前需要明确映射的模式（facets、aura:id DOM 访问、force:recordData、应用事件）。

请勿在以下场景中使用此技能：

• 从 Figma 或 PRD 编写全新的 LWC，且没有 Aura 源码（请转交给 experience-lwc-generate）。
• 重构现有 LWC（请转交给 experience-lwc-generate）。
• 对未使用此技能完成的转换进行事后完整性评分，或将 Lightning Out Beta 迁移到 2.0 宿主页面——目前没有已检入的技能涵盖这些场景。

前置条件

• Aura 组件包文件（至少需要 .cmp；通常还包括控制器、helper、CSS、事件和接口）。
• 目标 LWC 路径（模块文件夹）——从 sfdx-project.json 的 packageDirectories 中查找调用方的模块目录树（通常是其中一个列出的包路径下的 lwc/<name>/ 子目录）。
• 若要通过解析器辅助查找依赖项（阶段 2，第 7 步）：调用方工作区中已安装 @sfdc-internal/adk-knowledge 包。如果未安装，技能会将缺失的依赖项标记为未知，而不会失败。
• 了解项目后续的 LWC 编写流程——此技能会将 PRD 交接给该流程，但不会调用它。

核心原则

在每个阶段开始前和执行期间，遵循 Aura → LWC 迁移原则：先理解再转换，优先保证功能等价而非结构等价，利用原生 Web 标准，逐步迁移，并进行充分测试。架构差异（双向绑定 → 单向绑定、Aura 事件 → DOM 事件、aura:id → this.template.querySelector 等）记录在 references/aura-migration-guidelines.md 中。

知识库

• references/aura-prd-framework.md — 从 Aura 组件起草框架无关 PRD 的 14 个部分组成的框架。
• references/aura-migration-guidelines.md — 核心原则 + Aura 与 LWC 的架构差异 + 标记 / JS / 事件 / 生命周期转换表。
• references/aura-reference-expert.md — 静态资源、全局值提供程序、HTML 转通用表述、URL、组件依赖项、Aura.Action 处理程序。
• references/aura-data-expert.md — 数据要求、force:recordData、lightning:recordViewForm、Apex 控制器。
• references/aura-api-expert.md — API 表面：公共属性、方法、布局、组件事件、DOM 事件。
• references/aura-slots-expert.md — 默认和命名插槽（Aura facets / {!v.body} → LWC 插槽）。
• references/aura-style-expert.md — CSS、SLDS、设计令牌、动态样式。
• references/aura-values-expert.md — 默认值和初始化模式。
• references/aura-resolver-expert.md — 通过 @sfdc-internal/adk-knowledge 包解析未知组件、事件、接口和库。
• references/aura-redundant-code-expert.md — 在交接给 LWC 前，从 PRD 中去除仅适用于 Aura 的冗余内容（已注释代码、遥测、未使用的私有属性 / 方法）。
• WCAG 2.2 — 计划在后续 PR 中单独推出 Aura 专用无障碍审查技能 accessibility-code-review-aura（SC 1.3.1 (ii) 表格、1.3.5 识别输入用途、3.2.1 聚焦时、3.2.2 输入时、3.3.2 标签或说明、4.1.2 名称 / 角色 / 值）；在此之前，Phase 3 会内嵌应用 WCAG 前言。
• references/aura-to-lwc-completeness-checklist.md — 转换后的验证标准。

起草或完善相应 PRD 部分之前，请先打开相关参考资料。

工作流

此技能仅涵盖分析和 PRD 生成阶段。它不会生成、编辑或验证 LWC 包、wire 适配器或测试。调用此技能时，必须执行以下 Phase 1–3。Phase 4–5 描述了推荐的后续编写流程，仅供调用方参考，不会由此技能执行。

Phase 1 — 分析并起草 PRD

**目标：**生成一份 PRD YAML 草稿，涵盖 14 部分框架中的所有内容。

1. 检查调用方提供的 Aura 包文件。提取组件名称、.cmp 元数据中的 access 属性，以及所有嵌入或引用的组件。
2. 应用 references/aura-prd-framework.md 中的框架。在概述中明确写出 access 属性，并说明其影响（GLOBAL：可供所有命名空间公开使用；PRIVILEGED/PUBLIC：受限；等等）。
3. 切勿在 unknowns 部分列出宿主组件本身，否则会造成循环依赖。如果不存在有效的未知项，请使用空数组。
4. 将 PRD 草稿保存到工作区（例如，packages/skills/<skill>-workspace/<iteration>/PRD-draft.yaml）。

**交付物：**涵盖 14 个部分的 PRD 草稿（YAML）。

阶段 2 — 使用 Aura 专家视角完善 PRD

目标： 使用八种 Aura 专家框架强化每个章节。

按顺序应用各位专家的分析。每轮都读取 PRD 草稿，并就地重写相关章节。

1. 引用分析 — 对 staticReferences、componentCommunication 和 unknowns 应用 references/aura-reference-expert.md。枚举每个 $Resource、$ContentAsset、$Label、$Browser、$Locale、/lightning/* 路由，以及 c:* / force:* / lightning:* 依赖。蓝图中绝不能直接包含 Aura 专属字符串 $ContentAsset、$Label、$Resource、$Browser 或 $Locale；请将每个字符串替换为意图描述。
2. 数据分析 — 对 dataRequirements 应用 references/aura-data-expert.md。蓝图的 dataRequirements 不得包含 force:recordData 或 lightning:recordViewForm — 请改为记录底层记录、字段和对象 API 名称。将 sObjectName 重命名为 objectApiName。记录 Apex 控制器方法名称、输入参数和输出结构。
3. API 分析 — 对 componentCommunication、interactions 和 staticReferences 应用 references/aura-api-expert.md。记录每个公开属性（包括类型、默认值和所有用途）、<aura:method> 声明、事件触发（component.getEvent(...).fire()），以及 Object 类型的回调属性（这些属性会转换为 LWC 自定义事件）。
4. 插槽分析 — 对 contentRequirements 应用 references/aura-slots-expert.md。将每个 {!v.body} / {#v.body} 转换为默认插槽条目（LWC 组件只能有一个默认插槽 — 记录其出现的条件），并将每个 <aura:attribute type="Aura.Component"> 或 "Aura.Component[]" 转换为具名插槽条目。
5. 样式分析 — 对 styling 和 dataRequirements 应用 references/aura-style-expert.md。将与样式相关的属性从 dataRequirements 移至 styling。记录 SLDS 钩子、自定义 CSS，以及由 JS 驱动的任何动态样式。
6. 取值分析 — 对 dataRequirements 应用 references/aura-values-expert.md。对于每个 Aura 属性，在 what 属性中记录其默认值（类型 + 字面值；或 $Label 引用的命名空间 + 名称）。
7. 解析器分析 — 对 unknowns 应用 references/aura-resolver-expert.md。对于每个未知项，解析命名空间 + 名称，根据映射规则查找 node_modules/@sfdc-internal/adk-knowledge/dist/ 下对应的文件，然后内联解析出的内容，或注明需要人工研究。如果未安装 @sfdc-internal/adk-knowledge 包，请注明预期路径并保留该未知项。
8. 冗余代码清理 — 对整个 PRD 应用 references/aura-redundant-code-expert.md。删除已注释掉的标记/JS/CSS、遥测/检测代码，以及其他位置未使用的私有属性/方法 — 这些内容不会迁移到 LWC。保持 PRD 的 JSON 结构不变；各章节可以包含空数组。生成一份简短报告，仅列出实际发生变化的项目。

交付内容： 应用了全部八轮专家分析的增强版 PRD（YAML）。

阶段 3 — 无障碍检查

**目标：**确保 PRD 的 accessibility 部分符合 WCAG 2.2 的最低要求。

1. 对 Aura 源文件（.cmp、.controller.js、.helper.js、.renderer.js、.css）应用 WCAG 2.2 审查指南。涵盖 Aura 范围内的成功准则：1.3.1（ii）表格、1.3.5 识别输入目的、3.2.1 获得焦点、3.2.2 输入、3.3.2 标签或说明、4.1.2 名称／角色／值。（如果后续 PR 中发布了配套的 accessibility-code-review-aura 技能，则改为移交给该技能。）
2. 将每项发现纳入 PRD 的 accessibility 部分。对于每项要求，注明其满足的 WCAG 成功准则，以及拟议的 LWC 实现方式（优先使用语义化 HTML，仅在语义化 HTML 无法实现相同效果时才使用 ARIA）。
3. 仅指出直接违反 WCAG 成功准则的问题。不要提出 WCAG 范围之外的改进建议。

**交付物：**包含无障碍部分的 PRD，其中列出每项必需功能、其满足的 WCAG 成功准则以及 LWC 实现方式。

阶段 4 — 下游编写（后续指导，本阶段不执行）

增强版 PRD 完成后，调用方可以将其交给 LWC 编写工作流。本技能不执行任何编写工作。建议的后续步骤：

• 将增强版 PRD 作为设计输入传递给 experience-lwc-generate，替代 Figma／书面规格输入。本技能不会调用 experience-lwc-generate；调用方应将其作为后续步骤触发。
• 对于数据访问决策（UIAPI／GraphQL／Apex），调用方可以咨询以 LDS 为重点的工作流，将 PRD 的 dataRequirements 部分转化为具体适配器。
• 对于 SLDS 样式决策，调用方可以咨询 SLDS 设计工作流。

阶段 5 — 下游验证（后续指导，本阶段不执行）

LWC 编写完成后，调用方可以使用项目的标准测试和审查工作流验证迁移后的组件——Jest 覆盖率、无障碍 Jest、a11y／安全／RTL 审查、遥测、功能标志控制等。将 references/aura-to-lwc-completeness-checklist.md 用作已完成 LWC 的最终评分检查。

交叉引用

• experience-lwc-generate — 建议的下游编写交接（不执行；调用方应在本技能完成 PRD 后触发）。

验证（仅限 PRD）

• 增强版 PRD 涵盖全部 14 个框架部分，且不含 TODO／占位内容。
• dataRequirements 不直接引用 force:recordData 或 lightning:recordViewForm，也不包含 sObjectName 键（已重命名为 objectApiName）。
• staticReferences 和其他部分不含 $Resource、$Label、$ContentAsset、$Browser、$Locale 等原始 Aura 字符串。
• 每个 <aura:method> 都出现在 interactions 中，并附有相应的触发条件。
• 每个 {!v.body}／{#v.body} 都作为默认插槽出现在 contentRequirements 中（并注明存在条件）。
• 每个 <aura:attribute type="Aura.Component"> 都作为命名插槽出现在 contentRequirements 中。
• 所有未知项均已通过 @sfdc-internal/adk-knowledge 包解决（或标记为需手动处理，并注明尝试过的知识文件路径）。