refactor code, ẩn thông tin ssh

docs/load_fw_ssh_docs.md

@@ -1,60 +1,166 @@
-# Tài liệu Kỹ thuật: Nạp Firmware qua SSH (`core/ssh_flasher.py`)
+# Tài liệu Kỹ thuật: Flash Firmware qua SSH
 
-Module `ssh_flasher.py` chịu trách nhiệm nạp Firmware lên các thiết bị OpenWrt nạp mới hoặc nạp lại thông qua hai giao thức Telnet và SSH. Nó được thiết kế với độ an toàn cao để xử lý đa luồng (ví dụ: quét và nạp hàng loạt thiết bị cùng lúc), có cơ chế tự động thử lại (Retry) và cơ chế dự phòng mật khẩu khi thiết bị bị kẹt mật khẩu cũ.
+Tài liệu này gộp toàn bộ logic SSH cho cả hai quy trình: **Nạp Mới FW** (Factory Reset) và **Update FW** (thiết bị đang chạy). Luồng SSH được tách thành nhiều file với trách nhiệm rõ ràng thay vì gói gọn trong một module duy nhất.
 
-## 1. Sơ đồ Luồng Hoạt Động (Operational Flow)
+---
+
+## 1. Kiến Trúc Tổng Quan — Vai Trò Từng File
+
+```
+core/
+├── ssh_utils.py          ← Transport layer dùng chung (không có business logic)
+├── ssh_new_flash.py      ← Luồng SSH Nạp Mới FW (Telnet → SSH → sysupgrade)
+├── ssh_update_flash.py   ← Luồng SSH Update FW   (SSH trực tiếp → sysupgrade)
+├── flash_new_worker.py   ← QThread điều phối Nạp Mới (API LuCI hoặc SSH)
+└── flash_update_worker.py← QThread điều phối Update FW (SSH only)
+```
+
+### `core/ssh_utils.py` — Transport Layer Dùng Chung
+
+Chứa các helper function cấp thấp, **không mang logic nghiệp vụ**, được import bởi cả 2 luồng SSH:
+
+| Hàm                                                    | Mô tả                                                                                                                     |
+| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
+| `_create_ssh_client(ip, user, password, timeout)`      | Tạo SSH client với `AutoAddPolicy`, retry 3 lần. Nếu lỗi `AuthenticationException` thì raise ngay (không retry vô nghĩa). |
+| `_upload_firmware(client, firmware_path, status_cb)`   | Upload file `.bin` qua SCP lên `/tmp/<filename>`. Retry 3 lần, timeout SCP là 350 giây. Trả về `remote_path`.             |
+| `_verify_firmware(client, remote_path, status_cb)`     | Chạy `test -f && ls -lh` để xác nhận file tồn tại trên device sau khi upload.                                             |
+| `_sync_and_sysupgrade(client, remote_path, status_cb)` | Chạy `sync` rồi `sysupgrade -F -v -n`. Đứt kết nối = thành công. Trả về `"DONE"` hoặc `"FAIL: ..."`.                      |
+
+### `core/ssh_new_flash.py` — Luồng Nạp Mới FW
+
+Xử lý thiết bị **vừa Factory Reset** hoặc **chưa có mật khẩu**. Bao gồm:
+
+- **`_SimpleTelnet`**: Telnet client thủ công bằng raw socket — thay thế `telnetlib` bị xoá khỏi Python 3.13+.
+- **`set_device_password()`**: Đặt mật khẩu thiết bị, thử Telnet port 23 trước, fallback sang SSH nếu Telnet đóng.
+- **`flash_device_new_ssh()`**: Hàm flash chính — gọi `set_device_password` (nếu `set_passwd=True`) rồi kết nối SSH và gọi pipeline `_upload → _verify → _sync_and_sysupgrade` từ `ssh_utils`.
+
+### `core/ssh_update_flash.py` — Luồng Update FW
+
+Xử lý thiết bị **đang chạy MiraV3**, SSH đã mở sẵn với pass đã biết. Không có Telnet, không có set_passwd:
+
+- **`flash_device_update_ssh()`**: Kết nối SSH (thử `password`, fallback `backup_password` nếu auth fail), rồi gọi thẳng pipeline `_upload → _verify → _sync_and_sysupgrade` từ `ssh_utils`.
+
+### `core/flash_new_worker.py` — QThread Nạp Mới
+
+`NewFlashThread` — điều phối flash song song cho chế độ **Nạp Mới**:
+
+- Nếu `method="ssh"` → gọi `flash_device_new_ssh()` từ `ssh_new_flash`.
+- Nếu `method="api"` → gọi `flash_device()` từ `flasher` (LuCI HTTP).
+- Nhận đủ credentials từ UI: `ssh_user`, `ssh_password`, `ssh_backup_password`, `set_passwd`.
+
+### `core/flash_update_worker.py` — QThread Update FW
+
+`UpdateFlashThread` — điều phối flash song song cho chế độ **Update FW**:
+
+- Luôn dùng SSH, credentials hardcode an toàn trong module (`root` / `admin123a`, backup `admin`).
+- Không nhận credentials từ UI — tránh nhập sai gây flash nhầm.
+
+---
+
+## 2. Sơ Đồ Luồng — Nạp Mới FW (SSH)
 
 ```mermaid
 graph TD
-    A[Bắt đầu Flash SSH] -->|Jitter Delay 0.1s - 1.5s| B{Có yêu cầu Set Password?}
-    B -- Không --> F[Bước 1: Kết nối SSH]
-    B -- Có --> C[Thử kết nối Telnet port 23]
+    A[NewFlashThread.run] --> B{method = ssh?}
+    B -- api --> API[flash_device - LuCI HTTP]
+    B -- ssh --> C[flash_device_new_ssh]
 
-    C -- Thành công --> C1[Gửi lệnh `passwd` > admin123a] --> F
-    C -- Lỗi / Timeout / Bị từ chối --> D[Thử SSH với mật khẩu rỗng]
+    C -->|set_passwd=True| D[set_device_password]
+    C -->|set_passwd=False| Jitter[Jitter 0.1s - 1.5s]
 
-    D -- Thành công --> D1[Gửi lệnh `passwd` > admin123a] --> F
-    D -- Lỗi 'Authentication Failed' --> E[Thử SSH với Backup Password]
+    D --> D1[Thử Telnet port 23]
+    D1 -- Thành công --> D2[passwd > new_password via Telnet]
+    D2 --> D3[Chờ 3s để Dropbear khởi động]
+    D1 -- Lỗi / Timeout --> D4[Fallback SSH với old_password rỗng]
+    D4 -- Auth Fail --> D5[Thử backup_password]
+    D5 -- Auth Fail --> D6[Thử chính new_password - idempotent]
+    D6 -- Fail --> Z[DỪNG - Báo FAIL]
+    D3 --> F
+    D4 -- OK --> F
+    D5 -- OK --> F
+    D6 -- OK --> F
 
-    E -- Thành công --> E1[Gửi lệnh `passwd` > admin123a] --> F
-    E -- Thất bại --> E2[Thử SSH với Password cấu hình]
-
-    E2 -- Thành công --> F
-    E2 -- Thất bại --> Z[DỪNG LẠI - Báo Lỗi]
-
-    F -->|Kết nối SSH thành công sau Retry 3 lần| G[Bước 2: Push Firmware SCP vào /tmp/]
-    G -->|Tối đa 3 lần Retry| H[Bước 3: Xác minh File `test -f`]
-    H --> I[Bước 4: Đồng bộ bộ nhớ `sync`]
-    I --> J[Bước 5: Gọi `sysupgrade -F -v -n /tmp/...`]
-    J --> K{Kết nối bị đứt?}
-    K -- Có --> L[Khởi động lại thành công - Báo DONE]
-    K -- Không --> M[Báo lỗi Sysupgrade]
+    Jitter --> F[_create_ssh_client - retry 3 lần]
+    F --> G[_upload_firmware via SCP vào /tmp/]
+    G -->|retry 3 lần| H[_verify_firmware - test -f]
+    H --> I[_sync_and_sysupgrade]
+    I --> J[sync rồi sysupgrade -F -v -n]
+    J --> K{Kết nối đứt?}
+    K -- Có --> L[DONE - Device đang Reboot]
+    K -- Không trong 4s --> M[FAIL - Lấy log /tmp/sysup.log]
 ```
 
