fix: 聯動防呆機制-如果右側預覽視窗正在顯示這個節點的指令,連帶關閉它,防止無鎖寫入。

This commit is contained in:
swpa 2026-06-01 11:39:58 +08:00
parent 2168ccf770
commit 2cbbdb7b0c
5 changed files with 195 additions and 32 deletions

View File

@ -39,10 +39,13 @@
7. **無痛切換 (Feature Toggle)**: 必須保留 `USE_DB` 開關,若 DB 連線異常,必須能自動退回使用 JSON 檔案讀寫。
8. **無聲錯誤是原罪**: 所有設備互動模組必須使用 `try-except`,並回傳標準 JSON `{"status": "error", "message": "..."}`。嚴禁 FastAPI 直接拋出 500。
9. **CLI 執行策略 (Absolute Path Strategy)**: 針對設備寫入或還原設定時,一律採用「絕對路徑」指令,無需模擬傳統 Cisco IOS 的模式切換。寫入腳本的結尾或區塊末端,務必加上 `commit`。
10. **精準 Prompt 偵測**: 透過 SSH 讀取設備回傳時,嚴禁盲目依賴 `timeout`。必須在 `read_until_quiet` 中傳入 `prompt_pattern` (如 `r"\(config\)#"` 或 `r"(?:#|>)"`) 進行正規表達式匹配,以最高速釋放資源。
### 🎨 前端規範
10. **DOM 神聖不可侵犯**: 在前端 JS 中,嚴禁為了視覺美化刪除 `leaf-container`, `data-path`, `data-original` 等錨點。隱藏請用 `display: none`。
11. **設備操作原子性 (Atomicity)**:任何涉及「讀取後寫入」或「備份後寫入」的設備操作,必須確保嚴格的先後順序(使用 `await`),嚴禁使用 `BackgroundTasks` 導致 Race Condition。若過程耗時必須透過 SSE 即時回報進度。
12. **資料庫防膨脹原則**:實作任何會自動產生大量資料的功能(如自動備份、日誌),必須同時實作 Retention Policy保留策略/定期清理機制),不可只寫入不刪除。
13. **安全還原原則 (Safe Restore)**: 嚴禁直接將整份備份檔盲目寫入設備。任何還原操作必須遵循「三階段流程」:產生差異 (Diff) ➡️ 前端預覽 (Preview) ➡️ 授權執行 (Commit)。
14. **前端防禦性編程 (Defensive Programming)**: 處理 API 回傳資料、DOM 元素取值或陣列過濾時,必須嚴格防範 Null/Undefined 情況(例如使用 `(item.description || '').toLowerCase()` 與 `?.` 運算子)。確保前端 UI 絕對不會因為單一欄位資料缺失或舊版快取而導致整個畫面或功能崩潰。
11. **DOM 神聖不可侵犯**: 在前端 JS 中,嚴禁為了視覺美化刪除 `leaf-container`, `data-path`, `data-original` 等錨點。隱藏請用 `display: none`。
12. **UI 狀態安全還原**: 動態修改 DOM 的 CSS 屬性(如 `flex`, `width`)後,若需恢復原狀,嚴禁寫死預設值,必須將屬性設為空字串 `''`,讓瀏覽器自然退回 HTML 定義的樣式,避免改 A 壞 B。
13. **設備操作原子性 (Atomicity)**:任何涉及「讀取後寫入」或「備份後寫入」的設備操作,必須確保嚴格的先後順序(使用 `await`),嚴禁使用 `BackgroundTasks` 導致 Race Condition。若過程耗時必須透過 SSE 或 ReadableStream 即時回報進度。
14. **資料庫防膨脹原則**:實作任何會自動產生大量資料的功能(如自動備份、日誌),必須同時實作 Retention Policy保留策略/定期清理機制),不可只寫入不刪除。
15. **安全還原原則 (Safe Restore)**: 嚴禁直接將整份備份檔盲目寫入設備。任何還原操作必須遵循「三階段流程」:產生差異 (Diff) ➡️ 前端預覽 (Preview) ➡️ 授權執行 (Commit)。
16. **前端防禦性編程 (Defensive Programming)**: 處理 API 回傳資料、DOM 元素取值或陣列過濾時,必須嚴格防範 Null/Undefined 情況(例如使用 `(item.description || '').toLowerCase()` 與 `?.` 運算子)。確保前端 UI 絕對不會因為單一欄位資料缺失或舊版快取而導致整個畫面或功能崩潰。

