## Context

「製程不良追溯分析」是 TMTT 測試站不良的回溯歸因工具。目前架構為三階段 staged pipeline（seed-resolve → lineage → events），反向追溯只取 `upstream_history` domain 做機台歸因。

已有的基礎設施：
- **EventFetcher** 已支援 `materials` domain（查 `LOTMATERIALSHISTORY`），可直接複用
- **LineageEngine** 已能追溯 split chain 到 root ancestor，`child_to_parent` map 可直接求 root
- 前端使用 **ECharts** (vue-echarts) 渲染柏拉圖，組件化完善
- 歸因邏輯 `_attribute_defects()` 是通用 pattern：`factor_value → detection_lots mapping → rate calculation`

## Goals / Non-Goals

**Goals:**
- 在反向追溯中新增原物料、源頭晶片兩個歸因維度，與現有機台歸因並列
- 提升柏拉圖的分析能力（排序切換、80% 標記線、tooltip 強化）
- 讓使用者理解歸因計算方式（分析摘要面板）
- 明細表嫌疑因子命中呈現，與柏拉圖 Top N 連動
- 嫌疑機台的維修上下文面板
- 報廢歷史查詢頁面承接產品分布分析（PACKAGE / TYPE / WORKFLOW）

**Non-Goals:**
- 正向追溯改版（後續獨立處理）
- 維修事件作為獨立歸因維度（時間交叉模型複雜，本次僅作為嫌疑機台的上下文資訊）
- Cross-filter 聯動（點圖表 bar 聯動篩選所有圖表 — 本次不做，僅做嫌疑命中）
- 站點層級歸因柏拉圖（產品每站都經過，無鑑別力）

## Decisions

### D1: 原物料歸因邏輯 — 複用 `_attribute_defects` pattern

**選擇**：新增 `_attribute_materials()` 函數，邏輯與 `_attribute_defects()` 完全對稱，只是 key 從 `(workcenter_group, equipment_name, equipment_id)` 換成 `(material_part_name, material_lot_name)`。

**替代方案**：泛化為通用 `_attribute_by_factor(records, key_fn)` 函數。
**理由**：各維度的 record 結構不同（upstream_history 有 station/equipment，materials 有 part/lot），強行泛化需要額外 adapter 層。先用對稱複製，後續若新增更多維度再考慮抽象。

### D2: 原物料資料取得 — EventFetcher materials domain

**選擇**：在 staged trace events 階段新增請求 `materials` domain。前端的 `useTraceProgress.js` 在 backward 模式時改為 `domains: ['upstream_history', 'materials']`。

**替代方案**：另開一個獨立 API 查原物料。
**理由**：EventFetcher 已有完善的 materials domain（batch、cache、rate limit），staged trace pipeline 已能處理多 domain 並行查詢，無需重複建設。

### D3: 源頭晶片歸因 — 從 lineage ancestors 提取 root

**選擇**：在 lineage stage 的 response 中新增 `roots` 欄位（`{seed_cid: root_container_name}`），不需要額外 SQL 查詢。LineageEngine 已有 `child_to_parent` map，遍歷到無 parent 的節點即為 root。後端 `_attribute_wafer_roots()` 以 `root_container_name` 為 key 做歸因。

**替代方案**：用 SQL CONNECT BY 直接查 root。
**理由**：lineage stage 已經完整追溯了 split chain，root 資訊是副產品，不需要額外 DB roundtrip。

### D4: 柏拉圖排列 — 替換 PACKAGE/TYPE/WORKFLOW

**選擇**：6 張柏拉圖改為：

| 位置 | 原本 | 改為 |
|------|------|------|
| 左上 | 依上游機台歸因 | 依上游機台歸因（保留） |
| 右上 | 依不良原因 | 依原物料歸因（新） |
| 左中 | 依偵測機台 | 依源頭晶片歸因（新） |
| 右中 | 依 WORKFLOW | 依不良原因（保留） |
| 左下 | 依 PACKAGE | 依偵測機台（保留） |
| 右下 | 依 TYPE | 移除 |

