jimmy60504 commited on
Commit
ed6729a
·
1 Parent(s): 1628958

docs: update copilot instructions and project plan for improved workflow and user experience

Browse files
.github/copilot-instructions.md CHANGED
@@ -132,27 +132,50 @@ commit 前確認以下兩點:
132
  2. 根據需求類型,讀取相應的 spec 模塊(`01-*` / `02-*` / `03-*` / `04-*`)。
133
  3. LLM 掃描現有程式碼,列出符合、缺漏、或違反的地方。
134
  4. 產出「需要做的工作清單」。
135
- 5. 確認後更新相應 spec 模塊,根據清單建立 `spec/plan.md` 作為後續執行的輸入。
136
 
137
- ### `/project.plan`(迭代開發時用)
138
- - **目的**:根據 `spec/plan.md` 拆解本次迭代的任務,指導程式碼實作。
139
  - **流程**:
140
- 1. 基於 plan.md 的目標,讀取對應的 spec 模塊(如「新增 CSV 欄位」→ `01-data-contract.md` + `04-extensions.md`)。
141
- 2. 產出編號任務清單與驗收標準。
142
- 3. 逐個實作任務,完成後更新 `changelog.md`。
143
- 4. 下次迭代時,舊 plan.md 可拋棄,根據新需求重新開始。
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
144
 
145
  ### 標準工作流
146
 
147
  **當需求改變時:**
148
- 1. 執行 `/project.spec` 討論規格調整 + 程式碼比較 → 讀取相應 spec 模塊。
149
- 2. 確認工作清單後更新對應的 spec 模塊(`00-*` `04-*` 之一)。
150
- 3. 根據清單建立 `spec/plan.md`(定義本次迭代範圍)。
151
 
152
  **執行迭代時:**
153
- 4. 執行 `/project.plan` 根據 plan.md 拆解任務讀取對應 spec 模塊。
154
- 5. 根據任務清單實作,完成後更新 `changelog.md`。
155
- 6. 迭代結束,舊的 plan.md task.md 可拋棄。
 
156
 
157
  **下次需求改變時:** 回到步驟 1。
158
 
 
132
  2. 根據需求類型,讀取相應的 spec 模塊(`01-*` / `02-*` / `03-*` / `04-*`)。
133
  3. LLM 掃描現有程式碼,列出符合、缺漏、或違反的地方。
134
  4. 產出「需要做的工作清單」。
135
+ 5. **直接更新 `spec/spec.md`** 等待使用者確認 → 確認後同步至 `README.md` 和 `spec/plan.md`。
136
 
137
+ ### `/project.plan`(迭代規劃時用)
138
+ - **目的**:生成本次 sprint 的計畫,讓使用者在 MD 上討論和調整。
139
  - **流程**:
140
+ 1. 產生 `spec/plan.md`(包含迭代目標、高層任務列表、風險評估等)
141
+ 2. **暫停等待使用者確認**(用戶可直接在 MD 上編輯)
142
+ 3. 確認後,提示執行 `/project.task` 進行詳細任務拆解
143
+
144
+ ### `/project.task`(任務拆解時用)
145
+ - **目的**:根據確認的 `spec/plan.md`,拆解為具體的任務步驟與程式碼變更點。
146
+ - **流程**:
147
+ 1. 根據 `spec/plan.md` 的高層任務列表,生成詳細任務拆解(T-001、T-002 等)
148
+ 2. 展示每個任務的具體變更點(檔案、行號、修改內容)
149
+ 3. **暫停等待使用者確認**(用戶可調整任務順序或內容)
150
+ 4. 確認後,提示執行 `/project.apply` 應用程式碼變更
151
+
152
+ ### `/project.apply`(程式碼應用時用)
153
+ - **目的**:直接應用經過確認的程式碼變更。
154
+ - **流程**:
155
+ 1. 根據 `spec/task.md` 的確認任務清單,直接應用所有程式碼修改
156
+ 2. 執行語法/編譯檢查
157
+ 3. 更新 `spec/task.md` 標記已完成的任務([x])
158
+ 4. **暫停並提示使用者**:「程式碼已應用,請進行手動測試」
159
+
160
+ ### `/project.report`(交付與清理時用)
161
+ - **目的**:記錄變更並清理臨時計畫檔案。
162
+ - **流程**:
163
+ 1. 根據使用者已完成的測試結果,自動更新 `changelog.md`
164
+ 2. 清理 `spec/plan.md` 和 `spec/task.md`(下次迭代時重新生成)
165
+ 3. 生成交付報告(品質狀態、需求對齐等)
166
+ 4. 提示用戶本次迭代已完成,可開始新迭代
167
 
