AI 智慧報告系統 — 完整 Spec

先看這裡 — TL;DR

┌─────────────────────────────────────────────────────────────────┐
│  Layer 4 — UI (Widget Renderer)                                  │
│   - 對話介面 + 預設問題 chip + 動態 widget canvas                │
│   - 每個 widget 來自固定 library,不讓 AI 自由畫                  │
│   - NotebookLM-style「資料來源 panel」可展開                     │
└──────────────────────▲──────────────────────────────────────────┘
                       │ Report Manifest (JSON)
┌──────────────────────┴──────────────────────────────────────────┐
│  Layer 3 — Manifest Generator (AI agent)                         │
│   - Claude / OpenAI 收老闆問題 → 寫 Report Manifest              │
│   - 規範化 schema 約束 LLM 只能輸出合法 Widget IDs               │
│   - 包含 trust_score / data_sources / explanations               │
└──────────────────────▲──────────────────────────────────────────┘
                       │ Tool calls (whitelist functions)
┌──────────────────────┴──────────────────────────────────────────┐
│  Layer 2 — AI Query Orchestrator                                 │
│   - Intent classification(revenue/forecast/comparison/...)      │
│   - Tool selection + parameter validation                        │
│   - Cold start fallback(no data → industry defaults)            │
│   - Trust score 計算(data_volume × algorithm_grade)             │
└──────────────────────▲──────────────────────────────────────────┘
                       │ Named tool functions (schema enforced)
┌──────────────────────┴──────────────────────────────────────────┐
│  Layer 1 — Data Mart Tools(AI 不直接 SQL)                      │
│   - 既有 report-analytics 7 演算法 wrap 成 tool function         │
│   - 新加:weather、holiday、年同期對比、客人 segment、菜單熱賣  │
│   - Materialized views for hot questions                          │
│   - 每個 tool 有明確 input/output schema,RLS 嚴格 gate           │
└──────────────────────▲──────────────────────────────────────────┘
                       │ SQL / RPC
                  ┌────┴─────┐
                  │ Supabase │
                  └──────────┘

原則: AI 永遠不能下 raw SQL。所有資料 access 走「白名單 named tool function」,每個 tool 有明確 input schema + output schema。違反 schema = orchestrator 直接拒絕。

Tool Categories(初版規劃)

Tool function 規範(範例)

// tools/get_revenue_summary.ts
export const TOOL_SPEC = {
  name: 'get_revenue_summary',
  description: '取得指定期間總營收 / 客單價 / 來客數',
  parameters: {
    period: { type: 'string', enum: ['today', 'yesterday', 'this_week',
      'last_week', 'this_month', 'last_month', 'custom'] },
    custom_start: { type: 'string', format: 'date', required: false },
    custom_end:   { type: 'string', format: 'date', required: false },
    granularity:  { type: 'string', enum: ['day', 'week', 'month'] },
  },
  output: {
    type: 'object',
    properties: {
      total_revenue:    { type: 'number' },
      guest_count:      { type: 'number' },
      avg_per_guest:    { type: 'number' },
      discount_rate:    { type: 'number' },
      data_points:      { type: 'integer', description: '實際有資料的天數' },
      data_completeness:{ type: 'number',  description: '0-1,期間內有資料天數比' },
    },
  },
}

export async function execute(params, ctx) {
  // 1. 驗證 restaurant_id 屬於 ctx.user
  // 2. 從 materialized view 撈
  // 3. 回 schema-compliant object
}

意圖分類(Intent Classification)

老闆問題進來,先 LLM 做 lightweight 分類(便宜模型,例 Haiku):

Tool 選擇 + 參數推導

分類完後,Claude(較強模型)做 multi-tool call:

冷啟動 fallback 規則

關鍵:AI 回的不是 HTML,不是自由 markdown。是嚴格 JSON schema 的 Manifest,UI 才有辦法限制 AI 不亂畫。

Manifest 結構