改為 5 張（2-2-1 排列），最後一行只有偵測機台。或視空間調整為 3-2 或 2-2-2。

**理由**：PACKAGE / TYPE / WORKFLOW 是「不良分布在哪些產品上」的分析，屬於報廢歷史查詢的範疇。製程不良追溯的核心問題是「不良來自哪個上游因子」。

### D5: 明細表結構化上游資料

**選擇**：後端 `_build_detail_table` 的 `UPSTREAM_MACHINES` 欄位改為回傳 list of `{station, machine}` 對象。同時新增 `UPSTREAM_MATERIALS` (list of `{part, lot}`) 和 `UPSTREAM_WAFER_ROOT` (string) 欄位。CSV export 時 flatten 回逗號字串。

前端明細表不顯示全部上游機台，改為只顯示「嫌疑因子命中」：根據當前柏拉圖（含 inline filter）的 Top N 嫌疑名單，與該 LOT 的上游因子做交叉比對。

### D6: 嫌疑機台上下文面板 — Popover 或 Side Drawer

**選擇**：使用 Popover（點擊柏拉圖 bar 時彈出），內容包含：
- 歸因數據：不良率、LOT 數、投入/報廢
- 設備資訊：站點、機型 (RESOURCEFAMILYNAME)
- 近期維修：呼叫 `GET /api/query-tool/lot-associations?type=jobs&container_id=<equipment_id>` 取近期 JOB 紀錄（需要以 equipment_id 查詢的 endpoint，可能需要新增或複用 equipment-period jobs）

**替代方案**：Side drawer 或 modal。
**理由**：Popover 輕量、不離開當前分析上下文。維修資料只需 3-5 筆近期紀錄，不需要完整的 JOB 列表。

### D7: 報廢歷史查詢頁面新增 Pareto 維度

**選擇**：在現有 ParetoSection.vue 新增維度下拉選擇器。後端 `reject_history_service.py` 的 reason Pareto 邏輯改為可指定 `dimension` 參數（`reason` / `package` / `type` / `workflow` / `workcenter` / `equipment`）。

## Risks / Trade-offs

### R1: 原物料資料量
原物料紀錄可能比 upstream_history 多很多（一個 LOT 可能消耗多種材料）。2000 個 LOT + 血緣的原物料查詢可能返回大量資料。
→ **Mitigation**: EventFetcher 已有 batch + cache 機制。若資料量過大，可限制原物料歸因只取前幾種 material_part_name（如前 20 種），其餘歸為「其他」。

### R2: LineageEngine root 不一定是晶圓
Split chain 的 root 可能不總是代表「晶圓批次」，取決於產品結構。某些產品線的 root 可能是其他中間製程的 LOT。
→ **Mitigation**: 以 `root_container_name` 顯示，不硬標籤為「晶圓」。UI label 用「源頭批次」而非「晶圓」。

### R3: Staged trace events 增加 domain 的延遲
新增 materials domain 會增加 events stage 的執行時間。
→ **Mitigation**: EventFetcher 已支援 concurrent domain 查詢（ThreadPoolExecutor），materials 和 upstream_history 可並行。Cache TTL 300s 也能有效減輕重複查詢。

### R4: 嫌疑機台維修資料可能需要新的 API
目前 query-tool 的 jobs API 是以 container_id 或 equipment + time_range 查詢，沒有「某台設備的近期 N 筆維修」的 endpoint。
→ **Mitigation**: 新增一個輕量的 equipment-recent-jobs endpoint，或在前端直接用 equipment-period jobs API 查近 30 天即可。

### R5: 報廢歷史查詢的 Pareto 維度切換需要後端支援
目前 Pareto 只支援按 reason 聚合，新增其他維度需要後端 SQL 重寫。
→ **Mitigation**: 報廢歷史查詢使用 two-phase caching pattern（完整 DataFrame 已快取），在 view refresh 階段做不同維度的 groupby 即可，不需重新查 DB。