# 📝 **Documents Management System Version 1.4.5: Application Requirements Specification**

**สถานะ:** FINAL-Rev.05
**วันที่:** 2025-11-29
**อ้างอิงพื้นฐาน:** v1.4.4
**Classification:** Internal Technical Documentation

## 📌 **1. วัตถุประสงค์**

สร้างเว็บแอปพลิเคชันสำหรับระบบบริหารจัดการเอกสารโครงการ (Document Management System - DMS) แบบครบวงจร ที่เน้นความปลอดภัยสูงสุด ความถูกต้องของข้อมูล (Data Integrity) และรองรับการขยายตัวในอนาคต (Scalability) โดยแก้ไขปัญหา Race Condition และเพิ่มความเสถียรในการจัดการไฟล์ และใช้ Unified Workflow Engine ในการจัดการกระบวนการอนุมัติทั้งหมดเพื่อความยืดหยุ่น

- มีฟังก์ชันหลักในการอัปโหลด จัดเก็บ ค้นหา แชร์ และควบคุมสิทธิ์การเข้าถึงเอกสาร
- ช่วยลดการใช้เอกสารกระดาษ เพิ่มความปลอดภัยในการจัดเก็บข้อมูล
- เพิ่มความสะดวกในการทำงานร่วมกันระหว่างองกรณ์
- **เสริม:** ปรับปรุงความปลอดภัยของระบบด้วยมาตรการป้องกันที่ทันสมัย
- **เสริม:** เพิ่มความทนทานของระบบด้วยกลไก resilience patterns
- **เสริม:** สร้างระบบ monitoring และ observability ที่ครอบคลุม

## 🛠️ **2. สถาปัตยกรรมและเทคโนโลยี (System Architecture & Technology Stack)**

ใช้สถาปัตยกรรมแบบ Headless/API-First ที่ทันสมัย ทำงานทั้งหมดบน QNAP Server ผ่าน Container Station เพื่อความสะดวกในการจัดการและบำรุงรักษา

**Domain:** `np-dms.work`, `www.np-dms.work`
**IP:** 159.192.126.103
**Docker Network:** ทุก Service จะเชื่อมต่อผ่านเครือข่ายกลางชื่อ `lcbp3` เพื่อให้สามารถสื่อสารกันได้

### **2.1 Infrastructure & Environment:**

- **Server:** QNAP (Model: TS-473A, RAM: 32GB, CPU: AMD Ryzen V1500B)
- **Containerization:** Container Station (Docker & Docker Compose) ใช้ UI ของ Container Station เป็นหลัก ในการ configuration และการรัน docker command
- **Development Environment:** VS Code/Cursor on Windows 11
- **Data Storage:** `/share/dms-data` บน QNAP
- **ข้อจำกัด:** ไม่สามารถใช้ .env ในการกำหนดตัวแปรภายนอกได้ ต้องกำหนดใน docker-compose.yml เท่านั้น

### **2.2 การจัดการ Configuration (ปรับปรุง):**

- ใช้ `docker-compose.yml` สำหรับ environment variables ตามข้อจำกัดของ QNAP
- **Secrets Management (ใหม่):**
  - ห้ามระบุ Sensitive Secrets (Password, Keys) ใน `docker-compose.yml` หลัก
  - ต้องใช้ไฟล์ `docker-compose.override.yml` (ที่ถูก gitignore) สำหรับ Inject Environment Variables ที่เป็นความลับในแต่ละ Environment (Dev/Prod)
  - ไฟล์ `docker-compose.yml` หลักให้ใส่ค่า Dummy หรือว่างไว้
- **แต่ต้องมี mechanism สำหรับจัดการ sensitive secrets อย่างปลอดภัย** โดยใช้:
  - Docker secrets (ถ้ารองรับ)
  - External secret management (Hashicorp Vault) หรือ
  - Encrypted environment variables
- Development environment ยังใช้ .env ได้ แต่ต้องไม่ commit เข้า version control
- ต้องมี configuration validation during application startup
- ต้องแยก configuration ตาม environment (development, staging, production)

### **2.3 Core Services:**

- **Code Hosting:** Gitea (Self-hosted on QNAP)

  - Application name: git
  - Service name: gitea
  - Domain: `git.np-dms.work`
  - หน้าที่: เป็นศูนย์กลางในการเก็บและจัดการเวอร์ชันของโค้ด (Source Code) สำหรับทุกส่วน

- **Backend / Data Platform:** NestJS

  - Application name: lcbp3-backend
  - Service name: backend
  - Domain: `backend.np-dms.work`
  - Framework: NestJS (Node.js, TypeScript, ESM)
  - หน้าที่: จัดการโครงสร้างข้อมูล (Data Models), สร้าง API, จัดการสิทธิ์ผู้ใช้ (Roles & Permissions), และสร้าง Workflow ทั้งหมดของระบบ

- **Database:** MariaDB 10.11

  - Application name: lcbp3-db
  - Service name: mariadb
  - Domain: `db.np-dms.work`
  - หน้าที่: ฐานข้อมูลหลักสำหรับเก็บข้อมูลทั้งหมด
  - Tooling: DBeaver (Community Edition), phpmyadmin สำหรับการออกแบบและจัดการฐานข้อมูล

- **Database Management:** phpMyAdmin

  - Application name: lcbp3-db
  - Service: phpmyadmin:5-apache
  - Service name: pma
  - Domain: `pma.np-dms.work`
  - หน้าที่: จัดการฐานข้อมูล mariadb ผ่าน Web UI

- **Frontend:** Next.js

  - Application name: lcbp3-frontend
  - Service name: frontend
  - Domain: `lcbp3.np-dms.work`
  - Framework: Next.js (App Router, React, TypeScript, ESM)
  - Styling: Tailwind CSS + PostCSS
  - Component Library: shadcn/ui
  - หน้าที่: สร้างหน้าตาเว็บแอปพลิเคชันสำหรับให้ผู้ใช้งานเข้ามาดู Dashboard, จัดการเอกสาร, และติดตามงาน โดยจะสื่อสารกับ Backend ผ่าน API

- **Workflow Automation:** n8n

  - Application name: lcbp3-n8n
  - Service: n8nio/n8n:latest
  - Service name: n8n
  - Domain: `n8n.np-dms.work`
  - หน้าที่: จัดการ workflow ระหว่าง Backend และ Line

- **Reverse Proxy:** Nginx Proxy Manager

  - Application name: lcbp3-npm
  - Service: Nginx Proxy Manager (nginx-proxy-manage: latest)
  - Service name: npm
  - Domain: `npm.np-dms.work`
  - หน้าที่: เป็นด่านหน้าในการรับ-ส่งข้อมูล จัดการโดเมนทั้งหมด, ทำหน้าที่เป็น Proxy ชี้ไปยัง Service ที่ถูกต้อง, และจัดการ SSL Certificate (HTTPS) ให้อัตโนมัติ

- **Search Engine:** Elasticsearch
- **Cache:** Redis

### **2.4 Business Logic & Consistency (ปรับปรุง):**

- **2.4.1 Unified Workflow Engine (หลัก):**

  - ระบบการเดินเอกสารทั้งหมด (Correspondence, RFA, Circulation) ต้อง ใช้ Engine กลางเดียวกัน โดยกำหนด Logic ผ่าน Workflow DSL (JSON Configuration) แทนการเขียน Hard-coded ลงในตาราง
  - Workflow Versioning (เพิ่ม): ระบบต้องรองรับการกำหนด Version ของ Workflow Definition โดยเอกสารที่เริ่มกระบวนการไปแล้ว (In-progress instances) จะต้องใช้ Workflow Version เดิม จนกว่าจะสิ้นสุดกระบวนการ หรือได้รับคำสั่ง Migrate จาก Admin เพื่อป้องกันความขัดแย้งของ State

- **2.4.2 Separation of Concerns:**

  - Module ต่างๆ (Correspondence, RFA, Circulation) จะเก็บเฉพาะข้อมูลของเอกสาร (Data) ส่วนสถานะและการเปลี่ยนสถานะ (State Transition) จะถูกจัดการโดย Workflow Engine

