docs: update README for Hold/cascade/security features and sync deploy script entries

Update README v5.5 with Hold Overview/History pages, cascade filters, table query whitelist, WIP filter preservation, and review hardening changelog. Sync start_server.sh required frontend entries to cover all 13 Vite-built pages. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-11 10:57:13 +08:00
parent f90a8a57b4
commit cd54d7cdcb
2 changed files with 88 additions and 11 deletions
--- a/README.md
+++ b/README.md
@@ -14,13 +14,17 @@
 | WIP 即時概況 | ✅ 已完成 |
 | WIP 明細查詢 | ✅ 已完成 |
 | Hold 狀態分析 | ✅ 已完成 |
+| Hold 即時概況（Matrix + Lot 明細） | ✅ 已完成 |
+| Hold 歷史績效 Dashboard | ✅ 已完成 |
 | 數據表查詢工具 | ✅ 已完成 |
 | 設備狀態監控 | ✅ 已完成 |
 | 設備歷史查詢 | ✅ 已完成 |
+| 設備級聯篩選（Group/Family/Machine） | ✅ 已完成 |
 | 管理員認證系統 | ✅ 已完成 |
 | 頁面狀態管理 | ✅ 已完成 |
 | Redis 快取系統 | ✅ 已完成 |
 | SQL 查詢安全架構 | ✅ 已完成 |
+| Table Query API 白名單防注入 | ✅ 已完成 |
 | 效能監控儀表板 | ✅ 已完成 |
 | 熔斷器保護機制 | ✅ 已完成 |
 | Worker 重啟控制 | ✅ 已完成 |
@@ -38,6 +42,7 @@
 | QC-GATE 即時狀態報表（Vue 3 + Vite） | ✅ 已完成 |
 | 數據表查詢頁面 Vue 3 遷移 | ✅ 已完成 |
 | WIP 三頁 Vue 3 遷移（Overview/Detail/Hold Detail） | ✅ 已完成 |
+| WIP Overview/Detail 篩選條件保留 | ✅ 已完成 |
 | 設備雙頁 Vue 3 遷移（Status/History） | ✅ 已完成 |
 | 設備快取 DataFrame TTL 一致性修復 | ✅ 已完成 |
 | 中段製程不良追溯分析（TMTT → 上游） | ✅ 已完成 |
@@ -46,6 +51,12 @@

 ## 開發歷史（Vite 重構後）

+- 2026-02-11：完成 table query API `table_name` 白名單驗證（`/api/query_table`、`/api/get_table_columns`）— 拒絕未註冊資料表，補上整合測試，避免 SQL injection 入口。
+- 2026-02-11：完成設備雙頁級聯篩選（`/resource`、`/resource-history`）— 新增 Group/Family/Machine 多層篩選聯動，前後端支援 `resource_ids` 條件，矩陣與明細篩選一致。
+- 2026-02-11：完成 Hold Dashboard/Portal 修補 — realtime equipment cache dedup、Portal iframe 載入修正、Hold Overview/Hold History 明細與樣式優化。
+- 2026-02-11：完成 WIP Overview/Detail 篩選狀態保留與 thundering-herd 緩解 — drill-down 往返保留 URL filters，auto refresh 引入 jitter（±15%）降低同步打點。
+- 2026-02-10：新增 Hold 即時概況（`/hold-overview`）— Hold type/reason 篩選、Workcenter×Package Matrix、Lot 明細分頁（50 筆/頁），前後端 API 全量打通（summary/matrix/lots）。
+- 2026-02-10：新增 Hold 歷史績效（`/hold-history`）— 日趨勢、原因 Pareto、滯留時長分布、明細分頁與 record type 過濾，支援 quality/non-quality/all 切換。
 - 2026-02-10：完成中段製程不良追溯分析（`/mid-section-defect`）— TMTT 測試站不良回溯至上游機台/站點/製程。三段式資料管線（TMTT 偵測 → SPLITFROMID BFS + COMBINEDASSYLOTS 合批展開 → 上游製程歷史），支援 205 種不良原因篩選、6 張 Pareto 圖表、日趨勢、LOT 明細分頁（200 筆/頁）。Loss reasons 24h Redis 快取、分析結果 5 分鐘快取、Detail API 分離（summary ~16KB + detail ~110KB/page，原 72MB 單次回應）。
 - 2026-02-09：完成設備雙頁 Vue 3 遷移（`/resource`、`/resource-history`）— 兩頁共 1,697 行 vanilla JS + 3,200 行 Jinja2 模板重寫為 Vue 3 SFC。抽取 `resource-shared/` 共用模組（CSS 基底、E10 狀態常數、HierarchyTable 三層展開樹表元件），History 頁 4 個 ECharts 圖表改用 vue-echarts，Status 頁複用 `useAutoRefresh` composable（5 分鐘自動刷新）。
 - 2026-02-09：完成 WIP 三頁 Vue 3 遷移（`/wip-overview`、`/wip-detail`、`/hold-detail`）— 三頁共 1,941 行 vanilla JS + Jinja2 重寫為 Vue 3 SFC。抽取共用 CSS/常數/元件至 `wip-shared/`，Pareto 圖改用 vue-echarts（與 QC-GATE 一致），Hold Detail 新增前端 URL params 判斷取代 Jinja2 注入。
