初始提交卡包 USB 工程

纳入固件源码、屏幕组件、nand_xfer 工具和文档。忽略本机构建产物、sdkconfig，以及含本机路径的依赖锁。

Co-authored-by: Cursor <[email protected]>

main/UI_DISPATCH/almanac_service.h

@@ -0,0 +1,26 @@
+#ifndef ALMANAC_SERVICE_H
+#define ALMANAC_SERVICE_H
+
+#include <stdbool.h>
+#include <stdint.h>
+
+typedef struct {
+    char lunar[24];
+    char dos[64];
+    char donts[64];
+} almanac_entry_t;
+
+typedef bool (*almanac_get_fn_t)(uint16_t year, uint8_t month, uint8_t day, almanac_entry_t *out, void *ctx);
+
+typedef struct {
+    almanac_get_fn_t get;
+    void *ctx;
+} almanac_provider_t;
+
+/* 设置外部数据提供者（例如 JSON 查表）；传 NULL 则回退内置实现 */
+void almanac_service_set_provider(const almanac_provider_t *provider);
+
+/* 按公历日期获取农历+宜忌；无外部 provider 时使用内置回退逻辑 */
+bool almanac_service_get(uint16_t year, uint8_t month, uint8_t day, almanac_entry_t *out);
+
+#endif /* ALMANAC_SERVICE_H */