# Thiết kế: Cổng số hóa di sản VR360 — Xã Như Quỳnh, tỉnh Hưng Yên

- **Ngày:** 2026-06-23
- **Dự án:** `phy-vr360`
- **Trạng thái:** Đã duyệt khung tổng thể, chờ duyệt spec chi tiết
- **Mục tiêu tầm nhìn:** Số hóa di tích, theo kịp định hướng chuyển đổi số 2026–2030, phục vụ người dân, học sinh, du khách và cơ quan quản lý nhà nước.

---

## 1. Bối cảnh & tài nguyên hiện có

Trong thư mục `d:\Code\vr360` có hai dự án:

- **`pdc-vr360`** — Sản phẩm hoàn chỉnh đang chạy cho **phường Định Công (Hà Nội)**. Gồm landing site Next.js 16 đầy đủ (trang chủ, giới thiệu, di tích, liên hệ…) và engine **`VirtualTour.tsx`** (~4.039 dòng, Three.js): panorama 360°, hotspot chuyển cảnh, bản đồ tuyến, thuyết minh audio, modal thông tin. Đây là **bản tham chiếu**, **giữ nguyên không sửa**.
- **`phy-vr360`** — Scaffold Next.js 16 trống (chỉ `page.tsx` mặc định), nhưng **đã chứa 26 ảnh panorama VR360** tại `public/images/Đình Thái Lạc/` và bộ icon (`flycam.png`, `hotspotelement.png`, `_ggMapPin.png`).

**Quyết định:** `phy-vr360` trở thành sản phẩm chính thức **"VR360 Di sản Xã Như Quỳnh"**, port bộ máy đã chạy ổn từ `pdc-vr360` sang.

### Đính chính tên di tích (đã xác nhận với chủ dự án)
- 26 ảnh trong thư mục `Đình Thái Lạc/` thực chất chụp **Chùa Thái Lạc (Pháp Vân tự)** — di tích quốc gia nổi tiếng với mảng chạm khắc gỗ thời Trần (thế kỷ 14).
- Trong danh mục 9 di tích quốc gia, mục ghi *"Đình Thái Lạc"* là **lỗi tên gọi**, cần **sửa thành "Chùa Thái Lạc (Pháp Vân tự)"** (KHÔNG thêm di tích mới — vẫn 9 di tích quốc gia).

### Stack kỹ thuật (port cho khớp pdc-vr360)
- Next.js 16 (App Router), React 19, TypeScript, Tailwind v4.
- Cần thêm vào `phy-vr360/package.json`: `three`, `@types/three`, `framer-motion`, `lucide-react`, `@paper-design/shaders-react`, `lottie-react`.
- ⚠️ **Lưu ý phiên bản Next.js:** AGENTS.md cảnh báo "This is NOT the Next.js you know" — đọc guide trong `node_modules/next/dist/docs/` trước khi viết code khác biệt với kiến thức cũ.

---

## 2. Cấu trúc trang (App Router, `src/app/`)

Bỏ các trang chào hàng của đơn vị thi công (`giai-phap`, `ke-hoach`, `tuyen-vr`). Bộ trang cổng di sản công cộng:

| Đường dẫn | Trang | Nội dung chính |
|---|---|---|
| `/` | Trang chủ | Hero, giới thiệu nhanh về xã, di tích nổi bật (tour Chùa Thái Lạc đang mở), lưới 15 di tích, giá trị di sản, CTA |
| `/gioi-thieu` | Giới thiệu Xã Như Quỳnh | Vị trí, lịch sử, vùng đất khoa bảng, tổng quan hệ thống di tích |
| `/di-tich` | Danh mục di tích | Bộ lọc **Cấp quốc gia / Cấp tỉnh**, tìm kiếm, lưới 15 thẻ di tích |
| `/di-tich/[slug]` | Chi tiết từng di tích | Ảnh, mô tả, thông tin xếp hạng, vị trí, nút "Tham quan VR360" nếu có |
| `/tour/chua-thai-lac` | **Tour VR360 (hoạt động đầy đủ)** | Engine ported + 26 ảnh panorama Chùa Thái Lạc |
| `/lien-he` | Liên hệ | Thông tin liên hệ, đầu mối cập nhật tư liệu |

