最後五天開始把兩個技能合成一個前後端專案。

在最後的五天實戰衝刺中（Day 26 ～ Day 30），我們將把前 25 天學習到的所有零件，融合成一個真正能端到端運行的生產級專案：
使用者在前端輸入一句自然語言（例如：「列出高價值客戶並評估近期退費風險」），後端 Embabel Agent 立即分析意圖、調用 Java 查詢 CRM 真實資料庫、組裝出強型別的 DashboardSpec，並透過 SSE 串流管線即時推播，最後由前端 json-render 漸進渲染出高互動性的動態儀表板。

但在敲下任何一行 Java 或 TypeScript 代碼之前，我們必須先做一件最關鍵、但也最容易被忽視的事：「定義 MVP 邊界與前後端 Spec 契約」。

很多 AI 專案之所以爛尾，原因往往不是技術不夠好，而是一開始就讓 AI 自由發揮寫 Code，導致後端隨意吐 JSON、前端到處修補未定義的元件，最終前後端對不上。今天作為整合專案的第 0 天，我們的原則是：「今天刻意不寫任何業務程式碼，先把邊界與契約徹底釘死！」

1. 今天要解決的痛點與核心觀念

痛點背景：AI 全端專案開發的三大典型翻車現場

1. 範圍蔓延（Scope Creep）：向 AI 說「幫我做個旅遊儀表板」，AI 一口氣列出 20 個功能、15 張圖表、3 種會員系統，結果五天做不完直接棄坑。
2. 契約偷跑（Contract Drift）：後端 Agent 先寫好了，自創了一套巢狀 JSON；前端工程師看到後崩潰，因為 json-render 根本吃不下深層巢狀結構。
3. 資料與敘事混淆：沒有事先區分哪些欄位是「真資料（Java）」、哪些是「分析文案（LLM）」，導致後端 Action 在組裝時手忙腳亂。

觀念圖解：專案五天整合里程碑與架構藍圖

┌────────────────────────────────────────────────────────────────────────┐
│                        最後五天實戰推進時間線                          │
├──────────────┬──────────────┬──────────────┬──────────────┬────────────┤
│ Day 26 (今天)│ Day 27       │ Day 28       │ Day 29       │ Day 30     │
│ MVP 邊界收斂 │ 後端 GOAP    │ SSE 串流     │ 前端 React   │ 端到端驗收 │
│ & 契約定義   │ Action 實作  │ 事件管線     │ 漸進渲染     │ & 生產就緒 │
└──────────────┴──────────────┴──────────────┴──────────────┴────────────┘

1. 前端互動層 (Vite + React 18 + Tailwind + @json-render/react)：包含自然語言輸入框、useDashboardStream 客戶端、思維鏈進度面板與 FlatTreeRenderer。
2. 傳輸層 (HTTP POST & SSE)：承載查詢請求與伺服器即時推播事件。
3. 後端治理與規劃層 (Spring Boot 3.3 + Java 21 + Spring AI + Embabel GOAP)：包含 DashboardStreamController、SseProgressBroker 與 A* GOAP 規劃器（意圖分析 $\rightarrow$ CRM 資料庫 $\rightarrow$ LLM 洞察 $\rightarrow$ 確定性組裝）。

2. 官方核心技術依據與架構深度

為了確保五天內能高品質完成專案，我們必須嚴格落實 「MVP 3/5/3/1 原則」：

1. 「3 / 5 / 3 / 1」邊界約束法則

• 3 個精確的自然語言查詢場景：
  1. 場景 A（單一客戶總覽）：「查詢客戶 1001 的年度消費總結與旅遊偏好」
  2. 場景 B（高價值常客洞察）：「列出年度消費超過 10 萬的高價值常客並標註忠誠度」
  3. 場景 C（客訴預警與方案）：「分析有爭議投訴的客戶並產出專屬安撫方案」
• 5 種受控前端 UI 元件（Catalog）：
  Stack（排版容器）、Heading（標題）、MetricCard（指標卡）、AlertBanner（預警橫幅）、DataTable（數據表格）。
• 3 種強型別後端領域物件（Domain Records）：
  CustomerQuery、TravellerActivity、DashboardSpec。
• 1 條穩健的 SSE 串流成功管線：
  status $\rightarrow$ plan $\rightarrow$ step $\rightarrow$ chunk $\rightarrow$ complete。

2. 「Prompt 驅動」開發心法（Prompt-Driven Development）

在現代 AI 輔助開發中，技能（Skills）是執行器，提示詞（Prompts）是指揮棒。
當你需求還沒想清楚時，千萬不要過早觸發程式碼生成技能；必須先將 AI 當作產品顧問，逼它做減法，等規格被框定在不可踰越的邊界內後，才正式啟動編碼。

3. 完整程式碼與提示詞實戰（Production-Ready Prompts & Spec）

以下提供今天必須執行的兩組「黃金提示詞」，以及由其產出的精確前後端契約規格書。

1. 提示詞 A：收斂 MVP 範圍（逼 AI 做減法）