- **2.4.3 Idempotency & Locking:**

  - ใช้กลไกเดิมในการป้องกันการทำรายการซ้ำ

- **2.4.4 Optimistic Locking (ใหม่):**

  - ใช้ Version Column ใน Database ควบคู่กับ Redis Lock สำหรับการสร้างเลขที่เอกสาร เพื่อเป็น Safety Net ชั้นสุดท้าย

- **2.4.5** **จะไม่มีการใช้ SQL Triggers**
  - เพื่อป้องกันตรรกะซ่อนเร้น (Hidden Logic) และความซับซ้อนในการดีบัก

### **2.5 Data Migration และ Schema Versioning:**

- ต้องมี database migration scripts สำหรับทุก schema change โดยใช้ TypeORM migrations
- ต้องรองรับ rollback ของ migration ได้
- ต้องมี data seeding strategy สำหรับ environment ต่างๆ (development, staging, production)
- ต้องมี version compatibility between schema versions
- Migration scripts ต้องผ่านการทดสอบใน staging environment ก่อน production
- ต้องมี database backup ก่อนทำ migration ใน production

### **2.6 กลยุทธ์ความทนทานและการจัดการข้อผิดพลาด (Resilience & Error Handling Strategy)**

- 2.6.1 Circuit Breaker Pattern: ใช้สำหรับ external service calls (Email, LINE, Elasticsearch)
- 2.6.2 Retry Mechanism: ด้วย exponential backoff สำหรับ transient failures
- 2.6.3 Fallback Strategies: Graceful degradation เมื่อบริการภายนอกล้มเหลว
- 2.6.4 Error Handling: Error messages ต้องไม่เปิดเผยข้อมูล sensitive
- 2.6.5 Monitoring: Centralized error monitoring และ alerting system

## **📦 3. ข้อกำหนดด้านฟังก์ชันการทำงาน (Functional Requirements)**

### **3.1. การจัดการโครงสร้างโครงการและองค์กร**

- 3.1.1. โครงการ (Projects): ระบบต้องสามารถจัดการเอกสารภายในหลายโครงการได้ (ปัจจุบันมี 4 โครงการ และจะเพิ่มขึ้นในอนาคต)
- 3.1.2. สัญญา (Contracts): ระบบต้องสามารถจัดการเอกสารภายในแต่ละสัญญาได้ ในแต่ละโครงการ มีได้หลายสัญญา หรืออย่างน้อย 1 สัญญา
- 3.1.3. องค์กร (Organizations):
  - มีหลายองค์กรในโครงการ องค์กรณ์ที่เป็น Owner, Designer และ Consultant สามารถอยู่ในหลายโครงการและหลายสัญญาได้
  - Contractor จะถือ 1 สัญญา และอยู่ใน 1 โครงการเท่านั้น

### **3.2. การจัดการเอกสารโต้ตอบ (Correspondence Management)**

- 3.2.1. วัตถุประสงค์:
  - เอกสารโต้ตอบ (correspondences) ระหว่างองค์กรณ์-องค์กรณ์ ภายใน โครงการ (Projects) และระหว่าง องค์กรณ์-องค์กรณ์ ภายนอก โครงการ (Projects), รองรับ To (ผู้รับหลัก) และ CC (ผู้รับสำเนา) หลายองค์กรณ์
- 3.2.2. ประเภทเอกสาร:
  - ระบบต้องรองรับเอกสารรูปแบบ ไฟล์ PDF, ZIP
  - เอกสารโต้ตอบ (Correspondence) สามารถมีได้หลายประเภท (Types) เช่น จดหมาย (Letter), อีเมล์ (Email), Request for Information (RFI), รวมถึง เอกสารขออนุมัติ (RFA) แต่ละ revision และสามารถเพิ่มประเภทใหม่ได้ในภายหลัง
- 3.2.3. การสร้างเอกสาร (Correspondence):
  - ผู้ใช้ที่มีสิทธิ์ (เช่น Document Control) สามารถสร้างเอกสารรอไว้ในสถานะ ฉบับร่าง" (Draft) ได้ ซึ่งผู้ใช้งานต่างองค์กรจะมองไม่เห็น
  - เมื่อกด "Submitted" แล้ว การแก้ไข, ถอนเอกสารกลับไปสถานะ Draft, หรือยกเลิก (Cancel) จะต้องทำโดยผู้ใช้ระดับ Admin ขึ้นไป พร้อมระบุเหตุผล
- 3.2.4. การอ้างอิงและจัดกลุ่ม:
  - เอกสารสามารถอ้างถึง (Reference) เอกสารฉบับก่อนหน้าได้หลายฉบับ
  - สามารถกำหนด Tag ได้หลาย Tag เพื่อจัดกลุ่มและใช้ในการค้นหาขั้นสูง
- 3.2.5. Workflow (Unified Workflow):
  - ระบบต้องรองรับ Workflow ที่เป็นแบบ Unified Workflow

### **3.3. การจัดการเอกสาขออนุมัติ (Request for Approval / RFA)**

- 3.3.1. วัตถุประสงค์:
  - เอกสารขออนุมัติ (RFA) ภายใน โครงการ (Projects)
- 3.3.2. ประเภทเอกสาร:
  - ระบบต้องรองรับเอกสารรูปแบบ ไฟล์ PDF
  - เอกสารขออนุมัติ (RFA) สามารถมีได้หลาย revision
  - มีประถทของเอกสาร ได้หลายประเภท (RFA Types) และสามารถเพิ่มประเภทใหม่ได้ในภายหลัง
- 3.3.3. การสร้างเอกสาร:
  - ผู้ใช้ที่มีสิทธิ์ (เช่น Document Control) สามารถสร้างเอกสารขออนุมัติ (RFA) รอไว้ในสถานะ ฉบับร่าง" (Draft) ได้ ซึ่งผู้ใช้งานต่างองค์กรจะมองไม่เห็น
  - เมื่อกด "Submitted" แล้ว การแก้ไข, ถอนเอกสารกลับไปสถานะ Draft, หรือยกเลิก (Cancel) จะต้องทำโดยผู้ใช้ระดับ Admin ขึ้นไป พร้อมระบุเหตุผล
- 3.3.4. การอ้างอิงและจัดกลุ่ม:
  - RFA สามารถอ้างถึง (Reference) แบบก่อสร้าง (Shop Drawing) ได้หลายฉบับ
- 3.3.5. Workflow (Unified Workflow):
  - ระบบต้องรองรับ Workflow ที่เป็นแบบ Unified Workflow ซึ่งจะมีสถานะและกิจกรรมที่ไม่เหมือนกันกับเอกสารโต้ตอบ (Correspondence)

### **3.4. การจัดการแบบคู่สัญญา (Contract Drawing)**

- 3.4.1. วัตถุประสงค์: แบบคู่สัญญา (Contract Drawing) ใช้เพื่ออ้างอิงและใช้ในการตรวจสอบ
- 3.4.2. ประเภทเอกสาร: ไฟล์ PDF
- 3.4.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
- 3.4.4. การอ้างอิงและจัดกลุ่ม: ใช้สำหรับอ้างอิง ใน Shop Drawings, มีการจัดหมวดหมู่ของ Contract Drawing

### **3.5. การจัดกาแบบก่อสร้าง (Shop Drawing)**

- 3.5.1. วัตถุประสงค์: แบบก่อสร้าง (Shop Drawing) ใช้เในการตรวจสอบ โดยจัดส่งด้วย Request for Approval (RFA)
- 3.5.2. ประเภทเอกสาร: ไฟล์ PDF, DWG, ZIP
- 3.5.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้ โดยผู้ใช้ที่มีสิทธิ์ (เช่น Document Control) สามารถสร้างเอกสารรอไว้ในสถานะ ฉบับร่าง" (Draft) ได้ ซึ่งผู้ใช้งานต่างองค์กรจะมองไม่เห็น
- 3.5.4. การอ้างอิงและจัดกลุ่ม: ใช้สำหรับอ้างอิง ใน RFA, มีการจัดหมวดหมู่ของ Shop Drawings โดยทุก แบบก่อสร้าง (Shop Drawing) แต่ละ revision ต้องมี RFA ได้เพียง 1 ฉบับ

