package handler import ( "net/http" "strconv" "strings" "time" "github.com/agentmail/gateway/internal/lunar" "github.com/agentmail/gateway/internal/middleware" ) /* * ── 农历换算(给客户端的日历格子用)── * * # 为什么要有这个端点(而不是让每个客户端自带一份换算) * * WebUI 用 `lunar-javascript`,服务端用 `lunar-go` —— 都是同一个作者(6tail)的实现, * 所以换算结果一致。但这是**两份实现**,而农历是**天文算法**: * `lunar-javascript` 的 `lunar.js` 有 43 万字节、内部是日月位置的级数展开, * **没有一张可以照搬的小数据表**(实测:全文件最大的数字字面量是 16KB 的级数系数数组, * 不是"某年到某年的月长表")。因此"把它移植到 ArkTS"这条路等于**再写一遍天文算法**, * 两边迟早会在某个闰月或某个朔日上差一天 —— 而那种错**表现为日期错位,不是报错**。 * * 所以换算只在服务端做一次,各客户端取结果。鸿蒙那边原来就是"没做"(`CalendarPage.ets` * 的注释里写着),这个端点是把那条补上的前提。 * * # 形状 * * `GET /api/v1/calendar/lunar?from=YYYY-MM-DD&to=YYYY-MM-DD` * * 返回一个**按日期键索引的映射**(不是数组):客户端拿到后是 `map[iso] -> 标签`, * 直接按格子键查,不需要自己遍历比对。范围是**闭区间**,且必须给全(不给默认值 —— * 默认范围会让"我要的是 3 月"和"服务端以为我要这个月"悄悄不一致)。 * * {"lunar": {"2026-09-18": {"day_name":"廿二","month_name":"七月","is_first_day":false, * "text":"廿二","leap":false,"full":"二〇二六年七月廿二"}}} * * `text` 是**格子里直接显示的那个串**:初一显示月名(如「七月」)、其余显示日名 * (如「廿二」)—— 与 WebUI `lib/lunar.ts` 的 `cellLunarLabel()` 同一口径。 * 每格都写完整月日会让格子全是重复的月份字样,而格子只有几十像素宽。 * * 范围上限:**不超过 400 天**。这不是安全边界(换算很便宜),而是防"客户端传了一个 * 十年前到十年后的范围"把响应撑到几 MB —— 日历一次最多显示 6 周。 */ // lunarRangeMaxDays 是一次请求允许的最大天数(含首尾)。 const lunarRangeMaxDays = 400 // parseDateKey 解析 `YYYY-MM-DD`(**按 UTC**,与纯逻辑层同一口径)。 // // 不接 RFC3339 时间戳:这个端点的入参是"日期键"(格子的键), // 不是"瞬间"。混用会让时区偏移把日期挪一天 —— 而界面看起来完全正常。 func parseDateKey(s string) (time.Time, bool) { t, err := time.Parse("2006-01-02", s) if err != nil { return time.Time{}, false } return t, true } // LunarLabels 是单个日期的农历标签。 type LunarLabels struct { // DayName 农历日名(初一…三十) DayName string `json:"day_name"` // MonthName 农历月名(正…冬/腊,闰月带「闰」) MonthName string `json:"month_name"` // IsFirstDay 是否初一(客户端据此决定格子里显示月名还是日名) IsFirstDay bool `json:"is_first_day"` // Text 格子里直接显示的那个串(初一=月名,其余=日名) Text string `json:"text"` // Leap 是否闰月 Leap bool `json:"leap"` // Full 完整中文表示(「二〇二六年七月廿二」),给详情/表单预览用 Full string `json:"full"` } // lunarMonthNames 农历月名。十一/十二月习惯写「冬月」「腊月」—— // 与 `lunar-javascript` 的 `Lunar.getMonthInChinese()` 一致(实测它也是这两个字)。 var lunarMonthNames = []string{ "", "正", "二", "三", "四", "五", "六", "七", "八", "九", "十", "冬", "腊", } // lunarDayNames 农历日名查表。 // // ★ **不用正则从 `Date.String()` 里截**:实测日名前缀有五种形态 // (初一/十一/二十/廿一/三十),写一个覆盖全部的正则既难读又容易漏 —— // WebUI 那版就漏了「二十」,20 号会退化成显示整串「七月二十」。 // 这个表与 `client/electron/src/lib/lunar.ts` 的 `LUNAR_DAY_NAMES` 逐字一致。 var lunarDayNames = []string{ "", "初一", "初二", "初三", "初四", "初五", "初六", "初七", "初八", "初九", "初十", "十一", "十二", "十三", "十四", "十五", "十六", "十七", "十八", "十九", "二十", "廿一", "廿二", "廿三", "廿四", "廿五", "廿六", "廿七", "廿八", "廿九", "三十", } // labelsOf 把一个公历日期转成农历标签。 // // ★ 越界/异常一律回 *零值+false*,**不猜**:农历换算是天文算法, // 猜一个日子比不显示更糟("看着有农历、其实是错的"最难发现)。 // `lunar.FromSolar` 内部对极端年份会 panic 保护,这里再兜一层。 func labelsOf(t time.Time) (LunarLabels, bool) { var d lunar.Date ok := func() (good bool) { defer func() { if recover() != nil { good = false } }() d = lunar.FromSolar(t) return true }() if !ok { return LunarLabels{}, false } absMonth := d.Month leap := false if absMonth < 0 { absMonth = -absMonth leap = true } if absMonth < 1 || absMonth > 12 || d.Day < 1 || d.Day > 30 { return LunarLabels{}, false } monthName := lunarMonthNames[absMonth] + "月" if leap { /* 闰月的「闰」必须带上:否则闰六月与六月在格子里长得一模一样 */ monthName = "闰" + monthName } dayName := lunarDayNames[d.Day] if dayName == "" { return LunarLabels{}, false } full := d.String() /* * 格子里显示什么:**初一显示月名、其余显示日名**(纸质日历的惯例)。 * 与 WebUI `cellLunarLabel()` 同一口径 —— 两端格子里必须是同一个串, * 否则同一天在两端的日历上长得不一样。 */ text := dayName if d.Day == 1 { text = monthName } return LunarLabels{ DayName: dayName, MonthName: monthName, IsFirstDay: d.Day == 1, Text: text, Leap: leap, Full: full, }, true } // LunarLabelsHandler 处理 `GET /api/v1/calendar/lunar?from=&to=`。 func LunarLabelsHandler(w http.ResponseWriter, r *http.Request) { user := middleware.GetUser(r) if user == nil { Error(w, http.StatusUnauthorized, "not authenticated") return } fromStr := strings.TrimSpace(r.URL.Query().Get("from")) toStr := strings.TrimSpace(r.URL.Query().Get("to")) if fromStr == "" || toStr == "" { /* 不设默认值:默认范围会让"我要 3 月"与"服务端以为我要这个月"悄悄不一致 */ Error(w, http.StatusBadRequest, "from and to are required (YYYY-MM-DD)") return } from, okFrom := parseDateKey(fromStr) to, okTo := parseDateKey(toStr) if !okFrom || !okTo { Error(w, http.StatusBadRequest, "from and to must be YYYY-MM-DD") return } if to.Before(from) { Error(w, http.StatusBadRequest, "to must not be before from") return } days := int(to.Sub(from).Hours()/24) + 1 if days > lunarRangeMaxDays { Error(w, http.StatusBadRequest, "range too large: at most "+strconv.Itoa(lunarRangeMaxDays)+" days") return } out := make(map[string]LunarLabels, days) for d := from; !d.After(to); d = d.AddDate(0, 0, 1) { if labels, ok := labelsOf(d); ok { out[d.Format("2006-01-02")] = labels } /* * 换不出来就**不放进 map**(客户端查不到 ⇒ 那一格不显示农历), * 而不是塞一个空对象 —— 空对象会让客户端以为"这一天有农历、只是没内容"。 */ } JSON(w, http.StatusOK, map[string]interface{}{"lunar": out}) }