# Agent Guidelines & Rules: ai_rekogition_smart

> **Date Reference:** 2026-08-31  
> **Commit Hash:** `[ต้องยืนยันกับทีม: ไม่พบ .git history ในไดเรกทอรีโปรเจกต์ (ไดเรกทอรี .git ว่างเปล่า) / uncommitted]`

---

## 1. ขอบเขตและกติกาสำหรับ AI Agent (Agent Rules)

เอกสารนี้กำหนดแนวทางและข้อปฏิบัติสำหรับ AI Agent ในการพัฒนา ปรับปรุง หรือแก้ไขโค้ดในโปรเจกต์ **ai_rekogition_smart** เพื่อป้องกันผลกระทบต่อข้อมูลจริงและความเสถียรของระบบ

---

## 2. สิ่งที่ทำได้อิสระ (Allowed Actions Without Prior Permission)

- **การแก้ไข Bug ในระดับไฟล์เดี่ยว (Single-file Bug Fixes)**: แก้ไขตรรกะข้อผิดพลาดใน Service หรือ Repository โดยไม่เปลี่ยน Signature ของ Public Method
- **การเขียนและปรับปรุงชุดทดสอบ (Adding & Improving Tests)**: เพิ่ม Unit/Integration Test ในไดเรกทอรี `tests/`
- **การปรับปรุงความปลอดภัยโค้ดภายใน**: เช่น เพิ่มการตรวจสอบ Sanitization, ปรับปรุงการจัดการ Exception, เพิ่มการ Cleanup Temp Files
- **การปรับแต่ง UI / CSS / JavaScript ฝั่งหน้าบ้าน**: ปรับปรุงหน้าตาและการตอบสนองใน `public/assets/` หรือ `SearchResultsRenderer.php` โดยไม่กระทบโครงสร้าง API Contract
- **การปรับปรุงเอกสารและ Docblocks**: เพิ่ม Type Hints, PHPDoc, และเอกสารคำอธิบายการทำงานใน `graft/` หรือ Markdown files

---

## 3. สิ่งที่ต้องขออนุญาต / ห้ามแตะโดยไม่ได้รับความเห็นชอบ (Restricted Actions)

- **การแก้ไข Database Schema และ Migration (`database/*.sql`)**: ห้ามแก้ไข Schema เดิมที่ใช้งานอยู่โดยพลการ การเพิ่มตารางหรือคอลัมน์ใหม่ต้องทำเป็น Migration ไฟล์ใหม่และขอการยืนยันก่อนเสมอ
- **ไฟล์ความปลอดภัยและการตรวจสอบสิทธิ์ (`src/ProfileAuth.php`, `config.php`)**: ห้ามแก้ไขกลไกการเข้ารหัส, Session Handling, หรือ Hardcoded Logic โดยไม่ได้รับอนุมัติ
- **การลบข้อมูลบน Cloud Storage (AWS S3) หรือ Rekognition Collections**: ห้ามรันคำสั่งหรือเขียนสคริปต์ที่สั่ง `DeleteObjects`, `DeleteCollection`, หรือลบ Records ในฐานข้อมูลแบบ Bulk
- **ไฟล์ตั้งค่าระบบและ Credentials (`config.php`, `config.example.php`)**: ห้ามนำ Secret Keys หรือ Passwords ของจริงไปเผยแพร่หรือเขียนทับด้วยข้อมูลม็อคที่ทำให้ระบบจริงใช้งานไม่ได้
- **การ Deploy / Production Configuration**: ห้ามเปลี่ยน Endpoint หรือ Config ที่กระทบ Production

---

## 4. มาตรฐานและแบบแผนในการพัฒนา (Coding & Project Conventions)

### 4.1 ภาษาและโครงสร้างโค้ด (PHP Standards)
- **Strict Types**: ต้องใส่ `declare(strict_types=1);` ไว้บนสุดของไฟล์ PHP ทุกไฟล์
- **PSR-4 Autoloading**: โค้ดทั้งหมดใน `src/` ต้องอยู่ภายใต้ Namespace `App\`
- **Type Safety**: ระบุ Type Declaration ให้กับ Parameter, Return Type, และ Class Properties ทุกตัว
- **Error Handling**: โยน Exception (`\RuntimeException`, `\InvalidArgumentException`) เมื่อเกิดข้อผิดพลาด และดักจับ `\Throwable` หรือ `\Aws\Exception\AwsException` ในระดับ Controller/Endpoint

### 4.2 ความปลอดภัยและการจัดการข้อมูล (Security Conventions)
- **Database Access**: ใช้ PDO Prepared Statement พร้อม Parameter Binding เสมอ ห้ามนำตัวแปรภายนอกมาต่อสตริง SQL โดยตรง
- **XSS Prevention**: ข้อมูลที่นำมาแสดงผลบน HTML ต้องผ่าน `htmlspecialchars($var, ENT_QUOTES, 'UTF-8')`
- **Session & CSRF**: มีการทำ `session_regenerate_id(true)` เมื่อยืนยันตัวตนสำเร็จ และตรวจสอบ Token สำหรับการดาวน์โหลดผ่าน `SearchDownloadTokens::verify()`
- **Resource Cleanup**: เมื่อประมวลผลไฟล์ชั่วคราว (Temporary Files) เช่น การแปลง HEIC หรือสร้าง Thumbnail ต้องครอบด้วยบล็อก `try ... finally` เพื่อสั่ง `@unlink()` หรือ `cleanup()` เสมอ

### 4.3 โครงสร้างโฟลเดอร์และการจัดเก็บไฟล์ (Directory Layout)
- `src/` — Business Logic, Services, Repositories, Helpers
- `public/` — Web Entry Points (Controllers / Pages / API Endpoints)
- `public/assets/` — CSS, JavaScript, Images
- `database/` — SQL Schema (`schema.sql`) และไฟล์ Migration แยกตามการเปลี่ยนแปลง
- `scripts/` — CLI Utility Scripts เช่น `create_collection.php`
- `storage/sessions/` — ไฟล์ PHP Session Storage
- `tests/` — Test Suites (`smoke.php`)

### 4.4 รูปแบบ Commit Message และ Tooling
- **Commit Message Style**: `[ต้องยืนยันกับทีม: ยังไม่มีการระบุข้อกำหนด Commit Message เช่น Conventional Commits (feat:, fix:, refactor:) รอทีมยืนยัน]`
- **Lint / Formatting Commands**: `[ต้องยืนยันกับทีม: ปัจจุบันยังไม่มี PHPStan / PHP_CodeSniffer / ESLint กำหนดไว้ใน composer.json แนะนำให้รัน composer test / php tests/smoke.php ก่อน Commit]`
- **คำสั่งรันเซิร์ฟเวอร์ทดสอบ**: `composer run serve` (หรือ `php -S localhost:8000 -t public`)
- **คำสั่งรันชุดทดสอบ**: `composer test` (หรือ `php tests/smoke.php`)