168
  ### 標準工作流
169
 
170
  **當需求改變時:**
171
+ 1. 執行 `/project.spec` 討論規格調整
172
+ 2. 直接在 `spec/spec.md` 上編輯 確認後同步至 `README.md` 和 `spec/plan.md`
 
173
 
174
  **執行迭代時:**
175
+ 3. 執行 `/project.plan` 生成計畫 → 在 `spec/plan.md` 上編輯確認後執行 `/project.task`
176
+ 4. 執行 `/project.task` 拆解任務 → 在 `spec/task.md` 上編輯 → 確認後執行 `/project.apply`
177
+ 5. 執行 `/project.apply` 直接應用程式碼 → 手動測試 → 測試完成後執行 `/project.report`
178
+ 6. 執行 `/project.report` 記錄變更 + 自動清理 plan 和 task
179
 
180
  **下次需求改變時:** 回到步驟 1。
181
 
.github/prompts/project.apply.prompt.md CHANGED
@@ -1,30 +1,45 @@
1
- # /project.apply — 選擇與啟動任務
2
 
3
  目的
4
- - 根據使用者在 `/project.task` 中的選擇,更新 `spec/task.md` 的 checklist。
5
- - 將使用者選中的 task 標記為要執行的狀態。
6
-
7
- 輸入(由提問者提供)
8
- - 想要執行的 task 編號清單(例如:T-001, T-003, T-005)
9
- - 任何想要排除或延後的 task
10
- - 對 task 的微調或補充(若有)
11
-
12
- 自動執行
13
- 1. 根據使用者選擇的編號清單,在 `spec/task.md` 中:
14
- - 為選中的 task 對應的 checklist 項目添加勾選標記 `[x]`
15
- - 為未選中的 task 保留空勾選 `[ ]`(表示待定或排除)
16
- 2. 保持 task 的描述、驗收標準等內容不變
17
- 3. 編號標記(T-001 等)不寫入 `spec/task.md`,僅在此步驟用於選擇
18
-
19
- 請輸出
20
- - 更新後的 `spec/task.md`(顯示哪些 task 被標記為 `[x]`)
21
- - 摘要說明:
22
- - 共有 X 個 task 被選中執行
23
- - 共有 Y 個 task 被延後或排除
24
- - 提示使用者已準備好,可進行 `/project.report`(若所有 task 已完成)或開始實作
25
-
26
- 守則
27
- - 編號(T-001 等)僅用於此步驟的選擇介面,不進入 `spec/task.md` 的實際內容。
28
- - 只更新 `spec/task.md` 的 checklist 標記,不修改 task 的其他內容。
29
- - 使用者可隨時回到 `/project.task` 重新調整。
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
30
 
 
1
+ # /project.apply — 應用程式碼變更
2
 
3
  目的