-## 2. Phân Tích Logic Cốt Lõi
+## 3. Sơ Đồ Luồng — Update FW (SSH)
 
-### 2.1 Cơ Chế Dự Phòng Mật Khẩu Đa Tầng (Fallback Mechanism)
+```mermaid
+graph TD
+    A[UpdateFlashThread.run] --> B[flash_device_update_ssh]
+    B --> C[_create_ssh_client với password chính]
+    C -- Auth OK --> F
+    C -- AuthenticationException --> D[Thử backup_password]
+    D -- Auth OK --> F
+    D -- Fail --> Z[DỪNG - Báo FAIL]
 
-Điểm mạnh của thuật toán là khả năng "lì lợm" lấy được quyền Root để đặt mật khẩu cho thiết bị. Các lớp dự phòng bao gồm:
+    F[_upload_firmware via SCP vào /tmp/] -->|retry 3 lần| G[_verify_firmware - test -f]
+    G --> H[_sync_and_sysupgrade]
+    H --> I[sync rồi sysupgrade -F -v -n]
+    I --> J{Kết nối đứt?}
+    J -- Có --> K[DONE - Device đang Reboot]
+    J -- Không trong 4s --> L[FAIL - Lấy log /tmp/sysup.log]
+```
 
-1. **Telnet (Port 23):** Router OpenWrt khi mới xuất xưởng hoặc ngay sau khi Factory Reset sẽ chặn kết nối SSH bằng tài khoản `root` mất gốc, nhưng lại mở Telnet không có mật khẩu. Script sẽ luôn thử bẻ khóa qua đường này đầu tiên. Bất kỳ ngoại lệ nào phát sinh ở luồng này (Refused, Timeout, Broken Pipe) cũng sẽ kích hoạt fallback.
-2. **SSH (Mật khẩu rỗng):** Nếu Telnet bị đóng cửa (chứng tỏ thiết bị đã được kích hoạt sơ), phần mềm thử mở cổng 22 với User `root` và mật khẩu rỗng `""`.
-3. **SSH (Backup Password):** Nếu mật khẩu rỗng bị từ chối bằng `AuthenticationException`, script định nhận diện máy đã bị kẹt một pass được cài đặt trước đó và chèn `backup_password` ra thử nghiệm.
-4. **SSH (Target Password):** Nếu trượt tới lớp thứ 3, script thử nốt với chính mật khẩu mục tiêu của dự án (mặc định: `admin123a`) để chặn trường hợp thiết bị đã đổi Pass thành công từ lần trước nhưng quá trình nạp Firmware chưa diễn ra.
+---
 