### **3.6. การจัดการ Workflow (Unified Workflow)**

- 3.6.1 Workflow Definition:

  - Admin ต้องสามารถสร้าง/แก้ไข Workflow Rule ได้ผ่านหน้าจอ UI (DSL Editor)
  - รองรับการกำหนด State, Transition, Required Role, Condition (JS Expression)

- 3.6.2 Workflow Execution:

  - ระบบต้องรองรับการสร้าง Instance ของ Workflow ผูกกับเอกสาร (Polymorphic)
  - รองรับการเปลี่ยนสถานะ (Action) เช่น Approve, Reject, Comment, Return
  - Auto-Action: รองรับการเปลี่ยนสถานะอัตโนมัติเมื่อครบเงื่อนไข (เช่น Review ครบทุกคน)

- 3.6.3 Flexibility:

  - รองรับ Parallel Review (ส่งให้หลายคนตรวจพร้อมกัน)
  - รองรับ Conditional Flow (เช่น ถ้ายอดเงิน > X ให้เพิ่มผู้อนุมัติ)

- 3.6.4 Workflow การอนุมัติ:

  - รองรับกระบวนการอนุมัติที่ซับซ้อนและเป็นลำดับ เช่น ส่งจาก Originator -> Organization 1 -> Organization 2 -> Organization 3 แล้วส่งผลกลับตามลำดับเดิม (โดยถ้า องกรณ์ใดใน Workflow ให้ส่งกลับ ก็สามารถส่งผลกลับตามลำดับเดิมโดยไม่ต้องรอให้ถึง องกรณืในลำดับถัดไป)

- 3.6.5 การจัดการ:

  - สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบของ องกรณ์ ที่อยู่ใน Workflow ได้
  - มีระบบแจ้งเตือน ให้ผู้รับผิดชอบของ องกรณ์ ที่อยู่ใน Workflow ทราบ เมื่อมี RFA ใหม่ หรือมีการเปลี่ยนสถานะ
  - สามารถข้ามขั้นตอนได้ในกรณีพิเศษ (โดยผู้มีสิทธิ์)
  - สามารถส่งกลับขั้นตอนก่อนหน้าได้

### **3.7.การจัดการเอกสารนำส่ง (Transmittals)**

- 3.7.1. วัตถุประสงค์: เอกสารนำส่ง ใช้สำหรับ นำส่ง Request for Approval (RFAS) หลายฉบับ ไปยังองค์กรอื่น
- 3.7.2. ประเภทเอกสาร: ไฟล์ PDF
- 3.7.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
- 3.7.4. การอ้างอิงและจัดกลุ่ม: เอกสารนำส่ง เป็นส่วนหนึ่งใน Correspondence

### **3.8.ใบเวียนเอกสาร (Circulation Sheet)**

- 3.8.1. วัตถุประสงค์: การสื่อสาร เอกสาร (Correspondence) ทุกฉบับ จะมีใบเวียนเอกสารเพื่อควบคุมและมอบหมายงานภายในองค์กร (สามารถดูและแก้ไขได้เฉพาะคนในองค์กร)
- 3.8.2. ประเภทเอกสาร: ไฟล์ PDF
- 3.8.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ในองค์กรนั้น สามารถสร้างและแก้ไขได้
- 3.8.4. การอ้างอิงและจัดกลุ่ม: การระบุผู้รับผิดชอบ:
  - ผู้รับผิดชอบหลัก (Main): มีได้หลายคน
  - ผู้ร่วมปฏิบัติงาน (Action): มีได้หลายคน
  - ผู้ที่ต้องรับทราบ (Information): มีได้หลายคน
- 3.8.5. การติดตามงาน:
  - สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบประเภท Main และ Action ได้
  - มีระบบแจ้งเตือนเมื่อมี Circulation ใหม่ และแจ้งเตือนล่วงหน้าก่อนถึงวันแล้วเสร็จ
  - สามารถปิด Circulation ได้เมื่อดำเนินการตอบกลับไปยังองค์กรผู้ส่ง (Originator) แล้ว หรือ รับทราบแล้ว (For Information)

### **3.9. ประวัติการแก้ไข (Revisions):** ระบบจะเก็บประวัติการสร้างและแก้ไข เอกสารทั้งหมด

### **3.10. การจัดเก็บไฟล์ (File Handling - ปรับปรุงใหญ่)**

- **3.10.1 Two-Phase Storage Strategy:**

  1. **Phase 1 (Upload):** ไฟล์ถูกอัปโหลดเข้าโฟลเดอร์ `temp/` และได้รับ `temp_id`
  2. **Phase 2 (Commit):** เมื่อ User กด Submit ฟอร์มสำเร็จ ระบบจะย้ายไฟล์จาก `temp/` ไปยัง `permanent/{YYYY}/{MM}/` และบันทึกลง Database ภายใน Transaction เดียวกัน
  3. **Cleanup:** มี Cron Job ลบไฟล์ใน `temp/` ที่ค้างเกิน 24 ชม. (Orphan Files)

- **3.10.2 Security:**

  - Virus Scan (ClamAV) ก่อนย้ายเข้า Permanent
  - Whitelist File Types: PDF, DWG, DOCX, XLSX, ZIP
  - Max Size: 50MB
  - Access Control: ตรวจสอบสิทธิ์ผ่าน Junction Table ก่อนให้ Download Link

- **3.10.3 ความปลอดภัยของการจัดเก็บไฟล์:**
  - ต้องมีการ scan virus สำหรับไฟล์ที่อัปโหลดทั้งหมด โดยใช้ ClamAV หรือบริการ third-party
  - จำกัดประเภทไฟล์ที่อนุญาต: PDF, DWG, DOCX, XLSX, ZIP (ต้องระบุรายการที่ชัดเจน)
  - ขนาดไฟล์สูงสุด: 50MB ต่อไฟล์
  - ไฟล์ต้องถูกเก็บนอก web root และเข้าถึงได้ผ่าน authenticated endpoint เท่านั้น
  - ต้องมี file integrity check (checksum) เพื่อป้องกันการแก้ไขไฟล์
  - Download links ต้องมี expiration time (default: 24 ชั่วโมง)
  - ต้องบันทึก audit log ทุกครั้งที่มีการดาวน์โหลดไฟล์สำคัญ

### **3.11. การจัดการเลขที่เอกสาร (Document Numbering - ปรับปรุง)**

- 3.11.1. ระบบต้องสามารถสร้างเลขที่เอกสาร (Running Number) ได้โดยอัตโนมัติและยืดหยุ่นสูง
- 3.11.2. Logic การนับเลข (Counter Logic): การนับเลขจะต้องรองรับการแยกตาม Key ที่ซับซ้อนขึ้น:
  - **Project** + **Originator** + **Type** + **Discipline** (ถ้ามี) + **Sub-Type** (ถ้ามี) + **Year**
- 3.11.3. Format Template:
  - รองรับการกำหนดรูปแบบด้วย Token Replacement เช่น:
    - `{ORG}-{TYPE}-{DISCIPLINE}-{SEQ:4}-{REV}` -> `TEAM-RFA-STR-0001-A`
  - รองรับ Token: `{PROJECT}`, `{ORG}`, `{TYPE}`, `{DISCIPLINE}`, `{SUBTYPE}`, `{SUBTYPE_NUM}`, `{YEAR}`, `{YEAR_SHORT}`, `{SEQ:n}`
