# Độ chính xác của tính toán

## TÓM TẮT

API AstroWay sử dụng **Swiss Ephemeris** (mã C chính thức từ Astrodienst,
những người tạo ra **astro.com**) — cùng một công cụ mà các nhà chiêm tinh chuyên nghiệp
đã sử dụng trong hơn 30 năm trên **Solar Fire ($495), Kepler ($995), Astro Gold ($29.99/tháng)**
và **Janus**. Chúng tôi đã biên dịch nó thành WebAssembly và cung cấp lớp API REST,
không qua trung gian. Mỗi endpoint tính toán cơ bản đều được bảo vệ bởi các bài kiểm thử
regression snapshot; độ chính xác của công cụ đã được xác minh thông qua **triangulation**
với ba nguồn độc lập + so với **Danh mục Nhật thực 5 Thiên niên kỷ của NASA**:

- **Vị trí hành tinh**: `< 0.1 giây cung` so với swetest CGI chính thức của Astrodienst
- **Cusp của nhà Placidus**: khớp chính xác `0.000"`
- **Nhật thực**: `< 1 phút` so với Danh mục Nhật thực của NASA
- **Đường ACG**: `< 1.5 km` trên xích đạo so với swetest
- **Bình minh/hoàng hôn**: `< 10 giây` so với timeanddate.com
- **Mặt Trăng VOC, nhập cung, giao hội hành tinh**: độ chính xác đến phần giây

## Công cụ

| Thành phần | Giá trị |
|------------|---------|
| Thư viện | Swiss Ephemeris C code (aloistr/swisseph) |
| Phiên bản | upstream Astrodienst C code |
| Bindings | swisseph-wasm (WebAssembly trong Node.js) |
| Ephemeris | DE431 JPL ephemeris (qua tệp .se1) |
| Fallback | Moshier analytical (cho ngày ngoài 1800-2399) |
| Code sharing | Shared `@/core` với app.astroway.info — một công cụ, hai phương thức vận chuyển |

## Phương pháp

Độ chính xác được xác minh thông qua **triangulation** — so sánh với ba nguồn độc lập:

### 1. swetest CGI (chuẩn mực)

Triển khai tham chiếu chính thức Swiss Ephemeris từ chính Astrodienst — những người đã tạo ra
**Astro.com** và phục vụ hàng triệu nhà chiêm tinh trên toàn thế giới. Nguồn công khai uy tín nhất.
Công cụ của chúng tôi **tương đồng** (0.00–0.07 giây cung lệch).

### 2. Kerykeion (Python)

Thư viện Python độc lập sử dụng `pyswisseph` bindings thay vì lớp WASM của chúng tôi.
Xác nhận rằng lớp WASM của chúng tôi không làm sai lệch dữ liệu.

### 3. Prokerala API

API Swiss Ephemeris từ xa (ayanamsa Lahiri theo sidereal). Độ lệch hệ thống 8–17 giây cung
liên quan đến các phiên bản công thức Lahiri ayanamsa khác nhau, **không phải** do độ chính xác
của công cụ.

## Kết quả triangulation

| Bản đồ | so với swetest (Astrodienst) | so với Kerykeion (Python) | so với Prokerala API |
|--------|-------------------------------|----------------------------|-----------------------|
| Monroe 1926   | **0.00"** | 0.19" | 16.95" (hệ thống) |
| Diana 1961    | **0.00"** | 0.69" | 8.18" (hệ thống)  |
| Einstein 1879 | 0.07"     | Lỗi LMT của Kerykeion | 14.96" (hệ thống) |

## Bộ snapshot regression ở cấp endpoint

Mỗi endpoint tính toán cơ bản đều được bảo vệ bởi các bài kiểm thử snapshot đã đóng băng
trên 3 bản đồ tham chiếu (Monroe / Diana / Einstein) = **{siteMeta.snapshotCount} snapshot**.

Bộ snapshot phát hiện:

- **Lỗi ánh xạ dữ liệu đầu vào** — ID hành tinh, UT, hệ thống nhà sai
- **Xử lý hậu kỳ** — làm tròn, chuyển đổi đơn vị, mất dấu
- **Khác biệt mặc định** — mean vs true node, địa tâm vs vị trí quan sát
- **Schema drift** — xác thực bỏ sót định dạng sai
- **Triển khai lỗi thời** — dist prod không khớp với code

Ngưỡng: `5e-5°` (≈0.18 giây cung) theo mặc định cho tất cả trường số.

## Benchmark chi tiết

### Vị trí hành tinh (tropical, so với swetest)

| Bản đồ | Ngày | Độ lệch tối đa |
|--------|------|----------------|
| Marilyn Monroe  | 1926-06-01 | **0.00"** |
| Princess Diana  | 1961-07-01 | **0.00"** |
| Albert Einstein | 1879-03-14 | 0.07"     |

### Cusp của nhà Placidus (so với swetest)

