syncable-entity-builder-and-validation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Syncable Entity: Builder & Validation (Step 3/6)

可同步实体：构建器与验证（第3步/共6步）

Purpose: Implement business rule validation and create migration action builders.

When to use: After completing Steps 1-2 (Types, Cache, Transform). Required before implementing action handlers.

用途：实现业务规则验证并创建迁移动作构建器。

适用时机：完成第1-2步（类型定义、缓存、转换）之后，实现动作处理器之前必须完成此步骤。

Quick Start

快速开始

This step creates:

Validator service (business logic validation)
Builder service (action creation)
Orchestrator wiring (CRITICAL - often forgotten!)

Key principles:

Validators never throw - return error arrays
Validators never mutate - pass optimistic entity maps
Use indexed lookups (O(1)) not
```
Object.values().find()
```
(O(n))

此步骤将创建：

验证器服务（业务逻辑验证）
构建器服务（动作创建）
编排器集成（至关重要 - 常被遗漏！）

核心原则：

验证器绝不抛出异常 - 返回错误数组
验证器绝不修改数据 - 使用乐观实体映射
使用索引查找（O(1)）而非
```
Object.values().find()
```
（O(n)）

Step 1: Create Validator Service

步骤1：创建验证器服务

File:

src/engine/workspace-manager/workspace-migration/workspace-migration-builder/validators/services/flat-my-entity-validator.service.ts

typescript

import { Injectable } from '@nestjs/common';
import { t, msg } from '@lingui/macro';
import { isDefined } from 'twenty-shared/utils';

import { type FlatMyEntity } from 'src/engine/metadata-modules/flat-my-entity/types/flat-my-entity.type';
import { type FlatMyEntityMaps } from 'src/engine/metadata-modules/flat-my-entity/types/flat-my-entity-maps.type';
import { WorkspaceMigrationValidationError } from 'src/engine/workspace-manager/workspace-migration/workspace-migration-builder/validators/types/workspace-migration-validation-error.type';
import { MyEntityExceptionCode } from 'src/engine/metadata-modules/my-entity/exceptions/my-entity-exception-code.enum';

@Injectable()
export class FlatMyEntityValidatorService {
  validateMyEntityForCreate(
    flatMyEntity: FlatMyEntity,
    optimisticFlatMyEntityMaps: FlatMyEntityMaps,
  ): WorkspaceMigrationValidationError[] {
    const errors: WorkspaceMigrationValidationError[] = [];

    // Pattern 1: Required field validation
    if (!isDefined(flatMyEntity.name) || flatMyEntity.name.trim() === '') {
      errors.push({
        code: MyEntityExceptionCode.NAME_REQUIRED,
        message: t`Name is required`,
        userFriendlyMessage: msg`Please provide a name for this entity`,
      });
    }

    // Pattern 2: Uniqueness check - use indexed map (O(1))
    const existingEntityWithName = optimisticFlatMyEntityMaps.byName[flatMyEntity.name];

    if (isDefined(existingEntityWithName) && existingEntityWithName.id !== flatMyEntity.id) {
      errors.push({
        code: MyEntityExceptionCode.MY_ENTITY_ALREADY_EXISTS,
        message: t`Entity with name ${flatMyEntity.name} already exists`,
        userFriendlyMessage: msg`An entity with this name already exists`,
      });
    }

    // Pattern 3: Foreign key validation
    if (isDefined(flatMyEntity.parentEntityId)) {
      const parentEntity = optimisticFlatParentEntityMaps.byId[flatMyEntity.parentEntityId];

      if (!isDefined(parentEntity)) {
        errors.push({
          code: MyEntityExceptionCode.PARENT_ENTITY_NOT_FOUND,
          message: t`Parent entity with ID ${flatMyEntity.parentEntityId} not found`,
          userFriendlyMessage: msg`The specified parent entity does not exist`,
        });
      } else if (isDefined(parentEntity.deletedAt)) {
        errors.push({
          code: MyEntityExceptionCode.PARENT_ENTITY_DELETED,
          message: t`Parent entity is deleted`,
          userFriendlyMessage: msg`Cannot reference a deleted parent entity`,
        });
      }
    }

    // Pattern 4: Standard entity protection
    if (flatMyEntity.isCustom === false) {
      errors.push({
        code: MyEntityExceptionCode.STANDARD_ENTITY_CANNOT_BE_CREATED,
        message: t`Cannot create standard entity`,
        userFriendlyMessage: msg`Standard entities can only be created by the system`,
      });
    }

    return errors;
  }