Components dùng chung port từ pdc-vr360: `SiteHeader`, `SiteFooter`, `BackToTopButton`, nền hero (`hero-shader-background`), và design system `globals.css` (hệ class `public-*`).

---

## 3. Danh mục 15 di tích

### Cấp quốc gia (9)
1. Đền Ghênh (Đền Ỷ Lan)
2. Từ Vũ họ Trương
3. Bãi đá đền Từ Vũ
4. Đình Ất
5. Chùa Hành Lạc
6. Đình Hành Lạc
7. Chùa Ông
8. **Chùa Thái Lạc (Pháp Vân tự)** ← đã sửa tên; **có tour VR360**
9. Chùa Vĩnh Thái

### Cấp tỉnh (6)
10. Đình Lê Xá
11. Đình Ngô Xuyên
12. Chùa Từ Kính
13. Cung Chí Nguyên (nơi Thạch Lam tìm cảm hứng viết "Dưới bóng hoàng lan")
14. Văn miếu Như Quỳnh
15. Dấu tích Chùa Lá

**Chiến lược nội dung (lựa chọn "Kết hợp"):**
- **Chùa Thái Lạc:** soạn nội dung đầy đủ, chuẩn mực, có nghiên cứu (lịch sử, kiến trúc, giá trị, mô tả từng cảnh tour).
- **14 di tích còn lại:** mô tả ngắn dạng mẫu (2–4 câu) + khung bố cục sẵn để bổ sung văn bản chính thức sau. Trạng thái "Đang bổ sung tư liệu".

---

## 4. Mô hình dữ liệu (`src/app/content.ts`)

```
commune = { name: "Xã Như Quỳnh, tỉnh Hưng Yên", intro, history, stats[] }

type HeritageLevel = "Cấp quốc gia" | "Cấp tỉnh";

type HeritageSite = {
  slug: string;
  name: string;
  type: string;            // "Chùa", "Đình", "Đền", "Văn miếu"...
  level: HeritageLevel;
  status: "Đang mở tour" | "Đang bổ sung tư liệu";
  shortDescription: string;
  longDescription?: string[]; // đầy đủ cho Thái Lạc; mẫu cho phần còn lại
  images: string[];
  vrUrl?: string;          // "/tour/chua-thai-lac" cho Thái Lạc
  isAvailable: boolean;
  location?: string;
};

heritageSites: HeritageSite[]   // 15 mục
```

Trang `/di-tich` và `/di-tich/[slug]` đọc từ mảng này. Slug sinh từ tên (không dấu, kebab-case).

---

## 5. Tour VR360 Chùa Thái Lạc

### 5.1 Port engine
`VirtualTour.tsx` của pdc **đã có sẵn type `TourConfig`** và đang phục vụ 2 tour (`dinh-lang-dinh-cong`, `chua-lien-hoa`) — engine vốn được tham số hóa. Việc cần làm:
- Port file `VirtualTour.tsx` + các phụ thuộc (icon, modal, hero background) sang `phy-vr360`.
- **Tổng quát hóa `SceneId`**: hiện là union type hard-code; đổi thành `string` để nhận scene động.
- **Tách dữ liệu tour ra file config riêng** (`src/app/tours/chua-thai-lac.ts`) thay vì nhúng trong component. Engine nhận một `TourConfig`.
- Xóa/không port dữ liệu Định Công + Liên Hoa (không có ảnh tương ứng trong phy-vr360).

### 5.2 Cấu hình 26 cảnh
26 ảnh: `4`, `Ao Cá Koi`, `Chính Diện Cổng Chùa`, `Chính Sảnh`, `Chính Điện 3`, `Chính`, `Chùa 1 Giữa`, `Chùa 1 Hữu`, `Chùa 1 Tả`, `Chùa 1 Trong - Giữa`, `Chùa 1 Trong Tả`, `Cổng Bên Trái`, `Cổng Hữu`, `Duong Tả Vòm`, `Giuawx`, `Gốc Ngoã Hữu`, `Gốc Ngoã Tả`, `Hữu 2`, `Hữu 3`, `La Hán Tả`, `Lối Vào Been Trái`, `Nhà Phật Hữu`, `Sau Chùa`, `Tượng Quan Âm`, `Đường Hữu`, `Đường Tả Qua Vòm`.

