leaudit-platform-frontend/app/api/dify-dataset/api/segmentApi.ts

/**
 * Dify Dataset 分段、子分段、检索 API 模块
 *
 * 提供浏览器端调用 Dify 分段管理和检索 API 的函数
 *
 * @module api/dify-dataset/api/segmentApi
 */

import axios from 'axios';
import type {
    Segment,
    SegmentsResponse,
    CreateSegmentRequest,
    UpdateSegmentRequest,
    CreateSegmentsResponse,
    ChildChunk,
    ChildChunksResponse,
    CreateChildChunkResponse,
    RetrieveRequest,
    RetrieveResponse,
    OperationResult,
} from '../type';

/**
 * API 基础 URL
 */
const API_URL = '/api/dataset';

// ============================================================================
// 分段 API
// ============================================================================

/**
 * 获取文档分段列表
 *
 * @param datasetId - 知识库 ID
 * @param documentId - 文档 ID
 * @param page - 页码，默认 1
 * @param limit - 每页数量，默认 20
 * @param keyword - 搜索关键词
 * @returns 分段列表响应
 */
export async function fetchSegments(
    datasetId: string,
    documentId: string,
    page: number = 1,
    limit: number = 20,
    keyword?: string
): Promise<SegmentsResponse> {
    const params = new URLSearchParams({
        page: page.toString(),
        limit: limit.toString(),
    });

    if (keyword) {
        params.append('keyword', keyword);
    }

    console.log('[Dataset Client] 获取分段列表:', { datasetId, documentId, page, limit });

    const response = await axios.get<SegmentsResponse>(
        `${API_URL}/datasets/${datasetId}/documents/${documentId}/segments?${params}`,
        { withCredentials: true }
    );
    return response.data;
}

/**
 * 获取单个分段详情
 *
 * @param datasetId - 知识库 ID
 * @param documentId - 文档 ID
 * @param segmentId - 分段 ID
 * @returns 分段详情
 */
export async function fetchSegment(
    datasetId: string,
    documentId: string,
    segmentId: string
): Promise<Segment> {
    console.log('[Dataset Client] 获取分段详情:', { datasetId, documentId, segmentId });

    const response = await axios.get<{ data: Segment }>(
        `${API_URL}/datasets/${datasetId}/documents/${documentId}/segments/${segmentId}`,
        { withCredentials: true }
    );
    return response.data.data;
}

/**
 * 新增分段（批量）
 * Dify API: POST /datasets/{dataset_id}/documents/{document_id}/segments
 *
 * @param datasetId - 知识库 ID
 * @param documentId - 文档 ID
 * @param segments - 分段列表
 * @returns 创建的分段列表
 */
export async function createSegments(
    datasetId: string,
    documentId: string,
    segments: CreateSegmentRequest[]
): Promise<CreateSegmentsResponse> {
    console.log('[Dataset Client] 新增分段:', { datasetId, documentId, count: segments.length });

    const response = await axios.post<CreateSegmentsResponse>(
        `${API_URL}/datasets/${datasetId}/documents/${documentId}/segments`,
        { segments },
        {
            headers: { 'Content-Type': 'application/json' },
            withCredentials: true,
        }
    );
    return response.data;
}

/**
 * 更新分段内容
 * Dify API: POST /datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}
 *
 * @param datasetId - 知识库 ID
 * @param documentId - 文档 ID
 * @param segmentId - 分段 ID
 * @param segment - 更新内容
 * @returns 更新后的分段
 */
export async function updateSegment(
    datasetId: string,
    documentId: string,
    segmentId: string,
    segment: UpdateSegmentRequest
): Promise<{ data: Segment; doc_form: string }> {
    console.log('[Dataset Client] 更新分段:', { datasetId, documentId, segmentId, segment });

    const response = await axios.post<{ data: Segment; doc_form: string }>(
        `${API_URL}/datasets/${datasetId}/documents/${documentId}/segments/${segmentId}`,
        { segment },
        {
            headers: { 'Content-Type': 'application/json' },
            withCredentials: true,
        }
    );
    return response.data;
}

/**
 * 删除分段
 *
 * @param datasetId - 知识库 ID
 * @param documentId - 文档 ID
 * @param segmentId - 分段 ID
 * @returns 操作结果
 */
export async function deleteSegment(
    datasetId: string,
    documentId: string,
    segmentId: string
): Promise<OperationResult> {
    console.log('[Dataset Client] 删除分段:', { datasetId, documentId, segmentId });

    const response = await axios.delete<OperationResult>(
        `${API_URL}/datasets/${datasetId}/documents/${documentId}/segments/${segmentId}`,
        { withCredentials: true }
    );
    return response.data;
}

/**
 * 启用/禁用分段
 * Dify API: POST /datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}
 * 通过更新分段的方式来切换状态
 *
 * @param datasetId - 知识库 ID
 * @param documentId - 文档 ID
 * @param segmentId - 分段 ID
 * @param enabled - 是否启用
 * @returns 操作结果
 */
