esengine/packages/core/src/ECS/Serialization/VersionMigration.ts

/**
 * 版本迁移系统
 *
 * 提供组件和场景数据的版本迁移支持
 */

import { SerializedComponent } from './ComponentSerializer';
import { SerializedScene } from './SceneSerializer';

/**
 * 组件迁移函数
 */
export type ComponentMigrationFunction = (data: any, fromVersion: number, toVersion: number) => any;

/**
 * 场景迁移函数
 */
export type SceneMigrationFunction = (
    scene: SerializedScene,
    fromVersion: number,
    toVersion: number
) => SerializedScene;

/**
 * 版本迁移管理器
 */
export class VersionMigrationManager {
    /**
     * 组件迁移函数注册表
     * Map<组件类型名, Map<版本号, 迁移函数>>
     */
    private static componentMigrations = new Map<string, Map<number, ComponentMigrationFunction>>();

    /**
     * 场景迁移函数注册表
     * Map<版本号, 迁移函数>
     */
    private static sceneMigrations = new Map<number, SceneMigrationFunction>();

    /**
     * 注册组件迁移函数
     *
     * @param componentType 组件类型名称
     * @param fromVersion 源版本号
     * @param toVersion 目标版本号
     * @param migration 迁移函数
     *
     * @example
     * ```typescript
     * // 从版本1迁移到版本2
     * VersionMigrationManager.registerComponentMigration(
     *     'PlayerComponent',
     *     1,
     *     2,
     *     (data) => {
     *         // 添加新字段
     *         data.experience = 0;
     *         return data;
     *     }
     * );
     * ```
     */
    public static registerComponentMigration(
        componentType: string,
        fromVersion: number,
        toVersion: number,
        migration: ComponentMigrationFunction
    ): void {
        if (!this.componentMigrations.has(componentType)) {
            this.componentMigrations.set(componentType, new Map());
        }

        const versionMap = this.componentMigrations.get(componentType)!;

        // 使用fromVersion作为key，表示"从这个版本迁移"
        versionMap.set(fromVersion, migration);
    }

    /**
     * 注册场景迁移函数
     *
     * @param fromVersion 源版本号
     * @param toVersion 目标版本号
     * @param migration 迁移函数
     *
     * @example
     * ```typescript
     * VersionMigrationManager.registerSceneMigration(
     *     1,
     *     2,
     *     (scene) => {
     *         // 迁移场景结构
     *         scene.metadata = { ...scene.metadata, migratedFrom: 1 };
     *         return scene;
     *     }
     * );
     * ```
     */
    public static registerSceneMigration(
        fromVersion: number,
        toVersion: number,
        migration: SceneMigrationFunction
    ): void {
        this.sceneMigrations.set(fromVersion, migration);
    }

    /**
     * 迁移组件数据
     *
     * @param component 序列化的组件数据
     * @param targetVersion 目标版本号
     * @returns 迁移后的组件数据
     */
    public static migrateComponent(
        component: SerializedComponent,
        targetVersion: number
    ): SerializedComponent {
        const currentVersion = component.version;

        if (currentVersion === targetVersion) {
            return component; // 版本相同，无需迁移
        }

        const migrations = this.componentMigrations.get(component.type);
        if (!migrations) {
            console.warn(`No migration path found for component ${component.type}`);
            return component;
        }

        let migratedData = { ...component };
        let version = currentVersion;

        // 执行迁移链
        while (version < targetVersion) {
            const migration = migrations.get(version);

            if (!migration) {
                console.warn(
                    `Missing migration from version ${version} to ${version + 1} for ${component.type}`
                );
                break;
            }

            migratedData.data = migration(migratedData.data, version, version + 1);
            version++;
        }

        migratedData.version = version;
        return migratedData;
    }

    /**
     * 迁移场景数据
     *
     * @param scene 序列化的场景数据
     * @param targetVersion 目标版本号
     * @returns 迁移后的场景数据
     */
    public static migrateScene(scene: SerializedScene, targetVersion: number): SerializedScene {
        const currentVersion = scene.version;

        if (currentVersion === targetVersion) {
            return scene; // 版本相同，无需迁移
        }

        let migratedScene = { ...scene };
        let version = currentVersion;

        // 执行场景级迁移
        while (version < targetVersion) {
            const migration = this.sceneMigrations.get(version);

            if (!migration) {
                console.warn(`Missing scene migration from version ${version} to ${version + 1}`);
                break;
            }

            migratedScene = migration(migratedScene, version, version + 1);
            version++;
        }

        migratedScene.version = version;

        // 迁移所有组件
        migratedScene = this.migrateSceneComponents(migratedScene);

        return migratedScene;
    }

