G-Launcher/Doc/G-LAUNCHER-HANDOFF.md

# ส่งต่องาน G-Launcher (G-LAUNCHER-HANDOFF)
> เอกสารส่งต่อสถานะทางเทคนิค ฉบับสมบูรณ์สำหรับ AI Agent และนักพัฒนา
> อ้างอิงมาตรฐานการบันทึกสถานะตามแบบฉบับ `GaC-hkrpg-go/docs`

---

> **อ่านหัวข้อนี้ก่อนเริ่มงานทุกครั้ง (CRITICAL NOTICE):**
> - **Active Branch:** ทำงานบนสาขา **`Dev`** เท่านั้น (ห้ามแตะต้องหรือ push ตรงเข้า main)
> - **Remote URL:** `https://gaytea.cod-algieba.ts.net/GaCy/G-Launcher.git`
> - **หลักการตัดสินใจ:** แยกคำว่า **“มีโค้ดใน source”**, **“build ผ่าน”**, **“วางไฟล์แล้ว”** และ **“ผู้ใช้ยืนยันผลจริงแล้ว”** ออกจากกันอย่างเด็ดขาด
> - **กฎเหล็กสถาปัตยกรรม:**
>   1. แก้ที่ Go Backend (`internal/`, `pkg/`) ก่อน Frontend UI เสมอ และต้องรัน `go vet ./...` ผ่าน 100% ก่อนแตะ UI
>   2. ห้าม Hardcode IP, URL, Port, หรือ Drive Letter ใดๆ ทั้งสิ้น (รวมไว้ที่ [`pkg/constant/constant.go`](../pkg/constant/constant.go))
>   3. วงจรอัปเดต: **โหลดลง Temp -> Build ใน Temp -> แทนที่ไฟล์เดิม -> ลบ Temp ทิ้ง 100%**

อัปเดตล่าสุด: 30 ตุลาคม 2026 (Asia/Bangkok) | สถานะ Git: Branch `Dev` สะอาด (All clean)

---

## 1. ตารางสรุปสถานะระบบ (System Implementation & Verification Matrix)

