experience-lwc-legacy-migrate

迁移旧版 LWC 技术栈

这里包含两种不同的迁移工作流，因为正在迁移 Aura 组件的用户通常也在迁移 Lightning Out 宿主页面——他们可以从同时了解两者的技能中受益。

迁移	使用场景	参考
Aura → LWC 完整性检查	Aura 组件已转换，需要验证是否有内容遗漏	aura-to-lwc-completeness-checklist.md
Lightning Out Beta → LO 2.0	将外部宿主页面从 lightning.out.js 迁移出去	lightning-out-beta-to-2-migration.md

何时使用此技能

• 用户已将 Aura 组件转换为 LWC，并希望进行结构化的完整性检查。
• 用户拥有一个非 Salesforce 宿主页面，该页面通过 Lightning Out Beta 嵌入 Salesforce LWC，需要迁移到 LO 2.0。
• 用户要将 $Lightning.use() / $Lightning.createComponent() 调用升级为 <lightning-out-application> Web 组件模式。
• 用户需要将硬编码的 LO 身份验证令牌替换为 OAuth PKCE + front-door 流程。

如果用户想从头构建全新的 LO 2.0 宿主页面（没有 Beta 代码需要迁移），此技能中的 LO 2.0 系统参考仍是权威信息来源——请直接引导他们查看。

先决条件

• 能够访问源文件（Aura 组件文件或 Beta 宿主页面）。
• 对于 LO 2.0 迁移：能够在 Salesforce Setup 中创建 External Client App (ECA)（需要 Consumer Key），并可选择创建 Lightning Out 2.0 App（18 位 App ID）。
• 对于 Aura 迁移：能够访问 LWC 转换内容，包括任何现有的 __tests__（Jest）和 __utam__（UTAM）文件夹。

工作流 A — Aura → LWC 完整性检查

目标：从 12 个维度评估已完成的 Aura 到 LWC 转换，并提出可执行的建议。

步骤 A1 — 确定组件

请用户提供组件名称（例如 accountTile）。定位 Aura 源文件（{componentName}.cmp、controller、helper、CSS）和 LWC 输出（{componentName}.html、.js、.css、.js-meta.xml）。

步骤 A2 — 执行检查清单

逐字遵循 aura-to-lwc-completeness-checklist.md：

• 按全部 12 项指标为转换打分（功能对等性、事件处理、数据绑定与状态、UI/UX 对等性、可扩展性与模块化、错误处理、本地化、安全与访问控制、性能、Salesforce 最佳实践、Jest 测试覆盖率、UTAM 页面对象）。
• 使用六级评分标准：Excellent / Good / Satisfactory / Limited / Poor / Missing。
• 按参考文档要求，以列表（而非表格）的形式呈现结果。

步骤 A3 — 总结并提出建议

最后给出总体信心评估，并按优先级列出具体、可执行的建议（修复什么、按什么顺序）。

工作流 B — Lightning Out Beta → LO 2.0

目标：将 Lightning Out Beta 宿主页面转换为 Lightning Out 2.0 宿主页面，同时保留客户的 HTML 结构、样式和业务逻辑。

步骤 B1 — 阅读 LO 2.0 心智模型

在编辑代码之前理解其架构： lightning-out-2-system-reference.md。

核心要点：LO 2.0 并非库升级。它在 iframe 中运行 LWC，并使用封闭的 shadow DOM——宿主页面的 JS 无法触及 LWC，反之亦然；宿主页面的 CSS 也不会层叠到其中。

步骤 B2 — 识别 Beta 模式

使用迁移指南的第 1 阶段查找：

• 模式 A — 加载 lightning.out.js 的脚本标签（提取域名）。
• 模式 B — 配置变量（端点、Aura 应用、组件、令牌）。
• 模式 C — $Lightning.use(...) 调用。
• 模式 D — $Lightning.createComponent(...) 调用。
• 模式 E — 模式 D 的第 3 个参数所引用的 DOM 目标元素。

参见 lightning-out-beta-to-2-migration.md § Phase 1。

步骤 B3 — 应用转换

脚本标签 URL、组件标签名称和属性名称的转换是确定性的——使用辅助脚本推导，确保每次结果都准确无误（保留命名空间，camelCase → kebab-case，Beta 主机 → 版本化 LO 2.0 库 URL）：

python3 scripts/convert-lo-names.py \
  --component c:myComponent \
  --attributes recordId,ownerId \
  --my-domain https://<DOMAIN>.lightning.force.com