@@ -99,6 +110,7 @@
 - Root cutover 盤點：`docs/root_cutover_inventory.md`
 - 頁面架構與抽屜分類：`docs/page_architecture_map.md`
 - 前端計算前移與 parity 規則：`docs/frontend_compute_shift_plan.md`
+- Hold 歷史頁資料口徑說明：`docs/hold_history.md`
 - Cutover gates / rollout / rollback：`docs/migration_gates_and_runbook.md`
 - 環境依賴缺口與對策：`docs/environment_gaps_and_mitigation.md`

@@ -421,6 +433,16 @@ sudo systemctl start mes-dashboard mes-dashboard-watchdog
 3. 查詢結果顯示於下方表格
 4. 點擊「匯出 Excel」下載報表

+#### Hold 即時概況
+- 可切換品質異常 / 非品質異常 / 全部
+- 透過 Workcenter × Package Matrix 點選快速篩選 Lot 明細
+- 支援手動刷新與分頁瀏覽
+
+#### Hold 歷史績效
+1. 選擇日期區間與 Hold 類型
+2. 查看日趨勢、原因 Pareto、滯留時長分布
+3. 以原因/時長條件篩選下方明細表
+
 #### 設備狀態監控
 - 顯示所有設備的即時狀態（PRD/SBY/UDT/SDT/EGT/NST）
 - 使用階層篩選功能：
@@ -461,9 +483,10 @@ A: 請確認瀏覽器允許下載檔案，並檢查查詢結果是否有資料
 ### Portal 入口頁面

 透過側邊欄抽屜分組導覽切換各功能模組：
- **報表類**：WIP 即時概況、設備即時概況、設備歷史績效、QC-GATE 即時狀態
- **查詢類**：設備維修查詢、批次追蹤工具、TMTT 不良分析、中段製程不良追溯
- **開發工具**（admin only）：數據表查詢、Excel 批次查詢、頁面管理、效能監控
+- **即時報表**：WIP 即時概況、Hold 即時概況（dev）、設備即時概況、QC-GATE 即時狀態
+- **歷史報表**：Hold 歷史績效（dev）、設備歷史績效
+- **查詢工具**：設備維修查詢
+- **開發工具**（admin only）：數據表查詢、Excel 批次查詢、批次追蹤工具、TMTT 不良分析、中段製程不良追溯、頁面管理、效能監控
 - 抽屜/頁面配置可由管理員動態管理（新增、重排、刪除）

 ### WIP 即時概況
@@ -472,7 +495,7 @@ A: 請確認瀏覽器允許下載檔案，並檢查查詢結果是否有資料
 - Workcenter × Package 矩陣表（Top 15 欄位、sticky 首欄、Total 行列）
 - Hold Pareto 分析（品質/非品質分組、ECharts 雙軸柏拉圖 + 明細表）
 - Autocomplete 篩選（WORKORDER/LOT ID/PACKAGE/TYPE，cross-filter + 300ms debounce）
- 矩陣點擊 drill-down 至 WIP Detail、Pareto 點擊 drill-down 至 Hold Detail
+- 矩陣點擊 drill-down 至 WIP Detail、Pareto 點擊 drill-down 至 Hold Detail；返回後保留篩選條件
 - 10 分鐘自動刷新 + AbortController 請求取消
 - **技術架構**：Vue 3 + Vite，Pareto 圖使用 vue-echarts

@@ -486,7 +509,7 @@ A: 請確認瀏覽器允許下載檔案，並檢查查詢結果是否有資料
 - 10 分鐘自動刷新 + AbortController 請求取消
 - **技術架構**：Vue 3 + Vite

