Quizzman 陰陽曆計算系統架構與天文參考模型

Abstract

背景與問題： 東亞傳統陰陽曆與民用曆法民俗計算，兼具現代天體力學之精密數學模型與深厚之歷史文化規約。於分散式運算系統中，地方民用日界限、力學時投影以及天體星曆模型之細微不一致，極易引發定朔偏移、節氣錯位及干支推算失誤等重大邊界缺陷。
方法論： 本規範全面公佈 Quizzman 曆法計算引擎 @quizzman/qm-calendar（版本 1.2.0）之系統架構。系統整合高精度天文還原管線：基於國際標準之連續儒略日數（JDN）與儒略日（JD）轉換；依據 VSOP87 行星攝動理論（Jean Meeus 129項精簡展開式）求解太陽視黃經；採用 Meeus 第49章級數解析定朔天文時刻；引入 5 年連續線性混合模型消除地球自轉減速差值 $\Delta T$ 之躍變不連續性；並以 UTC 瞬時為基準求解二十四節氣並投影至民用日。同時，系統嚴格規範真太陽時（True Solar Time）與均時差（Equation of Time）校正、夜子時與晨子時（早子與正子）跨日界限、六十花甲子同餘計算、以節氣月支為準之十二建除神煞、錨定固定 JDN 之二十八宿序列，以及涵蓋越南八個歷史時區時期之溯源轉換體系。
成果： 演算法稽核完整識別並修復九項重大系統邊界缺陷（A01 至 A09）。經驗證之計算引擎在獨立基準測試中取得 100%（139/139）合格率，通過 834 項邊界測試向量，並於公元 1800 年至 2200 年間（共 146,462 個民用日）進行逐日雙向往返測試，取得零誤差完全吻合。比對美國海軍天文台（USNO）2024年二分二至點，太陽黃經絕對誤差 $|\Delta\lambda_\odot| < 0.0005^\circ$；定朔時刻比對 NASA 權威星曆，偏差小於 0.1 分鐘。
結論： @quizzman/qm-calendar 系統確立了具備高復現性之標準數學體系，作為現代東亞陰陽曆法研究與相關企業級運算之可執行唯一真理來源（Executable Source of Truth）。

1 Scope

本文件公佈 Quizzman 陰陽曆運算系統（@quizzman/qm-calendar）之技術架構規範、數學模型與規範性法則，涵蓋：

1. 時間尺度表達式及連續轉換為儒略日數（JDN）與儒略日（JD）之演算法。
2. 天體力學計算管線：VSOP87 行星攝動理論、天文定朔求解、均時差（EoT）及地球自轉減速差值（$\Delta T$）連續平滑模型。
3. 陰陽曆月劃分、以「無中氣置閏」為核心之置閏演算法，以及越南（UTC+07:00）與中國（UTC+08:00）曆日分歧之成因分析。
4. 傳統歷法週期之代數形式化：六十花甲子干支柱、夜子時與晨子時約定、十二建除與二十八宿。
5. 真太陽時校正及跨午夜時生效日數（effectiveJdn）於四柱命理運算中之同步傳遞機制。
6. 越南歷史上自 1906 年以前至 1975 年以後共八個時區演化時期之還原模型。
7. 演算法稽核報告、根本原因剖析及九大核心邊界缺陷（A01 至 A09）之修復方案。

本規範適用於 Quizzman 體系下所有民用曆書查詢、天文運算模組及歷史年表處理系統。

2 Normative references

下列引據文件為本規範施行所不可或缺之依據：

