scm-harmonic-cmts-admin/PROJECT_STATE.md

📖 Harmonic CMTS Manager - Project State (Living Document)

⚠️ AI 助手請注意：本專案的核心架構與開發規範已移至 .clinerules。此檔案僅作為「專案進度存檔」與「待辦事項追蹤」使用。

---

✅ 已完成開發階段 (Completed Phases)

Phase 1: PostgreSQL 高可用性架構升級

• 成功導入 asyncpg，建立 database.py 管理非同步資料庫連線池。
• 建立 cmts_options, device_status, system_filters 資料表，嚴格遵守 config_type 雙軌隔離的主鍵設計。
• 實踐完整的「Zero-Downtime Fallback 機制」：資料庫連線異常時，自動退回使用 JSON 檔案讀寫。

Phase 2: 設備配置備份與快照機制

• 資料庫擴充：在 PostgreSQL 中建立 config_backups 資料表 (包含 id, host, timestamp, raw_cli, parsed_tree, snapshot_name, description)。
• 前端 UI 實作：完成「設備備份與還原」頁籤，包含建立快照表單與歷史紀錄列表。
• 前端 UI 優化與防禦性編程：實作具備 Null-Safety 與 .trim() 容錯的多維度前端搜尋過濾器 (支援快照名稱 + 描述雙欄位比對)。

Phase 3: 智慧差異還原與歷史預覽

• 前端安全還原防呆：實作三階段安全還原流程 UI (包含 Diff 預覽與確認寫入按鈕)，並加入跨設備還原阻斷機制。
• 後端 Diff 引擎實作：完成 /api/v1/backups/{id}/diff，成功生成絕對路徑指令陣列。
• 後端 SSH 交易寫入管道 (Transactional SSH Pipeline)：實作 /api/v1/backups/{id}/restore API，採用 StreamingResponse (NDJSON 串流回應)，並具備 Fail-safe abort 撤銷機制。

Phase 3.5: 企業級前端效能重構 (Extreme Performance Optimization)

• 記憶體遞迴渲染 (In-Memory Recursive Rendering)：徹底重構 tree-ui.js，將數千次 DOM 寫入壓縮為單次 innerHTML 寫入，解決「展開全部」導致瀏覽器卡死的問題。
• 非同步 UI 保護機制：在所有大型渲染場景 (初始載入、單點展開、全部展開) 導入 setTimeout 讓出主執行緒，並搭配沙漏游標與橘色讀取提示，確保 UI 絕對滑順。
• CSS 渲染隔離：導入 content-visibility: auto，讓不在可視範圍內的 DOM 節點暫停渲染計算。
• 精準 DOM 查詢：將鎖定狀態輪詢 (startLockStatusPolling) 的搜尋範圍限縮於當前啟用的視圖內，消除全域搜尋造成的卡頓 (Jank)。

---

🚀 即將到來的里程碑 (Upcoming Milestones Summary)

Phase 4: 自動化防護、進階管理與指令精準度 (Automation & Advanced Management)

• 智能視覺診斷 (Visual Diagnostics)：
  • CM 一鍵診斷中心：整合基礎狀態、PHY 射頻指標與 OFDM MER 頻譜。引入 Chart.js 將 ASCII 報表轉化為紅黃綠狀態圖與長條圖。
• 備份保留策略 (Retention Policy)：
  • 手動快照配額 (Manual Quota)：限制每台設備最多保留 20 份手動快照，達上限時，採用 FIFO (先進先出) 機制自動清理舊資料，防止資料庫無限膨脹。
• 系統日誌動態儀表板 (Log Viewer UI) :
  • 基於 FastAPI 實作一個 WebSocket Log Streamer。
    1. Custom Log Handler: 在現有的 Python logging 模組中，撰寫一個自訂的 Handler，能夠攔截系統的 Log 訊息（包含 ANSI 色碼）。
    2. WebSocket Endpoint: 建立一個 FastAPI WebSocket 路由 /ws/logs。
    3. Broadcaster: 實作一個簡單的機制，當 Custom Log Handler 收到新日誌時，能非同步地將訊息推播給所有連線中的 WebSocket 客戶端。

Phase 5: RPD 快速擴容與部署精靈 (Rapid RPD Provisioning Wizard)

• RPD 樣板克隆引擎 (Template Cloning)：
  • 於「MAC Domain 狀態感知配置精靈」中新增 RPD 擴容模式。允許使用者選擇現有設備上已配置完成的 RPD (支援 FDX, FDD, D3.1+) 作為基準樣板。
• Tree 節點複製與參數替換 (Node Duplication & Modification)：
  • 透過底層 Tree 架構，完整複製複雜的 RF 與通道設定，並提供 UI 介面供使用者修改唯一識別碼 (如 MAC Address、RPD Name)。
• 安全寫入與校驗 (Safe Provisioning)：
  • 結合 Phase 4 的防護機制，在將全新 RPD 配置寫入 CMTS 前，進行參數衝突檢查（避免 MAC 或 IP 重複），實現零錯誤的設備擴容。
• Diff 引擎指令精準度強化 (Diff Logic Hardening)：
  • 重新 Review generate_diff_commands 演算法。
  • 實作「指令截斷機制」，確保生成 no 移除指令時，能精準剝離多餘的 Value 或參數，避免 CMTS 拒絕執行或引發非預期刪除。

---

🐛 已知問題與技術債 (Known Issues & Tech Debt)

• 目前系統運行極度穩定，前端效能瓶頸已徹底消除，各項併發鎖定與 UI 狀態連動皆已完善。準備進入 Phase 4 的 Diff 引擎強化開發。