  validateMyEntityForUpdate(
    flatMyEntity: FlatMyEntity,
    updates: Partial<FlatMyEntity>,
    optimisticFlatMyEntityMaps: FlatMyEntityMaps,
  ): WorkspaceMigrationValidationError[] {
    const errors: WorkspaceMigrationValidationError[] = [];

    // Standard entity protection
    if (flatMyEntity.isCustom === false) {
      errors.push({
        code: MyEntityExceptionCode.STANDARD_ENTITY_CANNOT_BE_UPDATED,
        message: t`Cannot update standard entity`,
        userFriendlyMessage: msg`Standard entities cannot be modified`,
      });
      return errors; // Early return if standard
    }

    // Uniqueness check for name changes
    if (isDefined(updates.name) && updates.name !== flatMyEntity.name) {
      const existingEntityWithName = optimisticFlatMyEntityMaps.byName[updates.name];

      if (isDefined(existingEntityWithName) && existingEntityWithName.id !== flatMyEntity.id) {
        errors.push({
          code: MyEntityExceptionCode.MY_ENTITY_ALREADY_EXISTS,
          message: t`Entity with name ${updates.name} already exists`,
          userFriendlyMessage: msg`An entity with this name already exists`,
        });
      }
    }

    return errors;
  }

  validateMyEntityForDelete(
    flatMyEntity: FlatMyEntity,
  ): WorkspaceMigrationValidationError[] {
    const errors: WorkspaceMigrationValidationError[] = [];

    // Standard entity protection
    if (flatMyEntity.isCustom === false) {
      errors.push({
        code: MyEntityExceptionCode.STANDARD_ENTITY_CANNOT_BE_DELETED,
        message: t`Cannot delete standard entity`,
        userFriendlyMessage: msg`Standard entities cannot be deleted`,
      });
    }

    return errors;
  }
}

Performance warning: Avoid

Object.values().find()

- use indexed maps instead!

typescript

// ❌ BAD: O(n) - slow for large datasets
const duplicate = Object.values(optimisticFlatMyEntityMaps.byId).find(
  (entity) => entity.name === flatMyEntity.name && entity.id !== flatMyEntity.id
);

// ✅ GOOD: O(1) - use indexed map
const existingEntityWithName = optimisticFlatMyEntityMaps.byName[flatMyEntity.name];
if (isDefined(existingEntityWithName) && existingEntityWithName.id !== flatMyEntity.id) {
  // Handle duplicate
}

文件路径：

src/engine/workspace-manager/workspace-migration/workspace-migration-builder/validators/services/flat-my-entity-validator.service.ts

typescript

import { Injectable } from '@nestjs/common';
import { t, msg } from '@lingui/macro';
import { isDefined } from 'twenty-shared/utils';

import { type FlatMyEntity } from 'src/engine/metadata-modules/flat-my-entity/types/flat-my-entity.type';
import { type FlatMyEntityMaps } from 'src/engine/metadata-modules/flat-my-entity/types/flat-my-entity-maps.type';
import { WorkspaceMigrationValidationError } from 'src/engine/workspace-manager/workspace-migration/workspace-migration-builder/validators/types/workspace-migration-validation-error.type';
import { MyEntityExceptionCode } from 'src/engine/metadata-modules/my-entity/exceptions/my-entity-exception-code.enum';