4
+ - 根據使用者在 `/project.task` 中確認的任務,直接應用具體的程式碼變更。
5
+ - 更新 `spec/task.md` 標記已完成的任務。
6
+ - 等待使用者手動測試,測試完成後執行 `/project.report`。
7
+
8
+ 輸入
9
+ - 使用者確認的任務拆解清單(來自 `/project.task`)
10
+
11
+ 流程
12
+
13
+ ### 自動執行
14
+
15
+ 1. **直接應用程式碼變更**
16
+ - 根據 `spec/task.md` 的任務清單,應用所有程式碼修改
17
+ - 使用 `replace_string_in_file` 或 `insert_edit_into_file` 執行變更
18
+ - 執行相關檢查(語法檢查、編譯檢查等,若適用)
19
+
20
+ 2. **更新 `spec/task.md`**
21
+ - 為已完成的任務標記勾選 `[x]`
22
+ - 保留任務描述和驗收標準
23
+
24
+ ### 暫停點:等待使用者手動測試
25
+
26
+ 1. **提示使用者**:「程式碼已應用,請進行手動測試」
27
+ 2. **等待使用者回饋**:
28
+ - 測試是否通過驗收標準
29
+ - 是否需要調整或修復
30
+ - 測試完成後執行 `/project.report`
31
+
32
+ ### 後續步驟(由使用者執行)
33
+
34
+ 使用者手動測試完成後:
35
+ - 執行 `/project.report` 記錄本次迭代的變更摘要
36
+ - `/project.report` 會自動更新 `changelog.md` 並清理 `spec/plan.md` 和 `spec/task.md`
37
+
38
+ ## 守則
39
+
40
+ - **直接執行**:不需要展示階段或再次確認
41
+ - **精準定位**:所有變更需精確指向檔案、函式、行號
42
+ - **驗證變更**:應用後須檢查語法/編譯正確性
43
+ - **等待測試**:暫停並等待使用者手動測試結果
44
+ - **後續交付**:由 `/project.report` 負責記錄和清理
45
 
.github/prompts/project.plan.prompt.md CHANGED
@@ -15,20 +15,36 @@
15
  請輸出
16
  - 產生 `spec/plan.md` 檔案,內容包含:
17
  - **簡短前置**:需求重述與關鍵假設(若有)。
18
- - **Checklist(最多 7 項)**:
19
- - 要做的子任務(小而可驗收),每項附驗收標準。
 
 
20
  - **Invariants 對齊**:逐條列出是否受影響(Done/Not Impacted/At Risk),並指向 `spec/spec.md` 的相關條目。
21
  - **風險與回滾**:主要風險、緩解、回滾方式(最小可逆)。
22
  - **冒煙測試**:2–4 個步驟,含預期輸出要點。
23
- - 完成後提示使用者檔案已建立,可進行修改後再回覆「核准」或「下一步」。
24
- - 使用者確認後的後續流程:
25
- 1. 根據 plan.md 討論結果更新 `spec/spec.md`(若有新規格需求或不變條件變更)
26
- 2. 根據 plan.md 的 Checklist 產生 `spec/task.md`(任務拆解與驗收標準)
27
- 3. 執行 `/project.task` 列出變更方案與驗收標準
28
- 4. 核准後自行實作變更
29
- 5. 完成後執行 `/project.report` 收斂交付
30
-
31
- 守則
32
- - 產生 `spec/plan.md` 後,不做其他檔案修改或指令執行。
33
- - 若需求可能影響公共行為或 I/O shape,必須在 plan 中標註需先更新 `spec/spec.md`。
 
 
 
 
 
 
 
 
 
 
 
 
 
 
34
  - plan.md 的所有決策必須遵守 spec.md 的全局約束;不可違反或繞過 spec 中定義的不變條件。
 
15
  請輸出
16
  - 產生 `spec/plan.md` 檔案,內容包含:
17
  - **簡短前置**:需求重述與關鍵假設(若有)。
18
+ - **迭代目標**:本次 sprint 要解決什麼問題或新增什麼功能。
19
+ - **範圍**:涉及的模組、檔案、外部依賴。
20
+ - **驗收標準**:本次迭代完成的定義(Definition of Done)。
21
+ - **高層任務列表**:要做的主要工作項(不需詳細拆解,詳細拆解由 `/project.task` 負責)。
22
  - **Invariants 對齊**:逐條列出是否受影響(Done/Not Impacted/At Risk),並指向 `spec/spec.md` 的相關條目。
23
  - **風險與回滾**:主要風險、緩解、回滾方式(最小可逆)。
24
  - **冒煙測試**:2–4 個步驟,含預期輸出要點。