| ระบบย่อย (Subsystem) | โค้ดใน Source | Build ผ่าน | Deploy/Run | ยืนยันผลจริง | รายละเอียดทางเทคนิค / ไฟล์อ้างอิง |
| :--- | :---: | :---: | :---: | :---: | :--- |
| **Go Backend Core Services** | ✅ | ✅ | ✅ | ✅ | บริการ 5 ตัวลงทะเบียนใน `main.go` ผ่าน `app.RegisterService` |
| **Wails v3 TypeScript Bindings** | ✅ | ✅ | ✅ | ✅ | สร้างผ่าน `wails3 generate bindings` ลงที่ `frontend/bindings/` |
| **Frontend UI (React 19 + DaisyUI)** | ✅ | ✅ | ✅ | ✅ | React 19 + Vite + Tailwind v4 + DaisyUI v5 คอมไพล์ผ่าน 100% |
| **Auto-Updater & Bootstrap Script** | ✅ | ✅ | ✅ | ✅ | `scripts/bootstrap.ps1` ทำงานแบบ Temp Build + Cleanup 100% |
| **One-Click Batch Launcher** | ✅ | ✅ | ✅ | ✅ | `update-and-build.bat` เรียกใช้ PowerShell Bypass UTF-8 BOM |
| **Go Backend Source Updater** | ✅ | ✅ | ✅ | ⚠️ รอ UI เรียก | `BuildAndUpdateFromSource` ใน `internal/git-service/launcher.go` |
| **Portable MinGit Runtime** | ✅ | ✅ | ✅ | ✅ | `internal/git-service/git_runtime.go` ดึง MinGit x64 อัตโนมัติ |
| **Atomic Game Path Persistence** | ✅ | ✅ | ✅ | ✅ | `internal/fs-service/game-selection.go` ใช้ Windows `MoveFileEx` |
| **Zift Archive Patching (.ziff)** | ✅ | ✅ | ✅ | ⚠️ รอด่านทดสอบ | `internal/diff-service/ziff.go` ครอบ `zift.exe` |
| **HPatchz Delta Patching (.hdiff)** | ✅ | ✅ | ✅ | ⚠️ รอด่านทดสอบ | `internal/diff-service/hpatchz.go` ครอบ `hpatchz.exe` |
| **Thai Mod Engine (ExcelData)** | ✅ | ✅ | ✅ | ⚠️ รอเกมจริง | `internal/language-service/thai-patch.go` มีระบบ `.backup` |
| **Multi-Language (i18n)** | ✅ | ✅ | ✅ | ✅ | 6 ภาษา (`th`, `en`, `ja`, `ko`, `vi`, `zh`) ใน `frontend/public/locales/` |
| **Standalone Tool Extraction** | ✅ | ✅ | ✅ | ✅ | แตกไฟล์ `assets/` (`7za.exe`, `hpatchz.exe`, `zift.exe`) ลง `bin/` |
| **Server Selection & GaCy PS** | ✅ | ✅ | ✅ | ✅ | ปุ่มเลือกเซิร์ฟเวอร์ด้านข้าง + ระบบดาวน์โหลด GaCy-GO (ZIP หรือ standalone sdk/server) |
| **High-Res Branding & Icons** | ✅ | ✅ | ✅ | ✅ | ภาพไอคอน 433x433 คมชัด ไร้รอยแตก, รีแบรนด์เป็น G-Launcher และ GaCy ทั้งหมด |
| **GaCy SRTools Integration** | ✅ | ✅ | ✅ | ✅ | เชื่อมโยง URL เครื่องมือ `https://gacy-srtool.vercel.app/` ทั้ง Header และหน้าหลัก |
| **Diagnostic Logging Subsystem** | ✅ | ✅ | ✅ | ✅ | `pkg/logger` บันทึก `%APPDATA%/g-launcher/logs/launcher.log` พร้อมปุ่มเปิดโฟลเดอร์/คัดลอกใน UI |

---

## 2. กับดักและบทเรียนทางเทคนิคที่ห้ามพลาด (Technical Traps & Pitfalls)

### กับดักที่ 1: Wails v3 Embed Directive ขาดไม่ได้
* **อาการ:** `go build` หรือ `go vet` ฟ้อง `pattern all:frontend/dist: no matching files found`
* **สาเหตุ:** `main.go` มีการประกาศ `//go:embed all:frontend/dist` ซึ่ง Compiler ของ Go จะปฏิเสธการคอมไพล์ทันทีหากโฟลเดอร์ `frontend/dist` ว่างเปล่าหรือไม่มีอยู่จริง
* **แนวทางแก้ไข:** ต้องรัน `npm --prefix frontend run build` ก่อน หรือมีไฟล์ `.gitkeep` วางอยู่ใน `frontend/dist/` เสมอ

### กับดักที่ 2: Windows PowerShell 5.1 กับปัญหา UTF-8 Encoding
* **อาการ:** รัน `powershell -File script.ps1` แล้วพังด้วยข้อผิดพลาดไวยากรณ์ เช่น `Unexpected token '}'` หรือ `You must provide a value expression following the '-' operator`
* **สาเหตุ:** `powershell.exe` (เวอร์ชัน 5.1 เดิมของ Windows) จะอ่านไฟล์ข้อความภาษาไทยด้วย System ANSI Code Page (CP874 หรือ Windows-1252) หากไฟล์ถูกบันทึกเป็น UTF-8 แบบไม่มี BOM ไบต์อักขระภาษาไทยบางตัวจะถูกตีความเป็นเครื่องหมายคำพูด (`"`) หรือเครื่องหมายลบ (`-`) ทำให้ Parser พัง
* **แนวทางแก้ไข:** ไฟล์ `.ps1` ที่มีอักขระสองไบต์หรือภาษาไทย **ต้องบันทึกด้วย UTF-8 with BOM (`[System.Text.Encoding]::UTF8`) เสมอ**