@Injectable()
export class FlatMyEntityValidatorService {
  validateMyEntityForCreate(
    flatMyEntity: FlatMyEntity,
    optimisticFlatMyEntityMaps: FlatMyEntityMaps,
  ): WorkspaceMigrationValidationError[] {
    const errors: WorkspaceMigrationValidationError[] = [];

    // Pattern 1: Required field validation
    if (!isDefined(flatMyEntity.name) || flatMyEntity.name.trim() === '') {
      errors.push({
        code: MyEntityExceptionCode.NAME_REQUIRED,
        message: t`Name is required`,
        userFriendlyMessage: msg`Please provide a name for this entity`,
      });
    }

    // Pattern 2: Uniqueness check - use indexed map (O(1))
    const existingEntityWithName = optimisticFlatMyEntityMaps.byName[flatMyEntity.name];

    if (isDefined(existingEntityWithName) && existingEntityWithName.id !== flatMyEntity.id) {
      errors.push({
        code: MyEntityExceptionCode.MY_ENTITY_ALREADY_EXISTS,
        message: t`Entity with name ${flatMyEntity.name} already exists`,
        userFriendlyMessage: msg`An entity with this name already exists`,
      });
    }

    // Pattern 3: Foreign key validation
    if (isDefined(flatMyEntity.parentEntityId)) {
      const parentEntity = optimisticFlatParentEntityMaps.byId[flatMyEntity.parentEntityId];

      if (!isDefined(parentEntity)) {
        errors.push({
          code: MyEntityExceptionCode.PARENT_ENTITY_NOT_FOUND,
          message: t`Parent entity with ID ${flatMyEntity.parentEntityId} not found`,
          userFriendlyMessage: msg`The specified parent entity does not exist`,
        });
      } else if (isDefined(parentEntity.deletedAt)) {
        errors.push({
          code: MyEntityExceptionCode.PARENT_ENTITY_DELETED,
          message: t`Parent entity is deleted`,
          userFriendlyMessage: msg`Cannot reference a deleted parent entity`,
        });
      }
    }

    // Pattern 4: Standard entity protection
    if (flatMyEntity.isCustom === false) {
      errors.push({
        code: MyEntityExceptionCode.STANDARD_ENTITY_CANNOT_BE_CREATED,
        message: t`Cannot create standard entity`,
        userFriendlyMessage: msg`Standard entities can only be created by the system`,
      });
    }

    return errors;
  }

  validateMyEntityForUpdate(
    flatMyEntity: FlatMyEntity,
    updates: Partial<FlatMyEntity>,
    optimisticFlatMyEntityMaps: FlatMyEntityMaps,
  ): WorkspaceMigrationValidationError[] {
    const errors: WorkspaceMigrationValidationError[] = [];

    // Standard entity protection
    if (flatMyEntity.isCustom === false) {
      errors.push({
        code: MyEntityExceptionCode.STANDARD_ENTITY_CANNOT_BE_UPDATED,
        message: t`Cannot update standard entity`,
        userFriendlyMessage: msg`Standard entities cannot be modified`,
      });
      return errors; // Early return if standard
    }

    // Uniqueness check for name changes
    if (isDefined(updates.name) && updates.name !== flatMyEntity.name) {
      const existingEntityWithName = optimisticFlatMyEntityMaps.byName[updates.name];

      if (isDefined(existingEntityWithName) && existingEntityWithName.id !== flatMyEntity.id) {
        errors.push({
          code: MyEntityExceptionCode.MY_ENTITY_ALREADY_EXISTS,
          message: t`Entity with name ${updates.name} already exists`,
          userFriendlyMessage: msg`An entity with this name already exists`,
        });
      }
    }

    return errors;
  }

  validateMyEntityForDelete(
    flatMyEntity: FlatMyEntity,
  ): WorkspaceMigrationValidationError[] {
    const errors: WorkspaceMigrationValidationError[] = [];

    // Standard entity protection
    if (flatMyEntity.isCustom === false) {
      errors.push({
        code: MyEntityExceptionCode.STANDARD_ENTITY_CANNOT_BE_DELETED,
        message: t`Cannot delete standard entity`,
        userFriendlyMessage: msg`Standard entities cannot be deleted`,
      });
    }

    return errors;
  }
}

性能警告：避免使用

Object.values().find()

- 改用索引映射！

typescript

// ❌ BAD: O(n) - slow for large datasets
const duplicate = Object.values(optimisticFlatMyEntityMaps.byId).find(
  (entity) => entity.name === flatMyEntity.name && entity.id !== flatMyEntity.id
);

// ✅ GOOD: O(1) - use indexed map
const existingEntityWithName = optimisticFlatMyEntityMaps.byName[flatMyEntity.name];
if (isDefined(existingEntityWithName) && existingEntityWithName.id !== flatMyEntity.id) {
  // Handle duplicate
}

Step 2: Create Builder Service

步骤2：创建构建器服务

File:

src/engine/workspace-manager/workspace-migration/workspace-migration-builder/builders/my-entity/workspace-migration-my-entity-actions-builder.service.ts

typescript

import { Injectable } from '@nestjs/common';

import { WorkspaceEntityMigrationBuilderService } from 'src/engine/workspace-manager/workspace-migration/workspace-migration-builder/workspace-entity-migration-builder.service';
import { FlatMyEntityValidatorService } from 'src/engine/workspace-manager/workspace-migration/workspace-migration-builder/validators/services/flat-my-entity-validator.service';
import { type UniversalFlatMyEntity } from 'src/engine/workspace-manager/workspace-migration/universal-flat-entity/types/universal-flat-my-entity.type';
import {
  type UniversalCreateMyEntityAction,
  type UniversalUpdateMyEntityAction,
  type UniversalDeleteMyEntityAction,
} from 'src/engine/workspace-manager/workspace-migration/workspace-migration-builder/builders/my-entity/types/workspace-migration-my-entity-action.type';

