DashBoard/openspec/changes/query-tool-lineage-model-alignment/design.md

Context

「批次追蹤工具」目前已拆成三個頁籤（正向/反向/設備），但 lineage 核心仍以 SPLITFROMID 與 DW_MES_PJ_COMBINEDASSYLOTS 為主，資料語意不足以完整表達現場流程：

• GC 並非 GA 的必經節點，且非 1:1；部分批次只有 GC 抽點，部分完全不經 GC。
• Wafer LOT（DW_MES_CONTAINER.FIRSTNAME）是 GA/GC 共同上游錨點，應獨立建模。
• GD 重工追溯主鏈在 DW_MES_CONTAINER：ORIGINALCONTAINERID + FIRSTNAME + SPLITFROMID，僅靠 COMBINED 表無法表達完整重工來源。

已驗證資料特徵（實查）：

• GD lot 可由 DW_MES_PJ_COMBINEDASSYLOTS.FINISHEDNAME 反解至 GDxxxx-Axx。
• 該 GD lot 在 DW_MES_CONTAINER 中可取得 MFGORDERNAME=GD... 與 ORIGINALCONTAINERID、FIRSTNAME。
• ORIGINALCONTAINERID 對應來源 lot 可回接 Wafer LOT（FIRSTNAME）。

約束條件：

