snapshot of https://github.com/twentyhq/twenty.git (main, 2026-09-17; blobs > 131072B omitted)

packages/twenty-docs/l/zh/developers/contribute/capabilities/backend-development/best-practices-server.mdx

@@ -0,0 +1,22 @@
+---
+title: 最佳实践
+---
+
+本文档概述了当您在后端工作时应遵循的最佳实践。
+
+## 遵循模块化方法
+
+后端遵循模块化方法，这是使用 NestJS 的基本原则。 确保将代码分解为可重用的模块，以保持代码库的清晰和有序。
+每个模块应封装特定的功能或特性，并具有明确的范围。 这种模块化方法使关注点分离更加清晰，并消除了不必要的复杂性。
+
+## 将服务暴露以供模块使用
+
+始终创建具有明确单一职责的服务，这有助于提高代码的可读性和可维护性。 以具有描述性且一致的方式为服务命名。
+
+您还应该公开希望在其他模块中使用的服务。 通过 NestJS 强大的依赖注入系统，可以实现向其他模块公开服务，并促进组件间的松耦合。
+
+## 避免使用 `any` 类型
+
+当您将变量声明为 `any` 类型时，TypeScript 的类型检查器不会进行任何类型检查，使得可以将任何类型的值赋给该变量。 TypeScript 使用类型推断，根据值来确定变量的类型。 若声明为 `any`，TypeScript 将无法再推断其类型。 这使开发过程中难以捕捉到与类型相关的错误，导致运行时错误，使代码维护性更差，可靠性更低，且更难以被他人理解。
+
+因此，一切都应该有一个类型。 因此，如果您创建包含名字和姓氏的新对象，应该创建一个包含名字和姓氏的接口或类型，以定义您正在操作的对象的形状。

packages/twenty-docs/l/zh/developers/contribute/capabilities/backend-development/custom-objects.mdx

@@ -0,0 +1,39 @@
+---
+title: 自定义对象
+---
+
+对象是存储特定于组织的数据（记录、属性和值）的结构。 Twenty 提供标准对象和自定义对象。
+
+标准对象是为所有用户提供特定属性的内置对象。 Twenty 的标准对象示例包括“公司”和“人员”。 标准对象具有对所有 Twenty 用户可用的标准字段，如 Company.displayName。
+
+自定义对象是您可以创建的对象，用于存储专属于您组织的信息。 它们不是内置的；您可以创建和自定义自定义对象来保存标准对象不适合存储的信息。
+
+## 高级模式
+
+<div style={{textAlign: 'center'}}>
+    <img src="/images/docs/server/custom-object-schema.png" alt="高级模式" />
+</div>
+
+<br />
+
+## 工作原理
+
+自定义对象来自确定对象形状、名称和类型的元数据表。 所有这些信息都存在于元数据模式数据库中，由表组成：
+
+* **DataSource**：说明数据所在的详细信息。
+* **Object**：描述对象并链接到数据源。
+* **Field**：列出对象的字段并连接到对象。
+
+要添加自定义对象，工作空间成员将查询 /metadata API。 这将相应地更新元数据，并根据元数据计算 GraphQL 架构，将其存储在 GQL 缓存中以备后用。
+
+<div style={{textAlign: 'center'}}>
+    <img src="/images/docs/server/add-custom-objects.jpeg" alt="查询 /metadata API 以添加自定义对象" />
+</div>
+
+<br />
+
+要获取数据，流程涉及通过 /graphql 端点进行查询并通过查询解析器传递。
+
+<div style={{textAlign: 'center'}}>
+    <img src="/images/docs/server/custom-object-schema.png" alt="查询 /graphql 端点以获取数据" />
+</div>

packages/twenty-docs/l/zh/developers/contribute/capabilities/backend-development/feature-flags.mdx

@@ -0,0 +1,46 @@
+---
+title: 功能标志
+---
+
+功能标志用于隐藏实验性功能。 对于 Twenty，它们是在工作区级别设置的，而不是在用户级别。
+
+## 添加新的功能标志
+
+在 `FeatureFlagKey.ts` 中添加功能标志:
+
+```ts
+type FeatureFlagKey =
+  | 'IS_FEATURENAME_ENABLED'
+  | ...;
+```
+
+还要将其添加到 `feature-flag.entity.ts` 中的枚举：
+
+```ts
+enum FeatureFlagKeys {
+    IsFeatureNameEnabled = 'IS_FEATURENAME_ENABLED',
+    ...
+}
+```
+
+要在 **后端** 功能上应用功能标志，请使用:
+
+```ts
+@Gate({
+  featureFlag: 'IS_FEATURENAME_ENABLED',
+})
+```
+
+要在 **前端** 功能上应用功能标志，请使用:
+
+```ts
+const isFeatureNameEnabled = useIsFeatureEnabled('IS_FEATURENAME_ENABLED');
+```
+
+## 配置部署的功能标志
+
+更改 Table `core.featureFlag` 中的相应记录：
+
+| iD | 键                        | workspaceId | 值   |
+| -- | ------------------------ | ----------- | --- |
+| 随机 | `IS_FEATURENAME_ENABLED` | 工作区 ID      | `真` |