25
+
26
+ ## ⏸️ 暫停點(重要)
27
+
28
+ **完成 `spec/plan.md` 生成後,立即停止,等待使用者確認。**
29
+
30
+ ### 第一階段:討論與確認計畫(直接在 spec/plan.md 上編輯)
31
+
32
+ 1. **直接生成/更新 `spec/plan.md`**
33
+ - 你可以直接在 MD 上進行編輯和調整
34
+ - 修改目標、範圍、任務優先序等
35
+ - 如果改錯了可以直接 discard
36
+
37
+ 2. **完成編輯後**:
38
+ - 回覆「確認」或「核准」
39
+
40
+ ### 第二階段:任務拆解(用戶確認後)
41
+
42
+ 待你確認後:
43
+ 1. **提示你執行 `/project.task`** 來進行詳細的任務拆解與驗收標準
44
+
45
+ ## 守則
46
+
47
+ - **必須遵守暫停點**:產生 `spec/plan.md` 後,等待使用者確認,不進行任何進一步的操作。
48
+ - **允許多輪編輯**:用戶可在 `spec/plan.md` 上任意修改、調整,直到滿意為止。
49
+ - **可安全 discard**:用戶可隨時放棄編輯,discard 檔案變更,無副作用。
50
  - plan.md 的所有決策必須遵守 spec.md 的全局約束;不可違反或繞過 spec 中定義的不變條件。
.github/prompts/project.report.prompt.md CHANGED
@@ -1,18 +1,47 @@
1
- # /project.report — 總結與交付
2
 
3
  目的
4
- - 收斂本次變更的交付物、品質狀態與後續建議。
5
- - 在使用者完成實作與測試後,協助總結成果並更新 `change-log.md`。
6
-
7
- 請輸出
8
- - **變更摘要**(對照 `spec/task.md` 與 `spec/plan.md`)
9
- - **品質門檻**:Build/Lint 狀態、I/O 契約驗證、降級與 logging 覆蓋
10
- - **Requirements coverage**:對照 `spec/spec.md` 的不變條件與需求,標記 Done/Deferred(含原因)
11
- - **使用者體驗變更檢查**:若涉及 UI 行為、功能說明、輸入選項或操作流程的改變,列出需要更新 README 的項目(例如新增欄位、UI 互動邏輯變更、新功能說明等),並提示使用者需同步更新 `README.md` 的「主要功能」或「快速開始」等相關章節
12
- - **建議的 change-log 條目**:格式符合 change-log.md 的記錄標準
13
- - **後續建議**:風險、後續工作、優化空間
14
-
15
- 守則
16
- - 不做檔案修改;由使用者根據報告內容手動更新 `changelog.md` 與 `README.md`。
17
- - 若有 UX 變更,明確提示使用者需要更新 README 的具體章節與內容。
18
- - 完成後提示使用者本次 sprint 交付狀態與下一步建議。
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # /project.report — 交付與清理
2
 
3
  目的
4
+ - 記錄本次迭代的變更摘要到 `changelog.md`
5
+ - 清理臨時計畫檔案(`spec/plan.md` `spec/task.md`)
6
+ - 生成交付報告
7
+
8
+ 輸入
9
+ - 使用者已完成手動測試(來自 `/project.apply` 後的測試階段)
10
+
11
+ 自動執行
12
+
13
+ ### 1. 更新 `changelog.md`
14
+
15
+ - 在 `[Unreleased]` 或最新版本下,根據 `spec/task.md` 生成變更摘要
16
+ - 格式:
17
+ ```markdown
18
+ ### Added/Changed/Fixed
19
+ - **功能名稱或模組**(日期)
20
+ - 具體變更描述(2-3 條要點)
21
+ - 相關檔案簡稱
22
+ ```
23
+
24
+ ### 2. 清理臨時檔案
25
+
26
+ - 刪除 `spec/plan.md`(已完成的迭代計畫)
27
+ - 刪除 `spec/task.md`(已完成的任務拆解)
28
+ - 下次迭代時會重新生成
29
+
30
+ ### 3. 生成交付報告
31
+
32
+ 輸出內容:
33
+ - **變更摘要**:對照 `spec/task.md` 的已完成任務
34
+ - **品質狀態**:
35
+ - Build/Lint 狀態
36
+ - 語法/編譯檢查結果
37
+ - I/O 契約驗證
38
+ - **Requirements 對齐**:對照 `spec/spec.md` 的不變條件
39
+ - **UX 變更檢查**:若有 UI/功能變更,提示需更新 `README.md` 的相關章節
40
+ - **建議的 changelog 條目**:提供文本供參考(已自動寫入)
41
+
42
+ ## 守則
43
+
44
+ - **自動執行更新**:自動更新 `changelog.md` 並清理 plan 和 task 檔案
45
+ - **保留 spec.md**:不刪除 `spec/spec.md`(長期規格保留)
46
+ - **明確提示**:清楚告知已清理哪些檔案
47
+ - **交付完成**:提示本次迭代已交付,可開始新的迭代週期
.github/prompts/project.spec.prompt.md CHANGED
@@ -52,17 +52,45 @@
52
  - 主要風險與回滾建議
