PROJECT_STATUS.md

# DSP Bode Plot 專案進度總結 (2026-05-15)

## 1. 核心功能優化 (DSP & 定點數運算)
- **細部微調 (Fine-tuning)**：實施了基於 $\delta$ (Delta) 與 $r$ (Radius) 的參數化微調。
- **定點數精確度修正**：採用「兩倍值整數運算」邏輯，解決了 $0.5$ 步階在浮點數圓整時產生的「按鍵沒反應」Bug。
- **防止漂移 (Oscillation Logic)**：針對數位微調，實施了奇偶震盪平衡邏輯。當調整 $\delta$ 導致 $r$ 必須隨動時，採用震盪補償防止 $r$ 產生單向累積誤差。
- **參數連動策略**：在 $0.5$ 步階時，採取「優先滿足目標變動」原則。若調整 $\delta$，則 $r$ 隨動；反之亦然。

## 2. UI/UX 介面調整
- **側邊欄優化**：
    - 將 $r$ 與 $\delta$ 的調整區域改為**垂直堆疊**，適應 21rem 的窄邊欄。
    - 移除冗餘的 $a1, a2$ 預覽方塊，僅保留帶有數學公式標籤的 $r, \delta$ 預覽。
- **步階序列**：數位微調步階改為自訂序列：`[0.5, 1, 2, 4, 8, 32, 256, 1024, 4096, 16384, 65536]`。
- **微調量顯示**：統一使用 `±` 符號並帶空格（例如 `± 0.5`）。
- **智能禁用**：當數位步階為 $0.5$ 時，自動禁用 $r$ 的控制項，確保以 $\delta$ 為主導。

## 3. 繪圖系統 (Bode Plot)
- **幅值圖 (Magnitude)**：
    - 初始範圍：基於 $systemGain \times 3$，涵蓋 $70 \text{ dB}$。
    - 保留手動彈性：設定為 `fixedrange: false`，支援滑鼠縮放與 Auto Scale。
    - 狀態保持：使用 `uirevision`，確保微調參數時不會跳回初始縮放。
- **相位圖 (Phase)**：
    - 絕對鎖死：固定範圍為 $[-180^\circ, 180^\circ]$。
    - 禁止縮放：設定為 `fixedrange: true`，提供穩定的絕對參考。
- **座標軸連動**：幅值圖與相位圖的 **X 軸（頻率）已完全同步**。不論在哪一張圖進行橫向縮放，兩者都會連動。

## 4. 數學公式參考
- **理想空間**：
    - $a1 = -1 - r + \delta$
    - $a2 = r + \delta$
- **定點數空間 (Q14 為例)**：
    - $a0 = 2^{14} = 16384$
    - $a1 = -a0 - r + \delta$
    - $a2 = r + \delta$
    - $2\delta = a1 + a2 + a0$
    - $2r = a2 - a1 - a0$

## 5. 目前 Git 狀態
- **當前分支**：`dev-v2-rounding-fix-20260517` (已推送到 origin)。
- **同步說明**：此版本包含了 Rounding 功能、Vite proxy 修復與 production build。
- **同事試用指令**：
    ```bash
    git fetch
    git checkout dev-v2-rounding-fix-20260517
    ```

---
*Last Updated: 2026-05-15 17:47*

---

# DSP Bode Plot 專案進度更新 (2026-05-17)

## 6. 定點數 Rounding 模擬 (V2 Feature)
- **Round (+0.5 補償) 功能**：在 `integer_lfilter()` 中實作了硬體級四捨五入模擬，使用 `(acc + (1 << (shift - 1))) >> shift` 取代傳統的 `acc >> shift` (Floor)。
- **UI 控制**：於「定點數模擬設定」區塊新增 **Floor (SRA) / Round (+0.5)** 互斥按鈕（與「階數 Order」相同風格），放置於 Q_in / Q_out 同列。預設為 Round。
- **API 參數**：`/api/filter` 與 `/api/filter/download` 端點已支援 `use_round` 參數。
- **高精度狀態變數架構**：前饋 (Feed-forward) 不右移，保留完整 $Q_{in+b}$ 精度；僅回授 (Feedback) 與最終輸出做位移縮放。

