/*
 *      Copyright (c) 2018-2028, Chill Zhuang All rights reserved.
 *
 *  Redistribution and use in source and binary forms, with or without
 *  modification, are permitted provided that the following conditions are met:
 *
 *  Redistributions of source code must retain the above copyright notice,
 *  this list of conditions and the following disclaimer.
 *  Redistributions in binary form must reproduce the above copyright
 *  notice, this list of conditions and the following disclaimer in the
 *  documentation and/or other materials provided with the distribution.
 *  Neither the name of the dreamlu.net developer nor the names of its
 *  contributors may be used to endorse or promote products derived from
 *  this software without specific prior written permission.
 *  Author: Chill 庄骞 (smallchill@163.com)
 */
package org.sxkj.gd.workorder.service;

import org.sxkj.gd.workorder.entity.GdClueEventStatusFlowEntity;
import org.sxkj.gd.workorder.vo.GdClueEventStatusFlowVO;
import org.springblade.core.mp.base.BaseService;

import java.util.List;

/**
 * 事件状态流转履历表 服务类
 *
 * @author system
 * @since 2026-07-29
 */
public interface IGdClueEventStatusFlowService extends BaseService<GdClueEventStatusFlowEntity> {

    /**
     * 根据事件ID查询状态流转记录列表
     * <p>
     * 按操作时间升序排列，用于时间线展示
     * </p>
     *
     * @param eventId 事件ID
     * @return 状态流转记录列表
     */
    List<GdClueEventStatusFlowVO> getStatusFlowsByEventId(Long eventId);

    /**
     * 插入状态流转记录
     * <p>
     * 仅用于内部调用，不允许外部修改
     * </p>
     *
     * @param eventId       事件ID
     * @param oldStatus     变更前状态
     * @param newStatus     变更后状态
     * @param operateContent 操作备注
     * @param operateTime   操作时间
     * @return 是否成功
     */
    boolean insertStatusFlow(Long eventId, Integer oldStatus, Integer newStatus, String operateContent, java.util.Date operateTime);

    /**
     * 根据事件ID查询状态时间线
     * <p>
     * 返回所有状态（包含已到达和未到达），并标识每个状态是否已到达。
     * 状态流转规则：
     * - 如果最后一条流转记录的目标状态是该状态，则已到达
     * - 如果最后一条流转记录的源状态是该状态，则未到达（已离开）
     * - 处置中(1)和已处置(3)可以来回切换
     * </p>
     *
     * @param eventId 事件ID
     * @return 状态时间线列表（按状态编码升序）
     */
    List<GdClueEventStatusFlowVO> getStatusTimeline(Long eventId);

}