## Context

目前 `portal.html` 透過 `iframe + frame_id + toolFrame` 在同一頁面切換多個報表。此模式雖可避免整頁跳轉，但帶來以下問題：

- 內容生命週期拆成多個 frame，除錯與事件追蹤困難
- 導覽邏輯被 iframe lazy-load、高度同步、active frame 狀態綁死
- 測試對 DOM/互動契約依賴 iframe 結構，變更成本高
- 已完成 Vite 模組化的頁面其實已可獨立路由載入，不需要 iframe 承載

此外，`drawers` 設定在目前環境已不是初始預設值，而是營運中配置（來源：`data/page_status.json`）：

- `reports`（即時報表，order=1，admin_only=false）
- `drawer-2`（歷史報表，order=2，admin_only=false）
- `drawer`（查詢工具，order=3，admin_only=false）
- `dev-tools`（開發工具，order=4，admin_only=true）

對應頁面已分散配置在上述抽屜，例如：

- 即時報表：`/wip-overview`、`/hold-overview`、`/resource`、`/qc-gate`
- 歷史報表：`/hold-history`、`/resource-history`
- 查詢工具：`/job-query`
- 開發工具：admin pages 與部分工具頁（含 `tables`、`excel-query`、`query-tool`、`tmtt-defect`、`mid-section-defect`）

因此本次改造不只是移除 iframe，而是要把「抽屜資訊架構」從「載入技術（frame）耦合」解耦到「路由與權限治理」。

## Goals / Non-Goals

**Goals:**
- 移除 portal 內容區的 iframe 依賴與 frame 管理邏輯
- 保留抽屜分組、admin 權限過濾、健康狀態檢查 UI
- 將側欄點擊行為改為同視窗路由導頁
- 維持既有 route path 與頁面業務邏輯不變
- 更新測試使其驗證新契約（link/navigation）
- 在不破壞既有 `drawers/pages` 資料模型下，支持 Router-based 導覽

**Non-Goals:**
- 不在第一階段一次重寫全部 legacy 頁面內容
- 不調整後端 API 介面或權限模型
- 不更動 page_status.json 的資料模型（僅調整 portal 消費方式）

## Decisions

### Decision 1: 抽屜保留後端治理，前端改為 Router-aware 導覽
- **選擇**: `get_navigation_config()` 仍作為抽屜與頁面來源，前端側欄只消費 route / status / admin_only，不再消費 frame_id/toolFrame。
- **理由**:
  - 保留既有營運中的抽屜設定與管理流程
  - 抽屜責任回到 IA（分類、排序、權限），避免綁定載入技術
  - 降低一次性資料遷移與管理頁調整風險
- **備選方案**:
  - 改由前端硬編抽屜：短期可行，但與管理後台脫鉤，營運成本增加

### Decision 2: 導入 SPA Shell + Vue Router，分階段替換多入口模式
- **選擇**: 建立 SPA shell 承接抽屜導覽，主要報表頁優先轉為 router view；既有可獨立頁先保持可直接訪問。
- **理由**:
  - 符合大型遷移所需的漸進路線
  - 可保留既有 URL 合約並分批改造
- **備選方案**:
  - 一次切成全 SPA：改動面過大，回歸與 rollback 風險高

### Decision 3: Legacy 頁面採先包裝、後重寫策略（已確認）
- **選擇**: `job-query`、`excel-query`、`query-tool`、`tmtt-defect` 先以 wrapper route 納入新殼層，再逐頁重寫為標準 Vue 模組。
- **理由**:
  - 先完成抽屜/導航/樣式治理，不被單頁重寫阻塞
  - 可逐步替換，控制每次上線風險
- **備選方案**:
  - 直接重寫四頁：會延後主幹遷移，且依賴資料邏輯盤點完整度

### Decision 4: Tailwind 為主樣式系統，保留過渡期雙軌
- **選擇**: 新增 Tailwind 設計 token 與元件規範，新功能優先用 Tailwind；舊頁 CSS 分批遷移。
- **理由**:
  - 先建立統一規範，避免繼續累積散落 CSS
  - 遷移節奏可與功能迭代對齊

## Risks / Trade-offs

- **[Risk] 切頁不再常駐多頁狀態，使用者感知切換較慢** → **Mitigation**: 保持頁面 bundle 切分與快取策略，後續再評估 prefetch。
- **[Risk] 既有測試仍假設 iframe DOM 結構** → **Mitigation**: 分階段更新 template/e2e/stress 斷言為 router/navigation 契約。
- **[Risk] 抽屜配置與路由表可能出現不一致** → **Mitigation**: 新增導航一致性檢查（缺失 route、權限錯置、排序衝突）。
- **[Risk] Tailwind 與既有 CSS 共存期造成樣式衝突** → **Mitigation**: 設定 migration lint 規則與 page-level ownership，限制新增散落 CSS。
- **[Risk] Legacy wrapper 週期拉長導致技術債滯留** → **Mitigation**: 在 tasks 中明確列出逐頁重寫里程碑與退出條件。

