docs: add Doc folder with architecture, rules, updater lifecycle, and project memory
This commit is contained in:
CAtlas0784 committed
1 parent
0a97749a1c
commit
3411e5b058
7 files changed
+414
No files matched your search
@@ -58,3 +58,19 @@
|
||||
* ฝั่ง 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/`](file:///c:/Users/Phitchayut/Desktop/G%20Launcher/Doc/README.md) ถูกสร้างขึ้นเพื่อเก็บรายละเอียดทั้งหมดของโปรเจกต์
|
||||
* **เมื่อใดก็ตามที่ AI ฟื้นตัวหลังจากการทำ Compact บริบท หรือเริ่มเซสชันใหม่:**
|
||||
* **ให้ AI อ่านไฟล์ในโฟลเดอร์ `Doc/` ทันที** เพื่อคืนความจำและทำความเข้าใจกฎ สถาปัตยกรรม และประวัติของระบบก่อนเริ่มทำงานเสมอ
|
||||
@@ -0,0 +1,128 @@
|
||||
# 🏗️ G-Launcher Architecture & Technical Reference
|
||||
|
||||
เอกสารนี้อธิบายสถาปัตยกรรมภายในของ **G-Launcher** ซึ่งสร้างขึ้นด้วย **Wails v3 Alpha** ผสานขุมพลังของ **Go Backend** และ **React 19 + TypeScript Frontend**
|
||||
|
||||
---
|
||||
|
||||
## 🏛️ ภาพรวมระดับสูง (System Overview)
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
subgraph Frontend["Frontend Layer (React 19 + TypeScript + Vite)"]
|
||||
UI["React UI (DaisyUI 5 + Tailwind 4)"]
|
||||
Stores["Zustand Stores (launcherStore, modalStore)"]
|
||||
Bindings["Auto-generated TypeScript Bindings (@bindings/...)"]
|
||||
UI <--> Stores
|
||||
Stores <--> Bindings
|
||||
end
|
||||
|
||||
subgraph IPC["Wails v3 IPC & Event Gateway"]
|
||||
IPCBridge["Typed IPC Calls & Event Subscriptions"]
|
||||
Bindings <--> IPCBridge
|
||||
end
|
||||
|
||||
subgraph Backend["Backend Layer (Go 1.24 Core Services)"]
|
||||
AppSvc["AppService (Window controls, Version info)"]
|
||||
FSSvc["FSService (Safe IO, Game path persistence)"]
|
||||
GitSvc["GitService (Updater, MinGit runtime, Proxies)"]
|
||||
DiffSvc["DiffService (Protobuf diffs, HPatchz, Zift)"]
|
||||
LangSvc["LanguageService (Thai asset modding & ExcelData)"]
|
||||
|
||||
IPCBridge <--> AppSvc
|
||||
IPCBridge <--> FSSvc
|
||||
IPCBridge <--> GitSvc
|
||||
IPCBridge <--> DiffSvc
|
||||
IPCBridge <--> LangSvc
|
||||
end
|
||||
|
||||
subgraph OS["OS & Filesystem Integration"]
|
||||
GameExe["Game Process (StarRail.exe / Unity)"]
|
||||
ConfigDir["%APPDATA%/g-launcher (game-selection.json)"]
|
||||
ToolsDir["tools/ (MinGit, Go, Node.js portable)"]
|
||||
AssetsDir["bin/ (7za.exe, hpatchz.exe, zift.exe)"]
|
||||
end
|
||||
|
||||
FSSvc --> GameExe
|
||||
FSSvc --> ConfigDir
|
||||
GitSvc --> ToolsDir
|
||||
DiffSvc --> AssetsDir
|
||||
LangSvc --> AssetsDir
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧩 บริการหลังบ้านทั้ง 5 ตัว (Go Backend Services)
|
||||
|
||||
บริการทั้งหมดถูกประกาศและลงทะเบียนใน [`main.go`](../main.go) ผ่าน `app.RegisterService(...)`:
|
||||
|
||||
### 1. [`AppService`](../internal/app-service/app.go)
|
||||
* จัดการวงจรชีวิตของหน้าต่าง Launcher:
|
||||
* ย่อหน้าต่าง (`Minimize()`), ขยาย/คืนขนาด (`ToggleMaximize()`), ปิดหน้าต่าง (`Close()`)
|
||||
* ปิดโปรแกรมอัตโนมัติเมื่อตั้งเวลา (`CloseAppAfterTimeout(seconds)`)
|
||||
* คืนค่าเวอร์ชันปัจจุบันของ Launcher (`GetCurrentLauncherVersion()`)
|
||||
|
||||
### 2. [`FSService`](../internal/fs-service/)
|
||||
* **`game-selection.go`:** บันทึกและอ่านพาธตัวเกมที่ผู้ใช้เลือก โดยใช้วิธี **Atomic Write** เขียนลงไฟล์ชั่วคราวแล้วเรียกใช้ Windows API `MoveFileEx` ป้องกันไฟล์เสีย
|
||||
* **`dialog.go`:** เปิด Native File Dialog ให้ผู้ใช้เลือกไฟล์ตัวเกม (`StarRail.exe`)
|
||||
* **`file.go`:** ตรวจสอบความมีอยู่ของไฟล์ (`FileExists()`), ตรวจสอบสิทธิ์, ค้นหาโฟลเดอร์
|
||||
|
||||
### 3. [`GitService`](../internal/git-service/)
|
||||
* **`git_runtime.go`:** ระบบตรวจสอบ Git ในเครื่อง หากไม่มีจะดาวน์โหลด **Portable MinGit** มาไว้ที่โฟลเดอร์เครื่องมืออัตโนมัติ
|
||||
* **`launcher.go`:** ระบบอัปเดตตัว Launcher:
|
||||
* ตรวจสอบอัปเดตผ่าน `latest.json` manifest หรือ Releases API
|
||||
* อัปเดตผ่านการคอมไพล์จากโค้ดต้นทาง (`BuildAndUpdateFromSource`) โดยดาวน์โหลดลง Temp, บิลด์ใน Temp, สลับแทนที่ตัวเก่าด้วย `selfupdate.Apply`, และลบ Temp ทิ้ง
|
||||
* **`proxy.go` & `server.go`:** ดาวน์โหลดและคลายแพ็กเกจ Local Proxy และ Local Server จาก Release endpoints พร้อมรายงานความคืบหน้าแบบมัลติเธรด
|
||||
|
||||
### 4. [`DiffService`](../internal/diff-service/)
|
||||
* **`hpatchz.go`:** เรียกใช้ `hpatchz.exe` เพื่อแพตช์ไฟล์แบบ Delta diff (`.hdiff`)
|
||||
* **`ziff.go`:** รองรับการแพตช์ไฟล์ฟอร์แมต Zift (`.ziff`) ผ่าน `zift.exe` ที่ผสานมาจาก Sunbringer
|
||||
* **`chunk.go`:** ถอดรหัสและประมวลผล Hoyoverse Protobuf chunk manifests
|
||||
|
||||
### 5. [`LanguageService`](../internal/language-service/)
|
||||
* **`thai-patch.go`:** ระบบติดตั้ง/ถอนการติดตั้งม็อดภาษาไทยสำหรับเกม โดยแก้ไบต์ในไฟล์ `ExcelData`
|
||||
* สำรองไฟล์เดิมเป็น `.backup` ก่อนลงมือแก้ไขเสมอ เพื่อให้สามารถกู้คืนได้แบบ Atomic
|
||||
|
||||
---
|
||||
|
||||
## 🎨 สถาปัตยกรรมส่วนหน้า (Frontend Architecture)
|
||||
|
||||
* **Framework:** React 19 + TypeScript + Vite
|
||||
* **UI & Styles:** TailwindCSS v4 + DaisyUI v5 (ธีมมินิมอล โมเดิร์น ปรับแต่งจาก Firefly)
|
||||
* **State Management:** Zustand:
|
||||
* `launcherStore.ts`: เก็บสถานะตัวเกม, พาธ, เซิร์ฟเวอร์, พร็อกซี, ความเร็วการดาวน์โหลด
|
||||
* `modalStore.ts`: ควบคุมการเปิด/ปิด Modal หน้าต่างแจ้งเตือนและอัปเดต
|
||||
* **Localization (i18n):** รองรับ 6 ภาษา (`th`, `en`, `zh`, `ja`, `ko`, `vi`)
|
||||
* **IPC Bindings:** สร้างจากคำสั่ง `wails3 generate bindings` ส่งโค้ดมาที่ `frontend/bindings/` เป็น Type-safe functions ที่เรียกตรงเข้าสู่ Go Backend ได้ทันที
|
||||
|
||||
---
|
||||
|
||||
## 📦 โครงสร้างไฟล์และโฟลเดอร์หลัก
|
||||
|
||||
```
|
||||
G-Launcher/
|
||||
├── Doc/ # 📚 เอกสารสถาปัตยกรรมและคู่มือการพัฒนาสำหรับนักพัฒนาและ AI
|
||||
├── build/ # คอนฟิกการบิลด์, ไอคอน, Windows Manifest, Taskfile
|
||||
├── frontend/ # React 19 Frontend (Vite, TypeScript, Tailwind)
|
||||
│ ├── bindings/ # Auto-generated IPC Bindings จาก Wails v3
|
||||
│ ├── public/ # Static assets & localization files (locales/*.json)
|
||||
│ └── src/ # React components, pages, stores, hooks
|
||||
├── internal/ # โค้ด Backend ภาษา Go (แบ่งตาม Domain Services)
|
||||
│ ├── app-service/ # Window controls & version logic
|
||||
│ ├── diff-service/ # HPatchz & Zift delta patching
|
||||
│ ├── fs-service/ # Safe filesystem & game path persistence
|
||||
│ ├── git-service/ # Self-updater, MinGit, server/proxy downloaders
|
||||
│ └── language-service/ # Thai patch modding & asset recovery
|
||||
├── pkg/ # แพ็กเกจ Go ที่ใช้ร่วมกัน
|
||||
│ ├── constant/ # รวมศูนย์ URL, ค่าคงที่, คอนฟิก (ห้าม Hardcode)
|
||||
│ ├── firefly/ # Protobuf parser & chunk utilities
|
||||
│ ├── hpatchz/ # HPatchz CLI wrappers
|
||||
│ └── sevenzip/ # 7-Zip decompression helpers
|
||||
├── proto/ # Protobuf definitions
|
||||
├── scripts/ # สคริปต์ Release และ Bootstrap (bootstrap.ps1)
|
||||
├── tools/ # (Ignored) โฟลเดอร์เก็บ Portable runtimes (MinGit, Go, Node)
|
||||
├── AGENTS.md # กฎระเบียบและแนวทางการพัฒนาสำหรับ AI Agent
|
||||
├── build.bat # สคริปต์คอมไพล์สำหรับ Windows
|
||||
├── main.go # Entry point ของโปรแกรม และลงทะเบียน Go Services
|
||||
├── update-and-build.bat # One-click updater & local builder (Zero-Dependency)
|
||||
└── Taskfile.yml # Task orchestration file
|
||||
```
|
||||
@@ -0,0 +1,62 @@
|
||||
# 📜 G-Launcher Development Rules & Engineering Guidelines
|
||||
> กฎเหล็ก 6 ข้อและแนวทางปฏิบัติที่ต้องปฏิบัติตามอย่างเคร่งครัด โดยไม่มีข้อยกเว้น
|
||||
|
||||
---
|
||||
|
||||
### 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 ด้วย `wails3 generate 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`](../pkg/constant/constant.go)
|
||||
* สำหรับ 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
|
||||
* **Binary Replacement Safety:** การอัปเดตไฟล์ `.exe` ของ Launcher ต้องเปลี่ยนชื่อตัวเก่าเป็น `.old` ก่อนสลับไฟล์ใหม่เข้ามา หากล้มเหลวต้อง Rollback คืนค่าเดิมทันที
|
||||
|
||||
---
|
||||
|
||||
### 5. 🧰 Zero-Dependency & Portability First
|
||||
* ไม่สมมติว่าเครื่องผู้ใช้ปลายทางมี Git, Go, Node.js หรือ 7-Zip อยู่ใน PATH
|
||||
* ต้องมี Toolchain Helper และ Portable Runtimes ในตัว:
|
||||
* **MinGit:** ใช้ระบบ Auto-download MinGit portable หากตรวจไม่พบ Git ในระบบ
|
||||
* **Go & Node.js:** หากรันสคริปต์คอมไพล์ในเครื่องที่ไม่มีสภาพแวดล้อม สคริปต์จะดาวน์โหลด Portable Go 1.24 และ Portable Node.js v22 มาไว้ในโฟลเดอร์ `tools/` อัตโนมัติ
|
||||
* **Tools Extraction:** ดึง binary tools (`7za.exe`, `hpatchz.exe`, `zift.exe`) ออกจาก embed assets อัตโนมัติเมื่อเริ่มโปรแกรม
|
||||
|
||||
---
|
||||
|
||||
### 6. 🌿 Git Workflow & Code Hygiene
|
||||
* **Active Branch:** ทำงานและ Commit บน branch **`Dev`** เท่านั้น (ห้าม push สู่ main โดยตรง)
|
||||
* **Pre-commit Verification:**
|
||||
* ฝั่ง Go: `go vet ./...` ต้องผ่าน 100%
|
||||
* ฝั่ง Frontend: `npm run build` ต้องผ่าน 100%
|
||||
* **Clean Repository:** รักษาความสะอาดของ [`.gitignore`](../.gitignore) ห้าม commit ไฟล์ `_references/`, `dist/`, `node_modules/`, `bin/`, `temp/`, `tools/`, หรือ `server/` เข้าสู่ Git
|
||||
@@ -0,0 +1,61 @@
|
||||
# 📜 G-Launcher Development History & Decision Logs
|
||||
|
||||
เอกสารนี้บันทึกประวัติการพัฒนา การตัดสินใจเชิงเทคนิค และที่มาของฟีเจอร์ต่างๆ ในโปรเจกต์ **G-Launcher**
|
||||
|
||||
---
|
||||
|
||||
## 🏛️ จุดกำเนิดและการผสานโค้ด (Origins & Merging)
|
||||
|
||||
G-Launcher เกิดจากการรวมจุดเด่นของ 2 โปรเจกต์ต้นแบบเข้าด้วยกัน:
|
||||
|
||||
### 1. `Firefly-Shelter/Firefly_Launcher` (รากฐานฝั่ง UI & Architecture)
|
||||
* **สิ่งที่นำมาใช้:**
|
||||
* โครงสร้าง UI หน้าต่าง Launcher สไตล์มินิมอล โมเดิร์น (TailwindCSS + DaisyUI)
|
||||
* สถาปัตยกรรม Proxy และ Local Server Downloader
|
||||
* ระบบเปลี่ยนภาษาหลายภาษาแบบไดนามิก (i18next)
|
||||
* Zustand Store (`launcherStore`, `modalStore`)
|
||||
|
||||
### 2. `horoyoi-san/game-Launcher` (`sunbringer-launcher` branch) (ฟังก์ชันความปลอดภัย & เครื่องมือ)
|
||||
* **สิ่งที่นำมาใช้:**
|
||||
* เครื่องมือแพตช์ไฟล์ฟอร์แมต Zift (`.ziff`) ผ่าน `zift.exe`
|
||||
* ระบบจัดเตรียม Portable MinGit อัตโนมัติ (`git_runtime.go`)
|
||||
* การสำรองไฟล์เกมเดิมเป็น `.backup` ก่อนแก้ไข และระบบ Atomic Rollback
|
||||
* การบันทึกพาธเกมแบบทนทานต่อ Crash ด้วย Windows API `MoveFileEx` (`game-selection.go`)
|
||||
* สคริปต์คำนวณเวอร์ชันและแฮช SHA-256 (`scripts/launcher-release.mjs`)
|
||||
* ระบบติดตั้งม็อดแปลภาษาไทย (`thai-patch.go`)
|
||||
|
||||
---
|
||||
|
||||
## 📅 ไทม์ไลน์การพัฒนา (Changelog & Milestone Timeline)
|
||||
|
||||
### Milestone 1: Rebranding & Repository Initial Setup
|
||||
* ตั้งชื่อโปรเจกต์อย่างเป็นทางการว่า **G-Launcher** ภายใต้สังกัด **GaCy**
|
||||
* สร้าง Git Remote: `https://gaytea.cod-algieba.ts.net/GaCy/G-Launcher.git`
|
||||
* สร้างและตั้งค่าการทำงานบนสาขา **`Dev`** เป็นสาขาหลัก
|
||||
* รีแบรนด์ Go Module เป็น `g-launcher`, ปรับปรุง `build/config.yml`, `Taskfile.yml`, `main.go`, และ `wails.exe.manifest`
|
||||
* เพิ่มไฟล์ข้อกำหนดการพัฒนา [`AGENTS.md`](../AGENTS.md) และเอกสารแนะนำโปรเจกต์ [`README.md`](../README.md)
|
||||
|
||||
### Milestone 2: Thai Localization & Game Selection Persistence
|
||||
* สร้างไฟล์คำแปลภาษาไทยฉบับเต็ม: `frontend/public/locales/th.json`
|
||||
* เพิ่มปุ่มเลือกภาษาไทยใน `LanguageSwitcher`
|
||||
* เชื่อมโยงระบบจำพาธเกมลงใน `%APPDATA%/g-launcher/game-selection.json` โดยใช้ `MoveFileEx` แบบ Atomic Write
|
||||
|
||||
### Milestone 3: CI/CD & Build Workflow
|
||||
* ดัดแปลงสคริปต์คำนวณเวอร์ชัน `scripts/launcher-release.mjs` พร้อมชุดทดสอบอัตโนมัติ `launcher-release.test.mjs`
|
||||
* สร้าง GitHub Actions Workflow: `.github/workflows/build-launcher.yml`
|
||||
* แก้ไขข้อผิดพลาด Mermaid ELK parser บน Gitea (`Referenced shape does not exist: OS`) โดยปรับรูปแบบลูกศรในไดอะแกรมสถาปัตยกรรม
|
||||
|
||||
### Milestone 4: Zero-Dependency Local Auto-Updater
|
||||
* พัฒนาสคริปต์ [`update-and-build.bat`](../update-and-build.bat) และ [`scripts/bootstrap.ps1`](../scripts/bootstrap.ps1)
|
||||
* ระบบตรวจจับและดาวน์โหลด Portable MinGit, Go 1.24, Node.js v22 และ Wails v3 CLI อัตโนมัติลงใน `tools/`
|
||||
* แก้ไขปัญหา Text Encoding ของ Windows PowerShell 5.1 ด้วยการบันทึกไฟล์เป็น UTF-8 with BOM
|
||||
|
||||
### Milestone 5: Isolated Temp Build & Rollback (Current Milestone)
|
||||
* ปรับปรุงสถาปัตยกรรมการอัปเดตใหม่ตามกฎ:
|
||||
> **"โหลด Temp มา -> Build ใหม่ใน Temp -> นำมาแทนของเก่า -> ลบ Temp ทิ้ง 100%"**
|
||||
* ซอร์สโค้ดถูก clone ลง `temp/build_workspace` (หรือ `os.MkdirTemp`)
|
||||
* คอมไพล์ Frontend และ Go Backend ภายในโฟลเดอร์ Temp
|
||||
* สลับไฟล์ไบนารี `bin/G-Launcher.exe` อย่างปลอดภัยด้วยการสำรอง `.old` และมีระบบ Rollback อัตโนมัติหากเกิดข้อผิดพลาด
|
||||
* ลบโฟลเดอร์ Temp ทิ้ง 100% ผ่านบล็อก `finally` / `defer`
|
||||
* เพิ่มเมธอด `BuildAndUpdateFromSource` ใน Go `GitService`
|
||||
* สร้างโฟลเดอร์เอกสารความจำถาวร [`Doc/`](./README.md) เพื่อป้องกัน AI ลืมบริบทหลัง Compact
|
||||
@@ -0,0 +1,43 @@
|
||||
# 📚 G-Launcher Developer & AI Memory Documentation (`Doc/`)
|
||||
> แหล่งรวบรวมข้อมูลสถาปัตยกรรม กฎการพัฒนา รายละเอียดระบบ และประวัติการทำโปรเจกต์
|
||||
> **(ใช้สำหรับนักพัฒนาและให้ AI อ่านทบทวนบริบททุกครั้งหลังเกิดการ Compact)**
|
||||
|
||||
---
|
||||
|
||||
## 🎯 สรุปข้อมูลหลักที่ห้ามลืม (Master Quick Reference)
|
||||
|
||||
| หัวข้อ | ข้อมูลสำคัญ |
|
||||
| :--- | :--- |
|
||||
| **ชื่อโปรเจกต์** | **G-Launcher** (Go + Wails v3 + React 19 + Vite) |
|
||||
| **เจ้าของโปรเจกต์** | **GaCy** |
|
||||
| **Remote Repository** | `https://gaytea.cod-algieba.ts.net/GaCy/G-Launcher.git` |
|
||||
| **Active Branch** | **`Dev`** เท่านั้น (ห้าม push ตรงเข้า main หรือ branch อื่น) |
|
||||
| **โครงสร้างรากฐาน** | ผสมผสาน UI/Proxy จาก `Firefly_Launcher` + Core Tools/Rollback จาก `horoyoi-san/game-Launcher` |
|
||||
| **กฎเหล็กอันดับ 1** | **แก้ระบบหลังบ้าน (Go Backend) ก่อน UI เสมอ** (`go vet ./...` ต้องผ่านก่อนแก้ Frontend) |
|
||||
| **กฎเหล็กอันดับ 2** | **ห้าม Hardcode URL / IP / Path สัมบูรณ์** (รวมไว้ที่ [`pkg/constant/constant.go`](../pkg/constant/constant.go)) |
|
||||
| **กฎเหล็กอันดับ 3** | **ระบบอัปเดต:** โหลดลง Temp -> Build ใน Temp -> แทนที่ตัวเก่า -> ลบ Temp ทิ้ง 100% |
|
||||
|
||||
---
|
||||
|
||||
## 📑 สารบัญเอกสารในโฟลเดอร์นี้
|
||||
|
||||
1. [**ARCHITECTURE.md**](./ARCHITECTURE.md)
|
||||
* สถาปัตยกรรมโครงสร้างโปรเจกต์ Wails v3, Frontend React 19, และ Backend Services ทั้ง 5 ตัว
|
||||
2. [**DEVELOPMENT_RULES.md**](./DEVELOPMENT_RULES.md)
|
||||
* กฎ 6 ข้อในการพัฒนา และบทเรียนจาก Horoyoi-san & โปรเจกต์เดิม (Ananta / GaC-hkrpg-go)
|
||||
3. [**UPDATER_SYSTEM.md**](./UPDATER_SYSTEM.md)
|
||||
* กลไกและวงจรชีวิตของระบบ Auto-Updater และ Local Build (Temp Isolation, Rollback, Cleanup)
|
||||
4. [**HISTORY_AND_LOGS.md**](./HISTORY_AND_LOGS.md)
|
||||
* ไทม์ไลน์และประวัติการพัฒนาตั้งแต่เริ่มรวม 2 Repos จนถึงฟีเจอร์ปัจจุบัน
|
||||
|
||||
---
|
||||
|
||||
## 🤖 คำแนะนำสำหรับ AI Agent (เมื่อตื่นขึ้นมาหลัง Compact)
|
||||
|
||||
หากพบว่าความจำใน context ถูกย่อ (compacted):
|
||||
1. **อ่านไฟล์ในโฟลเดอร์นี้ก่อนเริ่มทำงานเสมอ** เพื่อคืนบริบทของโปรเจกต์ทั้งหมด
|
||||
2. เช็คว่ากำลังอยู่บน branch `Dev` หรือไม่ ด้วยคำสั่ง `git status`
|
||||
3. ก่อน commit โค้ดใดๆ ต้องรัน:
|
||||
* `go vet ./...` (ต้องผ่าน 100%)
|
||||
* `npm --prefix frontend run build` (ต้องผ่าน 100%)
|
||||
4. สื่อสารกับผู้ใช้เป็นภาษาไทยที่กระชับ ตรงประเด็น และรายงานผลการทำงานอย่างชัดเจน
|
||||
@@ -0,0 +1,103 @@
|
||||
# 🚀 G-Launcher Updater & Bootstrap Build System
|
||||
|
||||
เอกสารนี้อธิบายรายละเอียดเชิงลึกของระบบ **Auto-Update & Local Build Bootstrap** ของ G-Launcher ซึ่งถูกออกแบบมาเพื่อรองรับกรณีที่ผู้ใช้หรือเซิร์ฟเวอร์ Git (เช่น Gitea) ไม่มี CI/CD Runner บนคลาวด์สำหรับคอมไพล์ไบนารีล่วงหน้า
|
||||
|
||||
---
|
||||
|
||||
## 🎯 กฎเหล็กของระบบอัปเดต (The Golden Updater Rule)
|
||||
|
||||
> **"โหลด Temp มา -> Build ใหม่ใน Temp -> นำมาแทนของเก่า -> ลบ Temp ทิ้ง 100%"**
|
||||
|
||||
### เหตุผลทางสถาปัตยกรรม (Architectural Rationale)
|
||||
1. **ป้องกัน Windows File Lock:** ระบบปฏิบัติการ Windows จะล็อกไฟล์ `.exe` ที่กำลังทำงานอยู่ทันที ทำให้ไม่สามารถเขียนทับ (overwrite) ตัวเองได้โดยตรง แต่ Windows อนุญาตให้ **เปลี่ยนชื่อ (Rename)** ไฟล์ executable ที่กำลังทำงานอยู่ได้
|
||||
2. **รักษาความสะอาดของโปรเจกต์ (Zero Pollution):** ไม่ทำการ build หรือ pull โค้ดทับโฟลเดอร์ทำงานหลักโดยตรง เพื่อป้องกันไฟล์ขยะหรือ node_modules ปนเปื้อน
|
||||
3. **Atomic Rollback:** หากกระบวนการคอมไพล์ใน Temp ล้มเหลว โปรแกรมเวอร์ชันเดิมจะยังคงทำงานได้สมบูรณ์ ไม่เสียหาย
|
||||
|
||||
---
|
||||
|
||||
## 🔄 วงจรชีวิตของระบบอัปเดต (Updater Lifecycle)
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
autonumber
|
||||
actor User as ผู้ใช้งาน / Contributor
|
||||
participant Bootstrap as bootstrap.ps1 / Go GitService
|
||||
participant TempDir as โฟลเดอร์ชั่วคราว (Temp)
|
||||
participant Git as Git Repository (Dev Branch)
|
||||
participant Target as bin/G-Launcher.exe
|
||||
|
||||
User->>Bootstrap: รัน update-and-build.bat หรือกด Update ใน UI
|
||||
Note over Bootstrap: ตรวจสอบและเตรียม Portable Git, Go, Node.js (tools/)
|
||||
Bootstrap->>TempDir: 1. สร้างโฟลเดอร์ชั่วคราว (temp/build_workspace)
|
||||
Bootstrap->>Git: 2. Clone โค้ดสาขา Dev ลงใน TempDir
|
||||
Git-->>TempDir: ดาวน์โหลดซอร์สโค้ดสำเร็จ
|
||||
|
||||
rect rgb(30, 40, 60)
|
||||
Note over TempDir: 3. บิลด์ทั้งหมดภายใน TempDir
|
||||
TempDir->>TempDir: npm install & npm run build (React Frontend)
|
||||
TempDir->>TempDir: go mod tidy
|
||||
TempDir->>TempDir: wails3 generate syso (Manifest & Icon)
|
||||
TempDir->>TempDir: go build -tags production -> bin/G-Launcher.exe
|
||||
end
|
||||
|
||||
rect rgb(40, 60, 40)
|
||||
Note over Bootstrap,Target: 4. สลับไฟล์ไบนารี (Atomic Swap & Rollback)
|
||||
Bootstrap->>Target: เปลี่ยนชื่อตัวเก่าเป็น G-Launcher.exe.old
|
||||
Bootstrap->>Target: ย้ายตัวใหม่จาก TempDir มาแทนที่ Target
|
||||
alt ย้ายไฟล์สำเร็จ
|
||||
Bootstrap->>Target: ลบไฟล์ G-Launcher.exe.old
|
||||
else เกิดข้อผิดพลาด
|
||||
Bootstrap->>Target: Rollback ย้าย .old กลับมาเป็นตัวหลัก
|
||||
end
|
||||
end
|
||||
|
||||
rect rgb(60, 30, 30)
|
||||
Note over Bootstrap,TempDir: 5. ล้างและทำลายโฟลเดอร์ชั่วคราว (finally / defer)
|
||||
Bootstrap->>TempDir: ลบโฟลเดอร์ TempDir ทั้งหมด (Purge 100%)
|
||||
end
|
||||
|
||||
Bootstrap->>Target: 6. รัน G-Launcher.exe เวอร์ชันใหม่
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ ไฟล์ที่เกี่ยวข้องและการทำงาน
|
||||
|
||||
### 1. [`update-and-build.bat`](../update-and-build.bat)
|
||||
* สคริปต์ Batch สั้นๆ สำหรับดับเบิลคลิกบน Windows
|
||||
* ตั้งค่า UTF-8 (`chcp 65001`) และส่งต่อการทำงานไปยัง `scripts/bootstrap.ps1` ผ่านคำสั่ง:
|
||||
```cmd
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -File "%~dp0scripts\bootstrap.ps1" %*
|
||||
```
|
||||
|
||||
### 2. [`scripts/bootstrap.ps1`](../scripts/bootstrap.ps1)
|
||||
* **การตรวจหาและดาวน์โหลดเครื่องมือพกพา (Prerequisites):**
|
||||
* `Git`: หากในเครื่องไม่มี จะดาวน์โหลด **Portable MinGit** มาไว้ที่ `tools/mingit/`
|
||||
* `Go`: หากไม่มี Go compiler จะดาวน์โหลด **Portable Go 1.24** มาไว้ที่ `tools/go/`
|
||||
* `Node.js & npm`: หากไม่มี Node.js จะดาวน์โหลด **Portable Node.js v22** มาไว้ที่ `tools/node/`
|
||||
* `Wails v3 CLI`: ติดตั้งผ่าน `go install github.com/wailsapp/wails/v3/cmd/wails3@v3.0.0-alpha.74`
|
||||
* **Isolated Temp Build:**
|
||||
* ใช้โฟลเดอร์ `$tempBuildDir = Join-Path $rootDir "temp\build_workspace"`
|
||||
* สั่ง `git clone --depth 1 --branch Dev <RepoUrl> $tempBuildDir`
|
||||
* รัน `npm install`, `npm run build`, และ `go build` ภายใน Temp
|
||||
* **Atomic Replacement & Rollback:**
|
||||
* เปลี่ยนชื่อ `bin/G-Launcher.exe` เดิมเป็น `.old`
|
||||
* ย้ายตัวใหม่เข้ามาแทนที่ หากล้มเหลวจะคืนค่า `.old` ทันที
|
||||
* **Guaranteed Cleanup:**
|
||||
* วางคำสั่งลบโฟลเดอร์ชั่วคราวไว้ในบล็อก `finally { ... }` เพื่อรับประกันว่าจะถูกลบออก 100% แม้สคริปต์จะหยุดทำงานกลางคัน
|
||||
|
||||
### 3. Go Backend: [`internal/git-service/launcher.go`](../internal/git-service/launcher.go)
|
||||
* ฟังก์ชัน [`BuildAndUpdateFromSource(branch string)`](../internal/git-service/launcher.go#L95) ใน `GitService`:
|
||||
```go
|
||||
// 1. สร้างโฟลเดอร์ชั่วคราว
|
||||
tempDir, err := os.MkdirTemp("", "g-launcher-build-*")
|
||||
defer os.RemoveAll(tempDir) // รับประกันการลบโฟลเดอร์ Temp เสมอ
|
||||
|
||||
// 2. Clone โค้ดต้นทาง
|
||||
cloneCmd := exec.Command(gitExe, "clone", "--depth", "1", "--branch", branch, constant.LauncherRepoURL, tempDir)
|
||||
...
|
||||
// 3. Build ใน Temp
|
||||
...
|
||||
// 4. สลับไฟล์ที่กำลังรันอยู่ด้วย selfupdate.Apply
|
||||
err = selfupdate.Apply(builtFile, selfupdate.Options{})
|
||||
```
|
||||
@@ -176,6 +176,7 @@ wails3 task package
|
||||
G-Launcher/
|
||||
├── .github/workflows/ # GitHub Actions release & build workflows
|
||||
├── assets/ # Embedded binary tools (7za, hpatchz, zift, appicon)
|
||||
├── Doc/ # Technical documentation, architecture & AI memory
|
||||
├── build/ # Wails build configurations & OS templates
|
||||
│ ├── config.yml # App metadata (CompanyName, ProductName, AppID)
|
||||
│ └── windows/ # Windows manifests, icons, info.json
|
||||
|
||||
Reference in new issue
Block a user