# 🧩 สัญญาทางเทคนิค: กลไกการแพตช์ไฟล์ตัวเกม (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`](../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` ขนาดใหญ่ของตัวเกมจริง ต้องรอการทดสอบร่วมกับไฟล์แพตช์จริงในสภาพแวดล้อมของผู้ใช้