/******************************************************************************
 * @file    usr_rtc.h
 * @brief   板级 RTC：硬件对时 + 客户读本地日历
 * @author  cyWu <1917507415@qq.com>
 * @date    2026.08.19
 * @version V1.1.0
 * @history
 * - V1.0.0, 2026.08.19, cyWu, 从模组固件移植至 SOC SDK
 * - V1.1.0, 2026.08.19, cyWu, 精简接口；usr_rtc_get_time 返回本地日历
 ******************************************************************************/

#ifndef __USR_RTC_H__
#define __USR_RTC_H__

#include <stdint.h>
#include "system/sys_time.h"

/*============================================================================*/
/* 宏定义                                                                     */
/*============================================================================*/

#define USR_RTC_YEAR_MIN          (2026u)     /**< 合法年份下限 */
#define USR_RTC_YEAR_MAX          (2098u)     /**< 合法年份上限 */
#define USR_RTC_TZ_ABS_MAX_S      (57600)     /**< 时区偏移绝对值上限（±16h） */
#define USR_RTC_SYNC_COMPENSATE_S (1u)        /**< 网关对时延迟补偿（秒） */

/*============================================================================*/
/* 错误码（init / set_from_unix）                                             */
/*============================================================================*/

typedef enum {
    USR_RTC_OK = 0,
    USR_RTC_ERR_PARAM,
    USR_RTC_ERR_NOT_INIT,
    USR_RTC_ERR_INVALID,   /**< 年份非法，等待 App 对时 */
} UsrRtc_Ret_t;

/*============================================================================*/
/* 外部接口                                                                   */
/*============================================================================*/

/**
 * @brief  打开 rtc 设备并加载时区
 * @return USR_RTC_OK=成功，USR_RTC_ERR_NOT_INIT=设备打开失败或 RTC 未使能
 */
UsrRtc_Ret_t usr_rtc_init(void);

/**
 * @brief  获取当前本地时间（客户常用）
 * @param  t 成功时写入年月日时分秒；失败时不改动
 * @return 1=已对时且读成功，0=未初始化/未对时/参数非法
 */
uint8_t usr_rtc_get_time(struct sys_time *t);

/**
 * @brief  App/网关 DEVICEINFO：UTC 秒 + 时区写入 RTC
 * @param  unix_utc UTC Unix 秒；0 无效
 * @param  tz_s     时区偏移秒（东八区 28800）
 * @return USR_RTC_OK=成功，USR_RTC_ERR_NOT_INIT=未初始化，USR_RTC_ERR_PARAM=参数非法，USR_RTC_ERR_INVALID=年份非法
 */
UsrRtc_Ret_t usr_rtc_set_from_unix(uint64_t unix_utc, int32_t tz_s);

#endif /* __USR_RTC_H__ */