docs: update README
This commit is contained in:
31
README.md
31
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`。
|
||||
|
Reference in New Issue
Block a user