# 🛡️ K AegisRole — Modern Discord Role Safeguard & Restoration Engine
[](https://www.python.org/)
[](https://github.com/Rapptz/discord.py)
[](https://sqlite.org/)
[](https://discordpy.readthedocs.io/)
[](LICENSE)
> **Language / ภาษา**: [🇹🇭 ภาษาไทย](#-ภาษาไทย-thai-version) | [🇬🇧 English](#-english-version)
---
# 🇹🇭 ภาษาไทย (Thai Version)
ระบบสำรองและกู้คืนยศอัตโนมัติสำหรับ Discord พัฒนาและปรับปรุงใหม่ทั้งหมดด้วยมาตรฐานปี 2026 รองรับสถาปัตยกรรม **discord.py 2.x**, แยกโมดูลการทำงานด้วย **Cogs**, จัดเก็บข้อมูลอย่างปลอดภัยด้วย **SQLite Database**, และมีหน้าตาอินเตอร์เฟซ Discord Component Embeds และ Rich Console สวยงามระดับมืออาชีพ
## 🌟 ฟีเจอร์เด่น (Key Features)
### 1. 💾 การสำรองยศที่ปลอดภัยและแม่นยำ (Safe Role Backup)
- บันทึกยศโดยใช้ **Role ID** เป็นหลัก พร้อมชื่อสำรอง ป้องกันปัญหายศถูกเปลี่ยนชื่อ
- กรองยศของระบบบอท (`@everyone` และ Managed Bot Roles) ออกโดยอัตโนมัติ
- ป้องกันข้อมูลชนกันระหว่างเซิร์ฟเวอร์ (Guild Isolation)
- มีระบบ Cooldown ป้องกันการกดสแปมปุ่ม พร้อมแจ้งเวลาที่เหลืออย่างชัดเจน
### 2. 🔄 การกู้คืนยศแบบ Batch Call (Atomic Role Restoration)
- คืนยศทั้งหมดในคำสั่งเดียวผ่าน `add_roles(*roles)` ไม่โดน Discord Rate Limit บล็อก
- ตรวจสอบลำดับยศ (Role Hierarchy) อัตโนมัติ: ข้ามยศที่อยู่สูงกว่าบอทอย่างปลอดภัย พร้อมแจ้งเตือนแอดมิน
- แยกแยะรายงานชัดเจน: ยศที่ได้รับคืน, ยศที่มีอยู่แล้ว, และยศที่ข้ามไป
### 3. ⚡ ระบบคืนยศอัตโนมัติเมื่อสมาชิกเข้าดิสใหม่ (Auto-Restore on Rejoin)
- สมาชิกที่เผลอกดออกจากเซิร์ฟเวอร์ หรือดิสคอร์ดหลุด เมื่อกลับเข้ามาใหม่ บอทสามารถคืนยศเดิมให้ทันทีโดยอัตโนมัติ (เปิด/ปิด ได้ผ่านคำสั่ง `/saveroles config`)
- รองรับการบันทึกยศอัตโนมัติเมื่อสมาชิกออกจากเซิร์ฟเวอร์ (Auto-save on leave)
### 4. 👤 การแสดงข้อมูลโปรไฟล์ผู้ใช้ (Interactive User Profile)
- การแสดงผลแบบ Discord Dynamic Timestamps (`<t:TIMESTAMP:R>`)
- แสดงอายุบัญชี, วันที่เข้าร่วมเซิร์ฟเวอร์, สถานะ Nitro Boost, และสถานะการสำรองยศปัจจุบัน
### 5. ⭐ ระบบรีวิวผ่านหน้าต่าง Modal (Interactive Review Modal)
- ผู้ใช้สามารถกดปุ่มรีวิวเพื่อเปิด Modal กรอกคะแนนดาว (1 - 5 ดาว) พร้อมพิมพ์ข้อความติชม
- จัดเก็บบันทึกลงฐานข้อมูล และส่ง Embed สวยงามไปยังห้อง Review Log สำหรับแอดมิน
### 6. 🗄️ ฐานข้อมูล SQLite & Rich Console Logger
- ใช้งาน SQLite3 แบบมี Index ความเร็วสูง หมดปัญหาไฟล์ JSON เสียหาย
- ระบบบันทึก Log ลงไฟล์หมุนเวียนอัตโนมัติ (`logs/aegisrole.log`) พร้อมแบนเนอร์แสดงสถานะบน Console
---
## 📂 โครงสร้างโปรเจกต์ (Project Structure)
```
K AegisRole/
├── cogs/
│ ├── admin.py # คำสั่งตั้งค่าเซิร์ฟเวอร์, ดูสถิติ, ตรวจสอบสมาชิก
│ ├── events.py # ดักจับสมาชิกเข้า-ออก (Auto-restore & Auto-save)
│ └── saveroles.py # แผงควบคุมหลัก (Persistent Buttons & Modal)
├── data/
│ └── saveroles.db # ฐานข้อมูล SQLite จัดเก็บยศ, การตั้งค่า, และรีวิว
├── logs/
│ └── aegisrole.log # ไฟล์บันทึกประวัติการทำงาน (Max 5MB Rotating)
├── utils/
│ └── logger.py # คอนโซลสไตล์ Rich และระบบ Logging
├── .env.example # แม่แบบการตั้งค่า Environment Variables
├── config.py # โมดูลโหลดคอนฟิกและพาเลตสี
├── data_manager.py # ตัวจัดการฐานข้อมูล SQLite (CRUD & Auto-migration)
├── main.py # จุดเริ่มต้นการทำงานของบอท (Main Entry Point)
├── main_legacy.py.bak # ไฟล์โค้ดเดิมที่สำรองไว้
├── requirements.txt # รายการไลบรารีที่จำเป็น
├── setup_guide.md # คู่มือการตั้งค่าสิทธิ์บน Discord Developer Portal
├── DOCUMENTATION.md # เอกสารทางเทคนิคและสถาปัตยกรรมฉบับเต็ม
└── test_suite.py # ชุดทดสอบระบบอัตโนมัติ (Automated Unit Tests)
```
---
## 🚀 วิธีการเริ่มต้นใช้งาน (Quickstart - TH)
### 1. ติดตั้ง Dependencies
```bash
pip install -r requirements.txt
```
### 2. ตั้งค่าไฟล์ `.env`
คัดลอกไฟล์ `.env.example` ไปเป็น `.env` และใส่ค่า Discord Bot Token:
```env
DISCORD_TOKEN=your_bot_token_here
BOT_PREFIX=.
COOLDOWN_SECONDS=60
AUTO_RESTORE_ON_JOIN=false
```
### 3. ตรวจสอบระบบด้วย Test Suite
```bash
python test_suite.py
```
### 4. รันบอท
```bash
python main.py
```
---
## 🛠️ รายการคำสั่ง Slash Commands (TH)
| คำสั่ง | สิทธิ์ที่ต้องการ | คำอธิบาย |
|---|---|---|
| `/setupsaveroles [channel]` | Administrator | ส่งแผงปุ่มกดเซฟยศและคืนยศไปยังห้องที่เลือก |
| `/saveroles setup [channel]` | Administrator | เหมือนกับ `/setupsaveroles` |
| `/saveroles config` | Administrator | ตั้งค่าห้อง Log, ห้อง Review, และเปิด/ปิด Auto-restore |
| `/saveroles stats` | Manage Guild | ตรวจสอบสถิติจำนวนคนเซฟยศและรีวิวในเซิร์ฟเวอร์ |
| `/saveroles check [member]` | Administrator | ตรวจสอบข้อมูลยศที่สำรองไว้ของสมาชิกรายคน |
| `/saveroles clear [member]` | Administrator | ลบข้อมูลสำรองยศของสมาชิก |
| `/saveroles help` | ทุกคน | แสดงคู่มือการใช้งานระบบและคำอธิบายปุ่มกด |
