goodgo-platform/docs/audits/PROPERTY_DETAIL_INDEX.md

# Trang Chi Tiết Bất Động Sản - Mục Lục Tài Liệu

Ngày tạo: 2026-04-11  
Dự án: GoodGo Platform (Bất Động Sản Việt Nam)

---

## 📚 Các Tệp Tài Liệu

### 1. **PROPERTY_DETAIL_PAGE_ANALYSIS.md** (17KB, 553 dòng)
**Phân Tích Toàn Diện** - Bắt đầu từ đây để hiểu đầy đủ

Nội dung:
- ✅ Tổng quan dự án (Next.js 15, Tailwind, Zustand)
- ✅ Cấu trúc trang đầy đủ và kiến trúc
- ✅ Triển khai ảnh bất động sản
- ✅ Các thành phần liên quan đến ảnh (thư viện ảnh, tải lên)
- ✅ Cấu trúc và mẫu thành phần dự án
- ✅ Mẫu sử dụng Next.js Image
- ✅ Mẫu quản lý trạng thái (Zustand)
- ✅ Các thư viện bên thứ ba hiện có
- ✅ Tailwind và các token thiết kế
- ✅ API và kiểu dữ liệu (PropertyMedia, ListingDetail)
- ✅ Cấu trúc tệp đầy đủ
- ✅ Những điểm quan trọng và thực hành tốt nhất
- ✅ Các phụ thuộc chưa có

**Dùng khi:** Bạn cần hiểu sâu về kiến trúc

---

### 2. **PROPERTY_DETAIL_QUICK_REFERENCE.md** (13KB, 583 dòng)
**Đoạn Mã & Mẫu** - Hướng dẫn tra cứu nhanh

Nội dung:
- 🎯 Điều hướng nhanh (đường dẫn tệp, các route)
- 🖼️ Làm việc với ảnh (thư viện ảnh, tải lên, cấu trúc dữ liệu)
- 🎨 Mẫu tạo kiểu (tỉ lệ khung hình, các lớp Tailwind)
- 🔄 Mẫu quản lý trạng thái (Zustand, trạng thái cục bộ)
- 🧩 Mẫu thành phần UI (Button, Badge, Card, Dialog)
- 📱 Mẫu thiết kế đáp ứng (điểm dừng, lưới)
- 🔗 Các import thông dụng (import sẵn sàng để sao chép)
- 📊 Ví dụ lấy dữ liệu
- 🌐 Quốc tế hóa
- 🔐 Tính năng bảo mật
- 🧪 Các cân nhắc kiểm thử
- 🚀 Mẹo tối ưu hóa hiệu suất
- 📋 Các tác vụ thông dụng (thêm phần tử UI, chỉnh sửa thư viện ảnh)
- 🐛 Các vấn đề phổ biến & giải pháp

**Dùng khi:** Bạn cần đoạn mã, mẫu, hoặc câu trả lời nhanh

---

### 3. **PROPERTY_DETAIL_COMPONENTS_MAP.md** (14KB, 601 dòng)
**Phân Cấp Thành Phần & Kiến Trúc** - Tài liệu tham khảo trực quan

Nội dung:
- 🎯 Phân cấp thành phần trang (cây trực quan)
- 🖼️ Chi tiết thành phần Thư Viện Ảnh
- 📱 Chi tiết thành phần Tải Lên Ảnh
- 🧩 Các thành phần liên quan (kết quả tìm kiếm, thẻ bất động sản)
- 🌐 Luồng dữ liệu & ánh xạ API
- 🎨 Kiến trúc tạo kiểu
- 📊 Mẫu quản lý trạng thái
- 🔗 Bản đồ import & tham chiếu tệp
- 📈 Mức độ phức tạp của thành phần
- 🚀 Các cân nhắc về hiệu suất
- 🔄 Luồng điều hướng
- 📋 Danh sách kiểm tra thành phần
- 🛠️ Hướng dẫn bảo trì

**Dùng khi:** Bạn cần hiểu mối quan hệ giữa các thành phần

---

## 🎯 Hướng Dẫn Bắt Đầu Nhanh