## Migration Plan

1. 定義抽屜-路由契約（來源、排序、權限、可見性）並建立檢查機制。
2. 建立 SPA shell 與 Router，先接管 portal 導覽與主要報表頁入口。
3. 移除 iframe 導覽路徑，保留舊 URL 行為與 fallback。
4. 導入 Tailwind 設計系統並建立共用元件層。
5. 將四個 legacy 頁面先包裝接入新殼層，再分批重寫。
6. 完成測試與觀測遷移（模板、E2E、壓測、性能基線）。

## Current Baseline Snapshot (2026-02-11)

### Effective drawer visibility (derived from current `drawers + pages + status + admin_only`)

- Non-admin visible routes:
  - `reports`: `/wip-overview`, `/resource`, `/qc-gate`
  - `drawer-2`: `/resource-history`
  - `drawer`: `/job-query`
- Admin visible routes:
  - `reports`: `/wip-overview`, `/hold-overview`, `/resource`, `/qc-gate`
  - `drawer-2`: `/hold-history`, `/resource-history`
  - `drawer`: `/job-query`
  - `dev-tools`: `/tables`, `/admin/pages`, `/excel-query`, `/admin/performance`, `/query-tool`, `/tmtt-defect`, `/mid-section-defect`

### Query/route contracts that must not regress

- `/wip-overview`: query filters `workorder`, `lotid`, `package`, `type`, `status`
- `/wip-detail`: query filters `workcenter`, `workorder`, `lotid`, `package`, `type`, `status`
- `/hold-detail`: required query `reason` (missing reason redirects away by current server/client guard)
- `/resource-history`: query params built from date range, granularity, groups/families/machines, production flags

## Functional Parity Matrix

| Route / Surface | Migration Mode | Must Preserve |
| --- | --- | --- |
| `/` portal shell | SPA (router host) | Drawer grouping/order/visibility, health widget, auth-linked visibility |
| `/wip-overview` | Vue route view | Filter URL sync, status filter behavior, drill-down to detail pages |
| `/wip-detail` | Vue route view | Query-param entry, pagination/filter semantics, back-link query continuity |
| `/hold-overview` | Vue route view | Hold type/reason filter behavior, treemap/matrix interaction |
| `/hold-history` | Vue route view | Date/record type filter semantics, reason pareto interactions |
| `/resource` | Vue route view | Group/status filtering and summary parity |
| `/resource-history` | Vue route view | Query validation, summary/detail/export behavior parity |
| `/qc-gate` | Vue route view | Chart↔table linked filtering and refresh behaviors |
| `/job-query` | Wrapper first | Resource/date query, transaction query, CSV export |
| `/excel-query` | Wrapper first | Upload/column detect/query/export workflow |
| `/query-tool` | Wrapper first | Resolve/history/association/equipment-period workflow |
| `/tmtt-defect` | Wrapper first | Date-range query and CSV export workflow |

## Data Contract Safety Net

- 建立「遷移前基線快照」：
  - drawer visibility snapshot（admin / non-admin）
  - route response smoke snapshot（HTTP status + critical payload keys）
  - critical page JSON schema snapshots（summary/detail/pagination key sets）
- 建立「遷移後對等檢查」：
  - key presence parity（不可缺欄位）
  - type compatibility（數值/字串/陣列型別）
  - empty-state semantics（空資料行為一致）
- 對 legacy wrapper 頁面增加 wrapper-contract 測試：
  - route reachable
  - primary query path success
  - export path reachable (where applicable)

## Go / No-Go Gates (Cutover)

- G1 Route availability:
  - P0 路由（portal + major report routes）100% 回應 2xx/3xx
- G2 Drawer parity:
  - admin/non-admin 可見路由集合與 baseline 差異為 0
- G3 Workflow parity:
  - parity matrix 中每頁核心流程至少 1 條 smoke path 通過率 100%
- G4 Client stability:
  - E2E 測試中未捕獲未處理 JS runtime error（critical path）
- G5 Data contract:
  - critical API payload key/type parity gate 全部通過
- G6 Performance:
  - route switch latency 與 baseline 比較不得惡化超過既定閾值
- G7 Rollback readiness:
  - rollback rehearsal 完成且時間達標（可在目標時間內恢復舊路徑）

## Rollback / Kill-Switch Strategy

1. 保留舊入口路徑與必要 fallback，直到全量 gate 通過。
2. 使用可配置切換（feature flag / env-based toggle）控制新 shell 導航啟用。
3. 一旦觸發回滾條件（G1/G2/G3 任一 critical fail），立即切回舊導航路徑。
4. 回滾後保留觀測資料並建立失敗歸因報告，再進行下一輪修復與 rehearsal。

## Open Questions

- `frame_id/tool_src` 欄位何時在資料模型層正式退場？
- legacy wrapper 對使用者是否顯示遷移標記（例如 beta badge）？
- 動效方案是否在第一版限定 `Vue Transition`，GSAP 延後到二階段？