    /**
     * 迁移场景中所有组件的版本
     */
    private static migrateSceneComponents(scene: SerializedScene): SerializedScene {
        const migratedScene = { ...scene };

        migratedScene.entities = scene.entities.map(entity => ({
            ...entity,
            components: entity.components.map(component => {
                // 查找组件的目标版本
                const typeInfo = scene.componentTypeRegistry.find(
                    t => t.typeName === component.type
                );

                if (typeInfo && typeInfo.version !== component.version) {
                    return this.migrateComponent(component, typeInfo.version);
                }

                return component;
            }),
            children: this.migrateEntitiesComponents(entity.children, scene.componentTypeRegistry)
        }));

        return migratedScene;
    }

    /**
     * 递归迁移实体的组件
     */
    private static migrateEntitiesComponents(
        entities: any[],
        typeRegistry: Array<{ typeName: string; version: number }>
    ): any[] {
        return entities.map(entity => ({
            ...entity,
            components: entity.components.map((component: SerializedComponent) => {
                const typeInfo = typeRegistry.find(t => t.typeName === component.type);

                if (typeInfo && typeInfo.version !== component.version) {
                    return this.migrateComponent(component, typeInfo.version);
                }

                return component;
            }),
            children: this.migrateEntitiesComponents(entity.children, typeRegistry)
        }));
    }

    /**
     * 清除所有迁移函数
     */
    public static clearMigrations(): void {
        this.componentMigrations.clear();
        this.sceneMigrations.clear();
    }

    /**
     * 获取组件的迁移路径
     *
     * @param componentType 组件类型名称
     * @returns 可用的迁移版本列表
     */
    public static getComponentMigrationPath(componentType: string): number[] {
        const migrations = this.componentMigrations.get(componentType);
        if (!migrations) {
            return [];
        }

        return Array.from(migrations.keys()).sort((a, b) => a - b);
    }

    /**
     * 获取场景的迁移路径
     *
     * @returns 可用的场景迁移版本列表
     */
    public static getSceneMigrationPath(): number[] {
        return Array.from(this.sceneMigrations.keys()).sort((a, b) => a - b);
    }

    /**
     * 检查是否可以迁移组件
     *
     * @param componentType 组件类型名称
     * @param fromVersion 源版本
     * @param toVersion 目标版本
     * @returns 是否存在完整的迁移路径
     */
    public static canMigrateComponent(
        componentType: string,
        fromVersion: number,
        toVersion: number
    ): boolean {
        if (fromVersion === toVersion) {
            return true;
        }

        const migrations = this.componentMigrations.get(componentType);
        if (!migrations) {
            return false;
        }

        // 检查是否存在完整的迁移路径
        for (let v = fromVersion; v < toVersion; v++) {
            if (!migrations.has(v)) {
                return false;
            }
        }

        return true;
    }

    /**
     * 检查是否可以迁移场景
     *
     * @param fromVersion 源版本
     * @param toVersion 目标版本
     * @returns 是否存在完整的迁移路径
     */
    public static canMigrateScene(fromVersion: number, toVersion: number): boolean {
        if (fromVersion === toVersion) {
            return true;
        }

        // 检查是否存在完整的场景迁移路径
        for (let v = fromVersion; v < toVersion; v++) {
            if (!this.sceneMigrations.has(v)) {
                return false;
            }
        }

        return true;
    }
}

/**
 * 便捷的迁移构建器
 *
 * 提供链式API来定义迁移
 */
export class MigrationBuilder {
    private componentType?: string;
    private fromVersion: number = 1;
    private toVersion: number = 2;

    /**
     * 设置组件类型
     */
    public forComponent(componentType: string): this {
        this.componentType = componentType;
        return this;
    }

    /**
     * 设置版本范围
     */
    public fromVersionToVersion(from: number, to: number): this {
        this.fromVersion = from;
        this.toVersion = to;
        return this;
    }

    /**
     * 注册迁移函数
     */
    public migrate(migration: ComponentMigrationFunction | SceneMigrationFunction): void {
        if (this.componentType) {
            VersionMigrationManager.registerComponentMigration(
                this.componentType,
                this.fromVersion,
                this.toVersion,
                migration as ComponentMigrationFunction
            );
        } else {
            VersionMigrationManager.registerSceneMigration(
                this.fromVersion,
                this.toVersion,
                migration as SceneMigrationFunction
            );
        }
    }
}