using System.Collections;

namespace AibisDream.SaveSystem
{
    /// <summary>
    /// 快照提供者契约：将某一子系统的运行时状态与纯数据 DTO 互相转换。
    /// <para>
    /// 设计约定：DTO 不含事件、协程或 Unity 引用；<see cref="Capture"/> 只读，
    /// <see cref="Restore"/> 负责逐项写回。实现类通常很薄，实际逻辑在各 Manager 中。
    /// </para>
    /// </summary>
    public interface ISnapshotProvider
    {
        /// <summary>
        /// 稳定显式 id，用作 <see cref="SaveSnapshot.sections"/> 的 key。
        /// 见 <see cref="SnapshotProviderIds"/>，不使用 C# 类型全名。
        /// </summary>
        string SaveId { get; }

        /// <summary>
        /// 读档还原顺序。数值越小越先执行（如 scene=10 先于 actor=40）。
        /// </summary>
        int RestoreOrder { get; }

        /// <summary>从当前运行时捕获该子系统的快照 DTO；无可存内容时可返回 null。</summary>
        object Capture();

        /// <summary>将 DTO 逐项还原到运行时；可为协程以等待异步加载。</summary>
        IEnumerator Restore(object dto);
    }
}