viet-bazi-engine

Engine Bát Tự/Tứ Trụ viết bằng TypeScript, chạy hoàn toàn offline, deterministic và không có runtime dependency. Kết quả là JSON có type, stable machine codes, metadata giải thích và JSON Schema để dùng trực tiếp trong ứng dụng hoặc LLM tools.

Trạng thái: 0.46.0 — API đang ở giai đoạn pre-1.0. Không dùng kết quả làm cơ sở duy nhất cho quyết định y tế, pháp lý hoặc tài chính.

Tính năng

• Tứ Trụ Năm–Tháng–Ngày–Giờ theo Lập Xuân và 12 Tiết.
• Hai quy ước đổi ngày: đầu giờ Tý 23:00 và nửa đêm 00:00.
• Tàng Can, Thập Thần, Ngũ Hành, hình–xung–hợp–hại, Đại Vận và Lưu Niên.
• 23 Thần Sát phổ biến và cách cục heuristic có evidence.
• True solar time, catalog thành phố Việt Nam và phân tích độ nhạy giờ sinh.
• Compatibility, SVG accessible với biểu đồ Ngũ Hành/tương phản cao, localization Việt/Anh.
• Batch API, JSON CLI, self-contained Python wheel (cần Node.js 20+) và WASM calendar/full-engine adapter.
• JSON Schema Draft 2020-12, capability discovery và fixtures đối chiếu NAOJ.
• Audit report machine-readable ánh xạ rule/version với các trường input và output.

Bắt đầu nhanh

Yêu cầu Node.js 20 trở lên.

git clone https://github.com/iZenDeveloper/viet-bazi-engine.git
cd viet-bazi-engine
npm install
npm test

import { calculateBazi } from 'viet-bazi-engine';

const chart = calculateBazi({
  localDateTime: '1990-05-17T14:30:00',
  timezoneOffsetMinutes: 420,
  asOfYear: 2026,
  gender: 'female',
  trueSolarTime: true,
  location: { city: 'Hà Nội' },
  dayBoundary: 'early-zi'
});

console.log(chart.pillars, chart.elements, chart.metadata.methodology);

npm run build
node dist/cli.js --capabilities --compact
node dist/cli.js --compact '{"localDateTime":"1990-05-17T14:30:00","timezoneOffsetMinutes":420,"asOfYear":2026,"gender":"female"}'

Demo web/PWA offline sau khi build:

npm run demo
# Mở http://127.0.0.1:8080/demo/

Tài liệu

• Hướng dẫn bắt đầu
• API TypeScript
• CLI
• Python và WASM
• Phương pháp tính và độ chính xác
• JSON Schema và conformance fixtures
• Kiến trúc
• Lộ trình phát triển
• Demo web offline
• Quy trình phát hành
• Benchmark batch
• Đóng góp
• Lịch sử thay đổi

Kiểm thử và giới hạn đã công bố

Suite bao phủ TypeScript, Python wheel cô lập, CLI end-to-end, demo/PWA, parity WASM full-output, JSON Schema và conformance runner. README không ghi tổng test thủ công; CI là nguồn trạng thái chính xác. Bộ fixtures gồm 36 ranh Tiết chính thức NAOJ trong các năm 2013/2020/2026, 6 ngày Can–Chi 1900–2099 và 10 ca chéo múi giờ/ranh đổi ngày; sai số ranh Tiết quan sát lớn nhất là 11 phút với ngưỡng regression 15 phút.

Đo batch calculation bằng workload deterministic:

npm run build
npm run benchmark

Các trường phái Bát Tự có thể khác nhau về đổi ngày, khởi vận, cách cục và Thần Sát. Engine ghi rõ mọi convention trong metadata.methodology. Công thức hoàng kinh Mặt Trời và equation of time là xấp xỉ; ca sát ranh cần dùng analyzeBirthTimeSensitivity() và đối chiếu ephemeris chuyên dụng.

Giấy phép

MIT © iZenDeveloper.