From 3411e5b05870d724f1c2e72c0a685d4f4ee55c38 Mon Sep 17 00:00:00 2001 From: CAtlas0784 Date: Fri, 30 Oct 2026 21:36:24 +0700 Subject: [PATCH] docs: add Doc folder with architecture, rules, updater lifecycle, and project memory --- AGENTS.md | 16 +++++ Doc/ARCHITECTURE.md | 128 +++++++++++++++++++++++++++++++++++++++ Doc/DEVELOPMENT_RULES.md | 62 +++++++++++++++++++ Doc/HISTORY_AND_LOGS.md | 61 +++++++++++++++++++ Doc/README.md | 43 +++++++++++++ Doc/UPDATER_SYSTEM.md | 103 +++++++++++++++++++++++++++++++ README.md | 1 + 7 files changed, 414 insertions(+) create mode 100644 Doc/ARCHITECTURE.md create mode 100644 Doc/DEVELOPMENT_RULES.md create mode 100644 Doc/HISTORY_AND_LOGS.md create mode 100644 Doc/README.md create mode 100644 Doc/UPDATER_SYSTEM.md diff --git a/AGENTS.md b/AGENTS.md index 2b4b290..00a4e4d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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/` ทันที** เพื่อคืนความจำและทำความเข้าใจกฎ สถาปัตยกรรม และประวัติของระบบก่อนเริ่มทำงานเสมอ diff --git a/Doc/ARCHITECTURE.md b/Doc/ARCHITECTURE.md new file mode 100644 index 0000000..36a614a --- /dev/null +++ b/Doc/ARCHITECTURE.md @@ -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 +``` diff --git a/Doc/DEVELOPMENT_RULES.md b/Doc/DEVELOPMENT_RULES.md new file mode 100644 index 0000000..29fd95d --- /dev/null +++ b/Doc/DEVELOPMENT_RULES.md @@ -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 diff --git a/Doc/HISTORY_AND_LOGS.md b/Doc/HISTORY_AND_LOGS.md new file mode 100644 index 0000000..fd54a8c --- /dev/null +++ b/Doc/HISTORY_AND_LOGS.md @@ -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 diff --git a/Doc/README.md b/Doc/README.md new file mode 100644 index 0000000..6ea4414 --- /dev/null +++ b/Doc/README.md @@ -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. สื่อสารกับผู้ใช้เป็นภาษาไทยที่กระชับ ตรงประเด็น และรายงานผลการทำงานอย่างชัดเจน diff --git a/Doc/UPDATER_SYSTEM.md b/Doc/UPDATER_SYSTEM.md new file mode 100644 index 0000000..d752a8f --- /dev/null +++ b/Doc/UPDATER_SYSTEM.md @@ -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 $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{}) + ``` diff --git a/README.md b/README.md index 084e372..5a40c29 100644 --- a/README.md +++ b/README.md @@ -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