-### Hold 狀態分析
+### Hold 明細分析（Hold Detail）

 - 依 Hold 原因顯示摘要統計（Total Lots/QTY/平均滯留/最久滯留/影響站群）
 - 品質異常/非品質異常分類（前端常數判斷，紅/橙 gradient header）
@@ -496,13 +519,31 @@ A: 請確認瀏覽器允許下載檔案，並檢查查詢結果是否有資料
 - 10 分鐘自動刷新 + AbortController 請求取消
 - **技術架構**：Vue 3 + Vite，URL params 取代 Jinja2 注入

+### Hold 即時概況（Hold Overview）
+
+- Hold type / reason 篩選（quality / non-quality / all）
+- Summary cards（Total Lots / QTY / 平均滯留 / 最久滯留）
+- Workcenter × Package Matrix（QTY）點擊級聯到下方 Lot 明細
+- Lot 明細分頁（50 筆/頁）+ 篩選指示器 + 一鍵清除
+- 10 分鐘自動刷新 + visibilitychange 觸發刷新
+- **技術架構**：Vue 3 + Vite，複用 `hold-detail/SummaryCards` 與 `wip-shared/useAutoRefresh`
+
+### Hold 歷史績效（Hold History）
+
+- 日期區間 + Hold type 篩選（quality / non-quality / all）
+- Daily Trend（Hold/New Hold/Release/Future Hold）與 still-on-hold 指標
+- Record type 篩選（new/release/future）+ 原因 Pareto + 滯留時長分布
+- 明細表分頁（50 筆/頁）與 reason/duration 條件聯動
+- 手動刷新與初次載入 overlay
+- **技術架構**：Vue 3 + Vite（DailyTrend、ReasonPareto、DurationChart、DetailTable）
+
 ### 設備即時概況

 - 即時設備狀態總覽：10 張 KPI 卡片（OU%/AVAIL%/PRD/SBY/UDT/SDT/EGT/NST/OTHER/Total）
 - 三層階層矩陣表（workcenter group → family → resource），支援展開/收合與 cell click 篩選
 - 設備卡片格（auto-fill grid），顯示狀態/位置/LOT/JOB 資訊
 - LOT/JOB 浮動 tooltip（`<Teleport>` + viewport clamp 定位）
- 階層篩選（workcenter group 下拉 + 生產設備/重點設備/監控設備 checkbox）
+- 階層篩選（workcenter group + family + machine 級聯 + 生產設備/重點設備/監控設備 checkbox）
 - 5 分鐘自動刷新 + `visibilitychange` 即時刷新 + AbortController
 - Cache 狀態指示（green/yellow/red dot + 最後更新時間）
 - **技術架構**：Vue 3 + Vite，複用 `resource-shared/` 共用模組與 `useAutoRefresh` composable
@@ -512,7 +553,7 @@ A: 請確認瀏覽器允許下載檔案，並檢查查詢結果是否有資料
 - 9 張 KPI 卡片（OU%/AVAIL%/PRD/SBY/UDT/SDT/EGT/NST/機台數）
 - 4 個 vue-echarts 圖表：OU%/AVAIL% 趨勢折線、E10 狀態堆疊柱狀、workcenter OU% 橫向對比、OU% 熱圖
 - 三層階層明細表（使用 `resource-shared/HierarchyTable`），hours + percentage 格式
- 日期區間（預設 7 天）+ 粒度切換（日/週/月/年）+ 多選下拉篩選
+- 日期區間（預設 7 天）+ 粒度切換（日/週/月/年）+ Group/Family/Machine 級聯多選篩選
 - CSV 串流匯出（`/api/resource/history/export`）
 - **技術架構**：Vue 3 + Vite，4 圖表全部使用 `<VChart :option autoresize />`

@@ -605,7 +646,7 @@ CIRCUIT_BREAKER_RECOVERY_TIMEOUT=30
 | 技術 | 用途 |
 |------|------|
 | Jinja2 | 模板引擎（既有頁面） |
-| Vue 3 | UI 框架（QC-GATE、Tables、WIP 三頁、設備雙頁、中段不良追溯已遷移，漸進式擴展中） |
+| Vue 3 | UI 框架（QC-GATE、Tables、WIP 三頁、Hold Overview/History、設備雙頁、中段不良追溯已遷移） |
 | vue-echarts | ECharts Vue 封裝（QC-GATE、WIP Overview Pareto、Resource History 4 圖表、Mid-Section Defect 7 圖表） |
 | Vite 6 | 前端多頁模組打包（含 Vue SFC + HTML entry） |
 | ECharts | 圖表庫（npm tree-shaking + 舊版靜態檔案並存） |
