Integration Team 入职指南

本文为新加入 Integration Team 的成员提供结构化学习路径。请按顺序完成各阶段，并使用每阶段的问题进行自测。

前置条件

开始学习 Integration 专题前，请先完成：

1. 完成 RightCapital 通用入职流程。
2. 配置本地开发环境。
3. 获取相关 GitLab repository 的访问权限。
4. 获取 Admin Center（QA environment）的访问权限。

学习路径

阶段一：基础知识

目标：理解 Integration Team 的职责及其业务价值。

任务	资料
阅读 Integration 概览	Overview
理解架构	Architecture
观看 Integration 视频	Notion：Integration Videos

自测问题：

• Integration 对 advisor 的业务价值是什么？
• Integration 的主要类型有哪些（Data、SSO、CRM）？
• File-based 和 API-based integration 有什么区别？

阶段二：Collector

目标：理解文件型数据如何进入系统。

Task	Resource
阅读 Collector 文档	Collector
阅读 Collector 代码	GitLab：Collector

自测问题：

• Collector 的作用是什么？
• Collector 如何与 Vendor 通信（例如 SFTP）？
• Collector 的四个文件处理阶段（Downloader、Processor、Uploader、Finalize）分别是什么？
• 哪些输出供 ELT 使用，哪些输出供 legacy parser 使用？
• 为什么不能仅凭 S3 上存在 LATEST 判断 Retail API 是否已完成 ELT cutover？

阶段三：API-based Integration

目标：理解 API integration 的工作方式。

Task	Resource
阅读 API integrations 文档	API Integrations
阅读 Integrations 代码	GitLab：app/Integrations

自测问题：

• 如何与 Vendor 建立连接（OAuth、API key 等）？
• Connector/Integrator/Request 架构是什么？
• API integration 如何获取 Vendor 数据？
• 通常获取哪些数据（households、accounts、positions）？
• Vendor 数据如何关联到 RightCapital households？
• IntegrationConfigController 做什么？
• IntegrationImportController 做什么？

阶段四：File-based Integration

目标：理解文件型 integration 的工作方式，包括 ELT 和 legacy 两条路径。

Task	Resource
阅读 File integrations 文档	File Integrations
Explore integrations-file-based lib	GitLab: integrations-file-based

自测问题：

• Vendor 数据从哪里来（Collector 写入 S3）？
• 文件中通常有哪些数据（accounts、positions、securities）？
• 文件数据如何关联到 RightCapital households？

阶段五：Sync 流程

目标：理解 Nightly Sync 机制。

Task	Resource
阅读 Nightly Sync 文档	Nightly Sync

自测问题：

• 用一句话说明 Sync 是什么？
• 哪些数据会被同步？
• Holding 是什么？
• Holdings 如何同步？
• Holdings 有哪些类型？

阶段六：数据库 Schema

目标：理解数据模型。

重点学习的表：

Table	Purpose
integrations	Advisor’s connection to a Vendor
integration_mappings	Links between Vendor entities and RC entities

Self-check questions:

• What does a row in integrations represent?
• What is the reference field in integrations?
• What is the difference between credentials and reference?
• What does integration_mappings represent?
• What is the reference field in integration_mappings?
• What does parent_id being null vs non-null mean?
• What are the different mappable_type values and their meanings?

阶段七：SSO

目标：理解 Single Sign-On integration。

Task	Resource
阅读 SSO 文档	SSO
Explore SSO controllers	GitLab: app/Http/Controllers/Sso

Self-check questions:

• What is a Service Provider (SP)?
• What is an Identity Provider (IdP)?
• What is IdP-initiated SSO flow?
• What is SP-initiated SSO flow?
• How is a SAML Response validated?
• What fields are validated in a SAML Response?

动手练习

完成阅读后，尝试以下练习：

1. Trace a File-based sync: 先判断 vendor 是 ELT 还是 legacy，再沿 raw S3 → normalized S3 → Snowflake → Retail API 或 legacy S3 → Retail API parser → Database 链路追踪
2. Trace an API-based sync: Follow an OAuth flow → API call → Database save
3. Debug a Data Issue: Use Admin Center to view integration logs
4. Read Vendor files: Download a file from S3 and understand its structure

获取帮助

• Slack: #integration-team channel
• Documentation: This knowledge base + Notion
• Pair programming: Shadow a team member on a real task

来源

• Notion: Integration Team Onboarding