docs: enrich Doc/ with deep-dive technical contracts, traps, and handoff

2026-10-30 21:40:42 +07:00
1 parent 3411e5b058
commit fc262f8331
@@ -0,0 +1,112 @@
+# ส่งต่องาน 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/` |
+
+---
+
+## 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 เสมอ
+
+---
+
+## 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