-### 2.2 Xử Lý Đa Luồng Chống Nghẽn (Concurrency Limits)
+## 4. Phân Tích Logic Cốt Lõi
 
-Thư viện `paramiko` thường dễ đổ vỡ cấu trúc và báo lỗi `[Errno 64] Host is down` hoặc `[Errno 32] Broken Pipe` khi có vài chục luồng (threads) cùng mở port đập vào Network Stack OS (hoặc Switch/Router) ở đúng một chớp mắt. Lỗi này là dạng Transient (có tính tạm thời). Do đó hệ thống được nâng cấp:
+### 4.1 Cơ Chế Dự Phòng Mật Khẩu Đa Tầng (Nạp Mới)
 
-- **Jitter (Độ trễ ngẫu nhiên):** Sử dụng `time.sleep(random.uniform(0.1, 1.5))` trước khi chọc vào thiết bị. Sự sai lệch mili-giây này phân tán chùm yêu cầu dội vào mạng, tránh tự gây ra một cuộc tấn công từ chối dịch vụ (DDoS) nội bộ.
-- **Vòng lặp (Retry Hooks):** Quá trình đăng nhập (`_create_ssh_client`) cũng như upload payload (`SCPClient.put`) đều được bọc trong bộ đếm thử lại cực đỉnh (thử lại 3 lần sau mỗi 1-2 giây nghỉ). Việc này triệt hạ 99% các lỗi truyền TCP/IP và Timeout.
+Thuật toán `set_device_password` có 4 lớp dự phòng để chiếm được quyền Root trên thiết bị dù ở trạng thái nào:
 
-### 2.3 Cơ Chế Khôi Phục File (RAM Disk SCP)
+1. **Telnet (Port 23):** OpenWrt ngay sau Factory Reset mở Telnet không cần mật khẩu nhưng chặn SSH. Script luôn thử cổng này đầu tiên. Mọi exception (Refused, Timeout, Broken Pipe) đều kích hoạt fallback.
+2. **SSH mật khẩu rỗng `""`:** Nếu Telnet đóng, thử SSH với pass rỗng — trường hợp thiết bị đang ở trạng thái semi-configured.
+3. **SSH Backup Password:** Nếu pass rỗng bị `AuthenticationException`, thiết bị đang kẹt một pass cũ — thử `backup_password`.
+4. **SSH Target Password (Idempotent):** Thử lại với chính `new_password` để chặn trường hợp device đã đổi pass thành công từ lần flash trước nhưng chưa được flash firmware.
 