• 需沿用現有 /api/query-tool/*、/api/trace/* 路由，不做破壞式移除。
• 需保留 staged trace 的快取與 rate limit 行為。
• 需維持查詢效能，避免以 Wafer LOT 為起點時產生不可控 fan-out。

Goals / Non-Goals

Goals:

• 以「語意化節點/邊」重建 query-tool 的追溯模型，明確區分 split、merge、wafer-origin、gd-rework。
• 明確支持兩種入口集合：
  • 正向：Wafer LOT / GA-GC 工單 / GA-GC LOT
  • 反向：成品流水號 / GD 工單 / GD LOT ID
• 前端樹圖可視化要能辨識「GA 無 GC」與「GD 重工分支」。
• 將 GD 追溯落在 lot/workorder 層級保證可追，並保留 serial 層級可得資訊。

Non-Goals:

• 不承諾舊成品流水號與新成品流水號 1:1 映射。
• 不調整設備頁籤功能。
• 不在本變更導入新資料來源（僅使用既有 DWH 表）。

Decisions

D1. 建立 Typed Lineage Graph（節點/邊雙語意）

後端 lineage 輸出新增語意欄位，與現有欄位並存（過渡期兼容）：

• nodes: 依 container_id 聚合節點屬性（node_type, container_name, mfgorder_name, wafer_lot）
• edges: 邊列表（from_cid, to_cid, edge_type）
• edge_type 固定枚舉：
  • split_from
  • merge_source
  • wafer_origin
  • gd_rework_source

node_type 判定優先順序：

1. MFGORDERNAME LIKE 'GD%' 或 CONTAINERNAME LIKE 'GD%' → GD
2. MFGORDERNAME LIKE 'GC%' 或 CONTAINERNAME LIKE 'GC%' → GC
3. MFGORDERNAME LIKE 'GA%' 或 CONTAINERNAME LIKE 'GA%' → GA
4. OBJECTTYPE='LOT' 且為 Wafer 錨點節點 → WAFER
5. COMBINED FINISHEDNAME 的虛擬節點 → SERIAL

保留現有 children_map / parent_map 等欄位，前端逐步切換到 typed graph。

D2. 以 Profile 區分 seed-resolve 輸入語意

/api/trace/seed-resolve 改為 profile-aware 的 resolve type 規則：

• query_tool（正向）允許：wafer_lot, lot_id, work_order
• query_tool_reverse（反向）允許：serial_number, gd_work_order, gd_lot_id

其中：

• wafer_lot: 以 DW_MES_CONTAINER.FIRSTNAME 解析種子 lot 集合
• gd_work_order: 僅允許 GD% 前綴，對 DW_MES_CONTAINER.MFGORDERNAME 解析
• gd_lot_id: 以 DW_MES_CONTAINER.CONTAINERNAME 解析，且需同時符合 GD 規則（CONTAINERNAME LIKE 'GD%' 或 MFGORDERNAME LIKE 'GD%'）
• work_order（正向）限定 GA/GC（非 GD）

此設計避免正反向模式語意混用，且可在 API 層即早回饋錯誤。

D3. GD 反向追溯採「Container 主鏈 + Combined 輔鏈」

GD 反向演算法（三種起點共用）：

1. 種子為 serial 時，先由 DW_MES_PJ_COMBINEDASSYLOTS.FINISHEDNAME 找到 lot（常為 GDxxxx-Axx）；種子為 gd_lot_id 時直接命中該 lot；種子為 gd_work_order 時直接展開該工單 lot 群。
2. 對 serial 或 gd_lot_id 起點，讀取 lot 的 MFGORDERNAME 以展開同 GD 工單 lot 群。
3. 對每個 GD lot 取來源：
   • 主來源：ORIGINALCONTAINERID
   • 回退來源：SPLITFROMID（當 ORIGINAL 為空或無效）
4. 來源 lot 再透過 FIRSTNAME 接回 Wafer LOT 錨點。
5. COMBINED 僅負責「lot -> 成品流水號」映射，不作為 GD 來源主依據。

這可涵蓋「成品流水號 -> GD -> 來源 lot -> wafer」與「GD 工單 -> lot 群 -> 來源 lot」兩條路徑。

D4. 前端改為語意化樹圖且保持明細過濾邊界

LineageTreeChart 調整為語意視覺：

• 節點顏色/形狀區分 WAFER/GC/GA/GD/SERIAL
• 邊樣式區分 split/merge/wafer-origin/gd-rework
• 無 GC 時強制顯示 WAFER -> GA 直接鏈路，不用「缺失」呈現

互動邊界：

• 點擊節點僅更新 detail panel 的 container scope
• 不重新過濾/改寫樹本身（避免「點樹即變樹」）

D5. 效能策略：分段查詢 + 批次 + 快取

• lineage 查詢維持分段與批次（IN clause batching）策略。
• Wafer LOT 展開加入結果上限與分頁/裁切策略（避免單一查詢過大）。
• GD 關係查詢以 Redis/L2 做短期快取（可由 env 配置 TTL）。
• 監控新增 typed-edge 命中統計，觀察 wafer_origin 與 gd_rework_source 的覆蓋率。

D6. 向後相容與漸進切換

• API contract 採「新增欄位」方式，不先移除舊欄位。
• 前端先讀新欄位，保留舊欄位 fallback 一個版本週期。
• 若生產異常，可切回舊渲染路徑（feature flag 或 runtime config）。

Risks / Trade-offs

• [Risk] Wafer LOT fan-out 過大導致查詢壓力
  Mitigation: 設定種子展開上限、分段查詢、UI 提示「僅顯示前 N 筆」。

• [Risk] FIRSTNAME 同名造成跨流程誤連
  Mitigation: 邊生成時加上 OBJECTTYPE='LOT' 與工單/時間窗交叉約束；疑似多義連線以低信任度標記。

• [Risk] GD 舊/新 serial 無法 1:1 對映引發期待落差
  Mitigation: 在規格與 UI 說明明確宣告 serial 層級的限制，保證 lot/workorder 層級完整可追。

• [Risk] 新舊欄位並存造成前後端邏輯複雜
  Mitigation: 設定移除時程，待新前端穩定後再移除舊欄位讀取。

Migration Plan

1. 後端先落地 typed lineage（不改前端），確認 API 回傳兼容。
2. 前端切換至 typed graph 視覺與新 resolve 類型。
3. 啟用 GD reverse 路徑與 GC-optional 顯示規則。
4. 以實例資料驗證三種主流程：
   • WAFER -> GA（無 GC）
   • WAFER -> GC -> GA
   • SERIAL -> GD -> SOURCE LOT -> WAFER
5. 穩定後移除舊渲染相依欄位（若決議移除）。

Rollback：

• 關閉 typed graph 功能開關，前端退回舊欄位渲染。
• 保留新 SQL/欄位但不被前端使用，避免熱修回滾需 DB 變更。

Open Questions

• Wafer LOT 輸入值格式是否需要強制前綴或正則，以降低同名誤連？
• 正向 work_order 是否嚴格限制 GA/GC，或允許 GD 但提示「請用反向頁籤」？
• WAFER -> GA 直接鏈路在視覺上要以虛線還是實線呈現（避免與 split 混淆）？