fix(query-tool): batch detail loading, UX polish, and docs cleanup

- Fix multi-WO display: auto-select all tree roots after resolve so detail panel loads data for every work order, not just the first seed CID - Disable scroll-wheel zoom on lineage tree (roam: 'move') to prevent accidental layout jumps while preserving drag-pan - Add batch API endpoints (get_lot_history_batch, get_lot_associations_batch) to avoid N parallel requests hitting rate limits - Remove redundant Split sub-tab from LOT detail (tree already shows splits) - Rename 退貨 → 報廢 to match actual reject/scrap data semantics - Hide internal ID columns (CONTAINERID, EQUIPMENTID, RESOURCEID) from history table display - Add timeline scroll container and time range header for long timelines - Remove obsolete migration and architecture docs no longer needed Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-13 17:42:11 +08:00
parent 5b358d71c1
commit 248cbc25e0
119 changed files with 842 additions and 9085 deletions
--- a/openspec/changes/reject-history-query-page/design.md
+++ b/openspec/changes/reject-history-query-page/design.md
@@ -0,0 +1,123 @@
+## Context
+
+目前 `query-tool` 僅提供單點查詢 reject 資訊，沒有針對歷史趨勢、原因分布與績效指標的完整頁面。`DW_MES_LOTREJECTHISTORY` 存在同一 `HISTORYMAINLINEID` 對應多筆原因紀錄的特性，直接彙總 `MOVEINQTY` 會造成分母膨脹，讓報廢率失真。另一方面，現有語意中「reject 五欄合計」與 `DEFECTQTY` 曾被混用，導致跨頁面解讀不一致。
+
+此變更需要跨越前端（新報表頁）、後端（新 API + service + SQL）、與治理層（route contract、drawer/page registry、coverage test），屬於跨模組整合型設計。
+
+## Goals / Non-Goals
+
+**Goals:**
+- 建立 `/reject-history` 專用報表頁，提供篩選、KPI、趨勢、Pareto、明細與匯出。
+- 固化兩條指標語義並列：
+  - 扣帳報廢 `REJECT_TOTAL_QTY`
+  - 不扣帳報廢 `DEFECT_QTY`
+- 以事件層級去重 `MOVEIN_QTY`，避免因 `HISTORYMAINLINEID` 多筆造成比率失真。
+- 完整納入現有 pure Vite + portal-shell + route contract 治理流程。
+- 在視覺上清楚區分 reject 與 defect，避免操作端誤判。
+
+**Non-Goals:**
+- 不改寫既有 `query-tool` 與其 API 欄位契約。
+- 不新增第三方套件（沿用 Vue 3、ECharts、Flask、SQLLoader）。
+- 不在此變更內建立新的資料倉儲實體表（先以查詢層與 service 聚合實作）。
+- 不重構非 reject-history 相關頁面的 UI 風格。
+
+## Decisions
+
+### D1: 以單一「日粒度基底查詢」作為 API 共同資料來源
+
+**Decision:** 以 `src/mes_dashboard/sql/reject_history/performance_daily.sql` 作為基底查詢，summary/trend/pareto/list/export 都由 service 在同一語義上二次聚合。
+
+**Why:**
+- 可避免各 endpoint 重複實作計算邏輯造成語意漂移。
+- 已在 SQL 中明確定義五欄合計與 `DEFECTQTY` 分離，符合業務規則。
+- 可先解決語義一致性，再視流量評估是否做 materialization。
+
+**Alternatives considered:**
+- 各 API 各自寫 SQL：開發快但長期高風險，易出現欄位定義不一致。
+- 先建資料表再查詢：效能可控但前置成本高，超出本次提案節奏。
+
+### D2: `MOVEIN_QTY` 以事件去重策略統一計算
+
+**Decision:** 以 `HISTORYMAINLINEID` 為首選去重鍵；若缺值，退回 `CONTAINERID + TXNDATE(second) + SPECID` 組合鍵；只對事件首筆計入 `MOVEIN_QTY`。
+
+**Why:**
+- 原始資料存在一對多原因拆分，若不去重分母會被重複計算。
+- 去重規則集中在基底 SQL，前後端不用再各自補丁。
+
+**Alternatives considered:**
+- 以 `CONTAINERID` 去重：會誤合併同 lot 不同事件。
+- 不去重：報表比率不可用。
+
+### D3: API 採「頁面導向」端點設計
+
+**Decision:** 提供 `summary`、`trend`、`reason-pareto`、`list`、`export` 五個端點，參數模型一致（日期 + 維度過濾），由 route 層統一做驗證與邊界控制。
+
+**Why:**
+- 前端可平行載入、獨立重刷局部區塊。
+- 可針對高成本端點（list/export）單獨做 rate limit。
+- 與 `hold-history`/`resource-history` 現有模式一致。
+
+### D4: 前端視覺採「雙軸語義敘事」布局
+
+**Decision:** 在單頁內明確分離「扣帳報廢」與「不扣帳報廢」兩條視覺敘事線，避免混讀。
+
+**Visual structure:**
+- Header：漸層標題區，顯示頁名、資料更新時間、語義說明 badge（扣帳/不扣帳）。
+- Filter Card：日期區間 + 維度篩選（站群/站點/產品線/原因），含查詢與清除。
+- KPI Row（8 卡）：`MOVEIN_QTY`、`REJECT_TOTAL_QTY`、`DEFECT_QTY`、兩種 rate、`REJECT_SHARE_PCT`、受影響 lot/workorder。
+- Trend Row：
+  - 左圖：`REJECT_TOTAL_QTY` vs `DEFECT_QTY`（量）
+  - 右圖：`REJECT_RATE_PCT` vs `DEFECT_RATE_PCT`（率）
+- Pareto + Detail：原因 Pareto（支援 metric mode 切換）與可分頁明細表。
+
+**Visual semantics:**
+- Reject（扣帳）使用暖色語義（紅/橘系）
+- Defect（不扣帳）使用冷色語義（藍/青系）
+- `MOVEIN_QTY`、總計與背景採中性灰藍語義
+- 互動態（hover/active/filter chip）沿用既有 shared style token，確保與現有報表視覺一致
+
+**Alternatives considered:**
+- 只保留單圖單指標：無法傳達兩種語義並列。
+- 新建完全獨立視覺主題：與既有 portal 風格落差大、維運成本高。
+
+### D5: 新頁採 pure Vite entry + Flask static route + shell native loader
+
+**Decision:** `frontend/src/reject-history/index.html` 作為 entry，build 後由 Flask `send_from_directory` 提供 `/reject-history`，並註冊到 `routeContracts` 與 `nativeModuleRegistry`。
+
+**Why:**
+- 與既有 in-scope page 架構一致，降低整合風險。
+- 保留 shell canonical route 與 direct-entry 相容策略。
+
+### D6: 匯出欄位以「語義明示」優先於歷史相容命名
+
+**Decision:** CSV 欄位明確輸出 `REJECT_TOTAL_QTY` 與 `DEFECT_QTY`，並可附五個 reject 組成欄位；不使用易混淆別名。
+
+**Why:**
+- 報表是對外分析依據，語義清晰優先於短期縮寫便利。
+- 與 field-name-consistency 治理要求一致。
+
+## Risks / Trade-offs
+
+- **[基底 SQL 單一來源造成查詢負載偏高]** → 先以日期與維度條件收斂、list/export 加 rate limit，必要時再追加快取或物化。
+- **[使用者沿用舊語意理解 defect]** → UI 顯示語義說明 badge + tooltip，匯出欄位採顯式命名。
+- **[Pareto 指標切換造成理解成本]** → 預設以 `REJECT_TOTAL_QTY` 顯示，並保留清楚的 toggle label。
+- **[路由治理漏登記導致 shell 無法導航]** → contract parity test + page_status 驗證列為必做任務。
+- **[明細資料量大造成前端卡頓]** → 後端分頁、預設 `per_page=50`，並避免一次性全量載入。
+
+## Migration Plan
+
+1. 建立後端 SQL/service/routes（先讓 API 可單獨驗證）。
+2. 建立前端 reject-history 頁面與元件（先接 summary/trend，再接 pareto/list/export）。
+3. 整合 shell 治理資產：`routeContracts`、`nativeModuleRegistry`、`page_status`、Flask page route。
+4. 補齊測試：service、routes、route-contract parity、前端 smoke。
+5. 先以 `dev` 狀態上線到抽屜，完成 UAT 後調整為 `released`。
+
+**Rollback strategy:**
+- 將 `/reject-history` 從 page registry 標記為隱藏或 `dev` 並停用導航入口。
+- 保留已上線的既有頁面與 API，不影響既有報表路徑。
+
+## Open Questions
+
+- 趨勢圖預設粒度是否固定「日」，或需同頁支援週/月切換？
+- Pareto 預設排序基準是否固定 `REJECT_TOTAL_QTY`，是否要允許切換為 `DEFECT_QTY`？
+- 匯出是否要同時提供「彙總版」與「明細版」兩種檔案型態，或先只提供明細版？
--- a/openspec/changes/reject-history-query-page/proposal.md
+++ b/openspec/changes/reject-history-query-page/proposal.md
@@ -1,26 +1,29 @@
 ## Why