packages/twenty-docs/l/zh/developers/contribute/capabilities/backend-development/folder-architecture-server.mdx

@@ -0,0 +1,125 @@
+---
+title: 文件夹架构
+info: 详细了解我们的服务器文件夹架构
+---
+
+后端目录结构如下：
+
+```
+server
+  └───ability
+  └───constants
+  └───core
+  └───database
+  └───decorators
+  └───filters
+  └───guards
+  └───health
+  └───integrations
+  └───metadata
+  └───workspace
+  └───utils
+```
+
+## 能力
+
+定义权限并为每个实体提供处理程序。
+
+## 装饰器
+
+为增强功能在NestJS中定义自定义装饰器。
+
+有关更多详细信息，请参阅[自定义装饰器](https://docs.nestjs.com/custom-decorators)。
+
+## 过滤器
+
+包含异常过滤器，以处理可能在GraphQL端点中出现的异常。
+
+## 守卫
+
+有关更多详细信息，请参见[守卫](https://docs.nestjs.com/guards)。
+
+## 健康
+
+包含一个公开可用的REST API（healthz），返回JSON以确认数据库是否按预期工作。
+
+## 元数据
+
+定义自定义对象并提供GraphQL API（graphql/metadata）。
+
+## 工作区
+
+生成并提供基于元数据的自定义GraphQL架构。
+
+### 工作空间目录结构
+
+```
+workspace
+
+  └───workspace-schema-builder
+    └───factories
+    └───graphql-types
+    └───database
+    └───interfaces
+    └───object-definitions
+    └───services
+    └───storage
+    └───utils
+  └───workspace-resolver-builder
+    └───factories
+    └───interfaces
+  └───workspace-query-builder
+    └───factories
+    └───interfaces
+  └───workspace-query-runner
+    └───interfaces
+    └───utils
+  └───workspace-datasource
+  └───workspace-manager
+  └───workspace-migration-runner
+  └───utils
+  └───workspace.module.ts
+  └───workspace.factory.spec.ts
+  └───workspace.factory.ts
+```
+
+工作空间目录的根目录包含`workspace.factory.ts`，其中包含`createGraphQLSchema`函数。 此函数通过使用元数据为各个工作空间定制架构来生成工作空间特定的架构。 通过分离架构和解析程序的构建，我们使用`makeExecutableSchema`函数，该函数结合这些离散元素。
+
+这个策略不仅仅是关于组织，它还有助于优化，比如缓存生成的类型定义以提高性能和可扩展性。
+
+### 工作空间架构生成器
+
+生成GraphQL架构，并包括：
+
+#### 工厂：
+
+专门的构造函数用于生成与GraphQL相关的结构。
+
+* type.factory使用`TypeMapperService`将字段元数据翻译为GraphQL类型。
+* type-definition.factory创建从`objectMetadata`派生的GraphQL输入或输出对象。
+
+#### GraphQL类型
+
+包括枚举、输入、对象和标量，并作为架构构建的基石。
+
+#### 接口和对象定义
+
+包含GraphQL实体的蓝图，包括诸如`MONEY`或`URL`之类的预定义和自定义类型。
+
+#### 服务
+
+包含负责将FieldMetadataType与其适当GraphQL标量或查询修饰符相关联的服务。
+
+#### 存储
+
+包含`TypeDefinitionsStorage`类，其中包含可重用的类型定义，防止重复GraphQL类型。
+
+### 工作空间解析器生成器
+
+创建用于查询和修改GraphQL架构的解析器函数。
+
+此目录中的每个工厂负责生成不同类型的解析器，如`FindManyResolverFactory`，旨在跨各种表灵活应用。
+
+### 工作空间查询运行器
+
+在数据库上运行生成的查询并解析结果。

packages/twenty-docs/l/zh/developers/contribute/capabilities/backend-development/queue.mdx

@@ -0,0 +1,41 @@
+---
+title: 消息队列
+---
+
+队列支持异步操作的执行。 它们可用于执行后台任务，例如在注册时发送欢迎邮件。
+每个用例都将拥有一个继承自 `MessageQueueServiceBase` 的队列类。
+
+当前，我们仅支持使用 `bull-mq`[bull-mq](https://bullmq.io/) 作为队列驱动。
+
+## 创建和使用新队列的步骤
+
+1. 在枚举 `MESSAGE_QUEUES` 下为您的新队列添加队列名称。
+2. 提供以队列名称为依赖令牌的队列工厂实现。
+3. 在所需模块/服务中以队列名称作为依赖令牌注入您创建的队列。
+4. 添加与生产者相同令牌注入的工作类。
+
+### 示例用法
+
+```ts
+class Resolver {
+  constructor(@Inject(MESSAGE_QUEUES.custom) private queue: MessageQueueService) {}
+
+  async onSomeAction() {
+    //business logic
+    await this.queue.add(someData);
+  }
+}
+
+//async worker
+class CustomWorker {
+  constructor(@Inject(MESSAGE_QUEUES.custom) private queue: MessageQueueService) {
+    this.initWorker();
+  }
+
+  async initWorker() {
+    await this.queue.work(async ({ id, data }) => {
+      //worker logic
+    });
+  }
+}
+```

packages/twenty-docs/l/zh/developers/contribute/capabilities/backend-development/server-commands.mdx

@@ -0,0 +1,87 @@
+---
+title: 后端命令
+icon: terminal
+---
+
+## 实用命令
+
+这些命令应从 packages/twenty-server 文件夹中执行。
+从其他文件夹，您可以运行 `npx nx {command} twenty-server`（或 `npx nx run twenty-server:{command}`）。
+
+### 首次设置
+
+```
+npx nx database:reset twenty-server # setup the database with dev seeds
+```
+
+### 启动服务器
+
+```
+npx nx run twenty-server:start
+```
+
+### Lint
+
+```
+npx nx run twenty-server:lint # pass --fix to fix lint errors
+```
+
+### 测试
+
+```
+npx nx run twenty-server:test:unit          # run unit tests
+npx nx run twenty-server:test:integration   # run integration tests
+```
+
+注意：如果需要在运行集成测试之前重置数据库，可以运行 `npx nx run twenty-server:test:integration:with-db-reset`。
+
+### 重置数据库
+
+如果您想重置并为数据库预置数据，可以运行以下命令：
+
+```bash
+npx nx run twenty-server:database:reset
+```
+
+### 迁移
+
+#### 适用于 Core/Metadata 模式中的对象 (TypeORM)
+
+```bash
+npx nx run twenty-server:database:migrate:generate
+```
+
+## 技术栈
+
+Twenty 主要使用 NestJS 作为后端。
+
+Prisma 是我们最先使用的 ORM。 但为了允许用户创建自定义字段和对象，使用更底层的工具更有意义，因为我们需要进行精细控制。 项目现在使用 TypeORM。
+
+这是当前技术栈的样子。
+
+**核心**
+
+* [NestJS](https://nestjs.com/)
+* [TypeORM](https://typeorm.io/)
+* [GraphQL Yoga](https://the-guild.dev/graphql/yoga-server)
+
+**数据库**
+
+* [Postgres](https://www.postgresql.org/)
+
+**第三方集成**
+
+* [Sentry](https://sentry.io/welcome/) 用于 bug 跟踪
+
+**测试**
+
+* [Jest](https://jestjs.io/)
+
+**工具**
+
+* [Yarn](https://yarnpkg.com/)
+* [Oxlint](https://oxc.rs/docs/guide/usage/linter.html)
+
+**开发**
+
+* [AWS EKS](https://aws.amazon.com/eks/)

packages/twenty-docs/l/zh/developers/contribute/capabilities/backend-development/zapier.mdx

@@ -0,0 +1,85 @@
+---
+title: Zapier 应用
+---
+
+通过 [Zapier](https://zapier.com/) 无缝同步 Twenty 和 3000 多个应用。 自动化任务，提高生产力，提升客户关系！
+
+## 关于 Zapier
+
+Zapier 是一款工具，可通过连接你的团队每天使用的应用来实现工作流自动化。 Zapier 的基本概念是称为 Zaps 的自动化工作流，包含触发器和操作。
+
+您可以在[这里](https://zapier.com/how-it-works)了解更多关于 Zapier 的工作原理。
+
+## 设置
+
+### 步骤 1: 安装 Zapier 包
+
+```bash
+cd packages/twenty-zapier
+
+yarn
+```
+
+### 步骤 2: 使用 CLI 登录
+
+使用您的 Zapier 凭证通过 CLI 登录：
+
+```bash
+zapier login
+```
+
+### 步骤 3: 设置环境变量
+
+从 `packages/twenty-zapier` 文件夹运行：
+
+```bash
+cp .env.example .env
+```
+
+在本地运行应用程序，访问 [http://localhost:3000/settings/api-webhooks](http://localhost:3000/settings/api-webhooks)，并生成一个 API 密钥。
+
+将 `.env` 文件中的 **YOUR_API_KEY** 值替换为你刚刚生成的 API 密钥。
+
+## 开发
+
+<Warning>
+
+确保在执行任何 `zapier` 命令前运行 `yarn build`。
+
+</Warning>
+
+### 测试
+
+```bash
+yarn test
+```
+
+### Lint
+
+```bash
+yarn format
+```
+
+### 编辑代码时监视并编译
+
+```bash
+yarn watch
+```
+
+### 验证您的 Zapier 应用
+
+```bash
+yarn validate
+```
+
+### 部署您的 Zapier 应用
+
+```bash
+yarn deploy
+```
+
+### 列出所有 Zapier CLI 命令
+
+```bash
+zapier
+```