AncestorTree

Gia Phả Điện Tử - Họ Đặng làng Kỷ Các, Thạch Lâm, Hà Tĩnh

Phần mềm quản lý gia phả điện tử giúp gìn giữ và truyền thừa thông tin dòng họ qua các thế hệ.

"Gìn giữ tinh hoa - Tiếp bước cha ông"

Tính năng

Core (v1.0)

• Cây gia phả trực quan - Sơ đồ phả hệ tương tác, zoom, pan, collapse/expand, 10+ đời
• Quản lý thành viên - Hồ sơ cá nhân chi tiết (30+ trường thông tin)
• Phân quyền 4 cấp - Admin, Editor, Viewer, Guest (Supabase RLS)
• Tìm kiếm - Tra cứu nhanh theo tên, đời, chi nhánh
• Admin Panel - Quản lý người dùng, dữ liệu
• Responsive - Tương thích mobile/tablet/desktop

Vietnamese Cultural (v1.1–v1.3)

• Lịch âm dương - Chuyển đổi chính xác, hiển thị ngày giỗ
• Chi/nhánh - Quản lý theo cấu trúc dòng họ Việt Nam
• Đời (Generation) - Tính tự động theo phả hệ
• Can chi - Giáp Tý, Ất Sửu, ...
• Vinh danh thành tích - Bảng vinh danh thành viên xuất sắc (học tập, sự nghiệp, cống hiến)
• Quỹ khuyến học - Quản lý quỹ, học bổng, khen thưởng, theo dõi thu chi
• Hương ước gia tộc - Gia huấn, quy ước, lời dặn con cháu
• Thư mục thành viên - Danh bạ liên lạc với quyền riêng tư
• Lịch sự kiện - Theo dõi ngày giỗ, lễ, tết

Ceremony & Relations (v1.4–v1.5)

• Cầu đương - Phân công trách nhiệm cầu đương theo lịch âm (thuật toán DFS)
• Quan hệ gia đình - Hiển thị bố/mẹ/anh-chị-em/vợ-chồng/con theo giao diện trực quan
• Thêm thành viên có quan hệ - Chọn bố/mẹ khi tạo mới, thêm con vào gia đình
• Cây lọc theo gốc - Hiển thị cây gia phả bắt đầu từ bất kỳ thành viên nào

Local Development (v1.6)

• Chạy offline - Supabase CLI + Docker, không cần tài khoản cloud
• Dữ liệu demo - 18 thành viên 5 đời sẵn sàng sau pnpm local:setup
• Zero code change - Cùng code base, chỉ khác env vars
• Supabase CLI v2.76+ - Tương thích cả format mới (box-drawing table) và cũ (plain text)

Security (v1.7)

• Middleware bảo vệ toàn bộ - Tất cả trang (main) yêu cầu đăng nhập, không chỉ /admin
• RLS cật nhật - Số điện thoại, email, Zalo, địa chỉ chỉ hiển thị với thành viên đăng nhập
• Privacy mặc định an toàn - Thành viên mới tạo mặc định chế độ members only
• profiles bảo vệ - Danh sách tài khoản không có thể bị thu thập nếu chưa đăng nhập

Desktop App (v1.8)

• Cài và chạy - Tải installer, click cài, dùng ngay — không cần Node.js, Docker, hay tài khoản cloud
• Hoạt động offline - Dữ liệu lưu trên máy (SQLite), không cần internet
• Đầy đủ chức năng - 100% tính năng giống bản web
• Cross-platform - Hỗ trợ macOS và Windows
• Dữ liệu demo - 18 thành viên 5 đời sẵn sàng khi cài đặt
• Tự động cập nhật - Thông báo khi có phiên bản mới

Landing Page (v2.1)

• Trang giới thiệu - Hero, tính năng, screenshots, download, cộng đồng
• SEO - Canonical URL, robots.txt, Open Graph
• Download links - Liên kết tải desktop app cho macOS/Windows

Kho tài liệu & Hướng dẫn (v2.2)

