Initial commit

บริหารจัดการคิวนวดแผนไทย/docs/07_Developer_Security_Guide.md

@@ -0,0 +1,61 @@
+# 07. Enterprise Developer & Security Whitepaper
+**Project:** Thai Traditional Massage Queue Management System (TTMQMS Enterprise)  
+**Standard:** OWASP Top 10 2021 Mitigation & Clean Architecture PSR-12  
+**Version:** 1.0.0 Production  
+
+---
+
+## 1. Developer Architecture & Clean Code Guidelines
+ทีมพัฒนาจะต้องปฏิบัติตามมาตรฐานการเขียนโค้ดเพื่อรักษาความปลอดภัยและประสิทธิภาพสูงสุดของระบบ:
+- **PSR-12 Coding Standard:** โค้ด PHP ทั้งหมดใน `src/` ต้องผ่านเกณฑ์ PSR-12 การตั้งชื่อตัวแปรใช้ CamelCase สำหรับ Method/Property และ PascalCase สำหรับ Class
+- **Separation of Concerns:**
+  - **Controllers (`src/Controllers/`):** ทำหน้าที่ตรวจสอบ HTTP Request และส่งคืน JSON Response เท่านั้น ห้ามเขียนคำสั่ง SQL หรือ Business Logic ใน Controller เด็ดขาด
+  - **Services (`src/Services/`):** เป็นศูนย์รวม Business Logic เช่น `SmartQueueEngine`, `SoapNoteService`
+  - **Repositories / Models (`src/Models/`):** ทำหน้าที่ติดต่อฐานข้อมูลผ่าน PDO Prepared Statements เท่านั้น
+
+---
+
+## 2. OWASP Top 10 Security Checklist & Mitigation
+
+### 2.1 A01:2021 – Broken Access Control
+- **Mitigation:** ทุก API Endpoint (ยกเว้น `/auth/login` และ `/queues/walkin`) จะถูกตรวจสอบสิทธิ์ผ่าน `JwtAuthMiddleware` และ Role-Based Access Control (RBAC) หากหมอนวดพยายามเข้าถึง API ของแคชเชียร์ ระบบจะปฏิเสธด้วยสถานะ `HTTP 403 Forbidden`
+
+### 2.2 A02:2021 – Cryptographic Failures
+- **Mitigation:**
+  - รหัสผ่านผู้ใช้ถูกเข้ารหัสด้วย **Argon2id** (Memory-hard algorithm ที่ทนทานต่อ GPU Brute-force)
+  - ข้อมูลความลับและการสื่อสารระหว่างเซิร์ฟเวอร์ใช้ **TLS 1.3** และ **mTLS** สำหรับ HIS Gateway
+  - ข้อมูลส่วนบุคคลของผู้ป่วย (HN, เลขบัตร 13 หลัก) ได้รับการปกป้องตามนโยบาย PDPA
+
+### 2.3 A03:2021 – Injection (SQLi & XSS)
+- **Mitigation:**
+  - การเรียกใช้ฐานข้อมูลทั้งหมดผ่าน **PDO Prepared Statements with Bound Parameters** ป้องกัน SQL Injection 100%
+  - เอาต์พุตที่แสดงผลบนหน้าเว็บ PWA ถูกคัดกรองผ่าน Alpine.js `x-text` (Auto HTML-escaping) ป้องกัน Cross-Site Scripting (XSS)
+
+### 2.4 A07:2021 – Identification and Authentication Failures
+- **Mitigation:**
+  - บังคับใช้ **2-Factor Authentication (TOTP RFC 6238)** กับบัญชีเจ้าหน้าที่ทุกระดับ
+  - กำหนดเวลาหมดอายุของ JWT Access Token ไว้เพียง **60 นาที**
+  - ล็อกบัญชีผู้ใช้ชั่วคราว 15 นาที หากกรอกรหัสผ่านผิดเกิน 5 ครั้ง (Brute-force Throttle)
+
+---
+
+## 3. Comprehensive Troubleshooting Guide (การแก้ไขปัญหาเบื้องต้น)
+
+### ปัญหาที่ 1: เครื่องอ่านบัตรประชาชน Smart Card ไม่ตอบสนองเมื่อกดปุ่มบนหน้าเว็บ
+- **สาเหตุ:** เบราว์เซอร์ไม่ได้รับอนุญาตให้ใช้ WebUSB API หรือยังไม่ได้ติดตั้งบริการ PCSC Daemon
+- **วิธีแก้ไข:**
+  1. ตรวจสอบว่าเปิดใช้งานหน้าเว็บด้วย **Google Chrome** หรือ **Microsoft Edge** ผ่านโปรโตคอล **HTTPS**
+  2. ในเบราว์เซอร์ ไปที่ `chrome://settings/content/usbDevices` แล้วตรวจสอบว่าอนุญาตให้ `ttmqms.hospital.go.th` เข้าถึงอุปกรณ์ USB แล้ว
+  3. ตรวจสอบสถานะ PCSC Service ในเครื่องคอมพิวเตอร์: `sudo systemctl status pcscd` (Ubuntu) หรือใน Windows Services
+
+### ปัญหาที่ 2: AI Smart Queue ไม่ยอมจัดสรรหมอนวด (แจ้งเตือน ไม่มีหมอนวดว่าง)
+- **สาเหตุ:** หมอนวดในสาขาปฏิบัติงานครบชั่วโมงกำหนด (Max Daily Mins = 480) หรือเปลี่ยนสถานะเป็น *Busy / Off_Duty*
+- **วิธีแก้ไข:**
+  1. ไปที่หน้า **"จัดการห้องนวด & เตียง"** เพื่อตรวจสอบว่ามีเตียงสถานะ *Available* หรือไม่
+  2. ตรวจสอบตาราง Workload ในหน้าผู้บริหาร หากหมอนวดทำงานครบ 8 ชม. ให้พิจารณากดเพิ่มโควตาเวลาชั่วคราวในหน้า Settings หรือเปลี่ยนสถานะหมอนวดท่านอื่นให้เป็น *Available*
+
+### ปัญหาที่ 3: เครื่องพิมพ์ความร้อน ESC/POS ไม่ออกใบคิว
+- **สาเหตุ:** ขาดการเชื่อมต่อสาย USB หรือกระดาษความร้อนหมด/เปิดฝาค้างไว้
+- **วิธีแก้ไข:**
+  1. ตรวจสอบไฟสถานะบนเครื่องพิมพ์ ESC/POS 80mm
+  2. กดปุ่ม **"เชื่อมต่อ USB Printer"** ที่มุมขวาบนของหน้าเว็บอีกครั้ง และเลือกชื่ออุปกรณ์ Printer จาก Popup ของเบราว์เซอร์