# 🔌 สัญญาทางเทคนิค: Wails v3 IPC & Type-Safe Bindings Architecture

เอกสารนี้อธิบายกลไกการสื่อสารข้ามเลเยอร์ (IPC Bridge) ระหว่าง **Go Core Services** และ **React 19 Frontend** ในสถาปัตยกรรม Wails v3 Alpha ของ G-Launcher

---

## 1. ลำดับการลงทะเบียนและส่งผ่านข้อมูล (IPC Gateway Flow)

```mermaid
sequenceDiagram
    autonumber
    participant GoService as Go Service (internal/*-service)
    participant MainGo as main.go (RegisterService)
    participant WailsCLI as wails3 generate bindings
    participant TSBindings as frontend/bindings/@bindings/...
    participant ReactUI as React Component (frontend/src/...)

    GoService->>MainGo: ประกาศ Method พร้อม Input/Output Type ชัดเจน
    MainGo->>MainGo: app.RegisterService(application.NewService(serviceInstance))
    MainGo-->>WailsCLI: Wails CLI ทำการสแกน Abstract Syntax Tree (AST) ของ Go
    WailsCLI->>TSBindings: สร้างไฟล์ TypeScript Definition (.d.ts) และ JS Wrapper
    TSBindings->>ReactUI: นำเข้า (Import) มาใช้ใน React ด้วย Type Safety 100%
    ReactUI->>GoService: เรียกใช้แบบ Async Promise ผ่าน Native Webview IPC Bridge
    GoService-->>ReactUI: คืนค่า Array Result [value1, value2, ...] ตามธรรมเนียม Wails v3
```

---

## 2. ทำไมต้องยึดกฎ "System-First Architecture" อย่างเคร่งครัด?

1. **Static AST Analysis:** Wails v3 สร้าง Bindings โดยการวิเคราะห์โค้ด Go แบบ Static AST หากแก้ไข UI ให้เรียกฟังก์ชันหรือส่งพารามิเตอร์ที่ Go Backend ยังไม่มี โค้ดฝั่ง Frontend จะเกิด Type Error ทันทีตอนรัน `tsc`
2. **Runtime IPC Exception:** หากหลุดจากการตรวจสอบของ TypeScript (เช่น ใช้ `any` หรือเรียกแบบไดนามิก) เมื่อ Webview ส่ง IPC Message ผ่าน MessageHandler ของ Windows WebView2 ไปยัง Go Backend ที่ไม่มีตัวรับ จะทำให้เกิด `Unhandled IPC Error` ส่งผลให้หน้าต่างโปรแกรมค้าง จอดำ หรือเปิดมาเป็นหน้าจอสีขาวสนิท (White Screen of Death)
3. **แนวปฏิบัติที่ถูกต้อง:**
   * ขั้นที่ 1: เพิ่ม Struct หรือ Method ใน Go Backend ก่อน
   * ขั้นที่ 2: รัน `go vet ./...` ให้มั่นใจว่า Backend ไม่มีข้อผิดพลาด
   * ขั้นที่ 3: สั่งรัน `wails3 generate bindings` เพื่อซิงก์ TypeScript Bindings ลง `frontend/bindings/`
   * ขั้นที่ 4: ตรวจสอบ Interface ใน `frontend/bindings/`
   * ขั้นที่ 5: แก้ไข UI และ State Store ใน Frontend ให้สอดคล้องกัน

---

## 3. รายการบริการและผัง Bindings ทั้ง 5 โมดูล

### 1. `AppService` (`@bindings/g-launcher/internal/app-service`)
* `CloseAppAfterTimeout(seconds: number): Promise<void>`
* `GetCurrentLauncherVersion(): Promise<[boolean, string]>`
* `Minimize(): Promise<void>`
* `ToggleMaximize(): Promise<void>`
* `Close(): Promise<void>`

### 2. `FSService` (`@bindings/g-launcher/internal/fs-service`)
* `FileExists(path: string): Promise<boolean>`
* `OpenFileDialog(title: string, filter: string): Promise<string>`
* `SaveGameSelection(path: string): Promise<boolean>`
* `GetSavedGameSelection(): Promise<[boolean, string]>`
* `StartGameProcess(gamePath: string): Promise<[boolean, string]>`

### 3. `GitService` (`@bindings/g-launcher/internal/git-service`)
* `GetLatestLauncherVersion(): Promise<[boolean, string, string]>`
* `UpdateLauncherProgress(version: string): Promise<[boolean, string]>`
* `BuildAndUpdateFromSource(branch: string): Promise<[boolean, string]>`
* `GetLatestProxyVersion(): Promise<[boolean, string, string]>`
* `DownloadProxy(version: string): Promise<[boolean, string]>`
* `GetLatestServerVersion(): Promise<[boolean, string, string]>`
* `DownloadServer(version: string): Promise<[boolean, string]>`

### 4. `DiffService` (`@bindings/g-launcher/internal/diff-service`)
* `ApplyHDiffPatch(targetDir: string, diffFilePath: string): Promise<[boolean, string]>`
* `ApplyZiffPatch(targetDir: string, ziffFilePath: string): Promise<[boolean, string]>`
* `VerifyChunkChecksum(filePath: string, expectedHash: string): Promise<boolean>`

### 5. `LanguageService` (`@bindings/g-launcher/internal/language-service`)
* `InstallThaiPatch(gameDir: string): Promise<[boolean, string]>`
* `UninstallThaiPatch(gameDir: string): Promise<[boolean, string]>`
* `CheckThaiPatchStatus(gameDir: string): Promise<[boolean, boolean]>`

---

## 4. ผลการตรวจสอบความสมบูรณ์ (Verification Status)
* คำสั่ง `wails3 generate bindings` สแกนพบ: **470 Packages, 5 Services, 41 Methods, 0 Errors**
* โค้ดฝั่ง React คอมไพล์ผ่าน TypeScript Check (`tsc`) และ Vite Build ได้อย่างสมบูรณ์แบบ