G-Launcher/Doc/ARCHITECTURE.md

🏗️ G-Launcher Architecture & Technical Reference

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

---

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

graph TD
    subgraph Frontend["Frontend Layer (React 19 + TypeScript + Vite)"]
        UI["React UI (DaisyUI 5 + Tailwind 4)"]
        Stores["Zustand Stores (launcherStore, modalStore)"]
        Bindings["Auto-generated TypeScript Bindings (@bindings/...)"]
        UI <--> Stores
        Stores <--> Bindings
    end

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

    subgraph Backend["Backend Layer (Go 1.24 Core Services)"]
        AppSvc["AppService (Window controls, Version info)"]
        FSSvc["FSService (Safe IO, Game path persistence)"]
        GitSvc["GitService (Updater, MinGit runtime, Proxies)"]
        DiffSvc["DiffService (Protobuf diffs, HPatchz, Zift)"]
        LangSvc["LanguageService (Thai asset modding & ExcelData)"]
        
        IPCBridge <--> AppSvc
        IPCBridge <--> FSSvc
        IPCBridge <--> GitSvc
        IPCBridge <--> DiffSvc
        IPCBridge <--> LangSvc
    end

    subgraph OS["OS & Filesystem Integration"]
        GameExe["Game Process (StarRail.exe / Unity)"]
        ConfigDir["%APPDATA%/g-launcher (game-selection.json)"]
        ToolsDir["tools/ (MinGit, Go, Node.js portable)"]
        AssetsDir["bin/ (7za.exe, hpatchz.exe, zift.exe)"]
    end

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

---

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

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

1. AppService

• จัดการวงจรชีวิตของหน้าต่าง Launcher:
  • ย่อหน้าต่าง (Minimize()), ขยาย/คืนขนาด (ToggleMaximize()), ปิดหน้าต่าง (Close())
  • ปิดโปรแกรมอัตโนมัติเมื่อตั้งเวลา (CloseAppAfterTimeout(seconds))
  • คืนค่าเวอร์ชันปัจจุบันของ Launcher (GetCurrentLauncherVersion())

2. FSService

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

3. GitService

• 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

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

5. LanguageService

• 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