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

# Harmonic CMTS Manager - AI 開發守則與架構白皮書

## 1. 專案架構概覽與技術棧
- **定位**: 專為有線電視網路終端設備 (CMTS) 設計的企業級 Web 管理系統。
- **後端**: Python 3.10+, FastAPI (Async-first), AsyncSSH, Netmiko, asyncpg.
- **前端**: 原生 Vanilla JS (ES Modules), HTML5, CSS3, Xterm.js.
- **資料庫**: PostgreSQL (主要), JSON File Cache (高可用性降級備援).

### 📂 目錄與檔案結構
- **進入點**: `main.py`
- **路由管理**: API 路由統一放置於 `routers/` 目錄。包含 backup.py, config.py, leaf_options.py, lock.py, query.py, terminal.py。
- **前端介面**: `index.html` 與 `static/` 目錄。 包含 api.js, app.js, edit-mode.js, mac-domain.js, style.css, terminal.js, tree-ui.js, utils.js。
- **核心邏輯**: 
  - `cmts_scraper.py`: 負責底層爬蟲與資料處理。
  - `shared.py`: 放置共用函式 (如兩階段解析法)。
  - `config.py`: 配置轉譯器 (CLI Generator)。
- **資料庫**: 連線與 ORM 邏輯在 `database.py`，初始化腳本為 `init_db.py`。
- **併發控制**: `lock.py` (路徑階層鎖), `leaf_options.py` (SSE 頻道分流)。

## 2. 核心架構與業務邏輯 (Architecture & Logic)
- **兩階段解析法**: 依賴「縮排」與「`!`」劃分區塊，並動態降維成深層巢狀結構，使用 `deep_merge` 確保資料不遺失。
- **動態探測**: 透過發送 `[指令] ?` 動態學習資料結構，並採用 `BATCH_SIZE = 30` 搭配 `asyncio.sleep()` 進行非同步批次處理。
- **絕對路徑與 Commit 機制 (Absolute Path)**: Harmonic CMTS 支援從 Global 模式直接寫入帶有完整上下文的絕對路徑指令（如 `cable mac-domain 13:0/0.0 ...`），無須層層進入子模式。所有變更指令發送完畢後，必須執行 `commit` 才能生效。
- **智慧差異還原 (Smart Diff Recovery)**: 設備還原不採用盲目覆蓋，而是透過深度比對 (Deep Diff) 當前設備狀態與備份快照，動態生成包含 `no` 的反向刪除指令與新增/修改指令，確保配置精準還原且無殘留。
- **併發與狀態廣播**: 支援「父子繼層攔截」的路徑階層鎖，並利用 `asyncio.Queue` 實作 SSE 頻道分流，即時推播進度。
- **配置轉譯器**: 自動補齊父層級路徑，處理 `no [指令]` 刪除邏輯，並具備 `admin-state` 的生命週期防呆機制。

## 3. 🚨 AI 開發絕對約束 (Directives for AI)

### ⚙️ 系統與環境規範
1. **套件管理**: 若需安裝新套件，請提醒我手動在 `cmts_api_env` 中安裝，並更新 `requirements.txt`。
2. **資料讀取限制**: 請勿隨意讀取 `*_cache.json` 檔案的內容，若需了解資料結構，請參考 `cmts_scraper.py` 中的定義。
3. **狀態同步**: 完成重大修改或一個 Phase 後，必須主動更新 `PROJECT_STATE.md` 記錄最新進度與待辦事項。

### 💻 程式碼風格與後端規範
4. **語言與風格**: 註解與對話請一律使用**繁體中文**。Python 程式碼請遵循 PEP8 規範，並加上適當的 Type Hints (型別提示)。
5. **Async-First (非同步絕對優先)**: 嚴禁使用阻塞的同步 I/O。同步函數必須封裝進 `await asyncio.to_thread()`。
6. **嚴守「雙軌並行」**: 必須在任何 API 請求明確傳遞並驗證 `config_type` ('running' 或 'full')。絕對禁止 `running` 污染 `full` 快取。
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"(?:#|>)"`) 進行正規表達式匹配，以最高速釋放資源。

### 🎨 前端規範
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 絕對不會因為單一欄位資料缺失或舊版快取而導致整個畫面或功能崩潰。