• ISO 8601-1:2019 ^[1], Date and time — Representations for information interchange — Part 1: Basic rules.
• ISO 2145:1978 ^[2], Documentation — Numbering of divisions and subdivisions in written documents.
• ISO 690:2021 ^[3], Information and documentation — Guidelines for bibliographic references and citations to information resources.
• Jean Meeus (1998) ^[4], Astronomical Algorithms, 2nd Edition, Willmann-Bell, Richmond, Virginia.
• P. Bretagnon, G. Francou (1988) ^[5], Planetary theories in rectangular and spherical variables. VSOP87 solutions, Astronomy and Astrophysics, Vol. 202, pp. 309–315.
• E. M. Standish (1998) ^[6], JPL Planetary and Lunar Ephemerides, DE405/LE405, JPL Interoffice Memorandum 312.F.
• R. S. Park et al. (2021) ^[7], The JPL Planetary and Lunar Ephemerides DE440 and DE441, The Astronomical Journal, Vol. 161, No. 3.
• J. Chapront, G. Francou (2003) ^[8], The lunar theory ELP/MPP02, Astronomy and Astrophysics, Vol. 404, pp. 735–742.
• F. Espenak, J. Meeus (2006) ^[9], Five Millennium Catalog of Solar Eclipses: -1999 to +3000, NASA TP-2006-214141.
• Hồ Ngọc Đức (2000) ^[10], Lunisolar Calendar Calculations and Vietnamese Standard Meridian, Leipzig University.
• IANA Time Zone Database (2026a) ^[11], Time Zone Database, Internet Assigned Numbers Authority.
• USNO & HMNAO (2023) ^[12], The Astronomical Almanac for the Year 2024, Washington: US Government Publishing Office.
• Hong Kong Observatory (2024) ^[13], Gregorian-Lunar Calendar Conversion Tables of the Hong Kong Observatory (1901–2100).
• Doãn Lộc, Mai Giác Thành (1741) ^[14], Khâm Định Hiệp Kỷ Biện Phương Thư (欽定協紀辨方書), 四庫全書子部術數類第807冊.
• Quách Thủ Kính, Vương Tuần (1281) ^[15], Thọ Thời Lịch (授時曆), 元史卷五十二至五十五.
• Lê Quý Đôn (1777) ^[16], Vân Đài Loại Ngữ (芸臺類語), 卷一：言造考.
• Quizzman Technical Reference (2026) ^[17], Quizzman Lunisolar Calendar Engine Technical Reference and Architecture v2.1.
• Quizzman Quality Group (2026) ^[18], Quizzman Calendar Engine Algorithm Audit and Fix Verification Report, Technical Dossier AUD-2026-CAL-02.

3 Terms and definitions

就本標準之目的而言，適用下列術語與定義：

3.1 civil day

於地方時標中持續 86,400 秒之時間區間，自地方時 00:00:00 至 24:00:00。

3.2 astronomical new moon

月球中心與太陽中心在地心視黃道坐標系中具有相同視黃經（相對黃經差為 $0^\circ$）之天文瞬時，東亞曆法通稱為「朔」或「定朔」。

3.3 major solar term

中氣，指太陽視黃經到達 $30^\circ$ 整數倍之瞬時（$\lambda_\odot = 0^\circ, 30^\circ, 60^\circ, \dots, 330^\circ$）。

3.4 minor solar term

節氣，指太陽視黃經到達 $15^\circ$ 奇數倍之瞬時（$\lambda_\odot = 15^\circ, 45^\circ, 75^\circ, \dots, 345^\circ$）。

3.5 true solar time

真太陽時，直接依據特定地理經度上視太陽之時角所量度之時間，等於地方平太陽時加上均時差（EoT）。

3.6 early rat and late rat

子時（23:00 至 01:00）之劃分規約。夜子時（Early Rat，23:00–23:59）隸屬於當日；晨子時（Late Rat / 正子，00:00–00:59）歸入次日。

4 Symbols and abbreviated terms

• $Y, M, D$: 格里高利公曆年、月、日。
• $\text{JDN}$: 儒略日數（Julian Day Number），自公元前4713年1月1日格林威治平午起計之連續整數日計數器。
• $\text{JD}$: 連續儒略日（Julian Date），包含日小數部分之實數。
• $\text{UT}$ / $\text{UTC}$: 世界時 / 協調世界時。
• $\text{TT}$: 地球力學時（Terrestrial Time），滿足 $\text{TT} = \text{UT} + \Delta T$。
• $\Delta T$: 力學時與世界時之差值（$\text{TT} - \text{UT1}$），反映地球自轉減速。
• $\tau$: 自 J2000.0 起算之儒略千年數（$10,000$ 個平太陽年）。
• $T$: 自 J2000.0 起算之儒略世紀數（$36,525$ 日）。
• $\lambda_\odot$: 太陽地心視黃經。
• $\text{EoT}$: 均時差（Equation of Time），真太陽時與平太陽時之差。
• $\text{LMT}$: 地方平太陽時。
• $\text{TST}$: 真太陽時。

5 Conventions and assumptions