### Để Hiểu Triển Khai Hiện Tại:
1. Bắt đầu với **PROPERTY_DETAIL_PAGE_ANALYSIS.md** phần:
   - Phần 1: Cấu Trúc Trang Chi Tiết Bất Động Sản
   - Phần 2: Ảnh Bất Động Sản - Triển Khai Hiện Tại
   - Phần 3: Các Thành Phần Liên Quan Đến Ảnh

### Để Thực Hiện Thay Đổi:
1. Kiểm tra **PROPERTY_DETAIL_QUICK_REFERENCE.md**:
   - Tìm mẫu hoặc thành phần liên quan
   - Sao chép đoạn mã
   - Điều chỉnh cho phù hợp nhu cầu của bạn

2. Tham chiếu **PROPERTY_DETAIL_COMPONENTS_MAP.md**:
   - Hiểu vị trí của thành phần
   - Kiểm tra luồng dữ liệu
   - Xác minh quản lý trạng thái

### Để Xây Dựng Tính Năng Ảnh Mới:
1. **PROPERTY_DETAIL_PAGE_ANALYSIS.md** - Phần 5 (Cách Sử Dụng Next.js Image)
2. **PROPERTY_DETAIL_QUICK_REFERENCE.md** - Phần "Working with Images"
3. **PROPERTY_DETAIL_COMPONENTS_MAP.md** - "Image Gallery Component Details"

---

## 📍 Vị Trí Các Tệp Quan Trọng

### Tệp Chính
- **Trang**: `apps/web/app/[locale]/(public)/listings/[id]/page.tsx`
- **Client Chi Tiết**: `apps/web/components/listings/listing-detail-client.tsx`
- **Thư Viện Ảnh**: `apps/web/components/listings/image-gallery.tsx`
- **Tải Lên Ảnh**: `apps/web/components/listings/image-upload.tsx`
- **Thẻ Bất Động Sản**: `apps/web/components/search/property-card.tsx`

### Cấu Hình
- **Cấu Hình Tailwind**: `apps/web/tailwind.config.ts`
- **Cấu Hình Next.js**: `apps/web/next.config.js`
- **Kiểu Dáng Toàn Cục**: `apps/web/app/globals.css`

### API & Trạng Thái
- **API Listings**: `apps/web/lib/listings-api.ts`
- **Store Xác Thực**: `apps/web/lib/auth-store.ts`
- **Store So Sánh**: `apps/web/lib/comparison-store.ts`

### Thành Phần UI
- **Button**: `apps/web/components/ui/button.tsx`
- **Badge**: `apps/web/components/ui/badge.tsx`
- **Card**: `apps/web/components/ui/card.tsx`
- **Dialog**: `apps/web/components/ui/dialog.tsx`

---

## 🔑 Các Công Nghệ Chính

| Công Nghệ | Phiên Bản | Mục Đích |
|-----------|---------|---------|
| Next.js | 15.5.14 | Framework full-stack (App Router) |
| React | 18.3.0 | Thư viện UI |
| Tailwind CSS | 3.4.0 | Tạo kiểu với biến CSS |
| Zustand | 5.0.12 | Quản lý trạng thái |
| next-intl | 4.9.0 | i18n (Tiếng Việt/Tiếng Anh) |
| React Query | 5.96.2 | Quản lý trạng thái máy chủ |
| Lucide React | 1.7.0 | Biểu tượng |
| Mapbox GL | 3.21.0 | Bản đồ |
| CVA | 0.7.1 | Biến thể thành phần |

---

## ✨ Tính Năng Hiện Tại

### Hiển Thị Ảnh
- ✅ Ảnh chính đáp ứng (tỉ lệ khung hình 16:9)
- ✅ Nút điều hướng Trước/Tiếp theo
- ✅ Huy hiệu đếm ảnh ("X / Tổng số")
- ✅ Hình thu nhỏ cuộn ngang (64x64px)
- ✅ Tô sáng hình thu nhỏ được chọn
- ✅ Dự phòng trạng thái trống
- ✅ Tối ưu hóa Next.js Image (kích thước đáp ứng)
- ✅ Tải chậm cho hình thu nhỏ
- ✅ Tải ưu tiên cho ảnh đầu tiên

