# BÁO CÁO KHẮC PHỤC VÀ KIỂM CHUẨN KHIẾM KHUYẾT KỸ THUẬT (ISSUE FIX REPORT) ## Chuyên đề: Xử lý Khiếm khuyết Codebase ISS-05, ISS-06, ISS-07 * **Mã báo cáo:** `QPS-IFR-CAL-2026-001` * **Hồ sơ liên quan:** `ISS-CAL-2026-001` (Báo cáo Thẩm định Độc lập & Danh mục Khiếm khuyết Kỹ thuật) * **Bài báo mục tiêu:** `QP-CAL-001 v1.0.0` → Kế hoạch bản vá `v1.0.1` * **Mã nguồn áp dụng:** Engine Lịch pháp Quizzman (`qm-calendar v1.2.0` → `v1.2.1`) * **Ngày thực hiện & Nghiệm thu:** 2026-10-01 * **Cơ quan thực hiện:** Quizzman Core Engineering Group & Ban Thẩm duyệt Tiêu chuẩn QPS --- ## 1. Tóm tắt Thực thi (Executive Summary) Đợt thẩm định độc lập theo phương pháp *Claim → Cross-Reference → Evidence* đã ghi nhận 10 phát hiện trên bài báo `QP-CAL-001 v1.0.0`. Qua quá trình audit rà soát mã nguồn thực tế, đội ngũ kỹ thuật xác định có **3 khiếm khuyết ảnh hưởng trực tiếp đến mã nguồn (codebase)** cần can thiệp xử lý ngay: 1. **ISS-05 (Cao):** Mốc $\Delta T = 70.000\text{ s}$ tại năm 2025.0 bị hardcode làm tròn thô trong bảng tra, không khớp dữ liệu quan trắc IERS thực tế ($\approx 69.138\text{ s}$). 2. **ISS-06 (Cao):** Thiếu vắng giai đoạn Giờ Đài Phù Liễn / Paris Mean Time (`PLMT`, UTC+7:06:30, 1906–1911) theo quy chuẩn cơ sở dữ liệu múi giờ quốc tế IANA tzdb (`Asia/Ho_Chi_Minh`). 3. **ISS-07 (Rõ ràng):** Sai lệch 1 phút trong datum kiểm chuẩn điểm Thu Phân 2024 trong route API benchmark (`12:43:00Z` thay vì `12:44:00Z` theo công bố chính thức của USNO và NASA). Toàn bộ 3 khiếm khuyết đã được **sửa đổi trực tiếp trong mã nguồn Node.js/CJS và Rust**, bổ sung bộ kiểm thử tự động, kiểm chứng qua 834 boundary tests và 146.462 ngày kiểm thử đảo (roundtrip). Toàn bộ hệ thống đã được biên dịch, nạp lại trên môi trường sản xuất (PM2 cluster) và pass 100%. --- ## 2. Chi tiết Khắc phục Từng Khiếm khuyết ### 2.1. Khắc phục ISS-05: Neo chuẩn $\Delta T$ năm 2025.0 theo IERS Bulletin B 443 #### a. Bối cảnh & Căn cứ Đo lường - Trong phiên bản cũ, bảng tra `DELTA_T_TABLE` hardcode giá trị nguyên `2025: 70`. Mặc dù đoạn mã có ghi nhận đây là mốc nối tạm thời (*"compatibility handoff"*), việc thiếu chuẩn hóa so với số liệu quan trắc của IERS (International Earth Rotation and Reference Systems Service) dẫn đến độ bất định $0.86\text{ s}$ không cần thiết. - Căn cứ theo **IERS Bulletin B số 443** (công bố đo lường chu kỳ quay Trái Đất tại mốc 2025-01-01 00:00:00 UTC): $$UT1 - UTC = +0.0461939\text{ s}$$ $$TAI - UTC = 37.0000000\text{ s}$$ - Theo chuẩn của Cơ quan Niên giám Thiên văn Quân sự Hoa Kỳ (USNO) và Hiệp hội Thiên văn Quốc tế (IAU): $$\Delta T = TT - UT1 = (TT - TAI) + (TAI - UTC) - (UT1 - UTC)$$ Biết rằng hiệu số định nghĩa tuyệt đối giữa Thời gian Trái Đất (Terrestrial Time - TT) và Thời gian Nguyên tử Quốc tế (TAI) là hằng số: $$TT - TAI = 32.184\text{ s}$$ Ta tính được giá trị thực nghiệm chính xác của $\Delta T$ tại 2025.0: $$\Delta T_{2025.0} = 32.184 + 37.0 - 0.0461939 = 69.1378061\text{ s} \approx 69.14\text{ s}$$ #### b. Các tệp đã sửa đổi trong Codebase 1. `/opt/qm-calendar/backend/core/astro/delta-t.cjs`: - Cập nhật mốc 2025 từ `70` sang `69.14`. - Bổ sung chú thích minh thị xuất xứ từ IERS Bulletin B 443 và cơ chế chuyển tiếp trơn tru sang đa thức ngoại suy từ năm 2030. 2. `/opt/qm-calendar/backend/core/_lunar-core.source.cjs`: - Đồng bộ giá trị `2025: 69.14`. 3. `/opt/qm-calendar/rust/astro-core/src/delta_t.rs`: - Cập nhật phần tử bảng tra Rust: `(2025, 69.14)`. #### c. Kết quả Thử nghiệm & Kiểm chuẩn - **Tính liên tục & đơn điệu:** Chạy kiểm thử hồi quy `algorithm-regression.test.cjs` qua toàn bộ dải năm $2025.0 \to 2050.0$ với bước nhảy $0.25$ năm. Độ chênh lệch tại biên $2025.000001$ so với $2025.0$ là $< 0.000002\text{ s}$, đảm bảo tính trơn và đơn điệu hoàn hảo. - **Tác động tới điểm Sóc:** Khi chạy lại kiểm chuẩn điểm Sóc 11/01/2024 với $\Delta T$ mới, độ lệch so với mốc NASA giảm từ $0.07\text{ phút}$ ($4.2\text{ s}$) xuống chỉ còn **$0.05\text{ phút}$** ($3.0\text{ s}$). --- ### 2.2. Khắc phục ISS-06: Bổ sung giai đoạn Giờ Đài Phù Liễn (PLMT) 1906–1911 #### a. Bối cảnh & Căn cứ Lịch sử - Cơ sở dữ liệu múi giờ quốc tế IANA tzdb (`tzdata.zi` mục `Zone Asia/Ho_Chi_Minh`) quy định lịch sử múi giờ Việt Nam như sau: ``` Z Asia/Ho_Chi_Minh 7:6:30 - LMT 1906 Jul 7:6:30 - PLMT 1911 May 7 - %z 1942 D 31 23 ... ``` - **Sử liệu pháp lý:** Nghị định của Toàn quyền Đông Dương ban hành áp dụng giờ chuẩn của Đài Thiên văn Phù Liễn (Kiến An / Hải Phòng) kể từ ngày 01/07/1906. Đài Phù Liễn có kinh độ thiên văn $106^\circ 37' 30''\text{E}$, tương đương giờ chuẩn Paris Mean Time tại Đông Dương là $+07:06:30$. - Đến ngày 01/05/1911, chính quyền Đông Dương mới chính thức ban hành nghị định chuyển sang múi giờ chuẩn quốc tế thứ 7 (UTC+7:00:00). - Trước đây, codebase đã ghi nhận sự tồn tại của PLMT trong chú thích mã nguồn nhưng cố tình giản lược gộp vào UTC+7. Việc này khiến tuyên bố của Paper *"số hóa trọn vẹn theo IANA"* bị coi là không trung thực với chính tzdb. #### b. Các tệp đã sửa đổi trong Codebase 1. `/opt/qm-calendar/backend/core/timezone/vietnam.cjs`: - Phân tách PERIOD 2 thành 2 giai đoạn con tường minh: - **PERIOD 2A (01/07/1906 – 30/04/1911):** Đông Dương thuộc Pháp — Giờ Đài Thiên văn Phù Liễn (`PLMT`). Offset chính xác: $7 + \frac{6}{60} + \frac{30}{3600} = 7.108333333333333\text{ giờ}$ (`+7:06:30`). - **PERIOD 2B (01/05/1911 – 31/12/1942):** Đông Dương thuộc Pháp chuẩn hóa múi giờ kinh tuyến thứ 7 (`UTC+7`, offset `7.0`). - Cập nhật hàm `getHistoricalPeriodName()`: bổ sung mã phân kỳ lịch sử `'PLMT_PHU_LIEN'`. - Bảo toàn tính tương thích ngược cho hàm số nguyên `getVietnamTimeZone()`: `Math.round(7.10833) = 7`, đảm bảo các module chỉ cần múi giờ nguyên số không bị ảnh hưởng. 2. `/opt/qm-calendar/backend/core/_lunar-core.source.cjs`: - Đồng bộ toàn bộ khối logic PERIOD 2A và mã định danh `'PLMT_PHU_LIEN'`. 3. `/opt/qm-calendar/backend/services/calendar/lunar-core.test.cjs`: - Bổ sung 5 bộ kiểm thử tự động xác minh: - `getHistoricalVietnamTimezone(1, 1, 1908).offsetFormatted === '+7:06:30'` - `getVietnamTimeZone(1, 1, 1908) === 7` - `getHistoricalPeriodName(1, 1, 1908) === 'PLMT_PHU_LIEN'` - `getHistoricalPeriodName(1, 1, 1920) === 'FRENCH_INDOCHINA'` --- ### 2.3. Khắc phục ISS-07: Đính chính Datum Thu Phân 2024 trong API Benchmark #### a. Bối cảnh & Đối chuẩn Thiên văn - Cả hai cơ quan thiên văn hàng đầu thế giới là Cơ quan Niên giám Thiên văn Quân sự Hoa Kỳ (USNO) và Trung tâm Bay Không gian Goddard của NASA (NASA GSFC) đều công bố chính thức mốc Thu Phân (Autumnal Equinox) năm 2024 tại: $$\text{Thu Phân 2024} = \mathbf{2024\text{-}09\text{-}22\text{ }12:44\text{ UT}}$$ - Thời điểm hoàng kinh biểu kiến của Mặt Trời cắt kinh độ $180^\circ 00' 00''$ tính theo lý thuyết nhiễu động hành tinh VSOP87 là $12:43:37\text{ UT}$. Do $37\text{ giây} > 30\text{ giây}$, quy tắc làm tròn thiên văn quốc tế quy ước làm tròn thành **12:44 UT**. - Trong file mã nguồn tuyến API kiểm chứng `backend/services/calendar/calendar-routes.cjs` (dòng 1197) và tài liệu `backend/docs/ENGINE_TECHNICAL_REFERENCE.md`, lập trình viên trước đây đã nhập nhầm mốc `12:43:00Z` (lấy phần sàn của phút). #### b. Các tệp đã sửa đổi trong Codebase 1. `/opt/qm-calendar/backend/services/calendar/calendar-routes.cjs`: - Dòng 1197: Sửa mốc kiểm chứng từ `12:43` thành `12:44`: ```javascript { label: 'Autumnal Equinox 2024', jd: lunarCore.utcDateTimeToJulianDate(22, 9, 2024, 12, 44), target: 180, nasaUTC: '2024-09-22T12:44:00Z' } ``` 2. `/opt/qm-calendar/backend/docs/ENGINE_TECHNICAL_REFERENCE.md`: - Cập nhật bảng đối chuẩn điểm cardinal: ```markdown | Thu Phân 2024 | 22/09 12:44 | 180° | 180.000264° | 0.000264° | ``` #### c. Kết quả Thực nghiệm trên API Live - Gọi trực tiếp endpoint `GET /api/tool-module/calendar/astro/nasa-parity` trên cổng dịch vụ `4050`: ```json { "label": "Autumnal Equinox 2024", "nasaUTC": "2024-09-22T12:44:00Z", "targetDeg": 180, "engineDeg": 180.0003, "deltaDeg": 0.0003, "ok": true, "toleranceDeg": 1 } ``` - Sai số hoàng kinh đo được tại mốc 12:44 chỉ là $0.000264^\circ \approx 0.95''$ (dưới 1 giây cung), tốt hơn so với mốc cũ 12:43 ($0.000415^\circ$). --- ## 3. Ma trận Kiểm chuẩn Toàn diện Hệ thống Sau khi áp dụng toàn bộ bản vá cho cả 3 khiếm khuyết, toàn bộ các bộ test tự động của hệ thống `qm-calendar` đã được thực thi và xác nhận: | Bộ Kiểm thử (Test Suite) | Số lượng Test Assertions | Kết quả | Ghi chú kiểm thử | | :--- | :--- | :--- | :--- | | `lunar-core.test.cjs` | 113 / 113 | **PASS 100%** | Bổ sung kiểm thử PLMT 1906–1911 và kiểm tra Delta T | | `day-sky.test.cjs` | 15 / 15 | **PASS 100%** | Tính toán Mặt Trời, pha Trăng, Sky Viewer | | `tet-divergence.test.cjs` | 12 / 12 | **PASS 100%** | Phân kỳ Mậu Thân 1968, Đinh Hợi 2007, Sóc NASA $\Delta=0.05\text{ min}$ | | `truc-xiu.test.cjs` | 23 / 23 | **PASS 100%** | Thập Nhị Trực, Nhị Thập Bát Tú | | `folk-month-rules.test.cjs` | Suite Passed | **PASS 100%** | Quy tắc dân gian ngày lành | | `purpose-resolver.test.cjs` | Suite Passed | **PASS 100%** | Bộ giải xung hợp mục đích | | `algorithm-regression.test.cjs` | 834 / 834 | **PASS 100%** | Kiểm tra ranh giới thuật toán, tính đơn điệu $\Delta T$ | | `test_intl_tz.js` | 53 / 53 | **PASS 100%** | Múi giờ quốc tế CN, TW, JP, KR, US | | `rust/astro-core` Cargo Test | Unit test | **PASS 100%** | Đồng bộ parity giữa Node.js và Rust | | `exhaustive-lunar-roundtrip.cjs` | 146,462 / 146,462 ngày | **PASS 100%** | Quy đổi Dương $\to$ Âm $\to$ Dương từ 1800 đến 2200: **0 lỗi** | --- ## 4. Kết luận & Đóng Hồ sơ Khiếm khuyết 1. **Về phía Codebase:** - Cả 3 khiếm khuyết **ISS-05**, **ISS-06**, **ISS-07** đã được khắc phục triệt để và triển khai an toàn lên dịch vụ sản xuất. - Trạng thái codebase: **Verified & Deployed in `qm-calendar v1.2.1`**. 2. **Về phía Xuất bản Học thuật (Paper `QP-CAL-001`):** - Hồ sơ thẩm định công khai tại [paper.quizzman.com/issues/ISS-CAL-2026-001/](https://paper.quizzman.com/issues/ISS-CAL-2026-001/) đã ghi nhận việc tiếp nhận phương án xử lý. - Ban biên tập sẽ cập nhật nội dung văn bản trong bản vá `QP-CAL-001 v1.0.1` theo đúng các căn cứ đo lường và sửa đổi đã thực hiện tại báo cáo này.