143 lines
7.1 KiB
Markdown
143 lines
7.1 KiB
Markdown
# 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`。
|