把 docs/ 文件納入版本控制，.gitignore 補 .venv/ 與本機測試樣本

- docs/需求彙整-UIUX改版.md 與 docs/進度報告-2026-07-21.md 從建立至今
未被追蹤過，前者是要交付業主的需求文件
- docs/design/ 維持排除（設計素材不進版本控制，沿用原本排除 00pic/ 的慣例）
- .gitignore 補 .venv/ 與 _bug2test/

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.gitignore

@@ -33,6 +33,7 @@ __pycache__/
 *.pyc
 *.pyo
 .env
+.venv/
 
 # IDE
 .vscode/
@@ -50,3 +51,6 @@ shot.*
 
 # 殘留 log
 sessionsapp_log.txt
+
+# 本機手動測試用的壞格式樣本
+_bug2test/

docs/進度報告-2026-07-21.md

@@ -0,0 +1,35 @@
+# 致理語料分析平台 UI/UX 改版 — 進度報告（2026-07-21）
+
+## 總覽
+
+改版分成 11 個階段，依風險由低到高排序執行，每個階段都是「先做完、驗證通過才進下一階段」，不會一次改太多混在一起。目前狀態：
+
+**已完成 6 / 11 個階段**（Phase 0-6），全部經過實測驗證，程式碼已在獨立的工作分支上逐步提交存檔，尚未合併回主版本（等全部完成、確認過再一次推上去，不影響目前線上運作中的版本）。
+
+---
+
+## 各階段工作任務與施行複雜度
+
+| Phase | 工作任務 | 施行複雜度 | 狀態 |
+|---|---|---|---|
+| 0 | 建立測試基準（跑一次完整流程確認系統正常，作為之後每次改動的比對依據） | 低 | ✅ 已完成 |
+| 1 | 全站文字大小統一、Metadata表單標題編號跳號的小瑕疵修正、頁尾多餘連結移除、略過補充說明的文案定稿 | 低 | ✅ 已完成 |
+| — | （額外項目）對話框視覺調整：氣泡寬度、留白、配色微調 | 低 | ✅ 已完成 |
+| 2 | 修復「格式驗證失敗後無法重新上傳」的既有bug——原本使用者上傳檔案不符規定後，系統會要求重傳卻又不給重傳的入口，形成死結 | 中 | ✅ 已完成 |
+| 3 | 上傳驗證強化：檔名字首檢查（依研究情境判斷合法性）、每組至少需有1個檔案的完整性檢查、Metadata表單「群組數量」與實際上傳分組數的一致性檢查 | 中 | ✅ 已完成 |
+| 4 | 修復「運算失敗時步驟列沒有失敗提示」的既有bug——原本失敗時圓點會卡在「進行中」動畫上，使用者容易誤以為系統當機 | 中 | ✅ 已完成 |
+| 5 | 結果分頁排版微調（下載按鈕移到頁面頂部、圖表移到表格上方）；補上「監督式學習」「非監督式學習」兩個分頁原本缺少的下載按鈕 | 中 | ✅ 已完成 |
+| 6 | 修復「選定研究情境後無法變更」的既有bug（需求訪談時提到的重要問題）——新增「開始新分析」重置機制，讓使用者可以隨時安全地重新開始，不會卡在錯的情境選擇裡出不來 | 中高 | ✅ 已完成 |
+| 7 | 對話框與上傳欄合併成單一輸入框（原本上傳欄在對話框下方要往下捲動才看得到，使用者常找不到） | 高——牽涉到新舊元件並存過渡，需分兩步驟做（先新增新的、驗證沒問題後才拿掉舊的） | ⏳ 待進行 |
+| 8 | **左側導覽列大改版**——把現有「情境按鈕＋上傳卡片」的版面，改成設計討論時定案的左側固定導覽列（開始新分析／讀取進度／結果導覽） | 高——牽動整個版面結構重排 | ⏳ 待進行，**第一個看得出明顯視覺差異的階段** |
+| 9 | **首頁改版**——把設計稿的「4張情境卡片」首頁，真正實作進系統畫面 | 最高——全案技術難度最高的部分，因為 Gradio 這個開發框架本身沒有現成的方式能呈現這種卡片視覺，需要額外寫一段橋接程式，沒有前例可循 | ⏳ 待進行，**完整還原設計稿的階段** |
+| 10 | 持久化功能——中途可存檔、之後能讀檔繼續分析（不用整個重跑），分三小段（存檔／讀檔／錯誤狀況處理） | 高——全新功能，非既有bug修復 | ⏳ 待進行 |
+| 11 | 收尾：剩餘的畫面提示文字補齊＋全站完整回歸測試 | 低-中 | ⏳ 待進行 |
+
+---
+
+## 進度總結
+
+目前已經把系統裡「使用起來會卡住、會誤導使用者」的幾個既有問題都修好了（情境選錯無法重來、上傳失敗無法補救、運算失敗畫面沒反應、部分結果缺下載按鈕），這部分屬於「地基工程」，畫面上不會有明顯的視覺差異，但實際操作起來會順很多。
+
+接下來要做的是「看得到的改版」：把畫面重新排版（左側導覽列）、把首頁換成新設計（4張情境卡片），這兩個階段做完，畫面才會跟設計稿一致。

