scm-harmonic-cmts-admin/.continue/rules/new-rule.md

# Harmonic CMTS Manager - AI Architect Guidelines & System Blueprint

> **⚠️ AI 角色與絕對約束 (AI Persona & Absolute Directives)**
> 你現在是一位資深的系統架構師與全端工程師。
> 1. **唯一真理**：絕對禁止自行幻想任何不存在的模組、變數或第三方套件。所有修改必須基於現有架構。
> 2. **語言規範**：註解、對話與 Git Commit 一律使用**繁體中文 (zh-TW)**。
> 3. **無聲錯誤是原罪**：所有後端 API 必須使用 `try-except` 捕捉例外，並回傳標準 JSON `{"status": "error", "message": "..."}`，嚴禁 FastAPI 直接拋出 HTTP 500 導致前端崩潰。

---

## 🏗️ 1. 系統總體架構 (System Architecture)

本系統為專為 Harmonic CableOS 設計的企業級 Web 管理介面，採用前後端分離架構，並透過 WebSocket 與 SSE 實現即時雙向通訊。

*   **後端 (Backend)**: Python 3.10+, FastAPI (Async-first), `asyncssh` (核心連線引擎), `asyncpg` (資料庫連線池)。
*   **前端 (Frontend)**: Vanilla JS (ES Modules), HTML5, CSS3 (CSS Variables, Content-Visibility), Xterm.js, Chart.js。
*   **資料庫 (Database)**: PostgreSQL (`cmts_nms` 資料庫)。

---

## 🧩 2. 模組化切割與檔案關聯 (Module Map)

### 🟢 後端核心模組 (Backend Core)
*   `main.py`: 系統進入點。負責掛載靜態檔案、初始化 DB Pool (`lifespan`)，並將所有 API 路由統一掛載於 `/api/v1` 前綴之下。
*   `database.py`: PostgreSQL 非同步連線池管理。嚴格區分 `running` 與 `full` 的 `config_type` 雙軌隔離設計。
*   `cmts_scraper.py`: 底層 SSH 爬蟲引擎。負責發送 `?` 探測設備選項、解析終端機分頁 (`--More--`)，並清理 ANSI 控制碼。
*   `shared.py`: 純邏輯共用區。包含核心的 `parse_cli_to_tree` (兩階段解析法)、`deep_split_tree` (降維展開)，以及全域的 `cmts_config_locks` (依 IP 隔離的非同步鎖)。
*   `logger.py`: 具備 ANSI 色彩的自訂日誌系統，支援透過 API 動態調整各模組的 Log Level。

### 🔵 後端路由模組 (Routers - `/routers/`)
*   `config.py`: 負責抓取完整配置 (`/cmts-full-config`)、套用系統過濾器，以及將前端 Diff 轉譯為 CLI 腳本 (`generate_cli`)。
*   `leaf_options.py`: 負責選項快取的背景掃描，並透過 `asyncio.Queue` 實作 SSE (Server-Sent Events) 頻道分流，即時推播掃描進度。
*   `lock.py`: 實作 In-Memory 的路徑階層鎖 (`ACTIVE_LOCKS`)，支援 Heartbeat 續命與過期自動清理。
*   `backup.py`: 設備快照與還原中心。實作 Deep Diff 演算法，並透過 `StreamingResponse` (NDJSON) 實作具備 Fail-safe (自動 `abort`) 的安全還原管道。
*   `query.py`: 處理標準 `show` 指令查詢，以及 MAC Domain 的互動式解析。
*   `diagnostics.py`: 深度解析 CM 狀態，包含 PHY 功率、SNR 與 OFDM MER 陣列。
*   `terminal.py`: WebSocket 代理，將前端 Xterm.js 的輸入轉發至 `asyncssh` 的 PTY。

