traveling-around-the-world/README.md

traveling-around-the-world

一個以 React 為核心的單頁式應用程式（SPA），用來記錄自己走訪過的國家、城市與時間軸。初期資料儲存在瀏覽器 LocalStorage，並預留後端 Express + MongoDB 的擴充架構，後續可平滑升級成多人同步的雲端服務。

Monorepo 結構

traveling-around-the-world/
├─ client/   # Vite + React + TS 的前端 SPA
├─ server/   # Express + MongoDB (未來) API 服務
└─ shared/   # 前後端共用的型別定義

• client 預設採 LocalStorage 擷取資料，並透過 VisitProvider 可快速切換成 API 模式。
• server 已放好 Express + Mongoose 架構與 RESTful routes，只需接上 MongoDB 並啟動即可提供資料。
• shared 放行程型別 VisitDto，讓前後端保持相同資料契約。

前端（client）

技術與工具

• Vite + React 18 + TypeScript
• Material UI + Emotion 建構一致的 UI 與主題
• React Router 規劃 SPA 路由
• Zustand 追蹤 UI 狀態（訪問表單 Modal 與初始座標）
• React Query 統一處理資料讀寫與快取
• React Hook Form + Zod 表單驗證
• react-leaflet + OpenStreetMap 圖資，支援地圖點擊新增足跡

模組切分

• features/map：Leaflet 地圖、點擊事件、旅遊標記
• features/visits：資料型別、LocalStorage Repository、React Query hooks、統計卡片與表單元件
• components/layout：MUI AppBar + Drawer 布局、語言切換等元件
• state：Zustand store 控制訪問建立/編輯的 Modal
• components/overlay/VisitModal：以 Modal 呈現足跡表單，地圖右下角的 + 漂浮按鈕或點擊地圖即可開啟

LocalStorage → API 的切換

• 預設 VisitProvider mode="local" 會載入 localVisitRepository。
• 改為 mode="api" 並設定 apiBaseUrl 後，就會改用 VisitApiClient 透過 REST API 存取。
• Vite proxy 已轉發 /api 至 http://localhost:4000，未來後端啟動後無需改動前端呼叫。

多語系支援

• 透過 react-i18next 提供繁體中文與英文，語系檔位於 client/src/locales/。
• 右上角的語言選單 (LanguageSwitcher) 可即時切換語言，並記錄在 LocalStorage 方便下次載入。

開發啟動

1. 安裝相依套件：cd client && npm install
2. 啟動開發伺服器：npm run dev
3. 瀏覽器開啟 http://localhost:5173

注意：Leaflet 需要載入 CSS（已在 TravelMap 中引入 leaflet/dist/leaflet.css）。

Docker Compose 啟動

若想直接以容器方式啟動整個堆疊（MongoDB + Node API + Nginx 前端）：

1. 建立映像：docker compose build
2. 啟動服務：docker compose up -d
3. 前端：http://localhost:3000
4. API：http://localhost:4000

預設前端仍採 LocalStorage。如果要改用 API 資料來源，請在 client/src/app/App.tsx 把 VisitProvider mode="local" 改成 mode="api"。

後端（server）

技術堆疊

• Express 4
• Mongoose 8 + MongoDB（內建 visit schema，資料結構與前端共用）
• Zod 驗證 API 請求 payload
• Helmet、CORS、Morgan 提供基礎安全與紀錄

架構亮點

• src/app.ts 建立 Express App、共用中介層、/health 健康檢查
• src/modules/visits：模型、Service、Controller、Router 切分清晰
• visit.mapper.ts 將 Mongoose Doc 轉成 shared/visit.ts 的 DTO
• infra/db/mongo.ts 佈建 Mongo 連線抽象

啟動指令

1. 安裝套件：cd server && npm install
2. 建立 .env（可複製 .env.example）並設定 MONGODB_URI
3. 開發模式：npm run dev
4. 編譯產出：npm run build -> dist/

RESTful 端點：

• GET /api/visits：取得全部足跡
• POST /api/visits：新增足跡
• GET /api/visits/:id
• PUT /api/visits/:id
• DELETE /api/visits/:id

共享型別（shared）

• shared/visit.ts 定義 Visit DTO，前端 Visit 及後端回傳皆採相同結構。
• Vite 透過 @shared/* alias 匯入，後端則直接使用相對路徑，確保型別同步。

開發流程建議

1. LocalStorage MVP：僅啟動前端即可使用，點擊地圖開啟表單、資料存在瀏覽器。
2. 串接 API：建立 MongoDB，啟動 npm run dev 後將前端 VisitProvider 切換到 API 模式。
3. Geocoding：前端已透過 Nominatim 反向地理編碼在點擊地圖時預填國家 / 城市；若需更高配額可在後端建立 Proxy。
4. 照片/檔案：後端可擴增 S3/Cloudinary 上傳，再於前端 VisitCreateInput 增加檔案欄位。

待辦與下一步

• 實作 geocoding proxy，於點擊地圖後自動填入國家 / 城市
• 加入使用者認證（如 Auth0 或自建 JWT）以支援多人服務
• 將訪問紀錄導出成時間線或統計圖表（D3 / Recharts）
• 建立 Vitest / Jest 單元測試與 React Testing Library 元件測試
• 規劃 CI（GitHub Actions）自動執行 lint 與 test

授權

本專案採用 MIT License，詳見 LICENSE。