📖 前置知識

jaba 呷爸 jaba 是一個 AI 驅動的午餐訂便當系統，透過 LINE Bot 讓群組點餐變得簡單直覺。

專為團隊設計的午餐訂餐系統，使用者只需在 LINE 群組中用自然語言告訴呷爸想吃什麼，系統就會自動處理訂單。

功能特色

LINE 群組點餐：

  • 群組點餐 Session - 說「開單」開始、「收單」結束
  • AI 對話訂餐 - 用自然語言與 AI 互動，說「我要雞腿便當」就能完成訂餐
  • 共享對話歷史 - AI 可理解跟單（+1）等上下文
  • 多店家選擇 - 當天有多家店時，可自由選擇
  • 訂單修改 - 可新增、移除品項或取消訂單
  • 飲料縮寫辨識 - 支援「微微」「少少」「半半」等常見點法
  • 自動過濾 - AI 自動辨識訂餐訊息，忽略閒聊
  • 特價優惠 - 自動套用促銷折扣（買一送一、第二杯折扣）
  • 卡路里估算 - AI 自動估算餐點熱量
  • 個人偏好 - 透過 1對1 聊天記住稱呼和飲食偏好，群組點餐時自動套用

超級管理員功能：

  • 群組管理 - 管理多個 LINE 群組的訂單
  • 群組選擇器 - 切換不同群組查看訂單
  • 訂單 CRUD - 編輯、刪除使用者訂單
  • 代理點餐 - 代替群組成員新增訂單
  • 付款追蹤 - 標記付款狀態、處理退款
  • 店家管理 - 新增、編輯、啟用/停用店家
  • 菜單辨識 - 上傳菜單圖片，AI 自動辨識並建立菜單
  • 差異預覽 - 辨識後顯示新增/修改/可刪除項目
  • 特價辨識 - 自動識別促銷標示（買一送一、第二杯折扣、限時特價）
  • 菜單編輯 - 手動調整品項名稱、價格、尺寸變體
  • 今日設定 - 設定單一或多家今日營業店家
  • 歷史清理 - 清除過期訂單資料

系統功能：

  • 即時同步 - Socket.IO 即時廣播訂單與狀態變更
  • 看板頁面 - 顯示所有群組訂單、美食評論區、LINE QRCode
  • 美食評論區 - 顯示 LINE 群組中的點餐對話
  • Session 管理 - 每日對話紀錄自動管理
  • LINE Bot 介面 - 群組點餐的入口

系統架構

系統架構

技術棧

技術 用途
FastAPI Web 框架
Socket.IO 即時通訊
Claude / Gemini AI 對話與菜單辨識
JSON 檔案 資料儲存（無資料庫）
uv 套件管理

兩個主頁面

頁面 路徑 功能
看板頁 / 群組訂單總覽、美食評論區、LINE QRCode
管理頁 /manager 超級管理員：群組訂單管理、店家管理、付款追蹤

看板頁面：

看板頁面

顯示所有群組的訂單、美食評論區（LINE 群組對話）、LINE QRCode 方便加入呷爸好友。

超級管理員頁面：

管理頁面

管理員可選擇群組、查看訂單、代理點餐、標記付款狀態。

使用方式

LINE 群組點餐：

  1. 將呷爸 LINE Bot 加入群組
  2. 發送啟用密碼讓呷爸加入白名單
  3. 點餐流程：
    • 發送「開單」開始群組點餐
    • 與呷爸對話：「我要雞腿便當」「+1」「珍奶 微微 L」
    • 發送「收單」結束點餐並顯示統計

超級管理員：

  1. 開啟管理頁 /manager
  2. 輸入管理員密碼登入
  3. 選擇群組查看訂單、編輯、標記付款
  4. 透過 AI 對話設定店家：「今天吃佳香味」
  5. 上傳菜單圖片讓 AI 自動建立菜單

AI Prompt Context 架構

