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

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 ของเบราว์เซอร์