G-Launcher/AGENTS.md

📜 G-Launcher Development Rules & Engineering Guidelines

กฎและแนวทางการพัฒนา G-Launcher จากบทเรียนโปรเจกต์เดิมและคำแนะนำของ Horoyoi-san

---

1. 🏗️ แก้ที่ระบบหลังบ้านก่อน UI เสมอ (System-First Architecture)

• คำแนะนำจาก Horoyoi: "ระบบมันรองรับ build zig แนะนำตอนแก้ ให้แก้ที่ระบบก่อน แล้วค่อยไปแก้ UI หน้าต่างต่างๆ ของ launcher ไม่งั้นเดี๋ยวพัง"
• แนวปฏิบัติ:
  1. ทุกครั้งที่เพิ่มฟีเจอร์หรือแก้ไข logic ให้เริ่มที่ Go Backend (internal/, pkg/, main.go) ให้เสร็จสิ้น
  2. รัน go vet ./... เพื่อให้แน่ใจว่าไม่มี type error หรือ compilation error
  3. Generate หรืออัปเดต TypeScript Bindings (@bindings/...)
  4. จากนั้นจึงค่อยไปแก้ที่ Frontend UI (frontend/src/) เพื่อเชื่อมต่อกับ API / Event ของ Backend
  5. เหตุผล: Wails v3 มี Bindings และ Event IPC ที่ผูกกันแน่น หากแก้ UI ก่อนโดยที่ Backend ยังไม่พร้อม หน้าต่าง Launcher จะ crash หรือเกิด runtime exception ทันที

---

2. 🚫 ห้าม Hardcode เด็ดขาด (Strict No-Hardcoding Rule)

• ห้ามฝังค่าต่อไปนี้ในโค้ด logic โดยตรง:
  • URL, Domain, IP Address, หรือ Port (เช่น API Endpoint, Git Release URLs, Proxy URLs)
  • File Path สัมบูรณ์ (ห้ามใส่ C:\... หรือ Drive Letter ใดๆ)
  • ชื่อไฟล์หรือโฟลเดอร์เฉพาะทางที่อาจเปลี่ยนแปลงได้
• แนวปฏิบัติ:
  • รวมศูนย์ค่า Configuration ไว้ที่ pkg/constant/constant.go หรือไฟล์ Configuration กลาง
  • สำหรับ Path ให้ใช้ filepath.Join(...) เสมอ และเก็บข้อมูลผู้ใช้ไว้ที่ os.UserConfigDir() (%APPDATA%)
  • เปิดช่องให้ผู้ใช้สามารถปรับแต่ง URL เซิร์ฟเวอร์, พร็อกซี หรือพารามิเตอร์ของเกมได้ผ่าน UI Settings หรือ Config File

---

3. 🏷️ การเปลี่ยนชื่อและ References (Refactoring & Naming Rule)

• คำแนะนำจาก Horoyoi: "ส่วนชื่อที่เป็น sunbringer หรือชื่อผมค่อยไปเปลี่ยนทีหลังนะ"
• แนวปฏิบัติ:
  • ห้ามใช้วิธี Find-and-Replace ชื่อโปรเจกต์เดิม (เช่น sunbringer, firefly) แบบสุ่มสี่สุ่มห้าทั่วทั้งโปรเจกต์ เพราะอาจกระทบ internal protocol, protobuf identifier, build manifest หรือ package bindings
  • แยก User-Facing Branding (เช่น ชื่อหน้าต่าง, Title, Tooltip, Config metadata) ออกจาก System/Package naming ให้ชัดเจน
  • เปลี่ยนชื่อส่วนที่จำเป็นเมื่อระบบ core นิ่งแล้วเท่านั้น

---

4. 🛡️ ความปลอดภัยของข้อมูลและการ Rollback (Data Safety & Rollback)

• บทเรียนจาก GaC-hkrpg-go / Ananta:
  • ไฟล์ตัวเกม Hoyoverse / Unity มีขนาดใหญ่มากและเสียหายได้ง่าย
  • Safe Backup: ก่อนจะ Patch, แก้ไข หรือเขียนทับไฟล์ใดๆ ของเกม (เช่น .dll, .exe, asset binaries) จะต้องสำรองไฟล์เดิมไว้เป็นนามสกุล .backup เสมอ
  • Atomic Rollback: หากการ Copy, Verify หรือ Download เกิดความล้มเหลว ระบบจะต้อง Rollback นำไฟล์สำรองกลับคืนมาทันที ห้ามทิ้งไฟล์เกมให้อยู่ในสภาพเสียหาย
  • Atomic Write สำหรับ Config: การบันทึกไฟล์คอนฟิก (เช่น game-selection.json) ให้เขียนเป็น .tmp ก่อน แล้วใช้ Windows API MoveFileEx เพื่อป้องกันไฟล์เสียหายจากไฟดับหรือ crash

---

5. 🧰 Zero-Dependency & Portability First

• ไม่สมมติว่าเครื่องผู้ใช้ปลายทางมี Git, Zig หรือ 7-Zip อยู่ใน PATH
• ต้องมี Toolchain Helper และ Portable Runtimes ในตัว:
  • MinGit: ใช้ระบบ Auto-download MinGit portable หากตรวจไม่พบ Git ในระบบ
  • Tools Extraction: ดึง binary tools (7za.exe, hpatchz.exe, zift.exe) ออกจาก embed assets อัตโนมัติเมื่อเริ่มโปรแกรม

---

6. 🌿 Git Workflow & Code Hygiene

• Active Branch: ทำงานและ Commit บน branch Dev เท่านั้น
• Pre-commit Verification:
  • ฝั่ง Go: go vet ./... ต้องผ่าน 100%
  • ฝั่ง Frontend: npm run build ต้องผ่าน 100%
• Clean Repository: รักษาความสะอาดของ .gitignore ห้าม commit ไฟล์ _references/, dist/, node_modules/, bin/, temp/, หรือ server/ เข้าสู่ Git

---

7. 🚀 สถาปัตยกรรมระบบอัปเดต (Updater Rule)

• กลไก 4 ขั้นตอน:
  1. ดาวน์โหลด/Clone โค้ดลงโฟลเดอร์ชั่วคราว (temp/build_workspace หรือ os.MkdirTemp)
  2. คอมไพล์ Frontend และ Go Backend ภายในโฟลเดอร์ Temp
  3. นำไฟล์ใหม่มาแทนที่ตัวเดิม (bin/G-Launcher.exe) พร้อมระบบสำรอง .old และ Rollback
  4. ทำลายและลบโฟลเดอร์ Temp ทิ้ง 100% ผ่านบล็อก finally / defer ห้ามทิ้งไฟล์ขยะตกค้าง

---

8. 📚 เอกสารความจำโครงการสำหรับ AI (Persistent Context & Compaction Recovery)

• โฟลเดอร์ Doc/ ถูกสร้างขึ้นเพื่อเก็บรายละเอียดทั้งหมดของโปรเจกต์
• เมื่อใดก็ตามที่ AI ฟื้นตัวหลังจากการทำ Compact บริบท หรือเริ่มเซสชันใหม่:
  • ให้ AI อ่านไฟล์ในโฟลเดอร์ Doc/ ทันที เพื่อคืนความจำและทำความเข้าใจกฎ สถาปัตยกรรม และประวัติของระบบก่อนเริ่มทำงานเสมอ