/**
 * @file interact_manager.h
 * @brief AI Agent SDK - 交互模式策略管理器
 *
 * 基于策略模式管理交互模式切换，每种模式（Press/Wakeup/Continuous）
 * 通过各自的 ops 结构体定义行为。
 */

#ifndef CORE_INTERACT_MANAGER_H
#define CORE_INTERACT_MANAGER_H

#include "aiagent_types.h"

#ifdef __cplusplus
extern "C" {
#endif

/* 前向声明 */
typedef struct engine_internal_ctx engine_internal_ctx_t;

/**
 * @brief 按键事件类型
 */
typedef enum {
    INTERACT_KEY_PRESS = 0,
    INTERACT_KEY_RELEASE,
    INTERACT_KEY_LONG_PRESS,
} interact_key_event_t;

/**
 * @brief 交互模式操作表（策略接口）
 *
 * 每种交互模式实现此接口以定义其行为。
 */
typedef struct interact_mode_ops {
    const char *name;       /**< 模式名称（可读） */

    /**
     * @brief 进入此交互模式
     * @param ctx  引擎上下文
     * @return 0 成功, 负数 失败
     */
    int (*enter)(engine_internal_ctx_t *ctx);

    /**
     * @brief 退出此交互模式
     * @param ctx  引擎上下文
     * @return 0 成功, 负数 失败
     */
    int (*exit)(engine_internal_ctx_t *ctx);

    /**
     * @brief 处理按键按下事件
     * @param ctx  引擎上下文
     */
    void (*on_key_press)(engine_internal_ctx_t *ctx);

    /**
     * @brief 处理按键松开事件
     * @param ctx  引擎上下文
     */
    void (*on_key_release)(engine_internal_ctx_t *ctx);

    /**
     * @brief 处理长按事件
     * @param ctx  引擎上下文
     */
    void (*on_key_long_press)(engine_internal_ctx_t *ctx);

    /**
     * @brief 处理 TTS 开始播放事件
     * @param ctx  引擎上下文
     */
    void (*on_tts_start)(engine_internal_ctx_t *ctx);

    /**
     * @brief 处理 TTS 播放结束事件
     * @param ctx  引擎上下文
     */
    void (*on_tts_end)(engine_internal_ctx_t *ctx);

    /**
     * @brief 处理唤醒词检测事件
     * @param ctx  引擎上下文
     */
    void (*on_wakeword)(engine_internal_ctx_t *ctx);
} interact_mode_ops_t;

/**
 * @brief 初始化交互管理器
 *
 * @param ctx           引擎上下文
 * @param default_mode  初始交互模式
 * @return 0 成功, 负数 失败
 */
int interact_mgr_init(engine_internal_ctx_t *ctx, aiagent_interact_mode_t default_mode);

/**
 * @brief 切换交互模式
 *
 * 先调用当前模式的 exit()，再调用新模式的 enter()。
 *
 * @param ctx   引擎上下文
 * @param mode  目标交互模式
 * @return 0 成功, 负数 失败
 */
int interact_mgr_switch_mode(engine_internal_ctx_t *ctx, aiagent_interact_mode_t mode);

/**
 * @brief 重新进入当前交互模式
 *
 * 连接就绪后重新执行当前模式的 enter()。
 *
 * @param ctx  引擎上下文
 * @return 0 成功, 负数 失败
 */
int interact_mgr_reenter(engine_internal_ctx_t *ctx);

/**
 * @brief 获取当前交互模式
 *
 * @param ctx  引擎上下文
 * @return 当前交互模式枚举值
 */
aiagent_interact_mode_t interact_mgr_get_mode(engine_internal_ctx_t *ctx);

/**
 * @brief 获取当前交互模式名称
 *
 * @param ctx  引擎上下文
 * @return 模式名称字符串, 未初始化时返回 NULL
 */
const char *interact_mgr_get_mode_name(engine_internal_ctx_t *ctx);

/**
 * @brief 分发按键事件到当前模式
 *
 * @param ctx    引擎上下文
 * @param event  按键事件类型
 */
void interact_mgr_notify_key(engine_internal_ctx_t *ctx, interact_key_event_t event);

/**
 * @brief 分发 TTS 事件到当前模式
 *
 * @param ctx       引擎上下文
 * @param is_start  true 表示 TTS 开始, false 表示 TTS 结束
 */
void interact_mgr_notify_tts(engine_internal_ctx_t *ctx, bool is_start);

/**
 * @brief 分发唤醒词检测事件到当前模式
 *
 * @param ctx  引擎上下文
 */
void interact_mgr_notify_wakeword(engine_internal_ctx_t *ctx);

/**
 * @brief 释放交互管理器
 *
 * 退出当前模式并释放资源。
 *
 * @param ctx  引擎上下文
 */
void interact_mgr_deinit(engine_internal_ctx_t *ctx);

#ifdef __cplusplus
}
#endif

#endif /* CORE_INTERACT_MANAGER_H */
