# 📖 K AegisStaff — Full Technical Documentation & Architecture Reference
## เอกสารและคู่มือการทำงานฉบับสมบูรณ์ (Bilingual Edition)
> **Language / ภาษา**: [🇹🇭 ภาษาไทย](#-ภาษาไทย-thai-version) | [🇬🇧 English](#-english-version)
---
# 🇹🇭 ภาษาไทย (Thai Version)
## 📑 สารบัญ (TH)
1. [ภาพรวมของระบบ (System Overview)](#1-ภาพรวมของระบบ-th)
2. [สถาปัตยกรรมและกลไกการตรวจสอบสิทธิ์ (Architecture & Hierarchy)](#2-สถาปัตยกรรมและกลไกการตรวจสอบสิทธิ์-th)
3. [ฟีเจอร์การทำงานอย่างละเอียด (Full Feature Specifications)](#3-ฟีเจอร์การทำงานอย่างละเอียด-th)
4. [ตารางคำสั่ง Slash Commands ฉบับสมบูรณ์ (Command Reference)](#4-ตารางคำสั่ง-slash-commands-ฉบับสมบูรณ์-th)
5. [โครงสร้างการจัดเก็บข้อมูลและการจัดการ (Data Management)](#5-โครงสร้างการจัดเก็บข้อมูลและการจัดการ-th)
6. [การแก้ไขปัญหาที่พบบ่อย (Troubleshooting & FAQ)](#6-การแก้ไขปัญหาที่พบบ่อย-th)
---
### 1. ภาพรวมของระบบ (TH)
**K AegisStaff** เป็นระบบการจัดการเซิร์ฟเวอร์และลงโทษสมาชิก (Server Moderation & Administration) สำหรับ Discord ระดับ Enterprise ถูกออกแบบและเขียนขึ้นใหม่ทั้งหมดเพื่อแก้ปัญหาข้อบกพร่องของระบบเดิม:
- **แก้ไขปัญหาย้าย/ปิดเสียงช้า**: เปลี่ยนมาใช้ Discord Native Timeout API v10 ปิดเสียงได้ทันทีใน 0.1 วินาที ไม่ต้องวนลูปแก้สิทธิ์ทีละห้อง
- **แก้ไขปัญหาห้องรก**: บอทเดิมจะสร้างห้อง `welcome` ใหม่ทุกครั้งที่คนเข้าจนชนลิมิต 500 ห้องของ Discord ระบบใหม่มีคำสั่งตั้งค่าห้องต้อนรับชัดเจน ไม่มีการสร้างห้องมั่ว
- **แก้ไขปัญหาระบบโพลล์แครช**: แก้ไขโค้ดที่เรียก `.add_reaction()` บนค่าว่าง โดยปรับมาใช้ Discord UI Buttons ที่แข็งแกร่งและนับคะแนนสด
- **ระบบ Role Hierarchy ปลอดภัย 100%**: ตรวจสอบลำดับยศของผู้สั่งและบอทก่อนลงโทษเสมอ ป้องกัน `403 Forbidden`
---
### 2. สถาปัตยกรรมและกลไกการตรวจสอบสิทธิ์ (TH)
- **Role Hierarchy Enforcement**:
1. ผู้ใช้ทั่วไปไม่สามารถสั่งลงโทษ Server Owner หรือผู้ที่มี Role สูงกว่าตนเองได้
2. บอทจะไม่พยายามลงโทษผู้ที่มี Role สูงกว่าหรือเท่ากับยศสูงสุดของตัวบอท
- **Timeout Duration Engine**: รองรับการแปลงหน่วยเวลาทั้ง วินาที (`s`), นาที (`m`), ชั่วโมง (`h`), และวัน (`d`) ได้สูงสุด 28 วันตามมาตรฐานของ Discord
---
### 3. ฟีเจอร์การทำงานอย่างละเอียด (TH)
#### 3.1 การควบคุมวินัย (Moderation Actions)
- `/kick`: เตะสมาชิก พร้อมระบุเหตุผลและส่งการ์ดแจ้งเตือนผ่าน DM
- `/ban`: แบนสมาชิก พร้อมฟังก์ชันเลือกลบข้อความย้อนหลัง (0-7 วัน)
- `/unban`: ปลดแบนสมาชิกจากรายชื่อแบน
- `/timeout`: ระงับสิทธิ์สมาชิกด้วย Discord Timeout API
#### 3.2 ระบบตักเตือนและบันทึกประวัติ (Warning Tracker)
- บันทึกการเตือนทุกครั้งลงฐานข้อมูลพร้อม Warn ID, ผู้ลงโทษ, เวลา และเหตุผล
- สมาชิกสามารถถูกตรวจสอบประวัติย้อนหลังได้ตลอดเวลาผ่าน `/warn list`
#### 3.3 เครื่องมือจัดการห้องแชท (Chat Management)
- `/clear`: ลบข้อความ 1-100 ข้อความพร้อมตัวกรอง (คัดกรองเฉพาะผู้ใช้, เฉพาะบอท, หรือเฉพาะข้อความที่มีคีย์เวิร์ด)
- `/slowmode`: ปรับความช้าในการพิมพ์ 0 - 21,600 วินาที
- `/lock` & `/unlock`: ล็อกและปลดล็อกห้องแชทชั่วคราว
#### 3.4 ระบบโพลล์สำรวจความคิดเห็น (Interactive Polls)
- สร้างโพลล์คำถามพร้อมตัวเลือก 2-4 ตัวเลือก
- สมาชิกในเซิร์ฟเวอร์สามารถคลิกปุ่มโหวต และกดซ้ำเพื่อยกเลิกการโหวตได้แบบ Real-time
---
### 4. ตารางคำสั่ง Slash Commands ฉบับสมบูรณ์ (TH)
| คำสั่ง | สิทธิ์ที่ต้องการ | คำอธิบาย |
|---|---|---|
| `/kick` | Kick Members | เตะสมาชิกออกจากเซิร์ฟเวอร์ |
| `/ban` | Ban Members | แบนสมาชิกพร้อมเลือกลบประวัติข้อความ |
| `/unban` | Ban Members | ปลดแบนสมาชิก |
| `/timeout` | Moderate Members | สั่ง Timeout สมาชิกตามเวลาที่ระบุ |
| `/untimeout` | Moderate Members | ยกเลิก Timeout สมาชิก |
| `/warn add` | Manage Messages | เพิ่มการตักเตือนและบันทึกประวัติ |
| `/warn list` | ทุกคน | ดูประวัติการโดนเตือนของสมาชิก |
| `/warn clear` | Administrator | ล้างประวัติคำเตือน |
| `/clear` | Manage Messages | ล้างข้อความแบบมีฟิลเตอร์ |
| `/slowmode` | Manage Channels | ปรับความเร็วในการพิมพ์แชท |
| `/lock` | Manage Channels | ล็อกห้องแชท |
| `/unlock` | Manage Channels | ปลดล็อกห้องแชท |
| `/role add` | Manage Roles | มอบ Role แก่สมาชิก |
| `/role remove` | Manage Roles | ถอด Role ออกจากสมาชิก |
| `/userinfo` | ทุกคน | ดูข้อมูลสมาชิกและสถิติการสร้างบัญชี |
| `/serverinfo` | ทุกคน | ดูสถิติเซิร์ฟเวอร์ |
| `/poll` | ทุกคน | สร้างแบบสำรวจแบบ Interactive Buttons |
| `/staff_config log_channel` | Administrator | กำหนดห้องส่ง Audit Log |
| `/staff_config welcome` | Administrator | กำหนดห้องและข้อความต้อนรับ |
---
### 5. โครงสร้างการจัดเก็บข้อมูลและการจัดการ (TH)
- จัดเก็บข้อมูลทั้งหมดลงใน `data/moderation_data.json` ด้วยระบบ **Safe Atomic Write**
- บันทึกการทำงานทั้งหมดลงใน `logs/staff.log` ขนาดสูงสุด 5MB แบบหมุนเวียน 3 ไฟล์
---
### 6. การแก้ไขปัญหาที่พบบ่อย (TH)
1. **บอทแจ้งว่ายศของเป้าหมายสูงเกินไป**:
- ไปที่ Server Settings -> Roles แล้วลากยศของบอทให้อยู่ "สูงกว่า" ยศของสมาชิกที่ต้องการเตะหรือแบน
2. **ไม่พบข้อความ Log ส่งไปยังห้อง**:
- ให้รันคำสั่ง `/staff_config log_channel #ห้องที่ต้องการ` และตรวจสอบว่าบอทมีสิทธิ์ส่งข้อความในห้องนั้น