1. 系統內部基準時間軸： Quizzman 分散式架構核心之所有事務與記錄 SHALL 統一以 UTC 存儲與運算。
2. 越南標準子午線： 越南國家標准陰陽曆依據東經 $105^\circ$ 子午線推算，對應固定時區 UTC+07:00（第 10 節規範之特定歷史時期除外）。
3. J2000.0 曆元： 2000年1月1日 12:00:00 TT 對應標準數值 $\text{JDN} = 2451545$ 及 $\text{JD} = 2451545.0$。
4. 連續時間折算規約： 整數指標為 $\text{JDN}$ 之日期，其 UTC 午夜 00:00:00 瞬時之連續儒略日值為 $\text{JD} = \text{JDN} - 0.5$。

6 Architectural framework of the calendar engine

@quizzman/qm-calendar 系統遵循清晰解耦之四層架構體系：

┌────────────────────────────────────────────────────────────────────────┐
│                        API & Application Layer                         │
│   solarToLunar, lunarToSolar, getHourCanChi, getDayCanChi, Almanac     │
├────────────────────────────────────────────────────────────────────────┤
│                       Calendar & Domain Layer                          │
│   Sóc (New Moon), Tiết Khí (Solar Terms), Nhuận, Can Chi, Trực, Tú     │
├────────────────────────────────────────────────────────────────────────┤
│                       Astronomy & Ephemeris Layer                      │
│   VSOP87 Sun Longitude, Meeus Ch.49 New Moon, Delta T Blend, EoT       │
├────────────────────────────────────────────────────────────────────────┤
│                       Time Base & Coordinate Layer                     │
│   Continuous Julian Date, Timezone Reductions, Geodetic Coordinates    │
└────────────────────────────────────────────────────────────────────────┘

主計算流程處理輸入公曆日期之步驟如下：

1. 讀取 $(Y, M, D)$ 及地方時，根據歷史年代與地理位置確定法定時區偏移量 $Z$。
2. 轉換為 UTC 基準之整數 $\text{JDN}$ 與連續 $\text{JD}$。
3. 轉換為地球力學時尺度（$\text{TT} = \text{UT} + \Delta T$）。
4. 藉由 VSOP87 理論計算太陽黃經，並依 Meeus 第 49 章級數求解定朔瞬時。
5. 將定朔瞬時投影至地方民用日區間 $[00:00:00, 24:00:00)$，以確定陰曆月初一日。
6. 掃描歲實區間（冬至至次年冬至）之二十四節氣，依「無中氣置閏」法則判定閏月。
7. 構造並輸出完整結果集：農曆年月日、干支八字、納音五行、十二建除、二十八宿及吉凶神煞。

7 Astronomical foundation and coordinate reduction

7.1 Continuous Julian Date conversion

格里曆公曆日轉換為儒略日數之標準天文公式為：

$$\text{JDN} = 367Y - \left\lfloor \frac{7(Y + \lfloor (M+9)/12 \rfloor)}{4} \right\rfloor + \left\lfloor \frac{275M}{9} \right\rfloor + D + 1,721,013.5$$

由於 $\text{JDN}$ 為錨定於中午（12:00:00 UTC）之整數日計數器，連續時間轉換為 $\text{JD}$ 必須嚴格減去半日：

$$\text{JD} = \text{JDN} + \frac{\text{hour} + \frac{\text{minute}}{60} + \frac{\text{second}}{3600}}{24} - 0.5$$

在 00:00:00 UTC 時，$\text{JD} = \text{JDN} - 0.5$；在 12:00:00 UTC 時，$\text{JD} = \text{JDN}$。此數學形式確保消除了天文星曆測試中的半日系統性偏差（參見第 11.4 節）。

7.2 Planetary reduction via VSOP87 theory

本引擎採用 VSOP87 行星攝動理論（Meeus 129項精簡展開式）計算地球日心黃經，並進一步推導太陽地心坐標。時間變數 $\tau$ 表示自 J2000.0 起之儒略千年數：

$$\tau = \frac{\text{JD} - 2451545.0}{365250}$$

日心黃經 $L$（弧度）以多項式展開：

$$L = \frac{L_0 + L_1\tau + L_2\tau^2 + L_3\tau^3 + L_4\tau^4 + L_5\tau^5}{10^8}$$

其中各階分量 $L_k$ 為三角週期項之諧波疊加：

$$L_k = \sum_{i=1}^{N_k} A_i \cos(B_i + C_i \tau)$$

項數分佈為：$L_0$（64項）、$L_1$（34項）、$L_2$（20項）、$L_3$（7項）、$L_4$（3項）、$L_5$（1項）。太陽視黃經 $\lambda_\odot$ 加上 $180^\circ$ 並計入光行差與章動修正後得出：

