forgerock-to-ping-journey-migration

ForgeRock → Ping Journey SDK 迁移

帮助开发者将现有应用从旧版 ForgeRock SDK 迁移到新版 Ping Identity Journey SDK。此技能将推动一次谨慎且可审计的迁移：扫描代码库、预览计划、注释掉旧代码并替换（绝不悄悄删除）、验证构建，并留下可供开发者交给审阅者的报告。

支持的平台

平台	旧版包	新版包	参考资料
Android（Kotlin）	org.forgerock:forgerock-auth (FRAuth/FRSession)	com.pingidentity.sdks:journey	android-migration.md
iOS（Swift）	ForgeRock/forgerock-ios-sdk (FRAuth/FRUser)	ForgeRock/ping-ios-sdk (PingJourney/PingOidc)	ios-migration.md
JavaScript/TypeScript	@forgerock/javascript-sdk	@forgerock/journey-client + @forgerock/oidc-client	javascript-migration.md

每个参考文件都提供完整的新旧映射（导入项、类、方法、参数变更）。只加载与检测到的平台匹配的文件，不要预先读取全部三个文件。

触发时机

只要用户表示想将 ForgeRock 身份验证代码迁移到 Ping SDK，即触发此技能，即使用户没有使用“迁移”一词也是如此。触发示例：“我们需要弃用 FRAuth”、“把它转换为 journey-client”、“升级我们的 ForgeRock 集成需要做什么”、“用新 SDK 替换 FRSession.authenticate”。如有疑问，就主动提出——此处稍微积极一些是正确的，因为用户的磁盘上已经有旧版代码，ForgeRock 停止服务后这些代码将无法运行。

---

核心原则

开始前请阅读以下内容。它们将指导下面的每项判断。

1. 绝不悄悄删除旧版代码。 使用易于识别的标记将其注释掉，以便开发者通过 grep、diff 进行查找和对比，并能一步回滚。该标记也能让代码审查者清楚地看出变更内容。
2. 始终确保构建正常。 如果迁移前构建已损坏，请先停止迁移并帮助修复——否则无法判断迁移后的失败是否由此技能导致。
3. 遇到歧义时暂停。 新旧 SDK 在架构上有所不同（回调 → 协程/async-await、静态配置 → 工厂函数、抛出异常 → Result 类型）。如果某项转换需要做出会改变行为的判断，请留下 TODO(ping-migration): 并在继续前询问开发者。
4. 编辑前先预览。 在改动任何内容前，按文件分组，向开发者展示打算修改的完整位置列表。重新生成计划成本很低；撤销错误的大范围修改则代价高昂。
5. 在报告中说明。 最终产物是开发者将会阅读的报告。应将其视为首要输出，而不是事后补充。

---

工作流

按顺序执行以下阶段。不得悄悄跳过任何阶段——如果开发者希望跳过某个阶段，必须明确说明。

阶段 1 — 检测平台

识别目标项目使用的平台。请查找：

• Android：build.gradle、build.gradle.kts、settings.gradle*、gradle.properties、app/src/main/AndroidManifest.xml
• iOS：Package.swift、*.xcodeproj、*.xcworkspace、Podfile、Podfile.lock
• JavaScript/TypeScript：package.json（检查 dependencies 中是否有 @forgerock/javascript-sdk 或 @forgerock/ping-protect）

单体仓库可能包含多个平台。如果是这样，请在继续前与开发者确认本次会话要迁移哪些目标。

阶段 2 — 收集上下文

阅读项目根目录中的 AGENTS.md 和 CLAUDE.md（以及与平台相关的任何子项目根目录中的这两个文件）。这些文件通常包含入口点信息、身份验证模块的位置、自定义构建命令和推荐的约定——这些对安全迁移都至关重要。

如果这两个文件都不存在，请使用 agents-template.md 作为起点，提出创建 AGENTS.md。根据你能观察到的信息填写内容：项目结构、主要语言、构建命令、现有身份验证代码的位置。保存前请开发者确认或更正。这个文件不仅有助于本次迁移，也有助于未来的工作，因此稍作绕行是值得的。

如果开发者拒绝，则在没有该文件的情况下继续，但要在最终报告中注明。

阶段 3 — 构建前检查

更改任何内容之前，确认应用当前状态下可以构建。询问开发者：

“要我现在运行构建来确认基线正常吗？还是你已经知道它可以构建？”

如果对方同意或不确定，请运行适当的命令（见下文的构建命令）。如果构建失败，请在此处停止。先帮助修复已有的问题——不能在基线已损坏的情况下安全迁移。构建成功后再继续。

如果开发者说“尽管相信我，构建没问题”，则接受并继续，但要在报告中记录这一点，让他们知道自己选择跳过了基线检查。

阶段 4 — 确定迁移范围

询问开发者：

“你希望我扫描整个项目，还是只迁移特定区域（例如单个文件、功能模块或登录流程）？”