## 7. Vite Proxy 修正
- **Bug 修正**：`vite.config.js` 的 proxy target 從 `https://` 修正為 `http://`，與 uvicorn 的實際 HTTP 協議一致。

---

## ⚠️ 踩雷紀錄 (Lessons Learned)

### 🔴 Production Build 未同步 (2026-05-17)
**症狀**：修改了 `src/app-options.js` 與 `src/App.vue` 後，UI 按鈕有出現但功能完全不生效（Round/Floor 切換後濾波器輸出完全沒變化）。花了大量時間除錯。

**根因**：使用者透過 `http://localhost:8000/ui/` 存取系統。FastAPI 直接 serve `static/build/app.js`，而該檔案停留在 5 月 15 日的舊版（距今超過一天）。所有前端修改都只存在於 `src/` 原始碼，從未被 `npm run build` 編譯輸出。

**解法**：修改 `src/` 後務必執行 `npm run build`，再 `Ctrl+Shift+R` 硬重新整理瀏覽器。

**預防措施**：
1. 開發時優先使用 `http://localhost:5173/` (Vite dev server，自動 HMR)。
2. 若使用 port 8000，每次修改前端程式碼後必須 build。
3. 詳見 `ARCHITECTURE.md` 的「Development Environment Notes」章節。

### 🟡 Vite Proxy https/http 不匹配 (2026-05-17)
**症狀**：Vite dev server 的 API 轉發全部失敗 (502)，uvicorn 日誌大量出現 `Invalid HTTP request received.`。

**根因**：`vite.config.js` 設定了 `target: 'https://127.0.0.1:8000'`，但 uvicorn 以 HTTP 模式啟動。Vite proxy 嘗試發送 TLS 握手封包到純 HTTP 伺服器。

**解法**：將 proxy target 改為 `http://127.0.0.1:8000`，移除 `secure: false`。

---
*Last Updated: 2026-05-17 00:43*

---

# DSP Bode Plot 專案進度更新 (2026-05-17 - 第二階段重構與優化)

## 8. 回授變數命名重構與物理意義釐清
- **變數命名精確化**：為消除舊版回授項以 `fb_` 開頭容易讓工程師誤解為 `b` 係數的命名混淆，將 `dea/csv_processing.py` 的變數全面更名：
  - `fb_sum` $\rightarrow$ **`sum_a`** (回授 a 累加項)
  - `fb_shifted` $\rightarrow$ **`sum_a_scaled`** (已除以 $A_0$ 歸一化後的回授項)
  - `acc` 運算直接更新為直觀的 `acc = sum_b - sum_a_scaled`，完全與數學公式鏡像對齊。
- **明確白話文檔指引**：在根目錄與 bodeplot 目錄下的 `INTEGER_FILTER_IMPLEMENTATION.md` 文件中，新增了兩項白話物理意義說明：
  1. **為什麼回授部分除以 $A_0$？**（假設 $A_0 = 1$，放大後即為 $2^{Q_a}$，除以 $A_0$ 等同於算術右移 `shift_a`，旨在消去 $Q_a$ 放大的效應以防數值爆炸）。
  2. **為什麼輸入訊號 $x$ 與前饋 $b$ 不用中間歸一化？**（說明為了防止小數精度因中間右移而被截斷丟棄，故意將高精度一路鎖在歷史狀態變數中，延遲至最終輸出時才進行一次性對齊，藉此獲得最大 SNR 與最佳效能）。
  3. **加註 Floor 模式的警告**：加註 `（無條件捨去，非常不建議）`，指引工程師優先使用 Round 補償。