$$\lambda_\odot = L_{\text{heliocentric}} + 180^\circ - 0.00569^\circ - 0.00478^\circ \sin(\Omega)$$

其中 $\Omega = 125.04^\circ - 1934.136^\circ T$ 為月球升交點黃經。

7.3 Dynamical time reduction and continuous Delta T blending

系統採用 1620–2025 年之歷史經驗觀測表。為消除查表邊界（2025.0年為 $70.000\text{ s}$）與未來預測多項式（$74.467\text{ s}$）間之 $4.467\text{ s}$ 躍變不連續性，Quizzman 在 $[2025, 2030]$ 區間建構 5 年線性過渡平滑模型：

$$w = \frac{y - 2025}{5}, \quad y \in [2025, 2030]$$

$$\Delta T(y) = (1 - w) \times 70.0 + w \times P(y)$$

其中 $P(y)$ 為 Stephenson–Morrison 展開多項式。此舉確保時間軸之連續性，消除了跨越 2025 年時定朔與節氣計算之跳躍缺陷。

7.4 Astronomical New Moon determination

定朔時刻依 Jean Meeus 第 49 章演算法求解。相對於 1900.0 之朔望月序數 $k$ 為：

$$k = \lfloor (Y - 1900) \times 12.3685 \rfloor$$

平朔時刻展開為：

$$\text{JD}_{\text{mean}} = 2415020.75933 + 29.53058868k + 0.0001178T^2 - 0.000000155T^3 + 0.00033 \sin(166.56^\circ + 132.87^\circ T - 0.009173^\circ T^2)$$

計入 14 項主要週期性攝動校正項 $C_1$ 後，得出真朔天文時刻：

$$\text{JD}$${\text{soc}} = \text{JD}{\text{mean}} + C_1 - \frac{\Delta T}{86400}

8 Lunisolar calendar calculation algorithms

8.1 Assignment of lunar months and civil folding

於時區偏移為 $Z$ 之區域，民用日始於地方午夜。為確定農曆每月初一日，系統求解定朔時刻 $\text{JD}_{\text{soc}}$ 之地方民用日：

$$D_{\text{soc}} = \left\lfloor \text{JD}_{\text{soc}} + 0.5 + \frac{Z}{24} \right\rfloor$$

凡滿足 $D \in [D_{\text{soc}, i}, D_{\text{soc}, i+1})$ 之民用日 $D$，皆隸屬於農曆第 $i$ 月，農曆日序為 $d = D - D_{\text{soc}, i} + 1$。

8.2 Divergence mechanism between Vietnam and China lunisolar dates

越南採用 UTC+07:00（$Z=7$），中國採用 UTC+08:00（$Z=8$）。當定朔時刻發生於世界時 $[16:00, 17:00)$ 區間內時：

• 越南地方時：為當日 $D$ 之 $23:\text{xx}$，初一日落在 $D$ 日。
• 中國地方時：為次日 $D+1$ 之 $00:\text{xx}$，初一日落在 $D+1$ 日。

此機制導致越南春節或農曆月初一日比中國提早一個民用日。歷史典型分歧實例如下：

• 1968年戊申春節： 定朔發生於 1968年1月29日 16:29 UTC $\rightarrow$ 越南春節正月初一為1月29日，中國為1月30日（除夕三十為29日）。
• 1984–1985年置閏分歧： 1984年11月定朔發生於時區分界敏感區間，越南將11月23日排為正常冬月，而中國將該月定為閏十月，導致兩國農曆月份名稱相差一個月，該效應持續至1985年初。

8.3 Leap month determination rule

系統嚴格遵循《授時曆》^[15] 確立之東亞天文置閏法則：

1. 連續兩次冬至之間若包含 13 個朔望月，該歲實為閏年。
2. 冬至後首個不含任何中氣（Major Solar Term）之農曆月份 SHALL 被確立為閏月。

由於中氣位置以太陽黃經達到 $30^\circ$ 整數倍為精確依據，VSOP87 模型之角精度對裁決邊界閏月具有決定性作用。

9 Metaphysical and civil almanac mathematical models

9.1 Sexagenary cycle (Can Chi) closed-form congruences

六十花甲子結構於代數上同構於環 $\mathbb{Z}${10} \times \mathbb{Z}{12}。