它会输出 <c-...> 标签、kebab-case 属性和版本化 LO 2.0 库 URL。然后按照指南第 2 阶段操作：

1. 脚本标签 — 使用脚本输出的 library-url；添加 async。
2. 组件名称 / 属性 — 使用脚本输出的 component-tag 和 kebab-case 属性。
3. 组件标签 — 在目标位置直接将 <c-...> 标签添加到 HTML 中（此处需要自行判断——放在 Beta 渲染目标所在的位置）。
4. 替换 $Lightning 代码块 — 将其彻底删除，并从 assets/lo20-host-page-template.html 开始，填入配置常量；模板已包含辅助函数、mountLo20(frontdoorUrl, orgUrl)、boot() 和 OAuth 监听器。

步骤 B4 — 六条不可妥协的规则

违反这些规则会导致运行时静默失败，而且每条规则都可以通过确定性的代码结构检查来验证。不要凭目测检查，而应使用验证脚本强制执行——对迁移后的页面运行脚本并修复每一项 FAIL：

python3 scripts/validate-lo20-page.py <migrated-page.html>

脚本会为每条规则（以及 LO 2.0 库和移除 Beta 的检查）输出一行 PASS/FAIL；任何规则检查失败时，脚本都会以非零状态码退出。它会强制执行以下六条规则：

1. customElements.whenDefined(...) 必须接收字面字符串，不能使用 components 变量。
2. mountLo20(frontdoorUrl, orgUrl) 必须接受两个参数。
3. 每次调用 mountLo20(...) 前都必须调用 clearCachedResult()。
4. 调用 mountLo20(...) 时始终传入两个参数，即使 orgUrl 未定义也不例外。
5. 所有初始化都必须封装在 boot() 中，并在末尾调用 boot()。
6. 组件标签不能包含内联 display:none——应通过加载指示器控制可见性。

步骤 B5 — Salesforce 设置

• External Client App（ECA） — Setup → App Manager → New Connected App → External Client App。启用带 PKCE 的 OAuth。复制 Consumer Key。

• Lightning Out 2.0 App — 继续操作前先根据以下情况作出决定：

  条件	操作
  主机页面设置了 app-id="..."	Setup → Lightning Out → New LO App；将 18 位 App ID 复制到主机页面的 app-id 属性中
  主机页面直接嵌入 LWC（没有 app-id）	完全跳过 LO App

• 迁移默认与主机页面位于同一目录中的辅助文件： frontdoor-url.html（OAuth 回调）和 utils/LightningOutAuth.js （PKCE 实现）。

步骤 B6 — 执行 LO 2.0 验证清单

先运行 python3 scripts/validate-lo20-page.py <migrated-page.html>，通过机械检查，然后逐项完成完整迁移后检查清单中剩余的手动检查项——必须涵盖所有项目后才能宣布迁移完成。参见 lightning-out-beta-to-2-migration.md 末尾的“Verification Checklist”部分。

验证清单（高级别）

对于 Aura → LWC：

• 12 项完整性指标均已评分，并附有理由。
• 输出采用列表形式（而非表格），符合参考示例。
• 包含总体置信度说明。
• 列出具体且按优先级排序的建议。

对于 LO Beta → LO 2.0：

• 脚本标签使用 .my.salesforce.com/lightning/lightning.out.latest/index.iife.prod.js，并带有 async。
• 不再包含对 $Lightning.use / $Lightning.createComponent 的引用。
• 组件名称采用 kebab-case；属性也采用 kebab-case。
• mountLo20(frontdoorUrl, orgUrl) 接受两个参数。
• customElements.whenDefined(...) 使用字面字符串。
• 所有初始化都封装在 boot() 中，且 boot() 只调用一次。
• OAuth PKCE 流程替代了硬编码令牌；postMessage、BroadcastChannel 和 storage 监听器均已实现，并带有防御性编码。
• 组件标签没有内联 display:none。

故障排除

• LO 2.0 挂载卡住 — 自定义元素尚未注册。请检查库脚本标签 URL，以及 app-id / frontdoor-url 的值是否正确。
• 组件渲染为空 — 属性可能仍采用 camelCase。LO 2.0 会读取 HTML 属性，这些属性必须采用 kebab-case。
• OAuth 回调始终未触发 — postMessage / BroadcastChannel / storage 监听器中有一项被移除。LO 2.0 需要全部三项。
• Aura 检查清单中的 UTAM 或 Jest 评分为“缺失” — 如果团队有替代测试策略，这可能可以接受；应在建议中指出，而不是将其列为阻塞项。