### Tải Lên Ảnh
- ✅ Hỗ trợ kéo & thả
- ✅ Nhấp để duyệt
- ✅ Xác thực loại tệp (JPEG, PNG, WebP)
- ✅ Xác thực kích thước tệp (tối đa 10MB)
- ✅ Giới hạn tối đa 20 tệp
- ✅ Lưới xem trước
- ✅ Nút xóa khi di chuột qua
- ✅ Chỉ báo ảnh bìa
- ✅ Dọn dẹp URL khi unmount

### Tính Năng Trang
- ✅ Siêu dữ liệu SEO (Open Graph, Twitter Cards)
- ✅ Dữ liệu có cấu trúc JSON-LD
- ✅ Điều hướng breadcrumb
- ✅ Thẻ chi tiết bất động sản
- ✅ Danh sách tiện ích
- ✅ Tích hợp bản đồ
- ✅ Thanh bên liên hệ (cố định)
- ✅ Thống kê (lượt xem, lưu, hỏi thăm)
- ✅ Tích hợp tính năng so sánh

---

## 🚀 CHƯA Được Triển Khai

- ❌ Lightbox ảnh / zoom modal
- ❌ Điều hướng bàn phím (← →)
- ❌ Cử chỉ chạm / hỗ trợ vuốt
- ❌ Hiệu ứng chuyển tiếp carousel ảnh
- ❌ Thanh tiến trình tải lên
- ❌ Tiến trình tải lên nhiều tệp
- ❌ Cắt / chỉnh sửa ảnh
- ❌ Phát lại video
- ❌ Trình xem toàn cảnh 360°
- ❌ Phân tích ảnh bằng AI

---

## 📋 Tài Liệu Tham Khảo Nhanh Cấu Trúc Dữ Liệu

### PropertyMedia
```typescript
{
  id: string;
  url: string;              // HTTPS URL to image
  type: 'image' | 'video';  // Type filter
  order: number;            // Sort order (0, 1, 2...)
  caption: string | null;   // Optional caption
}
```

### ListingDetail (một phần)
```typescript
{
  id: string;
  property: {
    media: PropertyMedia[];  // Array of images/videos
    // ... other property fields
  };
  // ... other listing fields
}
```

---

## 🎓 Lộ Trình Học Tập

### Tôi muốn hiểu cách ảnh hoạt động:
1. Đọc: **PROPERTY_DETAIL_PAGE_ANALYSIS.md** - Phần 2
2. Xem lại: **PROPERTY_DETAIL_QUICK_REFERENCE.md** - Phần "Working with Images"
3. Kiểm tra: mã nguồn `image-gallery.tsx`
4. Kiểm tra: cấu hình ảnh `next.config.js`

### Tôi muốn chỉnh sửa thư viện ảnh:
1. Kiểm tra: **PROPERTY_DETAIL_QUICK_REFERENCE.md** - "Modify Image Gallery"
2. Chỉnh sửa: `apps/web/components/listings/image-gallery.tsx`
3. Kiểm thử: Hành vi đáp ứng và thay đổi trạng thái
4. Tham chiếu: **PROPERTY_DETAIL_COMPONENTS_MAP.md** - "Image Gallery Component Details"

### Tôi muốn thêm tính năng mới (như lightbox):
1. Chọn thư viện: **PROPERTY_DETAIL_PAGE_ANALYSIS.md** - Phần 7
2. Cài đặt: Dùng `pnpm add package-name -F @goodgo/web`
3. Tạo: Thành phần wrapper mới
4. Tích hợp: Với ImageGallery hiện có
5. Kiểm thử: Nhiều ảnh, đáp ứng, các trường hợp ngoại lệ

### Tôi muốn hiểu quản lý trạng thái:
1. Đọc: **PROPERTY_DETAIL_PAGE_ANALYSIS.md** - Phần 6
2. Xem lại: **PROPERTY_DETAIL_QUICK_REFERENCE.md** - Phần "State Management"
3. Kiểm tra: `auth-store.ts` và `comparison-store.ts`