1. 日柱干支（Day Pillar）： 給定連續整數儒略日數 $\text{JDN}$： $$I_{\text{can}} = (\text{JDN} + 9) \pmod{10}$$ $$I_{\text{chi}} = (\text{JDN} + 1) \pmod{12}$$ J2000.0 驗算： $\text{JDN} = 2451545 \rightarrow I_{\text{can}} = 4$（戊），$I_{\text{chi}} = 6$（午）$\rightarrow$ 確為 戊午 日。

2. 時柱干支與夜子／晨子時約定： 子時天干依「五鼠遁元」法自日干推導： $$I_{\text{rat_stem}} = (2 \times I_{\text{can}} + 1) \pmod{10}$$

   • 當 earlyRat = true（夜子時，23:00–23:59）：時柱採用當日之天干。
   • 當 earlyRat = false（晨子時／正子，00:00–00:59）：時柱採用次日之天干。

9.2 True Solar Time and effective date rollover

真太陽時（$\text{TST}$）修正地理經度及地球軌道偏心率引起之日行不均：

$$\text{TST} = \text{Clock Time} + (\lambda_{\text{local}} - \lambda_{\text{std}}) \times 4\text{ min/deg} + \text{EoT}$$

越南法定基準經線嚴格限定為 $\lambda_{\text{std}} = 105^\circ\text{E}$。若錯誤採用 $110^\circ\text{E}$，將引入 $20\text{ 分鐘}$ 之系統偏差，導致時支發生錯誤偏移。

當真太陽時校正導致時間跨越午夜（$< 00:00$ 或 $\ge 24:00$）時，系統計算出 effectiveLocalDateTime 與 effectiveJdn。四柱命理（日柱、時柱、節氣月）必須強制依據此 effectiveJdn 進行同步推移。

9.3 Twelve Day Officers (Thập Nhị Trực)

十二建除神煞（建、除、滿、平、定、執、破、危、成、收、開、閉）隨日地支及節氣月支週期演替 ^[14]：

$$I_{\text{officer}} = (I_{\text{chi}} - I_{\text{term_branch}} + 12) \pmod{12}$$

強制性原則：節氣月支自立春始為寅（$I=2$），立秋始為申（$I=8$）。嚴禁將公曆月號或農曆月序作為輸入參數。

9.4 Twenty-Eight Mansions (Nhị Thập Bát Tú)

二十八宿依據連續 $\text{JDN}$ 以模 28 週期運行。系統錨定於 1995年1月1日（星期日，虛日鼠，索引10），對應 $\text{JDN} = 2449719$：

$$I_{\text{mansion}} = (\text{JDN} - 2449719 + 10) \pmod{28}$$

若運算結果為負，加 28 歸一化至 $[0, 27]$。

10 Historical timezone reduction and civil boundaries

Quizzman 依據 IANA 時區資料庫（Asia/Ho_Chi_Minh）^[11] 完整將越南歷史上八個時區時期形式化：

歷史編年影響： 1960年至1975年間，南方採用 UTC+08:00，而北方自1968年起採用 UTC+07:00。兩地在該時期共存在 270 個農曆日分歧。典型者如 1965年乙巳春節：1965年2月1日在北方為正月初一，而南方為甲辰年臘月三十。

11 Algorithmic audit findings and formal resolution

2026年演算法架構稽核 ^[18] 完整查證並處置了九項架構性缺陷：

11.1 A01: 二十四節氣之民用日邊界

• 缺陷： 早期邏輯採用相鄰兩日正午黃經比較（noon-to-noon），導致下午發生之節氣延後至次日（2024年24個節氣中有12個偏移一日）。
• 修復： 引入 getSolarTermTransitionsForYear 求解精確 UTC 瞬時，再映射至地方民用日區間 $[00:00:00, 24:00:00)$。

11.2 A02: 節氣月支與展示節氣之不一致

• 缺陷： 節氣月支依 JDN 12:00 UTC 黃經計算，與展示用節氣之舊規則產生衝突。
• 修復： 統一以 getSolarTermTransitionsForYear 作為節氣、節氣月支及建除之單一真理源。

11.3 A03: 真太陽時生效日跨日傳遞

• 缺陷： TST 跨午夜時僅設置標誌而未更新 jdn，導致八字日柱與時柱仍取舊日。
• 修復： 全面傳遞 effectiveLocalDateTime 與 effectiveJdn。

11.4 A04: NASA 對照測試中儒略日原點半日偏差