@@ -668,12 +709,16 @@ DashBoard_vite/
 │   ├── src/resource-history/   # 設備歷史績效 (Vue 3 SFC)
 │   ├── src/job-query/          # 設備維修查詢 entry
 │   ├── src/excel-query/        # Excel 批次查詢 entry
+│   ├── src/query-tool/         # 批次追蹤工具 entry
+│   ├── src/tmtt-defect/        # TMTT 不良分析 entry
 │   ├── src/tables/             # 數據表查詢 entry (Vue 3 SFC)
 │   ├── src/qc-gate/            # QC-GATE 即時狀態 (Vue 3 SFC)
 │   ├── src/wip-shared/         # WIP 三頁共用 CSS/常數/元件
 │   ├── src/wip-overview/       # WIP 即時概況 (Vue 3 SFC)
 │   ├── src/wip-detail/         # WIP 明細查詢 (Vue 3 SFC)
 │   ├── src/hold-detail/        # Hold 狀態分析 (Vue 3 SFC)
+│   ├── src/hold-overview/      # Hold 即時概況 (Vue 3 SFC)
+│   ├── src/hold-history/       # Hold 歷史績效 (Vue 3 SFC)
 │   └── src/mid-section-defect/ # 中段不良追溯分析 (Vue 3 SFC)
 ├── shared/
 │   └── field_contracts.json    # 前後端共用欄位契約
@@ -758,8 +803,31 @@ conda run -n mes-dashboard python scripts/run_cache_benchmarks.py --enforce

 ## 變更日誌

+### 2026-02-11
+
+- 安全修補：`/api/query_table`、`/api/get_table_columns` 新增 `table_name` 白名單驗證
+  - 僅允許 `TABLES_CONFIG` 註冊表格，未授權名稱直接回傳 400
+  - 補上整合測試（拒絕惡意 table_name）
+- 設備頁篩選升級（`/resource`、`/resource-history`）：
+  - 新增 Group/Family/Machine 級聯篩選
+  - status/summary/matrix、history summary/detail/export 全線支援 `resource_ids`
+- Hold 與 Portal 修補：
+  - realtime equipment cache dedup，降低重複合併與資料抖動
+  - 修正 Portal iframe 載入與 Hold Dashboard 視覺/明細互動細節
+- WIP 體驗與穩定性：
+  - Overview → Detail → Overview 往返保留篩選條件（URL params）
+  - auto refresh 加入 jitter（±15%）避免多頁同步 thundering-herd
+- Review hardening：
+  - 7 個高流量頁面補齊安全/穩定性/效能細節（前端請求控制、後端防護與 page 配置一致性）
+
 ### 2026-02-10

+- 新增 Hold 即時概況（`/hold-overview`）：
+  - Hold type/reason 篩選 + Summary cards + Workcenter×Package Matrix + Lot 明細
+  - API：`/api/hold-overview/summary`、`/api/hold-overview/matrix`、`/api/hold-overview/treemap`、`/api/hold-overview/lots`
+- 新增 Hold 歷史績效（`/hold-history`）：
+  - Daily trend、Reason Pareto、Duration 分布、明細分頁（50 筆/頁）
+  - API：`/api/hold-history/trend`、`/api/hold-history/reason-pareto`、`/api/hold-history/duration`、`/api/hold-history/list`
 - 新增中段製程不良追溯分析頁面（`/mid-section-defect`）：
  - TMTT 測試站偵測到的不良，反向追蹤至上游機台/站點/製程的歸因分析
  - 三段式資料管線：TMTT 偵測 → LOT 族譜解析（SPLITFROMID BFS 分批鏈 + COMBINEDASSYLOTS 合批展開）→ 上游製程歷史
@@ -836,7 +904,7 @@ conda run -n mes-dashboard python scripts/run_cache_benchmarks.py --enforce
 - WIP overview/detail 導入共享 derive 模組（`frontend/src/core/wip-derive.js`）
 - 新增 cache benchmark fixture 與 baseline-vs-indexed 門檻驗證
 - 新增前端 Node 測試流程（`npm --prefix frontend test`）
- 更新 `README.mdj` 與 migration runbook 文件對齊 gate
+- 更新 `README.md` 與 migration runbook 文件對齊 gate

 ### 2026-02-07

@@ -914,5 +982,5 @@ conda run -n mes-dashboard python scripts/run_cache_benchmarks.py --enforce

 ---

-**文檔版本**: 5.4
-**最後更新**: 2026-02-10
+**文檔版本**: 5.5
+**最後更新**: 2026-02-11