View File

@ -39,10 +39,13 @@
7. **無痛切換 (Feature Toggle)**: 必須保留 `USE_DB` 開關,若 DB 連線異常,必須能自動退回使用 JSON 檔案讀寫。
8. **無聲錯誤是原罪**: 所有設備互動模組必須使用 `try-except`,並回傳標準 JSON `{"status": "error", "message": "..."}`。嚴禁 FastAPI 直接拋出 500。
9. **CLI 執行策略 (Absolute Path Strategy)**: 針對設備寫入或還原設定時,一律採用「絕對路徑」指令,無需模擬傳統 Cisco IOS 的模式切換。寫入腳本的結尾或區塊末端,務必加上 `commit`
10. **精準 Prompt 偵測**: 透過 SSH 讀取設備回傳時,嚴禁盲目依賴 `timeout`。必須在 `read_until_quiet` 中傳入 `prompt_pattern` (如 `r"\(config\)#"``r"(?:#|>)"`) 進行正規表達式匹配,以最高速釋放資源。
### 🎨 前端規範
10. **DOM 神聖不可侵犯**: 在前端 JS 中,嚴禁為了視覺美化刪除 `leaf-container`, `data-path`, `data-original` 等錨點。隱藏請用 `display: none`
11. **設備操作原子性 (Atomicity)**:任何涉及「讀取後寫入」或「備份後寫入」的設備操作,必須確保嚴格的先後順序(使用 `await`),嚴禁使用 `BackgroundTasks` 導致 Race Condition。若過程耗時必須透過 SSE 即時回報進度。
12. **資料庫防膨脹原則**:實作任何會自動產生大量資料的功能(如自動備份、日誌),必須同時實作 Retention Policy保留策略/定期清理機制),不可只寫入不刪除。
13. **安全還原原則 (Safe Restore)**: 嚴禁直接將整份備份檔盲目寫入設備。任何還原操作必須遵循「三階段流程」:產生差異 (Diff) ➡️ 前端預覽 (Preview) ➡️ 授權執行 (Commit)。
14. **前端防禦性編程 (Defensive Programming)**: 處理 API 回傳資料、DOM 元素取值或陣列過濾時,必須嚴格防範 Null/Undefined 情況(例如使用 `(item.description || '').toLowerCase()``?.` 運算子)。確保前端 UI 絕對不會因為單一欄位資料缺失或舊版快取而導致整個畫面或功能崩潰。
11. **DOM 神聖不可侵犯**: 在前端 JS 中,嚴禁為了視覺美化刪除 `leaf-container`, `data-path`, `data-original` 等錨點。隱藏請用 `display: none`
12. **UI 狀態安全還原**: 動態修改 DOM 的 CSS 屬性(如 `flex`, `width`)後,若需恢復原狀,嚴禁寫死預設值,必須將屬性設為空字串 `''`,讓瀏覽器自然退回 HTML 定義的樣式,避免改 A 壞 B。
13. **設備操作原子性 (Atomicity)**:任何涉及「讀取後寫入」或「備份後寫入」的設備操作,必須確保嚴格的先後順序(使用 `await`),嚴禁使用 `BackgroundTasks` 導致 Race Condition。若過程耗時必須透過 SSE 或 ReadableStream 即時回報進度。
14. **資料庫防膨脹原則**:實作任何會自動產生大量資料的功能(如自動備份、日誌),必須同時實作 Retention Policy保留策略/定期清理機制),不可只寫入不刪除。
15. **安全還原原則 (Safe Restore)**: 嚴禁直接將整份備份檔盲目寫入設備。任何還原操作必須遵循「三階段流程」:產生差異 (Diff) ➡️ 前端預覽 (Preview) ➡️ 授權執行 (Commit)。
16. **前端防禦性編程 (Defensive Programming)**: 處理 API 回傳資料、DOM 元素取值或陣列過濾時,必須嚴格防範 Null/Undefined 情況(例如使用 `(item.description || '').toLowerCase()``?.` 運算子)。確保前端 UI 絕對不會因為單一欄位資料缺失或舊版快取而導致整個畫面或功能崩潰。