### Tôi muốn hiểu mẫu thành phần:
1. Đọc: **PROPERTY_DETAIL_PAGE_ANALYSIS.md** - Phần 4
2. Kiểm tra: **PROPERTY_DETAIL_COMPONENTS_MAP.md** - "Component Complexity Levels"
3. Xem lại: **PROPERTY_DETAIL_QUICK_REFERENCE.md** - Phần "UI Component Patterns"

---

## 🔗 Điều Hướng Giữa Các Tài Liệu

```
PROPERTY_DETAIL_PAGE_ANALYSIS.md
├─ "Section 1" → Component structure → See PROPERTY_DETAIL_COMPONENTS_MAP.md
├─ "Section 2" → Image implementation → See PROPERTY_DETAIL_QUICK_REFERENCE.md "Working with Images"
├─ "Section 4" → Component patterns → See PROPERTY_DETAIL_QUICK_REFERENCE.md "UI Component Patterns"
├─ "Section 5" → Next.js patterns → See PROPERTY_DETAIL_QUICK_REFERENCE.md "Using Images in Components"
└─ "Section 6" → State management → See PROPERTY_DETAIL_QUICK_REFERENCE.md "State Management"

PROPERTY_DETAIL_QUICK_REFERENCE.md
├─ Quick navigation → See PROPERTY_DETAIL_COMPONENTS_MAP.md for full tree
├─ Working with images → See PROPERTY_DETAIL_PAGE_ANALYSIS.md Section 2
└─ Common tasks → See PROPERTY_DETAIL_COMPONENTS_MAP.md "Maintenance Guide"

PROPERTY_DETAIL_COMPONENTS_MAP.md
├─ Page hierarchy → Overview → See PROPERTY_DETAIL_PAGE_ANALYSIS.md Section 1
├─ Gallery details → Implementation → See PROPERTY_DETAIL_PAGE_ANALYSIS.md Section 2
└─ Import map → File paths → See PROPERTY_DETAIL_PAGE_ANALYSIS.md Section 10
```

---

## 💡 Mẹo & Thực Hành Tốt Nhất

### Tối Ưu Hóa Ảnh
- Luôn dùng thuộc tính `sizes` với Next.js Image
- Chỉ đặt `priority={true}` cho ảnh hiển thị trên màn hình đầu tiên
- Dùng container tỉ lệ khung hình để tránh dịch chuyển bố cục
- Để Next.js tự chọn định dạng (WebP, AVIF)

### Thiết Kế Thành Phần
- Giữ các thành phần tập trung (trách nhiệm đơn lẻ)
- Dùng CVA để quản lý biến thể
- Ưu tiên kết hợp hơn kế thừa
- Giữ trạng thái cục bộ cho UI, trạng thái toàn cục cho ứng dụng

### Quản Lý Trạng Thái
- Dùng Zustand cho trạng thái toàn cục (xác thực, so sánh)
- Dùng trạng thái React cục bộ cho UI thành phần (chỉ số thư viện ảnh)
- Dùng React Query cho trạng thái máy chủ
- Chỉ lưu dữ liệu thiết yếu vào localStorage

### Kiểm Thử
- Mock thành phần Next.js Image
- Kiểm thử hành vi đáp ứng
- Kiểm thử các trường hợp ngoại lệ (trạng thái trống, nhiều ảnh)
- Mock các store Zustand

---

## 🤝 Đóng Góp Thay Đổi

### Để chỉnh sửa thư viện ảnh:
1. Tạo nhánh mới
2. Chỉnh sửa `apps/web/components/listings/image-gallery.tsx`
3. Kiểm thử hành vi đáp ứng
4. Cập nhật định nghĩa kiểu nếu cần
5. Gửi PR kèm mô tả

### Để thêm tính năng ảnh mới:
1. Kiểm tra PROPERTY_DETAIL_PAGE_ANALYSIS.md Phần 12 (phần chưa có)
2. Đánh giá các lựa chọn thư viện
3. Tạo thành phần wrapper
4. Tích hợp mà không phá vỡ các tính năng hiện có
5. Ghi lại các thay đổi

