G-Launcher/Doc/diff-patching-engine.md

🧩 สัญญาทางเทคนิค: กลไกการแพตช์ไฟล์ตัวเกม (Diff & Patching Engine)

เอกสารนี้ระบุรายละเอียดการทำงานของระบบประมวลผลไฟล์ส่วนต่าง (Delta Patching) และการขยายแพ็กเกจข้อมูลเกมใน G-Launcher ซึ่งผสานเทคโนโลยีจาก Firefly Launcher และ Sunbringer เข้าด้วยกัน

---

1. ภาพรวมของเครื่องมือและฟอร์แมตที่รองรับ

รูปแบบไฟล์	เครื่องมือประมวลผล	ที่มาของโค้ด	หน้าที่และการทำงาน
.hdiff	bin/hpatchz.exe	Firefly / Hoyoverse	ใช้สำหรับอัปเดตไฟล์เกมแบบไบนารีเดลต้า (Byte-level Delta Patch)
.ziff	bin/zift.exe	Horoyoi-san (Sunbringer)	อัปเดตไฟล์เกมแบบบีบอัดพิเศษ Zift archive สำหรับม็อดและไฟล์แพตช์เฉพาะ
.zip / .7z	bin/7za.exe	7-Zip Portable	คลายไฟล์ข้อมูลเกม แพตช์เสียง และแพ็กเกจเซิร์ฟเวอร์/พร็อกซี
Protobuf Chunk	pkg/firefly/	Firefly Engine	อ่านและถอดรหัส Hoyoverse manifest chunk สำหรับตรวจสอบความสมบูรณ์ของไฟล์

---

2. กลไกการสกัดเครื่องมือจาก Embed Assets (Tool Extraction Lifecycle)

เพื่อบรรลุเป้าหมาย Zero-Dependency ผู้ใช้ปลายทางไม่จำเป็นต้องมี 7-Zip หรือ HDiffz ติดตั้งในเครื่องล่วงหน้า:

1. ไบนารีของเครื่องมือทั้งหมดถูกฝัง (Embed) อยู่ในโค้ด Go ผ่าน //go:embed assets/* ใน main.go
2. เมื่อ Launcher เริ่มทำงาน ฟังก์ชันตรวจสอบจะสแกนโฟลเดอร์ bin/:
   • หากตรวจไม่พบ bin/7za.exe, bin/hpatchz.exe หรือ bin/zift.exe
   • ระบบจะดึงไบต์จากหน่วยความจำออกมาเขียนเป็นไฟล์ executable ในโฟลเดอร์ bin/ อัตโนมัติ พร้อมตั้งสิทธิ์การรัน
3. ไฟล์ที่ได้รับการดูแล:
   • bin/7za.exe, bin/7za.dll, bin/7zxa.dll
   • bin/hpatchz.exe
   • bin/zift.exe

---

3. กฎความปลอดภัยของข้อมูลตัวเกม (Safe Backup & Atomic Rollback)

ไฟล์ตัวเกมมีขนาดใหญ่หลายสิบกิกะไบต์และเสียหายได้ง่าย หากการแพตช์ล้มเหลวระหว่างทาง ห้ามทิ้งไฟล์ให้อยู่ในสภาพพัง:

[เริ่มต้นแพตช์ไฟล์: StarRailBase.dll]
          │
          ▼
1. สำรองไฟล์เดิม (Safe Backup)
   └── คัดลอก StarRailBase.dll -> StarRailBase.dll.backup
          │
          ▼
2. ดำเนินการแพตช์ด้วย HPatchz หรือ Zift
   └── hpatchz.exe StarRailBase.dll patch.hdiff StarRailBase.dll.tmp
          │
          ▼
3. ตรวจสอบความถูกต้อง (Checksum Verification)
   ├── หากผลลัพธ์ตรงกับ Checksum ที่กำหนด:
   │   ├── สลับ StarRailBase.dll.tmp -> StarRailBase.dll
   │   └── ลบไฟล์สำรอง StarRailBase.dll.backup ทิ้ง
   │
   └── หากเกิดข้อผิดพลาด / Checksum ไม่ตรง:
       ├── ลบไฟล์ชั่วคราว StarRailBase.dll.tmp ทิ้งทันที
       ├── Atomic Rollback: กู้คืนไฟล์จาก StarRailBase.dll.backup
       └── ส่งข้อความแจ้งเตือนความล้มเหลวให้ผู้ใช้ทราบอย่างชัดเจน

---

4. สถานะการทดสอบและข้อจำกัด

• ความพร้อมของระบบ: โครงสร้าง Service และ Command Execution เขียนเสร็จสมบูรณ์ 100% ใน internal/diff-service/
• ขอบเขตที่รอการยืนยัน: การทดสอบด้วยไฟล์ .ziff และ .hdiff ขนาดใหญ่ของตัวเกมจริง ต้องรอการทดสอบร่วมกับไฟล์แพตช์จริงในสภาพแวดล้อมของผู้ใช้