- 3.11.4. Transmittal Logic: รองรับเงื่อนไขพิเศษสำหรับ Transmittal ที่เลขอาจเปลี่ยนตามผู้รับ (To Owner vs To Contractor)
- 3.11.5. กลไกความปลอดภัย: ยังคงใช้ Redis Distributed Lock และ Optimistic Locking เพื่อป้องกันเลขซ้ำหรือข้าม
- 3.11.6. ต้องมี retry mechanism และ fallback strategy เมื่อการ generate เลขที่เอกสารล้มเหลว
- 3.11.7 Fallback Logic (เพิ่ม):
  - กรณีที่เอกสารประเภทนั้นไม่มี discipline_id หรือ sub_type_id (เป็นค่า NULL หรือไม่ระบุ) ให้ระบบใช้ค่า Default (เช่น 0) ในการจัดกลุ่ม Counter เพื่อป้องกัน Error และรับประกันความถูกต้องของ Running Number (Uniqueness Guarantee)
  - Scenario 1: Redis Unavailable
    - Fallback เป็น database-only locking (pessimistic lock)
    - Log warning และแจ้ง ops team
    - ระบบยังใช้งานได้แต่ performance ลดลง
  - Scenario 2: Lock Acquisition Timeout
    - Retry 5 ครั้งด้วย exponential backoff (1s, 2s, 4s, 8s, 16s)
    - หลัง 5 ครั้ง: Return error 503 "Service Temporarily Unavailable"
    - Frontend แสดง user-friendly message: "ระบบกำลังยุ่ง กรุณาลองใหม่ภายหลัง"
  - Scenario 3: Version Conflict After Lock
    - Retry transaction อีก 2 ครั้ง
    - หากยังล้มเหลว: Log error พร้อม context และ return 409 Conflict
    - Frontend แสดง user-friendly message: "เลขที่เอกสารถูกเปลี่ยน กรุณาลองใหม่"
  - Monitoring:
    - Alert ถ้า lock acquisition failures > 5% ใน 5 นาที
    - Dashboard แสดง lock wait time percentiles

### **3.12. การจัดการ JSON Details (JSON & Performance - ปรับปรุง)**

- **3.12.1 วัตถุประสงค์**

  - จัดเก็บข้อมูลแบบไดนามิกที่เฉพาะเจาะจงกับแต่ละประเภทของเอกสาร
  - รองรับการขยายตัวของระบบโดยไม่ต้องเปลี่ยนแปลง database schema
  - จัดการ metadata และข้อมูลประกอบสำหรับ correspondence, routing, และ workflows

- **3.12.2 โครงสร้าง JSON Schema**
  ระบบต้องมี predefined JSON schemas สำหรับประเภทเอกสารต่างๆ:

  - 3.12.2.1 Correspondence Types
    - GENERIC: ข้อมูลพื้นฐานสำหรับเอกสารทั่วไป
    - RFI: รายละเอียดคำถามและข้อมูลทางเทคนิค
    - RFA: ข้อมูลการขออนุมัติแบบและวัสดุ
    - TRANSMITTAL: รายการเอกสารที่ส่งต่อ
    - LETTER: ข้อมูลจดหมายทางการ
    - EMAIL: ข้อมูลอีเมล
  - 3.12.2.2 Rworkflow Types
    - workflow_definitions: กฎและเงื่อนไขการส่งต่อ
    - workflow_histories: สถานะและประวัติการส่งต่อ
    - workflow_instances: การดำเนินการในแต่ละขั้นตอน
  - 3.12.2.3 Audit Types
    - AUDIT_LOG: ข้อมูลการตรวจสอบ
    - SECURITY_SCAN: ผลการตรวจสอบความปลอดภัย

- **3.12.3 Virtual Columns (ปรับปรุง):**

  - สำหรับ Field ใน JSON ที่ต้องใช้ในการค้นหา (Search) หรือจัดเรียง (Sort) บ่อยๆ ต้องสร้าง Generated Column (Virtual Column) ใน Database และทำ Index ไว้ เพื่อประสิทธิภาพสูงสุด
  - Schema Consistency: Field ที่ถูกกำหนดเป็น Virtual Column ห้าม เปลี่ยนแปลง Key Name หรือ Data Type ใน JSON Schema Version ถัดไป หากจำเป็นต้องเปลี่ยน ต้องมีแผนการ Re-index หรือ Migration ข้อมูลเดิมที่ชัดเจน

- **3.12.4 Validation Rules**

  - ต้องมี JSON schema validation สำหรับแต่ละประเภท
  - ต้องรองรับ versioning ของ schema
  - ต้องมี default values สำหรับ field ที่ไม่บังคับ
  - ต้องตรวจสอบ data types และ format ให้ถูกต้อง

- **3.12.5 Performance Requirements**

  - JSON field ต้องมีขนาดไม่เกิน 50KB
  - ต้องรองรับ indexing สำหรับ field ที่ใช้ค้นหาบ่อย
  - ต้องมี compression สำหรับ JSON ขนาดใหญ่

- **3.12.6 Security Requirements**

  - ต้อง sanitize JSON input เพื่อป้องกัน injection attacks
  - ต้อง validate JSON structure ก่อนบันทึก
  - ต้อง encrypt sensitive data ใน JSON fields

- 3.12.7 JSON Schema Migration Strategy (เพิ่มเติม)
  สำหรับ Schema Breaking Changes:

  - Phase 1 - Add New Column
    ALTER TABLE correspondence_revisions
    ADD COLUMN ref_project_id_v2 INT GENERATED ALWAYS AS
    (JSON_UNQUOTE(JSON_EXTRACT(details, '$.newProjectIdPath'))) VIRTUAL;

  - Phase 2 - Backfill Old Records
    - ใช้ background job แปลง JSON format เก่าเป็นใหม่
    - Update `details` JSON ทีละ batch (1000 records)
  - Phase 3 - Switch Application Code
    - Deploy code ที่ใช้ path ใหม่
  - Phase 4 - Remove Old Column

    - หลังจาก verify แล้วว่าไม่มี error
    - Drop old virtual column

  - สำหรับ Non-Breaking Changes
    - เพิ่ม optional field ใน schema
    - Old records ที่ไม่มี field = ใช้ default value

### **3.13. ข้อกำหนดพิเศษ**

- ผู้ใช้งานที่มีสิทธิ์ระดับสูง (Global) หรือผู้ได้รับอนุญาตเป็นกรณีพิเศษ
  - สามารถเลือก สร้างในนามองค์กร (Create on behalf of) ได้ เพื่อให้สามารถออกเลขที่เอกสาร (Running Number) ขององค์กรอื่นได้โดยไม่ต้องล็อกอินใหม่
  - สามารถทำงานแทนผู้ใช้งานอื่นได้ Routing & Workflow ของ Correspondence, RFA, Circulation Sheet

### **3.14. การจัดการข้อมูลหลักขั้นสูง (Admin Panel for Master Data)**

- 3.14.1. Disciplines Management: Admin ต้องสามารถ เพิ่ม/ลบ/แก้ไข สาขางาน (Disciplines) แยกตามสัญญา (Contract) ได้
- 3.14.2. Sub-Type Mapping: Admin ต้องสามารถกำหนด Correspondence Sub-types และ Mapping รหัสตัวเลข (เช่น MAT = 11) ได้
- 3.14.3. Numbering Format Configuration: Admin ต้องมี UI สำหรับตั้งค่า Format Template ของแต่ละ Project/Type ได้โดยไม่ต้องแก้โค้ด

## **🔐 4. ข้อกำหนดด้านสิทธิ์และการเข้าถึง (Access Control Requirements)**

### **4.1. ภาพรวม:**

- ผู้ใช้และองค์กรสามารถดูและแก้ไขเอกสารได้ตามสิทธิ์ที่ได้รับ โดยระบบสิทธิ์จะเป็นแบบ Role-Based Access Control (RBAC)

### **4.2. ลำดับชั้นของสิทธิ์ (Permission Hierarchy):**