• 缺陷： 測試代碼將世界時小數直接疊加至已錨定於正午之 jdFromDate 而未扣減 0.5 日，造成約 $0.5^\circ$ 之假性黃經誤差。
• 修復： 全面採用規範之 utcDateTimeToJulianDate()，太陽黃經對比 USNO 誤差降至 $0.0005^\circ$ 以內。

11.5 A05: 吉日選擇介面契約重構

• 缺陷： 設計文件記載多因子神煞評分引擎，而公開 API 實際實現為基於規則之因果推導器。
• 修復： 修訂技術契約，載明公開 API 為具備溯源性之因果規則求解器，神煞數據作為補充性參考元數據。

11.6 A06: 2025年曆元 Delta T 階躍不連續性

• 缺陷： 歷史經驗查表至2025年以 $70.0\text{ s}$ 截止，預測多項式始於 $74.467\text{ s}$，存在 $4.467\text{ s}$ 跳躍。
• 修復： 部署 5 年線性過渡平滑模型於 $[2025, 2030]$ 區間。

11.7 A07: 農曆月長邊界檢查

• 缺陷： 農曆轉公曆接受小月中輸入 30 日，導致公曆結果溢出至次一農曆月。
• 修復： 增加硬性邊界約束：$1 \le d \le (D_{\text{soc}, i+1} - D_{\text{soc}, i})$。

11.8 A08: 1975年南方時區過渡測試預期對齊

• 缺陷： 舊測試預期南方於1975年5月1日轉為 UTC+07:00，與正式法令及 IANA tzdb 矛盾。
• 修復： 修正測試標準，確認精確分界點為 1975年6月13日 00:00。

11.9 A09: 防止朔望月序數估算過界導致農曆日為 0

• 缺陷： 平均朔估算公式於特定邊界條件下選取了未來朔點，造成農曆日計算值為 0。
• 修復： 約束定朔搜尋演算法，使其始終選取不大於當前民用日之最近定朔。

12 Empirical validation and benchmark results

引擎通過了四個層次之嚴格檢驗：

12.1 USNO 2024 Cardinal Points Parity

將 VSOP87 精簡模型計算之太陽黃經與 USNO 官方公佈之 2024 年二分二至點實測數據進行嚴格比對 ^[12]：

| 現象 | UTC 瞬時 | USNO 預期 $\lambda_\odot$ | 引擎計算 $\lambda_\odot$ | 絕對誤差 $|\Delta\lambda_\odot|$ | |---|---|---|---|---| | 2024 春分 | 2024-03-20 03:06:00Z | $0.0^\circ$ | $359.999602^\circ$ | $0.000398^\circ$ | | 2024 夏至 | 2024-06-20 20:51:00Z | $90.0^\circ$ | $90.000051^\circ$ | $0.000051^\circ$ | | 2024 秋分 | 2024-09-22 12:43:00Z | $180.0^\circ$ | $179.999585^\circ$ | $0.000415^\circ$ | | 2024 冬至 | 2024-12-21 09:20:00Z | $270.0^\circ$ | $269.999788^\circ$ | $0.000212^\circ$ |

所有測試點皆大幅優於容許極限 $|\Delta\lambda_\odot| < 0.0005^\circ$（$1.8''$）。

12.2 NASA New Moon Parity

對於 2024 年 1 月 11 日之定朔，NASA 記錄極小瞬時為 11:57 UTC。Quizzman 引擎計算結果為 11:56:56 UTC，絕對偏差僅為 $0.07\text{ 分鐘}$（遠低於 $2.0\text{ 分鐘}$ 容差閾值）。

12.3 Golden Date Verification: 2026年9月1日（越南民用時）

對基準校核日 2026年9月1日（UTC+07:00）展開跨領域全景校驗：

12.4 Exhaustive Bi-directional Roundtrip

全量迴歸測試管線連續掃描公元 1800 年 1 月 1 日至 2200 年 12 月 31 日間每一民用日（共計 146,462 日）。每一日期皆執行「公曆轉農曆（solarToLunar）」並隨即「農曆轉公曆（lunarToSolar）」逆運算：

• 驗證民用日總數：146,462 日。
• 雙向完全吻合日數：146,462 日（達成率 $100$）。
• 差異與錯誤數：0。

12.5 AI 模型幻覺於基準構建中之剖析

在初始基準庫建構期間，曾運用大型語言模型（Google Gemini）生成 12 個邊界測試用例。初測顯示 7/12 個用例失敗。經深入調研確認，所有 7 個失敗皆源於 LLM 幻覺生成錯誤之預期真值：

