G-Launcher/Doc/wails3-ipc-bindings-contract.md

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

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

---

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

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 ได้อย่างสมบูรณ์แบบ