53
  - 冒煙測試建議(2–3 個步驟驗證調整是否生效)
54
 
55
- 完成後
56
- - 產生上述四部分內容,展示給使用者
57
- - 使用者確認後的後續流程:
58
- 1. 根據確認結果更新 `spec/spec.md`(新增/修改規格項)
59
- 2. **更新 `README.md`**:將規格調整中的**高層次設計理念、使用者情境、架構思想**同步至 README(確保即使 spec 後續重建,這些核心思想仍得到保留);細節實作內容暫不更新,待任務完成後補充
60
- 3. 根據「工作清單」建立 `spec/plan.md`(定義本次 sprint 範圍)
61
- 4. 執行 `/project.plan` 進行任務拆解與驗收標準
62
- 5. 開始迭代開發
63
-
64
- 守則
65
- - 規格建議基於使用者輸入與現有 `spec/spec.md`;未經確認不做檔案修改。
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
66
  - 程式碼分析需精準定位(檔案、函式、行號),便於快速定位與修改。
67
  - 工作清單應與現有的 `spec/spec.md` 章節結構對應,避免遺漏或重複。
68
  - 若發現規格與程式碼有深層衝突,需明確標註為「需要討論」的項目。
 
52
  - 主要風險與回滾建議
53
  - 冒煙測試建議(2–3 個步驟驗證調整是否生效)
54
 
55
+ ## ⏸️ 暫停點與雙向確認流程(重要)
56
+
57
+ **完成四部分分析後,立即停止,等待使用者評審與確認。**
58
+
59
+ ### 第一階段:評審與確認規格變更(直接在 spec/spec.md 上編輯)
60
+
61
+ 1. **直接更新 `spec/spec.md`**:
62
+ - 應用四部分內容的建議
63
+ - 新增/修改/移除規格項
64
+ - 用戶可直接在 MD 檔案上進行二次調整
65
+
66
+ 2. **用戶進行討論與調整**(在 MD 檔案上):
67
+ - 直接編輯 `spec/spec.md`
68
+ - 調整、新增或移除規格項
69
+ - 修改相關描述或限制
70
+ - 如果改錯了可以直接 discard(無副作用)
71
+
72
+ 3. **完成編輯後**:
73
+ - 用戶回覆「確認」或「核准」
74
+
75
+ 4. **確認後繼續第二階段**
76
+
77
+ ### 第二階段:相關文件同步(用戶確認後)
78
+
79
+ 待用戶確認後,按順序執行:
80
+ 1. **更新 `README.md`**:將規格調整中的**高層次設計理念、使用者情境、架構思想**同步至 README(確保即使 spec 後續重建,這些核心思想仍得到保留);細節實作內容暫不更新,待任務完成後補充
81
+ 2. 根據「工作清單」建立 `spec/plan.md`(定義本次 sprint 範圍)
82
+
83
+ ### 第三階段:後續開發(可選)
84
+
85
+ - 執行 `/project.plan` 進行任務拆解與驗收標準
86
+ - 開始迭代開發
87
+
88
+ ## 守則
89
+
90
+ - **必須遵守暫停點**:更新 `spec/spec.md` 後,等待使用者確認,不主動修改 `README.md` 或建立 `spec/plan.md`。
91
+ - **允許多輪編輯**:用戶可在 `spec/spec.md` 上任意修改、調整,直到滿意為止。
92
+ - **可安全 discard**:用戶可隨時放棄編輯,discard 檔案變更,無副作用。
93
+ - 規格建議基於使用者輸入與現有 `spec/spec.md`;直接在 `spec/spec.md` 上實作,等待確認後再同步其他檔案。
94
  - 程式碼分析需精準定位(檔案、函式、行號),便於快速定位與修改。
