# This is NOT the Next.js you know This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices. # Language - **一律以台灣繁體中文回答使用者。** - **程式碼內禁止中文**：comment、log、字串常數、識別字一律用英文（面向使用者的 UI 文案除外）。 # Ready Set Ride 「展件互動系統」的 iPad 端控制介面。三組「電腦＋螢幕＋iPad」在展場區網內，民眾透過 iPad（PWA）操控 Unity 螢幕內容，流程結束後上傳圖片至客戶 FTPS，並以 QR Code 顯示對應圖片網址供掃描。 完整的系統架構、網路 / TLS、MQTT topic 設計、Windows 部署與開工檢查清單請見 **[docs/architecture.md](docs/architecture.md)**（單一事實來源，動到部署 / MQTT / 上傳流程前先讀）。 ## Stack - **Next.js 16 (Turbopack)** + React 19，App Router，`src/` 目錄。`output: 'standalone'`（Windows 上以 `node server.js` 跑，非 `next start`）。 - **Bun** 為套件管理與 script runner（`bun run dev` / `bun run build`）。 - **PWA**：`@serwist/turbopack`（service worker，非 `@serwist/next`）。 - **MQTT**：`mqtt.js` over WebSocket（`useMQTT` hook）。 - **狀態**：`zustand` + `persist`（裝置設定，如 station id）。 - **樣式**：Tailwind v4 + shadcn（style `base-nova`，icon `lucide`）。 - **驗證**：`zod` v4（import 為 `import * as z from 'zod'`）。 - **圖片上傳**：`basic-ftp`（implicit FTPS）。 ## Commands - `bun run dev` — 開發伺服器 - `bun run build` — production build - `bun run lint` — Biome check - `bun run format` — Biome format（write） ## Conventions - 路徑別名 `@/*` → `./src/*`。元件 `@/components`、UI `@/components/ui`、hooks `@/hooks`、lib `@/lib`。 - **Biome** 為唯一 formatter / linter：2 空格縮排、**single quotes**、import 自動排序。`src/components/ui`（shadcn 產出）不在 format / lint 範圍內，勿手動改它的風格。 - Next.js domain rules（`next` / `react`）已在 Biome 開啟，遵守其提示。 ## Gotchas - **`src/` 目錄**：所有 app code 在 `src/` 下。serwist 的 `swSrc` 等以「專案根目錄」為基準的路徑要寫成 `src/app/sw.ts`，不是 `app/sw.ts`（後者會在 build collect page data 階段報 `Could not resolve .../app/sw.ts`）。 - **FTPS 必須跑在 Node runtime，不能用 Bun**：此 FTPS server 在 data connection 上要求 TLS session resumption，Bun 不支援。涉及 `src/lib/ftps.ts` 的 Server Action / script 一律標 Node runtime（standalone 預設即 Node，勿標 edge）。 - FTPS 設定由環境變數載入（`FTP_HOST` / `FTP_USER` / `FTP_PASSWORD` 必填，`FTP_PORT`/`FTP_REMOTE_DIR`/`FTP_PUBLIC_BASE_URL` 選填），見 `loadFtpConfig()`。勿把帳密寫死進程式碼。 - **Windows host**：路徑用 `path` API，勿寫死 POSIX 斜線。