@solidxai/core 0.1.10 → 0.1.11-beta.1

package/src/services/datasource-introspection.service.ts

@@ -0,0 +1,1536 @@
+import { BadRequestException, Injectable, NotFoundException } from "@nestjs/common";
+import { ModuleRef } from "@nestjs/core";
+import { getDataSourceToken } from "@nestjs/typeorm";
+import { createHash } from "crypto";
+import * as fs from "fs/promises";
+import * as path from "path";
+import { camelCase, startCase } from "lodash";
+import { DataSource } from "typeorm";
+import { CreateModelMetadataDto } from "src/dtos/create-model-metadata.dto";
+import { DatasourceIntrospectionMappingColumnDto, DatasourceIntrospectionMappingDto } from "src/dtos/datasource-introspection-mapping.dto";
+import { UpdateModelMetaDataDto } from "src/dtos/update-model-metadata.dto";
+import { LegacyTableType } from "src/enums/legacy-table-type.enum";
+import type { DatasourceIntrospectionColumn, DatasourceIntrospectionProvider, DatasourceIntrospectionTableRef } from "src/interfaces/datasource-introspection-provider.interface";
+import { ModuleMetadataHelperService } from "src/helpers/module-metadata-helper.service";
+import { ModelMetadataHelperService } from "src/helpers/model-metadata-helper.service";
+import { ModelMetadataRepository } from "src/repository/model-metadata.repository";
+import { ModuleMetadataRepository } from "src/repository/module-metadata.repository";
+import type { ModelMetadata } from "src/entities/model-metadata.entity";
+import { DatasourceManagementService, type DatasourceRecord } from "./datasource-management.service";
+import { FieldMetadataService } from "./field-metadata.service";
+import { ModelMetadataService } from "./model-metadata.service";
+import { MssqlDatasourceIntrospectionProviderService } from "./datasource-introspection/mssql-datasource-introspection-provider.service";
+import { MysqlDatasourceIntrospectionProviderService } from "./datasource-introspection/mysql-datasource-introspection-provider.service";
+import { PostgresDatasourceIntrospectionProviderService } from "./datasource-introspection/postgres-datasource-introspection-provider.service";
+
+type TableInventoryRecord = {
+    schema: string | null;
+    tableName: string;
+    mapped: boolean;
+    mappedModelId: number | null;
+    mappedModelSingularName: string | null;
+    mappedModelDisplayName: string | null;
+    mappedModuleId: number | null;
+    mappedModuleName: string | null;
+    mappedModuleDisplayName: string | null;
+    suggestedLegacyTableType: LegacyTableType;
+    suggestedBaseClassName: string;
+    suggestedIdColumnName: string | null;
+    suggestedUserKeyField: string;
+    columnCount: number;
+    physicalColumnCount: number;
+};
+
+type TableDetailColumnRecord = {
+    columnName: string;
+    fieldName: string;
+    dataType: string;
+    solidFieldType: string;
+    ormType: string;
+    nullable: boolean;
+    defaultValue: string | null;
+    characterMaximumLength: number | null;
+    numericPrecision: number | null;
+    numericScale: number | null;
+    ordinalPosition: number | null;
+    isAutoGenerated: boolean;
+    handledBySuperclass: boolean;
+    superclassFieldName: string | null;
+};
+
+type TableDdlRecord = {
+    statement: string | null;
+    available: boolean;
+    note: string | null;
+};
+
+type MappingPreviewRecord = {
+    operation: "create" | "update";
+    mappedModelId: number | null;
+    metadataJson: {
+        filePath: string;
+        model: Record<string, any>;
+    };
+    migration: {
+        willGenerate: boolean;
+        filePath: string | null;
+        fileName: string | null;
+        className: string | null;
+        timestamp: number | null;
+        content: string | null;
+        note: string;
+        missingSystemColumns: string[];
+    };
+    summary: {
+        includedColumnNames: string[];
+        removedColumnNames: string[];
+        missingSystemColumns: string[];
+        generatedSystemColumnCount: number;
+    };
+    modelPayload: CreateModelMetadataDto | UpdateModelMetaDataDto;
+};
+
+type ReviewedMetadataModel = {
+    singularName: string;
+    pluralName: string;
+    displayName: string;
+    description: string;
+    dataSource: string;
+    dataSourceType: string;
+    tableName: string;
+    userKeyFieldUserKey: string;
+    isChild: boolean;
+    legacyTableType: LegacyTableType;
+    parentModelUserKey: string;
+    enableAuditTracking: boolean;
+    enableSoftDelete: boolean;
+    draftPublishWorkflow: boolean;
+    internationalisation: boolean;
+    fields: Record<string, any>[];
+};
+
+type SystemColumnDefinition = {
+    columnName: string;
+    type: string;
+    length?: string | null;
+    isNullable?: boolean;
+    defaultExpression?: string | null;
+    isGenerated?: boolean;
+    isUnique?: boolean;
+};
+
+@Injectable()
+export class DatasourceIntrospectionService {
+    private readonly supportedDatasourceTypes = new Set(["mssql", "mysql", "postgres"]);
+
+    constructor(
+        private readonly moduleRef: ModuleRef,
+        private readonly datasourceManagementService: DatasourceManagementService,
+        private readonly moduleMetadataRepository: ModuleMetadataRepository,
+        private readonly modelMetadataRepository: ModelMetadataRepository,
+        private readonly moduleMetadataHelperService: ModuleMetadataHelperService,
+        private readonly modelMetadataHelperService: ModelMetadataHelperService,
+        private readonly fieldMetadataService: FieldMetadataService,
+        private readonly modelMetadataService: ModelMetadataService,
+        private readonly mssqlProvider: MssqlDatasourceIntrospectionProviderService,
+        private readonly mysqlProvider: MysqlDatasourceIntrospectionProviderService,
+        private readonly postgresProvider: PostgresDatasourceIntrospectionProviderService,
+    ) { }
+
+    async getBootstrap(moduleId: number) {
+        const module = await this.loadModule(moduleId);
+        const datasources = this.datasourceManagementService
+            .listRecords()
+            .filter((record) => this.supportedDatasourceTypes.has(record.type?.toLowerCase?.() ?? ""));
+
+        return {
+            data: {
+                module: this.toModuleSummary(module),
+                datasources: datasources.map((record) => this.toDatasourceSummary(record)),
+                recommendedDatasourceName: datasources.find((record) => record.name === module.defaultDataSource)?.name
+                    ?? datasources[0]?.name
+                    ?? null,
+            },
+        };
+    }
+
+    async getTables(moduleId: number, datasourceName: string) {
+        const module = await this.loadModule(moduleId);
+        const datasource = this.requireDatasource(datasourceName);
+
+        if (datasource.synchronize === true) {
+            return {
+                data: {
+                    module: this.toModuleSummary(module),
+                    datasource: this.toDatasourceSummary(datasource),
+                    synchronizeBlocked: true,
+                    synchronizeMessage: this.buildSynchronizeBlockedMessage(datasource),
+                    records: [],
+                    meta: {
+                        totalRecords: 0,
+                    },
+                },
+            };
+        }
+
+        const inventory = await this.buildTableInventory(datasource);
+
+        return {
+            data: {
+                module: this.toModuleSummary(module),
+                datasource: this.toDatasourceSummary(datasource),
+                synchronizeBlocked: false,
+                synchronizeMessage: null,
+                records: inventory.records,
+                meta: {
+                    totalRecords: inventory.records.length,
+                },
+            },
+        };
+    }
+
+    async getTableDetail(moduleId: number, datasourceName: string, tableName: string, schema?: string) {
+        const module = await this.loadModule(moduleId);
+        const datasource = this.requireDatasource(datasourceName);
+
+        if (datasource.synchronize === true) {
+            throw new BadRequestException(this.buildSynchronizeBlockedMessage(datasource));
+        }
+
+        const inventory = await this.buildTableInventory(datasource);
+        const tableKey = this.toTableKey(schema ?? null, tableName);
+        const selectedTable = inventory.recordsByKey.get(tableKey);
+        if (!selectedTable) {
+            throw new NotFoundException(`Table "${tableName}" was not found on datasource "${datasource.name}".`);
+        }
+
+        const provider = this.getProvider(datasource.type);
+        const runtimeDataSource = this.resolveDataSourceByName(datasource.name);
+        const rawColumns = inventory.columnsByKey.get(tableKey) ?? [];
+        const detailColumns = rawColumns.map((column) => this.toDetailColumnRecord(column, selectedTable.suggestedLegacyTableType, datasource.type));
+        const userKeyCandidates = this.buildUserKeyCandidates(rawColumns);
+        const suggestedSingularName = this.toSingularNameCandidate(tableName);
+        const suggestedPluralName = this.toPluralNameCandidate(tableName, suggestedSingularName);
+        const rawDdl = await this.buildRawDdl(provider, runtimeDataSource, {
+            tableName: selectedTable.tableName,
+            tableSchema: selectedTable.schema,
+        });
+
+        return {
+            data: {
+                module: this.toModuleSummary(module),
+                datasource: this.toDatasourceSummary(datasource),
+                table: selectedTable,
+                columns: detailColumns,
+                rawDdl,
+                userKeyCandidates,
+                suggestedMetadata: {
+                    singularName: suggestedSingularName,
+                    pluralName: suggestedPluralName,
+                    displayName: startCase(suggestedSingularName),
+                    tableName: selectedTable.tableName,
+                    schema: selectedTable.schema,
+                    dataSource: datasource.name,
+                    dataSourceType: datasource.type,
+                    legacyTableType: selectedTable.suggestedLegacyTableType,
+                    baseClassName: selectedTable.suggestedBaseClassName,
+                    userKeyField: selectedTable.suggestedUserKeyField,
+                    synchronize: false,
+                },
+            },
+        };
+    }
+
+    async previewMapping(moduleId: number, mappingDto: DatasourceIntrospectionMappingDto) {
+        const plan = await this.buildMappingPreview(moduleId, mappingDto);
+
+        return {
+            data: {
+                operation: plan.operation,
+                mappedModelId: plan.mappedModelId,
+                metadataJson: plan.metadataJson,
+                migration: plan.migration,
+                summary: plan.summary,
+            },
+        };
+    }
+
+    async applyMapping(moduleId: number, mappingDto: DatasourceIntrospectionMappingDto) {
+        const plan = await this.buildMappingPreview(moduleId, mappingDto);
+
+        if (plan.operation === "update" && !mappingDto.modelId) {
+            throw new BadRequestException("Mapped tables require a model id before changes can be applied.");
+        }
+
+        const persistedModel = plan.operation === "update" && mappingDto.modelId
+            ? await this.modelMetadataService.update(mappingDto.modelId, plan.modelPayload as UpdateModelMetaDataDto)
+            : await this.modelMetadataService.create(plan.modelPayload as CreateModelMetadataDto);
+
+        if (plan.migration.willGenerate && plan.migration.content && plan.migration.filePath) {
+            await fs.mkdir(path.dirname(plan.migration.filePath), { recursive: true });
+            await fs.writeFile(plan.migration.filePath, plan.migration.content, "utf8");
+        }
+
+        const persistedModelId = mappingDto.modelId ?? (persistedModel as ModelMetadata | undefined)?.id ?? null;
+
+        return {
+            data: {
+                modelId: persistedModelId,
+                operation: plan.operation,
+                metadataJson: plan.metadataJson,
+                migration: {
+                    ...plan.migration,
+                    written: Boolean(plan.migration.willGenerate && plan.migration.filePath),
+                },
+                summary: plan.summary,
+            },
+        };
+    }
+
+    private async buildMappingPreview(moduleId: number, mappingDto: DatasourceIntrospectionMappingDto): Promise<MappingPreviewRecord> {
+        const module = await this.loadModule(moduleId);
+        const datasource = this.requireDatasource(mappingDto.dataSource);
+
+        if (datasource.synchronize === true) {
+            throw new BadRequestException(this.buildSynchronizeBlockedMessage(datasource));
+        }
+
+        const inventory = await this.buildTableInventory(datasource);
+        const tableKey = this.toTableKey(mappingDto.schema ?? null, mappingDto.tableName);
+        const tableRecord = inventory.recordsByKey.get(tableKey);
+        if (!tableRecord) {
+            throw new NotFoundException(`Table "${mappingDto.tableName}" was not found on datasource "${datasource.name}".`);
+        }
+
+        const existingModel = mappingDto.mapped && mappingDto.modelId
+            ? await this.modelMetadataRepository.findOne({
+                where: { id: mappingDto.modelId },
+                relations: ["fields", "module", "parentModel"],
+                order: {
+                    fields: {
+                        id: "ASC",
+                    },
+                },
+            })
+            : null;
+
+        if (mappingDto.mapped && !existingModel) {
+            throw new NotFoundException(`Mapped model "${mappingDto.modelId}" was not found.`);
+        }
+
+        const reviewedModel = this.normalizeReviewedMetadataModel(mappingDto.reviewedModel, mappingDto);
+        const modelPayload = reviewedModel
+            ? this.buildModelPayloadFromReviewedModel(moduleId, mappingDto, existingModel, reviewedModel)
+            : this.buildModelPayload(moduleId, mappingDto, existingModel);
+        const metadataJson = reviewedModel
+            ? await this.buildMetadataJsonPreviewFromReviewedModel(module.name, reviewedModel)
+            : await this.buildMetadataJsonPreview(module.name, mappingDto, existingModel);
+        const migration = await this.buildMigrationPreview(module.name, datasource, mappingDto, inventory.columnsByKey.get(tableKey) ?? []);
+        const includedColumnNames = mappingDto.columns
+            .filter((column) => !column.handledBySuperclass && column.include)
+            .map((column) => column.columnName);
+        const removedColumnNames = mappingDto.columns
+            .filter((column) => column.matched && !column.handledBySuperclass && !column.include)
+            .map((column) => column.columnName);
+
+        return {
+            operation: mappingDto.mapped ? "update" : "create",
+            mappedModelId: mappingDto.modelId ?? null,
+            metadataJson,
+            migration,
+            summary: {
+                includedColumnNames,
+                removedColumnNames,
+                missingSystemColumns: migration.missingSystemColumns,
+                generatedSystemColumnCount: migration.missingSystemColumns.length,
+            },
+            modelPayload,
+        };
+    }
+
+    private buildModelPayload(
+        moduleId: number,
+        mappingDto: DatasourceIntrospectionMappingDto,
+        existingModel: ModelMetadata | null,
+    ): CreateModelMetadataDto | UpdateModelMetaDataDto {
+        const includedColumns = mappingDto.columns.filter((column) => !column.handledBySuperclass && column.include);
+        const matchedFieldIds = new Set<number>(
+            mappingDto.columns
+                .filter((column) => typeof column.fieldId === "number")
+                .map((column) => column.fieldId as number),
+        );
+
+        const preservedFieldPayloads = existingModel
+            ? existingModel.fields
+                .filter((field) => field.isSystem || !matchedFieldIds.has(field.id))
+                .map((field) => this.sanitizeExistingFieldPayload(field))
+            : [];
+
+        const updatedFieldPayloads = includedColumns.map((column) => {
+            const existingField = existingModel?.fields?.find((field) => field.id === column.fieldId) ?? null;
+            return this.buildFieldPayload(column, mappingDto, existingField);
+        });
+
+        return {
+            singularName: mappingDto.singularName.trim(),
+            pluralName: mappingDto.pluralName.trim(),
+            displayName: mappingDto.displayName.trim(),
+            description: mappingDto.description.trim() || mappingDto.displayName.trim(),
+            dataSource: mappingDto.dataSource,
+            dataSourceType: mappingDto.dataSourceType,
+            tableName: mappingDto.tableName,
+            enableSoftDelete: mappingDto.enableSoftDelete,
+            enableAuditTracking: mappingDto.enableAuditTracking,
+            internationalisation: mappingDto.internationalisation,
+            draftPublishWorkflow: mappingDto.draftPublishWorkflow,
+            moduleId,
+            fields: [...preservedFieldPayloads, ...updatedFieldPayloads],
+            isSystem: false,
+            isChild: false,
+            parentModelId: null,
+            parentModelUserKey: "",
+            legacyTableType: mappingDto.legacyTableType,
+        };
+    }
+
+    private buildModelPayloadFromReviewedModel(
+        moduleId: number,
+        mappingDto: DatasourceIntrospectionMappingDto,
+        existingModel: ModelMetadata | null,
+        reviewedModel: ReviewedMetadataModel,
+    ): CreateModelMetadataDto | UpdateModelMetaDataDto {
+        const systemFieldPayloads = existingModel
+            ? existingModel.fields
+                .filter((field) => field.isSystem)
+                .map((field) => this.sanitizeExistingFieldPayload(field))
+            : [];
+
+        const reviewedFieldPayloads = reviewedModel.fields.map((field) => {
+            const matchedExistingField = this.matchExistingFieldForReviewedModel(field, mappingDto, existingModel);
+            return {
+                ...field,
+                ...(matchedExistingField?.id ? { id: matchedExistingField.id } : {}),
+                isUserKey: field.name === reviewedModel.userKeyFieldUserKey,
+                isSystem: field.isSystem ?? false,
+            };
+        });
+
+        return {
+            singularName: reviewedModel.singularName.trim(),
+            pluralName: reviewedModel.pluralName.trim(),
+            displayName: reviewedModel.displayName.trim(),
+            description: reviewedModel.description.trim() || reviewedModel.displayName.trim(),
+            dataSource: reviewedModel.dataSource,
+            dataSourceType: reviewedModel.dataSourceType,
+            tableName: reviewedModel.tableName,
+            enableSoftDelete: reviewedModel.enableSoftDelete,
+            enableAuditTracking: reviewedModel.enableAuditTracking,
+            internationalisation: reviewedModel.internationalisation,
+            draftPublishWorkflow: reviewedModel.draftPublishWorkflow,
+            moduleId,
+            fields: [...systemFieldPayloads, ...reviewedFieldPayloads],
+            isSystem: false,
+            isChild: false,
+            parentModelId: null,
+            parentModelUserKey: reviewedModel.parentModelUserKey ?? "",
+            legacyTableType: reviewedModel.legacyTableType,
+        };
+    }
+
+    private async buildMetadataJsonPreview(
+        moduleName: string,
+        mappingDto: DatasourceIntrospectionMappingDto,
+        existingModel: ModelMetadata | null,
+    ) {
+        const filePath = await this.moduleMetadataHelperService.getModuleMetadataFilePath(moduleName);
+        const previewFields = await this.buildMetadataPreviewFields(mappingDto, existingModel);
+
+        return {
+            filePath,
+            model: {
+                singularName: mappingDto.singularName.trim(),
+                pluralName: mappingDto.pluralName.trim(),
+                displayName: mappingDto.displayName.trim(),
+                description: mappingDto.description.trim() || mappingDto.displayName.trim(),
+                dataSource: mappingDto.dataSource,
+                dataSourceType: mappingDto.dataSourceType,
+                tableName: mappingDto.tableName,
+                userKeyFieldUserKey: mappingDto.userKeyField,
+                isChild: false,
+                legacyTableType: mappingDto.legacyTableType,
+                parentModelUserKey: "",
+                enableAuditTracking: mappingDto.enableAuditTracking,
+                enableSoftDelete: mappingDto.enableSoftDelete,
+                draftPublishWorkflow: mappingDto.draftPublishWorkflow,
+                internationalisation: mappingDto.internationalisation,
+                fields: previewFields,
+            },
+        };
+    }
+
+    private async buildMetadataJsonPreviewFromReviewedModel(
+        moduleName: string,
+        reviewedModel: ReviewedMetadataModel,
+    ) {
+        const filePath = await this.moduleMetadataHelperService.getModuleMetadataFilePath(moduleName);
+
+        return {
+            filePath,
+            model: reviewedModel,
+        };
+    }
+
+    private async buildMetadataPreviewFields(
+        mappingDto: DatasourceIntrospectionMappingDto,
+        existingModel: ModelMetadata | null,
+    ) {
+        const finalFields = new Map<string, any>();
+        const existingFields = existingModel?.fields ?? [];
+        const matchedFieldIds = new Set<number>(
+            mappingDto.columns
+                .filter((column) => typeof column.fieldId === "number")
+                .map((column) => column.fieldId as number),
+        );
+        const includedColumns = mappingDto.columns.filter((column) => !column.handledBySuperclass && column.include);
+
+        for (const field of existingFields) {
+            if (field.isSystem || !matchedFieldIds.has(field.id)) {
+                finalFields.set(this.toFieldPreviewKey(field.id, field.name), this.sanitizeExistingFieldPayload(field));
+            }
+        }
+
+        for (const column of includedColumns) {
+            const existingField = existingFields.find((field) => field.id === column.fieldId) ?? null;
+            const fieldPayload = this.buildFieldPayload(column, mappingDto, existingField);
+            finalFields.set(this.toFieldPreviewKey(fieldPayload.id ?? null, fieldPayload.name), fieldPayload);
+        }
+
+        for (const column of mappingDto.columns.filter((entry) => entry.matched && !entry.include && entry.fieldId)) {
+            const existingField = existingFields.find((field) => field.id === column.fieldId);
+            if (!existingField || existingField.isSystem) {
+                continue;
+            }
+
+            finalFields.set(
+                this.toFieldPreviewKey(existingField.id, existingField.name),
+                {
+                    ...this.sanitizeExistingFieldPayload(existingField),
+                    isMarkedForRemoval: true,
+                    isUserKey: false,
+                },
+            );
+        }
+
+        const serialized = Array.from(finalFields.values())
+            .filter((field) => !field.isSystem)
+            .map((field) => ({
+                ...field,
+                isUserKey: field.name === mappingDto.userKeyField,
+            }))
+            .sort((left, right) => {
+                const leftOrder = typeof left.id === "number" ? left.id : Number.MAX_SAFE_INTEGER;
+                const rightOrder = typeof right.id === "number" ? right.id : Number.MAX_SAFE_INTEGER;
+                if (leftOrder !== rightOrder) {
+                    return leftOrder - rightOrder;
+                }
+
+                return `${left.name}`.localeCompare(`${right.name}`);
+            });
+
+        const previewFields: Record<string, any>[] = [];
+        for (const field of serialized) {
+            previewFields.push(await this.fieldMetadataService.createFieldConfig(field as any));
+        }
+
+        return previewFields;
+    }
+
+    private async buildMigrationPreview(
+        moduleName: string,
+        datasource: DatasourceRecord,
+        mappingDto: DatasourceIntrospectionMappingDto,
+        tableColumns: DatasourceIntrospectionColumn[],
+    ) {
+        const systemColumnDefinitions = this.getLegacySystemColumnDefinitions(mappingDto.legacyTableType, datasource.type);
+        const existingColumns = new Set(tableColumns.map((column) => column.columnName.toLowerCase()));
+        const missingSystemColumns = systemColumnDefinitions.filter((definition) => !existingColumns.has(definition.columnName.toLowerCase()));
+        const removedLegacyMappings = mappingDto.columns.filter((column) => column.matched && !column.include && !column.handledBySuperclass);
+
+        if (!missingSystemColumns.length) {
+            return {
+                willGenerate: false,
+                filePath: null,
+                fileName: null,
+                className: null,
+                timestamp: mappingDto.plannedMigrationTimestamp ?? null,
+                content: null,
+                note: removedLegacyMappings.length
+                    ? "No migration will be generated for this change because it only updates metadata mapping for existing legacy columns."
+                    : "All required SolidX system columns already exist on this table, so no migration will be generated.",
+                missingSystemColumns: [],
+            };
+        }
+
+        const modulePath = await this.moduleMetadataHelperService.getModulePath(moduleName);
+        const migrationTimestamp = mappingDto.plannedMigrationTimestamp ?? Date.now();
+        const migrationBaseName = `Sync${startCase(this.toSingularNameCandidate(mappingDto.tableName)).replace(/\s+/g, "")}SolidxSystemFields`;
+        const className = `${migrationBaseName}${migrationTimestamp}`;
+        const fileName = `${migrationTimestamp}-${migrationBaseName}.ts`;
+        const filePath = path.join(modulePath, "migrations", datasource.name, fileName);
+
+        return {
+            willGenerate: true,
+            filePath,
+            fileName,
+            className,
+            timestamp: migrationTimestamp,
+            content: this.renderMigrationTemplate(className, mappingDto, missingSystemColumns),
+            note: `Saving this mapping will also write a template migration for the missing SolidX system columns: ${missingSystemColumns.map((column) => column.columnName).join(", ")}.`,
+            missingSystemColumns: missingSystemColumns.map((column) => column.columnName),
+        };
+    }
+
+    private sanitizeExistingFieldPayload(field: any) {
+        const {
+            createdAt,
+            updatedAt,
+            deletedAt,
+            model,
+            mediaStorageProvider,
+            identifier,
+            ...rest
+        } = field ?? {};
+
+        if (mediaStorageProvider?.id && !rest.mediaStorageProviderId) {
+            rest.mediaStorageProviderId = mediaStorageProvider.id;
+        }
+
+        return rest;
+    }
+
+    private normalizeReviewedMetadataModel(
+        reviewedModel: Record<string, any> | undefined,
+        mappingDto: DatasourceIntrospectionMappingDto,
+    ): ReviewedMetadataModel | null {
+        if (!reviewedModel) {
+            return null;
+        }
+
+        if (typeof reviewedModel !== "object" || Array.isArray(reviewedModel)) {
+            throw new BadRequestException("Reviewed metadata JSON must be a valid object.");
+        }
+
+        const readString = (key: string, allowEmpty = false) => {
+            const value = reviewedModel[key];
+            if (typeof value !== "string") {
+                throw new BadRequestException(`Reviewed metadata JSON is missing a valid "${key}" string value.`);
+            }
+
+            const trimmed = value.trim();
+            if (!allowEmpty && !trimmed) {
+                throw new BadRequestException(`Reviewed metadata JSON cannot leave "${key}" blank.`);
+            }
+
+            return trimmed;
+        };
+
+        const readBoolean = (key: string) => {
+            const value = reviewedModel[key];
+            if (typeof value !== "boolean") {
+                throw new BadRequestException(`Reviewed metadata JSON is missing a valid "${key}" boolean value.`);
+            }
+            return value;
+        };
+
+        const rawFields = reviewedModel.fields;
+        if (!Array.isArray(rawFields)) {
+            throw new BadRequestException("Reviewed metadata JSON must contain a fields array.");
+        }
+
+        const immutableKeyChecks: Array<{ key: keyof DatasourceIntrospectionMappingDto; label: string }> = [
+            { key: "dataSource", label: "dataSource" },
+            { key: "dataSourceType", label: "dataSourceType" },
+            { key: "tableName", label: "tableName" },
+            { key: "legacyTableType", label: "legacyTableType" },
+        ];
+
+        for (const check of immutableKeyChecks) {
+            if (`${reviewedModel[check.label] ?? ""}` !== `${mappingDto[check.key] ?? ""}`) {
+                throw new BadRequestException(`Reviewed metadata JSON cannot change immutable binding key "${check.label}".`);
+            }
+        }
+
+        const normalizedFields = rawFields.map((field, index) => this.normalizeReviewedField(field, index));
+        const fieldNames = new Set<string>();
+        for (const field of normalizedFields) {
+            const loweredName = field.name.toLowerCase();
+            if (fieldNames.has(loweredName)) {
+                throw new BadRequestException(`Reviewed metadata JSON contains duplicate field name "${field.name}".`);
+            }
+            fieldNames.add(loweredName);
+        }
+
+        const userKeyFieldUserKey = readString("userKeyFieldUserKey");
+        if (!normalizedFields.some((field) => field.name === userKeyFieldUserKey && !field.isMarkedForRemoval)) {
+            throw new BadRequestException("Reviewed metadata JSON must keep the selected userKeyFieldUserKey in the fields array.");
+        }
+
+        return {
+            singularName: readString("singularName"),
+            pluralName: readString("pluralName"),
+            displayName: readString("displayName"),
+            description: readString("description", true),
+            dataSource: readString("dataSource"),
+            dataSourceType: readString("dataSourceType"),
+            tableName: readString("tableName"),
+            userKeyFieldUserKey,
+            isChild: false,
+            legacyTableType: mappingDto.legacyTableType,
+            parentModelUserKey: typeof reviewedModel.parentModelUserKey === "string" ? reviewedModel.parentModelUserKey : "",
+            enableAuditTracking: readBoolean("enableAuditTracking"),
+            enableSoftDelete: readBoolean("enableSoftDelete"),
+            draftPublishWorkflow: readBoolean("draftPublishWorkflow"),
+            internationalisation: readBoolean("internationalisation"),
+            fields: normalizedFields.map((field) => ({
+                ...field,
+                isUserKey: field.name === userKeyFieldUserKey,
+            })),
+        };
+    }
+
+    private normalizeReviewedField(field: any, index: number) {
+        if (!field || typeof field !== "object" || Array.isArray(field)) {
+            throw new BadRequestException(`Reviewed metadata JSON field at index ${index} is not a valid object.`);
+        }
+
+        if (typeof field.name !== "string" || !field.name.trim()) {
+            throw new BadRequestException(`Reviewed metadata JSON field at index ${index} must include a non-empty "name".`);
+        }
+
+        if (typeof field.type !== "string" || !field.type.trim()) {
+            throw new BadRequestException(`Reviewed metadata JSON field "${field.name}" must include a non-empty "type".`);
+        }
+
+        if (typeof field.ormType !== "string" || !field.ormType.trim()) {
+            throw new BadRequestException(`Reviewed metadata JSON field "${field.name}" must include a non-empty "ormType".`);
+        }
+
+        if (typeof field.columnName !== "string" || !field.columnName.trim()) {
+            throw new BadRequestException(`Reviewed metadata JSON field "${field.name}" must include a non-empty "columnName".`);
+        }
+
+        return {
+            ...field,
+            name: field.name.trim(),
+            type: field.type.trim(),
+            ormType: field.ormType.trim(),
+            columnName: field.columnName.trim(),
+            displayName: typeof field.displayName === "string" && field.displayName.trim()
+                ? field.displayName.trim()
+                : startCase(field.name),
+            description: typeof field.description === "string" ? field.description : "",
+        };
+    }
+
+    private matchExistingFieldForReviewedModel(
+        reviewedField: Record<string, any>,
+        mappingDto: DatasourceIntrospectionMappingDto,
+        existingModel: ModelMetadata | null,
+    ) {
+        const nonSystemFields = existingModel?.fields?.filter((field) => !field.isSystem) ?? [];
+        const byColumnName = typeof reviewedField.columnName === "string"
+            ? mappingDto.columns.find((column) => column.columnName.toLowerCase() === reviewedField.columnName.toLowerCase())
+            : null;
+        if (byColumnName?.fieldId) {
+            return nonSystemFields.find((field) => field.id === byColumnName.fieldId) ?? null;
+        }
+
+        const byColumnOnExisting = typeof reviewedField.columnName === "string"
+            ? nonSystemFields.find((field) => `${field.columnName ?? ""}`.toLowerCase() === reviewedField.columnName.toLowerCase())
+            : null;
+        if (byColumnOnExisting) {
+            return byColumnOnExisting;
+        }
+
+        const byName = nonSystemFields.find((field) => field.name?.toLowerCase?.() === reviewedField.name.toLowerCase());
+        return byName ?? null;
+    }
+
+    private buildFieldPayload(
+        column: DatasourceIntrospectionMappingColumnDto,
+        mappingDto: DatasourceIntrospectionMappingDto,
+        existingField?: any,
+    ) {
+        const preserved = existingField ? this.sanitizeExistingFieldPayload(existingField) : {};
+        const maxLength =
+            column.characterMaximumLength && ["shortText", "longText"].includes(column.solidFieldType)
+                ? column.characterMaximumLength
+                : preserved.max;
+
+        return {
+            ...preserved,
+            ...(column.fieldId ? { id: column.fieldId } : {}),
+            name: column.fieldName,
+            displayName: preserved.displayName ?? startCase(column.fieldName),
+            description: preserved.description ?? "",
+            type: column.solidFieldType,
+            ormType: column.ormType,
+            length: preserved.length ?? column.characterMaximumLength ?? undefined,
+            defaultValue: preserved.defaultValue ?? column.defaultValue ?? undefined,
+            required: preserved.required ?? (!column.nullable || column.isPrimaryKey),
+            unique: preserved.unique ?? false,
+            encrypt: preserved.encrypt ?? false,
+            index: preserved.index ?? false,
+            max: maxLength ?? undefined,
+            min: preserved.min ?? undefined,
+            private: preserved.private ?? false,
+            isSystem: preserved.isSystem ?? false,
+            isMarkedForRemoval: false,
+            columnName: column.columnName,
+            isUserKey: mappingDto.userKeyField === column.fieldName,
+            enableAuditTracking: preserved.enableAuditTracking ?? mappingDto.enableAuditTracking,
+            isMultiSelect: preserved.isMultiSelect ?? false,
+            isPrimaryKey: column.isPrimaryKey,
+        };
+    }
+
+    private toFieldPreviewKey(id: number | null | undefined, name: string) {
+        return typeof id === "number" ? `id:${id}` : `name:${name.toLowerCase()}`;
+    }
+
+    private getLegacySystemColumnDefinitions(legacyTableType: LegacyTableType, datasourceType: string): SystemColumnDefinition[] {
+        const normalizedDatasourceType = datasourceType.toLowerCase();
+        const timestampType = normalizedDatasourceType === "postgres"
+            ? "timestamp"
+            : normalizedDatasourceType === "mysql"
+                ? "datetime"
+                : "datetime2";
+        const publishedAtType = normalizedDatasourceType === "postgres"
+            ? "timestamp"
+            : "datetime";
+        const integerType = normalizedDatasourceType === "postgres" ? "integer" : "int";
+        const varcharType = normalizedDatasourceType === "mssql" ? "nvarchar" : "varchar";
+        const currentTimestampDefault = normalizedDatasourceType === "postgres"
+            ? "now()"
+            : normalizedDatasourceType === "mysql"
+                ? "CURRENT_TIMESTAMP"
+                : "getdate()";
+        return this.modelMetadataHelperService
+            .getSystemFieldsMetadata(legacyTableType)
+            .map((field) => {
+                switch (field.name) {
+                    case "id":
+                        return {
+                            columnName: field.columnName,
+                            type: integerType,
+                            isNullable: false,
+                            isGenerated: true,
+                            isUnique: true,
+                        } satisfies SystemColumnDefinition;
+                    case "createdAt":
+                    case "updatedAt":
+                        return {
+                            columnName: field.columnName,
+                            type: timestampType,
+                            isNullable: false,
+                            defaultExpression: currentTimestampDefault,
+                        } satisfies SystemColumnDefinition;
+                    case "deletedAt":
+                        return {
+                            columnName: field.columnName,
+                            type: timestampType,
+                            isNullable: true,
+                        } satisfies SystemColumnDefinition;
+                    case "deletedTracker":
+                        return {
+                            columnName: field.columnName,
+                            type: varcharType,
+                            length: "255",
+                            isNullable: false,
+                            defaultExpression: "'not-deleted'",
+                        } satisfies SystemColumnDefinition;
+                    case "publishedAt":
+                        return {
+                            columnName: field.columnName,
+                            type: publishedAtType,
+                            isNullable: true,
+                        } satisfies SystemColumnDefinition;
+                    case "localeName":
+                        return {
+                            columnName: field.columnName,
+                            type: "varchar",
+                            length: "255",
+                            isNullable: true,
+                        } satisfies SystemColumnDefinition;
+                    case "defaultEntityLocaleId":
+                    case "createdBy":
+                    case "updatedBy":
+                        return {
+                            columnName: field.columnName,
+                            type: integerType,
+                            isNullable: true,
+                        } satisfies SystemColumnDefinition;
+                    default:
+                        return {
+                            columnName: field.columnName,
+                            type: "varchar",
+                            isNullable: true,
+                        } satisfies SystemColumnDefinition;
+                }
+            });
+    }
+
+    private renderMigrationTemplate(
+        className: string,
+        mappingDto: DatasourceIntrospectionMappingDto,
+        missingSystemColumns: SystemColumnDefinition[],
+    ) {
+        const tableNameLiteral = this.toMigrationTableName(mappingDto.schema, mappingDto.tableName);
+        const deletedAtIndexName = this.buildMigrationObjectName("IDX", tableNameLiteral, "ss_deleted_at");
+        const generatedIdUniqueName = this.buildMigrationObjectName("UQ", tableNameLiteral, "ss_id");
+
+        const upColumnStatements = missingSystemColumns.map((definition) => {
+            const columnLiteral = this.renderTableColumnLiteral(definition);
+            return [
+                `        if (!(await queryRunner.hasColumn(tableName, ${JSON.stringify(definition.columnName)}))) {`,
+                `            await queryRunner.addColumn(tableName, new TableColumn(${columnLiteral}));`,
+                "        }",
+            ].join("\n");
+        }).join("\n\n");
+
+        const postUpStatements: string[] = [];
+        if (missingSystemColumns.some((definition) => definition.columnName === "ss_deleted_at")) {
+            postUpStatements.push(
+                [
+                    "        {",
+                    "            const table = await queryRunner.getTable(tableName);",
+                    `            if (table && !table.indices.some((index) => index.name === ${JSON.stringify(deletedAtIndexName)})) {`,
+                    "                await queryRunner.createIndex(tableName, new TableIndex({",
+                    `                    name: ${JSON.stringify(deletedAtIndexName)},`,
+                    "                    columnNames: [\"ss_deleted_at\"],",
+                    "                }));",
+                    "            }",
+                    "        }",
+                ].join("\n"),
+            );
+        }
+        if (missingSystemColumns.some((definition) => definition.columnName === "ss_id")) {
+            postUpStatements.push(
+                [
+                    "        {",
+                    "            const table = await queryRunner.getTable(tableName);",
+                    `            if (table && !table.indices.some((index) => index.name === ${JSON.stringify(generatedIdUniqueName)})) {`,
+                    "                await queryRunner.createIndex(tableName, new TableIndex({",
+                    `                    name: ${JSON.stringify(generatedIdUniqueName)},`,
+                    "                    columnNames: [\"ss_id\"],",
+                    "                    isUnique: true,",
+                    "                }));",
+                    "            }",
+                    "        }",
+                ].join("\n"),
+            );
+        }
+
+        const downStatements: string[] = [];
+        if (missingSystemColumns.some((definition) => definition.columnName === "ss_id")) {
+            downStatements.push(
+                [
+                    "        {",
+                    "            const table = await queryRunner.getTable(tableName);",
+                    `            const index = table?.indices.find((entry) => entry.name === ${JSON.stringify(generatedIdUniqueName)});`,
+                    "            if (index) {",
+                    "                await queryRunner.dropIndex(tableName, index);",
+                    "            }",
+                    "        }",
+                ].join("\n"),
+            );
+        }
+        if (missingSystemColumns.some((definition) => definition.columnName === "ss_deleted_at")) {
+            downStatements.push(
+                [
+                    "        {",
+                    "            const table = await queryRunner.getTable(tableName);",
+                    `            const index = table?.indices.find((entry) => entry.name === ${JSON.stringify(deletedAtIndexName)});`,
+                    "            if (index) {",
+                    "                await queryRunner.dropIndex(tableName, index);",
+                    "            }",
+                    "        }",
+                ].join("\n"),
+            );
+        }
+        downStatements.push(
+            ...missingSystemColumns
+                .slice()
+                .reverse()
+                .map((definition) => [
+                    `        if (await queryRunner.hasColumn(tableName, ${JSON.stringify(definition.columnName)})) {`,
+                    `            await queryRunner.dropColumn(tableName, ${JSON.stringify(definition.columnName)});`,
+                    "        }",
+                ].join("\n")),
+        );
+
+        return [
+            "import { MigrationInterface, QueryRunner, TableColumn, TableIndex } from \"typeorm\";",
+            "",
+            `export class ${className} implements MigrationInterface {`,
+            `    name = '${className}'`,
+            "",
+            "    public async up(queryRunner: QueryRunner): Promise<void> {",
+            `        const tableName = ${JSON.stringify(tableNameLiteral)};`,
+            upColumnStatements,
+            postUpStatements.length ? `\n${postUpStatements.join("\n\n")}` : "",
+            "    }",
+            "",
+            "    public async down(queryRunner: QueryRunner): Promise<void> {",
+            `        const tableName = ${JSON.stringify(tableNameLiteral)};`,
+            downStatements.join("\n\n"),
+            "    }",
+            "}",
+            "",
+        ].filter(Boolean).join("\n");
+    }
+
+    private renderTableColumnLiteral(definition: SystemColumnDefinition) {
+        const properties: string[] = [
+            `{\n                name: ${JSON.stringify(definition.columnName)},`,
+            `                type: ${JSON.stringify(definition.type)},`,
+        ];
+
+        if (definition.length) {
+            properties.push(`                length: ${JSON.stringify(definition.length)},`);
+        }
+        if (typeof definition.isNullable === "boolean") {
+            properties.push(`                isNullable: ${definition.isNullable},`);
+        }
+        if (definition.defaultExpression) {
+            properties.push(`                default: ${JSON.stringify(definition.defaultExpression)},`);
+        }
+        if (definition.isGenerated) {
+            properties.push("                isGenerated: true,");
+            properties.push("                generationStrategy: \"increment\",");
+        }
+        if (definition.isUnique) {
+            properties.push("                isUnique: true,");
+        }
+
+        properties.push("            }");
+        return properties.join("\n");
+    }
+
+    private buildMigrationObjectName(prefix: string, tableName: string, columnName: string) {
+        const hash = createHash("md5").update(`${tableName}:${columnName}:${prefix}`).digest("hex").slice(0, 24);
+        return `${prefix}_${hash}`;
+    }
+
+    private toMigrationTableName(schema: string | null | undefined, tableName: string) {
+        return schema ? `${schema}.${tableName}` : tableName;
+    }
+
+    private async buildRawDdl(
+        provider: DatasourceIntrospectionProvider,
+        dataSource: DataSource,
+        table: DatasourceIntrospectionTableRef,
+    ): Promise<TableDdlRecord> {
+        try {
+            const statement = await provider.getTableDefinition(dataSource, table);
+            return {
+                statement,
+                available: Boolean(statement),
+                note: statement ? null : "The datasource provider did not return a CREATE TABLE statement for this table.",
+            };
+        } catch (error) {
+            return {
+                statement: null,
+                available: false,
+                note: `DDL preview is unavailable right now: ${(error as Error)?.message ?? "Unknown error."}`,
+            };
+        }
+    }
+
+    private async buildTableInventory(datasource: DatasourceRecord) {
+        const provider = this.getProvider(datasource.type);
+        const runtimeDataSource = this.resolveDataSourceByName(datasource.name);
+        const [tables, columns, models] = await Promise.all([
+            provider.listTables(runtimeDataSource),
+            provider.listColumns(runtimeDataSource),
+            this.modelMetadataRepository.find({ relations: { module: true } as any }),
+        ]);
+
+        const modelMap = this.buildModelMap(models);
+        const columnsByKey = this.groupColumnsByTable(columns);
+        const tableKeys = new Set<string>();
+
+        for (const table of tables) {
+            tableKeys.add(this.toTableKey(table.tableSchema, table.tableName));
+        }
+
+        for (const column of columns) {
+            tableKeys.add(this.toTableKey(column.tableSchema, column.tableName));
+        }
+
+        const records = Array.from(tableKeys)
+            .map((tableKey) => {
+                const matchingTable = tables.find((table) => this.toTableKey(table.tableSchema, table.tableName) === tableKey);
+                const tableColumns = columnsByKey.get(tableKey) ?? [];
+                const schema = matchingTable?.tableSchema ?? tableColumns[0]?.tableSchema ?? null;
+                const tableName = matchingTable?.tableName ?? tableColumns[0]?.tableName;
+                if (!tableName) {
+                    return null;
+                }
+
+                const suggestedLegacyTableType = this.detectLegacyTableType(datasource.type, tableColumns);
+                const suggestedIdColumn = this.getSuggestedIdColumn(datasource.type, tableColumns, suggestedLegacyTableType);
+                const mappedModel = modelMap.get(this.toModelMapKey(datasource.name, tableName)) ?? null;
+                const physicalColumns = tableColumns.filter((column) => !this.isHandledBySuperclass(column.columnName, suggestedLegacyTableType));
+
+                return {
+                    schema,
+                    tableName,
+                    mapped: Boolean(mappedModel),
+                    mappedModelId: mappedModel?.id ?? null,
+                    mappedModelSingularName: mappedModel?.singularName ?? null,
+                    mappedModelDisplayName: mappedModel?.displayName ?? null,
+                    mappedModuleId: mappedModel?.module?.id ?? null,
+                    mappedModuleName: mappedModel?.module?.name ?? null,
+                    mappedModuleDisplayName: mappedModel?.module?.displayName ?? null,
+                    suggestedLegacyTableType,
+                    suggestedBaseClassName: this.getBaseClassName(suggestedLegacyTableType),
+                    suggestedIdColumnName: suggestedIdColumn?.columnName ?? null,
+                    suggestedUserKeyField: this.buildUserKeyCandidates(tableColumns)[0]?.name ?? "id",
+                    columnCount: tableColumns.length,
+                    physicalColumnCount: physicalColumns.length,
+                } satisfies TableInventoryRecord;
+            })
+            .filter((record): record is TableInventoryRecord => Boolean(record))
+            .sort((left, right) => {
+                if (left.mapped !== right.mapped) {
+                    return left.mapped ? 1 : -1;
+                }
+
+                const leftLabel = `${left.schema ?? ""}.${left.tableName}`.toLowerCase();
+                const rightLabel = `${right.schema ?? ""}.${right.tableName}`.toLowerCase();
+                return leftLabel.localeCompare(rightLabel);
+            });
+
+        return {
+            records,
+            recordsByKey: new Map(records.map((record) => [this.toTableKey(record.schema, record.tableName), record])),
+            columnsByKey,
+        };
+    }
+
+    private buildModelMap(models: ModelMetadata[]) {
+        const map = new Map<string, ModelMetadata>();
+
+        for (const model of models) {
+            if (!model.tableName) {
+                continue;
+            }
+
+            map.set(this.toModelMapKey(model.dataSource, model.tableName), model);
+            map.set(this.toModelMapKey("*", model.tableName), model);
+        }
+
+        return map;
+    }
+
+    private groupColumnsByTable(columns: DatasourceIntrospectionColumn[]) {
+        const grouped = new Map<string, DatasourceIntrospectionColumn[]>();
+
+        for (const column of columns) {
+            const key = this.toTableKey(column.tableSchema, column.tableName);
+            const bucket = grouped.get(key);
+            if (bucket) {
+                bucket.push(column);
+                continue;
+            }
+
+            grouped.set(key, [column]);
+        }
+
+        return grouped;
+    }
+
+    private detectLegacyTableType(datasourceType: string, columns: DatasourceIntrospectionColumn[]): LegacyTableType {
+        const normalizedDatasourceType = datasourceType.toLowerCase();
+        const hasExistingGeneratedId = columns.some((column) => column.isAutoGenerated);
+
+        if ((normalizedDatasourceType === "mssql" || normalizedDatasourceType === "mysql") && hasExistingGeneratedId) {
+            return LegacyTableType.EXISTING_ID;
+        }
+
+        return LegacyTableType.GENERATED_ID;
+    }
+
+    private getSuggestedIdColumn(
+        datasourceType: string,
+        columns: DatasourceIntrospectionColumn[],
+        legacyTableType: LegacyTableType,
+    ) {
+        if (legacyTableType !== LegacyTableType.EXISTING_ID) {
+            return null;
+        }
+
+        const normalizedDatasourceType = datasourceType.toLowerCase();
+        if (normalizedDatasourceType !== "mssql" && normalizedDatasourceType !== "mysql") {
+            return null;
+        }
+
+        return columns.find((column) => column.isAutoGenerated) ?? null;
+    }
+
+    private buildUserKeyCandidates(columns: DatasourceIntrospectionColumn[]) {
+        const eligibleColumns = columns.filter((column) => !column.columnName.toLowerCase().startsWith("ss_"));
+        const scoreMap = new Map<string, { name: string; label: string; score: number; reason: string }>();
+        const priorityMatchers = [
+            { score: 100, reason: "Exact legacy external identifier", test: (name: string) => name === "external_id" || name === "externalid" },
+            { score: 95, reason: "Exact user key style column", test: (name: string) => name === "user_key" || name === "userkey" },
+            { score: 90, reason: "Code-style business identifier", test: (name: string) => name === "code" || name.endsWith("_code") },
+            { score: 85, reason: "Reference-style business identifier", test: (name: string) => name.includes("reference") || name.endsWith("_number") || name.endsWith("_no") },
+            { score: 80, reason: "Human readable display field", test: (name: string) => name === "name" || name === "display_name" || name.endsWith("_name") },
+            { score: 70, reason: "Contact field that could identify a record", test: (name: string) => name === "email" || name === "mobile" || name === "phone" },
+            { score: 60, reason: "Fallback primary identifier", test: (name: string) => name === "id" },
+        ];
+
+        for (const column of eligibleColumns) {
+            const normalizedName = column.columnName.toLowerCase();
+
+            for (const matcher of priorityMatchers) {
+                if (!matcher.test(normalizedName)) {
+                    continue;
+                }
+
+                const existing = scoreMap.get(column.columnName);
+                if (!existing || matcher.score > existing.score) {
+                    scoreMap.set(column.columnName, {
+                        name: this.toFieldName(column.columnName),
+                        label: column.columnName,
+                        score: matcher.score,
+                        reason: matcher.reason,
+                    });
+                }
+            }
+        }
+
+        const candidates = Array.from(scoreMap.values())
+            .sort((left, right) => right.score - left.score || left.label.localeCompare(right.label))
+            .map((candidate, index) => ({
+                ...candidate,
+                isDefault: index === 0,
+            }));
+
+        if (candidates.length) {
+            return candidates;
+        }
+
+        const hasIdColumn = eligibleColumns.some((column) => column.columnName.toLowerCase() === "id");
+        return [{
+            name: "id",
+            label: hasIdColumn ? "id" : "id (fallback)",
+            score: 0,
+            reason: "Default to the SolidX id field when no stronger user key candidate is available.",
+            isDefault: true,
+        }];
+    }
+
+    private toDetailColumnRecord(
+        column: DatasourceIntrospectionColumn,
+        legacyTableType: LegacyTableType,
+        datasourceType: string,
+    ): TableDetailColumnRecord {
+        const superclassFieldName = this.getSuperclassFieldName(column.columnName, legacyTableType);
+        const fieldName = legacyTableType === LegacyTableType.EXISTING_ID && column.isAutoGenerated
+            ? "id"
+            : this.toFieldName(column.columnName);
+
+        return {
+            columnName: column.columnName,
+            fieldName,
+            dataType: column.dataType,
+            solidFieldType: this.toSolidFieldType(column),
+            ormType: this.toOrmFieldType(column, datasourceType),
+            nullable: column.isNullable,
+            defaultValue: column.defaultValue,
+            characterMaximumLength: column.characterMaximumLength,
+            numericPrecision: column.numericPrecision,
+            numericScale: column.numericScale,
+            ordinalPosition: column.ordinalPosition,
+            isAutoGenerated: column.isAutoGenerated,
+            handledBySuperclass: Boolean(superclassFieldName),
+            superclassFieldName,
+        };
+    }
+
+    private getSuperclassFieldName(columnName: string, legacyTableType: LegacyTableType) {
+        return this.getLegacySuperclassFieldName(columnName, legacyTableType);
+    }
+
+    private getLegacySuperclassFieldName(columnName: string, legacyTableType: LegacyTableType) {
+        const normalized = columnName.toLowerCase();
+        const legacyFieldMap: Record<string, string> = {
+            ss_created_at: "createdAt",
+            ss_updated_at: "updatedAt",
+            ss_deleted_at: "deletedAt",
+            ss_deleted_tracker: "deletedTracker",
+            ss_published_at: "publishedAt",
+            ss_locale_name: "localeName",
+            ss_default_entity_locale_id: "defaultEntityLocaleId",
+            ss_created_by_id: "createdBy",
+            ss_updated_by_id: "updatedBy",
+        };
+
+        if (normalized === "ss_id" && legacyTableType === LegacyTableType.GENERATED_ID) {
+            return "id";
+        }
+
+        return legacyFieldMap[normalized] ?? null;
+    }
+
+    private isHandledBySuperclass(columnName: string, legacyTableType: LegacyTableType) {
+        return Boolean(this.getSuperclassFieldName(columnName, legacyTableType));
+    }
+
+    private getBaseClassName(legacyTableType: LegacyTableType) {
+        if (legacyTableType === LegacyTableType.GENERATED_ID) {
+            return "LegacyCommonEntityWithGeneratedId";
+        }
+
+        return "LegacyCommonEntityWithExistingId";
+    }
+
+    private toSolidFieldType(column: DatasourceIntrospectionColumn) {
+        const normalized = column.dataType.toLowerCase();
+        const charLength = column.characterMaximumLength ?? null;
+
+        if (["bit", "bool", "boolean"].includes(normalized)) {
+            return "boolean";
+        }
+
+        if (["bigint"].includes(normalized)) {
+            return "bigint";
+        }
+
+        if (["int", "integer", "smallint", "tinyint"].includes(normalized)) {
+            return "int";
+        }
+
+        if (["numeric", "decimal", "float", "double", "real", "money", "smallmoney"].includes(normalized)) {
+            return "decimal";
+        }
+
+        if (["date"].includes(normalized)) {
+            return "date";
+        }
+
+        if (["time"].includes(normalized)) {
+            return "time";
+        }
+
+        if (["datetime", "datetime2", "timestamp", "timestamptz", "smalldatetime"].includes(normalized) || normalized.includes("date")) {
+            return "datetime";
+        }
+
+        if (["json", "jsonb", "simple-json", "simplejson"].includes(normalized) || normalized.includes("json")) {
+            return "json";
+        }
+
+        if (["uniqueidentifier", "uuid"].includes(normalized)) {
+            return "uuid";
+        }
+
+        if (["text", "ntext", "mediumtext", "longtext", "clob"].includes(normalized)) {
+            return "longText";
+        }
+
+        if (["varchar", "nvarchar", "char", "nchar", "citext"].includes(normalized)) {
+            if (charLength !== null && charLength > 255) {
+                return "longText";
+            }
+
+            return "shortText";
+        }
+
+        return "shortText";
+    }
+
+    private toOrmFieldType(column: DatasourceIntrospectionColumn, datasourceType: string) {
+        const normalized = column.dataType.toLowerCase();
+        const normalizedDatasourceType = datasourceType.toLowerCase();
+
+        if (normalizedDatasourceType === "mssql") {
+            if (["bit", "bool", "boolean"].includes(normalized)) return "bit";
+            if (["bigint"].includes(normalized)) return "bigint";
+            if (["int", "integer", "smallint", "tinyint"].includes(normalized)) return "int";
+            if (["numeric"].includes(normalized)) return "numeric";
+            if (["decimal", "float", "double", "real", "money", "smallmoney"].includes(normalized)) return "decimal";
+            if (["date"].includes(normalized)) return "date";
+            if (["time"].includes(normalized)) return "time";
+            if (["datetime2"].includes(normalized)) return "datetime2";
+            if (["datetime", "smalldatetime", "timestamp"].includes(normalized) || normalized.includes("date")) return "datetime";
+            if (["json", "jsonb", "simple-json", "simplejson"].includes(normalized) || normalized.includes("json")) return "simple-json";
+            if (["uniqueidentifier", "uuid"].includes(normalized)) return "uniqueidentifier";
+            if (["text", "ntext", "mediumtext", "longtext", "clob"].includes(normalized)) return "text";
+            if (["nvarchar", "nchar"].includes(normalized)) return "nvarchar";
+            return "varchar";
+        }
+
+        if (normalizedDatasourceType === "mysql") {
+            if (["bigint"].includes(normalized)) return "int";
+            if (["int", "integer", "smallint", "tinyint"].includes(normalized)) return "int";
+            if (["decimal", "numeric"].includes(normalized)) return "decimal";
+            if (["float", "double", "real", "money", "smallmoney"].includes(normalized)) return "double";
+            if (["bit", "bool", "boolean"].includes(normalized)) return "boolean";
+            if (["date"].includes(normalized)) return "date";
+            if (["time"].includes(normalized)) return "time";
+            if (["datetime", "timestamp", "smalldatetime"].includes(normalized) || normalized.includes("date")) return "datetime";
+            if (["json", "jsonb", "simple-json", "simplejson"].includes(normalized) || normalized.includes("json")) return "json";
+            if (["mediumtext"].includes(normalized)) return "mediumtext";
+            if (["longtext", "text", "ntext", "clob"].includes(normalized)) return "longtext";
+            return "varchar";
+        }
+
+        if (["bigint"].includes(normalized)) return "bigint";
+        if (["int", "integer", "smallint", "tinyint"].includes(normalized)) return "integer";
+        if (["decimal", "numeric", "float", "double", "real", "money", "smallmoney"].includes(normalized)) return "decimal";
+        if (["bit", "bool", "boolean"].includes(normalized)) return "boolean";
+        if (["date"].includes(normalized)) return "date";
+        if (["time"].includes(normalized)) return "time";
+        if (["timestamptz"].includes(normalized)) return "timestamptz";
+        if (["datetime", "datetime2", "timestamp", "smalldatetime"].includes(normalized) || normalized.includes("date")) return "timestamp";
+        if (["jsonb"].includes(normalized)) return "jsonb";
+        if (["json", "simple-json", "simplejson"].includes(normalized) || normalized.includes("json")) return "json";
+        if (["text", "ntext", "mediumtext", "longtext", "clob"].includes(normalized)) return "text";
+        return "varchar";
+    }
+
+    private toFieldName(columnName: string) {
+        return camelCase(columnName.replace(/^ss_/, ""));
+    }
+
+    private toSingularNameCandidate(tableName: string) {
+        const normalized = camelCase(tableName);
+        if (normalized.endsWith("ies")) {
+            return `${normalized.slice(0, -3)}y`;
+        }
+
+        if (normalized.endsWith("ses")) {
+            return normalized.slice(0, -2);
+        }
+
+        if (normalized.endsWith("s") && !normalized.endsWith("ss")) {
+            return normalized.slice(0, -1);
+        }
+
+        return normalized;
+    }
+
+    private toPluralNameCandidate(tableName: string, singularName: string) {
+        const normalized = camelCase(tableName);
+        if (normalized && normalized !== singularName) {
+            return normalized;
+        }
+
+        if (singularName.endsWith("y")) {
+            return `${singularName.slice(0, -1)}ies`;
+        }
+
+        if (singularName.endsWith("s")) {
+            return `${singularName}es`;
+        }
+
+        return `${singularName}s`;
+    }
+
+    private toTableKey(schema: string | null, tableName: string) {
+        return `${(schema ?? "").toLowerCase()}::${tableName.toLowerCase()}`;
+    }
+
+    private toModelMapKey(datasourceName: string, tableName: string) {
+        return `${datasourceName.toLowerCase()}::${tableName.toLowerCase()}`;
+    }
+
+    private buildSynchronizeBlockedMessage(datasource: DatasourceRecord) {
+        return `Datasource "${datasource.displayName}" has synchronize enabled. Set ${datasource.envPrefix}_DATABASE_SYNCHRONIZE=false before starting legacy table introspection.`;
+    }
+
+    private resolveDataSourceByName(datasourceName: string) {
+        const token = datasourceName === "default" ? getDataSourceToken() : getDataSourceToken(datasourceName);
+
+        try {
+            const dataSource = this.moduleRef.get<DataSource>(token, { strict: false });
+            if (!dataSource) {
+                throw new NotFoundException(`Datasource "${datasourceName}" is not registered in the current runtime.`);
+            }
+
+            return dataSource;
+        } catch (error: any) {
+            throw new NotFoundException(
+                `Failed to resolve datasource "${datasourceName}": ${error?.message ?? error}`,
+            );
+        }
+    }
+
+    private getProvider(type: string): DatasourceIntrospectionProvider {
+        const providers: DatasourceIntrospectionProvider[] = [
+            this.mssqlProvider,
+            this.mysqlProvider,
+            this.postgresProvider,
+        ];
+
+        const provider = providers.find((candidate) => candidate.supports(type));
+        if (!provider) {
+            throw new BadRequestException(`Datasource type "${type}" is not supported for introspection yet.`);
+        }
+
+        return provider;
+    }
+
+    private requireDatasource(datasourceName: string) {
+        const datasource = this.datasourceManagementService.findOneByName(datasourceName);
+        if (!datasource) {
+            throw new NotFoundException(`Datasource "${datasourceName}" is not configured.`);
+        }
+
+        if (!this.supportedDatasourceTypes.has(datasource.type?.toLowerCase?.() ?? "")) {
+            throw new BadRequestException(`Datasource "${datasource.type}" is not supported for introspection yet.`);
+        }
+
+        return datasource;
+    }
+
+    private async loadModule(moduleId: number) {
+        const module = await this.moduleMetadataRepository.findOne({
+            where: { id: moduleId },
+        });
+
+        if (!module) {
+            throw new NotFoundException(`Module with id "${moduleId}" was not found.`);
+        }
+
+        return module;
+    }
+
+    private toModuleSummary(module: any) {
+        return {
+            id: module.id,
+            name: module.name,
+            displayName: module.displayName,
+            description: module.description ?? "",
+            defaultDataSource: module.defaultDataSource ?? "",
+        };
+    }
+
+    private toDatasourceSummary(record: DatasourceRecord) {
+        return {
+            name: record.name,
+            displayName: record.displayName,
+            type: record.type,
+            envPrefix: record.envPrefix,
+            isDefault: record.isDefault,
+            synchronize: record.synchronize,
+            host: record.host,
+            port: record.port,
+            database: record.database,
+        };
+    }
+}