export async function toggleSegmentStatus(
    datasetId: string,
    documentId: string,
    segmentId: string,
    enabled: boolean
): Promise<OperationResult> {
    console.log('[Dataset Client] 切换分段状态:', { datasetId, documentId, segmentId, enabled });

    const response = await axios.post<OperationResult>(
        `${API_URL}/datasets/${datasetId}/documents/${documentId}/segments/${segmentId}`,
        { segment: { enabled } },
        {
            headers: { 'Content-Type': 'application/json' },
            withCredentials: true,
        }
    );
    return response.data;
}

// ============================================================================
// 子分段 API（父子模式）
// ============================================================================

/**
 * 获取子分段列表
 * Dify API: GET /datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks
 *
 * @param datasetId - 知识库 ID
 * @param documentId - 文档 ID
 * @param segmentId - 分段 ID
 * @param page - 页码
 * @param limit - 每页数量
 * @param keyword - 搜索关键词
 * @returns 子分段列表响应
 */
export async function fetchChildChunks(
    datasetId: string,
    documentId: string,
    segmentId: string,
    page: number = 1,
    limit: number = 20,
    keyword?: string
): Promise<ChildChunksResponse> {
    const params = new URLSearchParams({
        page: page.toString(),
        limit: limit.toString(),
    });

    if (keyword) {
        params.append('keyword', keyword);
    }

    console.log('[Dataset Client] 获取子分段列表:', { datasetId, documentId, segmentId, page, limit });

    const response = await axios.get<ChildChunksResponse>(
        `${API_URL}/datasets/${datasetId}/documents/${documentId}/segments/${segmentId}/child_chunks?${params}`,
        { withCredentials: true }
    );
    return response.data;
}

/**
 * 新增子分段
 * Dify API: POST /datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks
 *
 * @param datasetId - 知识库 ID
 * @param documentId - 文档 ID
 * @param segmentId - 分段 ID
 * @param content - 子分段内容
 * @returns 创建的子分段
 */
export async function createChildChunk(
    datasetId: string,
    documentId: string,
    segmentId: string,
    content: string
): Promise<CreateChildChunkResponse> {
    console.log('[Dataset Client] 新增子分段:', { datasetId, documentId, segmentId });

    const response = await axios.post<CreateChildChunkResponse>(
        `${API_URL}/datasets/${datasetId}/documents/${documentId}/segments/${segmentId}/child_chunks`,
        { content },
        {
            headers: { 'Content-Type': 'application/json' },
            withCredentials: true,
        }
    );
    return response.data;
}

/**
 * 更新子分段
 * Dify API: PATCH /datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}
 *
 * @param datasetId - 知识库 ID
 * @param documentId - 文档 ID
 * @param segmentId - 分段 ID
 * @param childChunkId - 子分段 ID
 * @param content - 更新内容
 * @returns 更新后的子分段
 */
export async function updateChildChunk(
    datasetId: string,
    documentId: string,
    segmentId: string,
    childChunkId: string,
    content: string
): Promise<ChildChunk> {
    console.log('[Dataset Client] 更新子分段:', { datasetId, documentId, segmentId, childChunkId });

    const response = await axios.patch<{ data: ChildChunk }>(
        `${API_URL}/datasets/${datasetId}/documents/${documentId}/segments/${segmentId}/child_chunks/${childChunkId}`,
        { content },
        {
            headers: { 'Content-Type': 'application/json' },
            withCredentials: true,
        }
    );
    return response.data.data;
}

/**
 * 删除子分段
 * Dify API: DELETE /datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}
 *
 * @param datasetId - 知识库 ID
 * @param documentId - 文档 ID
 * @param segmentId - 分段 ID
 * @param childChunkId - 子分段 ID
 * @returns 操作结果
 */
export async function deleteChildChunk(
    datasetId: string,
    documentId: string,
    segmentId: string,
    childChunkId: string
): Promise<OperationResult> {
    console.log('[Dataset Client] 删除子分段:', { datasetId, documentId, segmentId, childChunkId });

    const response = await axios.delete<OperationResult>(
        `${API_URL}/datasets/${datasetId}/documents/${documentId}/segments/${segmentId}/child_chunks/${childChunkId}`,
        { withCredentials: true }
    );
    return response.data;
}

// ============================================================================
// 检索 API
// ============================================================================

/**
 * 检索知识库
 * Dify API: POST /datasets/{dataset_id}/retrieve
 *
 * @param datasetId - 知识库 ID
 * @param query - 检索关键词
 * @param retrievalModel - 检索模型配置
 * @returns 检索结果
 */
export async function retrieveDataset(
    datasetId: string,
    query: string,
    retrievalModel?: RetrieveRequest['retrieval_model']
): Promise<RetrieveResponse> {
    console.log('[Dataset Client] 检索知识库:', { datasetId, query });

    const requestBody: RetrieveRequest = {
        query,
        retrieval_model: retrievalModel,
    };

    const response = await axios.post<RetrieveResponse>(
        `${API_URL}/datasets/${datasetId}/retrieve`,
        requestBody,
        {
            headers: { 'Content-Type': 'application/json' },
            withCredentials: true,
        }
    );
    return response.data;
}