- Global: สิทธิ์สูงสุดของระบบ
- Organization: สิทธิ์ภายในองค์กร เป็นสิทธิ์พื้นฐานของผู้ใช้
- Project: สิทธิ์เฉพาะในโครงการ จะถูกพิจารณาเมื่อผู้ใช้อยู่ในโครงการนั้น
- Contract: สิทธิ์เฉพาะในสัญญา จะถูกพิจารณาเมื่อผู้ใช้อยู่ในสัญญานั้น (สัญญาเป็นส่วนหนึ่งของโครงการ)

### **4.3. กฎการบังคับใช้:**

- เมื่อตรวจสอบสิทธิ์ ระบบจะพิจารณาสิทธิ์จากทุกระดับที่ผู้ใช้มี และใช้ สิทธิ์ที่มากที่สุด (Most Permissive) เป็นตัวตัดสิน
- ตัวอย่าง: ผู้ใช้ A เป็น Viewer ในองค์กร แต่ถูกมอบหมายเป็น Editor ในโครงการ X เมื่ออยู่ในโครงการ X ผู้ใช้ A จะมีสิทธิ์แก้ไขได้

### **4.4. การกำหนดบทบาท (Roles) และขอบเขต (Scope):**

| บทบาท (Role)         | ขอบเขต (Scope) | คำอธิบาย                | สิทธิ์หลัก (Key Permissions)                                                           |
| :------------------- | :------------- | :---------------------- | :------------------------------------------------------------------------------------- |
| **Superadmin**       | Global         | ผู้ดูแลระบบสูงสุด       | ทำทุกอย่างในระบบ, จัดการองค์กร, จัดการข้อมูลหลักระดับ Global                           |
| **Org Admin**        | Organization   | ผู้ดูแลองค์กร           | จัดการผู้ใช้ในองค์กร, จัดการบทบาท/สิทธิ์ภายในองค์กร, ดูรายงานขององค์กร                 |
| **Document Control** | Organization   | ควบคุมเอกสารขององค์กร   | เพิ่ม/แก้ไข/ลบเอกสาร, กำหนดสิทธิ์เอกสารภายในองค์กร                                     |
| **Editor**           | Organization   | ผู้แก้ไขเอกสารขององค์กร | เพิ่ม/แก้ไขเอกสารที่ได้รับมอบหมาย                                                      |
| **Viewer**           | Organization   | ผู้ดูเอกสารขององค์กร    | ดูเอกสารที่มีสิทธิ์เข้าถึง                                                             |
| **Project Manager**  | Project        | ผู้จัดการโครงการ        | จัดการสมาชิกในโครงการ (เพิ่ม/ลบ/มอบบทบาท), สร้าง/จัดการสัญญาในโครงการ, ดูรายงานโครงการ |
| **Contract Admin**   | Contract       | ผู้ดูแลสัญญา            | จัดการสมาชิกในสัญญา, สร้าง/จัดการข้อมูลหลักเฉพาะสัญญา (ถ้ามี), อนุมัติเอกสารในสัญญา    |

### **4.5 . Token Management (ปรับปรุง)**

- **Payload Optimization:** ใน JWT Access Token ให้เก็บเฉพาะ `userId` และ `scope` ปัจจุบันเท่านั้น
- **Permission Caching:** สิทธิ์ละเอียด (Permissions List) ให้เก็บใน **Redis** และดึงมาตรวจสอบเมื่อ Request เข้ามา เพื่อลดขนาด Token และเพิ่มความเร็ว

### **4.6. กระบวนการเริ่มต้นใช้งาน (Onboarding Workflow) ที่สมบูรณ์**

- 4.6.1. สร้างองค์กร (Organization)
  - **Superadmin** สร้างองค์กรใหม่ (เช่น บริษัท A)
  - **Superadmin** แต่งตั้งผู้ใช้อย่างน้อย 1 คนให้เป็น **Org Admin** หรือ **Document Control** ของบริษัท A
- 4.6.2. เพิ่มผู้ใช้ในองค์กร
  - **Org Admin** ของบริษัท A เพิ่มผู้ใช้อื่นๆ (Editor, Viewer) เข้ามาในองค์กรของตน
- 4.6.3. มอบหมายผู้ใช้ให้กับโครงการ (Project)
  - **Project Manager** ของโครงการ X (ซึ่งอาจมาจากบริษัท A หรือบริษัทอื่น) ทำการ "เชิญ" หรือ "มอบหมาย" ผู้ใช้จากองค์กรต่างๆ ที่เกี่ยวข้องเข้ามาในโครงการ X
  - ในขั้นตอนนี้ **Project Manager** จะกำหนด **บทบาทระดับโครงการ** (เช่น Project Member, หรืออาจไม่มีบทบาทพิเศษ ให้ใช้สิทธิ์จากระดับองค์กรไปก่อน)
- 4.6.4. เมอบหมายผู้ใช้ให้กับสัญญา (Contract)
  - **Contract Admin** ของสัญญา Y (ซึ่งเป็นส่วนหนึ่งของโครงการ X) ทำการเลือกผู้ใช้ที่อยู่ในโครงการ X แล้ว มอบหมายให้เข้ามาในสัญญา Y
  - ในขั้นตอนนี้ **Contract Admin** จะกำหนด **บทบาทระดับสัญญา** (เช่น Contract Member) และสิทธิ์เฉพาะที่จำเป็น
- 4.6.5 Security Onboarding:
  - ต้องบังคับเปลี่ยน password ครั้งแรกสำหรับผู้ใช้ใหม่
  - ต้องมี security awareness training สำหรับผู้ใช้ที่มีสิทธิ์สูง
  - ต้องมี process สำหรับการรีเซ็ต password ที่ปลอดภัย
  - ต้องบันทึก audit log ทุกครั้งที่มีการเปลี่ยนแปลง permissions

### **4.7. การจัดการข้อมูลหลัก (Master Data Management) ที่แบ่งตามระดับ**

| ข้อมูลหลัก                          | ผู้มีสิทธิ์จัดการ               | ระดับ                              |
| :---------------------------------- | :------------------------------ | :--------------------------------- |
| ประเภทเอกสาร (Correspondence, RFA)  | **Superadmin**                  | Global                             |
| สถานะเอกสาร (Draft, Approved, etc.) | **Superadmin**                  | Global                             |
| หมวดหมู่แบบ (Shop Drawing)          | **Project Manager**             | Project (สร้างใหม่ได้ภายในโครงการ) |
| Tags                                | **Org Admin / Project Manager** | Organization / Project             |
| บทบาทและสิทธิ์ (Custom Roles)       | **Superadmin / Org Admin**      | Global / Organization              |
| Document Numbering Formats          | **Superadmin / Admin**          | Global / Organization              |

## **👥 5. ข้อกำหนดด้านผู้ใช้งาน (User Interface & Experience)**

### 5.1. Layout หลัก

- หน้าเว็บใช้รูปแบบ App Shell ที่ประกอบด้วย
  - Navbar (ส่วนบน): แสดงชื่อระบบ, เมนูผู้ใช้ (Profile), เมนูสำหรับ Document Control/เมนูสำหรับ Admin/Superadmin (จัดการผู้ใช้, จัดการสิทธิ์, และอื่นๆ), และปุ่ม Login/Logout
  - Sidebar (ด้านข้าง): เป็นเมนูหลักสำหรับเข้าถึงส่วนที่เกี่ยวข้องกับเอกสารทั้งหมด เช่น Dashboard, Correspondences, RFA, Drawings
  - Main Content Area: พื้นที่สำหรับแสดงเนื้อหาหลักของหน้าที่เลือก

### 5.2. หน้า Landing Page

- เป็นหน้าแรกที่แสดงข้อมูลบางส่วนของโครงการสำหรับผู้ใช้ที่ยังไม่ได้ล็อกอิน

### 5.3. หน้า Dashboard