我要做一個「自然語言輸入 -> Embabel 後端 Agent -> JSON UI Spec -> 前端 json-render 漸進渲染」的完整前後端專案。
請先擔任我的資深軟體架構顧問，現在嚴禁輸出任何 Java 或 React 程式碼。

請幫我把需求嚴格收斂在「五天內能 100% 開發並驗收完畢」的最小可行性產品（MVP），並遵守以下上限：
1. 剛好 3 個具代表性的自然語言查詢情境（涵蓋單一查詢、列表統計、異常預警）。
2. 剛好 5 種受控前端元件（不許自創額外複雜圖表）。
3. 剛好 3 種後端領域 Record 資料物件。
4. 剛好 1 條標準 SSE 串流流程。

請輸出這份 MVP 定義表，並明確列出「這次我們刻意不做（Out of Scope）」的項目清單。

2. 提示詞 B：釘死前後端共用的 Spec 契約

規格確定後，請幫我定義前後端共用的 UI Spec 資料契約（這是後端 Agent 的輸出，也是前端 json-render 的輸入）：

規範要求：
1. 頂層必須是 Flat Tree 格式：{ root: string, elements: Record<string, ElementSpec> }。
2. children 必須是 key 的字串陣列（string[]），嚴禁使用巢狀 JSX 結構。
3. 針對 3 個查詢場景，逐一列出會用到的 5 種元件型別（Stack, Heading, MetricCard, AlertBanner, DataTable）與 props 屬性。
4. 關鍵要求：每個 prop 都必須標註它是「確定性資料 (由 Java 填寫)」還是「敘事文字 (由 LLM 生成)」。

請只輸出這份契約表格與 TypeScript / Java 定義，不要寫任何業務邏輯實作。

3. 產出的前後端共用契約規格書（Contract Specification）

// 前後端共用：屬性權責劃分矩陣表
export interface ElementContract {
  Stack: {
    direction: "horizontal" | "vertical"; // [Java 確定性指定]
    gap: number;                          // [Java 確定性指定]
  };
  Heading: {
    text: string;                         // [LLM 創意生成] (如: "陳大文先生的年度旅遊總結")
    level: "h1" | "h2" | "h3";            // [Java 確定性指定]
  };
  AlertBanner: {
    severity: "info" | "warning" | "error" | "success"; // [LLM / 規則判定]
    message: string;                      // [LLM 創意解讀] (如: "近三個月取消率偏高，建議提供優惠")
  };
  MetricCard: {
    title: string;                        // [Java 確定性指定] (如: "近一年總消費")
    value: string | number;               // [Java 確定性計算] (如: "NT$ 143,000")
    trend?: "up" | "down" | "neutral";    // [Java 規則計算]
    change?: string;                      // [Java 規則計算] (如: "+18%")
  };
  DataTable: {
    columns: Array<{ key: string; label: string }>; // [Java 確定性定義]
    rows: Array<Record<string, any>>;              // [Java 確定性直連 DB] (嚴禁 LLM 轉抄！)
  };
}

4. 生產環境避坑指南與對比分析

常見踩雷與除錯秘訣

1. 雷區一：在第 26 天就急著寫 Controller 和 Action
   • 後果：寫到第 28 天發現前端 SSE 接不上某個資料型態，回過頭來重構後端所有的 Record，白白浪費兩天。
   • 解法：第一天務必嚴格執行「零業務代碼」，只產出合約介面與 Markdown 規格書。
2. 雷區二：沒有將「刻意不做（Out of Scope）」白紙黑字寫下來
   • 後果：開發到一半突然想加「使用者權限認證」、「多國語系切換」、「即時 PDF 匯出」，導致核心功能遲遲無法交付。
   • 解法：明確宣告本次 Out of Scope：無登入系統、無圖表自定義拖拉、無歷史紀錄搜尋。
3. 雷區三：允許 LLM 自由發揮非標準 JSON 鍵值
   • 後果：LLM 輸出 columns_list 而不是 columns，前端元件無法渲染。
   • 解法：透過 Zod Schema 與 Java Record 進行雙向約束。

專案規劃模式對比表

5. 實機畫面：收斂後的 MVP 入口

下圖是實作系統的首頁：一個自然語言輸入框、按場景分組的建議查詢（專職分析、動態篩選、清單排行、複合融合等，對應各專職 Agent），以及右側待命的 Embabel Agent 執行面板。所有查詢都被收斂在這些預先定義的場景邊界內——這就是「先決定要看什麼」落地後的樣子。

6. 今日動手實作任務與發文備註

🛠️ 今日實作任務

1. 建立專案結構：建立前後端分離的專案目錄（後端 server/，前端 client/）。
2. 存檔契約規格：將上述的 DashboardSpec 與 ElementContract 定義分別儲存為 Java 與 TypeScript 的型別檔案。
3. 思考題：為什麼在規劃階段將「表格資料列 rows」標記為「Java 確定性填寫」是整套 Generative UI 專案成功的最高關鍵？