95
  - 工作清單應與現有的 `spec/spec.md` 章節結構對應,避免遺漏或重複。
96
  - 若發現規格與程式碼有深層衝突,需明確標註為「需要討論」的項目。
.github/prompts/project.task.prompt.md CHANGED
@@ -1,34 +1,51 @@
1
- # /project.task — 任務清單
2
 
3
  目的
4
- - 根據 `spec/plan.md` 和 `spec/task.md`,列出本 sprint 的編號 task 清單,讓使用者檢查、調整、增減。
5
- - 這是一個檢查與微調階段,使用者可以修改 `spec/task.md` 內容,然後進行 `/project.apply` 選擇要執行的任務。
 
 
 
6
 
7
  請輸出
8
- - **編號 Task 清單**(基於 `spec/task.md` 的 Checklist):
9
- ```
10
- - [ ] T-001: <任務名稱>
11
- - 驗收標準:<具體檢驗方式>
12
- - 受影響檔案:<相對路徑>
13
- - 風險等級:<低/中/高>
14
- - [ ] T-002: <任務名稱>
15
- ...
16
- ```
17
- - **每個 task 的具體變更點**(項目化說明,不貼整段程式碼),含:
18
- - 變更位置(符號/區塊/行為)
19
- - 修改前後行為摘要
 
 
 
20
  - 相關欄位/限制(若有)
21
- - **品質門檻**(整體):
22
- - 公共契約是否有變更
23
- - 降級策略與 log 是否覆蓋
24
-
25
- 完成後
26
- - 提示使用者可以:
27
- - 調整 task 的內容(修改驗收標準、受影響檔案等)
28
- - 增加或移除 task
29
- - 修改 `spec/task.md` 後,回覆「確認」或「下一步」進行 `/project.apply`
30
-
31
- 守則
32
- - 不呼叫任何工具或修改檔案。
33
- - 編號(T-001、T-002 等)僅用於顯示與選擇,不會進入程式碼,不要寫入 spec/task.md 的內容中。
34
- - 若涉及公共契約變更,標註需先確認 `spec/spec.md` 的約束。
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # /project.task — 任務拆解
2
 
3
  目的
4
+ - 根據使用者確認的 `spec/plan.md`,進行詳細的任務拆解與驗收標準。
5
+ - 生成具體的任務步驟清單與程式碼變更點,為後續程式碼應用做準備。
6
+
7
+ 輸入
8
+ - 使用者已確認的 `spec/plan.md`
9
 
10
  請輸出
11
+ - 根據 `spec/plan.md` 的高層任務列表,生成詳細任務拆解:
12
+ - **編號 Task 清單**(T-001、T-002 等)
13
+ ```
14
+ ### T-001: <任務名稱>
15
+ - **描述**:詳細說明這個任務要做什麼
16
+ - **受影響檔案**:列出所有會被修改的檔案(相對路徑)
17
+ - **具體變更點**:
18
+ - 文件1.py (L100-150): 新增函式 xxx()
19
+ - 文件2.md: 更新章節 YYY
20
+ - **驗收標準**:如何檢驗這個任務完成
21
+ - **風險等級**:低/中/高
22
+ ```
23
+
24
+ - **關鍵變更點摘要**(不貼整段程式碼):
25
+ - 每個變更位置、修改前後行為
26
  - 相關欄位/限制(若有)