### กับดักที่ 3: Windows Process Lock ขณะอัปเดตตัวเอง
* **อาการ:** `go build` หรือการคัดลอกไฟล์ทับ `bin/G-Launcher.exe` ล้มเหลวด้วย `Access is denied`
* **สาเหตุ:** Windows ห้ามเขียนทับหรือลบ Executable (`.exe`) ที่โปรเซสกำลังทำงานอยู่
* **แนวทางแก้ไข:** **เปลี่ยนชื่อไฟล์เดิมแทน (Rename)** โดยเปลี่ยนชื่อ `G-Launcher.exe` ที่กำลังรันอยู่เป็น `G-Launcher.exe.old` (Windows อนุญาตให้ rename process executable ที่กำลังรันได้) จากนั้นจึงย้ายไฟล์ executable ตัวใหม่เข้ามาเสียบแทนที่ แล้วจึงสั่งเปิดตัวใหม่และลบตัวเก่า

### กับดักที่ 4: Wails v3 Binding Crash หากแก้ UI ก่อน Backend
* **อาการ:** หน้าต่าง Launcher เปิดขึ้นมาแล้วขาวสนิท จอดำ หรือ DevTools คอนโซลขึ้น `Cannot read properties of undefined`
* **สาเหตุ:** Frontend ฝั่ง React เรียกใช้งาน IPC method ผ่าน `@bindings/...` หาก Backend ยังไม่ได้ประกาศ method นั้น หรือ type signature ไม่ตรงกัน Wails IPC Gateway จะเกิด Unhandled Exception
* **แนวทางแก้ไข:** ปฏิบัติตาม **System-First Rule** โดยแก้ Go service ให้เสร็จ -> รัน `go vet ./...` -> รัน `wails3 generate bindings` -> ตรวจดู TypeScript interface -> จึงค่อยเริ่มเขียน UI

### กับดักที่ 5: Git Interactive Terminal Freeze
* **อาการ:** รัน `git push` หรือ `git clone` ผ่านสคริปต์อัตโนมัติแล้วโปรเซสค้าง (Hang) ไม่ยอมสิ้นสุด
* **สาเหตุ:** Git พยายามเปิด Interactive Prompt เพื่อถาม Username/Password ในเทอร์มินัลที่ไม่มี TTY
* **แนวทางแก้ไข:** ต้องตั้งค่า `$env:GIT_TERMINAL_PROMPT = "0"` ใน PowerShell หรือ `os.Setenv("GIT_TERMINAL_PROMPT", "0")` ใน Go ก่อนเรียกคำสั่ง Git เสมอ

### กับดักที่ 6: โครงสร้างไฟล์ GaCy-GO (for ship/sdkserver) และการตัด Firefly Proxy
* **อาการ:** ตัวเกม Star Rail ฟ้อง `Network connection error: Please check your network state, disable any network proxies...` และ Launcher หาเซิร์ฟเวอร์ไม่พบ
* **สาเหตุ:** 
  1. ไฟล์ Zip ของ `gacy 4.6.54.zip` แตกไฟล์ออกมามีโฟลเดอร์ย่อยชื่อ `for ship` บรรจุ `sdkserver-go.exe` หากค้นหาเฉพาะโฟลเดอร์ root จะมองไม่เห็น SDK Server ทำให้ Dispatch Server ไม่ถูกเปิด
  2. โค้ดเดิมยังคงสั่งรัน `firefly-go-proxy.exe` เข้าไปดักจับและเปลี่ยนระบบ Proxy ของ Windows ทำให้ Client ของ Star Rail ตรวจจับว่ามี Proxy แปลกปลอมและปฏิเสธการเชื่อมต่อ
