docs: update README

This commit is contained in:
2025-10-01 13:12:43 +08:00
parent 2dbfc43cad
commit cad2885cc2

View File

@@ -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 元件測試
- [ ] 規劃 CIGitHub Actions自動執行 `lint``test`
- [ ] 自動化部署流程模板Vercel / GitHub Actions
## 授權
本專案採用 MIT License詳見 `LICENSE`