package com.agent.management.service;

import com.agent.management.model.entity.KbDocument;
import org.springframework.web.multipart.MultipartFile;

import java.util.List;

public interface DocumentService {

    /**
     * 上传文件并触发异步处理（解析→分块→向量化→入库）
     *
     * @param file       文件
     * @param categoryId 分类 ID（可空表示未分类）
     * @return 创建的文档元数据（status=PENDING）
     */
    KbDocument upload(MultipartFile file, Long categoryId);

    /**
     * 列出文档（支持按分类/关键词过滤 + 分页）
     */
    PageResult list(Long categoryId, String keyword, int page, int size);

    /**
     * 获取文档详情
     */
    KbDocument get(Long id);

    /**
     * 重新向量化（重新执行 PENDING→READY 流程）
     */
    KbDocument revectorize(Long id);

    /**
     * 对文档中所有未向量化的分块执行向量化（不会清理已向量化的记录）
     */
    KbDocument vectorizeDocument(Long id);

    /**
     * 对单个未向量化的分块执行向量化
     */
    KbDocument vectorizeChunk(Long chunkId);

    /**
     * 删除文档（含文件、chunks、向量记录）
     */
    void delete(Long id);

    /**
     * 切换文档所属分类
     */
    KbDocument move(Long id, Long categoryId);

    /**
     * 查询某文档的分块内容（debug 用）
     */
    List<ChunkView> listChunks(Long documentId);

    /**
     * 分块视图（DTO）
     */
    record ChunkView(Long id, Integer chunkIndex, Integer chunkLevel, Integer charCount, String contentPreview, String content, String vectorId) {}

    /**
     * 简单分页结果（DTO）
     */
    record PageResult(List<KbDocument> items, long total, int page, int size) {}
}
