# 日本旅圖技術規劃

## 目前 MVP

- 型態：可規劃行程的互動式旅遊網站
- 技術：原生 HTML/CSS/JavaScript
- 地圖：Google Maps iframe 內嵌，並提供 Google Maps URL 跳轉
- 語言：繁中與日文
- 資料：`src/data.js` 內的結構化景點資料、來源連結與建議停留時間
- 使用者行程：透過 `src/storage.js` 保存每日行程草稿，目前預設落在 `localStorage`
- 內容後台：`admin.html` 透過 `src/storage.js` 管理待審資料草稿，可切換 local / Supabase
- 部署：可直接放到 Vercel、Cloudflare Pages、Netlify 或任意靜態主機

## 內容審核流程

現在的靜態後台先模擬正式資料庫流程：

1. 在 `admin.html` 新增景點草稿。
2. 每筆草稿需包含繁中/日文內容、地區、主題、座標、Google Maps 查詢字串、官方網址與至少一筆來源。
3. 草稿狀態可設為待審、已通過或已退回。
4. 主站 `index.html` 會自動併入已通過的本機草稿景點。
5. 後台可匯出已通過 JSON，之後可作為資料庫 seed 或 API payload。
6. 後台可貼上 JSON 批次匯入，格式可參考 `docs/sample-import.json`。

## 批次匯入格式

匯入器接受三種形狀：

- `[{ ...place }]`
- `{ "places": [{ ...place }] }`
- `{ "drafts": [{ "place": { ...place } }] }`

每筆 place 需要：

- `id`：英數與連字號，例如 `matsumoto-castle`
- `region`：必須存在於 `src/data.js` 的 regions
- `theme` 與 `tags`：必須存在於 `src/data.js` 的 themes
- `stayHours`、`lat`、`lng`
- `googleQuery`、`officialUrl`
- `sources`：至少一筆 `{ "name": "...", "url": "https://..." }`
- `zh` 與 `ja`：各含 `name`、`subtitle`、`summary`、`note`、`area`

## 正式版升級方向

- 前端：Next.js + TypeScript
- UI：Tailwind CSS，保留目前的資訊架構與元件切分
- 後端：Next.js Route Handlers，之後可拆成獨立 API
- 資料庫：PostgreSQL，建議 Supabase 或 Neon
- ORM：Prisma
- 多語系：next-intl，路徑規劃為 `/zh-TW` 與 `/ja`
- 地圖：Google Maps Embed API + Places API
- 排程：每日或每週擷取多來源摘要，進入人工審核佇列

## 建議資料表

- `regions`：地區、都道府縣、城市層級
- `places`：景點、美食、溫泉、文化點、購物點
- `place_translations`：繁中與日文名稱、摘要、文化說明
- `place_sources`：來源名稱、URL、擷取時間、授權註記
- `tags`：文化、美食、自然、歷史、購物、溫泉、藝術
- `place_tags`：景點與標籤關聯
- `content_drafts`：後台待審資料草稿
- `itineraries`：行程主檔
- `itinerary_days`：每日行程
- `itinerary_items`：行程項目順序

目前前端行程規劃器已支援每日開始時間、預估移動時間、跨日拖曳與 TXT 匯出；資料庫的 `itinerary_days` 已保留 `start_time` 與 `move_minutes`。

## 多來源策略

- 官方旅遊資料：JNTO、都道府縣與市町村觀光網站
- 開放內容：Wikivoyage、Wikipedia、Wikimedia Commons，需保留授權與 attribution
- 地點資料：Google Places API 補 Place ID、評分、營業時間、照片
- 外部文章：只保留標題、摘要、URL 與來源，不直接搬運全文
- 審核流程：半自動擷取後進入草稿，由管理者確認才發布

## 來源擷取流程

`scripts/source-intake.js` 已提供雛形，會讀取 `data/source-seeds.json`，從本機 HTML 或 URL 抽取 title、description、canonical 與第一段摘要，輸出 `docs/generated/source-drafts.json` 供後台批次匯入。細節見 `docs/source-intake.md`。

## Supabase/PostgreSQL

資料庫 schema 已整理在 `supabase/migrations/0001_initial_schema.sql`，初始資料由 `scripts/build-db-seed.js` 產生 `db/seed.sql`。細節見 `docs/database.md`。

## UI 與手機版

主站與後台採 responsive grid。`scripts/verify-ui.js` 會輸出桌機截圖、手機主站截圖與手機後台截圖，並檢查水平溢出。截圖位置：

- `artifacts/home.png`
- `artifacts/home-mobile.png`
- `artifacts/admin-mobile.png`

## Google Places API 欄位

欄位規格整理在 `docs/google-places-spec.md`。目前主站與後台已支援 optional `google` 物件，可先保存 Place ID、Google Maps URI、評分、評分數、營業時間與照片 metadata。等正式串 API 後，資料同步任務只需要把 API 回應轉成這個欄位格式。

## 部署模式

第一版可用靜態部署，現在建議先 build 到 `dist`：

1. 推到 GitHub。
2. 用 Vercel、Cloudflare Pages 或 Netlify 連接 repository。
3. Build command 使用 `node scripts/build-site.js` 或 `npm run build`。
4. Output directory / publish directory 使用 `dist`。

部署細節與環境變數見 `docs/deployment.md`。

正式版升級後：

1. Vercel 部署 Next.js。
2. Supabase/Neon 提供 PostgreSQL。
3. GitHub Actions 或 Vercel Cron 執行資料同步任務。
4. Google Maps API key 放在環境變數。