/**
 * @file scene_ai_study.h
 * @brief AI拍学机场景定义
 *
 * 提供子场景切换、视觉模式、增强Query、图片上传等接口
 */

#ifndef SCENE_AI_STUDY_H
#define SCENE_AI_STUDY_H

#include "aiagent_scene.h"
#include "scene_ai_study_config.h"

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief 获取AI拍学机场景操作表
 */
const aiagent_scene_ops_t *scene_ai_study_get_ops(void);

/**
 * @brief 切换子场景
 *
 * @param scene_type 子场景类型 (study_scene_type_t)
 * @return 0 成功, -1 失败
 */
int study_scene_setup(study_scene_type_t scene_type);

/**
 * @brief 设置视觉识别提示词模式
 *
 * 在 IMAGE_UNDERSTANDING 子场景下切换:
 * - "identify"       拍万物
 * - "shoot_chinese"  拍图识字(中文)
 * - "shoot_english"  拍图识字(英文)
 *
 * @param mode 模式字符串
 * @return 0 成功, -1 失败
 */
int study_scene_set_vision_prompt(const char *mode);

/**
 * @brief 设置增强 Query (文生图用)
 *
 * @param enhance_type 0=取消, 1=前置, 2=后置, 3=前后包裹
 * @param pre_query    前置文本
 * @param post_query   后置文本
 * @return 0 成功, -1 失败
 */
int study_scene_set_enhance_query(int enhance_type, const char *pre_query,
                                   const char *post_query);

/**
 * @brief 发送 JPEG 图片到服务端
 *
 * 用于: 拍万物、图生图、拍图识字
 *
 * @param jpeg_data JPEG 数据
 * @param jpeg_len  数据长度
 * @return 0 成功, -1 失败
 */
int study_scene_send_image(const uint8_t *jpeg_data, size_t jpeg_len);

/**
 * @brief 注册拍照回调
 *
 * 当服务端请求图片时，SDK 调用此回调通知应用层触发摄像头。
 * 应用层拍照完成后应调用 study_scene_send_image() 上传。
 */
void study_scene_register_photo_callback(void (*cb)(void));

#ifdef __cplusplus
}
#endif

#endif /* SCENE_AI_STUDY_H */
