Initial commit

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

@@ -0,0 +1,240 @@
+# 05. Enterprise Installation & Production Deployment Guide
+**Project:** Thai Traditional Massage Queue Management System (TTMQMS Enterprise)  
+**Target Environments:** Hospital DMZ / On-Premise Ubuntu 22.04 LTS / AWS / Google Cloud  
+**Containerization:** Docker & Docker Compose  
+**Version:** 1.0.0 Production  
+
+---
+
+## 1. System Requirements & Hardware Specification
+ก่อนเริ่มติดตั้งระบบ โปรดตรวจสอบความพร้อมของเซิร์ฟเวอร์ตามเกณฑ์ขั้นต่ำสำหรับสภาพแวดล้อม Production:
+- **CPU:** 4 Cores (Intel Xeon / AMD EPYC หรือ AWS t3.xlarge ขึ้นไป)
+- **RAM:** 8 GB DDR4+ (แนะนำ 16 GB สำหรับระบบที่รองรับผู้ใช้ 500+ คน/วัน)
+- **Storage:** 100 GB NVMe SSD (สำหรับ Database และ Log Retention 5 ปี)
+- **OS:** Ubuntu 22.04 LTS / Debian 12 / RHEL 9
+- **Network:** Port 80/443 (HTTPS Web Traffic), Port 3306 (MySQL), Port 6379 (Redis), Port 8080 (HIS mTLS Gateway)
+
+---
+
+## 2. Automated Docker Deployment (Recommended)
+วิธีที่สะดวกรวดเร็วและเป็นมาตรฐานที่สุดคือการรันผ่าน **Docker Compose** ซึ่งรวม PHP 8.1-FPM, Nginx, MySQL 8.0 และ Redis ไว้ในชุดเดียว
+
+### Step 2.1: Clone Repository & Prepare Environment Variables
+```bash
+# 1. คัดลอกโค้ดจาก Git Repository
+git clone https://github.com/hospital-it/ttmqms-enterprise.git /opt/ttmqms
+cd /opt/ttmqms
+
+# 2. สร้างไฟล์การตั้งค่าตัวแปรระบบ (.env)
+cp .env.example .env
+chmod 600 .env
+
+# 3. แก้ไขค่ารหัสผ่านและคีย์ลับ
+nano .env
+```
+**ตัวอย่างการตั้งค่าไฟล์ `.env`:**
+```ini
+APP_ENV=production
+APP_DEBUG=false
+APP_URL=https://ttmqms.hospital.go.th
+APP_KEY=base64:7vX9/2zH+Q8L5mN3bV6xC1aS4dF0gH2jK5lP8rT9wU0=
+
+DB_HOST=mysql
+DB_PORT=3306
+DB_DATABASE=ttmqms_db
+DB_USERNAME=ttmqms_user
+DB_PASSWORD=SuperSecretDbPassword@2026
+DB_ROOT_PASSWORD=SuperSecretRootPassword@2026
+
+REDIS_HOST=redis
+REDIS_PORT=6379
+REDIS_PASSWORD=SuperSecretRedisPassword@2026
+
+HIS_API_URL=https://192.168.1.250:8080/api
+HIS_MTLS_CERT_PATH=/etc/ssl/his/client.crt
+HIS_MTLS_KEY_PATH=/etc/ssl/his/client.key
+
+JWT_SECRET=EnterpriseJwtSecretKeyForTokenSigning9988776655
+JWT_TTL_MINUTES=60
+```
+
+### Step 2.2: Build and Launch Containers
+```bash
+# รันคำสั่งสร้างและเริ่มต้น Docker Containers ในโหมด Background
+docker compose up -d --build
+
+# ตรวจสอบสถานะการทำงานของ Container ทั้ง 4 ตัว (nginx, php, mysql, redis)
+docker compose ps
+```
+
+### Step 2.3: Initialize Database Schema & Stored Procedures
+```bash
+# สั่งรันสคริปต์นำเข้าโครงสร้างตาราง, Views, Triggers และ Stored Procedures
+docker exec -i ttmqms-mysql mysql -u root -pSuperSecretRootPassword@2026 ttmqms_db < database/schema.sql
+
+# ยืนยันการนำเข้าข้อมูลตัวอย่าง (Mock Data & Super Admin Account)
+docker exec -i ttmqms-mysql mysql -u root -pSuperSecretRootPassword@2026 ttmqms_db -e "SELECT id, national_id, full_name, role FROM users;"
+```
+
+---
+
+## 3. Nginx Reverse Proxy & SSL/TLS 1.3 Configuration
+เพื่อความปลอดภัยสูงสุดและรองรับ PWA Service Worker อย่างสมบูรณ์ ต้องกำหนดค่า Nginx ให้บังคับใช้ **HTTPS (TLS 1.2 / 1.3)** และแนบ Security Headers
+
+**ไฟล์การตั้งค่า `/etc/nginx/sites-available/ttmqms.conf`:**
+```nginx
+server {
+    listen 80;
+    server_name ttmqms.hospital.go.th;
+    return 301 https://$host$request_uri;
+}
+
+server {
+    listen 443 ssl http2;
+    server_name ttmqms.hospital.go.th;
+    root /opt/ttmqms/public;
+    index index.php index.html;
+
+    # SSL Certificates (Let's Encrypt / Hospital Enterprise CA)
+    ssl_certificate /etc/letsencrypt/live/ttmqms.hospital.go.th/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/ttmqms.hospital.go.th/privkey.pem;
+    ssl_protocols TLSv1.2 TLSv1.3;
+    ssl_ciphers HIGH:!aNULL:!MD5;
+    ssl_prefer_server_ciphers on;
+
+    # OWASP Security Headers
+    add_header X-Frame-Options "SAMEORIGIN" always;
+    add_header X-XSS-Protection "1; mode=block" always;
+    add_header X-Content-Type-Options "nosniff" always;
+    add_header Referrer-Policy "no-referrer-when-downgrade" always;
+    add_header Content-Security-Policy "default-src 'self' http: https: data: blob: 'unsafe-inline' 'unsafe-eval';" always;
+    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always;
+
+    # PWA Service Worker Routing & Static Asset Caching
+    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot|manifest\.json)$ {
+        expires 30d;
+        add_header Cache-Control "public, no-transform";
+    }
+
+    # Front Controller Routing (REST API & View Router)
+    location / {
+        try_files $uri $uri/ /index.php?$query_string;
+    }
+
+    location ~ \.php$ {
+        fastcgi_pass php-fpm:9000;
+        fastcgi_index index.php;
+        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
+        include fastcgi_params;
+        fastcgi_read_timeout 60;
+    }
+
+    # Deny access to sensitive files (.env, git, sql)
+    location ~ /\.(?!well-known).* {
+        deny all;
+    }
+}
+```
+
+---
+
+## 4. CI/CD Pipeline Configuration (GitHub Actions -> Production)
+การตรวจสอบคุณภาพโค้ด (Lint/Test) และ Deploy ขึ้นเซิร์ฟเวอร์โรงพยาบาลแบบอัตโนมัติเมื่อทำการ Merge เข้าสาขา `main`
+
+**ไฟล์ `.github/workflows/deploy.yml`:**
+```yaml
+name: TTMQMS Enterprise CI/CD Pipeline
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  test-and-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v3
+
+      - name: Setup PHP 8.1
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.1'
+          extensions: pdo_mysql, mbstring, gd, redis
+
+      - name: Validate PHP Syntax (Linting)
+        run: |
+          find . -name "*.php" -exec php -l {} \; | grep -v "No syntax errors" || true
+
+  deploy-production:
+    needs: test-and-lint
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy via SSH to Hospital Production Server
+        uses: appleboy/ssh-action@master
+        with:
+          host: ${{ secrets.PROD_HOST }}
+          username: ${{ secrets.PROD_USER }}
+          key: ${{ secrets.PROD_SSH_KEY }}
+          script: |
+            cd /opt/ttmqms
+            git pull origin main
+            docker compose down
+            docker compose up -d --build
+            docker system prune -f
+            echo "🚀 Deployment to TTMQMS Production Server Successful!"
+```
+
+---
+
+## 5. Manual Apache / XAMPP / MAMP / WAMP Deployment (การติดตั้งแบบคัดลอกลงโฟลเดอร์ `htdocs`)
+สำหรับโรงพยาบาลที่ใช้เซิร์ฟเวอร์แบบดั้งเดิม (On-Premise Apache Web Server) หรือผู้พัฒนาที่ต้องการรันผ่านจำลองเซิร์ฟเวอร์เช่น **XAMPP, MAMP, WAMP, AppServ** สามารถติดตั้งระบบโดยการคัดลอกไฟล์ไปวางในโฟลเดอร์ `htdocs` ได้ทันที 100% เนื่องจากระบบถูกสร้างด้วย PHP 8.1 สถาปัตยกรรม Clean Architecture โดยไม่พึ่งพา Node.js Server หรือ Build Pipeline ที่ซับซ้อน
+
+### Step 5.1: เตรียมความพร้อมโปรแกรมจำลองเซิร์ฟเวอร์ (XAMPP / MAMP)
+1. ตรวจสอบเวอร์ชันของ PHP ต้องเป็น **PHP 8.1 ขึ้นไป**
+2. เปิดไฟล์ `php.ini` (เช่น `C:\xampp\php\php.ini`) แล้วตรวจสอบให้แน่ใจว่าได้ลบเครื่องหมายเซมิโคลอน `;` เพื่อเปิดใช้งาน Extensions ดังนี้:
+   ```ini
+   extension=pdo_mysql
+   extension=mbstring
+   extension=gd
+   extension=intl
+   extension=curl
+   ```
+   *(หมายเหตุ: หากไม่มี Redis สามารถใช้งานได้ตามปกติ โดยระบบจะสลับไปใช้ Database/File Session พื้นฐาน)*
+
+### Step 5.2: คัดลอกไฟล์ระบบไปยังโฟลเดอร์ `htdocs`
+1. คัดลอกโฟลเดอร์โครงการ `ttmqms-enterprise` ทั้งหมดไปวางในโฟลเดอร์ `htdocs` ของท่าน:
+   - **Windows (XAMPP):** `C:\xampp\htdocs\ttmqms`
+   - **macOS (MAMP):** `/Applications/MAMP/htdocs/ttmqms`
+   - **Linux (Apache Manual):** `/var/www/html/ttmqms`
+2. ระบบได้เตรียมไฟล์ `.htaccess` ไว้ที่ Root (`/ttmqms/.htaccess`) และใน `/public/.htaccess` เรียบร้อยแล้ว ซึ่งจะทำการส่งคำขอทั้งหมดไปยัง Front Controller (`public/index.php`) และป้องกันการดาวน์โหลดไฟล์ความลับเช่น `.env` โดยอัตโนมัติ
+
+### Step 5.3: นำเข้าฐานข้อมูลผ่าน phpMyAdmin
+1. เปิดเบราว์เซอร์ไปที่ `http://localhost/phpmyadmin`
+2. สร้างฐานข้อมูลใหม่ชื่อ **`ttmqms_db`** (เลือก Collation เป็น `utf8mb4_unicode_ci` หรือ `utf8mb4_general_ci`)
+3. คลิกแท็บ **Import (นำเข้า)** เลือกไฟล์ `database/schema.sql` แล้วกด Import (ระบบจะสร้างโครงสร้างตารางทั้ง 13 ตาราง, Views, AI Stored Procedure, Triggers และข้อมูลตัวอย่างให้อัตโนมัติในครั้งเดียว)
+
+### Step 5.4: ตั้งค่าตัวแปรระบบในไฟล์ `.env`
+1. เข้าไปที่โฟลเดอร์ `htdocs/ttmqms` ทำการคัดลอกไฟล์ `.env.example` แล้วเปลี่ยนชื่อเป็น **`.env`**
+2. เปิดไฟล์ `.env` ด้วย Notepad หรือ VS Code แล้วตั้งค่าการเชื่อมต่อ MySQL ตามเครื่องของท่าน (ตัวอย่างของ XAMPP):
+   ```ini
+   APP_ENV=local
+   APP_DEBUG=true
+   APP_URL=http://localhost/ttmqms
+
+   DB_HOST=127.0.0.1
+   DB_PORT=3306
+   DB_DATABASE=ttmqms_db
+   DB_USERNAME=root
+   DB_PASSWORD=
+   ```
+
+### Step 5.5: เข้าใช้งานระบบผ่านเว็บเบราว์เซอร์
+- เปิดเบราว์เซอร์แล้วพิมพ์ URL: **`http://localhost/ttmqms`** (หรือ `http://localhost/ttmqms/public`)
+- หน้าเว็บจะแสดงระบบคิวนวดแผนไทย TTMQMS Enterprise พร้อมเข้าสู่ระบบด้วยเลขบัตรประชาชนและทดสอบออกคิวได้ทันที!
+
+---
+*คู่มือฉบับนี้จัดทำขึ้นเพื่อผู้ดูแลระบบและวิศวกรเครือข่ายของโรงพยาบาลโดยเฉพาะ*