un2266 commited on
Commit
6afdd75
·
1 Parent(s): b9619ff

文件同步:補記 4 項導覽掛載與下載時序修復(commit 56a8c3b)

Browse files

修復項目由 15 項增為 19 項,2.2 由 4 項增為 8 項:開始研究分析後
左側導覽列消失、硬點技術執行紀錄內容區塊空白、技術執行紀錄缺大
標題、下載研究報告/完整分析資料在報告撰寫完成前提早出現缺件。
3.1 打包下載機制規則同步更新,程式碼行號一併校正。

docs/UIUX優化成果與技術說明.md CHANGED
@@ -1,7 +1,7 @@
1
  # 譯彩紛呈 II 分析引擎 SpectraEngine UI/UX 優化成果與技術說明
2
 
3
  - 文件建立日期:2026-07-20
4
- - 最後更新日期:2026-08-06(全文重整為成果導向架構,對應 commit `f8aab79`)
5
  - 專案委託方:致理科技大學應日系 鄧敏君老師
6
  - 專案執行:利他設計工作室 吳千卉
7
  - 用途:說明本次 UI/UX 優化執行的工作項目,並保留設計規範與技術決策,供後續工程接手參考
@@ -13,7 +13,7 @@
13
  | 章節 | 這一章做了什麼 |
14
  |---|---|
15
  | **一、專案說明** | 系統定位、本次施工的技術限制、以及不可誤改的既有架構。動手前該知道的事都在這裡 |
16
- | **二、修復既有問題** | 修好 **15 個**原本就存在的問題,分三類:6 個會讓使用者卡死、只能重整頁面的;4 個畫面顯示與實際狀態不符的;5 個看得出來不對的視覺與可讀性瑕疵 |
17
  | **三、功能新增與調整** | 新增四顆打包下載捷徑(原本要跑三個分頁下載 15 個檔案)、補齊兩個統計子頁缺少的下載入口、加上離開頁面前的防手滑確認、移除畫面底部的多餘連結列 |
18
  | **四、設計規範** | 這次改版怎麼決定畫面長相:資訊架構、三欄式版面、語料說明表單、視覺規範(字級、字體、配色與 WCAG 稽核)、各種空白與錯誤狀態,以及本次另外交付的 `design.md` 設計系統文件 |
19
  | **五、未完成項目** | **8 項**經評估超出本次委託範圍、或需要業主決定的項目。每項在此僅簡述,完整技術評估見《開發優化建議》 |
@@ -55,7 +55,7 @@
55
 
56
  ---
57
 
58
- ## 二、修復既有問題(15 項)
59
 
60
  ### 2.1 流程卡住,必須重整頁面才能繼續(6 項)
61
 
@@ -103,7 +103,7 @@
103
 
104
  commit `bd3ee2c`
105
 
106
- ### 2.2 畫面顯示與實際狀態不符(4 項)
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
- - 內容為空的那一包不會產生,對應按鈕就不出現。例如 LLM 報告產製失敗時,「下載研究報告」不會亮出來
 
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` |