From cad2885cc2c819c4bfae4de358215b4960bf9ac7 Mon Sep 17 00:00:00 2001 From: MH Hung Date: Wed, 1 Oct 2025 13:12:43 +0800 Subject: [PATCH] docs: update README --- README.md | 31 ++++++++++++++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index b4c0d80..73ad3e5 100644 --- a/README.md +++ b/README.md @@ -25,19 +25,33 @@ traveling-around-the-world/ - 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/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 擠得太滿。 + ### 多語系支援 - 透過 `react-i18next` 提供繁體中文與英文，語系檔位於 `client/src/locales/`。 - 右上角的語言選單 (`LanguageSwitcher`) 可即時切換語言，並記錄在 LocalStorage 方便下次載入。 @@ -49,6 +63,20 @@ traveling-around-the-world/ > **注意**：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`。 + +### 部署到 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 前端）： @@ -102,6 +130,7 @@ RESTful 端點： - [ ] 將訪問紀錄導出成時間線或統計圖表（D3 / Recharts） - [ ] 建立 Vitest / Jest 單元測試與 React Testing Library 元件測試 - [ ] 規劃 CI（GitHub Actions）自動執行 `lint` 與 `test` +- [ ] 自動化部署流程模板（Vercel / GitHub Actions） ## 授權 本專案採用 MIT License，詳見 `LICENSE`。