[REQUIRES_FULL_CACHE_FLUSH_WHEN_RELEASED] Refactor FlatEntity to be UniversalFlatEntity superset (#17452)

# Introduction In this PR we're refactoring the `FlatEntity` type to become a superset of the `UniversalFlatEntity`. Right now we're storing all the extra properties in `__universal` property, at some point it might just be sibling to other entity and we might rely on the `propertiesToCompare` constants and TypeScript allowing passing a superset type into a smaller subset type ## FromTo utils The entity to flat entity method now computes the universal information, standardized a typing and pattern to do ## Example Also strictly type ```ts "bbb019ea-6205-498c-aea5-67bc53bce8a9": { "workspaceId": "20202020-1c25-4d02-bf25-6aeccf7ea419", "universalIdentifier": "20202020-d111-4d11-8d11-da5ab0a11002", "applicationId": "d01b010d-b984-465b-b40b-370e954e5188", "id": "bbb019ea-6205-498c-aea5-67bc53bce8a9", "pageLayoutTabId": "791a512f-169f-4209-b731-aa86716668c6", "title": "Deals by Company", "type": "GRAPH", "objectMetadataId": "9e14efea-df5b-4c0e-aba9-cfe455f32397", "gridPosition": { "row": 0, "column": 6, "rowSpan": 6, "columnSpan": 6 }, "configuration": { "color": "orange", "orderBy": "FIELD_ASC", "timezone": "UTC", "displayLegend": true, "displayDataLabel": false, "showCenterMetric": true, "configurationType": "PIE_CHART", "firstDayOfTheWeek": 0, "aggregateOperation": "COUNT", "groupBySubFieldName": "name", "groupByFieldMetadataId": "6673ff18-63d2-47a1-8f85-2b9b09ca27a5", "aggregateFieldMetadataId": "8d64ee41-5dd4-4de6-945a-7c0c18399715" }, "createdAt": "2026-01-28T14:08:52.140Z", "updatedAt": "2026-01-28T14:08:52.140Z", "deletedAt": null, "__universal": { "universalIdentifier": "20202020-d111-4d11-8d11-da5ab0a11002", "applicationUniversalIdentifier": "20202020-64aa-4b6f-b003-9c74b97cee20", "pageLayoutTabUniversalIdentifier": "20202020-d011-4d11-8d11-da5ab0a01001", "objectMetadataUniversalIdentifier": "20202020-9549-49dd-b2b2-883999db8938", "gridPosition": { "row": 0, "column": 6, "rowSpan": 6, "columnSpan": 6 }, "configuration": { "color": "orange", "orderBy": "FIELD_ASC", "timezone": "UTC", "displayLegend": true, "displayDataLabel": false, "showCenterMetric": true, "configurationType": "PIE_CHART", "firstDayOfTheWeek": 0, "aggregateOperation": "COUNT", "groupBySubFieldName": "name", "aggregateFieldMetadataUniversalIdentifier": "20202020-d01a-4131-8a31-f123456789ab", "groupByFieldMetadataUniversalIdentifier": "20202020-cbac-457e-b565-adece5fc815f" } } }, ```
2026-01-28 17:46:34 +01:00
parent 81eaee81a8
commit fe9d6f34ff
90 changed files with 3058 additions and 538 deletions
@@ -1,15 +1,22 @@
 import { Module } from '@nestjs/common';
 import { TypeOrmModule } from '@nestjs/typeorm';

+import { ApplicationEntity } from 'src/engine/core-modules/application/application.entity';
 import { AgentEntity } from 'src/engine/metadata-modules/ai/ai-agent/entities/agent.entity';
 import { WorkspaceFlatAgentMapCacheService } from 'src/engine/metadata-modules/flat-agent/services/workspace-flat-agent-map-cache.service';
 import { WorkspaceFlatRoleTargetByAgentIdService } from 'src/engine/metadata-modules/flat-agent/services/workspace-flat-role-target-by-agent-id.service';
 import { WorkspaceManyOrAllFlatEntityMapsCacheModule } from 'src/engine/metadata-modules/flat-entity/services/workspace-many-or-all-flat-entity-maps-cache.module';
+import { RoleEntity } from 'src/engine/metadata-modules/role/role.entity';
 import { RoleTargetEntity } from 'src/engine/metadata-modules/role-target/role-target.entity';

@Module({
  imports: [
-    TypeOrmModule.forFeature([AgentEntity, RoleTargetEntity]),
+    TypeOrmModule.forFeature([
+      AgentEntity,
+      ApplicationEntity,
+      RoleEntity,
+      RoleTargetEntity,
+    ]),
    WorkspaceManyOrAllFlatEntityMapsCacheModule,
  ],
  providers: [
@@ -5,11 +5,13 @@ import { Repository } from 'typeorm';

 import { WorkspaceCacheProvider } from 'src/engine/workspace-cache/interfaces/workspace-cache-provider.service';

+import { ApplicationEntity } from 'src/engine/core-modules/application/application.entity';
 import { AgentEntity } from 'src/engine/metadata-modules/ai/ai-agent/entities/agent.entity';
 import { type FlatAgentMaps } from 'src/engine/metadata-modules/flat-agent/types/flat-agent-maps.type';
 import { transformAgentEntityToFlatAgent } from 'src/engine/metadata-modules/flat-agent/utils/transform-agent-entity-to-flat-agent.util';
 import { createEmptyFlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/constant/create-empty-flat-entity-maps.constant';
 import { WorkspaceCache } from 'src/engine/workspace-cache/decorators/workspace-cache.decorator';
+import { createIdToUniversalIdentifierMap } from 'src/engine/workspace-cache/utils/create-id-to-universal-identifier-map.util';
 import { addFlatEntityToFlatEntityMapsThroughMutationOrThrow } from 'src/engine/workspace-manager/workspace-migration/utils/add-flat-entity-to-flat-entity-maps-through-mutation-or-throw.util';

@Injectable()
@@ -18,20 +20,35 @@ export class WorkspaceFlatAgentMapCacheService extends WorkspaceCacheProvider<Fl
  constructor(
    @InjectRepository(AgentEntity)
    private readonly agentRepository: Repository<AgentEntity>,
+    @InjectRepository(ApplicationEntity)
+    private readonly applicationRepository: Repository<ApplicationEntity>,
  ) {
    super();
  }

  async computeForCache(workspaceId: string): Promise<FlatAgentMaps> {
-    const agents = await this.agentRepository.find({
-      where: { workspaceId },
-      withDeleted: true,
-    });
+    const [agents, applications] = await Promise.all([
+      this.agentRepository.find({
+        where: { workspaceId },
+        withDeleted: true,
+      }),
+      this.applicationRepository.find({
+        where: { workspaceId },
+        select: ['id', 'universalIdentifier'],
+        withDeleted: true,
+      }),
+    ]);
+
+    const applicationIdToUniversalIdentifierMap =
+      createIdToUniversalIdentifierMap(applications);

    const flatAgentMaps = createEmptyFlatEntityMaps();

    for (const agentEntity of agents) {
-      const flatAgent = transformAgentEntityToFlatAgent(agentEntity);
+      const flatAgent = transformAgentEntityToFlatAgent({
+        entity: agentEntity,
+        applicationIdToUniversalIdentifierMap,
+      });

      addFlatEntityToFlatEntityMapsThroughMutationOrThrow({
        flatEntity: flatAgent,
@@ -6,10 +6,13 @@ import { IsNull, Not, Repository } from 'typeorm';

 import { WorkspaceCacheProvider } from 'src/engine/workspace-cache/interfaces/workspace-cache-provider.service';

+import { ApplicationEntity } from 'src/engine/core-modules/application/application.entity';
 import { FlatRoleTargetByAgentIdMaps } from 'src/engine/metadata-modules/flat-agent/types/flat-role-target-by-agent-id-maps.type';
-import { fromRoleTargetsEntityToFlatRoleTarget } from 'src/engine/metadata-modules/flat-role-target/utils/from-role-target-entity-to-flat-role-target.util';
+import { fromRoleTargetEntityToFlatRoleTarget } from 'src/engine/metadata-modules/flat-role-target/utils/from-role-target-entity-to-flat-role-target.util';
 import { RoleTargetEntity } from 'src/engine/metadata-modules/role-target/role-target.entity';
+import { RoleEntity } from 'src/engine/metadata-modules/role/role.entity';
 import { WorkspaceCache } from 'src/engine/workspace-cache/decorators/workspace-cache.decorator';
+import { createIdToUniversalIdentifierMap } from 'src/engine/workspace-cache/utils/create-id-to-universal-identifier-map.util';

@Injectable()
@WorkspaceCache('flatRoleTargetByAgentIdMaps')
@@ -17,6 +20,10 @@ export class WorkspaceFlatRoleTargetByAgentIdService extends WorkspaceCacheProvi
  constructor(
    @InjectRepository(RoleTargetEntity)
    private readonly roleTargetRepository: Repository<RoleTargetEntity>,
+    @InjectRepository(ApplicationEntity)
+    private readonly applicationRepository: Repository<ApplicationEntity>,
+    @InjectRepository(RoleEntity)
+    private readonly roleRepository: Repository<RoleEntity>,
  ) {
    super();
  }
@@ -24,13 +31,30 @@ export class WorkspaceFlatRoleTargetByAgentIdService extends WorkspaceCacheProvi
  async computeForCache(
    workspaceId: string,
  ): Promise<FlatRoleTargetByAgentIdMaps> {
-    const roleTargetEntities = await this.roleTargetRepository.find({
-      where: {
-        workspaceId,
-        agentId: Not(IsNull()),
-      },
-      withDeleted: true,
-    });
+    const [roleTargetEntities, applications, roles] = await Promise.all([
+      this.roleTargetRepository.find({
+        where: {
+          workspaceId,
+          agentId: Not(IsNull()),
+        },
+        withDeleted: true,
+      }),
+      this.applicationRepository.find({
+        where: { workspaceId },
+        select: ['id', 'universalIdentifier'],
+        withDeleted: true,
+      }),
+      this.roleRepository.find({
+        where: { workspaceId },
+        select: ['id', 'universalIdentifier'],
+        withDeleted: true,
+      }),
+    ]);
+
+    const applicationIdToUniversalIdentifierMap =
+      createIdToUniversalIdentifierMap(applications);
+    const roleIdToUniversalIdentifierMap =
+      createIdToUniversalIdentifierMap(roles);

    const flatRoleTargetByAgentIdMaps: FlatRoleTargetByAgentIdMaps = {};

@@ -38,8 +62,11 @@ export class WorkspaceFlatRoleTargetByAgentIdService extends WorkspaceCacheProvi
      Omit<RoleTargetEntity, 'agentId'> &
        NonNullableRequired<Pick<RoleTargetEntity, 'agentId'>>
    >) {
-      const flatRoleTarget =
-        fromRoleTargetsEntityToFlatRoleTarget(roleTargetEntity);
+      const flatRoleTarget = fromRoleTargetEntityToFlatRoleTarget({
+        entity: roleTargetEntity,
+        applicationIdToUniversalIdentifierMap,
+        roleIdToUniversalIdentifierMap,
+      });

      flatRoleTargetByAgentIdMaps[roleTargetEntity.agentId] = flatRoleTarget;
    }
@@ -1,9 +1,26 @@
-import { type AgentEntity } from 'src/engine/metadata-modules/ai/ai-agent/entities/agent.entity';
-import { type FlatAgent } from 'src/engine/metadata-modules/flat-agent/types/flat-agent.type';
+import { isDefined } from 'twenty-shared/utils';
+
+import { type FlatAgent } from 'src/engine/metadata-modules/flat-agent/types/flat-agent.type';
+import {
+  FlatEntityMapsException,
+  FlatEntityMapsExceptionCode,
+} from 'src/engine/metadata-modules/flat-entity/exceptions/flat-entity-maps.exception';
+import { type FromEntityToFlatEntityArgs } from 'src/engine/workspace-cache/types/from-entity-to-flat-entity-args.type';
+
+export const transformAgentEntityToFlatAgent = ({
+  entity: agentEntity,
+  applicationIdToUniversalIdentifierMap,
+}: FromEntityToFlatEntityArgs<'agent'>): FlatAgent => {
+  const applicationUniversalIdentifier =
+    applicationIdToUniversalIdentifierMap.get(agentEntity.applicationId);
+
+  if (!isDefined(applicationUniversalIdentifier)) {
+    throw new FlatEntityMapsException(
+      `Application with id ${agentEntity.applicationId} not found for agent ${agentEntity.id}`,
+      FlatEntityMapsExceptionCode.ENTITY_NOT_FOUND,
+    );
+  }

-export const transformAgentEntityToFlatAgent = (
-  agentEntity: AgentEntity,
-): FlatAgent => {
  return {
    createdAt: agentEntity.createdAt.toISOString(),
    deletedAt: agentEntity.deletedAt?.toISOString() ?? null,
@@ -23,5 +40,11 @@ export const transformAgentEntityToFlatAgent = (
    applicationId: agentEntity.applicationId,
    modelConfiguration: agentEntity.modelConfiguration,
    evaluationInputs: agentEntity.evaluationInputs,
+    __universal: {
+      universalIdentifier: agentEntity.universalIdentifier,
+      applicationUniversalIdentifier,
+      responseFormat: agentEntity.responseFormat,
+      modelConfiguration: agentEntity.modelConfiguration,
+    },
  };
 };