Spaces:
Sleeping
Sleeping
文件同步:補記 4 項導覽掛載與下載時序修復(commit 56a8c3b)
Browse files修復項目由 15 項增為 19 項,2.2 由 4 項增為 8 項:開始研究分析後
左側導覽列消失、硬點技術執行紀錄內容區塊空白、技術執行紀錄缺大
標題、下載研究報告/完整分析資料在報告撰寫完成前提早出現缺件。
3.1 打包下載機制規則同步更新,程式碼行號一併校正。
- docs/UIUX優化成果與技術說明.md +35 -7
docs/UIUX優化成果與技術說明.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
| 1 |
# 譯彩紛呈 II 分析引擎 SpectraEngine UI/UX 優化成果與技術說明
|
| 2 |
|
| 3 |
- 文件建立日期:2026-07-20
|
| 4 |
-
- 最後更新日期:2026-08-06(
|
| 5 |
- 專案委託方:致理科技大學應日系 鄧敏君老師
|
| 6 |
- 專案執行:利他設計工作室 吳千卉
|
| 7 |
- 用途:說明本次 UI/UX 優化執行的工作項目,並保留設計規範與技術決策,供後續工程接手參考
|
|
@@ -13,7 +13,7 @@
|
|
| 13 |
| 章節 | 這一章做了什麼 |
|
| 14 |
|---|---|
|
| 15 |
| **一、專案說明** | 系統定位、本次施工的技術限制、以及不可誤改的既有架構。動手前該知道的事都在這裡 |
|
| 16 |
-
| **二、修復既有問題** | 修好 **
|
| 17 |
| **三、功能新增與調整** | 新增四顆打包下載捷徑(原本要跑三個分頁下載 15 個檔案)、補齊兩個統計子頁缺少的下載入口、加上離開頁面前的防手滑確認、移除畫面底部的多餘連結列 |
|
| 18 |
| **四、設計規範** | 這次改版怎麼決定畫面長相:資訊架構、三欄式版面、語料說明表單、視覺規範(字級、字體、配色與 WCAG 稽核)、各種空白與錯誤狀態,以及本次另外交付的 `design.md` 設計系統文件 |
|
| 19 |
| **五、未完成項目** | **8 項**經評估超出本次委託範圍、或需要業主決定的項目。每項在此僅簡述,完整技術評估見《開發優化建議》 |
|
|
@@ -55,7 +55,7 @@
|
|
| 55 |
|
| 56 |
---
|
| 57 |
|
| 58 |
-
## 二、修復既有問題(
|
| 59 |
|
| 60 |
### 2.1 流程卡住,必須重整頁面才能繼續(6 項)
|
| 61 |
|
|
@@ -103,7 +103,7 @@
|
|
| 103 |
|
| 104 |
commit `bd3ee2c`
|
| 105 |
|
| 106 |
-
### 2.2 畫面顯示與實際狀態不符(
|
| 107 |
|
| 108 |
這四個問題的共通點是:系統實際狀態與畫面呈現的不一樣,使用者被誤導。
|
| 109 |
|
|
@@ -129,6 +129,32 @@ LLM 報告撰寫失敗時,原本只 yield 一則 WARNING 進技術執行紀錄
|
|
| 129 |
|
| 130 |
修法:`_EMPTY_HINT`(app_agent.py:1837)文案改為「請先於『AI對話』完成分析流程」。
|
| 131 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 132 |
### 2.3 視覺與可讀性(5 項)
|
| 133 |
|
| 134 |
**① 語料說明表單章節編號跳號**
|
|
@@ -174,14 +200,15 @@ LLM 報告撰寫失敗時,原本只 yield 一則 WARNING 進技術執行紀錄
|
|
| 174 |
|
| 175 |
規則:
|
| 176 |
|
| 177 |
-
- 指標計
|
| 178 |
-
-
|
|
|
|
| 179 |
- 只有一組有內容時不另外產生「完整分析資料」,避免兩顆按鈕內容一模一樣讓使用者猶豫該點哪個
|
| 180 |
- zip 內容與各結果頁提供的下載檔案完全一致(含檔名改名規則),不含僅供畫面顯示的中間產物
|
| 181 |
|
| 182 |
**命名沿革**:整包那顆原先叫「下載完整報告」,與「下載研究報告」字面過於接近,非技術使用者分不清哪個才是報告本文,2026-07-24 實機檢視後改為「下載完整分析資料」。
|
| 183 |
|
| 184 |
-
commit `8ac93d8`、`bd2428a`
|
| 185 |
|
| 186 |
### 3.2 統計子頁下載入口補齊
|
| 187 |
|
|
@@ -556,3 +583,4 @@ commit `d928c91`
|
|
| 556 |
| 2026-08-06 | 逐項對照程式碼校正 4.1–4.5:對話區塊與內容區塊拆為兩節(實際為三欄,結果頁收成二欄);移除從未實作的常駐情境標籤敘述;步驟列顯示條件由「完成後隱藏」更正為「只在 AI 對話頁顯示」;左側導覽版面圖改為八項平級並補圖示對照表;對話輸入框補註已實作但隱藏;結果分頁排版改為逐頁列出實際元件順序 |
|
| 557 |
| 2026-08-06 | 修正兩處導覽改名後未同步的文案並列入第二章,修復項目由 13 項增為 15 項:空狀態提示指向不存在的「主頁」(改為「AI對話」)、結果頁下載鈕命名不一致(統一為「下載+該頁名稱」)|
|
| 558 |
| 2026-08-06 | 《開發優化建議》原第七節底下的兩個子項提升為第七、第八節,使兩份文件的未完成項目由「8 項對 6 節+2 子項」變為「8 項對 8 節」,對照時不再需要換算層級;本文件 5.7/5.8 的指向同步更新 |
|
|
|
|
|
|
| 1 |
# 譯彩紛呈 II 分析引擎 SpectraEngine UI/UX 優化成果與技術說明
|
| 2 |
|
| 3 |
- 文件建立日期:2026-07-20
|
| 4 |
+
- 最後更新日期:2026-08-06(新增 4 項導覽掛載/下載時序修復,對應 commit `56a8c3b`)
|
| 5 |
- 專案委託方:致理科技大學應日系 鄧敏君老師
|
| 6 |
- 專案執行:利他設計工作室 吳千卉
|
| 7 |
- 用途:說明本次 UI/UX 優化執行的工作項目,並保留設計規範與技術決策,供後續工程接手參考
|
|
|
|
| 13 |
| 章節 | 這一章做了什麼 |
|
| 14 |
|---|---|
|
| 15 |
| **一、專案說明** | 系統定位、本次施工的技術限制、以及不可誤改的既有架構。動手前該知道的事都在這裡 |
|
| 16 |
+
| **二、修復既有問題** | 修好 **19 個**原本就存在的問題,分三類:6 個會讓使用者卡死、只能重整頁面的;8 個畫面顯示與實際狀態不符的;5 個看得出來不對的視覺與可讀性瑕疵 |
|
| 17 |
| **三、功能新增與調整** | 新增四顆打包下載捷徑(原本要跑三個分頁下載 15 個檔案)、補齊兩個統計子頁缺少的下載入口、加上離開頁面前的防手滑確認、移除畫面底部的多餘連結列 |
|
| 18 |
| **四、設計規範** | 這次改版怎麼決定畫面長相:資訊架構、三欄式版面、語料說明表單、視覺規範(字級、字體、配色與 WCAG 稽核)、各種空白與錯誤狀態,以及本次另外交付的 `design.md` 設計系統文件 |
|
| 19 |
| **五、未完成項目** | **8 項**經評估超出本次委託範圍、或需要業主決定的項目。每項在此僅簡述,完整技術評估見《開發優化建議》 |
|
|
|
|
| 55 |
|
| 56 |
---
|
| 57 |
|
| 58 |
+
## 二、修復既有問題(19 項)
|
| 59 |
|
| 60 |
### 2.1 流程卡住,必須重整頁面才能繼續(6 項)
|
| 61 |
|
|
|
|
| 103 |
|
| 104 |
commit `bd3ee2c`
|
| 105 |
|
| 106 |
+
### 2.2 畫面顯示與實際狀態不符(8 項)
|
| 107 |
|
| 108 |
這四個問題的共通點是:系統實際狀態與畫面呈現的不一樣,使用者被誤導。
|
| 109 |
|
|
|
|
| 129 |
|
| 130 |
修法:`_EMPTY_HINT`(app_agent.py:1837)文案改為「請先於『AI對話』完成分析流程」。
|
| 131 |
|
| 132 |
+
**⑤ 「開始研究分析」進入研究選擇畫面後,左側導覽列消失只剩「開始新分析」**
|
| 133 |
+
|
| 134 |
+
Python 端在 `on_start_analysis_show`(app_agent.py:3625)確實送出了 `result_nav_col` 的 `visible=True` 更新,但實測發現前端完全沒把這批導覽按鈕(AI對話/語言指標分析/⋯/技術執行紀錄)掛進 DOM。根因是 Gradio 6 的一個行為特性:元件**第一次**從 `visible=False` 翻成 `True`(此生第一次掛進 DOM)時,只有在觸發它的 generator 的**第一個** yield 裡設定才會真的生效;原本的寫法比照另一段既有的還原值修法(見「4-C 補償」相關註解)把這批更新延到第二個 yield 才送出,套錯了修法——那套「延一個 yield」處理的是另一種問題(曾經顯示過的元件被 Gradio 自動還原成舊值),不適用在「這輩子第一次要顯示」的元件上。
|
| 135 |
+
|
| 136 |
+
修法:把 `result_nav_col` 的 `visible=True` 搬到第一個 yield,比照 `on_scenario_pick`(app_agent.py:3727)已驗證可行的寫法。
|
| 137 |
+
|
| 138 |
+
**⑥ 硬點「技術執行紀錄」,右側內容區塊一片空白**
|
| 139 |
+
|
| 140 |
+
與⑤同一根因:`canvas_exec_col`(技術執行紀錄的內容容器)同樣被延到第二個 yield 才設 `visible=True`,導致從未掛進 DOM。這顆導覽按鈕本身在建構時刻意不設 `interactive=False`(設計意圖是「從第一秒就有內容可看」,不像其他結果頁要等運算完成才能點),所以使用者在研究選擇階段點下去,點得動、但內容區塊是空的。
|
| 141 |
+
|
| 142 |
+
修法:`canvas_exec_col` 與 `result_nav_col` 一併搬到第一個 yield。
|
| 143 |
+
|
| 144 |
+
**⑦ 技術執行紀錄頁沒有大標題**
|
| 145 |
+
|
| 146 |
+
其他三個結果頁(語言指標分析/敘述統計/研究報告)的標題文字,是每次 `_populate_tabs` 重新賦值時烤進內容字串裡的(例如 `"### 語言指標分析\n共 ..."`),屬於一次性結果、整段換新。但技術執行紀錄是逐行往下累加的執行 log(見 `_log_append`,app_agent.py:3183),內容從不整段重寫,因此從沒有機會把標題烤進去,這是設計之初就存在的缺口,不是後來才壞掉的。
|
| 147 |
+
|
| 148 |
+
修法:在 `canvas_exec_col`(app_agent.py:3126)內補上一顆獨立的靜態 `gr.Markdown("### 技術執行紀錄")`,與逐行累加的 log 內容分開,不受累加邏輯影響。
|
| 149 |
+
|
| 150 |
+
**⑧ 「下載研究報告」「下載完整分析資料」在 LLM 報告還沒寫完就提��出現,內容缺件**
|
| 151 |
+
|
| 152 |
+
分析運算的三個子階段(指標計算/統計分析/報告撰寫)中,「敘述統計技術報告」(`Final_Report-*.docx`)在統計分析子階段一結束就會產生,早於報告撰寫子階段真正完成。`_populate_tabs`(app_agent.py:3190)判斷這兩顆下載捷徑是否亮起時,只看檔案存不存在,沒有等報告撰寫子階段真正結束,導致統計分析一做完,這兩顆按鈕就提早亮起,使用者這時下載,拿到的 zip 只有統計技術報告、缺 LLM 報告本文。
|
| 153 |
+
|
| 154 |
+
修法:改成等 `state["analysis"]["report"]["status"]` 到達終態(`done` 或 `failed`,不再是 `running`)才決定要不要生成與顯示這兩顆按鈕;報告若最終失敗,仍讓使用者能拿到統計技術報告,不會被永久卡住拿不到任何東西。個別的「下載指標數據」「下載統計圖表」不受影響,維持各子階段一完成就能拿,見 3.1 規則更新。
|
| 155 |
+
|
| 156 |
+
⑤⑥⑦⑧ commit `56a8c3b`
|
| 157 |
+
|
| 158 |
### 2.3 視覺與可讀性(5 項)
|
| 159 |
|
| 160 |
**① 語料說明表單章節編號跳號**
|
|
|
|
| 200 |
|
| 201 |
規則:
|
| 202 |
|
| 203 |
+
- 「下載指標數據」「下載統計圖表」各自對應的子階段一跑完即可下載,不必等全部結束
|
| 204 |
+
- 「下載研究報告」「下載完整分析資料」**要等報告撰寫子階段跑到終態(成功或失敗,不再是進行中)才會生成與顯示**。這兩顆是「完整成果」的捷徑,若只憑檔案是否存在來判斷,統計分析一做完(早於報告撰寫完成)就會提早亮起,使用者這時下載會拿到缺 LLM 報告本文的 zip(2026-08-06 發現並修復,見 2.2 ⑧)
|
| 205 |
+
- 內容為空的那一包不會產生,對應按鈕就不出現。例如 LLM 報告產製失敗時,「下載研究報告」不會亮出來(仍會在報告撰寫子階段確定失敗後,讓使用者拿到統計技術報告,不是完全沒有下載機會)
|
| 206 |
- 只有一組有內容時不另外產生「完整分析資料」,避免兩顆按鈕內容一模一樣讓使用者猶豫該點哪個
|
| 207 |
- zip 內容與各結果頁提供的下載檔案完全一致(含檔名改名規則),不含僅供畫面顯示的中間產物
|
| 208 |
|
| 209 |
**命名沿革**:整包那顆原先叫「下載完整報告」,與「下載研究報告」字面過於接近,非技術使用者分不清哪個才是報告本文,2026-07-24 實機檢視後改為「下載完整分析資料」。
|
| 210 |
|
| 211 |
+
commit `8ac93d8`、`bd2428a`、`56a8c3b`
|
| 212 |
|
| 213 |
### 3.2 統計子頁下載入口補齊
|
| 214 |
|
|
|
|
| 583 |
| 2026-08-06 | 逐項對照程式碼校正 4.1–4.5:對話區塊與內容區塊拆為兩節(實際為三欄,結果頁收成二欄);移除從未實作的常駐情境標籤敘述;步驟列顯示條件由「完成後隱藏」更正為「只在 AI 對話頁顯示」;左側導覽版面圖改為八項平級並補圖示對照表;對話輸入框補註已實作但隱藏;結果分頁排版改為逐頁列出實際元件順序 |
|
| 584 |
| 2026-08-06 | 修正兩處導覽改名後未同步的文案並列入第二章,修復項目由 13 項增為 15 項:空狀態提示指向不存在的「主頁」(改為「AI對話」)、結果頁下載鈕命名不一致(統一為「下載+該頁名稱」)|
|
| 585 |
| 2026-08-06 | 《開發優化建議》原第七節底下的兩個子項提升為第七、第八節,使兩份文件的未完成項目由「8 項對 6 節+2 子項」變為「8 項對 8 節」,對照時不再需要換算層級;本文件 5.7/5.8 的指向同步更新 |
|
| 586 |
+
| 2026-08-06 | 修復項目由 15 項增為 19 項(2.2 由 4 項增為 8 項):「開始研究分析」後左側導覽列消失、硬點技術執行紀錄內容區塊空白、技術執行紀錄缺大標題、下載研究報告/完整分析資料在報告撰寫完成前提早出現缺件。前三項根因相同:Gradio 6 元件第一次從隱藏翻顯示時,只有在觸發它的 generator 第一個 yield 設定才會真的掛進 DOM,原寫法套錯了另一段既有修法(4-C 補償)延到第二個 yield 才設,改回第一個 yield。3.1 打包下載機制規則同步更新。commit `56a8c3b` |
|