README.md

# Difference Equation Analyzer

差分方程式與數位濾波器分析工具。後端使用 FastAPI，前端使用 Vue 3 + Vite 建置後由 FastAPI 以靜態檔案服務。

## 專案結構

- `dea_api.py`：FastAPI 後端、API 端點、LAN 存取限制、安全標頭。
- `src/`：Vue 前端原始碼。
- `static/index.html`：正式 UI 入口，載入建置後的前端資源。
- `static/build/app.js`、`static/build/app.css`：前端建置產物，正式服務會載入這兩個檔案。
- `static/style.css`：既有自訂 CSS，由 `src/style.css` 引入。
- `tests/`：後端回歸測試。
- `dea.service`：systemd 服務設定範本。
- `dea_legacy.py`：舊 Streamlit 版本，僅供參考。

## 使用網址

本機：

```bash
http://localhost:8000/ui/
```

區網其他裝置：

```bash
http://192.168.2.58:8000/ui/
```

根路徑 `/` 會自動導向 `/ui/`。

## 後端環境

建立或重建 Python 虛擬環境：

```bash
cd /home/wisetop/diff-eq-analyzer
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
```

本機開發啟動：

```bash
.venv/bin/uvicorn dea_api:app --host 127.0.0.1 --port 8000
```

## 前端建置

前端依賴由 `package.json` / `package-lock.json` 管理。首次安裝：

```bash
npm install
```

重新建置正式前端：

```bash
npm run build
```

建置後會更新：

```text
static/build/app.js
static/build/app.css
```

注意：正式頁面不再載入 Vue CDN 或 Tailwind CDN；Vue 會被打包到 `static/build/app.js`。目前仍使用 Plotly CDN。

## systemd 服務

查看狀態：

```bash
sudo systemctl status dea.service
```

啟動、停止、重啟：

```bash
sudo systemctl start dea.service
sudo systemctl stop dea.service
sudo systemctl restart dea.service
```

查看即時日誌：

```bash
sudo journalctl -u dea.service -f
```

修改 `dea.service` 或 `/etc/systemd/system/dea.service` 後：

```bash
sudo systemctl daemon-reload
sudo systemctl restart dea.service
```

## 測試與檢查

Python 語法檢查：

```bash
.venv/bin/python -m py_compile dea_api.py tests/test_dea_api.py
```

後端測試：

```bash
.venv/bin/python -m unittest discover -s tests
```

前端建置檢查：

```bash
npm run build
```

## 安全與效能設定

後端目前包含：

- 僅允許 private / loopback IP 存取。
- CSP、安全回應標頭、`X-Frame-Options: DENY`、`nosniff`。
- CSV 上傳大小限制：10 MB。
- 圖表用 CSV 回傳最多 5000 點，下載 CSV 仍保留完整資料。
- 係數數量上限：64。
- 濾波器頻率、係數有限值、`a[0]` 等輸入驗證。

目前 CSP 的 `script-src` 僅允許：

```text
'self' https://cdn.plot.ly
```

因此不再需要 `'unsafe-eval'`。

## 常見問題

### 網頁空白

1. 強制刷新瀏覽器：`Ctrl+F5`。
2. 確認服務狀態：

```bash
sudo systemctl status dea.service
```

3. 確認靜態檔案存在：

```bash
ls static/build/app.js static/build/app.css
```

4. 若剛改前端，請重新建置並重啟：

```bash
npm run build
sudo systemctl restart dea.service
```

### 服務無法啟動，出現 status=203/EXEC

通常是 `.venv` 路徑或 `uvicorn` 腳本路徑失效。重建虛擬環境後再重啟：

```bash
rm -rf .venv
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
sudo systemctl restart dea.service
```