用途：把 Capacitor 应用从 Ionic Enterprise SDK 插件迁移到 Capgo 开源插件，逐个替换并尽量保留登录会话与已存数据。背景是 Ionic 于 2025 年 2 月停止销售含 Enterprise SDK 的商业产品并逐步停止维护，需在许可或支持窗口结束前规划迁移。
触发条件：package.json 含 @ionic-enterprise/auth、@ionic-enterprise/identity-vault 或 @ionic-enterprise/secure-storage；代码导入 AuthConnect、ProviderOptions、Vault、BrowserVault、VaultType、DeviceSecurityType 或 Secure Storage 的 SQLite/KeyValueStorage；用户询问如何在不强制重新登录的情况下替换这些插件。不适用于 Appflow 实时更新/构建、社区或其他 SQLite 插件、生物识别 UX 或通用安全审查。
替换映射：Auth Connect 对应 @capgo/capacitor-social-login（provider: 'oauth2' 支持 OIDC/OAuth2，另有 google、apple、facebook 等），覆盖授权码 + PKCE、refreshToken 刷新、登出、原生 Apple/Google 登录，不覆盖令牌存储策略。Identity Vault 对应 @capgo/capacitor-native-biometric，可在 Keychain/Keystore 保存/读取/删除凭据，accessControl 用 BIOMETRY_CURRENT_SET 或 BIOMETRY_ANY，verifyIdentity 在 iOS 支持密码回退，含 biometryChange 监听；不覆盖不活动锁定超时、后台隐私屏、自定义密码库、内存库。Secure Storage（SQLite）对应 @capgo/capacitor-fast-sql 的 encrypted: true + encryptionKey，覆盖加密 SQLite（SQLCipher）、事务、批处理、KeyValueStore，不覆盖密钥管理。Secure Storage（键值）对应 @capgo/capacitor-data-storage-sqlite 或 Fast SQL KeyValueStore。非敏感设置可用 @capacitor/preferences，切勿存放令牌或密钥。
流程：先用 rg -n "@ionic-enterprise/" -g '!node_modules' . 检测并列出调用点与存储内容，多个插件时每个版本迁移一个。数据迁移采用两版本规则：版本 N 同时安装新旧插件，首次启动从旧存储读出写入新存储并设迁移标记，再清空旧存储；版本 N+1 移除企业插件。若接受全员强制重新登录，可单版本完成，但需明确确认。
Auth Connect 迁移：npm install @capgo/capacitor-social-login 后 npx cap sync，保持相同 client ID、scope 与重定向 URI，并在 IdP 注册新原生重定向。将各 provider 映射为 SocialLogin.initialize({ oauth2: { <providerId>: { ... } } }) 条目，替换 login/logout/refreshSession/isAccessTokenExpired 为 SocialLogin.login({ provider: 'oauth2', options: { providerId } })、logout、refreshToken 及自行过期检查。
Identity Vault 迁移：npm install @capgo/capacitor-native-biometric 后 npx cap sync，用 setCredentials/getSecureCredentials 存取，lockAfterBackgrounded 在 App 恢复时按超时显示锁屏并重新读取，iOS 需在 Info.plist 添加 NSFaceIDUsageDescription，后台隐私屏用 @capacitor/privacy-screen。
Secure Storage 迁移：npm install @capgo/capacitor-fast-sql 后 npx cap sync，用 FastSQL.connect({ database: 'app', encrypted: true, encryptionKey }) 与 KeyValueStore.open 打开，保持原 schema 并移植查询。加密需 SQLCipher：Android 在 android/app/build.gradle 加 net.zetetic:sqlcipher-android，iOS 用 CocoaPods 子规格 CapgoCapacitorFastSql/SQLCipher，否则报 Encryption is not available in this build。Fast SQL 运行本地 HTTP 服务，需 iOS 的 NSAllowsLocalNetworking 与 Android localhost 明文 network_security_config.xml。encryptionKey 应存于 Native Biometric 或服务端派生，禁止硬编码。
清理与验证：npm uninstall 三个企业包，rg 确认无残留，npx cap sync；确认无企业包后再从 .npmrc 移除注册表/令牌行。验证包括覆盖安装保持登录与数据、真机测试登录/刷新/登出/生物识别、更改生物识别后 BIOMETRY_CURRENT_SET 项不可读并回退登录、CI 无企业凭据下 npm ci 成功。常见错误：CI 401/404 为令牌过期；更新后登出为未做数据迁移；redirect_uri_mismatch 需注册新重定向并保持 scope 一致；网络错误需补 ATS/明文配置；生物识别变更后读取失败属预期，需重新认证并保存。