- เป็นหน้าแรกหลังจากล็อกอิน ประกอบด้วย
  - การ์ดสรุปภาพรวม (KPI Cards): แสดงข้อมูลสรุปที่สำคัญขององค์กร เช่น จำนวนเอกสาร, งานที่เกินกำหนด
  - ตาราง "งานของฉัน" (My Tasks Table): แสดงรายการงานทั้งหมดจาก Circulation ที่ผู้ใช้ต้องดำเนินการ
  - Security Metrics: แสดงจำนวน files scanned, security incidents, failed login attempts

### 5.4. การติดตามสถานะ

- องค์กรสามารถติดตามสถานะเอกสารทั้งของตนเอง (Originator) และสถานะเอกสารที่ส่งมาถึงตนเอง (Recipient)

### 5.5. การจัดการข้อมูลส่วนตัว (Profile Page)

- ผู้ใช้สามารถจัดการข้อมูลส่วนตัวและเปลี่ยนรหัสผ่านของตนเองได้

### 5.6. การจัดการเอกสารทางเทคนิค (RFA)

- ผู้ใช้สามารถดู RFA ในรูปแบบ Workflow Diagram ทั้งหมดได้ในหน้าเดียว
- Interactive History (เพิ่ม): ในแผนภาพ Workflow ผู้ใช้ต้องสามารถ คลิกที่ Node หรือ Step เก่าที่ผ่านมาแล้ว เพื่อดู Audit Log ย่อยของ Step นั้นได้ทันที (เช่น ใครเป็นคนกด Approve, เวลาไหน, มี Comment อะไร) โดยไม่ต้องสลับไปดูใน Tab History แยกต่างหาก
- ขั้นตอนที่ยังไม่ถึงหรือผ่านไปแล้วจะเป็นรูปแบบ disabled
- สามารถดำเนินการได้เฉพาะในขั้นตอนที่ได้รับมอบหมายงาน (active)
- สิทธิ์ Document Control ขึ้นไป สามารถกด "Force Proceed" ไปยังขั้นตอนต่อไปได้ทุกขั้นตอน หรือ "Revert" กลับขั้นตอนก่อนหน้าได้

### 5.7. การจัดการใบเวียนเอกสาร (Circulation)

- ผู้ใช้สามารถดู Circulation ในรูปแบบ Workflow ทั้งหมดได้ในหน้าเดียว,ขั้นตอนที่ยังไม่ถึงหรือผ่านไปแล้วจะเป็นรูปแบบ diable, สามารถดำเนินการได้เฉพาะในขั้นตอนที่ได้รับมอบหมายงาน (active) เช่น ตรวจสอบแล้ว เพื่อไปยังขั้นตอนต่อไป, สิทธิ์ Document Control ขึ้นไป สามรถกด ไปยังขั้นตอนต่อไป ได้ทุกขั้นตอน, การย้อนกลับ ไปขั้นตอนก่อนหน้า สามารถทำได้โดย สิทธิ์ Document Control ขึ้นไป

### 5.8. การจัดการเอกสารนำส่ง (Transmittals)

- ผู้ใช้สามารถดู Transmittals ในรูปแบบรายการทั้งหมดได้ในหน้าเดียว

### 5.9. ข้อกำหนด UI/UX การแนบไฟล์ (File Attachment UX)

- ระบบต้องรองรับการอัปโหลดไฟล์หลายไฟล์พร้อมกัน (Multi-file upload) เช่น การลากและวาง (Drag-and-Drop)
- ในหน้าอัปโหลด (เช่น สร้าง RFA หรือ Correspondence) ผู้ใช้ต้องสามารถกำหนดได้ว่าไฟล์ใดเป็น "เอกสารหลัก" (Main Document เช่น PDF) และไฟล์ใดเป็น "เอกสารแนบประกอบ" (Supporting Attachments เช่น .dwg, .docx, .zip)
- **Security Feedback:** แสดง security warnings สำหรับ file types ที่เสี่ยงหรือ files ที่ fail virus scan
- **File Type Indicators:** แสดง file type icons และ security status

### 5.10 Form & Interaction

- **Dynamic Form Generator:** ใช้ Component กลางที่รับ JSON Schema แล้ว Render Form ออกมาอัตโนมัติ เพื่อลดความซ้ำซ้อนของโค้ดหน้าบ้าน และรองรับเอกสารประเภทใหม่ๆ ได้ทันที
- **Optimistic Updates:** การเปลี่ยนสถานะ (เช่น กด Approve, กด Read) ให้ UI เปลี่ยนสถานะทันทีให้ผู้ใช้เห็นก่อนรอ API Response (Rollback ถ้า Failed)

### 5.11 Mobile Responsiveness

- **Table Visualization:** บนหน้าจอมือถือ ตารางข้อมูลที่มีหลาย Column (เช่น Correspondence List) ต้องเปลี่ยนการแสดงผลเป็นแบบ **Card View** อัตโนมัติ
- **Navigation:** Sidebar ต้องเป็นแบบ Collapsible Drawer

### 5.12 Resilience & Offline Support

- **Auto-Save Draft:** ระบบต้องบันทึกข้อมูลฟอร์มที่กำลังกรอกลง **LocalStorage** อัตโนมัติ เพื่อป้องกันข้อมูลหายกรณีเน็ตหลุดหรือปิด Browser โดยไม่ได้ตั้งใจ
- **State Management:** ใช้ State Management ที่เหมาะสมและไม่ซับซ้อนเกินไป โดยเน้นการใช้ React Query สำหรับ Server State และ React Hook Form สำหรับ Form State
- **Graceful Degradation:** หาก Service รอง (เช่น Search, Notification) ล่ม ระบบหลัก (CRUD) ต้องยังทำงานต่อได้

### 5.13. Secure In-App PDF Viewer (ใหม่)

- 5.13.1 Viewer Capabilities: ระบบต้องมี PDF Viewer ภายในแอปพลิเคชันที่สามารถเปิดดูไฟล์เอกสารหลัก (PDF) ได้ทันทีโดยไม่ต้องดาวน์โหลดลงเครื่อง เพื่อความสะดวกในการตรวจทาน (Review/Approve)
- 5.13.2 Security: การแสดงผลไฟล์ต้อง ห้าม (Disable) การทำ Browser Cache สำหรับไฟล์ Sensitive เพื่อป้องกันการกู้คืนไฟล์จากเครื่อง Client ภายหลัง
- 5.13.3 Performance: ต้องรองรับการส่งข้อมูลแบบ Streaming (Range Requests) เพื่อให้เปิดดูไฟล์ขนาดใหญ่ (เช่น แบบแปลน 50MB+) ได้รวดเร็วโดยไม่ต้องรอโหลดเสร็จทั้งไฟล์

## **🛡️ 6. ข้อกำหนดที่ไม่ใช่ฟังก์ชันการทำงาน (Non-Functional Requirements)**

### 6.1. การบันทึกการกระทำ (Audit Log)

- ทุกการกระทำที่สำคัญของผู้ใช้ (สร้าง, แก้ไข, ลบ, ส่ง) จะถูกบันทึกไว้ใน audit_logs เพื่อการตรวจสอบย้อนหลัง

  - 6.1.1 ขอบเขตการบันทึก Audit Log:

    - ทุกการสร้าง/แก้ไข/ลบ ข้อมูลสำคัญ (correspondences, RFAs, drawings, users, permissions)
    - ทุกการเข้าถึงข้อมูล sensitive (user data, financial information)
    - ทุกการเปลี่ยนสถานะ workflow (status transitions)
    - ทุกการดาวน์โหลดไฟล์สำคัญ (contract documents, financial reports)
    - ทุกการเปลี่ยนแปลง permission และ role assignment
    - ทุกการล็อกอินที่สำเร็จและล้มเหลว
    - ทุกการส่งคำขอ API ที่สำคัญ

  - 6.1.2 ข้อมูลที่ต้องบันทึกใน Audit Log:
    - ผู้ใช้งาน (user_id)
    - การกระทำ (action)
    - ชนิดของ entity (entity_type)
    - ID ของ entity (entity_id)
    - ข้อมูลก่อนการเปลี่ยนแปลง (old_values) - สำหรับ update operations
    - ข้อมูลหลังการเปลี่ยนแปลง (new_values) - สำหรับ update operations
    - IP address
    - User agent
    - Timestamp
    - Request ID สำหรับ tracing

