文件
文件
運行 Zest 所需的一切。
快速開始
前置需求
- Node.js 20+（建議使用 LTS）
- pnpm 9+
- macOS 以支援 BLE 熱感打印機
- Xcode CLI 工具（用於原生編譯）
安裝
Terminal
git clone https://github.com/ec812/zestcd zestpnpm installpnpm dev開發伺服器將在 http://localhost:3898 啟動
可用指令
| Command | 說明 |
|---|---|
| pnpm dev | 啟動開發伺服器（port 3898） |
| pnpm build | 生產環境建構 |
| pnpm start | 啟動生產伺服器 |
| pnpm lint | 執行 ESLint |
| pnpm test | 執行單元測試 |
功能
顧客端
| 功能 | Route | 說明 |
|---|---|---|
| 公開菜單 | / | 多語言菜品菜單（日文、英文、中文）按分類分組 |
| 掃碼點餐 | /order/[qr_code] | 掃描桌位 QR 碼，瀏覽菜單、加單、查看帳單 |
| 帳單查看 | /bill/[qr_code] | 唯讀帳單，適用於開放中的桌位訂單 |
| 訂位 | /book | 公開訂位表單（姓名、人數、日期時間、聯絡方式） |
| 顧客命令列 | zest | 專為 AI 代理設計的 CLI，用於瀏覽菜單、下單和查詢狀態 |
員工後台
| 功能 | Route | 說明 |
|---|---|---|
| 儀表板 | /admin | 統計數據、進行中訂單、今日訂位、暢銷菜品 |
| 菜品管理 | /admin/dishes | 菜品增刪改查、圖片上傳、AI 輔助多語言填充 |
| 桌位管理 | /admin/tables | 管理桌位、QR 碼、容量、區域 |
| 訂單管理 | /admin/orders | 看板式訂單板，SSE 即時更新 |
| 訂位管理 | /admin/bookings | 月曆和列表視圖管理訂位 |
| 菜品變體 | /admin/variants | 變體群組和選項（如尺寸、溫度） |
| 時段管理 | /admin/time-slots | 早午晚餐時段，支援每道菜不同定價 |
| 設定 | /admin/settings | 主題、服務費、基本費、地址、打印機名稱 |
後端能力
- 多語言資料模型 — 每道菜、每個時段、每個描述都包含 *_ja、*_en 和 *_zh 欄位
- 基於角色的 API 認證 — super_admin、admin 和 staff 具有不同權限範圍
- 按輪次點餐、逐項廚房狀態追蹤、服務費、基本費、付款追蹤
- 堂食和外帶 — 桌位 QR 點餐和帶取餐碼的外帶
- 即時更新 — Server-Sent Events（/api/orders/stream）用於即時訂單看板
- 熱感打印 — ESC/POS 廨房單據和收據，透過 BLE 連接
- 速率限制 — 公開訂單端點的滑動視窗限制
顧客命令列工具
zest CLI 讓顧客和 AI 代理能從命令列瀏覽菜單、下單和查詢狀態。
安裝
Terminal
npm install -g zest-cli# or run without installing:npx zest-cli <command>指令
| Command | 說明 |
|---|---|
| zest menu | 列出所有可用菜品 |
| zest menu --category sashimi --pretty | 按分類篩選，以人類可讀格式輸出 |
| zest dish <id> | 顯示單道菜品詳情 |
| zest order --mode dine-in --table T01 --items '[...]' | 下堂食訂單 |
| zest order --mode takeaway --name John --phone 5555 --items '[...]' | 下外帶訂單 |
| zest status <order_id> | 查詢訂單狀態和明細 |
| zest info | 顯示餐廳設定 |
| zest configure | 建立設定檔，包含 API URL 和顧客 token |
輸出格式
- 預設輸出為緊湊 JSON（適合 AI 代理）
- --pretty 啟用人類可讀的終端輸出，價格格式化顯示
設定
CLI 將設定儲存在 ~/.zest/config.json。執行 zest configure 可自動建立此檔案。
API URL 優先順序
- 1. ZEST_API_URL 環境變數
- 2. ~/.zest/config.json 中的 apiUrl
- 3. 預設值：http://localhost:3898
技術棧
| 層級 | 技術 |
|---|---|
| 框架 | Next.js 16 (App Router) + React 19 |
| 語言 | TypeScript 5 |
| 資料庫 | SQLite via better-sqlite3 (WAL mode) |
| 樣式 | Tailwind CSS v4 + shadcn/ui |
| 認證 | bcrypt + SHA-256 API keys (sk- prefix) |
| 打印 | ESC/POS, @abandonware/noble (BLE) |
| 人工智慧 | DeepSeek API (optional) |
| 命令列工具 | Commander.js + Axios |
| 套件管理 | pnpm (monorepo) |
設定
餐廳設定
透過 /admin/settings 頁面設定你的餐廳。所有設定儲存在 SQLite 中，可透過 REST API 存取。
- 主題 — 4 款內建配色主題（鼠尾草綠、海洋藍、深紅、薰衣草紫）
- 深色模式 — 切換淺色和深色外觀
- 服務費 — 啟用/停用，設定百分比（應用於訂單）
- 基本費 — 每人基本消費
- 餐廳地址和電話號碼
- 打印機名稱 — 設定廚房和吧台打印機目標
主題
Sage Green
溫暖的大地綠 — Zest 原始配色
Ocean Blue
靈感來自海洋的冷色深藍
Crimson Red
大膽、深沉的深紅色
Lavender Purple
柔和優雅的紫色調
熱感打印
Zest 支援 BLE 熱感打印機用於廚房單據和收據。在 macOS 上，打印機不能在系統設定中配對 — 需要 GATT 存取。
- 廚房單據 — 食物送到廚房打印機，飲品送到吧台打印機
- 收據 — 格式化帳單，包含明細、服務費和總計
- QR 碼打印 — 直接將桌位 QR 碼打印到熱感打印機