package com.agent.management.service;

import com.agent.management.model.vo.WorkflowVersionVO;

import java.util.List;

/**
 * 工作流版本快照服务。
 *
 * <p>目录策略（方案C Q2 选项1）：
 * <ul>
 *   <li>旧版本目录：以数字 id 命名，如 {@code workflow-versions/12/_versions/...}，保留原样</li>
 *   <li>新版本目录：以 name 命名，如 {@code workflow-versions/my-flow/_versions/...}</li>
 *   <li>查询时优先尝试 name 目录，回退到 id 目录</li>
 *   <li>已存在 id 目录的工作流，继续沿用 id 目录以保持历史一致</li>
 * </ul>
 */
public interface WorkflowVersionService {

    /**
     * 创建快照（保存当前工作流数据为 v{n+1}）
     *
     * @param workflowId   工作流内部主键
     * @param workflowName 工作流唯一标识（kebab-case），用于新目录命名
     * @param graphData    图数据 JSON
     * @param snapshotName 快照内嵌的 name 字段（工作流 displayName 等，仅供回滚时恢复）
     * @param message      快照备注
     */
    int createSnapshot(Long workflowId, String workflowName, String graphData, String snapshotName, String message);

    /** 获取当前版本号（若从未创建版本则返回 0） */
    int getCurrentVersion(Long workflowId, String workflowName);

    /** 列出所有版本 */
    List<WorkflowVersionVO> listVersions(Long workflowId, String workflowName);

    /** 获取指定版本的 graphData JSON 内容 */
    String getVersionContent(Long workflowId, String workflowName, int version);

    /** 回滚到指定版本（将快照内容恢复到工作流，不创建新快照） */
    void rollback(Long workflowId, String workflowName, int version);

    /** 更新版本备注 */
    void updateVersionMessage(Long workflowId, String workflowName, int version, String message);
}