* **แนวทางแก้ไข:**
  1. ปรับปรุง `FindServerExecutables()` ใน Go ให้ค้นหาไฟล์ไบนารีแบบ **Recursive Search** ทุกโฟลเดอร์ย่อย (`for ship`, `sdkserver`) และทำ Auto-Sync ไฟล์จาก `for ship` ขึ้นมาที่ root ของ `server/`
  2. ตัดระบบ `firefly-go-proxy` ออกจากการเริ่มเล่น GaCy PS 100% โดยเรียงลำดับการเปิด: **SDK Server (Dispatch) -> รอ 800ms -> Game Server -> รอ 1000ms -> เปิดตัวเกม**

---

## 3. รายละเอียดสถาปัตยกรรมระบบอัปเดต (Isolated Updater Architecture)

กระบวนการอัปเดตทั้งใน [`scripts/bootstrap.ps1`](../scripts/bootstrap.ps1) และ [`internal/git-service/launcher.go`](../internal/git-service/launcher.go) ปฏิบัติตามกฎ 4 ขั้นตอน:

```
[ผู้ใช้สั่งอัปเดต]
       │
       ▼
1. โหลดลงโฟลเดอร์ชั่วคราว (Temp Workspace)
   ├── สร้างโฟลเดอร์: temp/build_workspace หรือ os.MkdirTemp
   └── Clone ซอร์สโค้ด: git clone --depth 1 --branch Dev <RepoUrl> <TempDir>
       │
       ▼
2. คอมไพล์ในโฟลเดอร์ชั่วคราว (Isolated Build)
   ├── npm install --no-audit --no-fund
   ├── npm run build (คอมไพล์ React 19 Frontend)
   ├── go mod tidy
   ├── wails3 generate syso (สร้าง Windows Manifest & Application Icon)
   └── go build -tags production -trimpath -ldflags="-w -s -H windowsgui" -o <TempDir>/bin/G-Launcher.exe .
       │
       ▼
3. สลับไฟล์ไบนารี (Atomic Swap & Rollback)
   ├── ตรวจสอบว่าไฟล์ไบนารีใหม่มีขนาด > 0 ไบต์
   ├── เปลี่ยนชื่อ: bin/G-Launcher.exe -> bin/G-Launcher.exe.old
   ├── ย้ายไฟล์ใหม่: <TempDir>/bin/G-Launcher.exe -> bin/G-Launcher.exe
   ├── หากล้มเหลว: ย้าย .old กลับมาทันที (Atomic Rollback)
   └── หากสำเร็จ: ลบไฟล์ .old ทิ้ง
       │
       ▼
4. ทำลายโฟลเดอร์ชั่วคราว 100% (Purge Temp)
   └── บล็อก finally / defer os.RemoveAll ทำลายโฟลเดอร์ Temp ทิ้งทั้งหมด ห้ามทิ้งไฟล์ขยะ
```

---

## 4. Checklist สำหรับการตรวจสอบก่อน Commit / Push

ก่อนจะบันทึก Commit ใดๆ ในโปรเจกต์นี้ ให้ตรวจสอบ Checklist ต่อไปนี้ให้ครบ 100%:

1. [ ] อยู่บน Git branch **`Dev`** (`git branch --show-current` คืนค่า `Dev`)
2. [ ] ไม่มี URL, IP Address, หรือ Absolute Path (`C:\...`) ฮาร์ดโค้ดอยู่ในไฟล์ logic ใดๆ
3. [ ] ฝั่ง Go Backend: รัน `go vet ./...` ผ่าน 100% ไม่มีข้อผิดพลาด
4. [ ] ฝั่ง TypeScript/React: รัน `npm --prefix frontend run build` ผ่าน 100%
5. [ ] รัน `git status` แล้วไม่มีไฟล์ขยะ เช่น `tools/`, `node_modules/`, `bin/`, `temp/`, หรือ `*.old` ติดเข้ามาใน Staging Area