-目前專案只有在 `query-tool` 的設備子頁籤提供報廢相關查詢，缺少一個可長期追蹤「報廢歷史」的專用報表頁。隨著既有架構已完成 portal-shell、route contract、Vite 多頁治理，現在適合用同一套架構新增 `報廢歷史查詢`，避免再引入獨立樣式或旁路流程。
+目前專案僅在 `query-tool` 提供偏即時/點查型的報廢資訊，缺少可追蹤趨勢與績效的「報廢歷史」專用報表。資料評估也顯示 `DW_MES_LOTREJECTHISTORY` 同一 `HISTORYMAINLINEID` 會對應多筆原因紀錄，若直接加總 `MOVEINQTY` 會造成分母重複、報廢率失真；同時既有查詢對 reject/defect 命名語義不一致，容易誤解指標。現在應在既有 portal-shell + Vite + route contract 架構下，建立一個語義明確且可治理的歷史報表頁。

 ## What Changes

- 新增 `報廢歷史查詢` 頁面路由 `/reject-history`，採用既有 pure Vite + portal-shell native route 模式。
- 新增後端 `reject-history` API 群組（摘要、趨勢、原因 Pareto、明細、匯出），提供前端報表所需資料。
- 新增 `reject-history` service + SQL 模組，統一計算：
+- 新增 `報廢歷史查詢` 頁面路由 `/reject-history`，採用既有 pure Vite + portal-shell native route 模式，納入抽屜導航與頁面治理。
+- 新增後端 `reject-history` API 群組（摘要 KPI、日/週趨勢、原因 Pareto、明細、匯出），提供前端報表所需資料。
+- 新增 `reject-history` service + SQL 模組，建立一致指標定義並明確拆分兩條指標線：
  - 扣帳報廢：`REJECT_TOTAL_QTY = REJECTQTY + STANDBYQTY + QTYTOPROCESS + INPROCESSQTY + PROCESSEDQTY`
  - 不扣帳報廢：`DEFECT_QTY = DEFECTQTY`