### **6.2. Data Archiving & Partitioning (ใหม่)**

- สำหรับตารางที่มีขนาดใหญ่และโตเร็ว (เช่น `audit_logs`, `notifications`, `correspondence_revisions`) ต้องออกแบบโดยรองรับ **Table Partitioning** (แบ่งตาม Range วันที่ หรือ List) เพื่อประสิทธิภาพในระยะยาว

### **6.3. การค้นหา (Search):**

- ระบบต้องมีฟังก์ชันการค้นหาขั้นสูง ที่สามารถค้นหาเอกสาร **correspondence**, **rfa**, **shop_drawing**, **contract-drawing**, **transmittal** และ **ใบเวียน (Circulations)** จากหลายเงื่อนไขพร้อมกันได้ เช่น ค้นหาจากชื่อเรื่อง, ประเภท, วันที่, และ Tag

### **6.4. การทำรายงาน (Reporting):**

- สามารถจัดทำรายงานสรุปแยกประเภทของ Correspondence ประจำวัน, สัปดาห์, เดือน, และปีได้

### **6.5. ประสิทธิภาพ (Performance):**

- มีการใช้ Caching กับข้อมูลที่เรียกใช้บ่อย และใช้ Pagination ในตารางข้อมูลเพื่อจัดการข้อมูลจำนวนมาก
  - 6.5.1 ตัวชี้วัดประสิทธิภาพ:
    - **API Response Time:** < 200ms (90th percentile) สำหรับ operation ทั่วไป
    - **Search Query Performance:** < 500ms สำหรับการค้นหาขั้นสูง
    - **File Upload Performance:** < 30 seconds สำหรับไฟล์ขนาด 50MB
    - **Concurrent Users:** รองรับผู้ใช้พร้อมกันอย่างน้อย 100 คน
    - **Database Connection Pool:** ขนาดเหมาะสมกับ workload (default: min 5, max 20 connections)
    - **Cache Hit Ratio:** > 80% สำหรับ cached data
    - **Application Startup Time:** < 30 seconds
  - 6.5.2 Caching Strategy:
    - **Master Data Cache:** Roles, Permissions, Organizations, Project metadata (TTL: 1 hour)
    - **User Session Cache:** User permissions และ profile data (TTL: 30 minutes)
    - **Search Result Cache:** Frequently searched queries (TTL: 15 minutes)
    - **File Metadata Cache:** Attachment metadata (TTL: 1 hour)
    - **Document Cache:** Frequently accessed document metadata (TTL: 30 minutes)
    - **ต้องมี cache invalidation strategy ที่ชัดเจน:**
      - Invalidate on update/delete operations
      - Time-based expiration
      - Manual cache clearance สำหรับ admin operations
    - ใช้ Redis เป็น distributed cache backend
    - ต้องมี cache monitoring (hit/miss ratios)
  - 6.5.3 Frontend Performance:
    - **Bundle Size Optimization:** ต้องควบคุมขนาด Bundle โดยรวมไม่เกิน 2MB
    - **State Management Efficiency:** ใช้ State Management Libraries อย่างเหมาะสม ไม่เกิน 2 ตัวหลัก
    - **Memory Management:** ต้องป้องกัน Memory Leak จาก State ที่ไม่จำเป็น

### **6.6. ความปลอดภัย (Security):**

- มีระบบ Rate Limiting เพื่อป้องกันการโจมตีแบบ Brute-force
- การจัดการ Secret (เช่น รหัสผ่าน DB, JWT Secret) จะต้องทำผ่าน Environment Variable ของ Docker เพื่อความปลอดภัยสูงสุด
  - 6.6.1 Rate Limiting Strategy:
    - **Anonymous Endpoints:** 100 requests/hour ต่อ IP address
    - **Authenticated Endpoints:**
      - Viewer: 500 requests/hour
      - Editor: 1000 requests/hour
      - Document Control: 2000 requests/hour
      - Admin/Superadmin: 5000 requests/hour
    - **File Upload Endpoints:** 50 requests/hour ต่อ user
    - **Search Endpoints:** 500 requests/hour ต่อ user
    - **Authentication Endpoints:** 10 requests/minute ต่อ IP address
    - **ต้องมี mechanism สำหรับยกเว้น rate limiting สำหรับ trusted services**
    - ต้องบันทึก log เมื่อมีการ trigger rate limiting
  - 6.6.2 Error Handling และ Resilience:
    - ต้องมี circuit breaker pattern สำหรับ external service calls
    - ต้องมี retry mechanism ด้วย exponential backoff
    - ต้องมี graceful degradation เมื่อบริการภายนอกล้มเหลว
    - Error messages ต้องไม่เปิดเผยข้อมูล sensitive
  - 6.6.3 Input Validation:
    - ต้องมี input validation ทั้งฝั่ง client และ server (defense in depth)
    - ต้องป้องกัน OWASP Top 10 vulnerabilities:
      - SQL Injection (ใช้ parameterized queries ผ่าน ORM)
      - XSS (input sanitization และ output encoding)
      - CSRF (CSRF tokens สำหรับ state-changing operations)
    - ต้อง validate file uploads:
      - File type (white-list approach)
      - File size
      - File content (magic number verification)
    - ต้อง sanitize user inputs ก่อนแสดงผลใน UI
    - ต้องใช้ content security policy (CSP) headers
    - ต้องมี request size limits เพื่อป้องกัน DoS attacks
  - 6.6.4 Session และ Token Management:
    - **JWT token expiration:** 8 hours สำหรับ access token
    - **Refresh token expiration:** 7 days
    - **Refresh token mechanism:** ต้องรองรับ token rotation และ revocation
    - **Token revocation on logout:** ต้องบันทึก revoked tokens จนกว่าจะ expire
    - **Concurrent session management:**
      - จำกัดจำนวน session พร้อมกันได้ (default: 5 devices)
      - ต้องแจ้งเตือนเมื่อมี login จาก device/location ใหม่
    - **Device fingerprinting:** สำหรับ security และ audit purposes
    - **Password policy:**
      - ความยาวขั้นต่ำ: 8 characters
      - ต้องมี uppercase, lowercase, number, special character
      - ต้องเปลี่ยน password ทุก 90 วัน
      - ต้องป้องกันการใช้ password ที่เคยใช้มาแล้ว 5 ครั้งล่าสุด

### 6.7. การสำรองข้อมูลและการกู้คืน (Backup & Recovery)

- ระบบจะต้องมีกลไกการสำรองข้อมูลอัตโนมัติสำหรับฐานข้อมูล MariaDB [cite: 2.4] และไฟล์เอกสารทั้งหมดใน /share/dms-data [cite: 2.1] (เช่น ใช้ HBS 3 ของ QNAP หรือสคริปต์สำรองข้อมูล) อย่างน้อยวันละ 1 ครั้ง
- ต้องมีแผนการกู้คืนระบบ (Disaster Recovery Plan) ในกรณีที่ Server หลัก (QNAP) ใช้งานไม่ได้
- 6.7.1 ขั้นตอนการกู้คืน:
  - **Database Restoration Procedure:**
    - สร้างจาก full backup ล่าสุด
    - Apply transaction logs ถึง point-in-time ที่ต้องการ
    - Verify data integrity post-restoration
  - **File Storage Restoration Procedure:**
    - Restore จาก QNAP snapshot หรือ backup
    - Verify file integrity และ permissions
  - **Application Redeployment Procedure:**
    - Deploy จาก version ล่าสุดที่รู้ว่าทำงานได้
    - Verify application health
  - **Data Integrity Verification Post-Recovery:**
    - Run data consistency checks
    - Verify critical business data
  - **Recovery Time Objective (RTO):** < 4 ชั่วโมง
  - **Recovery Point Objective (RPO):** < 1 ชั่วโมง

