Twenty CRM OAuth Mastery 是一个为 Twenty CRM 系统提供深度 OAuth 2.0 认证支持的专业技能包，专注于 Google 和 Microsoft 第三方登录集成、令牌管理及自动化同步功能。该工具集涵盖从身份验证架构设计到实际部署运维的全流程知识体系，尤其擅长解决生产环境中常见的重定向循环、域名限制冲突和自动同步失效等复杂问题。通过系统化的代码模式指导与故障排查框架，帮助开发者快速定位并修复 OAuth 相关的技术障碍，确保用户能够顺畅完成登录并建立 Gmail 与日历服务的无缝连接。其核心优势在于结合 NestJS 框架特性，提供经过实战检验的 Passport 策略实现方式，同时强调环境配置、编译部署与前后端协同调试的关键细节。
核心功能特点
- 支持 Google 与 Microsoft OAuth 2.0 协议的专业级实现与故障排查
- 提供自动 Gmail 邮件与 Google Calendar 同步集成机制
- 包含完整的令牌刷新管理逻辑及错误处理策略
- 内置域名白名单配置方案，避免 .co 等二级域名被误拦截
- 覆盖前端 Cookie 读取与后端服务联调的全链路调试指南
- 配备单元测试与 Playwright 集成测试模板，保障稳定性
适用场景
Twenty CRM OAuth Mastery 主要面向需要在企业内部部署或维护 Twenty CRM 系统的开发团队和技术负责人。典型使用场景包括：当企业引入 Google Workspace 或 Microsoft 365 作为统一身份源时，需快速搭建安全的 OAuth 登录入口；在遇到用户登录后卡在欢迎页无法跳转至主界面（即‘重定向循环’）这类高频问题时，可通过本技能包中的排查清单精准定位是未重新构建后端容器还是 Cookie 设置不当所致；若希望用户在首次登录时自动建立 Gmail 收件箱与日历的事件同步通道，则必须遵循 validate() 方法中保留 access/refresh token 的关键规范。此外，对于拥有混合域名结构（如 company.com 与 company.co 并存）的组织而言，该工具提供了多维度域名管控策略——不仅涉及前端表单防重复提交机制，还包括数据库层 workspaceMetadata 表中的 approvedAccessDomains 字段更新。无论是新接入 OAuth 提供商、修复现有登录中断故障，还是优化用户体验以支持跨平台协作办公，此技能包均能提供结构化解决方案与最佳实践参考。