G-Launcher/Doc/ARCHITECTURE.md

# 🏗️ G-Launcher Architecture & Technical Reference

เอกสารนี้อธิบายสถาปัตยกรรมภายในของ **G-Launcher** ซึ่งสร้างขึ้นด้วย **Wails v3 Alpha** ผสานขุมพลังของ **Go Backend** และ **React 19 + TypeScript Frontend**

---

## 🏛️ ภาพรวมระดับสูง (System Overview)

```mermaid
graph TD
    subgraph FrontendLayer [Frontend Layer: React 19 and TypeScript]
        UI[React UI: DaisyUI 5 and Tailwind 4]
        Stores[Zustand Stores: launcherStore, modalStore]
        Bindings[TypeScript Bindings]
        UI <--> Stores
        Stores <--> Bindings
    end

    subgraph IPCLayer [Wails v3 IPC and Event Gateway]
        IPCBridge[Typed IPC Calls and Event Subscriptions]
        Bindings <--> IPCBridge
    end

    subgraph BackendLayer [Backend Layer: Go 1.24 Core Services]
        AppSvc[AppService - Window controls]
        FSSvc[FSService - Safe IO and Game Path]
        GitSvc[GitService - Updater and MinGit]
        DiffSvc[DiffService - Protobuf Diffs and HPatchz]
        LangSvc[LanguageService - Asset Modding]
        
        IPCBridge <--> AppSvc
        IPCBridge <--> FSSvc
        IPCBridge <--> GitSvc
        IPCBridge <--> DiffSvc
        IPCBridge <--> LangSvc
    end

    subgraph HostSystem [System and Filesystem Integration]
        GameExe[Game Process: StarRail.exe]
        ConfigDir[APPDATA User Config]
        ToolsDir[Portable Tools: MinGit and Node]
        AssetsDir[Binary Tools: 7za and HPatchz]
    end

    FSSvc --> GameExe
    FSSvc --> ConfigDir
    GitSvc --> ToolsDir
    DiffSvc --> AssetsDir
    LangSvc --> AssetsDir
```

---

## 🧩 บริการหลังบ้านทั้ง 5 ตัว (Go Backend Services)

บริการทั้งหมดถูกประกาศและลงทะเบียนใน [`main.go`](../main.go) ผ่าน `app.RegisterService(...)`:

### 1. [`AppService`](../internal/app-service/app.go)
* จัดการวงจรชีวิตของหน้าต่าง Launcher:
  * ย่อหน้าต่าง (`Minimize()`), ขยาย/คืนขนาด (`ToggleMaximize()`), ปิดหน้าต่าง (`Close()`)
  * ปิดโปรแกรมอัตโนมัติเมื่อตั้งเวลา (`CloseAppAfterTimeout(seconds)`)
  * คืนค่าเวอร์ชันปัจจุบันของ Launcher (`GetCurrentLauncherVersion()`)

### 2. [`FSService`](../internal/fs-service/)
* **`game-selection.go`:** บันทึกและอ่านพาธตัวเกมที่ผู้ใช้เลือก โดยใช้วิธี **Atomic Write** เขียนลงไฟล์ชั่วคราวแล้วเรียกใช้ Windows API `MoveFileEx` ป้องกันไฟล์เสีย
* **`dialog.go`:** เปิด Native File Dialog ให้ผู้ใช้เลือกไฟล์ตัวเกม (`StarRail.exe`)
* **`file.go`:** ตรวจสอบความมีอยู่ของไฟล์ (`FileExists()`), ตรวจสอบสิทธิ์, ค้นหาโฟลเดอร์

### 3. [`GitService`](../internal/git-service/)
* **`git_runtime.go`:** ระบบตรวจสอบ Git ในเครื่อง หากไม่มีจะดาวน์โหลด **Portable MinGit** มาไว้ที่โฟลเดอร์เครื่องมืออัตโนมัติ
* **`launcher.go`:** ระบบอัปเดตตัว Launcher:
  * ตรวจสอบอัปเดตผ่าน `latest.json` manifest หรือ Releases API
  * อัปเดตผ่านการคอมไพล์จากโค้ดต้นทาง (`BuildAndUpdateFromSource`) โดยดาวน์โหลดลง Temp, บิลด์ใน Temp, สลับแทนที่ตัวเก่าด้วย `selfupdate.Apply`, และลบ Temp ทิ้ง
