# 📖 K AegisPoke — Full Technical Documentation & Architecture Reference
## เอกสารและคู่มือการทำงานฉบับสมบูรณ์ (Bilingual Edition)
> **Language / ภาษา**: [🇹🇭 ภาษาไทย](#-ภาษาไทย-thai-version) | [🇬🇧 English](#-english-version)
---
# 🇹🇭 ภาษาไทย (Thai Version)
## 📑 สารบัญ (TH)
1. [ภาพรวมของระบบ (System Overview)](#1-ภาพรวมของระบบ-th)
2. [กลไกความปลอดภัยและระบบยกเลิกฉุกเฉิน (Safety & Abort Engine)](#2-กลไกความปลอดภัยและระบบยกเลิกฉุกเฉิน-th)
3. [ฟีเจอร์การทำงานอย่างละเอียด (Full Feature Specifications)](#3-ฟีเจอร์การทำงานอย่างละเอียด-th)
4. [ตารางคำสั่ง Slash Commands ฉบับสมบูรณ์ (Command Reference)](#4-ตารางคำสั่ง-slash-commands-ฉบับสมบูรณ์-th)
5. [การจัดการข้อมูลและ Presets (Data Management)](#5-การจัดการข้อมูลและ-presets-th)
6. [การแก้ไขปัญหาที่พบบ่อย (Troubleshooting & FAQ)](#6-การแก้ไขปัญหาที่พบบ่อย-th)
---
### 1. ภาพรวมของระบบ (TH)
**K AegisPoke** คือระบบควบคุมและจัดการการสลับห้องเสียงสมาชิก (Voice Channel Switcher & Poke) สำหรับชุมชน Discord ระดับมืออาชีพ พัฒนาด้วย Python 3.11 และ discord.py 2.7+ เพื่อแก้ปัญหาข้อจำกัดของระบบเดิม:
- **หมดปัญหาบอทโดน Discord แบน API**: มีระบบควบคุมอัตราการส่งคำขอ (Rate-Limiter) บังคับช่วงเวลาหน่วงขั้นต่ำ ไม่ให้เกิดสถานะ HTTP 429
- **หมดปัญหาย้ายแล้วผู้ใช้หลุดหาย**: มีระบบนำส่งกลับห้องหลัก (`channel_main`) เสมอ ทั้งกรณีครบรอบและกรณีถูกกดยกเลิก
- **หมดปัญหาคนแกล้งแอดมินหรือเจ้าของเซิร์ฟ**: มีระบบคุ้มกัน (Immunity System) อัตโนมัติสำหรับแอดมิน และเพิ่มยศคุ้มครองได้ไม่จำกัด
- **มีปุ่มหยุดฉุกเฉิน (Emergency Abort)**: ควบคุมได้แบบ Real-time บน Discord UI ไม่ต้องรอหรือพิมพ์คำสั่งแก้ในเทอร์มินัล
---
### 2. กลไกความปลอดภัยและระบบยกเลิกฉุกเฉิน (TH)
- **Active Session Registry**: บอทบันทึกสถานะการย้ายแบบเรียลไทม์ผ่าน `session_key = f"{guild_id}_{member_id}"` คู่กับ `asyncio.Event`
- **Interruptible Sleep**: ในแต่ละรอบการย้าย บอทจะไม่ใช้ `time.sleep` หรือการ sleep แบบบล็อก แต่จะใช้ `asyncio.wait_for(cancel_token.wait(), timeout=interval)` หากมีสัญญาณยกเลิก บอทจะหยุดการสลับห้องทันทีภายในเวลาไม่เกิน 0.05 วินาที
- **Voice Disconnect Detection**: หากผู้ใช้กดยกเลิกการเชื่อมต่อเสียง (Disconnect) หรือปิดโปรแกรม Discord บอทจะตรวจจับผ่าน `member.voice` และยุติเซสชันอัตโนมัติ
---
### 3. ฟีเจอร์การทำงานอย่างละเอียด (TH)
#### 3.1 การสลับห้องเสียง (`/poke run`)
- กำหนดสมาชิกเป้าหมาย, ห้องหลัก, ห้องสลับที่ 1, ห้องสลับที่ 2, จำนวนรอบ และระยะหน่วงเวลา
- บอทจะทำการตรวจสอบว่าทั้ง 3 ห้องต้องไม่ซ้ำกัน และสมาชิกต้องอยู่ในห้องเสียงจริงก่อนเริ่มทำงาน
#### 3.2 ระบบ Presets ถาวร (`/poke preset`)
- ผู้ใช้แต่ละคนสามารถบันทึกเทมเพลตที่ใช้เป็นประจำลงในฐานข้อมูล
- เมื่อต้องการเรียกใช้ เพียงพิมพ์ `/poke preset list` จะมีหน้าต่าง Embed และกล่องเลือก Dropdown ให้กดรันได้ทันทีโดยไม่ต้องระบุห้องใหม่ทุกครั้ง
#### 3.3 ระบบคุ้มกันความปลอดภัยระดับเซิร์ฟเวอร์ (`/poke_config`)
- ป้องกันการก่อกวนในเซิร์ฟเวอร์ขนาดใหญ่
- แอดมินสามารถเพิ่มยศที่ห้ามโดน Poke ได้ เช่น ยศ VIP, Moderator, Streamer
- ปรับแต่งรอบสูงสุด (`max_rounds`) ได้ตามความเหมาะสมของเซิร์ฟเวอร์
---
### 4. ตารางคำสั่ง Slash Commands ฉบับสมบูรณ์ (TH)
| คำสั่ง | สิทธิ์ที่ต้องการ | คำอธิบายการทำงาน |
|---|---|---|
| `/poke run` | Move Members | สั่งเริ่มย้ายสลับห้องเสียงตามพารามิเตอร์ที่ระบุ |
| `/poke stop` | Move Members | สั่งหยุดการทำงานของเซสชันสมาชิกคนนั้นทันที |
| `/poke preset save` | ทุกคน | บันทึกเส้นทางและเป้าหมายไว้เป็น Preset ส่วนตัว |
| `/poke preset list` | ทุกคน | แสดงรายการและเปิดเมนูเลือกใช้ Preset ของตนเอง |
| `/poke preset delete`| ทุกคน | ลบ Preset ที่บันทึกไว้ออก |
| `/poke_config status` | ทุกคน | ตรวจสอบการตั้งค่าขีดจำกัดความปลอดภัยของเซิร์ฟเวอร์ |
| `/poke_config set_limits` | Administrator | ปรับขีดจำกัดรอบสูงสุดและระยะหน่วงขั้นต่ำ |
| `/poke_config add_immune_role` | Administrator | เพิ่มยศที่ได้รับการคุ้มกัน ห้ามใครสั่ง Poke |
| `/poke_config remove_immune_role`| Administrator | ลบยศออกจากรายชื่อคุ้มกัน |
| `/ping` | ทุกคน | ตรวจสอบค่าความหน่วง WebSocket |
| `/stats` | ทุกคน | ตรวจสอบสถานะ RAM, เซิร์ฟเวอร์ และจำนวนเซสชัน |
| `/help` | ทุกคน | แสดงคู่มือการใช้งานแบบโต้ตอบ |
---
### 5. การจัดการข้อมูลและ Presets (TH)
- ข้อมูลถูกบันทึกด้วยเทคนิค **Safe Atomic Replacement**
- `data/presets.json`: จัดเก็บ Presets แยกตาม User ID
- `data/settings.json`: จัดเก็บการตั้งค่าความปลอดภัยราย Guild
- บันทึกการทำงานทั้งหมดลงใน `logs/poke.log` แบบหมุนเวียน 5MB สูงสุด 3 ไฟล์
---
### 6. การแก้ไขปัญหาที่พบบ่อย (TH)
1. **บอทไม่ยอมย้ายสมาชิก (แจ้งเตือนสิทธิ์ไม่พอ)**:
- ตรวจสอบว่าใน Discord บทบาทของบอทได้รับสิทธิ์ **Move Members (ย้ายสมาชิก)** หรือไม่
- ตรวจสอบว่าบอทมีสิทธิ์เข้าห้องเสียง (Connect) ทั้ง 3 ห้องหรือไม่
2. **คำสั่งฟ้องว่าผู้ใช้มีสิทธิ์คุ้มกัน**:
- หากเป้าหมายเป็นเจ้าของเซิร์ฟเวอร์หรือมีสิทธิ์ Administrator ระบบจะป้องกันโดยอัตโนมัติเพื่อความปลอดภัยของเซิร์ฟเวอร์