### Để cập nhật tài liệu:
1. Chỉnh sửa tệp `.md` tương ứng
2. Giữ các phần có tổ chức
3. Bao gồm ví dụ mã
4. Tham chiếu chéo các tài liệu khác
5. Duy trì định dạng nhất quán

---

## 📞 Câu Trả Lời Nhanh

**H: Làm thế nào để hiển thị ảnh?**  
Đ: Dùng `next/image` với bố cục `fill` và container tỉ lệ khung hình. Xem PROPERTY_DETAIL_QUICK_REFERENCE.md "Using Images in Components"

**H: Làm thế nào để thêm quản lý trạng thái?**  
Đ: Dùng Zustand cho toàn cục, React.useState cho cục bộ. Xem PROPERTY_DETAIL_PAGE_ANALYSIS.md Phần 6

**H: Làm thế nào để thêm lightbox?**  
Đ: Cài đặt thư viện, tạo wrapper, tích hợp với thư viện ảnh. Xem PROPERTY_DETAIL_QUICK_REFERENCE.md "Add Image Lightbox"

**H: Các thành phần UI ở đâu?**  
Đ: `apps/web/components/ui/`. Xem PROPERTY_DETAIL_PAGE_ANALYSIS.md Phần 10

**H: Những định dạng ảnh nào được cho phép?**  
Đ: JPEG, PNG, WebP. Xem PROPERTY_DETAIL_QUICK_REFERENCE.md "File Upload Component"

**H: Có điều hướng bàn phím không?**  
Đ: Hiện chưa có. Xem PROPERTY_DETAIL_COMPONENTS_MAP.md "Component Checklist"

---

## 📊 Thống Kê Tài Liệu

| Chỉ Số | Giá Trị |
|--------|-------|
| Tổng Số Dòng | 1.737 |
| Tài Liệu Phân Tích | 553 dòng |
| Tài Liệu Tham Khảo Nhanh | 583 dòng |
| Bản Đồ Thành Phần | 601 dòng |
| Ví Dụ Mã | 50+ đoạn |
| Tệp Quan Trọng Được Ghi Lại | 20+ |
| Công Nghệ Được Đề Cập | 10+ |

---

## ✅ Danh Sách Kiểm Tra Cho Nhà Phát Triển Mới

- [ ] Đọc PROPERTY_DETAIL_PAGE_ANALYSIS.md (Phần 1-3)
- [ ] Xem lại PROPERTY_DETAIL_COMPONENTS_MAP.md (Phân cấp trang)
- [ ] Kiểm tra vị trí tệp quan trọng (liệt kê ở trên)
- [ ] Hiểu cấu trúc dữ liệu (PropertyMedia, ListingDetail)
- [ ] Xem lại mã nguồn thư viện ảnh
- [ ] Hiểu mẫu Zustand store
- [ ] Xem lại mẫu thành phần UI
- [ ] Làm quen với các lớp Tailwind
- [ ] Kiểm thử với môi trường phát triển cục bộ
- [ ] Đánh dấu trang mục lục này để tham chiếu nhanh

---

## 🎓 Các Bước Tiếp Theo

1. **Hiểu Trạng Thái Hiện Tại**
   - Đọc phân tích toàn diện
   - Xem lại phân cấp thành phần
   - Kiểm tra các thành phần hiện có

2. **Lên Kế Hoạch Thay Đổi**
   - Tham chiếu hướng dẫn nhanh
   - Kiểm tra mẫu mã
   - Xác minh cấu trúc dữ liệu

3. **Triển Khai & Kiểm Thử**
   - Dùng các đoạn mã được cung cấp
   - Tuân theo các mẫu
   - Kiểm thử đáp ứng

4. **Cập Nhật Tài Liệu**
   - Cập nhật mục lục này nếu cần
   - Thêm vào các phần liên quan
   - Duy trì tính nhất quán

---

**Cập Nhật Lần Cuối:** 2026-04-11  
**Phiên Bản Tài Liệu:** 1.0  
**Trạng Thái:** Hoàn Chỉnh & Toàn Diện