View File

@ -13,25 +13,30 @@
- [x] 調整 `init_db.py` 為非同步啟動腳本。
### Phase 2: 設備配置備份與快照機制 (Completed)
- [x] **資料庫擴充**:在 PostgreSQL 中建立 `config_backups` 資料表 (包含 `id`, `host`, `timestamp`, `raw_cli`, `parsed_tree`, `snapshot_name`)。
- [x] **資料庫擴充**:在 PostgreSQL 中建立 `config_backups` 資料表 (包含 `id`, `host`, `timestamp`, `raw_cli`, `parsed_tree`, `snapshot_name`, `description`)。
- [x] **前端 UI 實作**:完成「設備備份與還原」頁籤,包含建立快照表單與歷史紀錄列表 (馬卡龍色系與 Flexbox 佈局)。
- [x] **後端 API 實作**:完成手動建立快照與取得歷史快照列表的 API 路由。
- [x] **前端 UI 優化與防禦性編程**:完成滿版視覺重構、原生日期選擇器整合,並實作具備 Null-Safety 與 `.trim()` 容錯的多維度前端搜尋過濾器 (支援快照名稱 + 描述雙欄位比對)。
### Phase 3: 智慧差異還原與歷史預覽 (Completed)
- [x] **歷史預覽 UI**:前端支援點擊歷史快照的「檢視」按鈕。
- [x] **前端安全還原防呆**:實作三階段安全還原流程 UI (包含 Diff 預覽與確認寫入按鈕),並加入跨設備還原阻斷機制。
- [x] **後端 Diff 引擎實作**:完成 `/api/v1/backups/{id}/diff`,成功生成絕對路徑指令陣列。
- [x] **前端串流接收器 (Streaming UI)**:升級 `executeSmartRestore`,使用 `ReadableStream` 即時渲染後端傳來的 SSH 逐行執行 Log並具備自動捲動功能。
- [x] **後端 SSH 交易寫入管道 (Transactional SSH Pipeline)**
- 實作 `/api/v1/backups/{id}/restore` API採用 `StreamingResponse` (NDJSON 串流回應)。
- 建立安全的逐行寫入機制 (Fail-safe),遇錯立即停止、發送 `abort` 撤銷變更,並回傳錯誤 Chunk。
- [x] **效能與體驗優化**:完成 DOM 陣列渲染優化、Terminal 資源回收 (防殭屍連線)、精準 Prompt 偵測,以及 UI 視窗連動防呆機制。
---
## 🚧 目前開發階段 (Current Phase)
### Phase 3: 智慧差異還原與歷史預覽 (Smart Diff Recovery & Preview)
- [x] **歷史預覽 UI**:前端支援點擊歷史快照的「檢視」按鈕。
- [x] **前端安全還原防呆**:實作三階段安全還原流程 UI (包含 Diff 預覽與確認寫入按鈕)。
- [x] **後端 Diff 引擎實作**:完成 `/api/v1/backups/{id}/diff`,成功生成絕對路徑指令陣列。
- [ ] **前端串流接收器 (Streaming UI)**:升級 `executeSmartRestore`,使用 ReadableStream 即時渲染後端傳來的 SSH 逐行執行 Log。
- [ ] **後端 SSH 交易寫入管道 (Transactional SSH Pipeline)**
- 實作 `/api/v1/backups/{id}/restore` API改為 Streaming Response (串流回應)。
- 建立安全的逐行寫入機制 (Fail-safe),遇錯立即停止並回傳錯誤 Chunk。
### Phase 4: 自動化防護與進階管理 (Automation & Advanced Management)
- [ ] **自動備份攔截 (Auto-Backup Interceptor)**:在執行任何 `generate_cli` (寫入設備變更) 之前,實作自動觸發背景備份 `running config` 的防呆機制,確保每次變更前都有還原點。
- [ ] **備份保留策略 (Retention Policy)**:實作定期清理過期或過多歷史快照的機制,防止資料庫無限膨脹。
---
## 🐛 已知問題與未來計畫 (Known Issues & Backlog)
- **[未來計畫] 自動備份攔截**:在執行任何 `generate_cli` (寫入設備變更) 之前,實作自動觸發背景備份 `running config` 的防呆機制
- 目前系統運行穩定,各項併發鎖定與 UI 狀態連動皆已完善。等待進入 Phase 4 開發。

