--- doc_id: "DOC-CLI-004" title: "Cẩm Nang Kiểm Thử Di Động Qua WebApp PWA Simulator" category: "client" diataxis_type: "how-to" status: "canonical" version: "2026.1" owner_role: "web_client_engineer" last_updated: "2026-09-29" tags: ["webapp-pwa", "mobile-simulator", "testing-guide", "chrome-devtools"] related_code: - "tools/serve_webapp.py" - "client/webapp/index.html" related_docs: - "docs/client/IOS_METAL_AND_CLIENT_ENGINE.md" summary: "Quy trình thiết lập và kiểm thử game trên iPhone/Android thật qua mạng Wi-Fi cục bộ không cần tài khoản Apple Developer." --- # FREEEXILE: HƯỚNG DẪN KIỂM THỬ TRÊN THIẾT BỊ DI ĐỘNG (WEBAPP PWA NATIVE SIMULATOR) > **Phòng ban phụ trách**: Lead Documentation Architect (`lead_documentation_architect`) & Web Simulation Engineer (`web_client_engineer`) > **Mục tiêu**: Giúp lập trình viên và QA kiểm thử toàn diện trải nghiệm người dùng, điều khiển cảm ứng ngón tay, giao diện tràn viền và hiệu ứng chiến đấu Ngũ Hành trên màn hình điện thoại thật mà **hoàn toàn không cần máy Mac hay tài khoản Apple Developer trả phí**. --- ## 1. TỔNG QUAN KIẾN TRÚC WEBAPP NATIVE SIMULATOR Do quy trình đóng gói TestFlight/Xcode truyền thống bắt buộc phải có máy tính macOS và tài khoản Apple Developer Program (99 USD/năm), FreeExile đã phát triển nền tảng **Mobile WebApp PWA Native Simulator** tại thư mục [`client/webapp/`](file:///c:/Projects/FreeExile/client/webapp/): - **Tiêu chuẩn PWA Standalone**: Khi cài đặt vào màn hình chính điện thoại, ứng dụng chạy độc lập, **ẩn 100% thanh URL và thanh công cụ của Safari/Chrome**, tương đương 1 ứng dụng Native. - **Tương thích màn hình cong & Safe Area Insets**: Tự động nhận diện tai thỏ (Notch), Dynamic Island trên iPhone 14/15/16 Pro và thanh điều hướng cử chỉ Home Bar qua biến CSS `env(safe-area-inset-top)` và `env(safe-area-inset-bottom)`. - **Hệ thống điều khiển cảm ứng công thái học 2 tay (Dual-Thumb Ergonomics)**: - **Tay trái (Left Thumb Zone)**: Cần điều khiển ảo linh hoạt (**Dynamic Floating Joystick**). Người chơi chạm vào bất kỳ điểm nào ở nửa trái màn hình, tâm joystick sẽ tự sinh ra ngay dưới đầu ngón tay. - **Tay phải (Right Thumb Zone)**: Cụm nút chiêu thức dạng vòng cung ngón cái: *Hỏa Lôi Phá* (Q), *Cửu Thiên Lôi Vũ* (W), *Thái Ất Kiếm Khí* (E), và nút lớn *Huyễn Ảnh Bộ* (Dodge roll với 0.25s i-frame bất tử). - **Hỗ trợ 9 ngôn ngữ tức thì**: Chuyển đổi ngôn ngữ trực tiếp từ thanh công cụ góc trên mà không cần khởi động lại app. --- ## 2. HƯỚNG DẪN KẾT NỐI VÀ KIỂM THỬ TRÊN ĐIỆN THOẠI THẬT ### Bước 1: Khởi động Local Web Server trên PC Mở PowerShell tại thư mục dự án và chạy: ```powershell python tools/serve_webapp.py ``` Server sẽ tự động dò tìm địa chỉ IP cục bộ của máy tính trong mạng Wi-Fi và hiển thị: ``` ================================================================= FREEEXILE: MOBILE NATIVE WEBAPP TESTING SERVER (Test on iPhone / Android via Wi-Fi or Tailscale) ================================================================= [+] Local Browser URL : http://localhost:8088/index.html [+] Phone / Tablet Wi-Fi: http://192.168.1.15:8088/index.html [+] Phone via Tailscale : http://100.121.197.18:8088/index.html ``` ### Bước 2: Truy cập từ iPhone / iPad / Android 1. Đảm bảo điện thoại của bạn đang kết nối vào **cùng một mạng Wi-Fi** (hoặc bật **Tailscale VPN**). 2. Mở trình duyệt **Safari** (trên iPhone/iPad) hoặc **Chrome** (trên Android). 3. Nhập địa chỉ hiển thị ở terminal (ví dụ: `http://100.121.197.18:8088` hoặc `http://192.168.1.15:8088`). ### Bước 3: Đưa ra Màn hình chính (Chế độ Native Fullscreen) - **Trên iPhone / iPad (Safari)**: 1. Nhấn vào biểu tượng **Chia sẻ** (hình vuông có mũi tên chỉ lên ở giữa dưới màn hình). 2. Cuộn xuống và chọn **"Thêm vào Màn hình chính" (Add to Home Screen)**. 3. Nhấn **Thêm (Add)**. 4. Mở icon **FreeExile** từ màn hình chính. Ứng dụng sẽ mở ở chế độ toàn màn hình không có bất kỳ viền trình duyệt nào! - **Trên Android (Chrome)**: 1. Nhấn vào biểu tượng menu **3 dấu chấm** ở góc trên bên phải. 2. Chọn **"Cài đặt ứng dụng" (Install app)** hoặc **"Thêm vào Màn hình chính"**. 3. Mở từ màn hình chính để tận hưởng trải nghiệm tràn viền. --- ## 3. KẾT NỐI QUA TAILSCALE VPN (KHÔNG CẦN CHUNG WI-FI, DÙNG ĐƯỢC CẢ 4G/5G) Nếu điện thoại và máy tính đã cài đặt **Tailscale**: 1. **Bật Tailscale trên điện thoại**: Mở app Tailscale trên iPhone/Android và gạt công tắc sang **Connected** (VPN hiển thị ở thanh trạng thái). 2. **Lấy địa chỉ Tailscale của máy tính**: - Địa chỉ IP Tailscale của máy tính này: `100.121.197.18` - Tên máy tính (MagicDNS): `ds1` 3. **Mở trình duyệt trên điện thoại và truy cập**: - `http://100.121.197.18:8088` (hoặc `http://ds1:8088`) 4. **Trải nghiệm**: - Máy tính và điện thoại có thể ở bất kỳ đâu (kể cả khi điện thoại dùng 4G/5G hoặc Wi-Fi khác), đường truyền được mã hóa P2P WireGuard với độ trễ cực thấp (~10-15ms). - Thêm vào Màn hình chính (Add to Home Screen) để chạy toàn màn hình như ứng dụng native. ## 4. KIỂM THỬ TRÊN TRÌNH DUYỆT MÁY TÍNH (DESKTOP SIMULATOR) Nếu muốn kiểm thử nhanh trên máy tính PC mà không cần cầm điện thoại: 1. Mở `http://localhost:8088/index.html` trên Google Chrome hoặc Microsoft Edge. 2. Bạn sẽ thấy thanh công cụ giả lập ở trên cùng: - **📱 iPhone 15 Pro**: Hiển thị trong khung viền kim loại điện thoại, hỗ trợ test kích thước màn hình và vùng bấm ngón cái. - **🖥️ Full Window**: Mở rộng toàn bộ cửa sổ trình duyệt. - **⛶ Fullscreen**: Bật chế độ F11 toàn màn hình. 3. Có thể dùng chuột kéo joystick ảo bên trái, hoặc dùng bàn phím: - Di chuyển: `W`, `A`, `S`, `D` hoặc các phím mũi tên. - Chiêu thức: `Q` (Lửa), `W` (Sét), `E` (Băng), `Space` (Lướt né Huyễn Ảnh Bộ). --- ## 5. DANH MỤC PHÒNG BAN LIÊN QUAN TRONG STUDIO | Phòng Ban | Nhân Sự Phụ Trách | Trách Nhiệm Vận Hành | | :--- | :--- | :--- | | **Phòng Tài Liệu (Documentation)** | `lead_documentation_architect` | Quản lý Game Bible, tài liệu API, hướng dẫn QA và checklist vận hành. | | **Phòng Ngôn Ngữ (Language & i18n)** | `localization_lead` | Duy trì bộ từ điển 9 thứ tiếng tại `data/locales/*.json`, Wiki đa ngữ tại `wiki/`. | | **Phòng Giả Lập Web Mobile** | `web_client_engineer` | Duy trì `client/webapp/`, tối ưu hóa hiệu năng canvas, điều khiển cảm ứng ngón tay. |