Ziwei Doushu VN là phiên bản Việt hóa toàn diện (theo chuẩn thuật ngữ Hán Việt truyền thống) của bộ máy lập lá số Tử Vi mã nguồn mở Renhuai123/ziwei-doushu, dựa trên hệ thống《Thiên Kỷ》của Nghê Hải Hạ và nhân tính toán iztro.
Dự án phục vụ cá nhân CEO (Nhi) và được triển khai trên VPS nội bộ qua Tailscale Funnel.
• GitHub: https://github.com/Renhuai123/ziwei-doushu (15.600+ sao, giấy phép MIT) • Công nghệ: TypeScript + Next.js 16 + React 19 + TailwindCSS + iztro 2.5.8 + lunar-javascript • Phụ thuộc ngoại tuyến: Không cần Redis hoặc PostgreSQL cho chế độ lá số cơ bản (Database chỉ cần cho tính năng Hạc Minh AI) • Mô hình tính toán: 100% phía máy khách (client side rendering) nên VPS chỉ phục vụ tập tin tĩnh
Thư viện iztro (https://github.com/SylarLong/iztro) đã tích hợp sẵn bộ locale vi-VN hoàn chỉnh bao gồm:
• star.ts: Tên tất cả 14 chính tinh, 6 cát tinh, 6 sát tinh, 37 tạp diệu bằng tiếng Việt
• palace.ts: Tên 12 cung vị bằng tiếng Việt
• heavenlyStem.ts: 10 Thiên Can (Giáp đến Quý)
• earthlyBranch.ts: 12 Địa Chi (Tý đến Hợi)
• mutagen.ts: 4 Tứ Hóa (Lộc, Quyền, Khoa, Kỵ)
• brightness.ts: Các cấp độ sáng (Miếu, Vượng, Đắc, Lợi, Bình, Hãm)
• fiveElementsClass.ts: 5 Ngũ Hành Cục (Thủy, Mộc, Kim, Thổ, Hỏa)
• gender.ts: Nam, Nữ
Bản gốc gọi astro.bySolar(..., 'zh-CN') và astro.byLunar(..., 'zh-CN') tại lib/ziwei/algorithm.ts dòng 489 và 499. Toàn bộ bảng tra cứu nội bộ (độ sáng, Tứ Hóa, cách cục, luận giải Thiên Kỷ) đều khớp theo khóa chữ Hán.
Chiến lược: KHÔNG thay đổi tham số ngôn ngữ bên trong nhân tính toán. Thay vào đó, xây dựng một lớp adapter lib/i18n/glossary-vi.ts chứa bảng ánh xạ Record<string, string> từ chữ Hán sang Hán Việt, và hàm localizeChart(chart: ZiweiChart): LocalizedChart tại lib/i18n/localize-chart.ts để chuyển đổi kết quả trước khi đưa ra giao diện.
Bản gốc mặc định Giờ Bắc Kinh (UTC+8, kinh tuyến chuẩn 120°E):
• lib/ziwei/share.ts: công thức (longitude - 120) * 4
• lib/ziwei/true-solar-time.ts: mặc định utcOffsetMinutes = 480
• lib/ziwei/cities.ts: chỉ có dữ liệu tỉnh thành Trung Quốc, Hồng Kông, Ma Cao và Đài Loan
Đối với người dùng sinh tại Việt Nam (UTC+7, kinh tuyến chuẩn 105°E):
• Truyền utcOffsetMinutes = 420 vào hàm calculateTrueSolarTime()
• Tạo tệp lib/ziwei/cities-vn.ts chứa dữ liệu kinh độ 63 tỉnh thành Việt Nam
• Kinh tuyến chuẩn tự động tính từ utcOffsetMinutes / 4 = 105
• Thư mục vật lý: /opt/ai-os/products/ceo/projects/personal/ziwei_doushu_vn/
• Node.js phiên bản: v20 trở lên (đã cài đặt sẵn trên VPS)
• Bộ quản lý tiến trình: PM2 (ecosystem.config.js)
• Máy chủ ngược: Caddy hoặc Nginx (cấu hình SSL tự động qua Tailscale Funnel)
• Public URL: https://vmi3427693.tail8c1aaf.ts.net/ziwei/
• Cổng nội bộ: 3100 (tránh xung đột với các dịch vụ hiện có: 3000 = OpenMAIC, 9120 = Hermes Dashboard)
| Mục đích | Tệp tin |
|---|---|
| Quy tắc kiến trúc và từ điển | PROJECT_RULES.md (thay thế AGENTS.md) |
| Bối cảnh hệ thống và bản đồ tệp | docs/APP_CONTEXT.md (tệp này) |
| Kế hoạch triển khai và phân bổ Subagent | docs/IMPLEMENTATION_PLAN.md |
| Quy trình phát triển và bàn giao | docs/WORKFLOW.md |
| Nhân tính toán an sao (bất biến, không sửa trực tiếp) | lib/ziwei/algorithm.ts |
| Bảng hằng số Thiên Can, Địa Chi, Tứ Hóa | lib/ziwei/constants.ts |
| Từ điển ánh xạ Hán Việt | lib/i18n/glossary-vi.ts |
| Hàm chuyển đổi lá số sang tiếng Việt | lib/i18n/localize-chart.ts |
| Dữ liệu kinh độ 63 tỉnh thành Việt Nam | lib/ziwei/cities-vn.ts |
| Chuỗi giao diện người dùng tiếng Việt | lib/i18n/ui-strings-vi.ts |
| Biểu mẫu nhập ngày giờ sinh (Việt hóa) | components/BirthForm.tsx |
| Bàn lá số 12 cung (Việt hóa) | components/ChartBoard.tsx |
| Ô hiển thị từng cung | components/PalaceCell.tsx |
.env)# Chế độ lá số cơ bản không cần ANTHROPIC_API_KEY, DATABASE_URL hoặc REDIS_URL
# Những biến này chỉ cần khi kích hoạt tính năng Hạc Minh AI (AI giải đoán)
NEXT_PUBLIC_SITE_URL=https://vmi3427693.tail8c1aaf.ts.net/ziwei