1. 錯誤指派 1968 年戊申春節之公曆日（給出 2 月 16 日而非 1 月 29 日）。
2. 捏造 1972 年整年持續存在兩國農曆分歧。
3. 混淆 1984 年春節與 1984 年 11 月分歧之起始點。
4. 對 2033 年置閏爭議年做出錯誤判斷。
5. 推算胡志明市真太陽時採用了虛構之 $110^\circ\text{E}$ 經度而非標準 $105^\circ\text{E}$。
6. 計算錯誤日地支：2026年3月24日誤猜丁巳（應為丁酉），2026年3月25日誤猜戊午（應為戊戌）。

核心工程結論：曆法與天體計算屬於嚴謹確定性之解析數理範疇，決不能依賴機率性語言模型之統計推斷。

13 Limitations

@quizzman/qm-calendar 引擎具備以下明確定義之技術邊界：

1. 最佳年表適用區間： VSOP87 精簡模型及 $\Delta T$ 經驗表於公元 1800 年至 2200 年間精度最優。在此區間以外，$\Delta T$ 累積不確定性可能影響發生於午夜前後數秒之定朔判定。
2. 月球運動解析論： 當前演算法採用 Meeus 第 49 章級數。後續路線圖計劃整合 ELP/MPP02 理論與 JPL DE440 數值積分內核，以實現跨千年尺度之亞秒級精度。
3. 1967年以前越南北方民用印曆約定： 採用紫金山天文台曆表（實際相當於 UTC+08:00）係基於當時印刷曆書事實之工程產品約定，並非官方溯源性民用法定時區之追認。

14 Conclusion

本規範依據 Quizzman Paper Standard（QPS-ISO 1.0）完整闡釋並確立了 @quizzman/qm-calendar 引擎之架構體系。藉由徹底修復九項根本性邊界缺陷、確立連續時間折算體系，並全數通過涵蓋 146,462 日之雙向往返測試與 USNO、NASA 之權威對照，本引擎展現了不可動搖之數學精確性與可靠性，作為現代東亞曆法運算之權威標準依據。

Bibliography

[1] International Organization for Standardization. ISO 8601-1:2019 Date and time — Representations for information interchange — Part 1: Basic rules. Geneva: ISO, 2019.
[2] International Organization for Standardization. ISO 2145:1978 Documentation — Numbering of divisions and subdivisions in written documents. Geneva: ISO, 1978.
[3] International Organization for Standardization. ISO 690:2021 Information and documentation — Guidelines for bibliographic references and citations to information resources. Geneva: ISO, 2021.
[4] Jean Meeus. Astronomical Algorithms. 2nd edition. Richmond: Willmann-Bell, Inc., 1998.
[5] Pierre Bretagnon, Gérard Francou. Planetary theories in rectangular and spherical variables. VSOP87 solutions. Astronomy and Astrophysics, 1988, vol. 202, pp. 309–315.
[6] E. Myles Standish. JPL Planetary and Lunar Ephemerides, DE405/LE405. JPL Interoffice Memorandum 312.F, 1998.
[7] Ryan S. Park, William M. Folkner, James G. Williams, Dale H. Boggs. The JPL Planetary and Lunar Ephemerides DE440 and DE441. The Astronomical Journal, 2021, vol. 161, no. 3, p. 105.
[8] Jean Chapront, Gérard Francou. The lunar theory ELP/MPP02. Astronomy and Astrophysics, 2003, vol. 404, no. 2, pp. 735–742.
[9] Fred Espenak, Jean Meeus. Five Millennium Catalog of Solar Eclipses: -1999 to +3000. NASA Technical Publication TP-2006-214141, 2006.
[10] Hồ Ngọc Đức. Lunisolar Calendar Calculations and Vietnamese Standard Meridian. Leipzig University Technical Report, 2000.
[11] Internet Assigned Numbers Authority. Time Zone Database (tzdb), version 2026a, 2026.
[12] United States Naval Observatory, Her Majesty's Nautical Almanac Office. The Astronomical Almanac for the Year 2024. Washington: U.S. Government Publishing Office, 2023.
[13] Hong Kong Observatory. Gregorian-Lunar Calendar Conversion Tables of the Hong Kong Observatory (1901–2100). Hong Kong SAR Government, 2024.
[14] Doãn Lộc, Mai Giác Thành. Khâm Định Hiệp Kỷ Biện Phương Thư (欽定協紀辨方書). Beijing: Qianlong 6th year, 1741.
[15] Quách Thủ Kính, Vương Tuần. Thọ Thời Lịch (授時曆). Dadu: Yuan Dynasty, 1281.
[16] Lê Quý Đôn. Vân Đài Loại Ngữ (芸臺類語) — Vol. 1: Ngôn tạo khảo. Thăng Long, 1777.
[17] Quizzman Research & Engineering Team. Quizzman Lunisolar Calendar Engine Technical Reference and Architecture v2.1. Quizzman Engineering Reports, 2026.
[18] Quizzman Research & Quality Assurance Group. Quizzman Calendar Engine Algorithm Audit and Fix Verification Report. Technical Audit Dossier AUD-2026-CAL-02, 2026.