遵循部分范围的要求。部分范围很常见，也合理——团队可能希望按模块逐步迁移。如果范围有限，请在扫描前确认确切的文件或目录集合。

阶段 5 — 扫描旧版用法

使用 Grep 和 Read，在选定范围内整理旧版 SDK 用法清单。参考文件列出了应搜索的所有旧版符号。重点搜索以下内容：

• Android：FRSession、FRUser、FRAuth、NodeListener、FROptions、FRDeviceCollector、import org.forgerock.android、WebAuthRegistrationCallback、DeviceBindingCallback、FRListener、PingOneProtect*
• iOS：FRAuth、FRSession、FRUser、FROptions、import FRAuth、import FRCore、WebAuthnRegistrationCallback、WebAuthnAuthenticationCallback、SelectIdPCallback、FRGoogleSignIn、FRFacebookSignIn、FRCaptchaEnterprise、Node.next { ... } 完成处理程序风格
• JavaScript：@forgerock/javascript-sdk、Config.set、FRAuth.start、FRAuth.next、FRUser.logout、UserManager.getCurrentUser、TokenManager.getTokens、TokenStorage、FRWebAuthn、CallbackType、FRCallback、FRStep、@forgerock/ping-protect

另外还要整理以下内容：

• 依赖文件 — build.gradle*、Package.swift、Podfile、package.json — 用于确定需要更新哪些声明。
• 清单/配置文件 — 例如 AndroidManifest.xml 中的重定向 URI、iOS Info.plist 中的 URL scheme、JS index.html — 以检查新 SDK 是否需要不同的条目。
• 测试文件 — 它们通常会重复身份验证设置代码，必须同步迁移。

阶段 6 — 预览计划

在编辑之前向开发者展示调查结果。结构如下：

## Migration plan (preview)