-- Firmware được tống thẳng tới phân vùng ảo RAM cục bộ đích (ví dụ: `/tmp/<tên_file>.bin`) thông qua giao thức SCP. Ghi file trực tiếp vào RAM cho phép đạt tốc độ tuyệt đối nhanh và tránh gây hao mòn sinh học lên FlashNOR của router.
-- Gửi lệnh `sync` qua kênh Shell để ép thiết bị lưu transaction xuống vùng nhớ cứng, chuẩn bị môi trường ổn định nhất.
+### 4.2 Cơ Chế Dự Phòng Mật Khẩu (Update FW)
 
-### 2.4 Thủ Thuật Gọi `sysupgrade -F`
+Đơn giản hơn: thử `password` chính → nếu `AuthenticationException` → thử `backup_password`. Không có Telnet, không có set_passwd. Nếu cả hai đều fail thì trả về `FAIL` ngay.
 
-- OpenWrt đời mới khá kén phần Metadata của Firmware Image. Cờ `-F` cởi trói kiểm duyệt đó và ép hệ điều hành nạp đè File bất chấp sự vắng mặt của metadata uImage. Cờ `-n` khiến hệ thống mất sách cấu hình cũ (Clean Flash).
-- Lệnh `sysupgrade` sẽ cắn xén cả phần OS dưới lõi máy sau đó Tắt mạng đột ngột. Do đó, script được lập trình để xử lý Exception: Sự kiện **MẤT KẾT NỐI CHỦ ĐỘNG** trong khu vực này là dấu hiệu ăn mừng của việc cài đặt thành công thay vì báo hỏng kết nối.
+### 4.3 Xử Lý Đa Luồng Chống Nghẽn
+
+`paramiko` dễ báo lỗi `[Errno 64] Host is down` hoặc `[Errno 32] Broken Pipe` khi hàng chục thread cùng hit network stack cùng một lúc. Hệ thống chống nghẽn bằng 2 cơ chế:
+
+- **Jitter ngẫu nhiên:** `time.sleep(random.uniform(0.1, 1.5))` phân tán chùm request theo thời gian, tránh tự gây DDoS nội bộ.
+- **Retry Hooks:** `_create_ssh_client` retry 3 lần (nghỉ 1s giữa mỗi lần). `_upload_firmware` retry 3 lần (nghỉ 1.5s). Triệt 99% lỗi TCP transient.
+
+### 4.4 RAM Disk SCP
+
+Firmware được upload thẳng vào `/tmp/<tên_file>.bin` — phân vùng RAM ảo của OpenWrt. Lợi ích:
+
+- Tốc độ ghi nhanh nhất (RAM vs Flash).
+- Không gây hao mòn FlashNOR của router.
+- File biến mất sau reboot, không để lại rác.
+
+### 4.5 Thủ Thuật `sysupgrade -F -v -n`
+
+| Cờ             | Tác dụng                                                                                                                 |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `-F` (Force)   | Bỏ qua kiểm tra Image Metadata — bắt buộc với file build Raw / `tim_uImage` để tránh lỗi _"Image metadata not present"_. |
+| `-v` (Verbose) | Log chi tiết vào `/tmp/sysup.log` để debug khi cần.                                                                      |
+| `-n` (No-keep) | Clean Flash — không giữ cấu hình cũ, tránh xung đột config giữa các phiên bản.                                           |
+
+**Đứt kết nối = Thành công:** `sysupgrade` phá kernel hiện tại rồi reboot nạp firmware mới → SSH session bị đứt là kết quả tất yếu và mong muốn. Script bẫy exception này và trả về `"DONE"`. Ngược lại, nếu sysupgrade fail sớm (< 4 giây, còn giữ kết nối), script đọc `/tmp/sysup.log` trả về error code đầy đủ.
+
+---
+
+## 5. Trình Gỡ Lỗi Nhanh
+
+Cả hai luồng đều gọi `status_cb(msg)` tại mỗi bước — toàn bộ tiến độ như _"Connecting SSH"_, _"Uploading firmware"_, _"Syncing filesystem"_ hiển thị trực tiếp tại cột **Status** trên giao diện chính.
+
+Để debug chi tiết hơn, chạy app qua terminal:
+
+```bash
+./run.sh
+```
+
+Mọi exception đều bị bắt và trả về chuỗi `"FAIL: <lý do>"` hiển thị lên UI — không có silent failure.