### 6.8. กลยุทธ์การแจ้งเตือน (Notification Strategy - ปรับปรุง)

- 6.8.1 ระบบจะส่งการแจ้งเตือน (ผ่าน Email หรือ Line [cite: 2.7]) เมื่อมีการกระทำที่สำคัญ\*\* ดังนี้:
  1. เมื่อมีเอกสารใหม่ (Correspondence, RFA) ถูกส่งมาถึงองค์กรณ์ของเรา
  2. เมื่อมีใบเวียน (Circulation) ใหม่ มอบหมายงานมาที่เรา
  3. (ทางเลือก) เมื่อเอกสารที่เราส่งไป ถูกดำเนินการ (เช่น อนุมัติ/ปฏิเสธ)
  4. (ทางเลือก) เมื่อใกล้ถึงวันครบกำหนด (Deadline) [cite: 3.2.5, 3.6.6, 3.7.5]
- 6.8.2 Grouping/Digest (ใหม่)
  - กรณีมีการแจ้งเตือนประเภทเดียวกันจำนวนมากในช่วงเวลาสั้นๆ (เช่น Approve เอกสาร 10 ฉบับรวด) ระบบต้อง **รวม (Batch)** เป็น 1 Email/Line Notification เพื่อไม่ให้รบกวนผู้ใช้ (Spamming)
- 6.8.3 Notification Delivery Guarantees
  - **At-least-once delivery:** สำหรับ important notifications
  - **Retry mechanism:** ด้วย exponential backoff (max 3 reties)
  - **Dead letter queue:** สำหรับ notifications ที่ส่งไม่สำเร็จหลังจาก retries
  - **Delivery status tracking:** ต้องบันทึกสถานะการส่ง notifications
  - **Fallback channels:** ถ้า Email ล้มเหลว ให้ส่งผ่าน SYSTEM notification
  - **Notification preferences:** ผู้ใช้ต้องสามารถกำหนด channel preferences ได้

### **6.9. Maintenance Mode (ใหม่)**

- ระบบต้องมีกลไก **Maintenance Mode** ที่ Admin สามารถเปิดใช้งานได้
  - เมื่อเปิด: ผู้ใช้ทั่วไปจะเห็นหน้า "ปิดปรับปรุง" และไม่สามารถเรียก API ได้ (ยกเว้น Admin)
  - ใช้สำหรับช่วง Deploy Version ใหม่ หรือ Database Migration

### **6.10. Monitoring และ Observability**

- 6.10.1 Application Monitoring
  - **Health checks:** /health endpoint สำหรับ load balancer
  - **Metrics collection:** Response times, error rates, throughput
  - **Distributed tracing:** สำหรับ request tracing across services
  - **Log aggregation:** Structured logging ด้วย JSON format
  - **Alerting:** สำหรับ critical errors และ performance degradation
- 6.10.2 Business Metrics
  - จำนวน documents created ต่อวัน
  - Workflow completion rates
  - User activity metrics
  - System utilization rates
  - Search query performance
- 6.10.3 Security Monitoring
  - Failed login attempts
  - Rate limiting triggers
  - Virus scan results
  - File download activities
  - Permission changes

### **6.11 JSON Processing & Validation**

- 6.11.1 JSON Schema Management
  - ต้องมี centralized JSON schema registry
  - ต้องรองรับ schema versioning และ migration
  - ต้องมี schema validation during runtime
- 6.11.2 Performance Optimization
  - **Caching:** Cache parsed JSON structures
  - **Compression:** ใช้ compression สำหรับ JSON ขนาดใหญ่
  - **Indexing:** Support JSON path indexing สำหรับ query
- 6.11.3 Error Handling
  - ต้องมี graceful degradation เมื่อ JSON validation ล้มเหลว
  - ต้องมี default fallback values
  - ต้องบันทึก error logs สำหรับ validation failures

## **🧪 7. ข้อกำหนดด้านการทดสอบ (Testing Requirements)**

### 7.1 Unit Testing

- ต้องมี unit tests สำหรับ business logic ทั้งหมด
- Code coverage อย่างน้อย 70% สำหรับ backend services
  - Business Logic: 80%+
  - Controllers: 70%+
  - Utilities: 90%+
- ต้องทดสอบ RBAC permission logic ทุกระดับ

### 7.2 Integration Testing

- ทดสอบการทำงานร่วมกันของ modules
- ทดสอบ database migrations และ data integrity
- ทดสอบ API endpoints ด้วย realistic data

### 7.3 End-to-End Testing

- ทดสอบ complete user workflows
- ทดสอบ document lifecycle จาก creation ถึง archival
- ทดสอบ cross-module integrations

### 7.4 Security Testing

- Penetration Testing: ทดสอบ OWASP Top 10 vulnerabilities
- Security Audit: Review code สำหรับ security flaws
- Virus Scanning Test: ทดสอบ file upload security
- Rate Limiting Test: ทดสอบ rate limiting functionality

### 7.5. Performance Testing

- Penetration Testing: ทดสอบ OWASP Top 10 vulnerabilities
- Security Audit: Review code สำหรับ security flaws
- Virus Scanning Test: ทดสอบ file upload security
  - **Rate Limiting Test:** ทดสอบ rate limiting functionality
  - **Load Testing:** ทดสอบด้วย realistic workloads
  - **Stress Testing:** หา breaking points ของระบบ
  - **Endurance Testing:** ทดสอบการทำงานต่อเนื่องเป็นเวลานาน

### 7.6. Disaster Recovery Testing

- ทดสอบ backup และ restoration procedures
- ทดสอบ failover mechanisms
- ทดสอบ data integrity หลังการ recovery

### 7.7 Specific Scenario Testing (เพิ่ม)

- **Race Condition Test:** ทดสอบยิง Request ขอเลขที่เอกสารพร้อมกัน 100 Request
  - **Transaction Test:** ทดสอบปิดเน็ตระหว่าง Upload ไฟล์ (ตรวจสอบว่าไม่มี Orphan File หรือ Broken Link)
  - **Permission Test:** ทดสอบ CASL Integration ทั้งฝั่ง Backend และ Frontend ให้ตรงกัน

## **8. ข้อกำหนดด้านการบำรุงรักษา (Maintenance Requirements)**

### **8.1. Log Retention:**

- Audit logs: 7 ปี
- Application logs: 1 ปี
- Performance metrics: 2 ปี

### **8.2. Monitoring และ Alerting:**

- ต้องมี proactive monitoring สำหรับ critical systems
- ต้องมี alerting สำหรับ security incidents
- ต้องมี performance degradation alerts

### **8.3. Patch Management:**

- ต้องมี process สำหรับ security patches
- ต้องทดสอบ patches ใน staging environment
- ต้องมี rollback plan สำหรับ failed updates

### **8.4. Capacity Planning:**

- ต้อง monitor resource utilization
- ต้องมี scaling strategy สำหรับ growth
- ต้องมี performance baselines และ trending

## **9. ข้อกำหนดด้านการปฏิบัติตามกฎระเบียบ (Compliance Requirements)**

### **9.1. Data Privacy:**

- ต้องปฏิบัติตามกฎหมายคุ้มครองข้อมูลส่วนบุคคล
- ต้องมี data retention policies
- ต้องมี data deletion procedures

### **9.2. Audit Compliance:**

- ต้องรองรับ internal และ external audits
- ต้องมี comprehensive audit trails
- ต้องมี reporting capabilities สำหรับ compliance

### **9.3. Security Standards:**

- ต้องปฏิบัติตาม organizational security policies
- ต้องมี security incident response plan
- ต้องมี regular security assessments

## **Document Control:**

- **Document:** Application Requirements Specification v1.4.5
- **Version:** 1.4
- **Date:** 2025-11-29
- **Author:** NAP LCBP3-DMS & Gemini
- **Status:** FINAL-Rev.05
- **Classification:** Internal Technical Documentation
- **Approved By:** Nattanin

---

`End of Requirements Specification v1.4.5`