**Tuyến tham quan đề xuất** (sẽ chốt chính xác khi triển khai, có review):
Cổng (Chính Diện Cổng Chùa → Cổng Hữu/Bên Trái) → đường/vòm (Đường Hữu, Đường Tả Qua Vòm, Duong Tả Vòm) → Chính Sảnh → Chính/Chính Điện → các ban (Chùa 1 Tả/Giữa/Hữu, Chùa 1 Trong…) → tượng (Tượng Quan Âm, La Hán Tả, Nhà Phật Hữu) → ngoại cảnh (Ao Cá Koi, Gốc Ngoã, Sau Chùa).

Mỗi cảnh: `id`, `order`, `title` (tiếng Việt), `location`, `image`, `initialYaw`, `mapPosition`, `hotspots[]` (nối các cảnh liền kề). Hotspot yaw/pitch tinh chỉnh bằng quan sát thực tế khi chạy dev.

### 5.3 Âm thanh
- Thái Lạc **chưa có file mp3 thuyết minh**. Tour chạy đầy đủ với **chú thích chữ trên màn hình** cho từng cảnh.
- Engine đã hỗ trợ `sceneNarration` / `backgroundAudio`; để cấu trúc sẵn, gắn audio sau khi có file. Nhạc nền có thể tạm bỏ hoặc dùng file trung tính (không port file nhạc Phật của Định Công nếu chưa xác nhận bản quyền/phù hợp).

---

## 6. Ngôn ngữ thiết kế

- **Palette di sản (giữ từ pdc):** xanh thẫm (mực/`tour-ink`) + vàng/hổ phách (nhấn/`primary`) + nền kem ấm. Trang trọng, phù hợp cơ quan nhà nước, tôn vinh di sản.
- Typography thân thiện tiếng Việt; tiêu đề đậm, thân chữ dễ đọc.
- Hiệu ứng reveal mượt (framer-motion), tiết chế, chuyên nghiệp; **mobile-first**, tối ưu cho điện thoại.
- Giữ hệ class `public-*` và token CSS từ `globals.css` của pdc để đảm bảo nhất quán & chất lượng đã được kiểm chứng.

---

## 7. Phân kỳ triển khai

1. **Phase 1 — Nền tảng:** thêm dependencies; port design system (`globals.css`), layout, `SiteHeader`/`SiteFooter`/`BackToTopButton`, nền hero, icon/modal assets; dựng `content.ts` + mô hình dữ liệu.
2. **Phase 2 — Các trang landing:** Trang chủ, Giới thiệu, Danh mục di tích (lọc + tìm kiếm), template trang chi tiết `[slug]`, Liên hệ — với nội dung "kết hợp".
3. **Phase 3 — Tour VR360 Chùa Thái Lạc:** port + tổng quát hóa engine, tách config, dựng 26 cảnh + hotspot + chú thích, chạy `/tour/chua-thai-lac` hoạt động như `dinh-lang-dinh-cong`.
4. **Phase 4 — Hoàn thiện:** kiểm tra responsive, hiệu năng tải ảnh, rà soát nội dung/chính tả, SEO/metadata, kiểm thử trải nghiệm.

---

## 8. Tiêu chí hoàn thành

- Landing site Như Quỳnh đầy đủ 6 nhóm trang, đẹp, mượt, chuẩn mực, responsive.
- 15 di tích hiển thị đúng phân cấp (9 quốc gia / 6 tỉnh), lọc & tìm kiếm hoạt động.
- Tour `/tour/chua-thai-lac` xem & tương tác được đầy đủ (panorama, chuyển cảnh, bản đồ tuyến, modal thông tin, chú thích cảnh) — ngang sản phẩm `dinh-lang-dinh-cong` của pdc.
- `pdc-vr360` (Định Công) không bị ảnh hưởng.

## 9. Việc để sau (ngoài phạm vi đợt này)

- Văn bản chính thức cho 14 di tích còn lại (chủ dự án cung cấp).
- Ảnh VR360 + tour cho các di tích khác.
- File mp3 thuyết minh cho Chùa Thái Lạc.
- (Tùy chọn tương lai) phiên bản tiếng Anh.