把 ChefsMate 變成有「AI 店長」的 POS — 先做可行性盤點

12. 給工程師看的技術規格

以下為 Phase 2 落地時的具體技術設計，給後續實作參考。本 section 預設讀者熟悉 supabase / Next.js / Swift。

12.1 Event Log 表設計

CREATE TABLE event_log (
  id BIGSERIAL PRIMARY KEY,
  ts TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  restaurant_id UUID NOT NULL REFERENCES restaurants(id),
  event_type TEXT NOT NULL,        -- e.g. "reservation.cancelled"
  entity_table TEXT NOT NULL,      -- "reservations"
  entity_id UUID NOT NULL,
  actor_user_profile_id UUID,      -- nullable for system events
  actor_role TEXT,                 -- "owner" / "staff" / "customer" / "system"
  payload JSONB NOT NULL,          -- { from, to, reason, ... }
  importance SMALLINT DEFAULT 5,   -- 0-10, AI scoring use
  correlation_id UUID,             -- 串連 multi-step 操作
  created_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE INDEX idx_event_log_restaurant_ts ON event_log(restaurant_id, ts DESC);
CREATE INDEX idx_event_log_entity ON event_log(entity_table, entity_id);
CREATE INDEX idx_event_log_type_ts ON event_log(event_type, ts DESC);
CREATE INDEX idx_event_log_high_importance ON event_log(restaurant_id, ts DESC) WHERE importance >= 7;

12.2 Event 寫入策略

• 不用 PG trigger（trigger 寫 JSONB 容易死掉、無法 testable）
• 改在每個 Orchestrator 完成時手動 emit event（已有 eventBus 雛形）
• events 走 eventBus.publish() → subscriber 寫 event_log（async, non-blocking）
• 失敗只 log warn，不影響 orchestrator 本身（best-effort）

12.3 AI Brain Edge Function 架構

supabase/functions/ai-brain/
├── index.ts            # 入口：接 /ai/chat 或 /ai/summarize
├── tools/              # tool library (AI 能呼叫的 orchestrator wrappers)
│   ├── query.ts        # SELECT-only queries
│   ├── action.ts       # POST orchestrator（要求 confirm token）
│   └── registry.ts     # tool 白名單 + role gating
├── context/            # 餵給 LLM 的 context builder
│   ├── recent_events.ts
│   ├── weather.ts
│   ├── holidays.ts
│   └── memory.ts       # short-term + long-term memory retrieval
└── llm/                # Anthropic SDK wrapper + prompt cache
    ├── client.ts
    └── prompts.ts

12.4 Memory Pipeline

12.5 Summarization Cron

// 每日 03:00 跑（避開營業時段）
POST /api/ai/cron/daily-summary
  ├── 拉昨日 event_log（filter importance >= 5）
  ├── 拉昨日 orders 統計
  ├── 拉天氣 + 假日
  ├── 餵 Claude Sonnet → JSON output: { highlights[], anomalies[], suggestions[] }
  ├── INSERT INTO daily_ai_summary (date, content_json)
  └── 老闆 POS 開機時 GET /api/ai/summary/today 顯示卡片

12.6 Vector DB 選型

• 用 pgvector（不要 Pinecone）— 已經在 supabase 上，省一筆 vendor
• embedding：Anthropic 還沒有 first-party embedding API，用 voyage-3-lite ($0.02/M tokens)
• summarization 頻率：每週 batch 一次，每次處理過去 7 天的 event_log，存進 ai_memory_summaries

12.7 安全 / Tool Gating

// tool registry 範例
const TOOLS = {
  query_reservations: { role: ['owner','staff'], readonly: true },
  query_orders:       { role: ['owner','staff'], readonly: true },
  send_email:         { role: ['owner'], readonly: false, max_per_day: 50, requires_confirm: true },
  create_purchase_order: { role: ['owner'], readonly: false, max_amount: 5000, requires_confirm: true },
  // ❌ never expose direct SQL / DDL
}

12.8 不該做的（避免 overengineering 清單）

• ❌ 不要寫自己的 agent framework — 直接用 Anthropic SDK + tool use
• ❌ 不要先做 voice (太多 edge cases)
• ❌ 不要先做 multi-agent / hierarchical agents
• ❌ 不要 fine-tune 模型（用 prompt + tool 就夠）
• ❌ 不要試圖讓 AI 替代 4 層架構的 orchestrator — AI 只是新的 client

12.9 Phase 2 第一個交付（demo-able）

讓老闆能驗收 Phase 2 的東西：

1. event_log 表上線 + 至少 3 種 orchestrator 在寫（cancellation / payment / settlement）
2. 每日摘要 cron 跑通，POS 開機顯示「昨日 1 件異常 + 2 個建議」
3. 沒有任何 UI 改動老闆能直接看 effect

Phase 2 通過 = 老闆說「我每天確實會看 AI 摘要」→ Phase 3 啟動。

12.10 監控 / Observability

// 必要的 metric
- ai_call_count_per_day
- ai_call_token_in / token_out (per restaurant)
- ai_call_latency_p95
- ai_tool_invocation_count by name
- ai_action_confirm_rate  (老闆按 confirm vs reject 比例 → 訊號 AI 對不對)
- daily_summary_generation_success_rate