Annex A (normative) Algorithmic Specifications and Core Functions

本節載明 @quizzman/qm-calendar 系統核心運算函式之規範性參考實作：

A.1 連續時間轉換為儒略日

export function utcDateTimeToJulianDate(
  year: number,
  month: number,
  day: number,
  hour: number = 0,
  minute: number = 0,
  second: number = 0
): number {
  const a = Math.floor((14 - month) / 12);
  const y = year + 4800 - a;
  const m = month + 12 * a - 3;
  const jdn =
    day +
    Math.floor((153 * m + 2) / 5) +
    365 * y +
    Math.floor(y / 4) -
    Math.floor(y / 100) +
    Math.floor(y / 400) -
    32045;
  const dayFraction = (hour + minute / 60 + second / 3600) / 24;
  return jdn + dayFraction - 0.5;
}

A.2 十二建除標準推算演算法

export function getDayOfficer(
  dayBranchIndex: number,
  solarMonthBranchIndex: number
): { index: number; name: string } {
  const OFFICERS = [
    'Kiến', 'Trừ', 'Mãn', 'Bình', 'Định', 'Chấp',
    'Phá', 'Nguy', 'Thành', 'Thu', 'Khai', 'Bế'
  ];
  const index = (dayBranchIndex - solarMonthBranchIndex + 12) % 12;
  return {
    index,
    name: OFFICERS[index]
  };
}

A.3 二十八宿 JDN 曆元錨定演算法

export function getMansion(jdn: number): { index: number; name: string } {
  const MANSHIONS_EPOCH_JDN = 2449719; // 1995-01-01 (Sunday) = 虛日鼠 (index 10)
  const MANSION_NAMES = [
    'Giác', 'Cang', 'Đê', 'Phòng', 'Tâm', 'Vĩ', 'Cơ',
    'Đẩu', 'Ngưu', 'Nữ', 'Hư', 'Nguy', 'Thất', 'Bích',
    'Khuê', 'Lâu', 'Vị', 'Mão', 'Tất', 'Chủy', 'Sâm',
    'Tỉnh', 'Quỷ', 'Liễu', 'Tinh', 'Trương', 'Dực', 'Chẩn'
  ];
  let index = (jdn - MANSHIONS_EPOCH_JDN + 10) % 28;
  if (index < 0) index += 28;
  return {
    index,
    name: MANSION_NAMES[index]
  };
}

Annex B (informative) Historical Timezone Decrees of Vietnam

越南各歷史時期民用法定時間法規彙編：

1. 1906年5月18日印度支那總督法令：自 1906年7月1日 00:00 起於法屬印度支那聯邦全境統一採用東經 $105^\circ$（UTC+07:00）時間。
2. 1942年12月23日法令：自 1942年12月31日 23:00 起將印度支那時間調快 60 分鐘至 UTC+08:00。
3. 1945年3月14日日軍司令部訓令：自 1945年3月15日 起強制印度支那全境改用東京時間（UTC+09:00）。
4. 1945年10月12日越南民主共和國臨時政府第 46-SL 號法令：恢復以東經 $105^\circ$（UTC+07:00）為獨立越南之官方時間。
5. 1959年9月4日越南共和國總統府第 362-CAB/MI 號法令：自 1959年12月31日 23:00 起將南方時區由 UTC+07:00 調快至 UTC+08:00。
6. 1967年8月8日越南民主共和國政府會議第 121-CP 號決議：頒佈曆法計算法則並自 1968年1月1日 起統一實施第七時區（UTC+07:00）。
7. 西貢–嘉定市軍管委員會通告：自 1975年6月13日 00:00 起將南方時間由 UTC+08:00 調慢 60 分鐘回退至 UTC+07:00，實現全國民用時標準之最終統一。