View File

@ -4198,6 +4198,28 @@ export async function cancelEditFolder(path, elementId) {
const safeOrigVal = escapeHTML(origVal);
container.innerHTML = `<span class="leaf-value" style="color: #16a085; margin-left: 5px; font-family: Courier New, monospace;">${safeOrigVal}</span>`;
});
// 🌟 聯動防呆機制:如果右側預覽視窗正在顯示這個節點的指令,連帶關閉它,防止無鎖寫入
if (currentEditElementId === elementId) {
document.querySelectorAll('.tree-view-instance').forEach(pane => {
pane.style.flex = '1';
pane.style.width = '100%';
pane.style.maxWidth = 'none';
});
const rightPane = document.getElementById('side-cli-preview');
if (rightPane) {
rightPane.style.flex = '1';
rightPane.style.maxWidth = '50%';
rightPane.style.width = '';
rightPane.style.display = 'none';
}
document.getElementById('drag-resizer').style.display = 'none';
currentEditPath = null;
currentEditElementId = null;
currentEditIsSuccess = false;
currentEditType = null;
}
}
export async function cancelEditLeaf(path, elementId) {
@ -4218,6 +4240,28 @@ export async function cancelEditLeaf(path, elementId) {
const origVal = container.getAttribute('data-original');
const safeOrigVal = escapeHTML(origVal);
container.innerHTML = `<span class="leaf-value" style="color: #16a085; margin-left: 5px; font-family: Courier New, monospace;">${safeOrigVal}</span>`;
// 🌟 聯動防呆機制:如果右側預覽視窗正在顯示這個節點的指令,連帶關閉它,防止無鎖寫入
if (currentEditElementId === elementId) {
document.querySelectorAll('.tree-view-instance').forEach(pane => {
pane.style.flex = '1';
pane.style.width = '100%';
pane.style.maxWidth = 'none';
});
const rightPane = document.getElementById('side-cli-preview');
if (rightPane) {
rightPane.style.flex = '1';
rightPane.style.maxWidth = '50%';
rightPane.style.width = '';
rightPane.style.display = 'none';
}
document.getElementById('drag-resizer').style.display = 'none';
currentEditPath = null;
currentEditElementId = null;
currentEditIsSuccess = false;
currentEditType = null;
}
}
// ==========================================
@ -4332,8 +4376,16 @@ function showCliPreviewModal(cliScript) {
textarea.style.backgroundColor = '#1e1e1e';
textarea.style.color = '#ecf0f1';
leftPanes.forEach(pane => pane.style.width = 'calc(50% - 11px)');
// 🛡️ 安全修改:解除 Flexbox 均分限制,讓 JS 拖拉的 width 生效
leftPanes.forEach(pane => {
pane.style.flex = 'none';
pane.style.maxWidth = 'none';
pane.style.width = 'calc(50% - 11px)';
});
rightPane.style.flex = 'none';
rightPane.style.maxWidth = 'none';
rightPane.style.width = 'calc(50% - 11px)';
resizer.style.display = 'flex';
rightPane.style.display = 'block';
@ -4347,10 +4399,24 @@ function showCliPreviewModal(cliScript) {
// 4. 側邊欄與執行邏輯
// ==========================================
export async function hideSideCLI() {
document.querySelectorAll('.tree-view-instance').forEach(pane => pane.style.width = '100%');
document.getElementById('drag-resizer').style.display = 'none';
document.getElementById('side-cli-preview').style.display = 'none';
// 🌟 完美修復:明確恢復 Flexbox 伸展能力與 100% 寬度
document.querySelectorAll('.tree-view-instance').forEach(pane => {
pane.style.flex = '1'; // 恢復 HTML 原本賦予的彈性伸展能力
pane.style.width = '100%'; // 強制撐滿整個父容器
pane.style.maxWidth = 'none';
});
const rightPane = document.getElementById('side-cli-preview');
if (rightPane) {
rightPane.style.flex = '1';
rightPane.style.maxWidth = '50%'; // 恢復 HTML 原本的 50% 限制
rightPane.style.width = '';
rightPane.style.display = 'none';
}
document.getElementById('drag-resizer').style.display = 'none';
// 以下為原本的取消編輯與還原邏輯,完全保持不變,確保功能安全
if (currentEditIsSuccess && currentEditElementId && currentEditPath) {
const wrapper = document.getElementById(`display-wrapper-${currentEditElementId}`);
if (wrapper) {
@ -4737,10 +4803,20 @@ function showReadOnlyCliPreviewModal(cliScript, rootPath) {
document.getElementById('side-execution-result').style.display = 'none';
leftPanes.forEach(pane => pane.style.width = 'calc(50% - 11px)');
// 🛡️ 安全修改:解除 Flexbox 均分限制,讓 JS 拖拉的 width 生效
leftPanes.forEach(pane => {
pane.style.flex = 'none';
pane.style.maxWidth = 'none';
pane.style.width = 'calc(50% - 11px)';
});
if (rightPane) {
rightPane.style.flex = 'none';
rightPane.style.maxWidth = 'none';
rightPane.style.width = 'calc(50% - 11px)';
rightPane.style.display = 'block';
}
if (resizer) resizer.style.display = 'flex';
if (rightPane) rightPane.style.display = 'block';
if (!window.isResizerInitialized && typeof initResizer === 'function') {
initResizer();

View File

@ -262,6 +262,28 @@ export async function cancelEditFolder(path, elementId) {
const safeOrigVal = escapeHTML(origVal);
container.innerHTML = `<span class="leaf-value" style="color: #16a085; margin-left: 5px; font-family: Courier New, monospace;">${safeOrigVal}</span>`;
});
// 🌟 聯動防呆機制:如果右側預覽視窗正在顯示這個節點的指令,連帶關閉它,防止無鎖寫入
if (currentEditElementId === elementId) {
document.querySelectorAll('.tree-view-instance').forEach(pane => {
pane.style.flex = '1';
pane.style.width = '100%';
pane.style.maxWidth = 'none';
});
const rightPane = document.getElementById('side-cli-preview');
if (rightPane) {
rightPane.style.flex = '1';
rightPane.style.maxWidth = '50%';
rightPane.style.width = '';
rightPane.style.display = 'none';
}
document.getElementById('drag-resizer').style.display = 'none';
currentEditPath = null;
currentEditElementId = null;
currentEditIsSuccess = false;
currentEditType = null;
}
}
export async function cancelEditLeaf(path, elementId) {
@ -282,6 +304,28 @@ export async function cancelEditLeaf(path, elementId) {
const origVal = container.getAttribute('data-original');
const safeOrigVal = escapeHTML(origVal);
container.innerHTML = `<span class="leaf-value" style="color: #16a085; margin-left: 5px; font-family: Courier New, monospace;">${safeOrigVal}</span>`;
// 🌟 聯動防呆機制:如果右側預覽視窗正在顯示這個節點的指令,連帶關閉它,防止無鎖寫入
if (currentEditElementId === elementId) {
document.querySelectorAll('.tree-view-instance').forEach(pane => {
pane.style.flex = '1';
pane.style.width = '100%';
pane.style.maxWidth = 'none';
});
const rightPane = document.getElementById('side-cli-preview');
if (rightPane) {
rightPane.style.flex = '1';
rightPane.style.maxWidth = '50%';
rightPane.style.width = '';
rightPane.style.display = 'none';
}
document.getElementById('drag-resizer').style.display = 'none';
currentEditPath = null;
currentEditElementId = null;
currentEditIsSuccess = false;
currentEditType = null;
}
}
// ==========================================
@ -396,8 +440,16 @@ function showCliPreviewModal(cliScript) {
textarea.style.backgroundColor = '#1e1e1e';
textarea.style.color = '#ecf0f1';
leftPanes.forEach(pane => pane.style.width = 'calc(50% - 11px)');
// 🛡️ 安全修改:解除 Flexbox 均分限制,讓 JS 拖拉的 width 生效
leftPanes.forEach(pane => {
pane.style.flex = 'none';
pane.style.maxWidth = 'none';
pane.style.width = 'calc(50% - 11px)';
});
rightPane.style.flex = 'none';
rightPane.style.maxWidth = 'none';
rightPane.style.width = 'calc(50% - 11px)';
resizer.style.display = 'flex';
rightPane.style.display = 'block';
@ -411,10 +463,24 @@ function showCliPreviewModal(cliScript) {
// 4. 側邊欄與執行邏輯
// ==========================================
export async function hideSideCLI() {
document.querySelectorAll('.tree-view-instance').forEach(pane => pane.style.width = '100%');
document.getElementById('drag-resizer').style.display = 'none';
document.getElementById('side-cli-preview').style.display = 'none';
// 🌟 完美修復:明確恢復 Flexbox 伸展能力與 100% 寬度
document.querySelectorAll('.tree-view-instance').forEach(pane => {
pane.style.flex = '1'; // 恢復 HTML 原本賦予的彈性伸展能力
pane.style.width = '100%'; // 強制撐滿整個父容器
pane.style.maxWidth = 'none';
});
const rightPane = document.getElementById('side-cli-preview');
if (rightPane) {
rightPane.style.flex = '1';
rightPane.style.maxWidth = '50%'; // 恢復 HTML 原本的 50% 限制
rightPane.style.width = '';
rightPane.style.display = 'none';
}
document.getElementById('drag-resizer').style.display = 'none';
// 以下為原本的取消編輯與還原邏輯,完全保持不變,確保功能安全
if (currentEditIsSuccess && currentEditElementId && currentEditPath) {
const wrapper = document.getElementById(`display-wrapper-${currentEditElementId}`);
if (wrapper) {
@ -801,10 +867,20 @@ function showReadOnlyCliPreviewModal(cliScript, rootPath) {
document.getElementById('side-execution-result').style.display = 'none';
leftPanes.forEach(pane => pane.style.width = 'calc(50% - 11px)');
// 🛡️ 安全修改:解除 Flexbox 均分限制,讓 JS 拖拉的 width 生效
leftPanes.forEach(pane => {
pane.style.flex = 'none';
pane.style.maxWidth = 'none';
pane.style.width = 'calc(50% - 11px)';
});
if (rightPane) {
rightPane.style.flex = 'none';
rightPane.style.maxWidth = 'none';
rightPane.style.width = 'calc(50% - 11px)';
rightPane.style.display = 'block';
}
if (resizer) resizer.style.display = 'flex';
if (rightPane) rightPane.style.display = 'block';
if (!window.isResizerInitialized && typeof initResizer === 'function') {
initResizer();