3.1 KiB

Raw Blame History

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/ 目錄。
前端介面: index.html 與 static/ 目錄。
核心邏輯:
- 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() 進行非同步批次處理。
併發與狀態廣播: 支援「父子繼層攔截」的路徑階層鎖，並利用 asyncio.Queue 實作 SSE 頻道分流，即時推播進度。
配置轉譯器: 自動補齊父層級路徑，處理 no [指令] 刪除邏輯，並具備 admin-state 的生命週期防呆機制。

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

⚙️ 系統與環境規範

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

💻 程式碼風格與後端規範

語言與風格: 註解與對話請一律使用繁體中文。Python 程式碼請遵循 PEP8 規範，並加上適當的 Type Hints (型別提示)。
Async-First (非同步絕對優先): 嚴禁使用阻塞的同步 I/O。同步函數必須封裝進 await asyncio.to_thread()。
嚴守「雙軌並行」: 必須在任何 API 請求明確傳遞並驗證 config_type ('running' 或 'full')。絕對禁止 running 污染 full 快取。
無痛切換 (Feature Toggle): 必須保留 USE_DB 開關，若 DB 連線異常，必須能自動退回使用 JSON 檔案讀寫。
無聲錯誤是原罪: 所有設備互動模組必須使用 try-except，並回傳標準 JSON {"status": "error", "message": "..."}。嚴禁 FastAPI 直接拋出 500。

🎨 前端規範

DOM 神聖不可侵犯: 在前端 JS 中，嚴禁為了視覺美化刪除 leaf-container, data-path, data-original 等錨點。隱藏請用 display: none。