{
  "version": "1.0",
  "question": "明天天氣會不會影響訂位?",
  "intent": "impact_analysis",
  "trust": {
    "tier": "silver",      // bronze / silver / gold
    "score": 72,           // 0-100
    "reason": "過去 90 天歷史 (data_completeness=0.95) + Pearson r=0.61"
  },
  "summary_md": "**明天降雨機率 70%,根據過去 3 個月資料,雨天訂位平均減少 23%。** 建議:備料量可以調降 10-15%,排班可以少 1 個外場。",
  "sources": [
    { "tool": "get_weather_forecast",  "params": {"date": "2026-05-19"} },
    { "tool": "compute_correlation",   "params": {"metric": "guest_count", "factor": "weather"} },
    { "tool": "get_guest_volume",      "params": {"period": "90d", "dimensions": ["weather_class"]} }
  ],
  "widgets": [
    {
      "id": "w1",
      "type": "KPICard",
      "props": {
        "title": "明天預測來客數",
        "value": "32-38 人",
        "delta": "-25%",
        "delta_label": "vs 一般週六",
        "trust_badge": "silver"
      }
    },
    {
      "id": "w2",
      "type": "InsightCallout",
      "props": {
        "icon": "weather-rain",
        "title": "預估影響",
        "body_md": "降雨機率 70% + 過去雨天平均訂位下降 23%(p<0.01,顯著)。",
        "actions": [
          { "label": "看歷史雨天紀錄", "open_source": "w4" }
        ]
      }
    },
    {
      "id": "w3",
      "type": "BarComparison",
      "props": {
        "title": "雨天 vs 晴天 訂位數對比",
        "series": [
          { "name": "晴天平均", "value": 42 },
          { "name": "雨天平均", "value": 32 }
        ],
        "footnote": "資料區間:2026-02-18 ~ 2026-05-18 (90 天)"
      }
    },
    {
      "id": "w4",
      "type": "DataTableWithFootnote",
      "collapsed": true,        // 預設摺疊,點開才展開
      "props": {
        "headers": ["日期", "天氣", "訂位數", "實到"],
        "rows": [/* ... */],
        "footnote": "來源:reservations + 中央氣象局 CWA API"
      }
    }
  ],
  "dimension_selectors": [        // 老闆可切換 UI 的維度
    {
      "id": "weather-dim",
      "label": "影響因子",
      "options": [
        { "value": "weather",  "label": "天氣",     "active": true },
        { "value": "holiday",  "label": "節假日" },
        { "value": "weekday",  "label": "星期幾" },
        { "value": "combined", "label": "綜合分析" }
      ]
    }
  ],
  "followup_prompts": [
    "那如果是連假?",
    "去年同期(5/19)賣多少?",
    "雨天最賣的菜是?"
  ]
}

原則:參考麥肯錫 / BCG / 一般 BI tool(Looker, Mode, Metabase)常用的報告元件,自製 ChefsMate Stitch 風格版。AI 只能挑這些,不能自繪。

初版 Widget 清單(12 個)

每個 widget 的通用 props

NotebookLM-style source panel

計算公式:

trust_score =
    data_volume_score    × 0.50     # 你有多少歷史資料?
  + algorithm_grade      × 0.30     # 用什麼演算法計算?
  + statistical_quality  × 0.20     # p-value / R² / 異常率

data_volume_score

algorithm_grade

tier 對應

Cold start 技巧

1. Industry defaults JSON:把餐飲業常見 KPI(食材 30%、人事 25%、利潤 10%、客單 NT$280)寫成可 hot-update 的 config(老闆可改)。
2. Seed 老闆設定:onboarding 問「你的店是什麼類型?(輕食 / 中餐 / 異國 / 居酒屋)」,根據類型套不同 default。
3. 邊用邊累積:每張單 / 每次關帳都餵進 Data Mart materialized view,信任分隨時間自動升級。
4. 透明告知:每個冷啟動的洞察都明標「行業基準 / 你的歷史」,不藏。

End-to-end flow(7 步)

老闆看到的畫面(概念)

關鍵風險 + 緩解

1. LLM 用哪家?
   • Claude(Anthropic)— tool-use 最強,文字解釋自然,費用中等
   • OpenAI GPT-4o-mini + GPT-4o
   • Google Gemini
   • 建議:Claude Haiku(分類)+ Sonnet(manifest 生成),理由是已有 token、Tool use schema 最穩
2. 戰情室擺哪?
   • POS 既有戰情室 tab(Phase 4 已有 ReportAPIClient,容易擴)
   • 客人端 web 老闆專屬頁面(更新即時但要重做 auth)
   • 建議:POS 戰情室 tab
3. 第一波支持哪 5 類問題?(MVP 範圍)
   • 建議:revenue_lookup / forecast / compare_period / impact_analysis / top_items
   • 另一選項:top_items 換 customer_insight
4. 冷啟動 industry default 來源:
   • 我手寫一份(基於餐飲業常識,可後續優化)
   • 找台灣餐飲協會 / 經濟部公開資料(較費時)
   • 建議:手寫 v1,後續更新
5. 「老闆切換維度」UX:
   • 切換 chip → 同畫面重打 API 拿新 Manifest(精準但慢)
   • 切換 chip → 客戶端 instant filter(快但 widget 要 pre-compute 所有維度)
   • 建議:預設 reply 多帶 1-2 個常見維度,切換瞬間切;冷門維度才打 API
6. NotebookLM 啟發要做多深?
   • 淺:每個 widget 有 source panel 可展開
   • 中:加 pin、分享、followup chip(完整 Phase 3)
   • 深:Audio overview(Phase 4 後續)
   • 建議:Phase 3 做到中,深的看後續