ส่งต่องาน 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 ผ่าน”, “วางไฟล์แล้ว” และ “ผู้ใช้ยืนยันผลจริงแล้ว” ออกจากกันอย่างเด็ดขาด

กฎเหล็กสถาปัตยกรรม:

แก้ที่ Go Backend (internal/, pkg/) ก่อน Frontend UI เสมอ และต้องรัน go vet ./... ผ่าน 100% ก่อนแตะ UI

ห้าม Hardcode IP, URL, Port, หรือ Drive Letter ใดๆ ทั้งสิ้น (รวมไว้ที่ pkg/constant/constant.go)

วงจรอัปเดต: โหลดลง 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 และ 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%:

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

12 KiB Raw Blame History