@Injectable()
export class WorkspaceMigrationMyEntityActionsBuilderService extends WorkspaceEntityMigrationBuilderService<
  'myEntity',
  UniversalFlatMyEntity,
  UniversalCreateMyEntityAction,
  UniversalUpdateMyEntityAction,
  UniversalDeleteMyEntityAction
> {
  constructor(
    private readonly flatMyEntityValidatorService: FlatMyEntityValidatorService,
  ) {
    super();
  }

  protected buildCreateAction(
    universalFlatMyEntity: UniversalFlatMyEntity,
    flatEntityMaps: AllFlatEntityMapsByMetadataName,
  ): BuildWorkspaceMigrationActionReturnType<UniversalCreateMyEntityAction> {
    const validationResult = this.flatMyEntityValidatorService.validateMyEntityForCreate(
      universalFlatMyEntity,
      flatEntityMaps.flatMyEntityMaps,
    );

    if (validationResult.length > 0) {
      return {
        status: 'failed',
        errors: validationResult,
      };
    }

    return {
      status: 'success',
      action: {
        type: 'create',
        metadataName: 'myEntity',
        universalFlatEntity: universalFlatMyEntity,
      },
    };
  }

  protected buildUpdateAction(
    universalFlatMyEntity: UniversalFlatMyEntity,
    universalUpdates: Partial<UniversalFlatMyEntity>,
    flatEntityMaps: AllFlatEntityMapsByMetadataName,
  ): BuildWorkspaceMigrationActionReturnType<UniversalUpdateMyEntityAction> {
    const validationResult = this.flatMyEntityValidatorService.validateMyEntityForUpdate(
      universalFlatMyEntity,
      universalUpdates,
      flatEntityMaps.flatMyEntityMaps,
    );

    if (validationResult.length > 0) {
      return {
        status: 'failed',
        errors: validationResult,
      };
    }

    return {
      status: 'success',
      action: {
        type: 'update',
        metadataName: 'myEntity',
        universalFlatEntity: universalFlatMyEntity,
        universalUpdates,
      },
    };
  }

  protected buildDeleteAction(
    universalFlatMyEntity: UniversalFlatMyEntity,
  ): BuildWorkspaceMigrationActionReturnType<UniversalDeleteMyEntityAction> {
    const validationResult = this.flatMyEntityValidatorService.validateMyEntityForDelete(
      universalFlatMyEntity,
    );

    if (validationResult.length > 0) {
      return {
        status: 'failed',
        errors: validationResult,
      };
    }

    return {
      status: 'success',
      action: {
        type: 'delete',
        metadataName: 'myEntity',
        universalFlatEntity: universalFlatMyEntity,
      },
    };
  }
}

文件路径：

src/engine/workspace-manager/workspace-migration/workspace-migration-builder/builders/my-entity/workspace-migration-my-entity-actions-builder.service.ts

typescript

import { Injectable } from '@nestjs/common';

import { WorkspaceEntityMigrationBuilderService } from 'src/engine/workspace-manager/workspace-migration/workspace-migration-builder/workspace-entity-migration-builder.service';
import { FlatMyEntityValidatorService } from 'src/engine/workspace-manager/workspace-migration/workspace-migration-builder/validators/services/flat-my-entity-validator.service';
import { type UniversalFlatMyEntity } from 'src/engine/workspace-manager/workspace-migration/universal-flat-entity/types/universal-flat-my-entity.type';
import {
  type UniversalCreateMyEntityAction,
  type UniversalUpdateMyEntityAction,
  type UniversalDeleteMyEntityAction,
} from 'src/engine/workspace-manager/workspace-migration/workspace-migration-builder/builders/my-entity/types/workspace-migration-my-entity-action.type';

@Injectable()
export class WorkspaceMigrationMyEntityActionsBuilderService extends WorkspaceEntityMigrationBuilderService<
  'myEntity',
  UniversalFlatMyEntity,
  UniversalCreateMyEntityAction,
  UniversalUpdateMyEntityAction,
  UniversalDeleteMyEntityAction