| Bản đồ | độ lệch ASC | độ lệch MC | Độ lệch tối đa cusp |
|--------|-------------|------------|----------------------|
| Monroe | 0.000" | 0.000" | 0.000" |
| Diana  | 0.000" | 0.000" | 0.000" |

### Nhật thực (so với Danh mục Nhật thực 5 Thiên niên kỷ của NASA)

| Sự kiện | NASA tối đa | Tối đa của chúng tôi | Độ lệch |
|---------|-------------|----------------------|---------|
| 2025-03-14 Nhật thực toàn phần Mặt Trăng  | 06:58 UT | 06:58 UT | 0.8 phút |
| 2025-03-29 Nhật thực một phần Mặt Trời | 10:47 UT | 10:47 UT | 0.5 phút |
| 2025-09-07 Nhật thực toàn phần Mặt Trăng  | 18:11 UT | 18:11 UT | 0.8 phút |
| 2025-09-21 Nhật thực một phần Mặt Trời | 19:41 UT | 19:42 UT | 1.0 phút |

### Astrocartography (so với công thức RA từ swetest)

Tất cả đường MC/IC/ASC/DSC sử dụng công thức chính xác `longitude = RA − GMST`
(tiêu chuẩn Kenneth Bowser). Độ lệch so với chuẩn: **< 1.5 km** trên xích đạo cho
tất cả hành tinh.

### Bình minh / Hoàng hôn Mặt Trời (so với timeanddate.com)

| Vị trí | Ngày | Tham số | Độ lệch |
|--------|------|---------|---------|
| London | 2026-04-15 | Bình minh | 0.6 giây |
| London | 2026-04-15 | Hoàng hôn  | 9 giây   |

**Vĩ độ cực** (|vĩ độ| > 66.5°) tự động trả về `polarState` + cảnh báo rằng
giờ hành tinh thông thường không xác định.

### Orbs của khía cạnh

AstroWay sử dụng **orbs biến đổi** theo từng hành tinh (quy tắc MIN của hai hành tinh),
như trên **ZET9** và **astro.com**. Orbs mặc định (cho bản đồ natal):

| Khía cạnh | Mặt Trời | Mặt Trăng | Nội hành tinh | Jupiter | Ngoại hành tinh |
|-----------|----------|-----------|---------------|---------|-----------------|
| Giao hội | 12°  | 10° | 5° | 8° | 5° |
| Lục hợp | 6.5° | 6°  | 5° | 5° | 5° |
| Hình vuông | 10°  | 8°  | 5° | 7° | 5° |
| Hợp | 12°  | 8°  | 5° | 5° | 5° |
| Đối xung | 12°  | 10° | 5° | 8° | 5° |

Các khía cạnh nhỏ (36°, 40°, 45°, 72°, 108°, 135°, 144°) **bị tắt theo mặc định**.
Chúng được bật rõ ràng qua `ALL_ASPECTS`.

## Vĩ độ cực

Với |vĩ độ| > 66.5°, các hệ thống Placidus / Koch / Regiomontanus không xác định về mặt
toán học. Trong những trường hợp này, Swiss Ephemeris tự động trả về Porphyry,
và API của chúng tôi bổ sung cảnh báo:

```json
{
  "system": "P",
  "warning": "Hệ thống Placidus không xác định cho lat=68.96° (> 66.5°). Swiss Ephemeris đã thay thế bằng Porphyry..."
}
```

## Kiểm tra liên tục

Regression được kiểm tra **trên mỗi PR** thông qua CI:

- `api-calc/tests/endpoints/` — {siteMeta.snapshotCount} snapshot so với các bản đồ tham chiếu (Monroe / Diana / Einstein) + synastry / composite / davison
- `.github/workflows/api-accuracy.yml` — tự động chạy trên PR
- Triangulation so với swetest CGI + Kerykeion — hàng tuần
- Giám sát Swiss Ephemeris upstream qua Dependabot

## Hạn chế đã biết

- **Ngày ngoài phạm vi** (trước 1800 và sau 2399): sử dụng Moshier analytical,
  độ chính xác ~0.1" (so với < 0.01" cho SWIEPH với tệp DE431)
- **Lilith thật (id=13) vs Lilith trung bình (id=12)**: chênh lệch lên đến 12° — theo mặc định
  là Lilith trung bình (hành vi ổn định), Lilith thật có sẵn qua
  `planetIds: [13]`
- **Vị trí quan sát vs địa tâm**: theo mặc định là địa tâm

## Liên kết

- Swiss Ephemeris: https://www.astro.com/swisseph/
- swetest CGI: https://www.astro.com/swisseph/swetest.htm
- Danh mục Nhật thực của NASA: https://eclipse.gsfc.nasa.gov/
- Kerykeion: https://github.com/g-battaglia/kerykeion
- Astrodienst: https://www.astro.com/

## Liên hệ

Về các vấn đề độ chính xác: hãy gửi email đến support@astroway.info kèm theo dữ liệu bản đồ
và chuẩn mực mong đợi (astro.com hoặc nguồn uy tín khác).