package com.guo.learningprogresstracker.service;

import com.guo.learningprogresstracker.entity.ReviewRecallRecordEntity;
import com.guo.learningprogresstracker.entity.ReviewStandardMindMapEntity;
import com.guo.learningprogresstracker.exception.NotFindEntitiesException;
import com.guo.learningprogresstracker.exception.OperationFailedException;

import java.util.List;
import java.util.Map;

/**
 * 标准思维导图服务。
 * <p>负责标准导图的按需生成、查询、用户编辑，以及用户回忆导图的对比。</p>
 */
public interface StandardMindMapService {

    /**
     * 获取指定任务的标准思维导图，不存在时自动生成。
     */
    ReviewStandardMindMapEntity getOrGenerate(String taskNum) throws NotFindEntitiesException, OperationFailedException;

    /**
     * 强制重新生成指定任务的标准思维导图。
     */
    ReviewStandardMindMapEntity regenerate(String taskNum) throws NotFindEntitiesException, OperationFailedException;

    /**
     * 增量更新：保留用户编辑过的节点，合并最新生成的节点。
     */
    ReviewStandardMindMapEntity incrementalGenerate(String taskNum) throws NotFindEntitiesException, OperationFailedException;

    /**
     * 用户手动编辑标准思维导图（用缩进大纲文本替换）。
     */
    ReviewStandardMindMapEntity updateByOutline(String taskNum, String outline) throws NotFindEntitiesException;

    /**
     * 用户提交回忆大纲，与标准导图对比并返回结果。
     *
     * @param recallOutline 用户回忆的缩进大纲文本
     * @param focusPath     可选：标准导图中的节点路径（/ 分隔），指定后仅对比该子树
     */
    ReviewStandardMindMapEntity recallCompare(String taskNum, String recallOutline, String focusPath) throws NotFindEntitiesException, OperationFailedException;

    /**
     * 根据内容文本在标准导图中查找最匹配的节点，返回节点路径。
     *
     * @return { "path": "节点A / 节点B", "nodeTitle": "节点B", "score": 0.85 }
     */
    Map<String, Object> findNode(String taskNum, String content) throws NotFindEntitiesException, OperationFailedException;

    /**
     * 获取该任务的所有回忆对比记录。
     */
    List<ReviewRecallRecordEntity> listRecallRecords(String taskNum) throws NotFindEntitiesException;

    /**
     * 获取单条对比记录详情。
     */
    ReviewRecallRecordEntity getRecallRecord(Integer recordId) throws NotFindEntitiesException;
}