- 將新頁面納入既有導航與契約治理（page registry、drawer、routeContracts、nativeModuleRegistry、shell coverage）。
- 補齊對應測試（API/服務單元測試、route contract 治理測試、必要的頁面整合測試）。
+- 以事件層級去重規則處理分母（`MOVEIN_QTY` 以 `HISTORYMAINLINEID` 為主鍵去重），避免多原因拆單導致比率失真。
+- 明確定義 UI/API/匯出欄位語義，避免沿用「defect=五欄合計」這類歷史命名混淆，確保報表對外語意一致。
+- 不變更既有 `query-tool` 現有頁面行為與既有 API 回應欄位（此變更先聚焦新頁能力）。

 ## Capabilities

 ### New Capabilities
- `reject-history-page`: 新增報廢歷史查詢頁面，提供篩選、KPI、趨勢、原因分析與明細查詢/匯出。
- `reject-history-api`: 新增報廢歷史 API 能力與資料聚合邏輯，定義扣帳報廢與不扣帳報廢的並列指標語義。
+- `reject-history-page`: 新增報廢歷史查詢頁面，提供篩選、KPI、趨勢、原因分析、明細查詢與匯出。
+- `reject-history-api`: 新增報廢歷史 API 能力與資料聚合邏輯，支援報表層的摘要、趨勢、Pareto、明細資料來源。
+- `reject-metric-semantics`: 新增 reject/defect 指標語義規範，要求五個 reject 欄位合計與 `DEFECTQTY` 必須分開呈現、分開計算、分開命名。

 ### Modified Capabilities
 - `unified-shell-route-coverage`: 新增 `/reject-history` 後，路由契約清單與前後端契約對照規則需同步更新。
 - `vue-vite-page-architecture`: 新頁面需納入 Vite entry/output 與 Flask static HTML 服務規範，保持既有純 Vite 頁治理一致性。
+- `field-name-consistency`: reject/defect 相關欄位在 UI、API、匯出命名需維持一致語義，避免跨頁面誤用。

 ## Impact

@@ -42,5 +45,8 @@
  - 新增 `tests/test_reject_history_service.py`
  - 新增 `tests/test_reject_history_routes.py`
  - 補充 route coverage / contract parity / e2e smoke
+- 資料語義：
+  - 報表需同時呈現 `REJECT_TOTAL_QTY`（扣帳報廢）與 `DEFECT_QTY`（不扣帳報廢）
+  - 不以單一欄位混用兩種語義，避免誤判製程損失
 - 依賴：
  - 不新增第三方套件，沿用現有 Flask + Vue + Vite + SQLLoader + QueryBuilder 架構
