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

Doc/diff-patching-engine.md

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