K AegisAutoRole

# 🎭 K AegisAutoRole — Intelligent Join-Role, Onboarding & Member Verification System ## ระบบมอบยศสมาชิกใหม่อัตโนมัติและแผงยืนยันตัวตนสำหรับ Discord [](https://www.python.org/) [](https://discordpy.readthedocs.io/) [](LICENSE) []() --- > **Short Summary / Description * (TH):** > 🎭 **K AegisAutoRole** คือระบบมอบยศสมาชิกใหม่อัตโนมัติและแผงยืนยันตัวตนระดับ Enterprise สำหรับเซิร์ฟเวอร์ Discord รองรับการมอบหลายยศพร้อมกันแบบ Atomic Batch, แยกยศระหว่างคนจริงกับบอท (Human & Bot Role Segregation), มีระบบหน่วงเวลาป้องกันการบุกถล่ม (Anti-Raid Delay) และปุ่มกดยืนยันตัวตน (Click-to-Verify Button) ที่ทำงานต่อเนื่องแม้รีสตาร์ตบอท 100% > **Short Summary / Description * (EN):** > 🎭 **K AegisAutoRole** is an enterprise-grade automated onboarding, join-role assignment, and member verification bot for Discord. It features multi-role batch assignment, human vs bot role segregation, anti-raid onboarding delays, and persistent interactive Click-to-Verify buttons. --- ## 📑 สารบัญ (Table of Contents) - [✨ จุดเด่นและฟีเจอร์หลัก (Core Features)](#-จุดเด่นและฟีเจอร์หลัก-core-features) - [🚀 ตารางเปรียบเทียบ (Legacy Bot vs K AegisAutoRole)](#-ตารางเปรียบเทียบ-legacy-bot-vs-k-aegisautorole) - [📋 คู่มือคำสั่ง Slash Commands ฉบับสมบูรณ์ (Command Reference)](#-คู่มือคำสั่ง-slash-commands-ฉบับสมบูรณ์-command-reference) - [🛠️ สถาปัตยกรรมระบบ (System Architecture)](#️-สถาปัตยกรรมระบบ-system-architecture) - [🚀 ขั้นตอนการติดตั้งและเริ่มต้นใช้งาน (Quickstart Guide)](#-ขั้นตอนการติดตั้งและเริ่มต้นใช้งาน-quickstart-guide) - [🧪 การทดสอบระบบ (Automated Tests)](#-การทดสอบระบบ-automated-tests) --- ## ✨ จุดเด่นและฟีเจอร์หลัก (Core Features) ### 1. 👥 Human & Bot Role Segregation - แยกการมอบยศระหว่างสมาชิกที่เป็นคนจริง (`human_roles`) และบอทที่ได้รับเชิญเข้าเซิร์ฟเวอร์ (`bot_roles`) ป้องกันไม่ให้บอทได้รับยศสมาชิกทั่วไป ### 2. ⚡ Atomic Multi-Role Batch Assignment - รองรับการมอบหลายยศพร้อมกันในการเรียก Discord API เพียงครั้งเดียว (`member.add_roles(*roles)`) รวดเร็ว ปลอดภัย และไม่ติด Rate Limit ### 3. 🛡️ Anti-Raid Join Delay - ตั้งเวลาหน่วง (0 - 600 วินาที) ก่อนมอบยศ ช่วยให้ระบบตรวจสอบหรือเจ้าหน้าที่สามารถระงับการบุกถล่มเซิร์ฟเวอร์ (Raid Attack) ได้ทันท่วงที ### 4. 🔘 Persistent Click-to-Verify Panel - สร้างแผงปุ่มกดยืนยันตัวตนในห้องกฎระเบียบ สมาชิกคลิกปุ่มเพียง 1 ครั้งเพื่อรับยศและปลดล็อกห้องแชท ปุ่มกดไม่มีวันหมดอายุแม้บอทจะรีสตาร์ต ### 5. 📬 Customizable Welcome & DM Card - ส่งข้อความต้อนรับเข้าห้อง Welcome พร้อมการ์ด Embed สวยงาม แสดงรูป Avatar ลำดับสมาชิก และแท็กเวลา Discord `<t:unix:R>` - เลือกระบบส่งข้อความส่วนตัว (Direct Message) ต้อนรับสมาชิกใหม่พร้อมตัวแปรปรับแต่ง `{user}`, `{server}`, `{time}` --- ## 🚀 ตารางเปรียบเทียบ (Legacy Bot vs K AegisAutoRole) | ความสามารถ | บอทเดิม (Legacy Bot) | 🎭 K AegisAutoRole (Modern) | |---|---|---| | **การตั้งค่า** | ฮาร์ดโค้ดชื่อยศและห้อง log ในโค้ด python | **ตั้งค่าผ่าน Slash Commands บันทึก JSON ถาวร** | | **จำนวนยศ** | รองรับได้แค่ 1 ยศ | **มอบหลายยศพร้อมกันแบบ Multi-Role Batch** | | **การแยกประเภทสมาชิก** | มอบยศเดียวกันหมดทั้งคนและบอท | **แยกยศคนกับยศบอทชัดเจน (Human / Bot)** | | **ระบบป้องกันการบุก** | ไม่มี คนเข้าปุ๊บได้ยศทันที เสี่ยง Raid | **มีตัวหน่วงเวลา Anti-Raid Delay (0-600s)** | | **แผงปุ่มกดยืนยันตัวตน** | ไม่มี | **สร้างแผง Click-to-Verify ด้วยปุ่ม UI ถาวร** | | **การจัดการเวลา** | คำนวณบวกเวลา UTC+7 แบบเดิม (Deprecated) | **Discord Native Timestamp Tags (`<t:unix:F>`)** | | **Logging & Terminal** | Print ข้อความธรรมดา | **Rich Console, Rotating Log 5MB** | --- ## 📋 คู่มือคำสั่ง Slash Commands ฉบับสมบูรณ์ (Command Reference) ### 👤 ยศสมาชิกใหม่ (`/autorole human`) | คำสั่ง | พารามิเตอร์ | คำอธิบาย | |---|---|---| | `/autorole human add` | `role` *(Required)* | เพิ่ม Role ที่จะมอบให้สมาชิกใหม่ที่เป็นคนจริง | | `/autorole human remove` | `role` *(Required)* | ลบ Role ออกจากรายการมอบให้อัตโนมัติ | | `/autorole human list` | *(None)* | แสดงรายชื่อ Role ทั้งหมดที่ตั้งไว้สำหรับสมาชิก | ### 🤖 ยศบอท (`/autorole bot`) | คำสั่ง | พารามิเตอร์ | คำอธิบาย | |---|---|---| | `/autorole bot add` | `role` *(Required)* | เพิ่ม Role สำหรับบอทที่ได้รับเชิญเข้าเซิร์ฟเวอร์ | | `/autorole bot remove` | `role` *(Required)* | ลบ Role บอทออกจากรายการ | ### ⚙️ การตั้งค่าระบบ Onboarding (`/autorole`) | คำสั่ง | พารามิเตอร์ | คำอธิบาย | |---|---|---| | `/autorole config` | `delay_seconds`, `send_dm`, `welcome_channel`, `log_channel`, `dm_message` | ปรับแต่งตัวเลือกทั้งหมดของระบบ Auto-Role | | `/autorole status` | *(None)* | ตรวจสอบภาพรวมการตั้งค่าทั้งหมดของเซิร์ฟเวอร์ | | `/autorole verify_panel` | `channel` *(Required)*, `role` *(Required)*, `title`, `description` | สร้างแผงปุ่มกดยืนยันตัวตนในห้องที่กำหนด | ### ℹ️ คำสั่งทั่วไป | คำสั่ง | คำอธิบาย | |---|---| | `/ping` | เช็กความเร็ว Gateway WebSocket | | `/stats` | แสดงสถิติการใช้งาน RAM, OS, Python และจำนวนสมาชิก | | `/help` | แสดงคู่มือการใช้งานบอทแบบโต้ตอบ | --- ## 🛠️ สถาปัตยกรรมระบบ (System Architecture) ```mermaid flowchart TD JoinEvent([สมาชิกใหม่เข้าเซิร์ฟเวอร์]) --> Gateway[Discord Gateway Event] Gateway --> CogEvents[cogs/events.py\non_member_join] subgraph AutoRole Engine CogEvents --> CheckBot{สมาชิกเป็นบอทหรือไม่?} CheckBot -->|คนจริง| LoadHumanRoles[โหลด human_role_ids] CheckBot -->|บอท| LoadBotRoles[โหลด bot_role_ids] LoadHumanRoles --> DelayCheck{มีการหน่วงเวลาหรือไม่?} DelayCheck -->|มี| SleepDelay[asyncio.sleep delay_seconds] DelayCheck -->|ไม่มี| FilterHierarchy SleepDelay --> FilterHierarchy[คัดกรองยศที่ต่ำกว่าบอท\nRole Hierarchy Filter] FilterHierarchy --> BatchAssign[มอบยศแบบ Atomic Batch\nmember.add_roles] BatchAssign --> SendWelcome[ส่งการ์ดห้อง Welcome] BatchAssign --> SendDM[ส่งข้อความต้อนรับทาง DM] BatchAssign --> AuditLog[บันทึกลงห้อง Audit Log] end subgraph Click-to-Verify UserClick([สมาชิกกดปุ่ม Verify]) --> PersistentView[VerificationView\nPersistent Button Callback] PersistentView --> AssignVerifiedRole[มอบยศทันที] end subgraph Storage DataMgr[data_manager.py] --> JSONCfg[(data/autorole_config.json)] AegisAutoRole --> LogFile[(logs/autorole.log)] end ``` --- ## 🚀 ขั้นตอนการติดตั้งและเริ่มต้นใช้งาน (Quickstart Guide) ### 1. ความต้องการพื้นฐาน - **Python 3.11 หรือใหม่กว่า** - สิทธิ์ของบอทในเซิร์ฟเวอร์: **Manage Roles (จัดการบทบาท)**, **Send Messages**, **Embed Links** - **ลำดับยศ (Role Hierarchy):** ยศของบอทต้องอยู่สูงกว่ายศที่จะมอบให้สมาชิก ### 2. ติดตั้ง Dependencies ```bash pip install -r requirements.txt ``` ### 3. ตั้งค่าโทเคน สร้างไฟล์ `.env` (คัดลอกจาก `.env.example`): ```ini DISCORD_BOT_TOKEN=ใส่โทเคนบอทของคุณที่นี่ ``` ### 4. รันระบบ ```bash python main.py ``` --- ## 🧪 การทดสอบระบบ (Automated Tests) ```bash python test_suite.py ```