# 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 圖資，支援地圖點擊新增足跡
- i18next 支援中英文切換，分類與設定等字串同步集中管理

### 模組切分
- `features/map`：Leaflet 地圖、點擊事件、旅遊標記
- `features/visits`：資料型別、LocalStorage Repository、React Query hooks、統計卡片與表單元件
- `features/categories`：旅程分類 CRUD、React Query 與 sidebar 管理介面
- `components/layout`：MUI AppBar + Drawer 布局、語言切換等元件
- `state`：Zustand store 控制訪問建立/編輯的 Modal
- `components/overlay/VisitModal`：以 Modal 呈現足跡表單，必須先點擊地圖右下角的 `+` 漂浮按鈕啟用定位，再第二次點擊地圖開啟表單
- `components/overlay/NavControlsDialog`：App Bar 右上角的「更多」按鈕會開啟的快速操作 Modal（語言、分類切換、相關連結）

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

### 旅程分類管理
- 所有旅程可指定分類，未指定時會自動歸入「未分類」。
- 側邊欄可透過 chip 快速篩選「全部 / 未分類 / 自訂分類」。
- 在「管理分類」清單可新增、重新命名或刪除分類；刪除時相關旅程會回到「未分類」。
- 當前分類會記錄在 LocalStorage，在地圖右下角新增旅程時會自動帶入。

### 快速操作面板
- App Bar 右上角改為「更多」圖示，點擊後會開啟 Modal。
- Modal 集中展示語言切換、目前分類切換以及開發相關連結（OpenStreetMap、React Leaflet）。
- 便於未來擴充更多設定選項，而不把 App Bar 擠得太滿。

### PWA 支援
- 新增 Web App Manifest（`client/public/manifest.webmanifest`）與 service worker 註冊，可在行動裝置安裝為獨立 App。
- 透過 `vite-plugin-pwa` 自動產生快取策略，支援離線瀏覽與版號自動更新。
- 內建 `icons/icon-192.svg`、`icons/icon-512.svg`，可於日後替換為專屬圖示。

### 多語系支援
- 透過 `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`）。

### 專案建置
- 推薦將 `client/package.json` 的 `build` 指令改為 `"build": "tsc --noEmit && vite build"`，避免 `tsconfig.node.json` 的 `noEmit` 限制造成錯誤。
- 調整後可執行 `npm run build`，產出靜態檔案於 `client/dist`。
- 首次啟用 PWA 時記得在 `client` 目錄重新執行 `npm install`，以安裝 `vite-plugin-pwa` 相依套件。

### 部署到 Vercel
1. 先在本地確認 `npm run build` 可成功（參考上節的建置指令變更）。
2. 將整個專案推送至 GitHub / GitLab / Bitbucket。
3. 在 Vercel 建立新專案時：
   - Project Root：`client`
   - Build Command：`npm run build`
   - Output Directory：`dist`
4. 連續部署：Vercel 會在每次 push default branch、自動建立 preview 的 PR 觸發建置並更新站台。
5. 若後續要加上環境變數，可在 Vercel 專案設定內補上即可。

### 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`
- [ ] 自動化部署流程模板（Vercel / GitHub Actions）

## 授權
本專案採用 MIT License，詳見 `LICENSE`。