zhongyou
/
scm-harmonic-cmts-admin
0
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
scm-harmonic-cmts-admin/.continue/rules/new-rule.md

6.4 KiB
Raw Blame History

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，不銷毀資料。