## 9. 韌體 C 語言實作最佳化 (32-bit MCU Optimization)
- **32位元整數重構**：為避免 64 位元除法/乘法在 32 位元微處理器（如 ARM Cortex-M 或是 RISC-V RV32I）上引發昂貴的軟體模擬消耗，將 `INTEGER_FILTER_IMPLEMENTATION.md` 中提供的 C 語言 Process 範例全部改為由 **`int32_t`** 為核心的高效能版本。

## 10. Vite HTTPS Proxy & SSL 完全對齊
- **HTTPS 代理修復**：為同時支援 Web Serial API（瀏覽器實體連接埠，要求 HTTPS 協議）與 Vite 5173 的自動熱更新開發，將 `vite.config.js` 的 proxy target 更新為 **`https://127.0.0.1:8000`**，並加上 **`secure: false`**（允許繞過自簽憑證限制），徹底解決了前端對代理伺服器發送明文請求所導致的 `Failed to execute 'json' on 'Response': Unexpected end of JSON input` 報錯。

## 11. 目前 Git 狀態與 GitLab 同步
- **當前分支**：`dev-v2-integretimedomain`
- **提交與推送**：已經將最新的變數重構、32-bit C 代碼優化、Vite HTTPS Proxy 更新成功 commit 並 Push 至 GitLab 遠端儲存庫，分支版控狀態極其乾淨。

---
*Last Updated: 2026-05-17 14:26*
-											Optimize DSP interface: stacked r/delta, fixed r-drift, locked phase, and linked axes
										
										
											2026-05-15 17:45:45 +08:00
+								# DSP Bode Plot 專案進度總結 (2026-05-15)
 								## 1. 核心功能優化 (DSP & 定點數運算)
 								- **細部微調 (Fine-tuning)**：實施了基於 $\delta$ (Delta) 與 $r$ (Radius) 的參數化微調。
 								- **定點數精確度修正**：採用「兩倍值整數運算」邏輯，解決了 $0.5$ 步階在浮點數圓整時產生的「按鍵沒反應」Bug。
 								- **防止漂移 (Oscillation Logic)**：針對數位微調，實施了奇偶震盪平衡邏輯。當調整 $\delta$ 導致 $r$ 必須隨動時，採用震盪補償防止 $r$ 產生單向累積誤差。
 								- **參數連動策略**：在 $0.5$ 步階時，採取「優先滿足目標變動」原則。若調整 $\delta$，則 $r$ 隨動；反之亦然。
 								## 2. UI/UX 介面調整
 								- **側邊欄優化**：
 								    - 將 $r$ 與 $\delta$ 的調整區域改為**垂直堆疊**，適應 21rem 的窄邊欄。
 								    - 移除冗餘的 $a1, a2$ 預覽方塊，僅保留帶有數學公式標籤的 $r, \delta$ 預覽。
 								- **步階序列**：數位微調步階改為自訂序列：`[0.5, 1, 2, 4, 8, 32, 256, 1024, 4096, 16384, 65536]`。
 								- **微調量顯示**：統一使用 `±` 符號並帶空格（例如 `± 0.5`）。
 								- **智能禁用**：當數位步階為 $0.5$ 時，自動禁用 $r$ 的控制項，確保以 $\delta$ 為主導。
 								## 3. 繪圖系統 (Bode Plot)
 								- **幅值圖 (Magnitude)**：
 								    - 初始範圍：基於 $systemGain \times 3$，涵蓋 $70 \text{ dB}$。
 								    - 保留手動彈性：設定為 `fixedrange: false`，支援滑鼠縮放與 Auto Scale。
 								    - 狀態保持：使用 `uirevision`，確保微調參數時不會跳回初始縮放。
 								- **相位圖 (Phase)**：
 								    - 絕對鎖死：固定範圍為 $[-180^\circ, 180^\circ]$。
 								    - 禁止縮放：設定為 `fixedrange: true`，提供穩定的絕對參考。
 								- **座標軸連動**：幅值圖與相位圖的 **X 軸（頻率）已完全同步**。不論在哪一張圖進行橫向縮放，兩者都會連動。
 								## 4. 數學公式參考
 								- **理想空間**：
 								    - $a1 = -1 - r + \delta$
 								    - $a2 = r + \delta$
 								- **定點數空間 (Q14 為例)**：
 								    - $a0 = 2^{14} = 16384$
 								    - $a1 = -a0 - r + \delta$
 								    - $a2 = r + \delta$
 								    - $2\delta = a1 + a2 + a0$
 								    - $2r = a2 - a1 - a0$
 								## 5. 目前 Git 狀態