--- a/openspec/changes/reject-history-query-page/specs/field-name-consistency/spec.md
+++ b/openspec/changes/reject-history-query-page/specs/field-name-consistency/spec.md
@@ -0,0 +1,22 @@
+## ADDED Requirements
+
+### Requirement: Reject and defect metric names SHALL remain semantically consistent across UI/API/export
+The system SHALL use explicit, stable names for charge-off reject and non-charge-off defect metrics across all output surfaces.
+
+#### Scenario: UI and API key alignment
+- **WHEN** summary/trend/list payloads are rendered on reject-history page
+- **THEN** UI labels for reject metrics SHALL map to `REJECT_TOTAL_QTY` and related reject-rate fields
+- **THEN** UI labels for defect metrics SHALL map to `DEFECT_QTY` and defect-rate fields
+
+#### Scenario: Export header alignment
+- **WHEN** reject-history CSV export is generated
+- **THEN** CSV headers SHALL include both `REJECT_TOTAL_QTY` and `DEFECT_QTY`
+- **THEN** header names SHALL preserve the same semantic meaning as API fields
+
+### Requirement: Reject component columns SHALL be explicitly distinguished from defect columns
+The system SHALL prevent ambiguous naming that collapses reject components and defect into a single term.
+
+#### Scenario: Component and aggregate coexistence
+- **WHEN** detailed records are presented
+- **THEN** reject component fields (`REJECTQTY`, `STANDBYQTY`, `QTYTOPROCESS`, `INPROCESSQTY`, `PROCESSEDQTY`) SHALL be distinguishable from `DEFECT_QTY`
+- **THEN** aggregate `REJECT_TOTAL_QTY` SHALL be clearly identified as component sum, not defect
--- a/openspec/changes/reject-history-query-page/specs/reject-history-api/spec.md
+++ b/openspec/changes/reject-history-query-page/specs/reject-history-api/spec.md
@@ -0,0 +1,84 @@
+## ADDED Requirements
+
+### Requirement: Reject History API SHALL validate required query parameters
+The API SHALL validate date parameters and basic paging bounds before executing database work.
+
+#### Scenario: Missing required dates
+- **WHEN** a reject-history endpoint requiring date range is called without `start_date` or `end_date`
+- **THEN** the API SHALL return HTTP 400 with a descriptive validation error
+
+#### Scenario: Invalid date order
+- **WHEN** `end_date` is earlier than `start_date`
+- **THEN** the API SHALL return HTTP 400 and SHALL NOT run SQL queries
+
+### Requirement: Reject History API SHALL provide summary metrics endpoint
+The API SHALL provide aggregated summary metrics for the selected filter context.
+
+#### Scenario: Summary response payload
+- **WHEN** `GET /api/reject-history/summary` is called with valid filters
+- **THEN** response SHALL be `{ success: true, data: { ... } }`
+- **THEN** data SHALL include `MOVEIN_QTY`, `REJECT_TOTAL_QTY`, `DEFECT_QTY`, `REJECT_RATE_PCT`, `DEFECT_RATE_PCT`, `REJECT_SHARE_PCT`, `AFFECTED_LOT_COUNT`, and `AFFECTED_WORKORDER_COUNT`
+
+### Requirement: Reject History API SHALL provide trend endpoint
+The API SHALL return time-series trend data for quantity and rate metrics.
+
+#### Scenario: Trend response structure
+- **WHEN** `GET /api/reject-history/trend` is called
+- **THEN** response SHALL be `{ success: true, data: { items: [...] } }`
+- **THEN** each trend item SHALL contain bucket date, `REJECT_TOTAL_QTY`, `DEFECT_QTY`, `REJECT_RATE_PCT`, and `DEFECT_RATE_PCT`
+
+#### Scenario: Trend granularity
+- **WHEN** `granularity` is provided as `day`, `week`, or `month`
+- **THEN** the API SHALL aggregate by the requested granularity
+- **THEN** invalid granularity SHALL return HTTP 400
+
+### Requirement: Reject History API SHALL provide reason Pareto endpoint
+The API SHALL return sorted reason distribution data with cumulative percentages.
+
+#### Scenario: Pareto response payload
+- **WHEN** `GET /api/reject-history/reason-pareto` is called
+- **THEN** each item SHALL include `reason`, `category`, selected metric value, `pct`, and `cumPct`
+- **THEN** items SHALL be sorted descending by selected metric
+
+#### Scenario: Metric mode validation
+- **WHEN** `metric_mode` is provided
+- **THEN** accepted values SHALL be `reject_total` or `defect`
+- **THEN** invalid `metric_mode` SHALL return HTTP 400
+
+### Requirement: Reject History API SHALL provide paginated detail endpoint
+The API SHALL return paginated detailed rows for the selected filter context.
+
+#### Scenario: List response payload
+- **WHEN** `GET /api/reject-history/list?page=1&per_page=50` is called
+- **THEN** response SHALL include `{ items: [...], pagination: { page, perPage, total, totalPages } }`
+- **THEN** each row SHALL include date, process dimensions, reason fields, `MOVEIN_QTY`, `REJECT_TOTAL_QTY`, `DEFECT_QTY`, and reject component columns
+
+#### Scenario: Paging bounds
+- **WHEN** `page < 1`
+- **THEN** page SHALL be treated as 1
+- **WHEN** `per_page > 200`
+- **THEN** `per_page` SHALL be capped at 200
+
+### Requirement: Reject History API SHALL provide CSV export endpoint
+The API SHALL provide CSV export using the same filter and metric semantics as list/query APIs.
+
+#### Scenario: Export payload consistency
+- **WHEN** `GET /api/reject-history/export` is called with valid filters
+- **THEN** CSV headers SHALL include both `REJECT_TOTAL_QTY` and `DEFECT_QTY`
+- **THEN** export rows SHALL follow the same semantic definitions as summary/list endpoints
+
+### Requirement: Reject History API SHALL centralize SQL in reject_history SQL directory
+The service SHALL load SQL from dedicated files under `src/mes_dashboard/sql/reject_history/`.
+
+#### Scenario: SQL file loading
+- **WHEN** reject-history service executes queries
+- **THEN** SQL SHALL be loaded from files in `sql/reject_history`
+- **THEN** user-supplied filters SHALL be passed through bind parameters
+- **THEN** user input SHALL NOT be interpolated into SQL strings directly
+
+### Requirement: Reject History API SHALL apply rate limiting on expensive endpoints
+The API SHALL rate-limit high-cost endpoints to protect Oracle and application resources.
+
+#### Scenario: List and export rate limiting
+- **WHEN** `/api/reject-history/list` or `/api/reject-history/export` receives excessive requests
+- **THEN** configured rate limiting SHALL reject requests beyond the threshold within the time window
--- a/openspec/changes/reject-history-query-page/specs/reject-history-page/spec.md
+++ b/openspec/changes/reject-history-query-page/specs/reject-history-page/spec.md
@@ -0,0 +1,105 @@
+## ADDED Requirements
+
+### Requirement: Reject History page SHALL provide filterable historical query controls
+The page SHALL provide a filter area for date range and major production dimensions to drive all report sections.
+
+#### Scenario: Default filter values
+- **WHEN** the page is first loaded
+- **THEN** `start_date` and `end_date` SHALL default to a valid recent range
+- **THEN** all other dimension filters SHALL default to empty (no restriction)
+
+#### Scenario: Apply and clear filters
+- **WHEN** user clicks "查詢"
+- **THEN** summary, trend, pareto, and list sections SHALL reload with the same filter set
+- **WHEN** user clicks "清除條件"
+- **THEN** all filters SHALL reset to defaults and all sections SHALL reload
+
+### Requirement: Reject History page SHALL present KPI cards with split reject/defect semantics
+The page SHALL display KPI cards that simultaneously show charge-off reject and non-charge-off defect metrics.
+
+#### Scenario: KPI cards render core metrics
+- **WHEN** summary data is loaded
+- **THEN** cards SHALL include `MOVEIN_QTY`, `REJECT_TOTAL_QTY`, `DEFECT_QTY`, `REJECT_RATE_PCT`, `DEFECT_RATE_PCT`, `REJECT_SHARE_PCT`, `AFFECTED_LOT_COUNT`, and `AFFECTED_WORKORDER_COUNT`
+- **THEN** numbers SHALL use zh-TW formatting
+
+#### Scenario: Visual distinction for semantic lanes
+- **WHEN** KPI cards are rendered
+- **THEN** reject-related cards SHALL use a warm-color visual lane
+- **THEN** defect-related cards SHALL use a cool-color visual lane
+- **THEN** page legend/badge text SHALL explicitly indicate charge-off vs non-charge-off meaning
+
+### Requirement: Reject History page SHALL display quantity and rate trends in separate charts
+The page SHALL show both quantity trend and rate trend to avoid mixing unit scales.
+
+#### Scenario: Quantity trend chart
+- **WHEN** trend data is loaded
+- **THEN** the quantity trend chart SHALL show `REJECT_TOTAL_QTY` and `DEFECT_QTY` over time
+- **THEN** the chart SHALL use a shared X-axis by date bucket
+
+#### Scenario: Rate trend chart
+- **WHEN** trend data is loaded
+- **THEN** the rate trend chart SHALL show `REJECT_RATE_PCT` and `DEFECT_RATE_PCT` over time
+- **THEN** rate values SHALL be displayed as percentages
+
+### Requirement: Reject History page SHALL provide reason Pareto analysis
+The page SHALL provide a Pareto view for loss reasons and support downstream filtering.
+
+#### Scenario: Pareto rendering and ordering
+- **WHEN** reason Pareto data is loaded
+- **THEN** items SHALL be sorted by selected metric descending
+- **THEN** a cumulative percentage line SHALL be shown
+
+#### Scenario: Pareto click filtering
+- **WHEN** user clicks a Pareto bar or row
+- **THEN** the selected reason SHALL become an active filter chip
+- **THEN** detail list SHALL reload with that reason
+- **THEN** clicking the same reason again SHALL clear the reason filter
+
+### Requirement: Reject History page SHALL show paginated detail rows
+The page SHALL provide a paginated detail table for investigation and traceability.
+
+#### Scenario: Detail columns
+- **WHEN** list data is loaded
+- **THEN** each row SHALL include date, workcenter group, workcenter, product dimensions, reason/category, `MOVEIN_QTY`, `REJECT_TOTAL_QTY`, `DEFECT_QTY`, and component reject columns
+
+#### Scenario: Pagination behavior
+- **WHEN** total records exceed per-page size
+- **THEN** Prev/Next and page summary SHALL be shown
+- **THEN** changing any filter SHALL reset page to 1
+
+### Requirement: Reject History page SHALL support CSV export from current filter context
+The page SHALL allow users to export records using the exact active filters.
+
+#### Scenario: Export with current filters
+- **WHEN** user clicks "匯出 CSV"
+- **THEN** export request SHALL include the current filter state and active reason filter
+- **THEN** downloaded file SHALL contain both `REJECT_TOTAL_QTY` and `DEFECT_QTY`
+
+### Requirement: Reject History page SHALL provide robust feedback states
+The page SHALL provide loading, empty, and error states without breaking interactions.
+
+#### Scenario: Initial loading
+- **WHEN** first query is running
+- **THEN** a loading overlay or skeleton SHALL be visible until required data sections are ready
+
+#### Scenario: API failure
+- **WHEN** any section API fails
+- **THEN** a visible error banner SHALL be shown
+- **THEN** already loaded sections SHALL remain interactive
+
+#### Scenario: Empty dataset
+- **WHEN** query returns no rows
+- **THEN** chart and table areas SHALL show explicit empty-state messages
+
+### Requirement: Reject History page SHALL maintain responsive visual hierarchy
+The page SHALL keep the same semantic grouping across desktop and mobile layouts.
+
+#### Scenario: Desktop layout
+- **WHEN** viewport is desktop width
+- **THEN** KPI cards SHALL render in multi-column layout
+- **THEN** trend and pareto sections SHALL render as two-column analytical panels
+
+#### Scenario: Mobile layout
+- **WHEN** viewport width is below responsive breakpoint
+- **THEN** cards and chart panels SHALL stack in a single column
+- **THEN** filter controls SHALL remain operable without horizontal overflow
--- a/openspec/changes/reject-history-query-page/specs/reject-metric-semantics/spec.md
+++ b/openspec/changes/reject-history-query-page/specs/reject-metric-semantics/spec.md
@@ -0,0 +1,58 @@
+## ADDED Requirements
+
+### Requirement: Charge-off reject metric SHALL be computed from five reject component columns
+The system SHALL compute `REJECT_TOTAL_QTY` as the sum of five reject-related quantity columns.
+
+#### Scenario: Reject total formula
+- **WHEN** a source record is transformed
+- **THEN** `REJECT_TOTAL_QTY` SHALL equal `REJECTQTY + STANDBYQTY + QTYTOPROCESS + INPROCESSQTY + PROCESSEDQTY`
+- **THEN** null component values SHALL be treated as zero
+
+### Requirement: Defect metric SHALL remain independent from reject total
+The system SHALL compute `DEFECT_QTY` only from `DEFECTQTY` and SHALL NOT merge it into `REJECT_TOTAL_QTY`.
+
+#### Scenario: Defect independence
+- **WHEN** a record has `DEFECTQTY > 0` and reject component sum equals 0
+- **THEN** `DEFECT_QTY` SHALL be non-zero
+- **THEN** `REJECT_TOTAL_QTY` SHALL remain 0
+
+### Requirement: Move-in denominator SHALL be deduplicated at event level
+The system SHALL deduplicate `MOVEIN_QTY` by event key before rate calculations.
+
+#### Scenario: Primary dedupe key
+- **WHEN** `HISTORYMAINLINEID` is present
+- **THEN** only one row per `HISTORYMAINLINEID` SHALL contribute `MOVEIN_QTY`
+
+#### Scenario: Fallback dedupe key
+- **WHEN** `HISTORYMAINLINEID` is missing
+- **THEN** fallback dedupe key SHALL use a deterministic composite key from transaction context
+
+### Requirement: Reject and defect rates SHALL use the same deduplicated denominator
+The system SHALL calculate percentage rates from deduplicated `MOVEIN_QTY` to ensure comparability.
+
+#### Scenario: Reject rate formula
+- **WHEN** `MOVEIN_QTY > 0`
+- **THEN** `REJECT_RATE_PCT` SHALL equal `REJECT_TOTAL_QTY / MOVEIN_QTY * 100`
+
+#### Scenario: Defect rate formula
+- **WHEN** `MOVEIN_QTY > 0`
+- **THEN** `DEFECT_RATE_PCT` SHALL equal `DEFECT_QTY / MOVEIN_QTY * 100`
+
+#### Scenario: Zero denominator handling
+- **WHEN** `MOVEIN_QTY = 0`
+- **THEN** both rate fields SHALL return 0 and SHALL NOT raise divide-by-zero errors
+
+### Requirement: Reject share SHALL describe reject proportion within total loss
+The system SHALL calculate reject share against combined reject and defect loss quantities.
+
+#### Scenario: Reject share formula
+- **WHEN** `REJECT_TOTAL_QTY + DEFECT_QTY > 0`
+- **THEN** `REJECT_SHARE_PCT` SHALL equal `REJECT_TOTAL_QTY / (REJECT_TOTAL_QTY + DEFECT_QTY) * 100`
+
+### Requirement: Metric naming SHALL preserve semantic meaning across transformations
+The system SHALL keep explicit names for charge-off reject and non-charge-off defect metrics.
+
+#### Scenario: No ambiguous remapping
+- **WHEN** service or export fields are generated
+- **THEN** `REJECT_TOTAL_QTY` SHALL NOT be renamed to `DEFECT_QTY`
+- **THEN** `DEFECT_QTY` SHALL refer only to `DEFECTQTY`
--- a/openspec/changes/reject-history-query-page/specs/unified-shell-route-coverage/spec.md
+++ b/openspec/changes/reject-history-query-page/specs/unified-shell-route-coverage/spec.md
@@ -0,0 +1,24 @@
+## ADDED Requirements
+
+### Requirement: Reject History route SHALL be included in governed shell route inventory
+The `/reject-history` route SHALL be represented in shell route contracts with complete governance metadata.
+
+#### Scenario: Frontend route contract entry
+- **WHEN** route contract validation runs against `frontend/src/portal-shell/routeContracts.js`
+- **THEN** `/reject-history` SHALL exist with route id, title, owner, render mode, visibility policy, scope, and compatibility policy
+
+#### Scenario: Native loader coverage
+- **WHEN** native module loader registry is validated
+- **THEN** `/reject-history` SHALL be resolvable in `nativeModuleRegistry`
+
+### Requirement: Reject History governance metadata SHALL be parity-validated across sources
+Shell governance checks SHALL enforce parity for `/reject-history` between frontend and backend contract inventories.
+
+#### Scenario: Contract parity for reject-history route
+- **WHEN** contract parity checks execute
+- **THEN** frontend and backend route inventories SHALL both include `/reject-history`
+- **THEN** metadata mismatch or missing route SHALL fail governance checks
+
+#### Scenario: Navigation visibility governance
+- **WHEN** page status/navigation config is evaluated
+- **THEN** `/reject-history` SHALL have governed drawer assignment and ordering metadata
--- a/openspec/changes/reject-history-query-page/specs/vue-vite-page-architecture/spec.md
+++ b/openspec/changes/reject-history-query-page/specs/vue-vite-page-architecture/spec.md
@@ -0,0 +1,40 @@
+## ADDED Requirements
+
+### Requirement: Reject History page SHALL be a pure Vite HTML entry
+The reject-history page SHALL be built from an HTML entry and emitted as static dist assets.
+
+#### Scenario: Vite entry registration
+- **WHEN** Vite config inputs are evaluated
+- **THEN** `reject-history` SHALL map to `frontend/src/reject-history/index.html`
+
+#### Scenario: Build output artifacts
+- **WHEN** `vite build` completes
+- **THEN** output SHALL include `reject-history.html`, `reject-history.js`, and `reject-history.css` in `static/dist/`
+
+### Requirement: Reject History route SHALL serve static dist HTML
+The Flask route for `/reject-history` SHALL serve pre-built static HTML through `send_from_directory`.
+
+#### Scenario: Static page serving
+- **WHEN** user navigates to `/reject-history`
+- **THEN** Flask SHALL serve `static/dist/reject-history.html` when the file exists
+- **THEN** HTML SHALL NOT be rendered through Jinja template interpolation
+
+#### Scenario: Dist fallback response
+- **WHEN** `reject-history.html` is missing in dist
+- **THEN** route SHALL return a minimal fallback HTML that still references `/static/dist/reject-history.js`
+
+### Requirement: Reject History shell integration SHALL use native module loading
+The page SHALL integrate with portal-shell native module loading policy.
+
+#### Scenario: Native module registration
+- **WHEN** shell resolves a route component for `/reject-history`
+- **THEN** it SHALL dynamically import `frontend/src/reject-history/App.vue`
+- **THEN** the route style bundle SHALL be loaded via registered style loaders
+
+### Requirement: Reject History page SHALL call APIs through shared core API module
+The page SHALL call backend APIs via `frontend/src/core/api.js` without legacy global dependencies.
+
+#### Scenario: API call path
+- **WHEN** reject-history page executes GET or export requests
+- **THEN** requests SHALL use shared API utilities (`apiGet`/equivalent)
+- **THEN** page behavior SHALL NOT depend on `window.MesApi`
--- a/openspec/changes/reject-history-query-page/tasks.md
+++ b/openspec/changes/reject-history-query-page/tasks.md
@@ -0,0 +1,53 @@
+## 1. Contract and Skeleton Setup
+
+- [ ] 1.1 Create backend blueprint scaffold `src/mes_dashboard/routes/reject_history_routes.py` and register it in `src/mes_dashboard/routes/__init__.py`
+- [ ] 1.2 Create service scaffold `src/mes_dashboard/services/reject_history_service.py` with SQL loader helpers
+- [ ] 1.3 Create frontend entry scaffold `frontend/src/reject-history/index.html`, `frontend/src/reject-history/main.js`, and `frontend/src/reject-history/App.vue`
+- [ ] 1.4 Add Vite input for `reject-history` in `frontend/vite.config.js`
+
+## 2. SQL and Metric Semantics Implementation
+
+- [ ] 2.1 Finalize base query `src/mes_dashboard/sql/reject_history/performance_daily.sql` for five-reject-sum + defect separation
+- [ ] 2.2 Add API-specific SQL files in `src/mes_dashboard/sql/reject_history/` (summary, trend, reason_pareto, list, export)
+- [ ] 2.3 Implement `MOVEIN_QTY` dedupe by `HISTORYMAINLINEID` with deterministic fallback key
+- [ ] 2.4 Implement consistent rate calculations (`REJECT_RATE_PCT`, `DEFECT_RATE_PCT`, `REJECT_SHARE_PCT`) with zero-denominator handling
+
+## 3. Backend API Routes
+
+- [ ] 3.1 Implement `GET /api/reject-history/summary` with date/filter validation
+- [ ] 3.2 Implement `GET /api/reject-history/trend` with `granularity` validation (`day|week|month`)
+- [ ] 3.3 Implement `GET /api/reject-history/reason-pareto` with `metric_mode` validation (`reject_total|defect`)
+- [ ] 3.4 Implement `GET /api/reject-history/list` with paging bounds and reason/category filters
+- [ ] 3.5 Implement `GET /api/reject-history/export` and CSV output contract
+- [ ] 3.6 Apply configured rate limiting to list/export endpoints
+
+## 4. Frontend Visual and Interaction Implementation
+
+- [ ] 4.1 Build page header with title, data timestamp, and semantic badges for charge-off reject vs non-charge-off defect
+- [ ] 4.2 Build filter panel (date range + dimensions + query/clear actions) and wire it to all API calls
+- [ ] 4.3 Implement KPI card row (8 cards) with warm/cool semantic color lanes and zh-TW number formatting
+- [ ] 4.4 Implement dual trend charts (quantity trend + rate trend) using ECharts with synchronized date buckets
+- [ ] 4.5 Implement reason Pareto chart/table with `metric_mode` switch and cumulative percentage line
+- [ ] 4.6 Implement detail table with pagination, active filter chips, and empty/error states
+- [ ] 4.7 Implement CSV export action using current filter context
+- [ ] 4.8 Add responsive rules so filter/cards/charts/table stay usable on tablet/mobile widths
+
+## 5. Shell and Route Governance Integration
+
+- [ ] 5.1 Add `/reject-history` contract entry to `frontend/src/portal-shell/routeContracts.js`
+- [ ] 5.2 Add `/reject-history` loader to `frontend/src/portal-shell/nativeModuleRegistry.js`
+- [ ] 5.3 Add `/reject-history` page metadata (drawer/order/status) to `data/page_status.json`
+- [ ] 5.4 Add Flask page route `/reject-history` using `send_from_directory` with dist fallback HTML
+
+## 6. Tests and Quality Gates
+
+- [ ] 6.1 Add service tests in `tests/test_reject_history_service.py` covering formulas, dedupe, and edge cases
+- [ ] 6.2 Add route tests in `tests/test_reject_history_routes.py` covering validation, payload shape, and rate-limit behavior
+- [ ] 6.3 Add/extend route-contract parity and shell coverage tests for `/reject-history`
+- [ ] 6.4 Add frontend smoke/integration test for query flow and major visual sections
+
+## 7. Documentation and Rollout
+
+- [ ] 7.1 Update implementation notes under `docs/reject_history_performance.md` to match API/UI field names
+- [ ] 7.2 Document rollout policy (`dev` visibility first, then `released`) and rollback path
+- [ ] 7.3 Run end-to-end verification checklist and capture evidence before implementation handoff