> {
  constructor(
    private readonly flatMyEntityValidatorService: FlatMyEntityValidatorService,
  ) {
    super();
  }

  protected buildCreateAction(
    universalFlatMyEntity: UniversalFlatMyEntity,
    flatEntityMaps: AllFlatEntityMapsByMetadataName,
  ): BuildWorkspaceMigrationActionReturnType<UniversalCreateMyEntityAction> {
    const validationResult = this.flatMyEntityValidatorService.validateMyEntityForCreate(
      universalFlatMyEntity,
      flatEntityMaps.flatMyEntityMaps,
    );

    if (validationResult.length > 0) {
      return {
        status: 'failed',
        errors: validationResult,
      };
    }

    return {
      status: 'success',
      action: {
        type: 'create',
        metadataName: 'myEntity',
        universalFlatEntity: universalFlatMyEntity,
      },
    };
  }

  protected buildUpdateAction(
    universalFlatMyEntity: UniversalFlatMyEntity,
    universalUpdates: Partial<UniversalFlatMyEntity>,
    flatEntityMaps: AllFlatEntityMapsByMetadataName,
  ): BuildWorkspaceMigrationActionReturnType<UniversalUpdateMyEntityAction> {
    const validationResult = this.flatMyEntityValidatorService.validateMyEntityForUpdate(
      universalFlatMyEntity,
      universalUpdates,
      flatEntityMaps.flatMyEntityMaps,
    );

    if (validationResult.length > 0) {
      return {
        status: 'failed',
        errors: validationResult,
      };
    }

    return {
      status: 'success',
      action: {
        type: 'update',
        metadataName: 'myEntity',
        universalFlatEntity: universalFlatMyEntity,
        universalUpdates,
      },
    };
  }

  protected buildDeleteAction(
    universalFlatMyEntity: UniversalFlatMyEntity,
  ): BuildWorkspaceMigrationActionReturnType<UniversalDeleteMyEntityAction> {
    const validationResult = this.flatMyEntityValidatorService.validateMyEntityForDelete(
      universalFlatMyEntity,
    );

    if (validationResult.length > 0) {
      return {
        status: 'failed',
        errors: validationResult,
      };
    }

    return {
      status: 'success',
      action: {
        type: 'delete',
        metadataName: 'myEntity',
        universalFlatEntity: universalFlatMyEntity,
      },
    };
  }
}

Step 3: Wire into Orchestrator (CRITICAL)

步骤3：集成到编排器（至关重要）

File:

src/engine/workspace-manager/workspace-migration/workspace-migration-builder/workspace-migration-build-orchestrator.service.ts

typescript

@Injectable()
export class WorkspaceMigrationBuildOrchestratorService {
  constructor(
    // ... existing builders
    private readonly workspaceMigrationMyEntityActionsBuilderService: WorkspaceMigrationMyEntityActionsBuilderService,
  ) {}

  async buildWorkspaceMigration({
    allFlatEntityOperationByMetadataName,
    flatEntityMaps,
    isSystemBuild,
  }: BuildWorkspaceMigrationInput): Promise<BuildWorkspaceMigrationOutput> {
    // ... existing code

    // Add your entity builder
    const myEntityResult = await this.workspaceMigrationMyEntityActionsBuilderService.build({
      flatEntitiesToCreate: allFlatEntityOperationByMetadataName.myEntity?.flatEntityToCreate ?? [],
      flatEntitiesToUpdate: allFlatEntityOperationByMetadataName.myEntity?.flatEntityToUpdate ?? [],
      flatEntitiesToDelete: allFlatEntityOperationByMetadataName.myEntity?.flatEntityToDelete ?? [],
      flatEntityMaps,
      isSystemBuild,
    });

    // ... aggregate errors

    return {
      status: aggregatedErrors.length > 0 ? 'failed' : 'success',
      errors: aggregatedErrors,
      actions: [
        ...existingActions,
        ...myEntityResult.actions,
      ],
    };
  }
}

⚠️ This step is the most commonly forgotten! Your entity won't sync without orchestrator wiring.

文件路径：

src/engine/workspace-manager/workspace-migration/workspace-migration-builder/workspace-migration-build-orchestrator.service.ts

typescript

@Injectable()
export class WorkspaceMigrationBuildOrchestratorService {
    constructor(
        // ... existing builders
        private readonly workspaceMigrationMyEntityActionsBuilderService: WorkspaceMigrationMyEntityActionsBuilderService,
    ) {}

