目的: 基于产品回复，明确各模块设计改动点，供团队内部对齐
关联文档: PRD | System Design | 流程图
一、用户分批策略（产品已明确，重大变更）
原设计范围为 19.8K（Top-up）+ 50K（Quantix），产品回复扩展为全量用户分批：
| 批次 | 用户群 | 优先级 | 数量 | 方式 | 策略 |
|---|
| — | 新 KYC 用户 | P0 | ~5,000/天 | 自动 | KYC 通过后直接分配 Zand IBAN，无需迁移 |
| Batch 1 | 存量活跃 IBAN 用户 | P0 | 19.9K | 自动（批量） | 批量触发 Zand IBAN 创建 |
| Batch 2 | 存量非活跃 IBAN、但有钱包交易的用户 | P1 | TBC (@Qian.Wang 查数据) | 自动（批量） | 同 Batch 1 流程 |
| Batch 3 | 存量无 IBAN、但活跃钱包用户 | P2 | TBC (@Qian.Wang 查数据) | 用户手动触发 | 用户在 mini-program 中主动申请 |
| — | 非活跃用户（9个月无 FundIn/FundOut） | 不处理 | TBC (@Qian.Wang 查数据) | — | 不做任何操作 |
活跃度定义（Glossary）
| 术语 | 定义 |
|---|
| Active IBAN | 近6个月 ≥ 1 笔成功交易 |
| Non-Active IBAN | 持有 FAB IBAN 且近6个月 < 1 笔成功交易 |
| Non-active wallet user | 近9个月 0 笔交易（含 FundIn + FundOut） |
| Automatic | KYC 后自动分配 IBAN / 存量用户批量触发 Zand IBAN |
| Manual | 等待用户手动触发后再调用 Zand IBAN API |
对设计的影响
- VIS 侧：迁移任务模块需支持多批次调度（P0 → P1 → P2），需增加活跃度判断逻辑
- 数据侧：@Qian.Wang 需提供 Batch 2/3/非活跃用户的精确数量，评估 Zand Create VA API 的 TPS 压力
二、UI/UX 展示方案（产品已明确）
2.1 Phase 1：迁移期
| 场景 | 展示方式 | 说明 |
|---|
| 新用户（KYC 后） | Payment Settings 页面直接展示 Zand IBAN | 无需额外 UI |
| 存量用户（迁移后） | Payment Settings 页面更新 IBAN + In-app 通知 + ToDo Card → 点击跳转 mini-program | 新旧版本 App 统一走 mini-program |
| mini-program 内容 | 展示3项信息：a) 旧 IBAN 详情 b) 新 IBAN 详情 c) 迁移期限倒计时（"Your old IBAN will be deleted after 30 days on DD/MM/YYYY"） | 同时展示双 IBAN + 倒计时 |
2.2 Phase 2：迁移完成后
| 场景 | 展示方式 | 说明 |
|---|
| Add Funds 页面 | 新增入口 → mini-program | 推广工资入账（Salary Credit）功能 |
| Payment Settings | 仅展示 Zand IBAN | FAB IBAN 已下线 |
对各模块的改动
前端侧：
- Payment Settings 页面：适配新 Zand IBAN 数据结构展示
Checkout 页面：待确认是否 Phase 1 需要改动（产品回复中未提及，需再确认）- 不需要新开发原生 IBAN 页面
Mini-program 侧（新增）：
- 开发迁移详情页：双 IBAN 对比 + 倒计时
- Phase 2 增加 Salary Credit 推广入口
- 开发者待定（需产品确认）
VIS 侧：
- 对接 mini-program 数据接口（旧 IBAN / 新 IBAN / 迁移截止日）
- 不再需要对接原生 IBAN 展示页面
三、通知体系（产品已明确）
3.1 个人用户通知
| 维度 | 方案 |
|---|
| 通知渠道 | In-app Notification + ToDo Section |
| 触发时机 | 新 IBAN 分配成功后立即发送首次通知 |
| 重复逻辑 | 每10天发送一次，直到检测到 1 笔成功的新 IBAN wallet top-up |
| 通知内容 | 产品方提供（@Raj 负责文案 & UI） |
| CTA 行为 | 点击 → 打开 mini-program（新旧版本 App 统一） |
3.2 ToDo Card 配置
businessId: BUS-xxx
templateId: TPL-yyy
需联系 TIANBO ZHOU (TZ) 创建 ToDo Card 模板
3.3 商户通知
| 维度 | 方案 |
|---|
| 通知渠道 | Email（通过 BD） |
| 负责方 | Merchant Team / BD 自行决定具体策略 |
| 活跃商户数 | < 150 家 |
对设计的影响
通知侧：
- 新增定时触发任务：10天周期检查 + 发送通知
- 新增通知关闭条件：监听新 IBAN 首笔成功交易事件
- 对接 ToDo Card 模块
VIS 侧：
- 提供"新 IBAN 首笔交易成功"事件回调给通知模块
四、异常处理机制（产品已明确）
| 场景 | 处理方案 |
|---|
| Zand IBAN 创建失败 | 不提供手动激活按钮，系统自动维护失败标记 |
| 自动重试 | 3 次重试机制（需定义重试间隔，建议：1h / 6h / 24h） |
| 3次重试仍失败 | 升级至 Zand 团队排查根因并提供解决方案 |
对设计的影响
VIS 侧：
- 迁移任务模块新增重试调度器（3次上限 + 递增间隔）
- 新增失败标记字段（migration_status: FAILED）
- 新增告警机制：3次失败后触发告警，输出失败用户清单
- 运营后台：展示重试状态 & 失败用户列表
五、60天并行窗口策略（产品已明确）
| 维度 | 方案 |
|---|
| 前端展示 | 展示明确时间线给用户（制造紧迫感），如 "30 days remaining" |
| 后端逻辑 | 软切换，不硬切断：60天后 FAB 仍继续作为 fallback 接收入账 |
| FAB 入账处理 | 迁移窗口期内 FAB 收到的款项由 C&S 手动转至 Zand Escrow（每日操作） |
| 真正下线时间 | 待全部用户迁移完成后再关闭 FAB |
对设计的影响
- 后端路由规则：无需实现硬性60天截止逻辑，简化为"如有 Zand IBAN 则优先路由 Zand，否则走 FAB"
- mini-program 需展示倒计时 UI（前端纯展示，与后端逻辑解耦）
- C&S 操作流程需文档化
六、Lean 迁移（产品已明确）
| 维度 | 方案 |
|---|
| 状态 | Lean guaranteed payment solution 已 ready to go-live |
| 存量用户迁移 | 单独触发通知，推送用户使用新 Lean 方案 |
| 旧连接清理 | 用户连接新 destination 后，旧 destination 自动删除 |
| 参考文档 | Lean Migration Detail |
对设计的影响
- 需要和 Lean 迁移的通知流程协调排期，避免同时推送多个迁移通知造成用户困扰
七、商户 IBAN 迁移（无重大变更）
与原设计基本一致，仅补充：
- 活跃商户确认 < 150 家
- 通知策略由 Merchant Team / BD 自行决定
- 开发量维持 3-4 个工作日估算
八、各模块改动汇总
VIS 侧（@Qian.Wang）
| # | 改动项 | 优先级 | 说明 |
|---|
| 1 | 迁移标签开启后新用户自动开通 Zand IBAN | P0 | 原设计不变 |
| 2 | 迁移任务模块：支持多批次调度（P0/P1/P2） | P0 | 新增批次调度能力 |
| 3 | 活跃度判断逻辑 | P0 | 新增：按6个月/9个月交易记录分类 |
| 4 | 重试调度器（3次上限） | P0 | 新增：替代手动激活方案 |
| 5 | 失败标记 + 告警 | P0 | 新增 |
| 6 | 双 IBAN 路由规则（软切换） | P0 | 原设计简化，无需硬切断 |
| 7 | mini-program 数据接口 | P0 | 新增：提供旧IBAN/新IBAN/截止日数据 |
| 8 | 运营后台页面 | P1 | 原设计不变，增加重试状态展示 |
| 9 | 迁移监控埋点 | P1 | 原设计不变 |
前端侧
| # | 改动项 | 优先级 | 说明 |
|---|
| 1 | Payment Settings 页面适配新 IBAN | P0 | 原设计不变 |
| 2 | Checkout 页面展示新 IBAN | 待确认 | 产品回复未提及，可能 Phase 1 不需要 |
Mini-program 侧（新增模块）
| # | 改动项 | 优先级 | 说明 |
|---|
| 1 | 迁移详情页（双 IBAN + 倒计时） | P0 | 新增：Phase 1 核心页面 |
| 2 | Salary Credit 入口页 | P2 | 新增：Phase 2 |
通知侧
| # | 改动项 | 优先级 | 说明 |
|---|
| 1 | In-app 通知 + ToDo Card 对接 | P0 | 渠道明确：不需要 SMS/Push 备用通道 |
| 2 | 10天周期定时触发任务 | P0 | 新增 |
| 3 | 新 IBAN 首笔成功交易监听（关闭通知） | P0 | 新增 |
九、关键里程碑依赖
flowchart LR
subgraph 前置依赖
A1[产品提供 mini-program 设计稿]
A2[产品提供通知文案 & ToDo UI]
A3[确认 mini-program 开发者]
A4[Qian 提供 Batch 2/3 用户数]
A5[确认 Zand API TPS 限制]
end
subgraph 开发阶段
B1[VIS 多批次调度开发]
B2[重试调度器开发]
B3[mini-program 数据接口开发]
B4[通知定时任务开发]
B5[ToDo Card 模板创建]
B6[mini-program 前端开发]
end
C([联调 & 测试])
A1 --> B1
A1 --> B6
A2 --> B4
A3 --> B6
A4 --> B1
A5 --> B1
B1 --> C
B2 --> C
B3 --> C
B4 --> C
B5 --> C
B6 --> C
完整流程图详见 migration_flow_diagrams.md