呷爸的 AI 對話由四個層次組成，每次對話時動態組合：

┌─────────────────────────────────────────────────────────┐
│  Layer 4 (Top): 當前訊息 (Current Message)              │
│     └─ 使用者輸入的文字                                 │
├─────────────────────────────────────────────────────────┤
│  Layer 3: 對話歷史 (Chat History)                       │
│     └─ 最近 20 條對話記錄                               │
├─────────────────────────────────────────────────────────┤
│  Layer 2: 動態上下文 (Dynamic Context)                  │
│     └─ JSON: 今日店家、菜單、使用者偏好、目前訂單       │
├─────────────────────────────────────────────────────────┤
│  Layer 1 (Base): 系統提示詞 (System Prompt)             │
│     └─ group_ordering_prompt.md 或 manager_prompt.md    │
└─────────────────────────────────────────────────────────┘
                         │
                         ▼
              ┌─────────────────────┐
              │    AI Response      │
              │  {message, actions[]}│
              └─────────────────────┘

三種 AI 模式：

模式 提示詞 用途
群組點餐 group_ordering_prompt.md LINE 群組訂餐
個人偏好 personal_prompt.md 1對1 聊天設定偏好
管理員 manager_prompt.md 店家設定

動態上下文範例（群組點餐模式）：

{
  "today": "2025-12-09",
  "today_stores": [{"store_id": "coco", "store_name": "CoCo都可茶飲"}],
  "group_id": "C1234567890",
  "group_name": "午餐群",
  "session_active": true,
  "group_orders": [{ "user_id": "U123", "display_name": "小明", "items": [...] }]
}

支援多個 AI Provider：

  • Claude CLI (haiku, sonnet, opus)
  • Gemini CLI

菜單辨識與差異預覽

上傳菜單圖片，AI 自動提取結構化資訊：

  • 識別品項名稱和價格
  • 識別促銷標記（買一送一、第二杯折扣、限時特價）
  • 識別尺寸變體（大杯/中杯）
  • 差異預覽後選擇性應用變更

差異預覽

辨識後顯示差異預覽：綠色為新增、黃色為修改、紅色為可刪除，可選擇性套用變更。

專案結構

jaba/
├── main.py                 # FastAPI 應用程式入口
├── app/
│   ├── ai.py               # AI 整合主入口
│   ├── data.py             # 資料存取模組
│   └── providers/          # CLI Provider 模組
│       ├── __init__.py     # BaseProvider 抽象類別與工廠
│       ├── claude.py       # Claude CLI 實作
│       └── gemini.py       # Gemini CLI 實作
├── data/
│   ├── stores/             # 店家資料與菜單
│   │   └── {store_id}/
│   │       ├── info.json   # 店家資訊
│   │       ├── menu.json   # 菜單
│   │       └── images/     # 菜品圖片
│   ├── linebot/            # LINE Bot 群組資料
│   │   └── sessions/
│   │       └── {group_id}.json  # 群組點餐 session（含訂單、付款）
│   ├── users/              # 使用者資料（以 LINE User ID 識別）
│   │   └── {line_user_id}/
│   │       ├── profile.json    # 使用者偏好
│   │       └── chat_history/   # 對話歷史
│   ├── board_chat/         # 看板聊天記錄
│   └── system/             # 系統設定
│       ├── config.json     # 系統配置
│       ├── today.json      # 今日店家
│       ├── ai_config.json  # AI 模型設定
│       └── prompts/        # AI 提示詞
├── templates/              # HTML 頁面
├── demo/                   # Demo 截圖
└── static/                 # 靜態資源

快速開始

# 安裝相依套件
uv sync

# 設定 API 金鑰
export ANTHROPIC_API_KEY="your-api-key"

# 啟動伺服器
uv run uvicorn main:socket_app --reload --host 0.0.0.0 --port 8098

# 開啟瀏覽器
# http://localhost:8098

相關連結