-											chore: update branch name in project status
										
										
											2026-05-17 01:00:46 +08:00
+								- **當前分支**：`dev-v2-rounding-fix-20260517` (已推送到 origin)。
 								- **同步說明**：此版本包含了 Rounding 功能、Vite proxy 修復與 production build。
-											Update project status with GitLab push info
										
										
											2026-05-15 17:47:23 +08:00
+								- **同事試用指令**：
 								    ```bash
 								    git fetch
-											chore: update branch name in project status
										
										
											2026-05-17 01:00:46 +08:00
+								    git checkout dev-v2-rounding-fix-20260517
-											Update project status with GitLab push info
										
										
											2026-05-15 17:47:23 +08:00
+								    ```
-											Optimize DSP interface: stacked r/delta, fixed r-drift, locked phase, and linked axes
										
										
											2026-05-15 17:45:45 +08:00
 								---
-											Update project status with GitLab push info
										
										
											2026-05-15 17:47:23 +08:00
+								*Last Updated: 2026-05-15 17:47*
-											feat: complete fixed-point Rounding simulation, fix Vite proxy, and update documentation
										
										
											2026-05-17 00:58:19 +08:00
 								---
 								# DSP Bode Plot 專案進度更新 (2026-05-17)
 								## 6. 定點數 Rounding 模擬 (V2 Feature)
 								- **Round (+0.5 補償) 功能**：在 `integer_lfilter()` 中實作了硬體級四捨五入模擬，使用 `(acc + (1 << (shift - 1))) >> shift` 取代傳統的 `acc >> shift` (Floor)。
 								- **UI 控制**：於「定點數模擬設定」區塊新增 **Floor (SRA) / Round (+0.5)** 互斥按鈕（與「階數 Order」相同風格），放置於 Q_in / Q_out 同列。預設為 Round。
 								- **API 參數**：`/api/filter` 與 `/api/filter/download` 端點已支援 `use_round` 參數。
 								- **高精度狀態變數架構**：前饋 (Feed-forward) 不右移，保留完整 $Q_{in+b}$ 精度；僅回授 (Feedback) 與最終輸出做位移縮放。
 								## 7. Vite Proxy 修正
 								- **Bug 修正**：`vite.config.js` 的 proxy target 從 `https://` 修正為 `http://`，與 uvicorn 的實際 HTTP 協議一致。
 								---
 								## ⚠️ 踩雷紀錄 (Lessons Learned)
 								### 🔴 Production Build 未同步 (2026-05-17)
 								**症狀**：修改了 `src/app-options.js` 與 `src/App.vue` 後，UI 按鈕有出現但功能完全不生效（Round/Floor 切換後濾波器輸出完全沒變化）。花了大量時間除錯。
 								**根因**：使用者透過 `http://localhost:8000/ui/` 存取系統。FastAPI 直接 serve `static/build/app.js`，而該檔案停留在 5 月 15 日的舊版（距今超過一天）。所有前端修改都只存在於 `src/` 原始碼，從未被 `npm run build` 編譯輸出。
 								**解法**：修改 `src/` 後務必執行 `npm run build`，再 `Ctrl+Shift+R` 硬重新整理瀏覽器。
 								**預防措施**：
 . 開發時優先使用 `http://localhost:5173/` (Vite dev server，自動 HMR)。
 . 若使用 port 8000，每次修改前端程式碼後必須 build。
 . 詳見 `ARCHITECTURE.md` 的「Development Environment Notes」章節。
 								### 🟡 Vite Proxy https/http 不匹配 (2026-05-17)
 								**症狀**：Vite dev server 的 API 轉發全部失敗 (502)，uvicorn 日誌大量出現 `Invalid HTTP request received.`。
 								**根因**：`vite.config.js` 設定了 `target: 'https://127.0.0.1:8000'`，但 uvicorn 以 HTTP 模式啟動。Vite proxy 嘗試發送 TLS 握手封包到純 HTTP 伺服器。
 								**解法**：將 proxy target 改為 `http://127.0.0.1:8000`，移除 `secure: false`。
 								---
 								*Last Updated: 2026-05-17 00:43*
