new_kbd/inc/time_manager.h

#ifndef TIME_MANAGER_H__
#define TIME_MANAGER_H__

#include <stdbool.h>
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

/*
 * 时间同步来源保持传输无关：
 * - BLE/USB/手动设置都复用同一套枚举；
 * - 后续如果新增其他同步链路，只需要补枚举值，不需要改事件语义。
 */
enum time_sync_source {
	TIME_SYNC_SOURCE_NONE = 0,
	TIME_SYNC_SOURCE_BLE,
	TIME_SYNC_SOURCE_USB,
	TIME_SYNC_SOURCE_MANUAL,
	TIME_SYNC_SOURCE_HID,
};

/*
 * 时间同步更新载荷：
 * - utc_ms 统一使用 UTC 毫秒时间戳，避免内部状态受本地时区影响；
 * - timezone_min 记录“显示层”所需的时区偏移，当前不拆 DST；
 * - accuracy_ms 允许上位机表达这次校时的可信度，未知时传 0 即可。
 */
struct time_sync_update {
	uint64_t utc_ms;
	int16_t timezone_min;
	uint32_t accuracy_ms;
	enum time_sync_source source;
};

/*
 * 时间快照用于提供给显示、日志或后续 USB/调试接口：
 * - synchronized=true 表示当前开机周期内已经收到有效校时；
 * - has_persisted_time=true 仅表示 flash 里存过一次历史校时，不代表当前时间仍然可信；
 * - ready=false 表示 time_manager 还没等到 settings_loader 完成初始化。
 */
struct time_manager_snapshot {
	uint64_t utc_ms;
	int16_t timezone_min;
	uint32_t accuracy_ms;
	enum time_sync_source source;
	bool ready;
	bool synchronized;
	bool has_persisted_time;
};

/* 返回当前模块是否已经完成初始化，供同步入口快速拒绝“过早写入”。 */
bool time_manager_is_ready(void);

/*
 * 获取当前时间快照：
 * - 返回 0：snapshot 已填充；
 * - 返回 -EINVAL：参数为空；
 * - 返回 -EAGAIN：模块未 ready；
 * - 返回 -ENODATA：当前开机周期尚未完成有效校时。
 */
int time_manager_get_snapshot(struct time_manager_snapshot *snapshot);

#ifdef __cplusplus
}
#endif

#endif /* TIME_MANAGER_H__ */