# https://github.com/twentyhq/twenty 项目说明书

生成时间：2026-05-18 21:19:12 UTC

## 目录

- [项目介绍](#page-introduction)
- [技术栈概览](#page-tech-stack)
- [Monorepo结构](#page-monorepo-structure)
- [前端架构](#page-frontend-architecture)
- [UI组件库](#page-ui-components)
- [后端架构](#page-server-architecture)
- [数据模型](#page-database-models)
- [Activities活动模块](#page-activities-module)
- [Views与Pipelines](#page-views-pipelines)
- [Apps扩展系统](#page-apps-system)
- [GitHub Connector示例](#page-github-connector)
- [Docker部署](#page-docker-deployment)

<a id='page-introduction'></a>

## 项目介绍

### 相关页面

相关主题：[技术栈概览](#page-tech-stack), [Monorepo结构](#page-monorepo-structure)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/twentyhq/twenty/blob/main/README.md)
- [packages/twenty-website-new/src/app/[locale]/(home)/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/(home)/page.tsx)
- [packages/create-twenty-app/README.md](https://github.com/twentyhq/twenty/blob/main/packages/create-twenty-app/README.md)
- [packages/twenty-front/src/modules/ai/components/LazyMarkdownRenderer.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/ai/components/LazyMarkdownRenderer.tsx)
- [packages/twenty-ui/src/layout/modal/components/__stories__/Modal.stories.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-ui/src/layout/modal/components/__stories__/Modal.stories.tsx)
</details>

# 项目介绍

## 项目概述

Twenty 是一个开源的客户关系管理系统（CRM），致力于为技术团队提供构建企业级 CRM 的模块化解决方案。该项目采用现代技术栈构建，具有 AI 就绪特性，支持企业快速定制和部署属于自己的 CRM 系统。

Twenty 的核心价值主张在于：**构建您的竞争对手无法购买的 CRM**。作为一个开源项目，Twenty 赋予企业对系统的完全控制权，同时保持灵活性以适应不断变化的业务需求。

资料来源：[packages/twenty-website-new/src/app/[locale]/(home)/page.tsx:8-12]()

## 核心特性

### 开源与可扩展性

Twenty 采用开源模式，允许企业自由部署、自托管和深度定制系统。项目采用模块化架构设计，使技术团队能够根据复杂业务需求构建定制化 CRM，同时在业务发展过程中快速适应变化。

资料来源：[packages/twenty-website-new/src/app/[locale]/why-twenty/page.tsx:5-15]()

### AI 集成能力

Twenty 被设计为 AI 就绪（AI-ready）系统。传统的 CRM 系统往往只是数据存储库，而 Twenty 正在演变为运营系统（Operating System）。AI 代理可以开始起草外展内容、评分潜在客户、研究客户账户、撰写跟进内容以及更新交易阶段。这些操作都会从 CRM 读取数据并写入 CRM。

资料来源：[packages/twenty-website-new/src/app/[locale]/why-twenty/page.tsx:30-45]()

### 无代码定制

系统提供无代码配置能力，允许用户在不依赖工程团队的情况下快速修改工作空间。自定义字段、工作流、视图和业务逻辑都可以通过可视化界面完成配置。

资料来源：[packages/twenty-website-new/src/app/[locale]/product/page.tsx:45-52]()

## 项目架构

Twenty 项目采用 monorepo 结构，主要包含以下核心包：

| 包名 | 说明 | 技术栈 |
|------|------|--------|
| `packages/twenty-front` | 前端应用 | React, TypeScript |
| `packages/twenty-ui` | UI 组件库 | React, Storybook |
| `packages/twenty-website-new` | 官网与文档 | Next.js |
| `packages/create-twenty-app` | CLI 脚手架工具 | Node.js |

### 架构图

```mermaid
graph TB
    subgraph 前端层
        A[packages/twenty-front<br/>前端应用]
        B[packages/twenty-website-new<br/>官网]
    end
    
    subgraph UI 层
        C[packages/twenty-ui<br/>UI 组件库]
    end
    
    subgraph 工具层
        D[packages/create-twenty-app<br/>CLI 工具]
        E[twenty-sdk]
    end
    
    A --> C
    B --> C
    D --> E
    
    style A fill:#e1f5fe
    style C fill:#fff3e0
    style D fill:#f3e5f5
```

## 包结构详解

### twenty-front

`packages/twenty-front` 是 Twenty 的核心前端应用，包含 CRM 的主要功能模块。该包使用 React 18 和 TypeScript 构建，采用组件化架构设计。

核心模块包括：

- **AI 模块** (`src/modules/ai`)：包含 `LazyMarkdownRenderer` 等组件，用于处理 AI 生成内容的渲染和展示
- **UI 组件系统**：基于 `packages/twenty-ui` 构建的完整组件生态
- **状态管理**：使用 React Context 和自定义 Hook 进行状态管理

资料来源：[packages/twenty-front/src/modules/ai/components/LazyMarkdownRenderer.tsx:1-30]()

### twenty-ui

`packages/twenty-ui` 是 Twenty 的共享 UI 组件库，提供了构建 CRM 界面所需的基础组件。该库使用 Storybook 进行文档化和测试。

主要组件包括：

- **Modal 组件**：支持多种配置选项（`size`、`padding`、`overlay`）
- **Button 组件**：支持多种变体（`primary`、`secondary`、`outlined`）和强调色
- **表单组件**：输入框、下拉选择器等
- **布局组件**：Container、Section 等

资料来源：[packages/twenty-ui/src/layout/modal/components/__stories__/Modal.stories.tsx:1-60]()

### twenty-website-new

`packages/twenty-website-new` 是 Twenty 的官方网站的代码库，基于 Next.js App Router 构建。该包负责展示产品信息、文档、合作伙伴页面和定价页面等。

网站结构包含多个主要页面：

- 首页 (`/`)：产品介绍和价值主张
- 产品页 (`/product`)：功能演示和特性展示
- 定价页 (`/pricing`)：定价方案和计算器
- 合作伙伴页 (`/partners`)：合作伙伴计划信息
- 客户案例页 (`/customers`)：成功案例展示
- 文章页 (`/articles`)：博客和团队文章
- 隐私政策页 (`/privacy-policy`)：隐私政策文档

资料来源：[packages/twenty-website-new/src/app/[locale]/(home)/page.tsx:1-25]()

### create-twenty-app

`create-twenty-app` 是 Twenty 的官方 CLI 脚手架工具，用于快速创建基于 Twenty CRM 的应用程序。该工具集成 `twenty-sdk`，为开发者提供开箱即用的项目模板。

快速开始命令：

```bash
npx create-twenty-app@latest my-twenty-app
cd my-twenty-app
yarn twenty dev
```

脚手架工具会自动创建包含 TypeScript、linting 配置和 twenty-sdk 集成的项目结构。

资料来源：[packages/create-twenty-app/README.md:1-25]()

## 页面组件架构

Twenty 网站的页面采用组件组合模式，主要包含以下结构化组件：

```mermaid
graph LR
    A[Hero 组件] --> B[TrustedBy 组件]
    A --> C[Problem 组件]
    A --> D[ThreeCards 组件]
    A --> E[Faq 组件]
    A --> F[Signoff 组件]
    
    style A fill:#e3f2fd
    style E fill:#e8f5e9
    style F fill:#fff8e1
```

### 核心组件列表

| 组件名称 | 用途 | 常见页面 |
|----------|------|----------|
| `Hero` | 首屏大图和主标题 | 所有页面 |
| `TrustedBy` | 客户信任展示 | 首页、定价、合作伙伴 |
| `Problem` | 问题陈述 | 首页 |
| `ThreeCards` | 三栏特性卡片 | 首页、合作伙伴、产品 |
| `Editorial` | 编辑风格内容区块 | Why Twenty 页面 |
| `Faq` | 常见问题解答 | 所有营销页面 |
| `Signoff` | 行动召唤区块 | 所有页面 |
| `Testimonials` | 用户推荐轮播 | 首页、合作伙伴 |
| `Demo` | 产品演示区块 | 产品页 |

## 国际化

Twenty 项目采用国际化（i18n）设计，所有用户可见的文本都通过 `i18n._()` 函数包裹，支持多语言切换。国际化配置位于 `src/lib/i18n` 目录下。

使用示例：

```tsx
{i18n._(msg`Get started`)}
{i18n._(msg`Stop fighting custom.`)}
{i18n._(msg`Start building, with Twenty`)}
```

资料来源：[packages/twenty-website-new/src/app/[locale]/(home)/page.tsx:15-22]()

## 企业级功能

### 自托管部署

Twenty 支持企业自托管部署，提供完整的许可证激活流程。企业用户可以在完成购买后，通过激活页面将许可证密钥集成到自托管实例中。

资料来源：[packages/twenty-website-new/src/app/[locale]/enterprise/activate/page.tsx:1-20]()

### 隐私与合规

Twenty 致力于遵守适用的数据保护法规，包括：

- 通用数据保护条例（GDPR）
- 加州消费者隐私法案（CCPA）

官方隐私政策于 2025 年 10 月 13 日生效。

资料来源：[packages/twenty-website-new/src/app/[locale]/privacy-policy/_components/PrivacyPolicyDocument.tsx:1-20]()

## 技术栈概览

| 领域 | 技术选择 |
|------|----------|
| 前端框架 | React 18, Next.js |
| 语言 | TypeScript |
| UI 组件 | twenty-ui (内部库) |
| 状态管理 | React Context, Hooks |
| 样式方案 | CSS-in-JS, Theme System |
| 国际化 | 自定义 i18n 方案 |
| 测试 | Storybook, Testing Library |
| 包管理 | Yarn, npm |

## 快速开始

开发者可以通过以下方式快速开始使用 Twenty：

1. **体验云端版本**：访问 [app.twenty.com/welcome](https://app.twenty.com/welcome)
2. **搭建本地开发环境**：使用 `create-twenty-app` CLI 工具
3. **贡献代码**：参考项目中的 `CLAUDE.md` 了解贡献指南

## 社区与支持

- **Discord 社区**：[discord.gg/cx5n4Jzs57](https://discord.gg/cx5n4Jzs57)
- **官方网站**：[twenty.com](https://twenty.com)
- **开源许可证**：采用开源许可证（详见 LICENSE 文件）

资料来源：[packages/create-twenty-app/README.md:5-8]()

## 总结

Twenty 是一个现代化的开源 CRM 平台，专为技术团队设计。它通过模块化架构、AI 集成能力和无代码定制特性，使企业能够构建真正符合自身需求的客户关系管理系统。作为一个活跃的开源项目，Twenty 持续演进，为开源 CRM 生态提供企业级替代方案。

---

<a id='page-tech-stack'></a>

## 技术栈概览

### 相关页面

相关主题：[项目介绍](#page-introduction), [前端架构](#page-frontend-architecture), [后端架构](#page-server-architecture)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [package.json](https://github.com/twentyhq/twenty/blob/main/package.json)
- [nx.json](https://github.com/twentyhq/twenty/blob/main/nx.json)
- [packages/twenty-front/package.json](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/package.json)
- [packages/twenty-server/package.json](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/package.json)
- [packages/twenty-website-new/package.json](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/package.json)
- [packages/twenty-docs/package.json](https://github.com/twentyhq/twenty/blob/main/packages/twenty-docs/package.json)
- [packages/create-twenty-app/README.md](https://github.com/twentyhq/twenty/blob/main/packages/create-twenty-app/README.md)
</details>

# 技术栈概览

Twenty 是一个开源的企业级 CRM 系统，采用现代化的全栈技术架构。本页面详细介绍整个项目的技术选型、核心依赖和架构设计。

## 项目架构概览

Twenty 采用 **Monorepo** 结构管理，使用 Nx 作为构建系统。整体架构分为前端展示层、后端服务层和数据持久层。

```mermaid
graph TD
    subgraph 前端层
        WEB[twenty-website-new<br/>营销网站]
        FRONT[twenty-front<br/>CRM前端应用]
    end
    
    subgraph 服务层
        SERVER[twenty-server<br/>后端服务]
        SDK[twenty-sdk<br/>SDK工具包]
    end
    
    subgraph 工具层
        CLI[create-twenty-app<br/>脚手架工具]
        DOCS[twenty-docs<br/>文档系统]
    end
    
    subgraph 数据层
        DB[(PostgreSQL)]
        CACHE[(Redis)]
    end
    
    WEB --> SERVER
    FRONT --> SERVER
    FRONT --> SDK
    CLI --> SDK
    SERVER --> DB
    SERVER --> CACHE
```

## 包结构说明

项目位于 `packages/` 目录下，主要包含以下核心包：

| 包名 | 说明 | 技术框架 |
|------|------|----------|
| `twenty-front` | CRM 前端应用 | React, TypeScript, GraphQL |
| `twenty-server` | 后端 API 服务 | Node.js, TypeScript |
| `twenty-website-new` | 营销网站 | Next.js, React, TypeScript |
| `twenty-docs` | 开发者文档 | MDX, Mintlify |
| `twenty-sdk` | SDK 开发工具包 | TypeScript |
| `create-twenty-app` | 项目脚手架 | Node.js CLI |

## 前端技术栈

### 核心框架

前端采用 **React 18** 作为 UI 框架，结合 **TypeScript** 提供类型安全。组件化架构支持高度定制化的 CRM 功能开发。

```mermaid
graph LR
    subgraph React生态
        CORE[React Core]
        ROUTER[React Router]
        QUERY[React Query<br/>数据获取]
        FORM[React Hook Form]
    end
    
    subgraph UI层
        COMP[组件库]
        ICONS[图标系统]
        STYLES[样式方案]
    end
    
    CORE --> ROUTER
    CORE --> QUERY
    CORE --> FORM
    ROUTER --> COMP
    QUERY --> COMP
```

### 营销网站技术选型

`twenty-website-new` 包采用 Next.js App Router 架构实现国际化营销站点：

- **Next.js 14+**：App Router 路由系统
- **国际化方案**：基于 `i18n._()` 的消息提取模式
- **样式方案**：CSS Modules + 设计系统变量
- **动态路由**：`[locale]` 动态段支持多语言

### 关键特性实现

从代码分析可知，前端实现了多项 CRM 核心功能：

| 功能模块 | 实现方式 | 文件位置 |
|----------|----------|----------|
| 对象元数据管理 | 标准化对象定义系统 | `packages/twenty-server/src/engine/workspace-manager/` |
| 字段元数据 | 字段类型系统 (UUID, DateTime 等) | `packages/twenty-server/.../field-metadata/` |
| 工作区管理 | Workspace Manager 统一管理 | `packages/twenty-server/.../workspace-manager/` |

## 后端技术栈

### 服务端架构

`twenty-server` 采用模块化的 Node.js 服务架构：

```mermaid
graph TD
    API[API Gateway]
    subgraph 引擎层
        WM[Workspace Manager]
        OBJ[Object Metadata]
        FIELD[Field Metadata]
    end
    
    subgraph 标准应用
        TWENTY_STD[Twenty Standard<br/>Application]
    end
    
    subgraph 数据层
        ORM[ORM Layer]
        DB[(Database)]
    end
    
    API --> WM
    WM --> OBJ
    WM --> FIELD
    OBJ --> TWENTY_STD
    FIELD --> TWENTY_STD
    TWENTY_STD --> ORM
    ORM --> DB
```

### 核心依赖

后端服务主要依赖以下技术：

| 技术类别 | 选型 | 用途 |
|----------|------|------|
| 运行时 | Node.js | 服务端运行环境 |
| 语言 | TypeScript | 类型安全开发 |
| 框架 | 自研引擎 | CRM 核心业务逻辑 |
| 数据库 | PostgreSQL | 主数据存储 |
| 缓存 | Redis | 会话和缓存管理 |
| API | GraphQL | 前后端数据交互 |

### 标准对象系统

系统内置标准对象通过 `create-standard-flat-object-metadata` 工具创建：

- **messageThread**：消息会话对象
- **message**：消息记录对象
- **noteTarget**：笔记关联对象

每个标准对象包含以下元数据属性：

| 属性 | 说明 |
|------|------|
| `universalIdentifier` | 全局唯一标识符 |
| `nameSingular/namePlural` | 单复数名称 |
| `labelSingular/labelPlural` | 显示标签 |
| `icon` | 图标标识 |
| `isSystem` | 系统对象标识 |
| `labelIdentifierFieldMetadataName` | 主标识字段 |

## 开发者工具链

### CLI 脚手架

`create-twenty-app` 提供快速启动能力：

```bash
npx create-twenty-app@latest my-twenty-app
cd my-twenty-app
yarn twenty dev
```

脚手架自动配置：
- TypeScript 项目结构
- ESLint + Prettier 代码规范
- twenty-sdk 集成
- 开发服务器配置

### SDK 工具包

`twenty-sdk` 是连接应用与 Twenty CRM 的官方开发工具包，封装了：
- GraphQL 客户端
- 认证模块
- 数据操作 API
- 类型定义导出

## 文档系统

### 开发者文档架构

`twenty-docs` 采用 MDX 格式编写文档，支持 Mintlify 文档站点生成：

```mermaid
graph LR
    MDX[MDX 源文件] --> NAV[导航结构]
    NAV --> CROWDIN[国际化 Crowdin]
    CROWDIN --> BUILD[docs.json]
    BUILD --> MINTLIFY[Mintlify 站点]
```

### 文档配置要点

| 文件 | 作用 |
|------|------|
| `navigation/base-structure.json` | 导航结构定义（英文源） |
| `navigation/navigation.template.json` | 翻译模板 |
| `l/<language>/navigation.json` | 各语言本地化 |
| `docs.json` | Mintlify 配置输出 |

## 构建与部署

### Monorepo 构建配置

项目使用 Nx 管理多包构建：

- 依赖关系自动分析
- 增量构建支持
- 任务编排优化
- affected 命令支持

### 云端部署

Twenty 支持多种部署方式：

| 部署方式 | 说明 | 适用场景 |
|----------|------|----------|
| Cloud SaaS | twenty.com 托管服务 | 开箱即用 |
| 自托管 | Docker/Kubernetes | 企业私有部署 |
| 开发预览 | 本地开发环境 | 开发调试 |

### 企业版激活

企业版通过许可证密钥激活，激活流程：
1. 完成企业版购买
2. 在自托管实例中输入许可证密钥
3. 系统验证并激活高级功能

## 总结

Twenty 的技术栈设计体现了现代化 CRM 的最佳实践：

- **前后端分离**：清晰的职责边界
- **TypeScript 全面覆盖**：类型安全
- **Monorepo 管理**：代码复用与统一版本控制
- **模块化架构**：易于扩展和维护
- **国际化支持**：全球化部署

这套技术架构既保证了系统的稳定性和可扩展性，又为开发者提供了良好的二次开发体验。

---

<a id='page-monorepo-structure'></a>

## Monorepo结构

### 相关页面

相关主题：[项目介绍](#page-introduction), [前端架构](#page-frontend-architecture)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [package.json](https://github.com/twentyhq/twenty/blob/main/package.json)
- [nx.json](https://github.com/twentyhq/twenty/blob/main/nx.json)
- [packages/twenty-docs/README.md](https://github.com/twentyhq/twenty/blob/main/packages/twenty-docs/README.md)
- [packages/twenty-website-new/src/app/[locale]/(home)/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/(home)/page.tsx)
- [packages/twenty-website-new/src/app/[locale]/articles/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/articles/page.tsx)
- [packages/twenty-docs/navigation/base-structure.json](https://github.com/twentyhq/twenty/blob/main/packages/twenty-docs/navigation/base-structure.json)
- [packages/twenty-server/src/engine/workspace-manager/twenty-standard-application/utils/object-metadata/create-standard-flat-object-metadata.util.ts](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/engine/workspace-manager/twenty-standard-application/utils/object-metadata/create-standard-flat-object-metadata.util.ts)
</details>

# Monorepo结构

## 概述

Twenty项目采用**Nx驱动的Monorepo架构**，将前端、后端、文档等多个应用和包组织在单一代码仓库中。这种架构模式便于统一管理依赖、共享代码库、简化CI/CD流程，并确保整个项目的一致性。

## 核心包结构

Twenty项目的主要包位于`packages/`目录下，每个包都有独立的职责：

| 包名 | 类型 | 描述 |
|------|------|------|
| `twenty-front` | Next.js应用 | CRM主前端界面 |
| `twenty-server` | Node.js服务 | 后端API和引擎 |
| `twenty-website-new` | Next.js应用 | 官方网站和营销页面 |
| `twenty-docs` | 文档 | Mintlify文档站点 |

## Nx工作区配置

项目根目录的`nx.json`定义了Monorepo的工作区配置：

```json
{
  "extends": "@nx/next/preset",
  "namedInputs": {
    "default": ["{projectRoot}/**/*"],
    "production": ["!{projectRoot}/**/*.spec.ts"]
  }
}
```

Nx提供了以下核心能力：

- **增量构建**：只重新构建变更影响的包
- **任务编排**：管理包之间的构建顺序和依赖关系
- **代码生成**：通过生成器创建模块、组件、服务
- **依赖图可视化**：展示包之间的依赖关系

## 前端包结构

### twenty-front

主CRM前端应用，包含以下核心目录：

```
packages/twenty-front/
├── src/
│   └── modules/           # 功能模块
│       ├── ai/            # AI相关组件
│       ├── activities/   # 活动管理
│       ├── companies/     # 公司管理
│       ├── contacts/      # 联系人
│       └── ...           # 其他业务模块
```

从`ThinkingStepsDisplay.tsx`可以看到前端组件遵循的约定：

- 使用React functional component
- 样式通过`Styled*`前缀的组件封装
- 支持TypeScript泛型和严格类型检查

### twenty-website-new

新版官方网站采用App Router结构：

```
packages/twenty-website-new/
├── src/
│   ├── app/
│   │   └── [locale]/      # 国际化路由
│   │       ├── (home)/    # 首页路由组
│   │       ├── articles/  # 文章页面
│   │       ├── releases/  # 发布日志
│   │       ├── customers/ # 客户案例
│   │       ├── partners/  # 合作伙伴
│   │       ├── product/   # 产品页面
│   │       ├── enterprise/# 企业版页面
│   │       ├── why-twenty/# 为什么选择Twenty
│   │       └── privacy-policy/ # 隐私政策
│   ├── sections/          # 可复用页面区块
│   │   ├── Hero/          # 英雄区组件
│   │   ├── Footer/        # 页脚
│   │   ├── CaseStudy/     # 案例研究组件
│   │   ├── AppPreview/    # 应用预览
│   │   └── ...
│   └── content/           # 内容配置
│       └── releases/      # 发布说明MDX
```

## 后端包结构

### twenty-server

后端服务位于`packages/twenty-server/`，采用模块化架构：

```
packages/twenty-server/
└── src/
    └── engine/
        ├── workspace-manager/           # 工作区管理
        │   └── twenty-standard-application/
        │       └── utils/
        │           ├── object-metadata/ # 对象元数据工具
        │           └── field-metadata/   # 字段元数据工具
        └── api/                         # API层
```

核心模块包括：

- **workspace-manager**：管理工作区生命周期和标准对象
- **twenty-standard-application**：标准应用定义，包含如`messageThread`、`message`等系统对象
- **metadata层**：处理元数据的创建和关系映射

## 文档系统

### twenty-docs

文档包使用Mintlify框架，支持国际化：

```
packages/twenty-docs/
├── navigation/
│   ├── base-structure.json      # 导航基准结构
│   └── navigation.template.json # 翻译模板
├── l/                           # 本地化文件
│   └── <language>/
│       └── navigation.json      # 语言特定导航
├── docs.json                    # 生成的Mintlify配置
└── docs/                        # MDX文档内容
```

文档导航配置流程：

1. 编辑`navigation/base-structure.json`定义结构和slug
2. 运行`yarn docs:generate-navigation-template`生成翻译模板
3. 上传到Crowdin进行翻译
4. 拉取翻译文件到`l/<language>/navigation.json`
5. 运行`yarn docs:generate`生成最终配置

## 依赖关系图

```mermaid
graph TD
    A[nx.json - 工作区配置] --> B[twenty-front]
    A --> C[twenty-server]
    A --> D[twenty-website-new]
    A --> E[twenty-docs]
    
    B --> F[@twenty-ui/* 共享UI组件]
    B --> C[API调用]
    
    C --> G[workspace-manager]
    C --> H[standard-application]
    
    D --> B[复用组件]
    D --> I[content - 发布日志]
    
    E --> J[base-structure.json]
    J --> K[Crowdin翻译]
    K --> L[本地化导航]
    L --> M[docs.json]
```

## 常用命令

项目根目录的`package.json`定义了关键脚本：

| 命令 | 描述 |
|------|------|
| `yarn docs:generate` | 生成文档配置 |
| `yarn docs:dev` | 本地开发文档 |
| `yarn docs:validate` | 验证文档构建 |
| `npx nx run twenty-docs:dev` | 运行文档开发服务器 |

## 页面组件层次结构

Twenty网站的页面采用组件组合模式：

```mermaid
graph TD
    A[Page Component] --> B[Menu.Root]
    A --> C[Hero.Root]
    A --> D[TrustedBy.Root]
    A --> E[Feature Sections]
    A --> F[Testimonials.Root]
    A --> G[Faq.Root]
    A --> H[Signoff.Root]
    A --> I[Footer]
    
    C --> C1[Hero.Heading]
    C --> C2[Hero.Body]
    C --> C3[Hero.Cta]
    C --> C4[Hero.AppPreview]
```

## 路由和国际化

网站使用Next.js App Router的`[locale]`动态路由实现国际化：

```
src/app/[locale]/
├── (home)/page.tsx      # 首页
├── articles/page.tsx    # 文章列表
├── releases/page.tsx    # 发布日志
├── customers/           # 客户案例
│   └── w3villa/page.tsx
├── product/page.tsx     # 产品页
└── enterprise/
    └── activate/page.tsx
```

## 标准对象元数据

后端定义了一系列标准对象（Standard Objects），每个对象都有标准的字段元数据：

| 对象名 | 标签 | 图标 | 用途 |
|--------|------|------|------|
| `messageThread` | Message Thread | IconMessage | 消息线程 |
| `message` | Message | IconMessage | 单条消息 |
| `noteTarget` | Note Target | - | 笔记关联 |

这些标准对象通过`createStandardFlatObjectMetadata`工具函数创建，具有：

- 系统字段（`id`, `createdAt`, `updatedAt`）
- 国际化标签支持（通过`i18nLabel`）
- 标准图标定义
- 审计日志配置

## 总结

Twenty的Monorepo结构设计遵循以下原则：

1. **职责分离**：每个包有明确的边界和职责
2. **共享代码**：通过包内部引用实现代码复用
3. **增量构建**：Nx确保只构建受影响的包
4. **国际化**：统一的locale路由和翻译管理
5. **模块化组件**：网站区块高度可复用

---

<a id='page-frontend-architecture'></a>

## 前端架构

### 相关页面

相关主题：[UI组件库](#page-ui-components), [后端架构](#page-server-architecture), [Monorepo结构](#page-monorepo-structure)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/twenty-website-new/src/app/[locale]/articles/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/articles/page.tsx)
- [packages/twenty-website-new/src/app/[locale]/(home)/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/(home)/page.tsx)
- [packages/twenty-website-new/src/app/[locale]/partners/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/partners/page.tsx)
- [packages/twenty-website-new/src/app/[locale]/enterprise/activate/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/enterprise/activate/page.tsx)
- [packages/twenty-website-new/src/app/[locale]/pricing/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/pricing/page.tsx)
- [packages/twenty-front/src/modules/ai/components/ThinkingStepsDisplay.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/ai/components/ThinkingStepsDisplay.tsx)
- [packages/twenty-front/src/pages/not-found/NotFound.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/pages/not-found/NotFound.tsx)
- [packages/twenty-website-new/src/sections/Footer/data.ts](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/sections/Footer/data.ts)
- [packages/twenty-website-new/src/app/[locale]/product/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/product/page.tsx)
</details>

# 前端架构

## 概述

Twenty 项目采用**多包架构**（monorepo 结构），前端代码分散在多个独立的功能包中，主要包括：

| 包名 | 用途 |
|------|------|
| `packages/twenty-front` | 主应用程序前端核心，包含 CRM 业务逻辑和 UI 组件 |
| `packages/twenty-website-new` | 营销网站和新版文档站点 |
| `packages/twenty-docs` | 开发者文档（基于 Mintlify） |
| `packages/create-twenty-app` | 项目脚手架 CLI 工具 |

本页面重点介绍 `twenty-front` 和 `twenty-website-new` 的前端架构设计。

---

## 整体架构分层

Twenty 前端采用**模块化分层架构**，各层职责清晰分离：

```mermaid
graph TD
    A[UI Layer<br/>React Components] --> B[Module Layer<br/>Feature Modules]
    B --> C[Hook Layer<br/>Custom Hooks]
    C --> D[State Layer<br/>Recoil/Zustand]
    D --> E[Service Layer<br/>API Clients]
    E --> F[API Layer<br/>GraphQL/REST]
    
    G[Pages] --> A
    H[Layouts] --> A
    I[Shared Components] --> A
```

### 层级职责说明

| 层级 | 说明 | 代码位置 |
|------|------|----------|
| UI Layer | 原子化组件和复合组件 | `packages/twenty-front/src/modules/*/components` |
| Module Layer | 业务功能模块封装 | `packages/twenty-front/src/modules/*` |
| Hook Layer | 可复用的业务逻辑钩子 | `packages/twenty-front/src/hooks` |
| State Layer | 全局状态管理 | `packages/twenty-front/src/modules/*/states` |
| Service Layer | API 调用封装 | `packages/twenty-front/src/modules/*/services` |

---

## 页面路由结构

### 营销网站路由 (`twenty-website-new`)

营销网站基于 **Next.js App Router**，采用国际化路由 `[locale]` 动态段：

```
src/app/[locale]/
├── page.tsx                    # 首页
├── articles/
│   └── page.tsx                # 文章列表页
├── partners/
│   └── page.tsx                # 合作伙伴页面
├── pricing/
│   └── page.tsx                # 定价页面
├── product/
│   └── page.tsx                # 产品功能页面
├── enterprise/
│   └── activate/
│       └── page.tsx            # 企业激活页面
├── customers/
│   ├── page.tsx                # 客户案例列表
│   └── w3villa/
│       └── page.tsx            # 特定案例页面
├── why-twenty/
│   └── page.tsx                # 为什么选择 Twenty
└── releases/
    └── page.tsx                # 发布日志
```

资料来源：[packages/twenty-website-new/src/app/[locale]/(home)/page.tsx:1-10]()

### CRM 应用路由 (`twenty-front`)

主应用使用自定义路由系统，通过 `AppPath` 常量定义路由路径：

```typescript
// 路由类型定义示例
export enum AppPath {
  Index = '/',
  NotFound = '/not-found',
  // ... 更多路由
}
```

资料来源：[packages/twenty-front/src/pages/not-found/NotFound.tsx:40-50]()

---

## 组件架构

### 组件组织模式

Twenty 前端采用**区域组件**（Section Components）和**功能组件**分离的组织模式：

```mermaid
graph LR
    A[Section Components] -->|Hero| B[HeadingGroup]
    A -->|Hero| C[Body]
    A -->|Hero| D[Cta]
    A -->|Hero| E[Visual]
    F[Feature Components] -->|TrustedBy| G[Logos]
    F -->|TrustedBy| H[Separator]
    F -->|Faq| I[Items]
    F -->|Testimonials| J[Carousel]
```

### 核心页面组件

| 组件 | 功能 | 源码位置 |
|------|------|----------|
| `Hero.Root` | 英雄区域根容器 | `twenty-website-new/src/sections/Hero` |
| `Hero.Heading` | 主标题渲染 | 同上 |
| `Hero.Body` | 正文内容 | 同上 |
| `Hero.Cta` | 行动按钮组 | 同上 |
| `TrustedBy.Root` | 信任背书区域 | `twenty-website-new/src/sections/TrustedBy` |
| `Faq.Root` | 常见问题区域 | `twenty-website-new/src/sections/Faq` |
| `Signoff.Root` | 结尾号召区域 | `twenty-website-new/src/sections/Signoff` |
| `Testimonials.Carousel` | 用户推荐轮播 | `twenty-website-new/src/sections/Testimonials` |

资料来源：[packages/twenty-website-new/src/app/[locale]/(home)/page.tsx:1-20]()

### 组件 Props 接口模式

组件使用强类型 Props 接口，继承基础配置：

```typescript
// Hero 组件 Props 示例
interface HeroProps {
  page: Pages;           // 页面标识
  scheme?: 'light' | 'dark';
  children: React.ReactNode;
}

// Heading 组件
interface HeadingPartProps {
  fontFamily: 'serif' | 'sans';
  children: React.ReactNode;
}
```

---

## 样式系统

### Styled Components 方案

Twenty 前端使用 `styled-components` 作为主要的样式解决方案：

```typescript
const StyledContainer = styled.div`
  display: flex;
  flex-direction: column;
  position: relative;
`;

const StyledBackDrop = styled.div`
  position: fixed;
  top: 0;
  width: 100%;
  z-index: ${RootStackingContextZIndices.NotFound};
`;
```

资料来源：[packages/twenty-front/src/pages/not-found/NotFound.tsx:1-30]()

### 主题配置

| 配置项 | 说明 |
|--------|------|
| `theme.colors.primary` | 主色调变体 |
| `theme.colors.secondary` | 次要色调变体 |
| `theme.fonts.serif` | 衬线字体（用于标题） |
| `theme.fonts.sans` | 无衬线字体（用于正文） |

---

## 国际化实现

### i18n 配置

项目使用 `@lingui` 进行国际化处理：

```typescript
import { msg } from '@lingui/macro';

// 使用 msg 宏定义翻译文本
const heading = i18n._(msg`Build your Enterprise CRM`);
const buttonLabel = i18n._(msg`Get started`);
```

### 国际化组件

| 组件 | 用途 |
|------|------|
| `<HeadingPart fontFamily="serif">` | 文本片段字体样式控制 |
| `<Eyebrow>` | 眉毛标题（小标签文字） |
| `<Trans>` | React 翻译组件 |

资料来源：[packages/twenty-website-new/src/app/[locale]/(home)/page.tsx:5-15]()

---

## 状态管理

### 思考步骤状态示例

AI 思考步骤的显示逻辑展示了状态管理模式：

```typescript
const ThinkingStepsDisplay = ({ parts, reasoningContent }) => {
  const shouldDisplayReasoningContent = !!reasoningContent;
  
  return (
    <StyledContainer>
      <StyledRowsContainer>
        {parts.map((part, index) => (
          <ThinkingStepRow
            key={index}
            part={part}
            rowIndex={index}
            isActive={isThinkingStepPartActive(part, isLastMessageStreaming)}
          />
        ))}
      </StyledRowsContainer>
    </StyledContainer>
  );
};
```

资料来源：[packages/twenty-front/src/modules/ai/components/ThinkingStepsDisplay.tsx:1-30]()

### 状态管理模式

| 模式 | 适用场景 | 库 |
|------|----------|-----|
| 组件本地状态 | UI 交互状态 | `useState` |
| 全局状态 | 跨模块共享数据 | `Recoil` / `Zustand` |
| 服务端状态 | API 数据缓存 | `React Query` / `SWR` |

---

## 路由与导航

### 主应用路由

```typescript
// AppPath 枚举定义
export enum AppPath {
  Index = '/',
  NotFound = '/not-found',
  // CRM 相关路由...
}

// 404 页面实现
export const NotFound = () => {
  const { t } = useLingui();
  
  return (
    <>
      <PageTitle title={t`Page Not Found | Twenty`} />
      <StyledBackDrop>
        <AnimatedPlaceholderErrorContainer>
          <AnimatedPlaceholder type="error404" />
          {/* 错误提示内容 */}
        </AnimatedPlaceholderErrorContainer>
      </StyledBackDrop>
      <Suspense fallback={null}>
        <BackgroundMockPage />
      </Suspense>
    </>
  );
};
```

资料来源：[packages/twenty-front/src/pages/not-found/NotFound.tsx:40-75]()

### 营销网站路由

营销网站采用 Next.js 的文件系统路由：

```typescript
// 动态路由段 [locale]
// 文件结构自动映射到 URL
// /articles -> 文章列表
// /pricing -> 定价页面
// /partners -> 合作伙伴
```

资料来源：[packages/twenty-website-new/src/app/[locale]/articles/page.tsx:1-10]()

---

## 页面布局模式

### 典型页面结构

```mermaid
graph TD
    A[Menu Header] --> B[Hero Section]
    B --> C[TrustedBy Section]
    C --> D[Feature Tabs/Sections]
    D --> E[Testimonials]
    E --> F[Faq Section]
    F --> G[Signoff Section]
    G --> H[Footer]
```

### 页面区域组件

| 区域组件 | 说明 |
|----------|------|
| `Menu.Root` | 顶部导航菜单 |
| `Hero.Root` | 首屏英雄区域 |
| `TrustedBy.Root` | 客户信任背书 |
| `Tabs.Root` | 功能特性标签页 |
| `ThreeCards.Root` | 三卡片布局 |
| `PromoSpacing` | 间距调整组件 |
| `Faq.Root` | 常见问题解答 |
| `Signoff.Root` | 页面结尾号召 |
| `Footer` | 页脚信息 |

资料来源：[packages/twenty-website-new/src/app/[locale]/partners/page.tsx:1-40]()

---

## 模块化设计

### 前端模块结构

```
packages/twenty-front/src/modules/
├── activities/          # 活动/任务模块
├── ai/                  # AI 功能模块
├── billing/             # 账单模块
├── calendar/            # 日历模块
├── companies/           # 公司管理模块
├── contacts/            # 联系人模块
├── people/              # 人员模块
├── tasks/               # 任务模块
└── ui-tweak/            # UI 定制模块
```

每个模块遵循统一的结构：

| 子目录 | 用途 |
|--------|------|
| `components/` | 模块专属组件 |
| `hooks/` | 模块专属钩子 |
| `states/` | 模块状态定义 |
| `services/` | 模块 API 服务 |
| `graphql/` | GraphQL 查询和变更 |

资料来源：[packages/twenty-front/src/modules/ai/components/ThinkingStepsDisplay.tsx:1-5]()

---

## 数据获取

### API 服务层

模块通过服务层封装 API 调用：

```typescript
// 服务接口定义示例
interface ApiService<T> {
  getAll(): Promise<T[]>;
  getById(id: string): Promise<T>;
  create(data: Partial<T>): Promise<T>;
  update(id: string, data: Partial<T>): Promise<T>;
  delete(id: string): Promise<void>;
}
```

### 页面数据获取模式

```typescript
// Next.js Server Component 模式
async function Page() {
  // 服务端获取数据
  const posts = await getPosts();
  
  return <Articles.Index posts={posts} />;
}
```

资料来源：[packages/twenty-website-new/src/app/[locale]/articles/page.tsx:10-20]()

---

## 错误处理

### 404 错误页面

```typescript
const NotFound = () => {
  return (
    <StyledBackDrop>
      <AnimatedPlaceholderErrorContainer>
        <AnimatedPlaceholder type="error404" />
        <AnimatedPlaceholderErrorTitle>
          <Trans>Off the beaten path</Trans>
        </AnimatedPlaceholderErrorTitle>
        <AnimatedPlaceholderErrorSubTitle>
          <Trans>The page you're seeking is either gone or never was.</Trans>
        </AnimatedPlaceholderErrorSubTitle>
        <StyledButtonContainer>
          <UndecoratedLink to={AppPath.Index}>
            <MainButton title={t`Back to content`} fullWidth />
          </UndecoratedLink>
        </StyledButtonContainer>
      </AnimatedPlaceholderErrorContainer>
    </StyledBackDrop>
  );
};
```

资料来源：[packages/twenty-front/src/pages/not-found/NotFound.tsx:50-70]()

---

## 构建与部署

### 包管理器

项目使用 **Yarn** 作为包管理器：

```bash
# 安装依赖
yarn install

# 开发模式
yarn dev

# 构建生产版本
yarn build
```

### 环境配置

| 环境变量 | 说明 |
|----------|------|
| `NEXT_PUBLIC_API_URL` | API 服务地址 |
| `DATABASE_URL` | 数据库连接字符串 |
| `STORAGE_SECRET` | 存储服务密钥 |

---

## 技术栈总结

| 类别 | 技术选型 |
|------|----------|
| 框架 | Next.js (App Router) / React 18 |
| 语言 | TypeScript |
| 样式 | styled-components |
| 状态管理 | Recoil / Zustand |
| 国际化 | @lingui |
| 包管理 | Yarn |
| 组件库 | 自定义组件系统 |
| 测试 | Jest / React Testing Library |

---

## 相关文档

- [Twenty 官方文档](https://docs.twenty.com)
- [Twenty GitHub 仓库](https://github.com/twentyhq/twenty)
- [Create Twenty App CLI](https://www.npmjs.com/package/create-twenty-app)

---

<a id='page-ui-components'></a>

## UI组件库

### 相关页面

相关主题：[前端架构](#page-frontend-architecture), [Activities活动模块](#page-activities-module)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/twenty-website-new/src/app/[locale]/(home)/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/(home)/page.tsx)
- [packages/twenty-website-new/src/app/[locale]/product/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/product/page.tsx)
- [packages/twenty-website-new/src/app/[locale]/pricing/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/pricing/page.tsx)
- [packages/twenty-website-new/src/app/[locale]/partners/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/partners/page.tsx)
- [packages/twenty-website-new/src/app/[locale]/customers/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/customers/page.tsx)
- [packages/twenty-website-new/src/app/[locale]/why-twenty/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/why-twenty/page.tsx)
- [packages/twenty-website-new/src/sections/Footer/data.ts](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/sections/Footer/data.ts)
- [packages/twenty-website-new/src/sections/Salesforce/components/PricingWindow.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/sections/Salesforce/components/PricingWindow.tsx)
</details>

# UI组件库

Twenty CRM 的 UI 组件库是一个模块化、可复用的前端组件集合，主要位于 `packages/twenty-front` 和 `packages/twenty-website-new` 包中。该组件库为整个 Twenty 产品提供一致的视觉语言和交互体验。

## 组件库架构

### 包结构

```
twenty/
├── packages/
│   ├── twenty-front/                    # 主应用前端组件
│   │   └── src/modules/ui-library/      # UI组件库核心
│   ├── twenty-website-new/              # 营销网站
│   │   └── src/sections/                # 页面区块组件
│   └── twenty-front-component-renderer/ # 组件渲染器
```

### 组件分类

Twenty UI 组件库按功能可分为以下几大类：

| 类别 | 功能描述 | 典型组件 |
|------|----------|----------|
| 布局组件 | 页面结构和容器 | Container, Panel |
| 导航组件 | 用户导航和路由 | LinkButton, UndecoratedLink |
| 内容组件 | 展示文本和媒体 | Heading, HeadingPart, Eyebrow |
| 表单组件 | 用户输入和交互 | MainButton, FakeButton |
| 数据展示 | 列表和表格 | Tiles, Cards |
| 交互反馈 | 动画和状态 | AnimatedPlaceholder, Tooltip |

## 核心组件详解

### Heading 标题组件

标题组件支持多种字体家族和尺寸配置，用于页面层级的视觉层次表达。

```tsx
<Heading size="lg" weight="light">
  <HeadingPart fontFamily="serif">
    {i18n._(msg`A modern CRM with`)}
  </HeadingPart>{' '}
  <HeadingPart fontFamily="sans">
    {i18n._(msg`an intuitive interface`)}
  </HeadingPart>
</Heading>
```

**参数说明：**

| 参数 | 类型 | 可选值 | 默认值 | 说明 |
|------|------|--------|--------|------|
| size | string | `sm`, `md`, `lg` | `md` | 标题尺寸 |
| weight | string | `light`, `regular`, `bold` | `regular` | 字体粗细 |
| fontFamily | string | `serif`, `sans` | `sans` | 字体系列 |

资料来源：[packages/twenty-website-new/src/app/[locale]/product/page.tsx]()

### LinkButton 链接按钮

用于页面间导航的按钮组件，支持多种变体和颜色配置。

```tsx
<LinkButton
  color="primary"
  href="https://app.twenty.com/welcome"
  label={i18n._(msg`Get started`)}
  variant="contained"
/>
```

**变体类型：**

| variant | 说明 |
|---------|------|
| `contained` | 实心填充样式 |
| `outlined` | 描边样式 |
| `text` | 纯文本样式 |

资料来源：[packages/twenty-website-new/src/app/[locale]/pricing/page.tsx]()

### Hero 英雄区域组件

页面顶部的核心展示区域，包含主标题、描述和行动号召按钮。

```tsx
<Hero.Root>
  <Hero.Heading page={Pages.Home}>
    <HeadingPart fontFamily="serif">
      {i18n._(msg`Build your Enterprise CRM`)}
    </HeadingPart>{' '}
    <HeadingPart fontFamily="sans">
      {i18n._(msg`at AI Speed`)}
    </HeadingPart>
  </Hero.Heading>
  <Hero.Body page={Pages.Home} size="sm">
    {i18n._(
      msg`Twenty gives technical teams the building blocks...`,
    )}
  </Hero.Body>
  <Hero.Cta>
    <LinkButton ... />
    <TalkToUsButton ... />
  </Hero.Cta>
  <Hero.AppPreview visual={APP_PREVIEW_DATA.visual} />
</Hero.Root>
```

**Hero 子组件结构：**

```mermaid
graph TD
    A[Hero.Root] --> B[Hero.Heading]
    A --> C[Hero.Body]
    A --> D[Hero.Cta]
    A --> E[Hero.AppPreview 或 Hero.PartnerVisual 等]
```

资料来源：[packages/twenty-website-new/src/app/[locale]/(home)/page.tsx]()

### ThreeCards 三卡片布局

用于特性展示的三列卡片布局组件。

```tsx
<ThreeCards.Root scheme="light">
  <ThreeCards.Intro page={Pages.Home} align="center">
    <Eyebrow>...</Eyebrow>
    <Heading>...</Heading>
  </ThreeCards.Intro>
  <ThreeCards.FeatureCards featureCards={FEATURE_CARDS} />
  <ThreeCards.IllustrationCards 
    illustrationCards={ILLUSTRATION_CARDS} 
    variant="simple" 
  />
</ThreeCards.Root>
```

**参数说明：**

| 参数 | 类型 | 说明 |
|------|------|------|
| scheme | `light`, `muted`, `dark` | 配色方案 |
| align | `left`, `center` | 内容对齐方式 |
| variant | `simple`, `feature` | 卡片变体 |

资料来源：[packages/twenty-website-new/src/app/[locale]/partners/page.tsx]()

### Faq 常见问题组件

可折叠的问答展示组件。

```tsx
<Faq.Root>
  <Faq.Intro>
    <Eyebrow colorScheme="secondary">...</Eyebrow>
    <Faq.Heading>...</Faq.Heading>
    <Faq.Cta>...</Faq.Cta>
  </Faq.Intro>
  <Faq.Items questions={FAQ_QUESTIONS} />
</Faq.Root>
```

**数据结构：**

```typescript
interface FaqQuestion {
  question: string;
  answer: string;
  category?: string;
}
```

资料来源：[packages/twenty-website-new/src/app/[locale]/product/page.tsx]()

### TrustedBy 信任背书组件

展示合作品牌和客户数量的组件。

```tsx
<TrustedBy.Root
  separator={i18n._(msg`trusted by`)}
  logos={TRUSTED_BY_LOGOS}
  clientCount={i18n._(msg`+10k others`)}
  cardBackgroundColor={ARTICLES_TOP_BACKGROUND_COLOR}
  compactBottom
/>
```

**参数说明：**

| 参数 | 类型 | 说明 |
|------|------|------|
| separator | ReactNode | 分隔文本 |
| logos | Logo[] | 品牌 Logo 数组 |
| clientCount | string | 客户数量文本 |
| compactBottom | boolean | 紧凑底部样式 |

资料来源：[packages/twenty-website-new/src/app/[locale]/partners/page.tsx]()

## 样式系统

### Styled Components

Twenty 使用 `styled-components` 进行样式管理，实现 CSS-in-JS 方案。

```tsx
const StyledBackDrop = styled.div`
  position: fixed;
  top: 0;
  width: 100%;
  z-index: ${RootStackingContextZIndices.NotFound};
`;

const StyledButtonContainer = styled.div`
  width: 200px;
`;
```

资料来源：[packages/twenty-front/src/pages/not-found/NotFound.tsx]()

### 主题配置

组件通过 ThemeProvider 获取主题配置，包括颜色、字体、间距等。

```typescript
<TrustedBy.Root
  backgroundColor={theme.colors.primary.background[100]}
  ...
/>
```

### 配色方案

| 方案名称 | 使用场景 |
|----------|----------|
| `light` | 明亮背景区块 |
| `muted` | 柔和背景区块 |
| `dark` | 深色背景区块 |
| `secondary` | 次要强调色 |

## 国际化支持

### @lingui 集成

组件使用 `@lingui` 进行国际化处理，所有用户可见文本都通过 `i18n._()` 或 `msg` 宏定义。

```tsx
import { msg } from '@lingui/macro';

// 静态文本
const label = msg`Get started`;

// 动态文本
{i18n._(
  msg`Twenty gives technical teams the building blocks for a custom CRM...`,
)}
```

资料来源：[packages/twenty-website-new/src/app/[locale]/(home)/page.tsx]()

## 页面构建模式

### 区块组合模式

Twenty 网站采用区块化设计，通过组合不同 Section 组件构建完整页面。

```tsx
export default function HomePage() {
  return (
    <>
      <Hero.Root>...</Hero.Root>
      <TrustedBy.Root>...</TrustedBy.Root>
      <Problem.Root>...</Problem.Root>
      <ThreeCards.Root>...</ThreeCards.Root>
      <Feature.Root>...</Feature.Root>
      <Testimonials.Root>...</Testimonials.Root>
      <Faq.Root>...</Faq.Root>
    </>
  );
}
```

**页面结构流程：**

```mermaid
graph LR
    A[Hero 英雄区] --> B[TrustedBy 信任背书]
    B --> C[Problem 问题陈述]
    C --> D[ThreeCards 特性卡片]
    D --> E[Feature 功能展示]
    E --> F[Testimonials 客户证言]
    F --> G[Faq 常见问题]
```

资料来源：[packages/twenty-website-new/src/app/[locale]/customers/page.tsx]()

### 页面类型枚举

```typescript
enum Pages {
  Home = 'home',
  Product = 'product',
  Pricing = 'pricing',
  Partners = 'partners',
  Articles = 'articles',
  WhyTwenty = 'whyTwenty',
}
```

## 组件渲染器

### ComponentRenderer 模块

`twenty-front-component-renderer` 包提供了动态渲染 UI 组件的能力，支持在运行时根据配置渲染不同组件。

```
packages/twenty-front-component-renderer/src/
```

该模块允许：
- 根据数据动态渲染组件
- 支持组件配置化
- 实现运行时主题切换

资料来源：[packages/twenty-front-component-renderer/src](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front-component-renderer/src)

## Footer 导航数据

Footer 组件使用配置化数据源定义链接和 CTAs。

```typescript
{
  id: 'footer-product',
  title: msg`Product`,
  ctas: [
    {
      color: 'secondary',
      href: 'https://app.twenty.com/welcome',
      kind: 'link',
      label: msg`Get started`,
      variant: 'outlined',
    },
  ],
  links: [
    {
      label: msg`API & SDKs`,
      href: 'https://docs.twenty.com/api-rest/overview',
      external: true,
    },
  ],
}
```

**Footer 数据结构：**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | string | 唯一标识符 |
| title | Message | 区块标题 |
| ctas | CTA[] | 行动号召按钮 |
| links | Link[] | 链接列表 |

资料来源：[packages/twenty-website-new/src/sections/Footer/data.ts]()

## 最佳实践

### 组件组合

使用复合组件模式，通过子组件构建复杂 UI：

```tsx
<Faq.Root>
  <Faq.Intro>...</Faq.Intro>
  <Faq.Items>...</Faq.Items>
</Faq.Root>
```

### 国际化处理

始终使用 `i18n._()` 或 `msg` 包装用户可见文本：

```tsx
// ✅ 正确
<Heading>{i18n._(msg`Welcome`)}</Heading>

// ❌ 错误
<Heading>Welcome</Heading>
```

### 样式隔离

使用 styled-components 的样式隔离，避免全局污染：

```tsx
const StyledContainer = styled.div`
  // 样式定义
`;
```

### 可访问性

确保交互组件包含适当的 ARIA 属性：

```tsx
<Separator aria-hidden="true" />
```

资料来源：[packages/twenty-website-new/src/sections/Salesforce/components/PricingWindow.tsx]()

## 总结

Twenty 的 UI 组件库采用模块化设计，通过复合组件模式、配置化数据和国际化支持，构建了一套高效、可维护的前端组件体系。开发者可以通过组合这些基础组件快速构建页面，同时保持视觉一致性和交互体验的统一。

---

<a id='page-server-architecture'></a>

## 后端架构

### 相关页面

相关主题：[数据模型](#page-database-models), [前端架构](#page-frontend-architecture), [Docker部署](#page-docker-deployment)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/twenty-server/src](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src)
- [packages/twenty-server/src/modules](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/modules)
- [packages/twenty-docs/developers/contribute/capabilities/backend-development](https://github.com/twentyhq/twenty/blob/main/packages/twenty-docs/developers/contribute/capabilities/backend-development)
- [packages/create-twenty-app/README.md](https://github.com/twentyhq/twenty/blob/main/packages/create-twenty-app/README.md)
- [packages/twenty-website-new/src/app/[locale]/enterprise/activate/page.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/app/[locale]/enterprise/activate/page.tsx)
</details>

# 后端架构

## 概述

Twenty 的后端架构是整个 CRM 系统的核心，负责处理业务逻辑、数据持久化、API 接口服务以及与 AI 能力的集成。Twenty 后端采用模块化架构设计，支持自托管部署和云端服务两种模式，为企业用户提供灵活的 CRM 解决方案。

后端服务位于 `packages/twenty-server/src` 目录下，采用 TypeScript 开发，具备良好的类型安全性和代码可维护性。系统核心功能围绕 **Companies（公司）**、**People（联系人）**、**Opportunities（商机）**、**Activities（活动）** 等 CRM 实体展开，通过统一的 GraphQL API 向前端和其他客户端提供服务。

## 技术栈概览

Twenty 后端采用现代化的技术栈构建，确保系统具备高性能、可扩展性和易维护性：

| 技术类别 | 技术选型 | 说明 |
|---------|---------|------|
| 运行时 | Node.js / Deno | 支持服务器端执行 |
| 语言 | TypeScript | 类型安全的开发体验 |
| 框架 | NestJS | 模块化的企业级框架 |
| API | GraphQL | 灵活的数据查询接口 |
| 数据库 | PostgreSQL | 关系型数据存储 |
| ORM | TypeORM | 数据库对象关系映射 |
| 认证 | JWT | 无状态身份验证 |
| 缓存 | Redis | 会话和数据缓存 |

## 模块化架构

Twenty 后端采用 **模块化架构（Module-based Architecture）**，每个功能领域都封装在独立的模块中。这种设计模式确保了代码的**高内聚、低耦合**，便于团队协作开发和功能扩展。

### 核心模块结构

```mermaid
graph TD
    A[twenty-server] --> B[modules]
    A --> C[core]
    A --> D[database]
    A --> E[graphql]
    
    B --> B1[companies]
    B --> B2[people]
    B --> B3[opportunities]
    B --> B4[activities]
    B --> B5[calendar]
    B --> B6[ai]
    B --> B7[messaging]
    
    C --> C1[auth]
    C --> C2[config]
    C --> C3[utils]
    
    D --> D1[migrations]
    D --> D2[seeds]
```

核心模块位于 `packages/twenty-server/src/modules` 目录下，每个子模块通常包含以下结构：

```
modules/[module-name]/
├── resolvers/       # GraphQL 解析器
├── services/        # 业务逻辑服务
├── repositories/    # 数据访问层
├── entities/        # 数据库实体定义
├── dto/            # 数据传输对象
└── tests/          # 单元测试
```

## GraphQL API 层

Twenty 通过 GraphQL 提供统一的数据接口，前端和其他客户端可以通过灵活的查询语法获取所需数据。GraphQL 层负责处理客户端请求的解析、权限验证和响应格式化。

### API 端点结构

```mermaid
graph LR
    A[Client] -->|GraphQL Query/Mutation| B[GraphQL Server]
    B --> C[Resolver Layer]
    C --> D[Service Layer]
    D --> E[Repository Layer]
    E --> F[(PostgreSQL)]
    
    G[Auth Service] -->|JWT Validation| B
    H[Cache Layer] -->|Redis Cache| D
```

### 查询示例

```graphql
query GetCompaniesWithOpportunities {
  findManyCompany(
    where: { deletedAt: { equals: null } }
    orderBy: { createdAt: Desc }
    take: 10
  ) {
    id
    name
    domain
    opportunities {
      id
      amount
      stage
    }
  }
}
```

GraphQL API 支持以下主要操作：

| 操作类型 | 说明 | 示例 |
|---------|------|------|
| Query | 数据查询 | 获取公司列表、联系人详情 |
| Mutation | 数据变更 | 创建商机、更新联系人 |
| Subscription | 实时推送 | 任务状态变更通知 |

## 数据模型

Twenty 后端定义了丰富的 CRM 数据模型，涵盖企业运营的各个方面。核心实体通过 TypeORM 注解与数据库表映射。

### 主要实体关系

```mermaid
erDiagram
    COMPANY ||--o{ PERSON : has
    COMPANY ||--o{ OPPORTUNITY : manages
    PERSON ||--o{ ACTIVITY : performs
    OPPORTUNITY ||--o{ ACTIVITY : generates
    USER ||--o{ ACTIVITY : owns
    USER ||--o{ COMPANY : assigns
```

### 核心实体说明

| 实体名称 | 说明 | 主要字段 |
|---------|------|---------|
| Company | 公司/组织 | name, domain, employees, revenue |
| Person | 联系人 | name, email, phone, companyId |
| Opportunity | 商机 | name, amount, stage, probability |
| Activity | 活动记录 | type, title, body, dueAt |
| User | 系统用户 | email, name, role, workspace |
| Workspace | 工作空间 | name, logo, settings |

## 认证与授权

Twenty 后端采用 **JWT（JSON Web Token）** 实现无状态身份验证，用户登录后获取 token，后续请求通过 token 验证用户身份。

### 认证流程

```mermaid
sequenceDiagram
    participant Client
    participant Server
    participant Database
    
    Client->>Server: POST /auth/login (email, password)
    Server->>Database: 验证用户凭据
    Database-->>Server: 用户数据
    Server->>Server: 生成 JWT Token
    Server-->>Client: { accessToken, refreshToken }
    
    Client->>Server: GET /graphql (Authorization: Bearer <token>)
    Server->>Server: 验证 Token
    Server-->>Client: 请求的数据
```

### 权限控制

系统支持基于角色的访问控制（RBAC），不同角色拥有不同的数据操作权限：

| 角色 | 数据访问 | 操作权限 |
|-----|---------|---------|
| Admin | 全部数据 | 完全控制 |
| Member | 分配的数据 | 创建、更新、查看 |
| Viewer | 分配的数据 | 仅查看 |

## 移动端支持与 SDK

Twenty 提供 `twenty-sdk` 作为构建第三方应用的基础，支持开发者基于 Twenty CRM 构建自定义应用。通过官方提供的 `create-twenty-app` CLI 工具，开发者可以快速初始化项目。

```bash
npx create-twenty-app@latest my-twenty-app
cd my-twenty-app
yarn twenty dev
```

SDK 负责处理以下功能：

- GraphQL API 通信封装
- 身份验证流程管理
- 数据缓存与同步
- 离线模式支持

## 企业部署与激活

对于企业客户，Twenty 提供自托管部署方案。企业版用户可以通过许可证密钥激活系统，实现完全的数据控制和定制化需求。

### 激活流程

```mermaid
graph TD
    A[购买企业许可证] --> B[获取许可证密钥]
    B --> C[部署 Twenty 实例]
    C --> D[激活页面配置密钥]
    D --> E{验证密钥}
    E -->|成功| F[启用企业功能]
    E -->|失败| G[检查密钥有效性]
    G --> D
```

激活相关的前端页面位于 `packages/twenty-website-new/src/app/[locale]/enterprise/activate/page.tsx`，使用 `Suspense` 和错误边界组件确保用户体验。

## 数据库设计

Twenty 使用 PostgreSQL 作为主数据库，通过 TypeORM 实现对象关系映射，支持数据库迁移和种子数据管理。

### 数据库目录结构

```
packages/twenty-server/src/database/
├── migrations/          # 数据库迁移脚本
├── seeds/              # 初始化种子数据
└── typeorm/            # 数据库配置
```

### 迁移管理

系统支持数据库版本控制，通过迁移脚本确保数据库结构与代码版本同步：

```bash
# 运行迁移
yarn database:migrate

# 回滚迁移
yarn database:rollback

# 生成新迁移
yarn database:generate --name=add_new_field
```

## 配置管理

Twenty 后端支持灵活的环境配置，通过环境变量和配置文件管理不同部署环境的参数。

### 配置项说明

| 配置类别 | 环境变量 | 说明 |
|---------|---------|------|
| 数据库 | DATABASE_URL | PostgreSQL 连接字符串 |
| 缓存 | REDIS_URL | Redis 连接地址 |
| 认证 | JWT_SECRET | Token 签名密钥 |
| AI | OPENAI_API_KEY | AI 服务 API 密钥 |
| 邮件 | SMTP_HOST | 邮件服务器地址 |

## 开发贡献指南

开发者可以通过以下方式参与 Twenty 后端开发：

1. **本地开发环境**：参考 `packages/twenty-docs/developers/contribute/capabilities/backend-development` 文档
2. **代码规范**：遵循项目定义的 ESLint 和 Prettier 配置
3. **测试覆盖**：新增功能需包含对应的单元测试和集成测试
4. **提交规范**：使用 Conventional Commits 格式描述变更

## 扩展能力

Twenty 后端设计支持多种扩展方式：

- **自定义对象**：创建符合业务需求的 CRM 实体
- **工作流自动化**：定义触发器和自动化动作
- **API 扩展**：通过 Apollo Federation 集成外部服务
- **Webhook**：与外部系统的事件集成

## 总结

Twenty 的后端架构采用现代化的模块化设计，通过 GraphQL API 提供灵活的数据接口，支持企业级 CRM 功能的实现。系统具备良好的可扩展性，支持自托管和云端两种部署模式，为不同规模的企业提供可靠的 CRM 解决方案。

---

<a id='page-database-models'></a>

## 数据模型

### 相关页面

相关主题：[后端架构](#page-server-architecture), [Activities活动模块](#page-activities-module)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/twenty-server/src/engine/workspace-manager/twenty-standard-application/utils/field-metadata/compute-note-target-standard-flat-field-metadata.util.ts](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/engine/workspace-manager/twenty-standard-application/utils/field-metadata/compute-note-target-standard-flat-field-metadata.util.ts)
- [packages/twenty-server/src/engine/workspace-manager/twenty-standard-application/utils/field-metadata/compute-blocklist-standard-flat-field-metadata.util.ts](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/engine/workspace-manager/twenty-standard-application/utils/field-metadata/compute-blocklist-standard-flat-field-metadata.util.ts)
- [packages/twenty-server/src/engine/workspace-manager/twenty-standard-application/utils/object-metadata/create-standard-flat-object-metadata.util.ts](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/engine/workspace-manager/twenty-standard-application/utils/object-metadata/create-standard-flat-object-metadata.util.ts)
- [packages/twenty-front/src/pages/onboarding/CreateWorkspace.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/pages/onboarding/CreateWorkspace.tsx)
</details>

# 数据模型

## 概述

Twenty 的数据模型是一个基于元数据驱动（Metadata-Driven）的动态数据架构，它允许用户在不修改代码的情况下自定义数据对象、字段和关系。系统采用 Prisma ORM 作为底层数据库抽象，并通过标准应用层（Twenty Standard Application）定义一组开箱即用的标准对象。

数据模型的核心设计理念：

- **对象（Object）**：代表业务实体，如 Company、Person、Opportunity 等
- **字段（Field）**：描述对象的属性，包含类型、默认值、验证规则等元信息
- **关系（Relation）**：定义对象之间的关联，支持一对一、一对多、多对多
- **工作区隔离**：每个工作区拥有独立的数据模型实例，实现多租户隔离

## 核心组件

### 标准对象（Standard Objects）

标准对象是 Twenty 内置的业务实体，涵盖 CRM 核心场景：

| 对象名称 | 标识符 | 描述 | 标签标识字段 |
|---------|--------|------|-------------|
| Company | company | 公司/组织 | name |
| Person | person | 个人联系人 | name |
| Opportunity | opportunity | 销售机会 | name |
| Note | note | 笔记 | title |
| NoteTarget | noteTarget | 笔记关联目标 | - |
| Message | message | 消息 | subject |
| MessageThread | messageThread | 消息线程 | subject |
| Blocklist | blocklist | 黑名单 | - |

### 标准字段（Standard Fields）

每个对象都包含一组标准字段，继承自 `BaseWorkspaceEntity` 基类：

| 字段名 | 类型 | 说明 | 系统字段 |
|--------|------|------|----------|
| id | UUID | 全局唯一标识 | 是 |
| createdAt | DATE_TIME | 创建时间 | 是 |
| updatedAt | DATE_TIME | 最后更新时间 | 是 |
| deletedAt | DATE_TIME | 软删除时间 | 是 |

资料来源：[compute-note-target-standard-flat-field-metadata.util.ts:11-49]()

### 字段类型（FieldMetadataType）

系统支持多种字段类型：

| 类型标识 | 说明 | 是否支持默认值 |
|---------|------|---------------|
| UUID | 通用唯一标识符 | 支持（`uuid`） |
| DATE_TIME | 日期时间 | 支持（`now`） |
| TEXT | 文本 | 支持 |
| NUMBER | 数字 | 支持 |
| BOOLEAN | 布尔值 | 支持 |
| CURRENCY | 货币 | 支持 |
| RELATION | 关系 | 不支持 |

## 元数据计算机制

### 对象元数据创建

标准对象元数据通过 `createStandardObjectFlatMetadata` 工具函数创建：

```typescript
createStandardObjectFlatMetadata({
  objectName: 'messageThread',
  dependencyFlatEntityMaps,
  context: {
    universalIdentifier: STANDARD_OBJECTS.messageThread.universalIdentifier,
    nameSingular: 'messageThread',
    namePlural: 'messageThreads',
    labelSingular: i18nLabel(msg`Message Thread`),
    labelPlural: i18nLabel(msg`Message Threads`),
    icon: 'IconMessage',
    isSystem: true,
    isAuditLogged: false,
    labelIdentifierFieldMetadataName: 'subject',
  },
  workspaceId,
  standardObjectMetadataRelatedEntityIds,
  twentyStandardApplicationId,
  now,
})
```

资料来源：[create-standard-flat-object-metadata.util.ts:120-145]()

### 字段元数据计算

字段元数据通过专用的计算工具生成。以 `noteTarget` 对象为例：

```typescript
createStandardFieldFlatMetadata({
  objectName,
  workspaceId,
  context: {
    fieldName: 'createdAt',
    type: FieldMetadataType.DATE_TIME,
    label: i18nLabel(msg`Creation date`),
    description: i18nLabel(msg`Creation date`),
    icon: 'IconCalendar',
    isSystem: true,
    isNullable: false,
    isUIReadOnly: true,
    defaultValue: 'now',
    settings: {
      displayFormat: DateDisplayFormat.RELATIVE,
    },
  },
  standardObjectMetadataRelatedEntityIds,
  dependencyFlatEntityMaps,
  twentyStandardApplicationId,
  now,
})
```

资料来源：[compute-note-target-standard-flat-field-metadata.util.ts:25-55]()

## 工作区数据模型初始化

当用户创建新工作区时，系统执行三步初始化流程：

```mermaid
graph TD
    A[用户提交创建工作区] --> B[Step 1: 设置数据库]
    B --> C[Step 2: 创建数据模型]
    C --> D[Step 3: 预填充工作区数据]
    D --> E[工作区就绪]
```

资料来源：[CreateWorkspace.tsx:1-50]()

### 初始化步骤说明

| 步骤 | 标识符 | 用户提示文案 |
|------|--------|-------------|
| 1 | Step1 | Setting up your database... |
| 2 | Step2 | Creating your data model... |
| 3 | Step3 | Prefilling your workspace data... |

```tsx
{pendingCreationLoaderStep === PendingCreationLoaderStep.Step1 && (
  <SubTitle>
    <Trans>Setting up your database...</Trans>
  </SubTitle>
)}
{pendingCreationLoaderStep === PendingCreationLoaderStep.Step2 && (
  <SubTitle>
    <Trans>Creating your data model...</Trans>
  </SubTitle>
)}
{pendingCreationLoaderStep === PendingCreationLoaderStep.Step3 && (
  <SubTitle>
    <Trans>Prefilling your workspace data...</Trans>
  </SubTitle>
)}
```

资料来源：[CreateWorkspace.tsx:35-48]()

## 数据模型架构图

```mermaid
graph TB
    subgraph 工作区层
        WM[Workspace Manager]
        SM[Standard Metadata]
    end
    
    subgraph 对象层
        CO[Company]
        PE[Person]
        OP[Opportunity]
        NO[Note]
        NOB[NoteTarget]
    end
    
    subgraph 字段层
        ID[BaseFields<br/>id, createdAt, updatedAt]
        CF[Custom Fields]
        RF[Relation Fields]
    end
    
    subgraph 存储层
        PR[Prisma ORM]
        DB[(PostgreSQL)]
    end
    
    WM --> SM
    SM --> CO
    SM --> PE
    SM --> OP
    SM --> NO
    NO --> NOB
    
    CO --> ID
    PE --> ID
    CO --> CF
    PE --> CF
    CO --> RF
    PE --> RF
    
    PR --> DB
```

## 字段属性配置

### 系统字段标记

| 属性 | 类型 | 说明 |
|------|------|------|
| isSystem | boolean | 是否为系统字段（不可删除） |
| isNullable | boolean | 是否允许为空 |
| isUIReadOnly | boolean | UI 是否只读 |
| isAuditLogged | boolean | 是否记录审计日志 |

### 日期字段显示格式

```typescript
settings: {
  displayFormat: DateDisplayFormat.RELATIVE,
}
```

支持的显示格式：

| 格式 | 说明 |
|------|------|
| DateDisplayFormat.RELATIVE | 相对时间（1小时前） |
| DateDisplayFormat.DATE_ONLY | 仅日期 |
| DateDisplayFormat.DATE_TIME | 日期时间 |

资料来源：[compute-blocklist-standard-flat-field-metadata.util.ts:25-60]()

## 依赖管理

数据模型采用依赖驱动（Dependency-Driven）的初始化机制。对象之间的依赖关系通过 `dependencyFlatEntityMaps` 传递：

```typescript
type FlatFieldMetadata = {
  id: string;
  objectName: string;
  fieldName: string;
  type: FieldMetadataType;
  workspaceId: string;
  isSystem: boolean;
  isNullable: boolean;
  defaultValue: string | null;
};
```

依赖计算确保父对象先于子对象创建，保证数据完整性。

## 总结

Twenty 的数据模型采用元数据驱动的设计，通过以下核心机制实现灵活性：

1. **标准对象层**：提供开箱即用的 CRM 实体
2. **字段元数据层**：支持多种类型和丰富配置
3. **工作区隔离**：确保多租户数据安全
4. **依赖解析**：保证对象创建顺序正确

该架构允许开发者在不修改核心代码的前提下扩展业务实体，同时通过 Prisma 抽象保证数据库层面的类型安全和迁移管理。

---

<a id='page-activities-module'></a>

## Activities活动模块

### 相关页面

相关主题：[前端架构](#page-frontend-architecture), [Views与Pipelines](#page-views-pipelines), [数据模型](#page-database-models)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/twenty-front/src/modules/activities](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/activities)
- [packages/twenty-front/src/modules/activities/emails](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/activities/emails)
- [packages/twenty-front/src/modules/activities/tasks](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/activities/tasks)
- [packages/twenty-front/src/modules/activities/calendar](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/activities/calendar)
- [packages/twenty-front/src/modules/activities/types/ActivityForEditor.ts](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/activities/types/ActivityForEditor.ts)
- [packages/twenty-website-new/src/sections/Feature/visuals/EmailsVisual.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/sections/Feature/visuals/EmailsVisual.tsx)
- [packages/twenty-website-new/src/sections/Feature/visuals/TasksVisual.tsx](https://github.com/twentyhq/twenty/blob/main/packages/twenty-website-new/src/sections/Feature/visuals/TasksVisual.tsx)

</details>

# Activities活动模块

## 概述

Activities活动模块是Twenty CRM系统中用于管理用户日常业务活动的核心功能模块。该模块涵盖了任务的创建与管理、便笺的记录以及电子邮件线程的查看等关键功能。Activities模块作为Twenty前端架构的重要组成部分，为用户提供了统一的交互界面来处理与客户关系相关的各类活动数据。

Activities模块的设计理念是将分散的业务活动统一到一个集中的管理平台，使用户能够在单一界面内完成从任务分配、进度跟踪到沟通记录的全流程操作。该模块与其他业务对象（如联系人、公司、交易等）紧密集成，确保了数据的关联性和可追溯性。

## 模块架构

### 目录结构

Activities模块位于`packages/twenty-front/src/modules/activities`目录下，采用功能分组的组织方式：

```
activities/
├── types/                    # 类型定义
│   └── ActivityForEditor.ts  # 编辑器活动类型
├── emails/                   # 邮件相关组件
├── tasks/                    # 任务相关组件
└── calendar/                 # 日历相关组件
```

### 核心类型定义

Activities模块的核心类型定义位于`ActivityForEditor.ts`文件中，定义了用于编辑器场景的活动数据结构：

```typescript
import { type Note } from '@/activities/types/Note';
import { type Task } from '@/activities/types/Task';

export type ActivityForEditor = Partial<Task | Note> &
  Partial<Pick<Task, 'status' | 'dueAt' | 'assignee' | 'taskTargets'>> &
  Partial<Pick<Note, 'noteTargets'>>;
```

这个联合类型的设计允许编辑器同时处理Task和Note两种活动类型，并通过`Partial`和`Pick`工具类型精确选择所需的字段，确保了类型系统的灵活性和安全性。

## 功能模块详解

### 任务模块 (Tasks)

任务模块负责管理和展示用户创建的业务任务。从视觉组件`TasksVisual.tsx`的实现可以看出，任务系统包含以下核心要素：

| 组件属性 | 说明 |
|---------|------|
| `task` | 任务描述文本 |
| `completed` | 任务完成状态 |
| `dueAt` | 任务截止日期 |
| `assignee` | 任务负责人 |
| `taskTargets` | 任务关联目标 |
| `status` | 任务状态 |

任务在界面上以列表形式展示，每个任务项包含完成状态指示器、任务名称和关联的时间戳。用户可以通过点击完成状态指示器来切换任务的完成状态，界面会通过删除线样式（`data-strikethrough`）来直观展示已完成的任务。

### 邮件模块 (Emails)

邮件模块提供了邮件线程的查看和管理功能。从`EmailsVisual.tsx`组件的实现来看，邮件系统包含以下结构：

```typescript
type EmailsVisualProps = {
  active: boolean;
};

export function EmailsVisual({ active: _active }: EmailsVisualProps) {
  const [openEmail, setOpenEmail] = useState<number | null>(null);
  // ...
}
```

邮件界面采用标签页式导航设计，包含多个邮件夹选项。每个邮件项展示发件人头像、发件人姓名、邮件主题和时间戳。点击邮件后可以展开查看完整的邮件内容，包括邮件线程中的所有消息记录。

邮件组件的核心数据结构包括：

- **DetailHeader**：邮件头部区域，显示主题和返回按钮
- **DetailSenderRow**：发件人信息行，包含头像、名称和时间
- **DetailContent**：邮件正文内容
- **ThreadMessage**：线程消息组件

### 日历模块 (Calendar)

日历模块用于展示和安排与活动相关的时间信息。该模块与任务模块深度集成，支持基于截止日期的时间视图展示。

## 数据流与状态管理

Activities模块采用了现代化的状态管理模式，组件内部使用React Hooks管理本地状态。以下是典型的状态管理模式：

```mermaid
graph TD
    A[用户操作] --> B[组件状态更新]
    B --> C{状态类型判断}
    C -->|完成状态| D[UI渲染更新]
    C -->|邮件操作| E[邮件列表更新]
    C -->|任务操作| F[任务列表更新]
    D --> G[持久化存储]
    E --> G
    F --> G
```

### 状态管理要点

Activities模块中的状态管理包含以下几个关键方面：

1. **本地状态管理**：使用`useState`管理组件级别的状态，如邮件展开状态
2. **条件渲染**：根据状态值决定UI展示内容，如根据`openEmail === null`判断显示邮件列表还是详情
3. **时间控制**：支持时间戳的展示和格式化

## 视觉展示组件

Twenty网站营销页面中的Features模块提供了丰富的可视化演示，展示了Activities功能在实际应用场景中的表现。

### 任务可视化

`TasksVisual.tsx`组件展示了任务列表的交互效果：

- 使用`ActivityRow`作为单个任务行的容器
- 使用`TaskCircleEl`展示完成状态指示器
- 使用`ActivityBody`包裹任务主体内容
- 使用`Timestamp`组件显示任务关联时间

### 邮件可视化

`EmailsVisual.tsx`组件模拟了完整的邮件客户端界面：

- 使用`TabBar`展示邮件分类标签
- 使用`InboxHeader`展示收件箱头部
- 使用`DetailHeader`和`DetailBody`构建邮件详情视图
- 支持邮件线程的展开和折叠

## 组件关联图

```mermaid
graph LR
    A[Activities模块] --> B[Task任务]
    A --> C[Note便笺]
    A --> D[Email邮件]
    A --> E[Calendar日历]
    B --> F[status]
    B --> G[dueAt]
    B --> H[assignee]
    B --> I[taskTargets]
    C --> J[noteTargets]
    D --> K[subject]
    D --> L[thread]
```

## 类型安全设计

Activities模块在TypeScript类型安全方面做了精心设计。`ActivityForEditor`类型采用了以下设计模式：

1. **联合类型**：使用`Task | Note`表示活动可以是任务或便笺
2. **交叉类型**：通过`&`操作符合并多个类型约束
3. **部分选择**：使用`Partial<Pick<...>>`精确选择需要的字段子集

这种设计模式的优势在于：
- 提供了编译时类型检查
- 支持灵活的数据组合
- 便于扩展新的活动类型

## 与后端标准对象的关联

Activities模块与后端的数据模型紧密对应。根据服务端代码结构，系统定义了一系列标准对象来支撑活动功能的实现：

| 后端对象 | 前端类型 | 说明 |
|---------|---------|------|
| messageThread | Email Thread | 邮件会话线程 |
| message | Email Message | 单条邮件消息 |
| task | Task | 业务任务 |
| note | Note | 便笺记录 |

这些标准对象定义了系统级别的活动元数据，包括对象名称、标签、图标等配置信息。

## 总结

Activities活动模块是Twenty CRM系统中连接用户日常业务操作与系统数据管理的核心桥梁。通过任务、便笺、邮件和日历四个子模块的协同工作，该模块为用户提供了完整的活动管理能力。

模块的设计遵循了现代前端开发的最佳实践，包括：
- 清晰的类型定义和类型安全保证
- 模块化的组件结构
- 灵活的状态管理方案
- 与后端标准对象模型的完整对应

这些设计使得Activities模块能够有效支撑企业的客户关系管理需求，同时保持了代码的可维护性和可扩展性。

---

<a id='page-views-pipelines'></a>

## Views与Pipelines

### 相关页面

相关主题：[Activities活动模块](#page-activities-module), [前端架构](#page-frontend-architecture)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/twenty-front/src/modules/views](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/views)
- [packages/twenty-front/src/modules/pipelines](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/pipelines)
- [packages/twenty-docs/user-guide/views-pipelines](https://github.com/twentyhq/twenty/blob/main/packages/twenty-docs/user-guide/views-pipelines)
- [packages/twenty-front/src/modules/views/states](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/views/states)
- [packages/twenty-front/src/modules/pipelines/states](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/pipelines/states)
- [packages/twenty-front/src/modules/views/hooks](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/views/hooks)
- [packages/twenty-front/src/modules/pipelines/hooks](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/pipelines/hooks)
- [packages/twenty-front/src/modules/views/components](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/views/components)
- [packages/twenty-front/src/modules/pipelines/components](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/pipelines/components)
</details>

# Views与Pipelines

## 概述

Views（视图）和 Pipelines（管道）是 Twenty CRM 中两个核心的数据展示与业务流程管理模块。它们共同构成了系统处理和组织工作流数据的基础架构，使企业能够灵活地自定义数据展示方式和管理销售/业务管道流程。

**Views** 负责定义数据列表的展示方式，包括字段配置、排序规则、筛选条件和显示布局等。**Pipelines** 则专注于管理业务流程管道，如销售管道中的阶段流转、机会追踪和自动化工作流。

资料来源：[packages/twenty-front/src/modules/views](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/views)
资料来源：[packages/twenty-front/src/modules/pipelines](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/pipelines)

## 架构设计

### 模块层级结构

Twenty 采用模块化架构设计，Views 和 Pipelines 作为独立的功能模块存在。以下是整体架构关系：

```mermaid
graph TD
    A[Twenty Frontend] --> B[Views 模块]
    A --> C[Pipelines 模块]
    B --> D[States 状态管理]
    B --> E[Hooks 自定义钩子]
    B --> F[Components 组件]
    C --> G[States 状态管理]
    C --> H[Hooks 自定义钩子]
    C --> I[Components 组件]
    D --> J[recoil 状态Atom]
    G --> J
```

### Views 与 Pipelines 的关系

Views 和 Pipelines 存在紧密的关联关系。Pipeline 视图本质上是一种特殊的 Views 实现，专门用于展示管道阶段和卡片式布局。

```mermaid
graph TD
    A[View] -->|继承| B[BaseView]
    A -->|扩展| C[PipelineView]
    C -->|包含| D[PipelineStages]
    C -->|包含| E[PipelineSteps]
    C -->|包含| F[Opportunities]
    D -->|关联| E
```

资料来源：[packages/twenty-docs/user-guide/views-pipelines](https://github.com/twentyhq/twenty/blob/main/packages/twenty-docs/user-guide/views-pipelines)

## Views 模块详解

### 模块结构

Views 模块位于 `packages/twenty-front/src/modules/views/`，包含以下核心子目录：

| 子目录 | 功能说明 |
|--------|----------|
| `states/` | Recoil 状态定义，包含视图配置的 Atom |
| `hooks/` | 自定义 React Hooks，提供视图操作接口 |
| `components/` | 视图相关 UI 组件 |
| `types/` | TypeScript 类型定义 |
| `utils/` | 视图工具函数 |

资料来源：[packages/twenty-front/src/modules/views](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/views)

### 状态管理

Views 模块使用 Recoil 进行状态管理，主要的状态 Atom 包括：

```typescript
// 视图配置状态
viewIdState        // 当前视图ID
viewSortsState     // 排序规则
viewFiltersState   // 筛选条件
viewFieldsState    // 字段配置
viewkanbanHideState // 看板隐藏状态
```

这些状态通过 Selector 进行派生计算，实现视图配置的响应式更新。

资料来源：[packages/twenty-front/src/modules/views/states](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/views/states)

### 核心 Hooks

Views 模块提供了多个自定义 Hooks 用于视图操作：

| Hook 名称 | 功能 |
|-----------|------|
| `useViews` | 获取视图列表和当前视图 |
| `useView` | 单个视图的 CRUD 操作 |
| `useViewSorts` | 排序规则管理 |
| `useViewFilters` | 筛选条件管理 |
| `useViewFields` | 字段配置管理 |
| `useUpdateViewSorts` | 更新排序规则 |
| `useUpdateViewFilters` | 更新筛选条件 |

资料来源：[packages/twenty-front/src/modules/views/hooks](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/views/hooks)

### 视图类型

系统支持多种视图类型，每种类型有不同的展示方式和配置选项：

| 视图类型 | 标识符 | 描述 |
|----------|--------|------|
| 列表视图 | `Table` | 表格形式展示数据，支持列配置 |
| 看板视图 | `Kanban` | 卡片分组展示，按阶段/字段分组 |
| 画廊视图 | `Gallery` | 卡片网格展示，适合媒体内容 |
| 时间线视图 | `Timeline` | 时间轴形式展示 |

## Pipelines 模块详解

### 模块结构

Pipelines 模块位于 `packages/twenty-front/src/modules/pipelines/`，是 Views 模块在业务管道场景下的扩展实现：

| 子目录 | 功能说明 |
|--------|----------|
| `states/` | 管道相关状态定义 |
| `hooks/` | 管道操作的自定义钩子 |
| `components/` | 管道展示组件（看板、卡片等） |
| `types/` | 管道相关类型定义 |
| `utils/` | 管道工具函数 |

资料来源：[packages/twenty-front/src/modules/pipelines](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/pipelines)

### 管道数据模型

```mermaid
classDiagram
    class Pipeline {
        +id: string
        +name: string
        +icon: string
        +stages: PipelineStage[]
    }
    class PipelineStage {
        +id: string
        +name: string
        +color: string
        +position: number
        +opportunities: Opportunity[]
    }
    class Opportunity {
        +id: string
        +title: string
        +companyId: string
        +pipelineStageId: string
        +amount: number
        +probability: number
    }
    
    Pipeline "1" *-- "n" PipelineStage
    PipelineStage "1" *-- "n" Opportunity
```

### 状态管理

Pipelines 模块的状态管理基于 Recoil，主要包括：

```typescript
// 管道状态
pipelinesState           // 所有管道列表
currentPipelineState     // 当前选中管道
pipelineStagesState      // 管道阶段

// 机会状态
opportunitiesState       // 所有机会
opportunitiesByPipelineStageState  // 按阶段分组的机会
```

资料来源：[packages/twenty-front/src/modules/pipelines/states](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/pipelines/states)

### 核心 Hooks

| Hook 名称 | 功能 |
|-----------|------|
| `usePipelines` | 获取管道列表 |
| `usePipeline` | 单个管道操作 |
| `usePipelineStages` | 管道阶段管理 |
| `useOpportunities` | 机会管理 |
| `useOpportunity` | 单个机会 CRUD |
| `useUpdatePipelineStage` | 更新阶段信息 |
| `useUpdateOpportunity` | 更新机会信息 |

资料来源：[packages/twenty-front/src/modules/pipelines/hooks](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/pipelines/hooks)

## 数据流与工作流程

### 视图数据加载流程

```mermaid
sequenceDiagram
    participant U as 用户
    participant C as Component
    participant H as Hook
    participant S as State
    participant A as API
    
    U->>C: 选择视图
    C->>H: useView(viewId)
    H->>S: 读取 viewIdState
    S-->>H: 返回视图配置
    H->>A: 请求视图数据
    A-->>H: 返回记录列表
    H->>S: 更新 viewDataState
    S-->>C: 触发重新渲染
    C-->>U: 展示视图数据
```

### 管道阶段流转

```mermaid
graph LR
    A[新建机会] --> B[资格筛选]
    B --> C[需求分析]
    C --> D[提案报价]
    D --> E[谈判审核]
    E --> F[成交]
    E --> G[输单]
    
    style A fill:#e1f5fe
    style F fill:#c8e6c9
    style G fill:#ffcdd2
```

## 组件系统

### Views 组件

Views 模块的组件位于 `packages/twenty-front/src/modules/views/components/`，主要组件包括：

| 组件 | 用途 |
|------|------|
| `ViewBar` | 视图顶部导航栏 |
| `ViewHeader` | 视图标题和操作按钮 |
| `ViewFieldsVisibilityDropdown` | 字段显示/隐藏控制 |
| `ViewSortDropdown` | 排序规则配置 |
| `ViewFiltersDropdown` | 筛选条件配置 |
| `Table` | 表格视图组件 |
| `Board` | 看板视图组件 |

资料来源：[packages/twenty-front/src/modules/views/components](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/views/components)

### Pipelines 组件

Pipelines 模块的组件位于 `packages/twenty-front/src/modules/pipelines/components/`：

| 组件 | 用途 |
|------|------|
| `PipelineView` | 管道主视图容器 |
| `PipelineBoard` | 看板式管道展示 |
| `PipelineStageColumn` | 管道阶段列 |
| `PipelineCard` | 机会卡片展示 |
| `PipelineAddButton` | 添加阶段/机会按钮 |
| `PipelineProgressBar` | 管道进度条 |

资料来源：[packages/twenty-front/src/modules/pipelines/components](https://github.com/twentyhq/twenty/blob/main/packages/twenty-front/src/modules/pipelines/components)

## 配置与定制

### 视图配置项

| 配置项 | 类型 | 说明 |
|--------|------|------|
| `fields` | Field[] | 显示的字段列表及顺序 |
| `sorts` | Sort[] | 排序规则 |
| `filters` | Filter[] | 筛选条件 |
| `kanbanHide` | string[] | 看板隐藏的阶段ID |
| `kanbanGroupBy` | string | 看板分组字段 |

### 管道配置项

| 配置项 | 类型 | 说明 |
|--------|------|------|
| `name` | string | 管道名称 |
| `icon` | string | 管道图标 |
| `stages` | Stage[] | 阶段列表 |
| `stageColors` | Record | 阶段颜色映射 |

## 与其他模块的集成

Views 和 Pipelines 模块与以下模块存在集成关系：

```mermaid
graph TD
    V[Views/Pipelines] --> |使用| O[Objects 模块]
    V --> |使用| F[Fields 模块]
    V --> |使用| R[Relations 模块]
    V --> |渲染| UI[UI Components]
    O --> |提供数据模型| D[Data GraphQL]
    F --> |提供字段定义| D
```

### Objects 模块集成

Views 基于 Objects（对象）模块定义的数据模型进行数据展示。每个视图绑定到特定的对象类型，如 "Opportunity"、"Company" 或 "Person"。

### Fields 模块集成

视图的字段配置依赖于 Fields 模块的字段定义系统，支持标准字段和自定义字段的动态配置。

## 用户使用指南

### 创建新视图

1. 在对象列表页面，点击视图选择器
2. 选择"创建新视图"
3. 配置视图名称、图标和基础设置
4. 配置显示字段、排序规则和筛选条件
5. 保存视图

### 配置销售管道

1. 进入 Pipelines 设置页面
2. 创建新管道或编辑现有管道
3. 添加/编辑管道阶段
4. 为每个阶段配置颜色和图标
5. 设置阶段流转规则（如有）

资料来源：[packages/twenty-docs/user-guide/views-pipelines](https://github.com/twentyhq/twenty/blob/main/packages/twenty-docs/user-guide/views-pipelines)

## 最佳实践

### 视图优化建议

| 实践 | 说明 |
|------|------|
| 限制字段数量 | 只显示必要字段，减少渲染开销 |
| 使用索引筛选 | 在大数据集上优先使用索引字段进行筛选 |
| 合理分组 | 看板视图避免过多分组导致的性能问题 |

### 管道设计建议

| 实践 | 说明 |
|------|------|
| 阶段数量控制 | 建议 4-7 个阶段，避免过于复杂 |
| 明确流转规则 | 为每个阶段的流转定义清晰的触发条件 |
| 机会状态同步 | 确保机会状态与管道阶段保持一致 |

## 技术限制与注意事项

- 视图配置存储在服务端，切换视图需要网络请求
- 管道阶段不支持嵌套层级结构
- 大型数据集（>10000 条记录）建议使用服务端分页
- 自定义字段在视图中需要额外配置才能显示

---

<a id='page-apps-system'></a>

## Apps扩展系统

### 相关页面

相关主题：[GitHub Connector示例](#page-github-connector), [Docker部署](#page-docker-deployment)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/twenty-apps/examples/hello-world](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/examples/hello-world)
- [packages/create-twenty-app/src](https://github.com/twentyhq/twenty/blob/main/packages/create-twenty-app/src)
- [packages/twenty-client-sdk/src](https://github.com/twentyhq/twenty/blob/main/packages/twenty-client-sdk/src)
- [packages/twenty-docs/developers/extend/apps](https://github.com/twentyhq/twenty/blob/main/packages/twenty-docs/developers/extend/apps)
</details>

# Apps扩展系统

## 概述

Twenty的Apps扩展系统是一个模块化的应用扩展框架，允许开发者在Twenty CRM平台上构建和部署自定义业务应用程序。该系统采用现代化的插件架构，开发者可以创建独立的应用包，并在Twenty工作区内注册和使用这些应用。

Apps扩展系统的主要目标是：

- 提供标准化的应用开发框架
- 支持前端和后端代码的打包与分发
- 与Twenty核心功能无缝集成
- 支持应用的发现、安装和卸载流程

## 核心组件

Apps扩展系统由以下几个核心包组成：

| 包名 | 功能描述 | 位置 |
|------|----------|------|
| twenty-apps | 核心应用框架和运行时 | packages/twenty-apps |
| twenty-client-sdk | 客户端SDK，提供React hooks和UI组件 | packages/twenty-client-sdk |
| create-twenty-app | 应用脚手架工具，用于快速创建新应用 | packages/create-twenty-app |
| twenty-docs | 开发者文档和API参考 | packages/twenty-docs/developers/extend/apps |

## 应用架构

### 整体架构

```mermaid
graph TD
    A[开发者] -->|create-twenty-app| B[新建App项目]
    B --> C[实现App功能]
    C --> D[打包应用]
    D --> E[twenty-apps运行时]
    E --> F[Twenty CRM]
    G[twenty-client-sdk] --> C
```

### 应用生命周期

```mermaid
stateDiagram-v2
    [*] --> 创建: create-twenty-app
    创建 --> 开发: 编写代码
    开发 --> 调试: 本地测试
    调试 --> 打包: 构建生产版本
    打包 --> 发布: 分发应用
    发布 --> 安装: 用户安装
    安装 --> 激活: 启用功能
    激活 --> 使用: 运行中
    使用 --> 卸载: 用户卸载
    卸载 --> [*]
```

## twenty-client-sdk

客户端SDK是Apps扩展系统的前端核心，提供了构建应用UI所需的React组件和Hooks。

### 主要导出模块

SDK包位于 `packages/twenty-client-sdk/src`，包含以下主要导出：

- **React hooks**：用于数据获取、状态管理和与Twenty后端通信
- **UI组件**：可复用的Twenty风格组件
- **类型定义**：TypeScript类型和接口
- **工具函数**：常用业务逻辑封装

### 使用示例

```typescript
import { useTwentyClient } from '@twenty/client-sdk';

// 在App中使用Twenty客户端
const MyApp = () => {
  const client = useTwentyClient();
  // 通过client与Twenty后端交互
};
```

## create-twenty-app

`create-twenty-app` 是Twenty提供的命令行工具，用于快速生成新的App项目脚手架。

### 命令行接口

```bash
npx create-twenty-app@latest my-app
```

### 项目结构

新建的应用项目包含以下标准结构：

```
my-app/
├── src/
│   ├── index.tsx          # 应用入口
│   ├── App.tsx            # 主应用组件
│   └── components/       # 组件目录
├── package.json
├── twenty-app.config.ts  # 应用配置
└── tsconfig.json
```

### 应用配置

应用配置文件 `twenty-app.config.ts` 定义应用的基本信息：

| 配置项 | 类型 | 描述 |
|--------|------|------|
| name | string | 应用名称 |
| version | string | 应用版本 |
| description | string | 应用描述 |
| icon | string | 应用图标标识 |

## hello-world示例

`packages/twenty-apps/examples/hello-world` 提供了一个完整的Hello World示例，展示了Apps扩展系统的基本用法。

### 示例结构

```
hello-world/
├── src/
│   ├── index.tsx
│   └── App.tsx
├── package.json
└── twenty-app.config.ts
```

### 核心实现

示例应用演示了以下关键功能：

1. **入口点定义**：通过 `index.tsx` 导出应用主组件
2. **配置声明**：在 `package.json` 中声明应用元数据
3. **基础UI渲染**：使用SDK组件构建简单界面

## 开发流程

### 环境准备

1. 安装Node.js (v18+)
2. 安装pnpm包管理器
3. 克隆Twenty仓库

### 创建新应用

```bash
# 使用create-twenty-app创建项目
pnpm create twenty-app my-first-app

# 进入项目目录
cd my-first-app

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev
```

### 开发规范

- 使用TypeScript进行开发
- 遵循Twenty的设计系统
- 使用SDK提供的类型定义
- 通过配置文件声明应用元数据

### 打包发布

```bash
# 构建生产版本
pnpm build

# 产出物位于 dist/ 目录
```

## 与Twenty核心的集成

Apps扩展系统与Twenty CRM核心深度集成，提供以下能力：

### 数据访问

通过 `twenty-client-sdk` 访问Twenty的数据模型：

- 读取标准对象（如Company、Person、Opportunity）
- 调用GraphQL API
- 订阅实时数据更新

### UI集成

应用UI可以：

- 使用Twenty的设计组件
- 遵循Twenty的主题风格
- 在Twenty的工作区界面中渲染

### 功能扩展

开发者可以通过App扩展以下功能：

- 自定义数据展示
- 业务工作流自动化
- 第三方服务集成
- 自定义报表和仪表盘

## 最佳实践

### 性能优化

1. 使用SDK提供的缓存机制
2. 实现合理的加载状态处理
3. 避免不必要的重新渲染

### 错误处理

1. 使用try-catch包装API调用
2. 向用户展示友好的错误提示
3. 记录错误日志便于调试

### 安全性

1. 不在客户端存储敏感凭证
2. 使用Twenty后端进行敏感操作
3. 遵循最小权限原则

## 相关资源

| 资源类型 | 链接 |
|----------|------|
| 官方文档 | [Apps扩展文档](https://github.com/twentyhq/twenty/blob/main/packages/twenty-docs/developers/extend/apps) |
| 客户端SDK | [twenty-client-sdk](https://github.com/twentyhq/twenty/blob/main/packages/twenty-client-sdk/src) |
| CLI工具 | [create-twenty-app](https://github.com/twentyhq/twenty/blob/main/packages/create-twenty-app/src) |
| 示例代码 | [hello-world示例](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/examples/hello-world) |

---

<a id='page-github-connector'></a>

## GitHub Connector示例

### 相关页面

相关主题：[Apps扩展系统](#page-apps-system), [后端架构](#page-server-architecture)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/twenty-apps/community/github-connector/README.md](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/community/github-connector/README.md)
- [packages/twenty-apps/community/github-connector/src](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/community/github-connector/src)
- [packages/twenty-apps/community/github-connector/src/modules/github](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/community/github-connector/src/modules/github)
</details>

# GitHub Connector示例

## 概述

GitHub Connector 是 Twenty CRM 的一个社区应用集成模块，旨在将 GitHub 平台的数据与 Twenty CRM 系统进行深度整合。该连接器通过 GitHub App 认证机制获取授权，实现对 GitHub 仓库、Issue、Pull Request 以及 Projects (v2) 等数据的同步和展示。

## 核心功能范围

GitHub Connector 提供了以下核心能力：

| 功能模块 | 描述 |
|---------|------|
| 仓库同步 | 自动同步指定的 GitHub 仓库数据 |
| Issue 管理 | 读取和展示仓库中的 Issue 信息 |
| Pull Request 追踪 | 监控和管理 Pull Request 状态 |
| Projects v2 集成 | 支持 GitHub Projects (v2) 数据的读取 |

## 认证机制

### GitHub App 认证流程

GitHub Connector 使用 GitHub App 认证方式进行授权，这种方式相比传统的 OAuth 更适合服务器端应用。

```mermaid
sequenceDiagram
    participant Connector as GitHub Connector
    participant GitHubAPI as GitHub API
    
    Note over Connector: 初始化配置
    Connector->>GitHubAPI: 使用 App Credentials 发起请求
    GitHubAPI-->>Connector: 返回 Installation Token
    Note over Connector: Token 缓存于内存
    Connector->>GitHubAPI: 使用 Installation Token 访问资源
    GitHubAPI-->>Connector: 返回请求的数据
```

### 必需的环境变量

| 变量名 | 必需 | 说明 |
|--------|------|------|
| `GITHUB_APP_ID` | 是 | GitHub App 设置页面中的数字 App ID |
| `GITHUB_APP_PRIVATE_KEY` | 是 | PEM 格式的私钥（支持换行） |
| `GITHUB_APP_INSTALLATION_ID` | 是 | App 在组织/用户上的安装 ID |
| `GITHUB_REPOS` | 是 | 逗号分隔的仓库列表，格式为 `owner/repo` |
| `GITHUB_PROJECTS` | 否 | 逗号分隔的 GitHub Projects (v2) 列表 |

## 创建 GitHub App

要创建 GitHub App 并配置连接器，请按以下步骤操作：

1. 访问 `https://github.com/settings/apps/new` 或组织页面 `https://github.com/organizations/<org>/settings/apps/new`
2. 配置以下 **仓库权限**：

| 权限类型 | 权限级别 |
|---------|---------|
| Contents | Read |
| Issues | Read |
| Pull Requests | Read |
| Metadata | Read |
| Organization → Projects (可选) | Read |

3. 生成私钥（会下载 `.pem` 文件）
4. 在组织/用户上安装 App，安装完成后的 URL 中包含安装 ID，格式为 `.../installations/12345678`
5. 将 App ID、PEM 私钥内容和安装 ID 填入对应的环境变量

## Token 管理

GitHub Connector 实现了智能的 Token 缓存机制：

- 连接器使用 App 凭证换取短期有效的安装 Token
- Token 被缓存在内存中
- 在 Token 即将过期前自动刷新
- 所有 GitHub API 调用都通过该安装 Token 进行认证

## 架构设计

### 模块结构

```
github-connector/
├── src/
│   ├── modules/
│   │   └── github/
│   │       ├── services/        # GitHub API 服务层
│   │       ├── types/           # TypeScript 类型定义
│   │       └── utils/           # 工具函数
│   └── index.ts                 # 模块入口
└── README.md
```

### 数据流向

```mermaid
graph LR
    A[GitHub API] -->|Installation Token| B[GitHub Connector]
    B -->|同步数据| C[Twenty CRM]
    C -->|存储| D[数据库]
    
    E[用户配置] -->|环境变量| B
```

## 集成示例场景

### 场景一：团队协作数据同步

将开发团队的 GitHub 活动（Issue 分配、PR 审查状态）同步到 CRM 中的相关公司或联系人记录，便于销售团队了解技术支持情况。

### 场景二：项目管理视图

通过 GitHub Projects (v2) 集成，在 Twenty CRM 中创建与 GitHub 项目进度对齐的任务视图。

### 场景三：客户案例追踪

对于使用 Twenty CRM 的技术咨询公司，可将客户项目的 GitHub 仓库活动作为交付进度的参考指标。

## 配置示例

### 环境变量配置

```bash
# 必需配置
GITHUB_APP_ID=123456
GITHUB_APP_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQD...
-----END PRIVATE KEY-----"
GITHUB_APP_INSTALLATION_ID=12345678
GITHUB_REPOS=octocat/hello-world,octo-org/octo-repo

# 可选配置
GITHUB_PROJECTS=octo-org:1,octo-org:2
```

### 仓库列表格式

`GITHUB_REPOS` 环境变量支持以下格式：

- 单个仓库：`owner/repo`
- 多个仓库：`owner/repo1,owner/repo2,another-owner/another-repo`

## 限制与注意事项

| 注意事项 | 说明 |
|---------|------|
| 权限要求 | GitHub App 必须具有相应仓库的读取权限 |
| 速率限制 | 受 GitHub API 速率限制约束 |
| Token 有效期 | Installation Token 有时效性，Connector 自动处理刷新 |
| 私钥格式 | 支持带换行的 PEM 格式 |

## 相关资源

- GitHub App 开发文档：https://docs.github.com/en/apps
- Twenty 官方文档：https://docs.twenty.com
- GitHub Connector 源码：https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/community/github-connector

## 资料来源

- [packages/twenty-apps/community/github-connector/README.md](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/community/github-connector/README.md)

---

<a id='page-docker-deployment'></a>

## Docker部署

### 相关页面

相关主题：[后端架构](#page-server-architecture)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/twenty-docker/k8s/README.md](https://github.com/twentyhq/twenty/blob/main/packages/twenty-docker/k8s/README.md)
- [packages/twenty-docker/scripts/1-click.sh](https://github.com/twentyhq/twenty/blob/main/packages/twenty-docker/scripts/1-click.sh)
- [packages/twenty-docker/docker-compose.yml](https://github.com/twentyhq/twenty/blob/main/packages/twenty-docker/docker-compose.yml)
- [packages/twenty-docker/helm/twenty](https://github.com/twentyhq/twenty/blob/main/packages/twenty-docker/helm/twenty)
- [packages/twenty-docs/developers/self-host](https://github.com/twentyhq/twenty/blob/main/packages/twenty-docs/developers/self-host)
</details>

# Docker部署

Twenty CRM 提供多种 Docker 部署方案，支持从简单的单机部署到复杂的 Kubernetes 集群部署。本文详细介绍如何使用 Docker 技术栈在自有基础设施上部署 Twenty CRM。

## 部署方案概览

Twenty 提供以下几种部署方式：

| 部署方式 | 适用场景 | 复杂度 | 自动化程度 |
|---------|---------|-------|-----------|
| Docker Compose | 单机部署、开发环境 | 低 | 一键部署 |
| Kubernetes | 生产集群 | 高 | 支持 Terraform |
| Helm Chart | Kubernetes 命名空间 | 中高 | 可配置 |

## 环境要求

### 硬件要求

- **CPU**: 最少 2 核，推荐 4 核以上
- **内存**: 最少 4GB，推荐 8GB 以上
- **磁盘**: 最少 20GB 可用空间

### 软件要求

- Docker Engine 20.10+
- Docker Compose 2.0+
- Kubernetes 1.24+（如需 K8s 部署）
- Terraform 1.0+（可选）

## Docker Compose 部署

Docker Compose 是最简单快速的部署方式，适合单机运行或初步体验。

### 快速开始

```bash
# 克隆仓库
git clone https://github.com/twentyhq/twenty.git
cd twenty/packages/twenty-docker

# 启动所有服务
docker-compose up -d
```

### 服务架构

```mermaid
graph TD
    A[用户] --> B[NGINX反向代理]
    B --> C[Twenty Frontend]
    B --> D[Twenty Server]
    C --> E[PostgreSQL]
    D --> E
    D --> F[Redis]
    D --> G[MinIO对象存储]
```

### 环境变量配置

创建 `.env` 文件配置必要的环境变量：

```bash
# 基础配置
APP_ENV=production
RELEASE_VERSION=latest

# 数据库配置
POSTGRES_DB=twenty
POSTGRES_USER=twenty
POSTGRES_PASSWORD=your_secure_password

# 存储配置
STORAGE_S3_REGION=us-east-1
STORAGE_S3_BUCKET=twenty-storage
STORAGE_S3_ACCESS_KEY_ID=your_access_key
STORAGE_S3_SECRET_ACCESS_KEY=your_secret_key

# 认证配置
ACCESS_TOKEN_SECRET=your_access_token_secret
LOGIN_TOKEN_SECRET=your_login_token_secret
```

## 一键部署脚本

Twenty 提供 `1-click.sh` 脚本实现自动化部署。

### 脚本功能

该脚本自动完成以下步骤：

1. 环境检测与依赖验证
2. 配置文件生成
3. Docker 服务启动
4. 数据库初始化
5. 健康检查验证

### 使用方法

```bash
# 下载并执行一键部署脚本
curl -fsSL https://raw.githubusercontent.com/twentyhq/twenty/main/packages/twenty-docker/scripts/1-click.sh | bash
```

### 脚本执行流程

```mermaid
graph TD
    A[执行1-click.sh] --> B{检测Docker环境}
    B -->|缺失| C[提示安装Docker]
    B -->|存在| D[检查docker-compose]
    D --> E[生成配置文件]
    E --> F[拉取镜像]
    F --> G[启动服务]
    G --> H[健康检查]
    H -->|失败| I[回滚并报错]
    H -->|成功| J[部署完成]
```

## Kubernetes 部署

对于生产环境，推荐使用 Kubernetes 进行部署以获得更好的可扩展性和高可用性。

### 部署步骤

#### 第一步：克隆仓库

```bash
git clone https://github.com/twentyhq/twenty.git
cd twenty/packages/twenty-docker/k8s
```

#### 第二步：自定义配置文件

**重要提示**：Kubernetes 清单文件和 Terraform 配置文件需要根据实际环境进行自定义。更新占位符和配置以符合您的环境要求。

#### 第三步：使用 Terraform 部署

1. 进入 Terraform 目录：
   ```bash
   cd terraform
   ```

2. 初始化 Terraform：
   ```bash
   terraform init
   ```

3. 规划部署：
   ```bash
   terraform plan
   ```

4. 执行部署：
   ```bash
   terraform apply
   ```

#### 第三步（替代方案）：使用 Kubernetes 清单

1. 创建命名空间：
   ```bash
   kubectl create namespace twentycrm
   ```

2. 创建密钥：
   ```bash
   kubectl create secret generic -n twentycrm tokens \
     --from-literal=accessToken=changeme \
     --from-literal=loginToken="changeme" \
     --from-literal=refreshToken="changeme" \
     --from-literal=fileToken="changeme"
   ```

3. 应用清单文件：
   ```bash
   kubectl apply -f deployment.yaml
   kubectl apply -f service.yaml
   kubectl apply -f ingress.yaml
   ```

### Kubernetes 组件说明

| 组件类型 | 资源名称 | 说明 |
|---------|---------|-----|
| Deployment | twenty-server | 后端服务部署 |
| Deployment | twenty-front | 前端服务部署 |
| Service | twenty-server | 服务内部访问 |
| Service | twenty-front | 前端负载均衡 |
| Ingress | twenty-ingress | 外部流量入口 |
| Secret | tokens | 认证令牌存储 |

### Ingress 配置示例

```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: twenty-ingress
  namespace: twentycrm
spec:
  rules:
  - host: your-domain.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: twenty-front
            port:
              number: 3000
```

配置 TLS 证书：

```bash
kubectl create secret tls -n twentycrm tls-secret \
  --cert=path/to/cert.pem \
  --key=path/to/key.pem

# 使用 helm 设置 ingress TLS
helm upgrade twenty ./helm/twenty \
  --set server.ingress.tls[0].hosts[0]=$DOMAIN \
  --set server.ingress.tls[0].secretName=tls-secret
```

## Helm Chart 部署

Twenty 提供 Helm Chart 用于 Kubernetes 部署。

### 安装 Helm Chart

```bash
# 添加 Helm 仓库
helm repo add twenty https://charts.twenty.com
helm repo update

# 安装 Twenty
helm install twenty twenty/twenty \
  --namespace twentycrm \
  --create-namespace \
  --values values.yaml
```

### 配置参数

| 参数路径 | 说明 | 默认值 |
|---------|-----|-------|
| `server.replicaCount` | 服务端副本数 | 1 |
| `server.image.repository` | 镜像仓库 | twentyhq/twenty-server |
| `server.image.tag` | 镜像标签 | latest |
| `server.service.type` | 服务类型 | ClusterIP |
| `server.ingress.enabled` | 启用 Ingress | false |
| `server.ingress.host` | 域名 | - |
| `database.enabled` | 启用内嵌数据库 | true |
| `database.externalHost` | 外部数据库地址 | - |
| `storage.type` | 存储类型 | minio |
| `storage.s3.endpoint` | S3 兼容端点 | - |

## 存储配置

### MinIO 对象存储

Twenty 使用 MinIO 作为默认对象存储解决方案。

```yaml
storage:
  type: minio
  minio:
    endpoint: minio:9000
    bucket: twenty-storage
    accessKey: minioadmin
    secretKey: minioadmin
```

### 外部 S3 兼容存储

如需使用 AWS S3 或其他 S3 兼容存储：

```yaml
storage:
  type: s3
  s3:
    endpoint: https://s3.amazonaws.com
    region: us-east-1
    bucket: your-bucket
    accessKeyId: your-key
    secretAccessKey: your-secret
```

## 数据库配置

### PostgreSQL 配置

```yaml
database:
  enabled: true
  postgres:
    host: postgres
    port: 5432
    database: twenty
    username: twenty
    password: your-password
```

### 使用外部数据库

```yaml
database:
  enabled: false
  externalHost: your-db-host.com
  externalPort: 5432
  externalDatabase: twenty
  externalUsername: twenty
  externalPassword: your-password
```

## 运维管理

### 日志查看

```bash
# 查看所有服务日志
docker-compose logs -f

# 查看特定服务日志
docker-compose logs -f server

# Kubernetes 日志
kubectl logs -n twentycrm deployment/twenty-server -f
```

### 服务重启

```bash
# Docker Compose
docker-compose restart

# Kubernetes
kubectl rollout restart deployment/twenty-server -n twentycrm
```

### 数据备份

建议使用 PostgreSQL 的 `pg_dump` 工具进行数据库备份：

```bash
# 数据库备份
docker-compose exec postgres pg_dump -U twenty twenty > backup.sql

# 恢复数据
docker-compose exec -T postgres psql -U twenty twenty < backup.sql
```

## 故障排查

### 常见问题

| 问题现象 | 可能原因 | 解决方案 |
|---------|---------|---------|
| 服务启动失败 | 端口冲突 | 检查 3000、5432、9000 端口占用 |
| 数据库连接失败 | 凭据错误 | 检查环境变量中的数据库配置 |
| 镜像拉取失败 | 网络问题 | 配置 Docker 镜像加速器 |
| Ingress 无法访问 | DNS 未配置 | 确认域名解析正确 |

### 健康检查

```bash
# Docker Compose 健康检查
docker-compose ps

# Kubernetes 健康检查
kubectl get pods -n twentycrm
kubectl describe pod -n twentycrm <pod-name>
```

### 资源清理

```bash
# 停止并删除容器
docker-compose down -v

# 删除所有镜像
docker-compose down --rmi all

# Kubernetes 清理
kubectl delete namespace twentycrm
```

## 安全建议

1. **更换默认密码**：部署前务必修改所有默认密码和密钥
2. **启用 HTTPS**：生产环境必须使用 TLS 证书
3. **网络隔离**：使用 Kubernetes NetworkPolicy 限制服务间通信
4. **定期更新**：关注 Twenty 最新版本，及时更新补丁
5. **日志审计**：配置日志收集和分析系统

## 相关文档

- [本地开发环境搭建](https://docs.twenty.com/developers/contribute/capabilities/local-setup)
- [应用开发指南](https://docs.twenty.com/developers/extend/apps/getting-started)
- [Kubernetes 快速入门](../helm/twenty/QUICKSTART.md)
- [Helm Chart 详细文档](../helm/twenty/README.md)

---

---

## Doramagic 踩坑日志

项目：twentyhq/twenty

摘要：发现 31 个潜在踩坑项，其中 7 个为 high/blocking；最高优先级：安装坑 - 来源证据：Bug(UI): BlockNote Editor slash command shows nothing when no matches are found。

## 1. 安装坑 · 来源证据：Bug(UI): BlockNote Editor slash command shows nothing when no matches are found

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bug(UI): BlockNote Editor slash command shows nothing when no matches are found
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_8f7dbe9bbbcb4664b1513a32d303b9eb | https://github.com/twentyhq/twenty/issues/20625 | 来源类型 github_issue 暴露的待验证使用条件。

## 2. 安装坑 · 来源证据：Restart loop after first workspace creation on a fresh self-host install 2.4.0

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Restart loop after first workspace creation on a fresh self-host install 2.4.0
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_45aa2211a5b64bdc84ba3b47e72701ce | https://github.com/twentyhq/twenty/issues/20666 | 来源类型 github_issue 暴露的待验证使用条件。

## 3. 运行坑 · 来源证据：Cannot use the Add New Button from the list to create Tasks and Notes - Error: Should never occur, encountered unknown…

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Cannot use the Add New Button from the list to create Tasks and Notes - Error: Should never occur, encountered unknown fields name in objectMetadataItem task
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_e572dc6d35d74c9ca8d15889a5cdcb12 | https://github.com/twentyhq/twenty/issues/15800 | 来源类型 github_issue 暴露的待验证使用条件。

## 4. 运行坑 · 来源证据：On record table, relation fields, we only display 3 items even when the cell is larger

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：On record table, relation fields, we only display 3 items even when the cell is larger
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_2446ebd3b44b4378b8725f00f1d22023 | https://github.com/twentyhq/twenty/issues/12039 | 来源类型 github_issue 暴露的待验证使用条件。

## 5. 维护坑 · 来源证据：Notes not editable in People section

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Notes not editable in People section
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_594e914f1db84296ad7d08410941f4ff | https://github.com/twentyhq/twenty/issues/20288 | 来源类型 github_issue 暴露的待验证使用条件。

## 6. 维护坑 · 来源证据：Object Type translations are not applied to details panel

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Object Type translations are not applied to details panel
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_d961ff61e7ff4bfbb2740d5b00781250 | https://github.com/twentyhq/twenty/issues/19790 | 来源类型 github_issue 暴露的待验证使用条件。

## 7. 安全/权限坑 · 来源证据：Pagination broken when sorting by multiple fields when first field has duplicates (both REST and Graphql APIs)

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Pagination broken when sorting by multiple fields when first field has duplicates (both REST and Graphql APIs)
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_b5b75503f7ff4e4493c3503f86acf36b | https://github.com/twentyhq/twenty/issues/20520 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 8. 安装坑 · 失败模式：installation: Restart loop after first workspace creation on a fresh self-host install 2.4.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Restart loop after first workspace creation on a fresh self-host install 2.4.0
- 对用户的影响：Developers may fail before the first successful local run: Restart loop after first workspace creation on a fresh self-host install 2.4.0
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Restart loop after first workspace creation on a fresh self-host install 2.4.0. Context: Observed when using docker
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_bbe448d3f1b2e30e0f7697a610dcf4b1 | https://github.com/twentyhq/twenty/issues/20666 | Restart loop after first workspace creation on a fresh self-host install 2.4.0

## 9. 安装坑 · 失败模式：installation: v1.22.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v1.22.0
- 对用户的影响：Upgrade or migration may change expected behavior: v1.22.0
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.22.0. Context: Observed during installation or first-run setup.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_7102b6d7804c49862dcef507bd3213a5 | https://github.com/twentyhq/twenty/releases/tag/v1.22.4 | v1.22.0

## 10. 安装坑 · 来源证据：Configuring view fields in UI results in BUILDER_INTERNAL_SERVER_ERROR during app sync

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Configuring view fields in UI results in BUILDER_INTERNAL_SERVER_ERROR during app sync
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_1807294d92bc4e919fe1baf88520bb3c | https://github.com/twentyhq/twenty/issues/20671 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 11. 配置坑 · 失败模式：configuration: Configuring view fields in UI results in BUILDER_INTERNAL_SERVER_ERROR during app sync

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: Configuring view fields in UI results in BUILDER_INTERNAL_SERVER_ERROR during app sync
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Configuring view fields in UI results in BUILDER_INTERNAL_SERVER_ERROR during app sync
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Configuring view fields in UI results in BUILDER_INTERNAL_SERVER_ERROR during app sync. Context: Observed during version upgrade or migration.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_7fe809524bbc2f0017b2770b4cc3ece0 | https://github.com/twentyhq/twenty/issues/20671 | Configuring view fields in UI results in BUILDER_INTERNAL_SERVER_ERROR during app sync

## 12. 配置坑 · 失败模式：configuration: TypeError in RestApiService swallows internal network errors, resulting in silent 500 responses

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: TypeError in RestApiService swallows internal network errors, resulting in silent 500 responses
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: TypeError in RestApiService swallows internal network errors, resulting in silent 500 responses
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: TypeError in RestApiService swallows internal network errors, resulting in silent 500 responses. Context: Observed when using docker
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_0bfb9bb57a943450e911d804ce107cbf | https://github.com/twentyhq/twenty/issues/20136 | TypeError in RestApiService swallows internal network errors, resulting in silent 500 responses

## 13. 配置坑 · 失败模式：configuration: v1.19.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v1.19.0
- 对用户的影响：Upgrade or migration may change expected behavior: v1.19.0
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.19.0. Context: Observed during version upgrade or migration.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_15301e2ca30bc826383cea157ed32bcb | https://github.com/twentyhq/twenty/releases/tag/v1.19.0 | v1.19.0

## 14. 配置坑 · 失败模式：configuration: v2.0.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v2.0.0
- 对用户的影响：Upgrade or migration may change expected behavior: v2.0.0
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v2.0.0. Context: Observed when using docker
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_ab9b1aea9055fca76d3a881c8ee8f317 | https://github.com/twentyhq/twenty/releases/tag/v2.0.0 | v2.0.0

## 15. 配置坑 · 失败模式：configuration: v2.3.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v2.3.0
- 对用户的影响：Upgrade or migration may change expected behavior: v2.3.0
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v2.3.0. Context: Observed when using docker
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_05b61500a200d1852774253b2b09cb5f | https://github.com/twentyhq/twenty/releases/tag/v2.3.0 | v2.3.0

## 16. 配置坑 · 失败模式：configuration: v2.4.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v2.4.0
- 对用户的影响：Upgrade or migration may change expected behavior: v2.4.0
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v2.4.0. Context: Source discussion did not expose a precise runtime context.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_c37fffb0f1bdf017e6070e311b099597 | https://github.com/twentyhq/twenty/releases/tag/v2.4.0 | v2.4.0

## 17. 配置坑 · 来源证据：TypeError in RestApiService swallows internal network errors, resulting in silent 500 responses

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：TypeError in RestApiService swallows internal network errors, resulting in silent 500 responses
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_4abd78a034024d29b94e860fbcb298e6 | https://github.com/twentyhq/twenty/issues/20136 | 来源类型 github_issue 暴露的待验证使用条件。

## 18. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:572984571 | https://github.com/twentyhq/twenty | README/documentation is current enough for a first validation pass.

## 19. 运行坑 · 来源证据：Bug(UI): Currency icon not aligned properly

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Bug(UI): Currency icon not aligned properly
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_c2c473e13c324a60a1b0ba450f77fb32 | https://github.com/twentyhq/twenty/issues/20640 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 20. 维护坑 · 失败模式：migration: v1.20.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this migration risk before relying on the project: v1.20.0
- 对用户的影响：Upgrade or migration may change expected behavior: v1.20.0
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.20.0. Context: Observed during version upgrade or migration.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_b9ae97dbbd9c277df82d69cda517b768 | https://github.com/twentyhq/twenty/releases/tag/v1.20.0 | v1.20.0

## 21. 维护坑 · 失败模式：migration: v1.21.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this migration risk before relying on the project: v1.21.0
- 对用户的影响：Upgrade or migration may change expected behavior: v1.21.0
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.21.0. Context: Observed during version upgrade or migration.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_ea380ef68973d4bb1f069cd337fd42af | https://github.com/twentyhq/twenty/releases/tag/v1.21.0 | v1.21.0

## 22. 维护坑 · 失败模式：migration: v1.23.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this migration risk before relying on the project: v1.23.0
- 对用户的影响：Upgrade or migration may change expected behavior: v1.23.0
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.23.0. Context: Observed during version upgrade or migration.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_d757a9aab11c1a39bfa726eebcb7ab5e | https://github.com/twentyhq/twenty/releases/tag/v1.23.0 | v1.23.0

## 23. 维护坑 · 失败模式：migration: v2.1.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this migration risk before relying on the project: v2.1.0
- 对用户的影响：Upgrade or migration may change expected behavior: v2.1.0
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v2.1.0. Context: Observed during version upgrade or migration.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_0bb1a26151a8ea54475ab5fc8c9566c7 | https://github.com/twentyhq/twenty/releases/tag/v2.1.0 | v2.1.0

## 24. 维护坑 · 失败模式：migration: v2.2.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this migration risk before relying on the project: v2.2.0
- 对用户的影响：Upgrade or migration may change expected behavior: v2.2.0
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v2.2.0. Context: Observed during version upgrade or migration.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_9cfa053b1c1093a4e4bdfc861bc786ab | https://github.com/twentyhq/twenty/releases/tag/v2.2.0 | v2.2.0

## 25. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:572984571 | https://github.com/twentyhq/twenty | last_activity_observed missing

## 26. 安全/权限坑 · 下游验证发现风险项

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:572984571 | https://github.com/twentyhq/twenty | no_demo; severity=medium

## 27. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:572984571 | https://github.com/twentyhq/twenty | no_demo; severity=medium

## 28. 能力坑 · 失败模式：capability: Bug(UI): BlockNote Editor slash command shows nothing when no matches are found

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: Bug(UI): BlockNote Editor slash command shows nothing when no matches are found
- 对用户的影响：Developers may hit a documented source-backed failure mode: Bug(UI): BlockNote Editor slash command shows nothing when no matches are found
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Bug(UI): BlockNote Editor slash command shows nothing when no matches are found. Context: Source discussion did not expose a precise runtime context.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_494ea45b2d55fcdc06b5b89a25d3dfe0 | https://github.com/twentyhq/twenty/issues/20625 | Bug(UI): BlockNote Editor slash command shows nothing when no matches are found

## 29. 能力坑 · 失败模式：capability: Bug(UI): Currency icon not aligned properly

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: Bug(UI): Currency icon not aligned properly
- 对用户的影响：Developers may hit a documented source-backed failure mode: Bug(UI): Currency icon not aligned properly
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Bug(UI): Currency icon not aligned properly. Context: Observed when using docker
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_5b942675e057e849cb68cf3923b56dce | https://github.com/twentyhq/twenty/issues/20640 | Bug(UI): Currency icon not aligned properly

## 30. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:572984571 | https://github.com/twentyhq/twenty | issue_or_pr_quality=unknown

## 31. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:572984571 | https://github.com/twentyhq/twenty | release_recency=unknown

<!-- canonical_name: twentyhq/twenty; human_manual_source: deepwiki_human_wiki -->