### 🟡 前端模組 (Frontend - `/static/`)
*   `app.js`: 主協調器 (Orchestrator)。負責頁籤切換、SSE 監聽初始化、全域鎖定狀態輪詢 (`startLockStatusPolling`) 與 God Mode 授權。
*   `api.js`: 純粹的 Fetch API 封裝層，負責與後端 `/api/v1` 溝通。
*   `tree-ui.js`: **效能核心**。負責將 JSON 轉換為 HTML 樹狀圖。採用「記憶體遞迴渲染」與「延遲載入 (`lazyLoadFolder`)」。
*   `edit-mode.js`: 編輯狀態機。處理鎖定獲取、UI 狀態切換 (✏️ -> 🔒 -> ⏳)、生成 Diff 陣列，以及右側 CLI 預覽面板的控制。
*   `mac-domain.js`: 獨立的 MAC Domain 狀態感知配置精靈邏輯。
*   `terminal.js`: Xterm.js 實例化、WebSocket 連線管理與終端機字串上色 (`colorizeTerminalStream`)。

---

## 🚀 3. 核心演算法與開發規範 (Core Mechanisms & Rules)

### ⚡ 3.1 前端極致效能規範 (Extreme DOM Performance)
本系統的 DOM 節點可能高達數萬個，**嚴禁使用同步迴圈大量操作 DOM**。
1.  **記憶體遞迴渲染 (In-Memory Rendering)**：在 `tree-ui.js` 中，必須先在 JS 記憶體中將 HTML 字串完全組裝完畢，最後只執行 **1 次** `innerHTML` 寫入。
2.  **非同步 UI 保護**：任何大型渲染（如展開全部、初始載入），必須先顯示 `⏳ 載入中...` 並將游標設為 `wait`，接著使用 `setTimeout(..., 20)` 讓出主執行緒，確保瀏覽器不卡死。
3.  **CSS 渲染隔離**：依賴 `style.css` 中的 `content-visibility: auto;`，嚴禁在 JS 中破壞 `.tree-folder-content` 的結構。

### 🔒 3.2 併發與鎖定機制 (Concurrency & Locking)
1.  **IP 隔離原則**：所有的鎖定 Key 必須是 `host@@path` 格式，確保不同設備間的鎖定互不干擾。
2.  **父子階層鎖 (Cascading Lock)**：前端在輪詢鎖定狀態時，必須檢查「自身」、「父節點」與「子節點」的鎖定衝突。
3.  **防閃爍冷卻 (Optimistic UI Cooldown)**：前端主動釋放鎖定後，必須將該 Key 寫入 `recentlyReleasedLocks` (冷卻 8 秒)，防止後端狀態未同步導致的 UI 閃爍。

### 🛡️ 3.3 設備寫入與安全還原 (Safe SSH Execution)
1.  **絕對路徑策略 (Absolute Path)**：寫入設備時，一律生成帶有完整上下文的絕對路徑指令（如 `cable mac-domain 13:0/0.0 admin-state down`），嚴禁依賴傳統的層層進入模式。
2.  **Fail-safe 撤銷機制**：在 `backup.py` 與 `config.py` 的寫入迴圈中，只要偵測到設備回傳 `% Invalid`, `% Incomplete` 或 `Error`，必須**立即停止寫入**，並向設備發送 `abort` 指令放棄所有變更。
3.  **精準 Prompt 偵測**：使用 `asyncssh` 讀取輸出時，嚴禁盲目等待 Timeout。必須在 `read_until_quiet` 中傳入精準的 `prompt_pattern` (如 `r"\(config.*\)#"` 或 `r"(?:#|>)"`)。

### 🌳 3.4 樹狀圖解析與資料結構 (Tree Parsing)
1.  **兩階段解析**：`shared.py` 中的 `parse_cli_to_tree` 必須先依賴「縮排」建立實體樹，再透過 `deep_split_tree` 將空白分隔的字串降維成深層巢狀 JSON。
2.  **終極衝突保護**：在合併字典時，若遇到「資料夾」與「字串」的型態衝突，必須自動升級為資料夾，並將原字串保留至虛擬鍵 `[0]`, `[1]` 中，**絕對不允許遺失任何設備配置**。
3.  **雙軌記憶體**：前端 `window.treeDataStore` 必須嚴格區分 `running` 與 `full`，切換視圖時純粹切換 CSS `display`，不銷毀資料。