Initial import of firmware and host projects

inc/time_manager.h

@@ -0,0 +1,69 @@
+#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__ */