-											docs: update PROJECT_STATUS.md with second-phase refactoring details
										
										
											2026-05-17 14:23:51 +08:00
 								---
 								# DSP Bode Plot 專案進度更新 (2026-05-17 - 第二階段重構與優化)
 								## 8. 回授變數命名重構與物理意義釐清
 								- **變數命名精確化**：為消除舊版回授項以 `fb_` 開頭容易讓工程師誤解為 `b` 係數的命名混淆，將 `dea/csv_processing.py` 的變數全面更名：
 								  - `fb_sum` $\rightarrow$ **`sum_a`** (回授 a 累加項)
 								  - `fb_shifted` $\rightarrow$ **`sum_a_scaled`** (已除以 $A_0$ 歸一化後的回授項)
 								  - `acc` 運算直接更新為直觀的 `acc = sum_b - sum_a_scaled`，完全與數學公式鏡像對齊。
 								- **明確白話文檔指引**：在根目錄與 bodeplot 目錄下的 `INTEGER_FILTER_IMPLEMENTATION.md` 文件中，新增了兩項白話物理意義說明：
 . **為什麼回授部分除以 $A_0$？**（假設 $A_0 = 1$，放大後即為 $2^{Q_a}$，除以 $A_0$ 等同於算術右移 `shift_a`，旨在消去 $Q_a$ 放大的效應以防數值爆炸）。
 . **為什麼輸入訊號 $x$ 與前饋 $b$ 不用中間歸一化？**（說明為了防止小數精度因中間右移而被截斷丟棄，故意將高精度一路鎖在歷史狀態變數中，延遲至最終輸出時才進行一次性對齊，藉此獲得最大 SNR 與最佳效能）。
 . **加註 Floor 模式的警告**：加註 `（無條件捨去，非常不建議）`，指引工程師優先使用 Round 補償。
 								## 9. 韌體 C 語言實作最佳化 (32-bit MCU Optimization)
 								- **32位元整數重構**：為避免 64 位元除法/乘法在 32 位元微處理器（如 ARM Cortex-M 或是 RISC-V RV32I）上引發昂貴的軟體模擬消耗，將 `INTEGER_FILTER_IMPLEMENTATION.md` 中提供的 C 語言 Process 範例全部改為由 **`int32_t`** 為核心的高效能版本。
 								## 10. Vite HTTPS Proxy & SSL 完全對齊
 								- **HTTPS 代理修復**：為同時支援 Web Serial API（瀏覽器實體連接埠，要求 HTTPS 協議）與 Vite 5173 的自動熱更新開發，將 `vite.config.js` 的 proxy target 更新為 **`https://127.0.0.1:8000`**，並加上 **`secure: false`**（允許繞過自簽憑證限制），徹底解決了前端對代理伺服器發送明文請求所導致的 `Failed to execute 'json' on 'Response': Unexpected end of JSON input` 報錯。
 								## 11. 目前 Git 狀態與 GitLab 同步
 								- **當前分支**：`dev-v2-integretimedomain`
 								- **提交與推送**：已經將最新的變數重構、32-bit C 代碼優化、Vite HTTPS Proxy 更新成功 commit 並 Push 至 GitLab 遠端儲存庫，分支版控狀態極其乾淨。
 								---
 								*Last Updated: 2026-05-17 14:26*