Platform(s): Android
Scope: app/src/main/java/com/example/auth/**

Dependency changes (1 file):
  - app/build.gradle.kts — remove org.forgerock:forgerock-auth, add com.pingidentity.sdks:journey

Code changes (4 files, 12 sites):
  - app/src/main/java/com/example/auth/AuthManager.kt — 5 sites
      line 23: FROptionsBuilder.build { ... } → Journey { ... }
      line 41: FRSession.authenticate → journey.start
      line 56: NodeListener<FRSession> → Node sealed-class handling
      line 78: NameCallback setter → property assignment
      line 102: FRUser.getCurrentUser()?.logout() → journey.user()?.logout()
  - app/src/main/java/com/example/auth/LoginViewModel.kt — 4 sites
      ...

Manual review items (2):
  - app/src/main/java/com/example/auth/DeviceHelper.kt:87 — uses custom FRDeviceCollector
    composition; the new API uses DefaultDeviceCollector. I'll add a TODO but
    want your input on whether the custom collectors are still needed.
  - app/src/main/AndroidManifest.xml:34 — redirect URI scheme matches legacy
    sample; confirm it still applies to your new OIDC client.

Proceed? (y / partial / no)

允许开发者编辑计划——他们可能想跳过某个文件、推迟某项工作或调整范围。获得批准前，不要开始阶段 7。

阶段 7 — 应用更改

对于每个站点，注释掉旧代码，并在其正下方插入新代码。请使用以下标记约定，以便一次 grep 就能定位所有更改：

Android / iOS（Kotlin/Swift 行注释）：

// [ping-migration] BEGIN legacy — safe to delete after verifying the migration
// FRSession.authenticate(context, "Login", nodeListener)
// [ping-migration] END legacy
val node: Node = journey.start("Login")

JavaScript/TypeScript（行注释）：

// [ping-migration] BEGIN legacy — safe to delete after verifying the migration
// const step = await FRAuth.start();
// [ping-migration] END legacy
const result = await journeyClient.start({ journey: 'Login' });

为什么要在两侧都使用开始/结束标记？在差异中，单行注释很容易被忽略；成对的标记能明确划定边界，方便开发者之后通过一次多行选择移除代码块。

依赖文件。 编辑前，先检查是否已声明新依赖（开发者可能已经开始迁移）。如果已声明，则跳过该条目并在报告中注明。修改时，使用相同的标记约定注释掉旧行，并在下方添加新的声明。对于不支持注释的 package.json，直接更新 dependencies，但要在报告的“依赖项”部分同时列出已移除和新增的包。

存在歧义的转换。 当映射需要判断时——例如，需要将基于回调的旧流程改为位于文件其他位置的协程/async 块，或涉及 NodeListener.onException 拆分为 ErrorNode/FailureNode 等行为变更——不要猜测。插入一条 TODO(ping-migration): 注释说明歧义，并在聊天中向开发者确认，然后再进行更改：

// TODO(ping-migration): onException previously handled both API errors and
// unexpected exceptions. The new SDK splits these into ErrorNode (API errors,
// has .message) and FailureNode (exceptions, has .cause). Do you want to
// preserve a single error path, or branch on node type for different UX?

一次处理一个文件，以便隔离故障并保持报告内容连贯。

阶段 8 — 构建后检查

询问开发者：

“准备好运行构建进行验证了吗？（这可能需要几分钟。）”

如果同意，则运行相应的构建命令。如果构建通过，继续阶段 9。

如果构建失败：

1. 显示错误。
2. 进行诊断——是转换错误、缺少依赖项、遗漏了清单/plist 更改，还是无关的既有问题？
3. 逐步修复并重新构建，直到构建通过。
4. 构建失败时，绝不要宣称迁移已完成。 如果无法让构建通过（例如，需要云凭据，或存在必须由开发者解决的实际运行时问题），请明确说明——不要用 ✅ 结束任务。

如果开发者拒绝运行构建，则在报告顶部添加醒目的提示：⚠️ Build verification was skipped — migration is not yet confirmed to compile.

阶段 9 — 编写迁移报告

在项目根目录（或部分迁移时，在已迁移子项目的根目录）编写 MIGRATION_REPORT.md。使用 report-template.md 作为结构模板。报告必须包含：

1. 摘要 — 已迁移的平台、范围、日期、构建状态。
2. 依赖项变更 — 已添加、移除或以注释形式保留的包。
3. 逐文件变更 — 路径、行号（旧代码 → 新代码）、每项变更的简要说明。
4. 手动审查项 — 所有遗留的 TODO(ping-migration):，并附上文件:行号指引。
5. 跳过的项目 — 开发者选择不迁移的内容。
6. 回滚说明 — 用于查找所有标记的 grep 命令，以及移除步骤。
7. 后续步骤 — 开发者验证行为后，运行 grep -R "\[ping-migration\] BEGIN legacy" 并移除已注释的代码块。

报告应能独立阅读——未参与本次交流的审阅者也应能理解更改内容及原因。

---

构建命令

使用项目的标准构建命令。如果 AGENTS.md 指定了命令，请优先使用。否则：

平台	命令（根据项目布局调整）
Android	./gradlew assembleDebug（或 ./gradlew :app:assembleDebug）
iOS（SPM）	xcodebuild -scheme <scheme> -destination 'generic/platform=iOS Simulator' build
iOS（CocoaPods）	pod install，然后运行 xcodebuild -workspace <name>.xcworkspace -scheme <scheme> build
JavaScript	根据 package.json 检测——根据锁文件使用 npm run build、pnpm build 或 yarn build

如果项目采用不同做法，请务必向开发者确认准确的命令。对于 iOS，每个项目的 scheme 和 destination 都可能不同；首次构建前请先询问。

---

始终需要人工处理的事项

这些转换无法安全地自动完成。请务必在报告中标出：

• 错误处理形式变更。 旧版 SDK 会抛出异常；新版 SDK 会返回 Result/密封类型。开发者通常需要重新考虑这些边界处的用户体验（重试？静默失败？登出？）。
• 令牌存储。 如果旧版应用将令牌写入自定义存储，新 SDK 的默认存储行为可能不同。请确认存储方案。
• 重定向 URI。 新的 OIDC 客户端可能需要不同的 URI scheme。请对照新的 OIDC 客户端配置，检查 manifest/plist 条目。
• 测试固件。 Mock FRListener 实现和伪造的 FRStep 对象无法直接转换——需要根据新的类型系统重写。
• 社交 / IdP 处理程序。 旧版 FRGoogleSignIn、FRFacebookSignIn 等已由独立的 PingExternalIdP* 模块取代；应用级配置（Google Client ID、Facebook App ID）可能需要在 Ping 中重新设置。
• 设备绑定和 FIDO。 类名和流程已变更（WebAuthRegistrationCallback → FidoRegistrationCallback；DeviceBindingCallback.bind(...) 的签名不同）。应用前务必向开发者展示差异。

---

不要做的事

• 即使开发者很赶，也不要在没有预览的情况下运行迁移。预览就是约定。
• 不要直接删除旧版代码。采用注释并替换的模式，以便回滚。
• 不要擅自选择构建命令。请与开发者确认，尤其是 scheme/destination 因项目而异的 iOS 项目。
• 如果跳过了任何阶段或构建失败，就不要宣称迁移成功。请在报告中直白说明。
• 不要在迁移过程中生成 shell 或特定语言的脚本——开发者可能没有 Node、Python 或 Ruby。请直接使用文件工具修改，并且仅调用项目原生构建工具。

---

参考文件

• android-migration.md — Android（Kotlin）完整旧版→新版映射。
• ios-migration.md — iOS（Swift）完整旧版→新版映射。
• javascript-migration.md — JavaScript/TypeScript 完整旧版→新版映射。
• agents-template.md — 项目缺少 AGENTS.md 时用于生成该文件的模板。
• report-template.md — 最终 MIGRATION_REPORT.md 的结构。

仅加载与检测到的平台相关的参考文件。迁移映射很长——不要预先加载所有文件。