# 📖 K AegisOCR — Full Technical Documentation & Architecture Reference
## เอกสารและคู่มือการทำงานฉบับสมบูรณ์ (Bilingual Edition)
> **Language / ภาษา**: [🇹🇭 ภาษาไทย](#-ภาษาไทย-thai-version) | [🇬🇧 English](#-english-version)
---
# 🇹🇭 ภาษาไทย (Thai Version)
## 📑 สารบัญ (TH)
1. [ภาพรวมของระบบ (System Overview)](#1-ภาพรวมของระบบ-th)
2. [สถาปัตยกรรมและกระบวนการประมวลผลภาพ (Vision Pipeline)](#2-สถาปัตยกรรมและกระบวนการประมวลผลภาพ-th)
3. [ฟีเจอร์การทำงานอย่างละเอียด (Full Feature Specifications)](#3-ฟีเจอร์การทำงานอย่างละเอียด-th)
4. [ตารางคำสั่ง Slash Commands และ Context Menu (Commands Reference)](#4-ตารางคำสั่ง-slash-commands-และ-context-menu-th)
5. [การตั้งค่าฐานข้อมูลและการจัดเก็บข้อมูล (Data Architecture)](#5-การตั้งค่าฐานข้อมูลและการจัดเก็บข้อมูล-th)
6. [การแก้ไขปัญหาที่พบบ่อย (Troubleshooting & FAQ)](#6-การแก้ไขปัญหาที่พบบ่อย-th)
---
### 1. ภาพรวมของระบบ (TH)
**K AegisOCR** เป็นระบบสกัดข้อความจากภาพ (Optical Character Recognition) สำหรับ Discord ระดับ Enterprise ที่ถูกออกแบบมาเพื่อทดแทนสคริปต์บอทแบบเดิม:
- **หมดปัญหาบอทกระตุกหรือค้าง**: กระบวนการ OCR ทั้งหมดถูกรันผ่าน `asyncio.to_thread` ไม่บล็อก Discord Gateway Heartbeat
- **หมดปัญหาการแจ้งเตือนสแปม**: แยกการทำงานระหว่างคำสั่ง Slash Command กับห้องสแกนภาพอัตโนมัติ ไม่ตอบกวนในห้องทั่วไป
- **รองรับข้อความยาวแบบไม่จำกัด**: แปลงเป็นไฟล์ข้อความ `.txt` อัตโนมัติเมื่อข้อความยาวเกินข้อจำกัด 2,000 ตัวอักษรของ Discord
- **ระบบคัดลอกข้อความง่าย (One-Click Copy)**: มีปุ่มส่งข้อความแบบ Ephemeral ให้ผู้ใช้กดคัดลอกได้ทันทีทั้งบนคอมพิวเตอร์และสมาร์ตโฟน
---
### 2. สถาปัตยกรรมและกระบวนการประมวลผลภาพ (TH)
```
[ ภาพต้นฉบับ ]
│
▼
[ Image Preprocessing ] ───► ขยายภาพ (Lanczos Upscale if < 800px)
│ ───► แปลง Grayscale (โหมด L)
│ ───► ปรับ Contrast 2.0x & Sharpen 1.5x
▼
[ Async ThreadPool ] ───► แยก Thread ไม่บล็อก Event Loop
│
▼
[ Tesseract OCR Engine ] ───► เลือกโมเดลภาษา (tha+eng, jpn, chi_sim)
│ ───► กำหนด Page Segmentation Mode (--psm 3)
▼
[ Post-Processing ] ───► ล้างช่องว่างซ้ำซ้อน (Regex Normalize)
│ ───► คำนวณความยาวตัวอักษรและจำนวนคำ
▼
[ Discord Delivery ] ───► ข้อความ <= 1500 ตัว: แสดงใน Embed
───► ข้อความ > 1500 ตัว: พรีวิว + แนบไฟล์ .txt
```
---
### 3. ฟีเจอร์การทำงานอย่างละเอียด (TH)
#### 3.1 ระบบสแกนภาพตามความต้องการ (On-Demand Slash Command)
- คำสั่ง `/ocr scan` รองรับการปรับแต่งภาพก่อนอ่าน:
- `auto`: ปรับ Contrast และ Sharpening อัตโนมัติ (แนะนำสำหรับเอกสารทั่วไป)
- `grayscale`: ปรับเป็นขาวดำธรรมดา (เหมาะสำหรับภาพที่มีความสว่างสม่ำเสมอ)
- `threshold`: ปรับเป็นขาวดำแบบ Binary จุดตัดเด็ดขาด (เหมาะสำหรับสลิปโอนเงินหรือใบเสร็จ)
- `raw`: ไม่ปรับแต่งภาพ (เหมาะสำหรับภาพที่คมชัดอยู่แล้ว)
#### 3.2 ระบบสแกนภาพจาก Context Menu (Right-Click App)
- ผู้ใช้สามารถคลิกขวาที่รูปภาพใดๆ ในเซิร์ฟเวอร์ -> เลือก **Apps** -> **Extract Text (OCR)**
- บอทจะทำการอ่านภาพและส่งข้อความที่ถอดได้กลับมาแบบ **Ephemeral** (เห็นเฉพาะตัวผู้คลิกเท่านั้น) เพื่อความเป็นส่วนตัว
#### 3.3 ระบบห้องสแกนอัตโนมัติ (Monitored Channels)
- แอดมินสามารถกำหนดห้องที่ต้องการให้บอทคอยอ่านภาพ เช่น ห้อง `#ส่งสลิป`, `#ใบเสร็จ`, หรือ `#ocr-lab` ด้วยคำสั่ง `/ocr_channel add #ห้อง`
- เมื่อมีสมาชิกส่งภาพลงในห้องนี้ บอทจะทำการถอดข้อความและพรีวิวให้ทันที
#### 3.4 คลังคำตอบโต้ตอบอัจฉริยะ (Smart Auto-Response Dictionary)
- บอทสามารถจับคู่คีย์เวิร์ดที่พบในภาพเข้ากับคำตอบที่เตรียมไว้
- ใช้อัลกอริทึม **Fuzzy Matching** (SequenceMatcher) เพื่อตรวจจับคำผิดหรือคำที่มีตัวอักษรตกหล่น โดยสามารถกำหนดค่าความเหมือน (Similarity Threshold) ได้
---
### 4. ตารางคำสั่ง Slash Commands และ Context Menu (TH)
| คำสั่ง / เมนู | สิทธิ์ที่ต้องการ | คำอธิบายการใช้งาน |
|---|---|---|
| `/ocr scan` | ทุกคน | สแกนภาพที่แนบ พร้อมเลือกภาษาและโหมดแต่งภาพ |
| `/ocr_url` | ทุกคน | สแกนภาพจากลิงก์ URL ตรง |
| `Extract Text (OCR)` | ทุกคน | คลิกขวาที่ข้อความเพื่อสกัดตัวอักษรแบบส่วนตัว |
| `/ocr_response add` | Manage Server | เพิ่มคู่คีย์เวิร์ดและข้อความตอบกลับอัตโนมัติ |
| `/ocr_response remove`| Manage Server | ลบคีย์เวิร์ดที่ไม่ต้องการใช้งาน |
| `/ocr_response list` | ทุกคน | ดูรายการคีย์เวิร์ดที่ตั้งค่าไว้ทั้งหมด |
| `/ocr_channel add` | Manage Channels | กำหนดห้องสำหรับสแกนภาพอัตโนมัติ |
| `/ocr_channel remove`| Manage Channels| ยกเลิกการสแกนภาพอัตโนมัติในห้องนั้น |
| `/ping` | ทุกคน | ตรวจสอบความเร็วการเชื่อมต่อของบอท |
| `/stats` | ทุกคน | ดูสถานะเซิร์ฟเวอร์ RAM, Python และ Tesseract Engine |
| `/help` | ทุกคน | แสดงคู่มือแนะนำการใช้งานแบบสรุป |
---
### 5. การตั้งค่าฐานข้อมูลและการจัดเก็บข้อมูล (TH)
- ข้อมูลการตั้งค่าถูกจัดเก็บในรูปแบบ JSON แบบแบ่งแยกไฟล์อย่างปลอดภัย:
- `data/ocr_settings.json`: เก็บการตั้งค่าห้องตรวจจับอัตโนมัติรายเซิร์ฟเวอร์
- `data/auto_responses.json`: เก็บคำตอบโต้ตอบอัตโนมัติ
- ใช้เทคนิค **Safe Atomic Write** (เขียนลง `.tmp` ก่อนเขียนทับไฟล์จริง) หมดปัญหาไฟล์ JSON พังหากไฟตกหรือปิดเครื่องกะทันหัน
---
### 6. การแก้ไขปัญหาที่พบบ่อย (TH)
1. **บอทแจ้งว่า `Tesseract not found`**:
- ตรวจสอบว่าได้ติดตั้ง Tesseract OCR ไว้ที่ `C:\Program Files\Tesseract-OCR\tesseract.exe` หรือไม่
- หากติดตั้งไว้ที่อื่น ให้ระบุพาธในไฟล์ `.env` เช่น `TESSERACT_PATH=D:\Tools\Tesseract\tesseract.exe`
2. **บอทอ่านภาษาไทยไม่ออก (เป็นตัวอักษรเอเลี่ยน)**:
- ตรวจสอบว่าในโฟลเดอร์ `tessdata` ของ Tesseract มีไฟล์ `tha.traineddata` หรือไม่ หากไม่มีสามารถดาวน์โหลดเพิ่มได้จาก [Tesseract tessdata repository](https://github.com/tesseract-ocr/tessdata)