docs/需求彙整-UIUX改版.md

@@ -0,0 +1,305 @@
+# SpectraEngine（譯彩紛呈 II 分析引擎）UI/UX 改版需求彙整
+
+- 文件建立日期：2026-07-20
+- 最後更新日期：2026-07-20
+- 專案委託方：致理科技大學應日系鄧老師
+- 專案執行：吳千卉
+- 用途：①與 UI/UX Pro Max Skill 協作設計時的需求依據 ②向業主說明本次改版變動內容與理由的對照文件
+
+---
+
+## 一、專案背景
+
+`SpectraEngine` 是一套針對重譯文本（retranslation）語言特徵的量化分析平台，技術上是 **Python + Gradio 單頁研究工具**（`app_agent.py`，約 3400 行），並非傳統前後端分離的 HTML/CSS/JS 網站，部署在 Hugging Face Spaces。系統採雙 Agent 架構：主 Agent（LLM1）負責研究情境引導與報告撰寫，工作程序 Agent（LLM2）負責上傳引導與格式驗證。
+
+本次改版目標：**優化操作流程與介面風格**，方向參考 ChatGPT／Claude 網頁版的排版與操作體驗，同時修正過程中發現的既有問題。
+
+## 二、技術背景與限制（改版時務必遵守）
+
+| 項目 | 說明 |
+|---|---|
+| Repo 結構 | 業主原始 repo：`github.com/minchun-git/SpectraEngine`（唯讀，**不可直接推送**）；工作用 fork：`github.com/unlag/SpectraEngine`；本地工作分支：`redesign/ui-refresh`，`main` 保持乾淨不動 |
+| 本地路徑 | `500_Projects\致理應日系-譯彩紛呈分析引擎`（`origin`=fork 可推，`upstream`=業主原始repo 唯讀） |
+| 本機測試 | `.venv` 已建置，`python app_agent.py` 啟動於 `http://127.0.0.1:7860`；無 API key 也能看主頁畫面，LLM 對話功能需 `.env` 填 `LLM1_API_KEY`/`LLM2_API_KEY` |
+| 測試套件 | **無**，每次改動需手動跑過完整流程驗證，不能只憑程式碼檢查 |
+| 風險分區 | `_CUSTOM_CSS`（1639–2550行）純樣式、低風險；`create_app()`（2706行起）版面配置、中風險（勿動 `.click()`/`.change()` 事件綁定）；`handle_*` 流程函式（1429–1620行）與核心運算函式（320–1330行）為高風險，**改版不應觸碰** |
+| Gradio 版本 | 6.20.0（`footer_links` 等新版 API 可用，不需 CSS hack） |
+
+## 三、已確認的既有 Bug（本次改版應一併修正，非新功能）
+
+### Bug 1：選定研究情境後無法變更
+- **位置**：`app_agent.py` 第 3170–3171 行
+- **原因**：情境按鈕選擇後 `scenario_btn_col` 被設為 `visible=False`，程式碼中沒有任何地方會再設回 `visible=True`；對話框打字輸入也不會被辨識為「換情境」指令
+- **修法**：與新版「開始新分析」的未儲存警示機制共用同一套邏輯（換情境＝重新開始）
+
+### Bug 2：格式驗證失敗後無法重新上傳
+- **位置**：`app_agent.py` 第 3209–3213 行（`on_upload_confirm` 失敗分支）
+- **原因**：驗證失敗訊息本身清楚（逐檔列出原因＋修正工具連結），但失敗分支把 `upload_row` 寫死 `gr.update(visible=False)`，導致使用者被叫去重新上傳卻沒有任何上傳欄位可用。目前無存檔機制，使用者唯一解法是重整頁面，導致整個流程歸零
+- **修法**：失敗分支的 `upload_row` 輸出改為 `visible=True`
+- **一併處理**：目前驗證失敗會把**全部**上傳檔案清空（`state["uploaded_files"] = []`），不論哪個檔案有問題。改為**只清除驗證失敗的檔案，已通過的檔案保留**，使用者只需補傳有問題的檔案
+- ⚠️ 修改僅能留在 `redesign/ui-refresh` 分支與 `origin`（千卉 fork），不推送到 `upstream`（業主原始 repo）
+
+### 既有小瑕疵：語料 Metadata 表單章節編號跳號
+- **位置**：Metadata 表單「二、比較結構」區塊僅情境 3、4 顯示，情境 1、2 時整段隱藏但編號未跟著調整，導致畫面顯示「一、三、四」跳過「二」
+- **修法**：**拿掉數字編號，改用純文字區塊標題**（不做動態重新編號，避免情境增減時編號邏輯複雜化）
+
+### Bug 3：步驟列沒有「失敗」視覺狀態，且此失敗路徑確定會被真實觸發
+- **位置**：`run_computation_pipeline_streaming`（第 1538 行起）的指標計算／統計分析例外處理分支（第 1556、1580 行附近），會把 `state["state"]` 設為 `"COMPLETE"` 並停止流程，但**頂部步驟列的渲染邏輯（`_todo_update`／`_build_header_html`）只看 `done_steps`／`current_step`，完全不管 `state["state"]`**，只有「完成／進行中／未開始」三種視覺狀態，沒有「失敗」狀態
+- **實際後果**：失敗當下卡在那一步的圓點會維持「進行中」的呼吸動畫效果，**永遠停在那裡閃爍**，只有對話串裡一行文字錯誤訊息，使用者容易誤以為系統還在運算、進而手滑刷新頁面
+- **確認會被真實觸發，不是純理論**：查了 `run_statistical_analysis` 的分群運算（`AgglomerativeClustering`／`KMeans`／`linkage`），這些函式都要求**樣本數（上傳文本數）必須 ≥ 分群數**，否則 scikit-learn 直接丟例外。���**目前的格式驗證完全沒有檢查「每組至少要上傳幾個檔案」**，使用者只上傳 1-2 個檔案或漏傳某一組，就會在統計分析階段真的撞上這個失敗路徑——這是新手使用者第一次操作就可能踩到的情況，不是極端邊界案例
+- **修法**：①步驟列加第四種視覺狀態（失敗／警示樣式，如紅色或驚嘆號圖示），失敗時明確停留顯示，不要繼續播放進行中動畫；錯誤訊息旁加明確的下一步動作（如「重新上傳」連結），不要只留文字說明 ②在格式驗證階段攔截根本原因，見下方「上傳驗證強化」
+- 補充：LLM 報告撰寫失敗的處理方式較好，會繼續往下走並提示「其他分析結果仍可下載」，只有指標計算與統計分析這兩個失敗分支有上述問題
+
+### Bug 3 附帶：上傳驗證強化（同一批修，分兩個檢查點）
+現況只驗證斷詞內容格式（`validate_ckip_format`），完全沒檢查檔名字首合法性、分組完整性。三項合併設計如下：
+
+**✅ 千卉判斷應修正的既有缺陷，非待業主確認事項（2026-07-20）**
+
+**第一階段（格式驗證關卡，`run_format_check`，第 1489 行）——可一次到位：**
+1. **檔名字首合法性**：與現有逐檔驗證斷詞格式的迴圈合併，依 `state["scenario"]` 判斷允許的字首集合——情境1、2 只接受 {A,B}；情境3、4 接受 {A,B,C}。不合法視同格式不符，錯誤訊息風格比照現有：「檔名 xxx.txt 的字首不符——本情境僅接受 A_xx.txt / B_xx.txt（或 C_xx.txt）格式」
+2. **每組至少1個檔案**：全部檔案通過檔名+格式驗證後，統計實際出現的字首集合——情境1、2必須同時有A、B，缺一即擋下，提示「請確認 A、B 兩組皆已上傳，目前偵測到：{...}」；情境3、4至少要有A、B
+
+**第二階段（無法併入格式驗證，時序限制）：**
+3. **Metadata表單「群組數量」跟實際上傳分組數的一致性**：使用者選「二群/三群」是在格式驗證**之後**的 Metadata 表單才填，格式驗證當下系統還不知道使用者意圖，結構上無法併入同一關。改在 `on_metadata_confirm`（第3331行附近）送出時多一道比對，不吻合就跳出提醒讓使用者確認
+
+## 四、新增功能缺口（非 Bug，需與業主確認是否納入本次改版範圍）
+
+### 缺口 1：無「整包下載」功能
+- `run_computation_pipeline_streaming`（第 1538 行起）只把所有產出檔案路徑收集進 `state["output_files"]`，跑完後僅顯示文字提示「各項結果請點選上方各分頁查看」，**沒有任何 zip 打包邏輯**。`state` 裡雖有 `zip_path` 欄位（第 1367 行）但從未被賦值使用
+- 使用者目前要拿到全部產出，必須跑進 3 個結果分頁各自下載
+- **本次改版做法**：先做 UI 假按鈕（「下載完整報告」，位置見下方左側導覽規劃），**不接真正的 zip 打包邏輯**，是否要做後端由業主決定
+
+### 缺口 2：「語料 Metadata 說明」略過後無法回頭補填
+- 目前點「略過」後，系統標記為「使用者未提供」並永久跳過，**沒有任何入口可以事後回來編輯**
+- **本次改版做法**：不做「回來補」功能，只調整文案誠實告知：「以下資訊會寫入報告開頭，您也可以先略過（略過後這次分析將不會用到這些補充說明）」
+
+### 缺口 3：統計比較分析「監督式學習」「非監督式學習」兩子頁沒有下載按鈕
+- 「1. 敘述統計」「2. 差異性分析」有各自的下載按鈕，但「3. 監督式學習」「4. 非監督式學習」**完全沒有下載入口**
+- 澄清：**不是內容產不出來**——後端 `run_statistical_analysis` 已經有算出並存檔（`imp_path`／`imp_fig_path`／`dendro_path`／`elbow_path`／`cluster_fig_path`／`cluster_csv_path`），只是沒有接對應的 UI 下載按鈕
+- **技術上確認可行、且是低成本修改**：「敘述統計」「差異性分析」兩子頁已經有接 `gr.File` 元件顯示下載按鈕（`tab_desc_file`／`tab_diff_file`），照同一種寫法幫「監督式學習」「非監督式學習」各加一個 `gr.File` 接到已存在的檔案路徑即可，不需新增任何運算邏輯
+- **結論**：不並入「整包下載」或左側導覽「下載指標數據」，維持跟敘述統計／差異性分析一致的做法，各自在右側子頁內容區補一顆自己的下載按鈕
+- **命名**：「下載監督式學習」／「下載非監督式學習」（比照現有 `label="下載敘述統計"`／`label="下載差異性分析"` 命名模式）
+- **下載內容**：
+
+  | 子頁 | 下載內容 |
+  |---|---|
+  | 監督式學習 | `imp_path`：特徵重要性分數排序表（CSV）；`imp_fig_path`：Top20 特徵重要性長條圖（PNG） |
+  | 非監督式學習 | `dendro_path`：階層式分群樹狀圖（PNG）；`elbow_path`：K-means Elbow 曲線（PNG）；`cluster_fig_path`：PCA 二維分群散佈圖（PNG）；`cluster_csv_path`：分群結果表（CSV） |
+
+- **✅ 已確認要做**：補上下載按鈕以維持四個子頁一致性
+
+## 五、資訊架構設計
+
+### 5.1 首頁（新增，取代原本「情境選擇」是對話中第一步的設計）
+- 單欄置中，大標題＋簡短說明
+- **直接展示 4 個情境選項卡片**（不做「開始新分析」按鈕→再選情境的兩步驟，選了任一情境卡片即直接開始）
+- 每個情境卡片需附一行說明文字（原本在對話中選情境旁邊只有短標籤，搬到首頁沒有 AI 陪同引導，需要更清楚的說明避免選錯）
+- **卡片說明文字草稿**（基於 `SCENARIOS` 字典裡現成但目前完全未使用的 `desc` 欄位改寫，供 Skill 協作時進一步優化語氣／字數）：
+
+  | 情境 | 卡片說明文字草稿 |
+  |---|---|
+  | 1. 人工翻譯 vs 機器翻譯 | 比較人工與機器譯本在語言特徵上的差異，聚焦人機翻譯風格對比。 |
+  | 2. 全譯 vs 編譯（節譯、改寫） | 比較完整翻譯與節譯／改寫版本，聚焦文本完整性與改寫策略。 |
+  | 3. 不同譯者的同期譯本 | 比較同一時期不同譯者的譯本，聚焦個人風格差異（已排除時代因素）。 |
+  | 4. 同一原文的不同時期人工譯本 | 比較同一原文在不同時期的譯本，聚焦歷時語言變化與翻譯規範演變。 |
+- 「讀取進度」為次要連結，入口在首頁；讀檔後**直接跳過首頁**，回到中斷當下的步驟與畫面狀態（不用再選一次情境）
+
+### 5.2 導覽層級：頂部步驟列 vs 左側「結果導覽」
+兩者互補、不衝突，但視覺上要做出層級差異避免使用者誤認重複：
+
+| | 頂部步驟列 | 左側結果導覽 |
+|---|---|---|
+| 性質 | 時間軸型：進度到第幾步 | 空間型：跳著看已完成結果 |
+| 內容 | ①上傳引導②文本上傳③格式驗證④指標計算⑤統計分析⑥報告撰寫⑦下載成果（共 7 步，原 8 步扣掉已搬到首頁的「情境選擇」） | 🏠對話／📊語言指標分析／📈統計比較分析（展開4子項）／📝LLM輔助分析 |
+| 生命週期 | 全部完成（第7步）後**隱藏**，讓畫面空間交給結果內容 | 分析開始前不出現；完成後接手成為主要瀏覽方式，與步驟列隱藏的時機交接一致 |
+
+### 5.3 情境標籤（新增，因情境選擇搬到首頁後產生的需求）
+- 進入工作區後需常駐顯示「目前情境」小標籤，**獨立於步驟列存在**（步驟列隱藏後仍要留著）
+- 格式：「情境：3. 不同譯者的同期譯本　[變更]」
+- 位置：右欄最上方、步驟列正上方
+- 「變更」連結沿用「開始新分析」的未儲存警示機制（換情境＝重新開始，同一套邏輯／同一個 Bug 1 修法）
+
+## 六、版面配置
+
+### 6.1 整體：二欄式（不做三欄）
+左欄導覽（窄）＋右欄主畫面。原因：「執行進度」已在業主上一版整併進頂部步驟列，不需要獨立第三欄。
+
+### 6.2 左側導覽列
+```
+┌─────────────────────┐
+│ 🆕 開始新分析          │
+│ 📂 讀取進度            │
+├─────────────────────┤
+│ 情境：X. ○○○○ [變更]   │  ← 分析開始後才出現
+│ 🏠 對話               │
+│ 📊 語言指標分析         │
+│ 📈 統計比較分析  ▾      │
+│    ├ 敘述統計          │
+│    ├ 差異性分析         │
+│    ├ 監督式學習         │
+│    └ 非監督式學習        │
+│ 📝 LLM輔助分析          │
+├─────────────────────┤  ← 分隔線
+│ ⬇️ 下載指標數據         │  ← 指標計算一跑完即可下載，不用等全部結束
+│ ⬇️ 下載完整報告(假按鈕)  │  ← 全案完成才出現/啟用
+├─────────────────────┤
+│ ⚙️ 設定　🔌 API        │  ← 置底，低視覺權重
+└─────────────────────┘
+```
+- 固定窄寬 240–280px
+- **桌面版可收合**成 ChatGPT 式細窄 icon bar（收合後只留：新對話/讀取進度 icon ＋ 置底設定/API icon）
+- **手機版**：漢堡選單/抽屜收合，預設只顯示對話主畫面，點擊展開側欄
+- 統計比較分析第二層 4 個子分頁用 Accordion 展開（沿用現有「技術執行紀錄」已使用過的收合元件模式，風險中低）
+
+### 6.3 右欄（對話畫面）
+```
+┌──────────────────────────────────────────┐
+│ 情境：3. 不同譯者的同期譯本  [變更]              │ ← 常駐情境標籤
+│ ① 上傳引導 ② 文本上傳 ③ 格式驗證 ④ 指標計算 ...   │ ← 頂部步驟列(7步，完成後淡出)
+├─────────────────────────���────────────────┤
+│   對話串（AI訊息左側藍線／使用者訊息右側）           │
+│   [若目前是 Metadata 步驟 → 插入獨立表單卡片，     │
+│    不套用聊天泡泡左右分欄邏輯，佔滿全欄寬，          │
+│    對話視窗仍在其上方，同頁面往下捲動、非彈出視窗]     │
+├──────────────────────────────────────────┤
+│ ▸ 技術執行紀錄（預設收合，弱化字級，主要給技術夥伴用）  │
+├──────────────────────────────────────────┤
+│ 📎  [ 輸入文字，或附加檔案… ]           送出 →   │ ← 改用 gr.MultimodalTextbox
+└──────────────────────────────────────────┘
+```
+- 對話與上傳改用 `gr.MultimodalTextbox` 合併（現有 UI 對話框在上、上傳欄在下要往下滾動，使用者常找不到）
+- 「技術執行紀錄」判斷是給業主的工程夥伴看的，非一般使用者需求，維持現況的收合行為即可，字級再弱化
+
+### 6.4 結果分頁排版
+| 分頁 | 內容 | 排版決策 |
+|---|---|---|
+| 📊 語言指標分析 | 說明文字＋75項指標數值表格＋下載 | 下載按鈕移到頁面頂部，不要放表格後面 |
+| 📈 統計-1 敘述統計 | 說明＋表格＋下載 | 沿用現有排版 |
+| 📈 統計-2 差異性分析 | 表格＋箱形圖＋下載 | 圖表在上、表格在下，先看圖抓重點 |
+| 📈 統計-3 監督式學習 | 特徵重要性表格＋圖（現有左右並排） | 沿用；側欄縮窄後放不下則改上下堆疊 |
+| 📈 統計-4 非監督式學習 | 樹狀圖＋Elbow並排／PCA全寬／分群表格 | 沿用現有配置 |
+| 📝 LLM輔助分析 | 報告文字＋下載 | 舒適閱讀排版（適中行寬、寬鬆行高） |
+
+## 七、語料 Metadata 說明表單
+
+- **四種情境都會出現此表單**：只要格式驗證通過即跳出，不因情境而整段略過；差異只在表單「內容」，不是「是否顯示」——情境1、2固定二群，不會出現「二、比較結構」（群組數量／比較方式）欄位；情境3、4可能二群或三群，才會多出這段。「略過」整份表單的選項四種情境皆可使用
+- **不套用「對話＋上傳合併」邏輯**：欄位量大（原文資訊5欄＋群組層表格＋個體層表格，情境3/4再加2欄），不適合塞進聊天氣泡或合併輸入框
+- **維持獨立表單卡片**，佔滿右欄全寬，位於對話視窗下方（同頁面往下捲動關係，**非 dialog／彈出視窗**，已實機截圖驗證）
+- 群組層／個體層表格**維持現有 Dataframe 元件不變**（先前曾提議改成卡片式已收回：現有元件已內建全螢幕展開編輯功能，且卡片式無法應對 20–30 組的規模）
+- 章節數字編號（一、二、三、四）拿掉，改純文字標題（見 Bug 清單）
+- 「略過」文案定稿：「以下資訊會寫入報告開頭，您也可以先略過（略過後這次分析將不會用到這些補充說明）」
+
+## 八、持久化機制（方案 D：進度存檔／讀檔）
+
+不做登入、不做 server 端多 session 儲存。理由：避免資安疑慮（無登入代表任何人拿到 session 網址都能看到他人資料）、避免與現有 Gradio session 架構衝突。
+
+| 機制 | 說明 |
+|---|---|
+| 防手滑 | `beforeunload` 事件，離開頁面前跳出確認 |
+| 中途下載 | 任一步驟完成即可下載當前已產出的部分成果 |
+| **存檔／讀檔** | 核心機制。存檔內容**含原始上傳文本**（不只中繼結果），確保讀檔後完整還原、不用重新上傳；讀取進度入口在首頁，讀檔後直接跳過首頁回到中斷步驟 |
+| 檔名／格式區分 | 存檔用自訂副檔名（如 `.spectra`），次要按鈕樣式＋警語；成果下載才用一般格式＋醒目主色按鈕，避免非技術使用者誤認「中繼存檔＝最終成果」 |
+| 多開分析 | 不需特別開發——開新分頁天生是獨立 session（Gradio `session_hash` 機制）；僅需在首次進站提示註明「建議同時只跑一個分析，以確保運算速度」（避免多分頁同時佔用運算資源） |
+
+## 九、下載機制與命名
+
+| 下載項目 | 內容 | 格式 | 命名 | 出現時機 |
+|---|---|---|---|---|
+| 下載指標數據 | 75項指標原始數值（工作底稿） | xlsx + csv | 「下載指標數據」 | 指標計算完成即可，不用等全部結束 |
+| 下載完整報告 | LLM生成研究報告本文 | docx + txt | 「下載完整報告」 | 全案完成才出現（**本次先做假按鈕，不接真正zip打包，見缺口1**） |
+
+⚠️ 兩者性質完全不同（數據 vs 報告），且**出現時機不同**，UI 互動邏輯不可誤設計成兩顆按鈕同時解鎖。
+
+## 十、Footer／設定／API 處理
+
+| 項目 | 決策 |
+|---|---|
+| 透過 API 使用 | 保留（技術文件用途），低視覺權重 |
+| 使用 Gradio 建構 | **不保留**。技術做法：`app.launch(footer_links=["api","settings"])`（Gradio 6.20.0 官方原生支援，非 CSS hack，無授權疑慮） |
+| 設定 | 整個面板保留，不拿掉任何子項（語言下拉／PWA提示／Screen Studio錄影工具都留著；其中僅「顯示主題」Light/Dark/System 為常用項） |
+| 呈現方式 | 不做懸停展開子選單（觸控裝置無 hover 狀態）；低視覺權重靜態呈現，置底 |
+| 技術備註 | API文件面板與設定面板是 Gradio 原生元件，會自動套用現有 `gr.themes.Base` 主題色，不需逐畫面客製設計 |
+
+## 十一、視覺規範
+
+- **全站基礎字級統一 14px**（`0.875rem`）：現況內文字級散亂寫死在 0.78–0.84rem 各處、無統一變數，改法是在 CSS Tokens 區塊定義 `--font-size-base: 0.875rem` 共用變數；標題與小徽章/步驟列不在統一範圍內，屬純 CSS 整理、風險低
+
+### 11.1 風格方向（與 UI/UX Pro Max Skill 協作結論，2026-07-20）
+- **對話區**（左側導覽＋對話串＋輸入框）：參考 **AI-Native UI** 風格——訊息泡泡、打字中三點跳動動畫、串流文字顯示，直接對應報告撰寫等待期間的載入體感需求
+- **結果分頁**（表格／圖表區）：參考 **Data-Dense Dashboard** 風格——多圖表/資料表並存、緊湊排版、最大化資訊密度，對應75項指標表格與4種統計圖表的呈現需求
+
+### 11.2 字體
+- **英文／數字**：Crimson Pro（學術感、研究工具調性）
+- **中文本文**：維持現有 **Noto Sans TC**（Skill 的字體資料庫為西文導向，不含中文字體，此為千卉判斷後的中西混搭決定，非 Skill 資料庫建議）
+
+### 11.3 配色——維持現有雙主題系統，不重新設計
+業主上一版已建立完整淺色／深色雙主題 token（sky＋indigo＋slate 系），經 WCAG 對比度驗算後確認品質良好，**本次改版不更換配色，只驗證與微調用法**：
+
+| | 淺色模式 | 深色模式 |
+|---|---|---|
+| 背景 | `#f8fafc` | `#020617` |
+| 主要文字對比度 | 約 14:1 | 約 14:1（同等優異） |
+| 一般強調色 `--c-accent`（按鈕/圖示/大字用） | `#0284c7`，約 4.09:1 | `#0ea5e9`，約 6.58:1 |
+| 加強強調色 `--c-accent-strong`（小字/連結文字用） | `#0369a1`，約 5.93:1 | 同等更高 |
+
+⚠️ **微調重點**：淺色模式的一般強調色 `#0284c7` 若直接用於一般大小的內文文字，對比度 4.09:1 略低於 WCAG AA 的 4.5:1 門檻（但用於按鈕/圖示/大字等允許 3:1 門檻的地方完全合格）。系統已內建 `--c-accent-strong`（`#0369a1`，5.93:1）供小字/連結使用，改版時**須確認一般強調色與加強強調色的使用場景沒有混用**，不需要新增變數，只是用法要正確對應。
+
+## 十二、既有架構限制（改版時不可誤改壞）
+
+- 4 個情境（人機對比／全譯vs編譯／譯者風格／歷時重譯）共用同一組步驟數，情境間步驟數一致，頂部步驟列可通用
+- 但同一步驟內部依情境分支：
+  - 情境1/2固定二群、情境3/4可二群或三群
+  - 語料Metadata表單情境3/4會多出「群組數量」「比較方式」欄位
+  - 統計分析依群組數用不同效果量算法（Cohen's d vs Eta squared）
+  - 報告撰寫依情境套用不同分析角度模板（SCENARIO_MODULE_1~4）
+  - → **Metadata表單這步不能設計成4情境長相完全一樣**
+
+## 十三、空狀態／極限狀態／錯誤狀態設計規劃
+
+### 13.1 空狀態（Empty States）
+| 情境 | 設計方向 |
+|---|---|
+| 首頁初訪（尚未選情境） | 單欄置中大標題＋4情境卡片＋讀取進度次要連結（見五之5.1） |
+| 結果分頁在分析尚未開始時 | 現有已有 `_EMPTY_HINT` 元件（置中圖示＋提示文字，內容近似「尚未產生資料／請先於主頁完成分析流程」），**沿用現有設計**，只需適配新版面（右欄／左側結果導覽）位置 |
+| 左側「結果導覽」在分析未開始前 | 整段不顯示（已決定，見六之6.2） |
+| 讀取進度但尚無任何存檔可讀（新功能首次使用） | 需設計提示文案；使用者第一次使用本系統不會有任何存檔，按下「讀取進度」前應清楚說明這是「上傳先前下載的存檔」，不是「系統幫你保存的雲端紀錄」 |
+
+### 13.2 極限狀態（Extreme States）
+| 情境 | 設計方向 |
+|---|---|
+| 上傳檔案數量極多（20–30 個群組） | 維持 Dataframe 元件（已內建全螢幕展開編輯），見七 |
+| **上傳檔案數量過少（單一檔案、或某組缺漏）** | 見 Bug 3：目前格式驗證未檢查「每組至少幾個檔案」，會導致統計分析分群運算真的失敗。**建議格式驗證階段就攔截**，並非只在結果端顯示失敗狀態即可 |
+| 完全沒有顯著指標（差異性分析 `sig_count=0`） | 現有邏輯 `if len(sig_df) > 0` 才產生箱形圖，無顯著指標時不產生圖片；**需設計對應的空狀態提示**（例如「本次分析未發現統計顯著的指標差異」），不要讓畫面留白讓使用者以為是系統壞掉 |
+| 報告內容極長 | 舒適閱讀排版＋下載按鈕固定定位（已決定，見六之6.4） |
+| 情境卡片標題／說明文字過長 | 首頁卡片版型需保留彈性，避免長文案破版 |
+
+### 13.3 錯誤狀態（Error States）
+| 情境 | 狀態 |
+|---|---|
+| 格式驗證失敗 | 已列入 Bug 2，本次修正 |
+| 情境無法變更 | 已列入 Bug 1，本次修正 |
+| 指標計算／統計分析失敗 | 已列入 Bug 3（新增步驟列第四種視覺狀態），本次修正，且已確認為真實可觸發 |
+| LLM 報告撰寫失敗 | 現有已有優雅降級處理（提示「其他分析結果仍可下載」），**沿用現有邏輯** |
+| 讀取進度檔案毀損或格式不符 | **新功能，尚無現成邏輯**，需設計對應錯誤訊息（例如「這個檔案看起來不是有效的進度存檔，請確認檔案是否正確」），並讓使用者能重新選擇檔案或改為開始新分析 |
+| LLM API 金鑰未設定／呼叫逾時 | 現有已有 try/except 文字降級訊息，**沿用現有機制**即可，不需額外設計 |
+
+## 十四、待業主確認的範圍清單（影響工作量估計，需業主拍板）
+
+1. 「下載完整報告」是否要做真正的 zip 整包後端邏輯（本次僅做假按鈕）
+2. 是否要做「Metadata 略過後事後回來補填」功能（本次不做，只調整文案）
+3. Session 輸出目錄的清理機制（維運層面，非 UI/UX 範圍，但影響 Hugging Face Space 長期磁碟空間）
+4. 是否要加入致理科技大學品牌／校徽識別（目前系統僅有 SpectraEngine 自身品牌，無委託單位識別）
+5. 是否要設定上傳檔案大小上限（目前無任何限制，異常巨大檔案可能拖慢運算或超出 Gradio 上傳限制），不急迫，可延後決定
+
+## 十五、更新紀錄
+
+| 日期 | 修改摘要 |
+|---|---|
+| 2026-07-20 | 初版建立：專案背景、技術限制、Bug 1-2、資訊架構、版面配置、Metadata 表單、持久化機制（方案D）、下載機制、Footer/設定/API處理、視覺規範（14px字級）、既有架構限制 |
+| 2026-07-20 | 新增 Bug 3（步驟列失敗視覺狀態，已確認真實可觸發）＋上傳驗證強化（檔名字首合法性／每組檔案數下限／Metadata群組數一致性）；新增十三章空狀態/極限狀態/錯誤狀態規劃；新增十四章待業主確認清單 |
+| 2026-07-20 | 「監督式學習」「非監督式學習」補下載按鈕確認要做（移出待業主清單），命名定為「下載監督式學習」／「下載非監督式學習」；格式驗證每組檔案數下限確認為既有缺陷修正、非待業主確認事項；精簡缺口3內容；補充 Metadata 表單四種情境皆會出現、差異僅在內容的說明 |
+| 2026-07-20 | 開始與 UI/UX Pro Max Skill 協作視覺設計：確定風格方向（對話區參考AI-Native UI、結果分頁參考Data-Dense Dashboard）、字體（英文數字Crimson Pro＋中文維持Noto Sans TC）、配色（維持業主既有雙主題系統，WCAG對比度驗算通過，不重新設計） |
+
+---
+
+*本文件會隨協作進度持續更新，最新版本以此檔案為準；每次重大修改請同步更新上方「最後更新日期」與本章節。*