Local Food — Bản đồ ẩm thực 63 tỉnh thành Việt Nam
Website giới thiệu món ăn đặc trưng của cả 63 tỉnh thành Việt Nam (theo địa giới
trước sáp nhập 2025), với bản đồ tương tác, công thức sơ lược và gợi ý cách thưởng thức.
Dự án Capstone của PM AI Bootcamp — làm theo đường ray 11 bước của
Capstone Playbook, mỗi bước có Cổng hiểu (PM phải giải thích lại được và bắt
≥1 lỗi của AI trước khi đi tiếp). Toàn bộ hồ sơ quản trị nằm trong repo, xem mục
Hồ sơ dự án.
Sản phẩm có gì
- Bản đồ tương tác (MapLibre GL + MapTiler): cả 63 tỉnh hiện đồng thời, marker là
ảnh món ăn thật chứ không phải chấm màu. Tỉnh nổi bật vẽ to hơn để dẫn mắt;
marker to dần và hiện thêm nhãn tên món khi zoom vào.
- 63 trang tỉnh (sinh tĩnh): mỗi tỉnh có 1 món chủ đạo + 2 món khác, kèm mô tả,
nguyên liệu chính, các bước làm sơ lược, cách ăn và nguồn tham chiếu.
- Tìm kiếm không dấu (gõ
pho ra phở), điều hướng thẳng tới đúng món.
- Lọc theo mùa / lễ hội (Tết Nguyên Đán, Trung Thu, bốn mùa).
- Trang
/browse liệt kê toàn bộ tỉnh, nhóm theo miền Bắc / Trung / Nam.
Số liệu nội dung
| Chỉ số | Giá trị |
|---|
| Tỉnh thành | 63 / 63 |
| Món ăn | 197 |
Nguồn tham chiếu (sourceRef) | 222 |
| Món thiếu nguồn | 0 (zod chặn ngay lúc build) |
| Món có ảnh Wikimedia thật | 75 (38%) |
| Món dùng ảnh dự phòng (gradient) | 122 (62%) |
Về ảnh: dự án không bịa URL ảnh. Món nào không tìm được ảnh thật trên
Wikimedia Commons thì dùng placeholder gradient có chủ đích, không phải ô ảnh vỡ.
Đây là lý do tỷ lệ có ảnh chỉ 38% — các món vùng núi phía Bắc và Tây Nguyên hầu như
không có ảnh trên Commons.
Công nghệ
| Thành phần | Lựa chọn | Lý do |
|---|
| Framework | Next.js 16 (App Router) + React 19 + TypeScript | Sinh tĩnh toàn bộ, SEO tốt |
| Bản đồ | MapLibre GL JS 4.7.1 + react-map-gl | Mã nguồn mở, không khoá vendor |
| Basemap | MapTiler (free tier) | Có bản đồ nền tiếng Việt chất lượng |
| Giao diện | Tailwind CSS v4 | — |
| Chuyển động | Framer Motion (motion/react) | Tôn trọng prefers-reduced-motion |
| Kiểm tra dữ liệu | zod | Validate thật 63 file JSON lúc build, không chỉ ép kiểu TypeScript |
| Lưu trữ nội dung | File JSON tĩnh, không backend | Xem ARCH-LF.md |
⚠️ MapLibre bị ghim ở 4.7.1 có lý do. Bản 6.5.0 có lỗi khiến vector tile
source không bao giờ load xong → bản đồ trắng hoàn toàn. Chi tiết điều tra nằm
trong DEVBOOK.md. Đừng nâng cấp mà không test lại kỹ.
Chạy tại máy
pnpm install
cp .env.example .env.local # rồi điền MapTiler key
pnpm dev # http://localhost:3000
Biến môi trường
Không có key thì bản đồ vẫn chạy bằng style demo công khai của MapLibre, chỉ kém đẹp hơn.
🔒 Lưu ý bảo mật: biến có tiền tố NEXT_PUBLIC_ luôn bị nhúng vào bundle
phía client — bất kỳ ai mở DevTools trên site đã deploy đều đọc được. Đây là bản
chất của thư viện bản đồ chạy phía trình duyệt, không tránh được. Vì vậy phải bật
domain restriction cho key trong MapTiler dashboard, giới hạn đúng domain deploy.
Lệnh khác
pnpm build # build production — cũng là lúc zod validate toàn bộ 63 file dữ liệu
pnpm start # chạy bản production
pnpm lint
# Ba cổng kiểm chất lượng, chạy độc lập được
pnpm check:geo # mọi centroid nằm trong đất liền VN (sinh ra từ rủi ro R13)
pnpm check:i18n # bản dịch khớp bản gốc: đủ món, đủ trường, khớp số bước
pnpm check:meal # phân loại mealTypes hợp lệ + KHÔNG trường nào khác bị sửa
check:meal làm một việc khác thường: ngoài kiểm dữ liệu, nó đối chiếu từng file
với bản trong git và fail nếu có trường nào ngoài mealTypes/mealTypeNote bị đụng.
Lý do: nhiều agent ghi song song vào data/provinces/*.json, mà đó là nội dung gốc
tiếng Việt không có bản sao nào ngoài git.
Ngoài ra node scripts/review-meal.mjs dựng phiếu soi phân loại — khoanh vùng chỗ dữ liệu
tự mâu thuẫn với nhãn, để người duyệt đọc ~23 món thay vì 197.
⚠️ Gotcha khi thêm tỉnh mới: lib/provinces.ts cache dữ liệu ở cấp module, nên
thêm file data/provinces/*.json mới mà dev server đang chạy thì route mới sẽ 404.
Phải restart dev server. Đã ghi trong DEVBOOK.md.
Cấu trúc
app/ # App Router — tiếng Việt ở gốc, tiếng Anh dưới /en
/ /browse /goi-y /provinces/[slug] /telemetry not-found
en/… # bản tiếng Anh song song, cùng bộ component
components/
map/ # FoodMap, DishMarker, MapToolbar, SovereigntyMarker, mapStyle
province/ # ProvinceHero, DishCard, DishTile, ProvinceDishExplorer
recommend/ # RerollButton, OfficeFlags — trang "Trưa nay ăn gì"
review/ # DishReviews, RecentReviews, StarRating
pages/ # thân trang dùng chung cho 2 ngôn ngữ (*View.tsx)
ui/ # Button, Badge, Sheet, Lightbox, ImageWithFallback
search/ # SearchBar (tìm kiếm không dấu)
data/
provinces/*.json # 63 file, mỗi tỉnh 1 file — thêm tỉnh = thêm file, không sửa code
i18n/en/*.json # bản dịch tiếng Anh, tách riêng để không đụng bản gốc
geo/ # ranh giới + centroid 63 tỉnh
sovereignty.json # Hoàng Sa, Trường Sa, Biển Đông — hiện ở mọi mức zoom
hero-bubbles.json # danh sách tỉnh nổi bật (marker to + mục "Tỉnh nổi bật")
lib/
types.ts schema.ts # kiểu dữ liệu + zod schema
provinces.ts geo.ts # đọc/validate dữ liệu, dựng GeoJSON cho bản đồ
i18n.ts (server) # nạp/ghép bản dịch — dùng node:fs, KHÔNG import từ client
locale.ts (dùng chung) # hằng số ngôn ngữ + localePath() — an toàn cho client
recommend.ts # bể gợi ý bữa trưa + bốc cặp tất định theo seed
reviews.ts # Supabase: đánh giá + báo nội dung sai
This is the beginning of the README. Read the rest at the original. Read the full README ↗
