/**
 * @file customer_tag.h
 * @brief 自定义标签消息解析（{"XCUSTOM":{...}} 格式）
 */

#ifndef CUSTOMER_TAG_H
#define CUSTOMER_TAG_H

#include <stddef.h>
#include <stdbool.h>

#ifdef __cplusplus
extern "C" {
#endif

/* ==========================================================================
 * 消息类型枚举
 * ========================================================================== */

typedef enum {
    TAG_MSG_TYPE_UNKNOWN = 0,
    TAG_MSG_TYPE_IDENTIFY,          /**< 拍万物 — 物体识别 */
    TAG_MSG_TYPE_SHOOT_CHINESE,     /**< 拍图识字 — 中文 */
    TAG_MSG_TYPE_SHOOT_ENGLISH,     /**< 拍图识字 — 英文 */
} tag_msg_type_t;

/* ==========================================================================
 * 解析结果结构体
 * ========================================================================== */

/** 数组元素最大个数 */
#define TAG_MAX_ARRAY_ITEMS    8
/** 字符串字段最大长度 */
#define TAG_MAX_STRING_LEN     128
/** 拼音/组词数组单项最大长度 */
#define TAG_MAX_ITEM_LEN       64

/* ---------- 拍万物 (identify) ---------- */

/**
 * @brief 单个汉字教学信息 (comments_ch.characters[] 元素)
 */
typedef struct {
    char name[TAG_MAX_ITEM_LEN];           /**< 汉字 */
    char pronunciation[TAG_MAX_ITEM_LEN];  /**< 拼音 */
    char meaning[TAG_MAX_STRING_LEN];      /**< 单字释义 */
    char words[TAG_MAX_ARRAY_ITEMS][TAG_MAX_ITEM_LEN]; /**< 组词 */
    int  words_count;
    char sentence[TAG_MAX_STRING_LEN];     /**< 例句 */
} tag_character_info_t;

/**
 * @brief 拍万物识别结果
 *
 * JSON 结构:
 * { "identify": {
 *     "name_ch": "...", "name_en": "...",
 *     "comments_ch": { "characters": [{name,pronunciation,meaning,words[],sentence}] },
 *     "comments_en": { "name": "...", "sentence": "...", "meaning": "..." }
 * }}
 */
typedef struct {
    char name_ch[TAG_MAX_STRING_LEN];      /**< 中文名称 */
    char name_en[TAG_MAX_STRING_LEN];      /**< 英文名称 */
    /* comments_ch.characters[] */
    tag_character_info_t characters[TAG_MAX_ARRAY_ITEMS];
    int  characters_count;
    /* comments_en */
    struct {
        char name[TAG_MAX_STRING_LEN];     /**< 英文名称 */
        char sentence[TAG_MAX_STRING_LEN]; /**< 英文例句 */
        char meaning[TAG_MAX_STRING_LEN];  /**< 英文例句翻译 */
    } comments_en;
} tag_identify_result_t;

/* ---------- 拍图识字-中文 (shoot_chinese) ---------- */

/**
 * @brief 拍图识字(中文)结果
 *
 * JSON 结构:
 * { "shoot_chinese": {
 *     "name": "字", "pronunciation": "拼音",
 *     "meaning": "释义", "words": [...], "example_sentence": "..."
 * }}
 */
typedef struct {
    char name[TAG_MAX_ITEM_LEN];           /**< 汉字 */
    char pronunciation[TAG_MAX_ITEM_LEN];  /**< 拼音 */
    char meaning[TAG_MAX_STRING_LEN];      /**< 释义 */
    char words[TAG_MAX_ARRAY_ITEMS][TAG_MAX_ITEM_LEN];
    int  words_count;
    char example_sentence[TAG_MAX_STRING_LEN]; /**< 例句 */
} tag_chinese_result_t;

/* ---------- 拍图识字-英文 (shoot_english) ---------- */

/**
 * @brief 拍图识字(英文)结果
 *
 * JSON 结构:
 * { "shoot_english": {
 *     "name_en": "word", "comment": "中文翻译",
 *     "sentence": "英文例句", "meaning": "例句翻译"
 * }}
 */
typedef struct {
    char name_en[TAG_MAX_STRING_LEN];      /**< 英文名称 */
    char comment[TAG_MAX_STRING_LEN];      /**< 中文翻译 */
    char sentence[TAG_MAX_STRING_LEN];     /**< 英文例句 */
    char meaning[TAG_MAX_STRING_LEN];      /**< 英文例句中文翻译 */
} tag_english_result_t;

/* ---------- 统一解析结果 ---------- */

typedef struct {
    tag_msg_type_t type;
    union {
        tag_identify_result_t identify;
        tag_chinese_result_t  chinese;
        tag_english_result_t  english;
    } data;
} tag_msg_info_t;

/* ==========================================================================
 * API
 * ========================================================================== */

/**
 * @brief 从事件数据中提取并解析 TAG 消息
 *
 * 在事件字符串中查找 JSON 内容，通过 key 判断类型并解析。
 *
 * @param event_data  事件数据 (可能包含前缀，函数会自动跳到 '{')
 * @param data_len    数据长度
 * @param out_info    [out] 解析结果
 * @return true 解析成功, false 未解析到结果
 */
bool tag_msg_parse(const char *event_data, size_t data_len, tag_msg_info_t *out_info);

/**
 * @brief 获取消息类型名称
 */
const char *tag_msg_type_name(tag_msg_type_t type);

#ifdef __cplusplus
}
#endif

#endif /* CUSTOMER_TAG_H */
