package com.ruoyi.phone.api;

import com.ruoyi.phone.domain.PhoneCallBackSHVO;
import com.ruoyi.phone.domain.PhoneCallBackVO;
import com.ruoyi.phone.domain.PhoneCallBackYQVO;
import com.ruoyi.phone.domain.PhoneCallRecordVO;
import com.ruoyi.phone.domain.PhoneCallReqYQVO;
import com.ruoyi.phone.domain.PhoneCallResultYQVO;
import com.ruoyi.phone.domain.PullTaskVO;
import com.ruoyi.task.domain.ServiceSubTaskDetailReq;

import java.util.List;

/**
 * 电话模块对外契约（<b>唯一对外包 {@code com.ruoyi.phone.api} 的入口</b>）。
 *
 * <h3>谁该用它</h3>
 * 其它模块（随访编排、定时任务、AI 机器人回调等）要"用到电话的功能"时，
 * 注入 {@link PhoneFacade}（常驻 Bean）调这里的方法；<b>不要</b>去注入本模块的
 * {@code IPhoneService} 实现、也不要 import 本模块的 controller/service 内部包。
 *
 * <h3>方法语义（与外部电话平台的回调一一对应，行为与原 {@code IServiceSubtaskService} 完全一致）</h3>
 * <ul>
 *   <li>{@link #phoneCallBack} —— 上海通道：语音识别结果上报，驱动多轮问答与挂机；</li>
 *   <li>{@link #phoneCallBackYQ} —— 雨绮通道：ASR / 静默 / 放音事件回调，返回下一步播报内容；</li>
 *   <li>{@link #taskPull} —— 雨绮通道：按小时配额拉取待外呼子任务（含开场白与首题）；</li>
 *   <li>{@link #saveQuestionAnswerPhone} —— 电话侧患者作答落库（走子任务明细）；</li>
 *   <li>{@link #recordAccept} —— 雨绮通道：通话记录回调（无人接听/已完成/拒访）；</li>
 *   <li>{@link #getFirstQues} / {@link #processResust} —— 三汇通道：取首题、ASR 结果处理。</li>
 * </ul>
 *
 * <h3>关闭时（{@code phone.enabled=false}）的行为</h3>
 * {@link PhoneFacade} 仍可注入，但所有方法<b>降级为空值/空列表并打 WARN，不抛异常</b>，
 * 保证调用方主流程不被拖垮（与满意度门面同一约束）。
 */
public interface PhoneApi {

    /**
     * 电话模块是否启用（运行时读 {@code sys_config: phone.enabled}，最多 10 秒生效）
     */
    boolean isEnabled();

    /**
     * 电话回调（上海）：语音识别结果上报
     *
     * @param phoneCallBackVO 回调入参（uuid + 识别文本）
     */
    void phoneCallBack(PhoneCallBackVO phoneCallBackVO);

    /**
     * 电话 ASR 通话回调（雨绮）
     *
     * @param phoneCallReqYQVO 回调入参（taskid 即子任务 ID + 当前题目的识别文本）
     * @return 下一步要播报的内容（type/value/silent_interval）；无可播报内容时返回空对象
     */
    PhoneCallBackYQVO phoneCallBackYQ(PhoneCallReqYQVO phoneCallReqYQVO);

    /**
     * 电话任务拉取（雨绮）
     *
     * @return 待外呼任务列表；无可拉取数据时返回空列表
     */
    List<PullTaskVO> taskPull();

    /**
     * 患者问题结果记录（电话）
     *
     * @param serviceSubTaskDetailReq 明细集合（入参为子任务 ID 或 taskid+patid 加密串）
     * @return 落库条数；模块关闭时返回 0
     */
    Integer saveQuestionAnswerPhone(ServiceSubTaskDetailReq serviceSubTaskDetailReq);

    /**
     * 通话记录回调（雨绮）
     *
     * @param phoneCallRecordVO 通话记录（挂断原因、录音路径等）
     * @return 处理结果（固定 1，保持原实现语义）
     */
    Integer recordAccept(PhoneCallRecordVO phoneCallRecordVO);

    /**
     * 根据电话号码获取首个问题（三汇）
     *
     * @param phoneCallReqYQVO 入参（phone）
     * @return 子任务 ID + 首题题号/内容；查不到时返回仅含默认 status 的空对象
     */
    PhoneCallBackSHVO getFirstQues(PhoneCallReqYQVO phoneCallReqYQVO);

    /**
     * 三汇 ASR 结果处理
     *
     * @param phoneCallResultYQVO ASR 结果（subId、scriptId、识别文本）
     * @return 下一题内容；匹配失败且重问次数用尽时返回题目切换结果
     */
    PhoneCallBackSHVO processResust(PhoneCallResultYQVO phoneCallResultYQVO);
}