27
+
28
+ - **品質門檻**:
29
+ - 是否影響公共契約
30
+ - 錯誤處理與日誌覆蓋情況
31
+
32
+ ## ⏸️ 暫停點
33
+
34
+ **完成任務拆解後,等待使用者確認。**
35
+
36
+ - 用戶可在本階段:
37
+ - 確認任務拆解是否合理
38
+ - 調整任務優先序或內容
39
+ - 修改 `spec/task.md` 後回覆「確認」
40
+
41
+ ### 確認後的下一步
42
+
43
+ 待用戶確認後:
44
+ 1. **提示執行 `/project.apply`** 來應用程式碼變更
45
+
46
+ ## 守則
47
+
48
+ - 不直接修改程式碼檔案,只展示變更方案。
49
+ - 編號(T-001 等)僅用於清單,不會寫入 spec 檔案。
50
+ - 若涉及公共契約變更,必須標註需先確認 `spec/spec.md`。
51
+ - 提供精確的檔案位置與行號,便於後續應用。
spec/plan.md CHANGED
@@ -1,54 +1,94 @@
1
- # 迭代計畫 (plan.md) — Sprint Template
2
 
3
- > 本檔案於每個迭代開始時填充,定義本次迭代的範圍、目標與驗收標準。
4
- > 完成後可拋棄;下次迭代時重新建立。
5
 
6
  ## 迭代資訊
7
 
8
  | 項目 | 值 |
9
  |-----|-----|
10
- | Sprint 編號 | 待填 |
11
- | 開始日期 | YYYY-MM-DD |
12
- | 預計結束日期 | YYYY-MM-DD |
13
- | 負責人 | 待填 |
14
 
15
  ## 迭代目標 (Goal)
16
 
17
- (簡述本次迭代要解決什麼問題或新增什麼功能)
18
 
19
- 示例:
20
- - 修復波形補零邏輯,確保不足 30 秒時正確補齊至 3000 samples
21
- - 新增遠端 Vs30 查詢備用方案
22
- - 改進 UI 地圖高度管理
23
 
24
  ## 範圍 (Scope)
25
 
26
- (本次迭代涉及哪些模組、檔案、外部依賴)
27
-
28
  | 模組 | 涉及檔案 | 變更類型 |
29
  |-----|--------|---------|
30
- | 待填 | `app.py` | bugfix / feature / refactor |
 
31
 
32
  ## 驗收標準 (Acceptance Criteria)
33
 
