feat: use gpt to create project, readme

README.md

@@ -1,2 +1,92 @@
 # 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
+- React Router 規劃 SPA 路由
+- Zustand 追蹤 UI 狀態（表單抽屜開關與初始座標）
+- React Query 統一處理資料讀寫與快取
+- React Hook Form + Zod 表單驗證
+- react-leaflet + OpenStreetMap 圖資，支援地圖點擊新增足跡
+- Tailwind CSS (JIT) 打造快速 UI
+
+### 模組切分
+- `features/map`：Leaflet 地圖、點擊事件、旅遊標記
+- `features/visits`：資料型別、LocalStorage Repository、React Query hooks、統計卡片與表單元件
+- `components/layout`：頁面主框架、側邊欄
+- `state`：Zustand store 控制表單抽屜
+
+### LocalStorage → API 的切換
+- 預設 `VisitProvider mode="local"` 會載入 `localVisitRepository`。
+- 改為 `mode="api"` 並設定 `apiBaseUrl` 後，就會改用 `VisitApiClient` 透過 REST API 存取。
+- Vite `proxy` 已轉發 `/api` 至 `http://localhost:4000`，未來後端啟動後無需改動前端呼叫。
+
+### 開發啟動
+1. 安裝相依套件：`cd client && npm install`
+2. 啟動開發伺服器：`npm run dev`
+3. 瀏覽器開啟 `http://localhost:5173`
+
+> **注意**：Leaflet 需要載入 CSS（已在 `TravelMap` 中引入 `leaflet/dist/leaflet.css`）。
+
+## 後端（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**：`features/visits/utils/geocoding.ts` 預留反向地理編碼函式，可透過自建 API Proxy 存取 Nominatim。
+4. **照片/檔案**：後端可擴增 S3/Cloudinary 上傳，再於前端 `VisitCreateInput` 增加檔案欄位。
+
+## 待辦與下一步
+- [ ] 實作 geocoding proxy，於點擊地圖後自動填入國家 / 城市
+- [ ] 加入使用者認證（如 Auth0 或自建 JWT）以支援多人服務
+- [ ] 將訪問紀錄導出成時間線或統計圖表（D3 / Recharts）
+- [ ] 建立 Vitest / Jest 單元測試與 React Testing Library 元件測試
+- [ ] 規劃 CI（GitHub Actions）自動執行 `lint` 與 `test`
+
+## 授權
+本專案採用 MIT License，詳見 `LICENSE`。