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

2026-10-30 21:40:42 +07:00
1 parent 3411e5b058
commit fc262f8331
@@ -0,0 +1,54 @@
+# 🧰 สัญญาทางเทคนิค: ระบบจัดการ Portable MinGit Runtime
+
+เอกสารนี้อธิบายกลไกของ **Portable MinGit** ใน G-Launcher ซึ่งช่วยให้ระบบสามารถรันคำสั่ง Git (เช่น Git Clone, Git Fetch, Git Checkout) ได้บนคอมพิวเตอร์ของผู้ใช้ทั่วไป แม้ว่าในเครื่องจะไม่ได้ติดตั้งโปรแกรม Git หรือไม่มีสิทธิ์ Administrator ก็ตาม
+
+---
+
+## 1. ที่มาและปัญหาเดิม (Background & Problem Statement)
+
+1. ผู้เล่นเกมทั่วไปส่วนใหญ่ไม่มีโปรแกรม Git สำหรับนักพัฒนาติดตั้งอยู่ในเครื่อง
+2. ตัวติดตั้ง Git for Windows ปกติต้องการสิทธิ์ Administrator (UAC Prompt) ซึ่งสร้างความยุ่งยากให้แก่ผู้ใช้งาน
+3. ตัวอัปเดต Launcher และระบบดาวน์โหลดเซิร์ฟเวอร์/พร็อกซี จำเป็นต้องใช้ Git ในการดึงข้อมูล
+
+---
+
+## 2. ลำดับการตรวจสอบและเตรียม Git Runtime (Discovery Order)
+
+ใน [`internal/git-service/git_runtime.go`](../internal/git-service/git_runtime.go) ฟังก์ชัน `ensureGit()` ทำงานตามลำดับความสำคัญดังนี้:
+
+```
+[ร้องขอ Git Executable]
+          │
+          ▼
+1. ตรวจสอบ System PATH (exec.LookPath("git"))
+   ├── พบ -> คืนพาธของ Git ในเครื่องทันที (เช่น C:\Program Files\Git\cmd\git.exe)
+   │
+   └── ไม่พบ -> เข้าสู่ขั้นตอนที่ 2
+          │
+          ▼
+2. ตรวจสอบโฟลเดอร์พกพาภายใน (tools/mingit/cmd/git.exe)
+   ├── พบ -> นำพาธนี้ไปใช้งานทันที
+   │
+   └── ไม่พบ -> เข้าสู่ขั้นตอนที่ 3
+          │
+          ▼
+3. ดาวน์โหลด Portable MinGit x64 อัตโนมัติ
+   ├── ดึงข้อมูล Release ล่าสุดจาก GitHub API:
+   │   https://api.github.com/repos/git-for-windows/git/releases/latest
+   ├── กรองหาไฟล์แพ็กเกจ: MinGit-*-64-bit.zip
+   ├── ดาวน์โหลดลงไฟล์ชั่วคราว os.CreateTemp
+   ├── แตกไฟล์ Zip ลงโฟลเดอร์เป้าหมาย
+   └── คืนค่าพาธ git.exe พร้อมใช้งาน
+```
+
+---
+
+## 3. การป้องกัน Terminal Freeze (Non-Interactive Terminal Execution)
+
+เมื่อโปรแกรม Launcher หรือสคริปต์อัตโนมัติเรียกใช้คำสั่ง Git หาก Git ตรวจพบว่าต้องการรหัสผ่านหรือการยืนยันตัวตน มันจะพยายามเปิด Interactive TTY Prompt ซึ่งส่งผลให้โปรเซสของ Launcher **ค้างอย่างถาวร (Hang/Freeze)**:
+
+### แนวทางป้องกันที่นำมาใช้:
+1. **ตั้งค่าตัวแปรสภาพแวดล้อม:**
+   * ใน Go Backend: `cmd.Env = append(os.Environ(), "GIT_TERMINAL_PROMPT=0")`
+   * ใน PowerShell: `$env:GIT_TERMINAL_PROMPT = "0"`
+2. **ผลลัพธ์:** หาก Git ต้องการการยืนยันตัวตนแต่ไม่สามารถทำได้ Git จะ Return Error ออกมาทันทีแทนที่จะค้าง ทำให้ระบบสามารถดักจับและส่ง Error ไปแจ้งเตือนบน UI ได้อย่างถูกต้อง