lcbp3/specs/01-requirements/06-non-functional.md

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

---

title: 'Non-Functional Requirements' version: 1.5.0 status: first-draft owner: Nattanin Peancharoen last_updated: 2025-11-30 related:

• specs/02-architecture/data-model.md#correspondence
• specs/03-implementation/backend-guidelines.md#correspondencemodule

---

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

• ทุกการกระทำที่สำคัญของผู้ใช้ (สร้าง, แก้ไข, ลบ, ส่ง) จะถูกบันทึกไว้ใน audit_logs เพื่อการตรวจสอบย้อนหลัง
  • ขอบเขตการบันทึก Audit Log:
    • ทุกการสร้าง/แก้ไข/ลบ ข้อมูลสำคัญ (correspondences, RFAs, drawings, users, permissions)
    • ทุกการเข้าถึงข้อมูล sensitive (user data, financial information)
    • ทุกการเปลี่ยนสถานะ workflow (status transitions)
    • ทุกการดาวน์โหลดไฟล์สำคัญ (contract documents, financial reports)
    • ทุกการเปลี่ยนแปลง permission และ role assignment
    • ทุกการล็อกอินที่สำเร็จและล้มเหลว
    • ทุกการส่งคำขอ API ที่สำคัญ
  • ข้อมูลที่ต้องบันทึกใน 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 ในตารางข้อมูลเพื่อจัดการข้อมูลจำนวนมาก

• ตัวชี้วัดประสิทธิภาพ:

  • 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

• 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)

• 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 เพื่อความปลอดภัยสูงสุด
  • 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
  • Error Handling และ Resilience:
    • ต้องมี circuit breaker pattern สำหรับ external service calls
    • ต้องมี retry mechanism ด้วย exponential backoff
    • ต้องมี graceful degradation เมื่อบริการภายนอกล้มเหลว
    • Error messages ต้องไม่เปิดเผยข้อมูล sensitive
  • 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
  • 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) ใช้งานไม่ได้
• ขั้นตอนการกู้คืน:
  • 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 - ปรับปรุง)

• ระบบจะส่งการแจ้งเตือน (ผ่าน Email หรือ Line [cite: 2.7]) เมื่อมีการกระทำที่สำคัญ** ดังนี้:
  1. เมื่อมีเอกสารใหม่ (Correspondence, RFA) ถูกส่งมาถึงองค์กรณ์ของเรา
  2. เมื่อมีใบเวียน (Circulation) ใหม่ มอบหมายงานมาที่เรา
  3. (ทางเลือก) เมื่อเอกสารที่เราส่งไป ถูกดำเนินการ (เช่น อนุมัติ/ปฏิเสธ)
  4. (ทางเลือก) เมื่อใกล้ถึงวันครบกำหนด (Deadline) [cite: 3.2.5, 3.6.6, 3.7.5]
• Grouping/Digest
  • กรณีมีการแจ้งเตือนประเภทเดียวกันจำนวนมากในช่วงเวลาสั้นๆ (เช่น Approve เอกสาร 10 ฉบับรวด) ระบบต้อง รวม (Batch) เป็น 1 Email/Line Notification เพื่อไม่ให้รบกวนผู้ใช้ (Spamming)
• 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

• 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
• Business Metrics
  • จำนวน documents created ต่อวัน
  • Workflow completion rates
  • User activity metrics
  • System utilization rates
  • Search query performance
• Security Monitoring
  • Failed login attempts
  • Rate limiting triggers
  • Virus scan results
  • File download activities
  • Permission changes

6.11. JSON Processing & Validation

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