52 lines
9.3 KiB
Markdown
52 lines
9.3 KiB
Markdown
# Repository rules
|
|
|
|
## ห้าม hardcode ค่าที่เปลี่ยนตามสภาพแวดล้อมหรือการใช้งาน
|
|
|
|
- ห้ามใส่ path ของเครื่อง, ชื่อผู้ใช้, Desktop, ไดรฟ์ติดตั้ง (`C:\...`), path ของเกม/Proxy/Server/Go/Node, IP, port, URL ของ deployment หรือ endpoint ลงใน source code, logic หรือ startup scripts
|
|
- ค่า URL, endpoint, และ repository config ต้องรวมศูนย์อยู่ที่ `pkg/constant/constant.go` หรือ config file กลางเท่านั้น ห้ามกระจายค่าคงที่หรือซ่อน hardcode ไว้ตาม service
|
|
- การเข้าถึง filesystem ภายในเครื่องต้องใช้ `filepath.Join(...)` เสมอ และโฟลเดอร์ข้อมูลผู้ใช้ต้องอ้างอิงผ่าน `os.UserConfigDir()` (`%APPDATA%`) เท่านั้น ห้ามเดาพาธจากไดรฟ์หรือชื่อโฟลเดอร์
|
|
- ค่าเฉพาะเครื่องต้องอยู่ในไฟล์ local ที่ถูก ignore หรือ environment ห้าม commit ข้อมูลเฉพาะเครื่องเข้า Git
|
|
- ห้ามอ้างว่าเอา hardcode ออกหมดทั้ง repository หากตรวจหรือแก้เพียงบางส่วน ต้องระบุขอบเขตและส่วนที่ยังเหลือจริงตามความเป็นจริง
|
|
|
|
## สถาปัตยกรรม System-First และลำดับการพัฒนา
|
|
|
|
- ทุกครั้งที่เพิ่มฟีเจอร์ ปรับแต่ง logic หรือแก้ schema ให้ทำที่ **Go Backend** (`internal/`, `pkg/`, `main.go`) ให้เสร็จสิ้นและรัน `go vet ./...` ผ่าน 100% ก่อนแตะ Frontend UI ทุกครั้ง
|
|
- เมื่อ Go Backend เปลี่ยนแปลง ต้องรัน `wails3 generate bindings` เพื่อซิงก์ TypeScript Bindings ลง `frontend/bindings/` ก่อนเริ่มเขียนหรือแก้ไข UI ใน `frontend/src/`
|
|
- ห้ามแก้ Frontend UI ให้เรียก method หรือ property ที่ยังไม่มีใน Go Backend เด็ดขาด เพราะจะทำให้ Wails v3 เกิด Unhandled Exception จนหน้าต่าง Launcher ขาวสนิทหรือ crash ทันที
|
|
- ห้ามอ้างว่าแค่ build ผ่านหรือไม่มี type error แปลว่าหน้าต่าง Launcher ทำงานถูกต้อง ต้องเปิดตรวจสอบการตอบสนองจริงหรือรายงานว่ายังรอการยืนยัน
|
|
|
|
## กฎของระบบอัปเดตและบิลด์ท้องถิ่น (Updater Lifecycle Contract)
|
|
|
|
- ระบบอัปเดตทั้งในสคริปต์และในแอป ต้องทำงานตามลำดับ 4 ขั้นตอนอย่างเคร่งครัด: **ดาวน์โหลดลง Temp -> Build ใหม่ใน Temp -> นำมาสลับแทนที่ของเก่า -> ลบ Temp ทิ้ง 100%**
|
|
- ห้าม git pull หรือรัน compiler ทับโฟลเดอร์หลักของ Launcher ขณะที่ตัว Launcher รันอยู่โดยตรง เพราะจะติด Windows Executable File Lock (`Access is denied`) และทำให้โฟลเดอร์ทำงานเสียหาย
|
|
- การสลับไฟล์ `.exe` บน Windows ต้องใช้วิธี Rename ไฟล์เดิมที่กำลังรันอยู่เป็น `.old` ก่อน แล้วจึงย้ายไฟล์ใหม่เข้ามาแทนที่ หากเกิดข้อผิดพลาดระหว่างย้าย ต้อง Rollback นำไฟล์ `.old` กลับคืนมาทันที ห้ามทิ้งไฟล์ให้อยู่ในสถานะเสียหาย
|
|
- โฟลเดอร์ชั่วคราว (`temp/build_workspace` หรือ `os.MkdirTemp`) ต้องถูกลบทิ้ง 100% ผ่านบล็อก `finally` หรือ `defer os.RemoveAll` เสมอ ห้ามทิ้งไฟล์ขยะตกค้าง
|
|
|
|
## ความปลอดภัยของข้อมูลและการแก้ไขไฟล์ตัวเกม (Data Safety & Atomic Operations)
|
|
|
|
- ไฟล์ตัวเกมและไฟล์เซฟเป็นข้อมูลที่มีขนาดใหญ่และเสียหายง่าย ก่อนจะ patch, แก้ไข หรือเขียนทับไฟล์ใดๆ (เช่น `.dll`, `.exe`, `ExcelData`) ต้องคัดลอกไฟล์เดิมไว้เป็นนามสกุล `.backup` เสมอ
|
|
- หากการ patch, verify hash, หรือ download เกิดข้อผิดพลาด ต้องทำ Atomic Rollback กู้คืนไฟล์ `.backup` กลับมาทันที ห้ามทิ้งไฟล์เกมในสภาพเสียหาย
|
|
- การบันทึกไฟล์คอนฟิก (เช่น `game-selection.json`) ห้ามใช้ `os.WriteFile` ธรรมดา เพราะไฟดับหรือ crash จะทำให้ไฟล์กลายเป็น 0 ไบต์ ต้องเขียนลง `.tmp` พร้อม `file.Sync()` แล้วสลับด้วย Windows API `MoveFileEx` (`MOVEFILE_REPLACE_EXISTING | MOVEFILE_WRITE_THROUGH`) เท่านั้น
|
|
|
|
## การจัดการเครื่องมือและ Zero-Dependency
|
|
|
|
- ห้ามสมมติว่าเครื่องผู้ใช้มี Git, Go, Node.js หรือ 7-Zip อยู่ใน PATH สคริปต์ bootstrap ต้องมีระบบดาวน์โหลด portable runtime อัตโนมัติลงใน `tools/`
|
|
- ฝั่ง Launcher ต้องแตก binary tools (`7za.exe`, `hpatchz.exe`, `zift.exe`) ออกจาก embed assets ลง `bin/` อัตโนมัติเมื่อเริ่มโปรแกรม
|
|
- สคริปต์ PowerShell ทั้งหมดที่มีอักขระสองไบต์หรือภาษาไทย ต้องบันทึกเป็น UTF-8 with BOM (`[System.Text.Encoding]::UTF8`) เสมอ เพื่อป้องกัน Windows PowerShell 5.1 ตีความไบต์ผิด
|
|
- คำสั่ง Git ในสคริปต์และในโค้ด ต้องกำหนด `GIT_TERMINAL_PROMPT=0` เสมอ เพื่อป้องกันโปรเซสค้างจากการรอ interactive credentials prompt
|
|
|
|
## การอนุรักษ์ Naming และการ Refactor
|
|
|
|
- ห้ามใช้วิธี Find-and-Replace ชื่อโปรเจกต์เดิม (เช่น `sunbringer`, `firefly`) สุ่มสี่สุ่มห้าทั่วทั้งโปรเจกต์ เพราะจะทำให้ internal protocol, protobuf serialization, หรือ build manifest พัง
|
|
- ให้แยก User-Facing Branding (เช่น ชื่อหน้าต่าง, Title, Tooltip) ออกจาก System/Package Identifier ภายในให้ชัดเจน เปลี่ยนเฉพาะส่วนที่จำเป็นเมื่อระบบ core นิ่งแล้วเท่านั้น
|
|
|
|
## Git Workflow และความสะอาดของ Repository
|
|
|
|
- ทำงานและ Commit บน branch **`Dev`** เท่านั้น ห้ามแตะต้องหรือ push เข้า main โดยตรง
|
|
- ก่อน Commit ทุกครั้ง: Go ต้องผ่าน `go vet ./...` 100% และ Frontend ต้องผ่าน `npm run build` 100%
|
|
- รักษาความสะอาดของ `.gitignore` ห้าม commit ไฟล์ `_references/`, `dist/`, `node_modules/`, `bin/`, `temp/`, `tools/`, `server/`, หรือ `*.old` เข้า Git
|
|
|
|
## การฟื้นตัวของ AI หลัง Compact บริบท
|
|
|
|
- เมื่อ AI เริ่มเซสชันใหม่หรือฟื้นตัวหลังจากการทำ Compact บริบท ให้เปิดอ่านไฟล์ในโฟลเดอร์ `Doc/` (โดยเฉพาะ `Doc/G-LAUNCHER-HANDOFF.md`) ทันทีเพื่อคืนบริบทและทำความเข้าใจสถานะจริงก่อนเริ่มงานเสมอ
|