package com.guo.learningprogresstracker.service;

import com.guo.learningprogresstracker.entity.StudyReportFragmentsEntity;
import com.guo.learningprogresstracker.entity.StudyReportsEntity;
import com.guo.learningprogresstracker.entity.TaskApplicationEntity;
import com.guo.learningprogresstracker.entity.TaskEntity;
import com.guo.learningprogresstracker.utils.MindMapNode;

import java.util.List;
import java.util.Optional;

/**
 * 思维导图 AI 生成客户端抽象。
 * <p>后续接入真实 AI 时实现此接口，通过 Spring {@code @Profile} / {@code @ConditionalOnProperty} 切换。
 * 当前由内置规则生成器 {@code BuiltinMindMapGenerator} 充当。</p>
 */
public interface MindMapAiClient {

    /**
     * 是否可用（例如：API Key 已配置）
     */
    boolean isAvailable();

    /**
     * 根据学习数据生成标准思维导图根节点
     *
     * @param task       学习任务
     * @param reports    该任务的全部学习报告
     * @param fragments  该任务的全部学习残片
     * @param applications 该任务的应用场景（可选）
     * @param clientHint 前端已有的大纲文本（可选，用于 AI 续写而非全量生成）
     * @return 标准思维导图的根节点；若无可生成数据则返回 {@link Optional#empty()}
     */
    Optional<MindMapNode> generate(TaskEntity task,
                                   List<StudyReportsEntity> reports,
                                   List<StudyReportFragmentsEntity> fragments,
                                   List<TaskApplicationEntity> applications,
                                   String clientHint);

    /**
     * 获取生成器标识（如 {@code BUILTIN} / {@code AI-4.5}）
     */
    String generatorName();
}