DEV-19566: Bank of America Open Banking API Migration

Ticket Overview

Field	Value
Key	DEV-19566
Summary	Upcoming Change: Bank of America Open Banking API Migration
Status	In Progress
Priority	Medium
Assignee	Heli Yin
Created by	Yan Hu
Created	2026-03-05

Background

Yodlee 通知 Bank of America (BOA) 将升级其 Open Banking API 至新版本，导致所有连接的认证方式发生变化。迁移暂定 2026 年 4 月底开始，6 月底结束。

核心变化：

1. 所有用户必须一次性重新认证 BOA 连接
2. BOA 的 Provider ID 将变更（Yodlee 侧的机构标识符更换为新 ID）
3. providerAccountId 和 accountId 保持不变（Yodlee 已确认，重新认证后连接 ID 和账户 ID 不变）

Product Lead (Megan) 要求工程团队评估 Yodlee 邮件中高亮的两个关注点：

• Sync Data Extracts API：如果应用通过 sync API 消费 Yodlee 数据，需验证应用能正确更新新的 provider 和 providerAccountId
• FastLink Deep Link Flow：如果应用使用 FastLink Deep Link flow，需将现有 provider ID 替换为新 provider ID

Investigation

1. Sync Data Extracts API — 不适用

RightCapital 不使用 Yodlee 的 Data Extracts API，使用的是标准 REST API：

API Endpoint	用途	代码位置
GET /providerAccounts	拉取所有 provider accounts	Api::getProviderAccounts()
GET /providerAccounts/{id}	获取单个 provider account	Api::getProviderAccount()
GET /accounts?providerAccountId={id}	获取账户详情	Api::getAccounts()
PUT /providerAccounts?providerAccountIds={id}	触发刷新	Api::startProviderAccountRefresh()

代码位置：retail-api/app/Integrations/Yodlee/Api.php

Provider ID 处理方式：Integrator::saveProviderAccount() 从 API response 中动态读取 providerId 和 id（providerAccountId），没有任何硬编码的 BOA provider ID。

retail-api/app/Integrations/Yodlee/Integrator.php

$provider_account_reference = $provider_account_array['id'];           // providerAccountId
$yodlee_provider_reference  = $provider_account_array['providerId'];   // providerId

使用 firstOrNew() 模式创建/更新记录，新的 ID 会自动创建新记录。

结论：不需要工程改动。

2. FastLink Deep Link Flow — 不适用

RightCapital 不使用 FastLink Deep Link Flow。Deep Link Flow 是指在初始化 FastLink 时传入 providerId 以跳过银行搜索，直接进入特定银行的登录页。

我们的 FastLink 配置接口：

frontend/app/src/.../yodlee-fast-link/yodlee-fast-link.ts

export interface IFastLinkConfig {
  params?: Partial<{
    userExperienceFlow: IUserExperienceFlow;
    providerAccountId?: number;  // 仅用于 Edit/Refresh，不是 providerId
    flow?: IFastLinkFlow;
  }>;
}

三种使用模式：

Mode	用途	是否传 providerId
Add	新增账户连接	否，用户在 FastLink 中搜索银行
Edit	更新凭证	否，传 providerAccountId（连接 ID，非机构 ID）
Refresh	手动刷新	否，传 providerAccountId

注意区分：providerAccountId（用户与银行之间的连接 ID）和 providerId（银行机构 ID）是不同概念。Deep Link Flow 需要传 providerId，我们没有使用。

前端还有一个 openFastLinkModal URL 参数：

const [{ openFastLinkModal: shouldOpenFastLinkModal = false }] = useSearch({
  openFastLinkModal: 'boolean',
});

这是应用内部的 URL 快捷方式（如 /profile/net-worth?openFastLinkModal=true），用于自动打开 FastLink 弹窗，与 Yodlee 的 Deep Link Flow 无关。

结论：不需要工程改动。

3. 迁移对现有数据的影响

Yodlee 确认的 ID 变化

Yodlee 已确认重新认证后各 ID 的变化情况：

ID 类型	是否变化	说明
providerId（银行机构 ID）	会变	旧 Provider ID → 新 Provider ID
providerAccountId（用户连接 ID）	不变	重新认证后保持原值
accountId（具体账户 ID）	不变	重新认证后保持原值

数据模型映射

Yodlee 概念	数据库表	主键字段
Provider ID（银行机构）	yodlee_providers	reference
Provider Account ID（用户连接）	yodlee_provider_accounts	reference
Account ID（具体账户）	account_yodlees	yodlee_account_reference

迁移后的数据流

由于 providerAccountId 和 accountId 不变，数据变化非常小：

迁移前：
  yodlee_providers(reference=旧ID, name="Bank of America")
    └── yodlee_provider_accounts(reference=PA_ID, yodlee_provider_reference=旧ID)
          └── account_yodlees(yodlee_account_reference=ACC_ID) → accounts

迁移后 + 用户重新认证：
  yodlee_providers(reference=新ID, name="Bank of America")  ← 新记录（自动创建）
    └── yodlee_provider_accounts(reference=PA_ID, yodlee_provider_reference=新ID)  ← 同一记录，外键更新
          └── account_yodlees(yodlee_account_reference=ACC_ID) → accounts  ← 完全不变

  yodlee_providers(reference=旧ID)  ← 孤儿记录（无害，仅占少量空间）

关键结论：

• 不会产生重复账户 — providerAccountId 不变，yodlee_provider_accounts 命中现有记录并更新外键
• 账户数据完整保留 — accountId 不变，account_yodlees 和 accounts 记录完全不受影响
• 账户历史数据连续 — 余额历史等不中断
• Advisor 无需手动删除旧账户 — 不存在旧账户/新账户并存的情况

YodleeProviderAccountController@index 行为

index 方法完全以 Yodlee API 返回为准，不查本地数据库：

retail-api/app/Http/Controllers/.../YodleeProviderAccountController.php

$provider_account_arrays = $yodlee_api->getProviderAccounts();  // 从 Yodlee API 拉取
foreach ($provider_account_arrays as $provider_account) {       // 只遍历 API 返回的
    $yodlee_provider_account = Integrator::saveProviderAccount($provider_account);
    $provider_accounts->add($yodlee_provider_account);
}
return response()->json(YodleeProviderAccountResource::collection($provider_accounts));

迁移后用户重新认证时：

• Yodlee API 返回相同的 providerAccountId，但 providerId 为新值
• saveProviderAccount() 通过 firstOrNew() 命中现有 yodlee_provider_accounts 记录
• yodlee_provider_reference 外键更新为新的 Provider ID
• 新的 yodlee_providers 记录自动创建（如不存在）
• 账户数据无缝衔接，前端无感知

Conclusion

项目	结论
Sync Data Extracts API	不适用，无需改动
FastLink Deep Link Flow	不适用，无需改动
工程改动	零
用户影响	BOA 连接需一次性重新认证
Advisor 操作	无需额外操作（账户数据无缝衔接）
数据连续性	providerAccountId 和 accountId 不变，账户历史完整保留
待确认项	等待 Yodlee 提供新 Provider ID 和具体时间表

Action Items

1. 回复 Megan：两个高亮关注点均不适用，不需要额外工程步骤
2. Mary 继续推进：通知 advisor 告知客户需要一次性重新认证 BOA 连接（重新认证后账户自动恢复，无需删除旧账户）
3. 后续跟进：Yodlee 分享新 Provider ID 和迁移时间表后，评估是否需要额外准备

Related

• Yodlee Vendor Documentation
• Data Models
• DEV-3438: Yodlee Soft-Refresh Async