* **`proxy.go` & `server.go`:** ดาวน์โหลดและคลายแพ็กเกจ Local Proxy และ Local Server จาก Release endpoints พร้อมรายงานความคืบหน้าแบบมัลติเธรด

### 4. [`DiffService`](../internal/diff-service/)
* **`hpatchz.go`:** เรียกใช้ `hpatchz.exe` เพื่อแพตช์ไฟล์แบบ Delta diff (`.hdiff`)
* **`ziff.go`:** รองรับการแพตช์ไฟล์ฟอร์แมต Zift (`.ziff`) ผ่าน `zift.exe` ที่ผสานมาจาก Sunbringer
* **`chunk.go`:** ถอดรหัสและประมวลผล Hoyoverse Protobuf chunk manifests

### 5. [`LanguageService`](../internal/language-service/)
* **`thai-patch.go`:** ระบบติดตั้ง/ถอนการติดตั้งม็อดภาษาไทยสำหรับเกม โดยแก้ไบต์ในไฟล์ `ExcelData`
* สำรองไฟล์เดิมเป็น `.backup` ก่อนลงมือแก้ไขเสมอ เพื่อให้สามารถกู้คืนได้แบบ Atomic

---

## 🎨 สถาปัตยกรรมส่วนหน้า (Frontend Architecture)

* **Framework:** React 19 + TypeScript + Vite
* **UI & Styles:** TailwindCSS v4 + DaisyUI v5 (ธีมมินิมอล โมเดิร์น ปรับแต่งจาก Firefly)
* **State Management:** Zustand:
  * `launcherStore.ts`: เก็บสถานะตัวเกม, พาธ, เซิร์ฟเวอร์, พร็อกซี, ความเร็วการดาวน์โหลด
  * `modalStore.ts`: ควบคุมการเปิด/ปิด Modal หน้าต่างแจ้งเตือนและอัปเดต
* **Localization (i18n):** รองรับ 6 ภาษา (`th`, `en`, `zh`, `ja`, `ko`, `vi`)
* **IPC Bindings:** สร้างจากคำสั่ง `wails3 generate bindings` ส่งโค้ดมาที่ `frontend/bindings/` เป็น Type-safe functions ที่เรียกตรงเข้าสู่ Go Backend ได้ทันที

---

## 📦 โครงสร้างไฟล์และโฟลเดอร์หลัก

```
G-Launcher/
├── Doc/                     # 📚 เอกสารสถาปัตยกรรมและคู่มือการพัฒนาสำหรับนักพัฒนาและ AI
├── build/                   # คอนฟิกการบิลด์, ไอคอน, Windows Manifest, Taskfile
├── frontend/                # React 19 Frontend (Vite, TypeScript, Tailwind)
│   ├── bindings/            # Auto-generated IPC Bindings จาก Wails v3
│   ├── public/              # Static assets & localization files (locales/*.json)
│   └── src/                 # React components, pages, stores, hooks
├── internal/                # โค้ด Backend ภาษา Go (แบ่งตาม Domain Services)
│   ├── app-service/         # Window controls & version logic
│   ├── diff-service/        # HPatchz & Zift delta patching
│   ├── fs-service/          # Safe filesystem & game path persistence
│   ├── git-service/         # Self-updater, MinGit, server/proxy downloaders
│   └── language-service/    # Thai patch modding & asset recovery
├── pkg/                     # แพ็กเกจ Go ที่ใช้ร่วมกัน
│   ├── constant/            # รวมศูนย์ URL, ค่าคงที่, คอนฟิก (ห้าม Hardcode)
│   ├── firefly/             # Protobuf parser & chunk utilities
│   ├── hpatchz/             # HPatchz CLI wrappers
│   └── sevenzip/            # 7-Zip decompression helpers
├── proto/                   # Protobuf definitions
├── scripts/                 # สคริปต์ Release และ Bootstrap (bootstrap.ps1)
├── tools/                   # (Ignored) โฟลเดอร์เก็บ Portable runtimes (MinGit, Go, Node)
├── AGENTS.md                # กฎระเบียบและแนวทางการพัฒนาสำหรับ AI Agent
├── build.bat                # สคริปต์คอมไพล์สำหรับ Windows
├── main.go                  # Entry point ของโปรแกรม และลงทะเบียน Go Services
├── update-and-build.bat     # One-click updater & local builder (Zero-Dependency)
└── Taskfile.yml             # Task orchestration file
```