• Kho tài liệu - Upload/lưu trữ ảnh lịch sử, gia phả giấy (PDF), bản đồ, video, bài viết
• Phân loại - 6 danh mục: Ảnh lịch sử, Giấy tờ, Bản đồ, Video, Bài viết, Khác
• Tìm kiếm & lọc - Gallery view với filter theo danh mục, tìm theo tiêu đề
• Gắn thẻ thành viên - Liên kết tài liệu với thành viên trong gia phả
• Admin quản lý - CRUD tài liệu, upload file, xác nhận xóa
• Hướng dẫn sử dụng - Trang /help trong app: 5 phần (điều hướng, workflow, phân quyền, mẹo, FAQ)
• Desktop conditional - Bản Desktop hiển thị thêm hướng dẫn sao lưu + bảng so sánh Desktop vs Web

Security & Settings (v2.2.1)

• Security hardening - File size limit, MIME type validation, column whitelisting trên import (@h4niz)
• Tùy chỉnh tên dòng họ - Cấu hình qua env vars NEXT_PUBLIC_CLAN_NAME / NEXT_PUBLIC_CLAN_FULL_NAME
• Trang Cài đặt - /admin/settings hiển thị thông tin dòng họ, hệ thống, hướng dẫn thay đổi
• API docs - Tài liệu API endpoints đầy đủ cho 14 bảng + Auth + Storage
• Secure coding review - OWASP Top 10 + ASVS Level 1 audit

Privacy & Verification (v2.3)

• Xác nhận thành viên - Admin duyệt tài khoản mới trước khi cho truy cập
• Sub-admin - Editor được cấp quyền xác nhận thành viên trong nhánh phụ trách
• Hạn chế Viewer - Viewer không thấy thông tin liên lạc, chỉ xem tên và cây gia phả
• Quyền riêng tư tài liệu - 3 cấp: Công khai / Thành viên / Nội bộ (admin+editor)
• Email xác nhận - Đăng ký cần verify email trước khi đăng nhập
• Trang chờ xác nhận - /pending-verification cho tài khoản chưa được duyệt
• Middleware fail-closed - Lỗi/timeout → chặn truy cập (không fail-open)
• Client-side guard - VerificationGuard trong layout bảo vệ client-side navigation

Hồ sơ, MFA & Sao lưu (v2.4.1)

• Hồ sơ tài khoản - /settings/profile: xem & sửa tên hiển thị, đổi mật khẩu, avatar
• Bảo mật MFA (TOTP) - /settings/security: bật/tắt Google Authenticator, quét QR, nhập OTP 6 số
• Sao lưu & Phục hồi - /admin/backup: xuất 13 bảng ra ZIP, nhập lại 1-click, tự động lịch sao lưu
• Quản lý tài khoản nâng cao - Admin khoá/mở khoá, xoá tài khoản vĩnh viễn, duyệt xác nhận
• Bulk Admin Actions - Checkbox chọn nhiều, xác nhận/khoá/xoá hàng loạt với Promise.allSettled
• Cài đặt dòng họ (động) - Sửa tên, năm thành lập, nguồn gốc trực tiếp trong admin (không cần env vars)
• Rate limiting - Giới hạn đăng nhập/đăng ký (20/phút login, 10/phút register, 6/5 phút forgot-password)
• Docker - Dockerfile + docker-compose.yml, 1 lệnh docker compose up là chạy

Cộng đồng & Nâng cao (v2.5)