    async buildWorkspaceMigration({
        allFlatEntityOperationByMetadataName,
        flatEntityMaps,
        isSystemBuild,
    }: BuildWorkspaceMigrationInput): Promise<BuildWorkspaceMigrationOutput> {
        // ... existing code

        // Add your entity builder
        const myEntityResult = await this.workspaceMigrationMyEntityActionsBuilderService.build({
            flatEntitiesToCreate: allFlatEntityOperationByMetadataName.myEntity?.flatEntityToCreate ?? [],
            flatEntitiesToUpdate: allFlatEntityOperationByMetadataName.myEntity?.flatEntityToUpdate ?? [],
            flatEntitiesToDelete: allFlatEntityOperationByMetadataName.myEntity?.flatEntityToDelete ?? [],
            flatEntityMaps,
            isSystemBuild,
        });

        // ... aggregate errors

        return {
            status: aggregatedErrors.length > 0 ? 'failed' : 'success',
            errors: aggregatedErrors,
            actions: [
                ...existingActions,
                ...myEntityResult.actions,
            ],
        };
    }
}

⚠️ 此步骤最容易被遗漏！ 不集成到编排器，你的实体将无法同步。

Validation Patterns

验证模式

Pattern 1: Required Field

模式1：必填字段验证

typescript

if (!isDefined(field) || field.trim() === '') {
  errors.push({ code: ..., message: ..., userFriendlyMessage: ... });
}

typescript

if (!isDefined(field) || field.trim() === '') {
    errors.push({ code: ..., message: ..., userFriendlyMessage: ... });
}

Pattern 2: Uniqueness (O(1) lookup)

模式2：唯一性验证（O(1)查找）

typescript

const existing = optimisticMaps.byName[entity.name];
if (isDefined(existing) && existing.id !== entity.id) {
  errors.push({ ... });
}

typescript

const existing = optimisticMaps.byName[entity.name];
if (isDefined(existing) && existing.id !== entity.id) {
    errors.push({ ... });
}

Pattern 3: Foreign Key Validation

模式3：外键验证

typescript

if (isDefined(entity.parentId)) {
  const parent = parentMaps.byId[entity.parentId];
  if (!isDefined(parent)) {
    errors.push({ code: NOT_FOUND, ... });
  } else if (isDefined(parent.deletedAt)) {
    errors.push({ code: DELETED, ... });
  }
}

typescript

if (isDefined(entity.parentId)) {
    const parent = parentMaps.byId[entity.parentId];
    if (!isDefined(parent)) {
        errors.push({ code: NOT_FOUND, ... });
    } else if (isDefined(parent.deletedAt)) {
        errors.push({ code: DELETED, ... });
    }
}

Pattern 4: Standard Entity Protection

模式4：标准实体保护

typescript

if (entity.isCustom === false) {
  errors.push({ code: STANDARD_ENTITY_PROTECTED, ... });
  return errors; // Early return
}

typescript

if (entity.isCustom === false) {
    errors.push({ code: STANDARD_ENTITY_PROTECTED, ... });
    return errors; // Early return
}

Checklist

检查清单

Before moving to Step 4:

Validator service created
Validator never throws (returns error arrays)
Validator never mutates (uses optimistic maps)
All uniqueness checks use indexed maps (O(1))
Required field validation implemented
Foreign key validation implemented
Standard entity protection implemented
Builder service extends
```
WorkspaceEntityMigrationBuilderService
```
Builder creates actions with universal entities
Builder wired into orchestrator (CRITICAL)
Builder injected in orchestrator constructor
Builder called in
buildWorkspaceMigration
Actions added to orchestrator return statement

进入第4步之前，请确认：

已创建验证器服务
验证器绝不抛出异常（返回错误数组）
验证器绝不修改数据（使用乐观映射）
所有唯一性检查均使用索引映射（O(1)）
已实现必填字段验证
已实现外键验证
已实现标准实体保护
构建器服务继承自
```
WorkspaceEntityMigrationBuilderService
```
构建器使用通用实体创建动作
构建器已集成到编排器（至关重要）
构建器已注入到编排器的构造函数中
在
buildWorkspaceMigration
中调用了构建器
动作已添加到编排器的返回结果中

Next Step

下一步

Once builder and validation are complete, proceed to: Syncable Entity: Runner & Actions (Step 4/6)

For complete workflow, see

@creating-syncable-entity

rule.

完成构建器与验证的开发后，请继续： 可同步实体：执行器与动作（第4步/共6步）

完整工作流请查看

@creating-syncable-entity

规则。