34
- (本次迭代完成的定義 Definition of Done)
35
-
36
- - [ ] 所有任務完成且代碼測試通過
37
- - [ ] 相關規格文件 (spec/*.md) 已同步更新
38
- - [ ] changelog.md 已記錄變更摘要
39
- - [ ] 無新增 WARNING/ERROR 日誌(除非預期)
40
 
41
  ## 任務拆解 (Tasks)
42
 
43
- (根據目標拆解成具體實作任務;參考 `spec/task.md` 範本)
44
-
45
- ### 任務 1: [功能名稱]
46
- - **描述**:待填
47
- - **涉及檔案**:`app.py`(L100-150)
48
- - **估時**:X hours
49
- - **驗收**:
50
- - [ ] 代碼實作完成
51
- - [ ] 相關 spec 更新
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
52
  - [ ] 測試通過
53
 
54
  ### 任務 2: [功能名稱]
 
1
+ # 迭代計畫 (plan.md) — 波形地圖自動載入改進
2
 
3
+ > 本次迭代優化 UI 流程,使波形地圖在應用啟動與事件切換時自動載入,提升使用體驗。
 
4
 
5
  ## 迭代資訊
6
 
7
  | 項目 | 值 |
8
  |-----|-----|
9
+ | Sprint 編號 | 001 |
10
+ | 開始日期 | 2025-10-26 |
11
+ | 預計結束日期 | 2025-10-26 |
12
+ | 負責人 | 使用者 |
13
 
14
  ## 迭代目標 (Goal)
15
 
16
+ **提升波形地圖的可用性與互動流程**
17
 
18
+ - 應用啟動時,自動載入預設地震事件的波形地圖(選定測站分布 + 波形圖)
19
+ - 使用者切換地震事件時,同步自動更新波形地圖,無需手動點擊「載入波形」按鈕
20
+ - 優化使用者體驗,減少操作步驟
 
21
 
22
  ## 範圍 (Scope)
23
 
 
 
24
  | 模組 | 涉及檔案 | 變更類型 |
25
  |-----|--------|---------|
26
+ | UI 工作流 | `app.py`(Gradio Blocks 事件綁定) | feature / refactor |
27
+ | 無規格變更 | - | N/A |
28
 
29
  ## 驗收標準 (Acceptance Criteria)
30
 
31
+ - [x] 應用啟動時,預設地震事件的波形地圖自動顯示
32
+ - [x] 選擇不同地震事件時,波形地圖同步自動更新
33
+ - [x] 「載入波形」按鈕保留可用,允許使用者手動重新載入
34
+ - [x] 實際觀測震度圖亦在事件切換時同步更新
35
+ - [x] 無新增 WARNING/ERROR 日誌
 
36
 
37
  ## 任務拆解 (Tasks)
38
 
39
+ ### 任務 1: 在 Gradio 初始化時自動載入預設地震事件的波形
40
+ - **描述**:於 Gradio Blocks 定義後,新增 `on_load` 事件,使應用啟動時自動調用 `load_and_display_waveform()`
41
+ - **涉及檔案**:`app.py`(Gradio 事件綁定部分,L1310-1340)
42
+ - **變更**:
43
+ - 在 demo.load 事件中綁定預設參數(事件、時間範圍、震央位置)
44
+ - 自動填充波形地圖、波形圖、狀態訊息
45
+ - **驗收**:應用載入後,輸入測站地圖與波形圖立即顯示
46
+
47
+ ### 任務 2: 地震事件切換時自動更新波形地圖
48
+ - **描述**:修改 `event_dropdown.change` 事件綁定,使其同時更新 **波形地圖** 與 **實際觀測圖**
49
+ - **涉及檔案**:`app.py`(L1331-1335)
50
+ - **變更**:
51
+ - 將 `event_dropdown.change` 的 callback 從單純的 `on_event_select` 改為同時調用波形載入邏輯
52
+ - 新增 callback 函數 `on_event_change()` 負責協調所有更新
53
+ - **驗收**:切換事件時,波形地圖、波形圖、實際觀測圖同步更新
54
+
55
+ ## Invariants 對齐
56
+
57
+ | 項目 | 狀態 | 說明 |
58
+ |-----|------|------|
59
+ | 波形輸入 | Not Impacted | 時間窗長度、補零策略維持不變 |
60
+ | 測站限制 | Not Impacted | 最多 25 站選擇邏輯維持不變 |
61
+ | 推論流程 | Not Impacted | 模型推論邏輯完全不涉及 |
62
+ | 預設地圖高度 | Not Impacted | 仍固定 800px |
63
+ | 錯誤處理 | Not Impacted | 降級策略維持不變 |
64
+
65
+ ## 風險與回滾
66
+
67
+ ### 主要風險
68
+ 1. **初始化順序問題**:Gradio 的 `on_load` 若在組件定義前執行,可能導致參考錯誤
69
+ - 緩解:確保 callback 中的所有輸出組件已定義
70
+ - 回滾:移除 `on_load` 事件綁定
71
+
72
+ 2. **事件切換時的重複載入**:如果 callback 未正確取消前次請求,可能導致多次 load
73
+ - 緩解:在 callback 內正確接收新的事件參數
74
+ - 回滾:恢復原始的 `on_event_select` 邏輯
75
+
76
+ ## 冒煙測試
77
+
78
+ 1. **應用啟動測試**
79
+ - 啟動應用後,確認輸入測站地圖、波形圖已自動顯示
80
+ - 確認狀態訊息顯示「✅ 已載入波形資料」
81
+ - 預計結果:地圖與波形圖可見,無錯誤日誌
82
+
83
+ 2. **事件切換測試**
84
+ - 從下拉菜單選擇另一個地震事件
85
+ - 確認波形地圖、波形圖、實際觀測圖自動更新
86
+ - 預計結果:所有視圖同步刷新,無額外操作
87
+
88
+ 3. **手動重新載入測試**
89
+ - 修改時間滑桿,點擊「載入波形」按鈕
90
+ - 確認波形地圖按新參數重新生成
91
+ - 預計結果:地圖與波形圖更新為新時間範圍
92
  - [ ] 測試通過
93
 
94
  ### 任務 2: [功能名稱]