• Góc giao lưu - Feed bài viết, bình luận, thả tim, upload ảnh (tối đa 5/bài), lọc theo loại, moderation
• Tìm quan hệ - BFS pathfinding giữa 2 thành viên + Vietnamese relationship labels
• Thống kê nâng cao - Dashboard biểu đồ (phân bố đời, giới tính, còn sống/mất) với Recharts
• Xuất PDF - Export tree viewport ra PDF (html2canvas + jsPDF, beta)
• GEDCOM 7.0 Export - Nâng cấp từ 5.5.1, hỗ trợ Vietnamese extensions (Quá Kế)
• GEDCOM Import - Parse .ged 5.5.1/7.0 → tạo people + families tự động
• CSV Export - Xuất danh sách thành viên ra Excel/CSV
• Phát hiện trùng lặp - Thuật toán Levenshtein + Vietnamese NFD normalization
• Chế độ người cao tuổi - Font size toggle + simplified list view
• Thông báo - Bell icon + 6 loại thông báo + DB triggers (không insert trực tiếp)
• Trang Hội đồng - /council: thông tin ban quản trị, lịch sử, sứ mệnh dòng họ (public)
• Trang Nhà thờ họ - /ancestral-hall: gallery ảnh, lịch tế lễ, bản đồ OpenStreetMap (public)
• Đăng ký thành viên - /register-member: form 12 trường + honeypot anti-spam + rate limit
• Admin duyệt đơn - /admin/registrations: duyệt/từ chối/xoá đơn ghi danh
• Tìm kiếm thông minh - Fuzzy search (Fuse.js) hỗ trợ dấu tiếng Việt
• SEO hoàn chỉnh - Sitemap động, robots.txt, Open Graph cho 4 trang public

Tech Stack

| Layer | Technology | |-------|------------| | Frontend | Next.js 16, React 19, TypeScript 5 | | Styling | Tailwind CSS 4, shadcn/ui, Radix UI | | Database | Supabase (PostgreSQL, Auth, Storage, RLS) | | State | React Query (TanStack Query) | | Desktop | Electron 34, sql.js (WASM SQLite) | | Deployment | Vercel + Supabase Cloud | | Cost | $0/tháng (100% free tier) |

Quick Start

One-line Install (khuyên dùng)

Cần: Docker Desktop đang chạy + Node.js 18+. Script tự cài pnpm & Supabase CLI nếu thiếu.

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/Minh-Tam-Solution/AncestorTree/main/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/Minh-Tam-Solution/AncestorTree/main/install.ps1 | iex

Xong → cd AncestorTree/frontend && pnpm dev → mở http://localhost:4000

Demo login: admin@giapha.local / admin123

Option A: Desktop App (dành cho người dùng phổ thông)

Code Signing Pending — Bản desktop đang chờ Apple Developer Certificate. Khi có code sign, bản cài đặt sẽ được phát hành tại GitHub Releases. Hiện tại, vui lòng sử dụng One-line Install hoặc Option B/C.

See docs/04-build/INSTALLATION-GUIDE.md for detailed instructions.

Option B: Local Development (manual)

Requires Docker Desktop + Node.js 18+ + pnpm + Supabase CLI

git clone https://github.com/Minh-Tam-Solution/AncestorTree.git
cd AncestorTree/frontend
pnpm install
pnpm local:setup   # starts Docker, runs migrations, writes .env.local
pnpm dev

Open http://localhost:4000

Demo login: admin@giapha.local / admin123

See docs/04-build/LOCAL-DEVELOPMENT.md for full guide.

Option C: Docker (1 lệnh, không cần Node.js)

git clone https://github.com/Minh-Tam-Solution/AncestorTree.git
cd AncestorTree
cp frontend/.env.local.example frontend/.env.local
# Fill in Supabase credentials
docker compose up -d

Open http://localhost:4000

Option D: Supabase Cloud

git clone https://github.com/Minh-Tam-Solution/AncestorTree.git
cd AncestorTree/frontend
pnpm install
cp .env.local.example .env.local
# Fill in NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_ANON_KEY
# Then run migrations in Supabase SQL Editor (supabase/migrations/ in order)
pnpm dev

Open http://localhost:4000

Project Structure

AncestorTree/
├── docs/                           # SDLC Documentation (LITE tier)
│   ├── 00-foundation/              # Vision, requirements, community
│   │   └── 06-Community/           # Community launch posts
│   ├── 01-planning/                # BRD, roadmap
│   ├── 02-design/                  # Architecture, UI/UX
│   ├── 04-build/                   # Sprint plans
│   └── 05-test/                    # Test plans
├── fron