np-dms/lcbp3
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Prepare to version 1.5 use spec-kit

Browse Source
This commit is contained in:
admin
2025-11-30 13:58:46 +07:00
parent eff0169c21
commit 241022ada6
169 changed files with 34584 additions and 26464 deletions
Download Patch File Download Diff File Expand all files Collapse all files

768
infrastructure/Markdown/0_Requirements_V1_4_3.md Normal file
View File

@@ -0,0 +1,768 @@
# 📝 **Documents Management System Version 1.4.3: Application Requirements Specification**
**สถานะ:** FINAL-Rev.01
**วันที่:** 2025-11-22
**อ้างอิงพื้นฐาน:** v1.4.3
**Classification:** Internal Technical Documentation
## 📌 **1. วัตถุประสงค์**
สร้างเว็บแอปพลิเคชันสำหรับระบบบริหารจัดการเอกสารโครงการ (Document Management System - DMS) แบบครบวงจร ที่เน้นความปลอดภัยสูงสุด ความถูกต้องของข้อมูล (Data Integrity) และรองรับการขยายตัวในอนาคต (Scalability) โดยแก้ไขปัญหา Race Condition และเพิ่มความเสถียรในการจัดการไฟล์และ Workflow
- มีฟังก์ชันหลักในการอัปโหลด จัดเก็บ ค้นหา แชร์ และควบคุมสิทธิ์การเข้าถึงเอกสาร
- ช่วยลดการใช้เอกสารกระดาษ เพิ่มความปลอดภัยในการจัดเก็บข้อมูล
- เพิ่มความสะดวกในการทำงานร่วมกันระหว่างองกรณ์
- **เสริม:** ปรับปรุงความปลอดภัยของระบบด้วยมาตรการป้องกันที่ทันสมัย
- **เสริม:** เพิ่มความทนทานของระบบด้วยกลไก 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 ตรรกะทางธุรกิจที่ซับซ้อนทั้งหมด** (เช่น การเปลี่ยนสถานะ Workflow [cite: 3.5.3, 3.6.5], การบังคับใช้สิทธิ์ [cite: 4.4], การตรวจสอบ Deadline [cite: 3.2.5]) **จะถูกจัดการในฝั่ง Backend (NestJS)** [cite: 2.3] เพื่อให้สามารถบำรุงรักษาและทดสอบได้ง่าย (Testability)
- **2.4.2 Unified Workflow Engine (ใหม่):** รวม Logic การเดินเอกสารของ `CorrespondenceRouting` และ `RfaWorkflow` ให้ใช้ Core Engine เดียวกันเพื่อลดความซ้ำซ้อนและง่ายต่อการบำรุงรักษา
- **2.4.3 Idempotency Keys (ใหม่):** API ที่สำคัญ (เช่น Submit Document, Approve) ต้องบังคับส่ง Header `Idempotency-Key` เพื่อป้องกันการทำรายการซ้ำจากการกดปุ่มรัวๆ หรือ Network Retry
- **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 หลายประเภท (Types) เช่น จดหมาย (Letter), อีเมล์ (Email), Request for Information (RFI), และสามารถเพิ่มประเภทใหม่ได้ในภายหลัง
- 3.2.3. การสร้างเอกสาร (Correspondence):
- ผู้ใช้ที่มีสิทธิ์ (เช่น Document Control) สามารถสร้างเอกสารรอไว้ในสถานะ ฉบับร่าง" (Draft) ได้ ซึ่งผู้ใช้งานต่างองค์กรจะมองไม่เห็น
- เมื่อกด "Submitted" แล้ว การแก้ไข, ถอนเอกสารกลับไปสถานะ Draft, หรือยกเลิก (Cancel) จะต้องทำโดยผู้ใช้ระดับ Admin ขึ้นไป พร้อมระบุเหตุผล
- 3.2.4. การอ้างอิงและจัดกลุ่ม:
- เอกสารสามารถอ้างถึง (Reference) เอกสารฉบับก่อนหน้าได้หลายฉบับ
- สามารถกำหนด Tag ได้หลาย Tag เพื่อจัดกลุ่มและใช้ในการค้นหาขั้นสูง
- 3.2.5. Correspondence Routing & Workflow
- 3.2.5.1 Routing Templates (แม่แบบการส่งต่อ)
- ผู้ดูแลระบบต้องสามารถสร้างแม่แบบการส่งต่อได้
- แม่แบบสามารถเป็นแบบทั่วไป (ใช้ได้ทุกโครงการ) หรือเฉพาะโครงการ
- แต่ละแม่แบบประกอบด้วยลำดับขั้นตอนการส่งต่อ
- การส่งจาก Originator -> Organization 1 -> Organization 2 -> Organization 3 แล้วส่งผลกลับตามลำดับเดิม (โดยถ้า องกรณ์ใดใน Wouting ให้ส่งกลับ ก็สามารถส่งผลกลับตามลำดับเดิมโดยไม่ต้องรอให้ถึง องกรณืในลำดับถัดไป)
- 3.2.5.2 Routing Steps (ขั้นตอนการส่งต่อ) แต่ละขั้นตอนในแม่แบบต้องกำหนด:
- **ลำดับขั้นตอน** (Sequence)
- **องค์กรผู้รับ** (To Organization)
- **วัตถุประสงค์** (Purpose): เพื่ออนุมัติ (FOR_APPROVAL), เพื่อตรวจสอบ (FOR_REVIEW), เพื่อทราบ (FOR_INFORMATION), เพื่อดำเนินการ (FOR_ACTION)
- **ระยะเวลาที่คาดหวัง** (Expected Duration)
- 3.2.5.3 Actual Routing Execution (การส่งต่อจริง) เมื่อสร้างเอกสารและเลือกใช้แม่แบบ ระบบต้อง:
- สร้างลำดับการส่งต่อตามแม่แบบ
- ติดตามสถานะของแต่ละขั้นตอน: ส่งแล้ว (SENT), กำลังดำเนินการ (IN_PROGRESS), ดำเนินการแล้ว (ACTIONED), ส่งต่อแล้ว (FORWARDED), ตอบกลับแล้ว (REPLIED)
- ระบุวันครบกำหนด (Due Date) สำหรับแต่ละขั้นตอน
- บันทึกผู้ดำเนินการและเวลาที่ดำเนินการ
- 3.2.5.4 Routing Flexibility (ความยืดหยุ่น)
- สามารถข้ามขั้นตอนได้ในกรณีพิเศษ (โดยผู้มีสิทธิ์)
- สามารถส่งกลับขั้นตอนก่อนหน้าได้
- สามารถเพิ่มความคิดเห็นในแต่ละขั้นตอน
- แจ้งเตือนอัตโนมัติเมื่อถึงขั้นตอนใหม่หรือใกล้ครบกำหนด
- 3.2.6. การจัดการ: มีการจัดการอย่างน้อยดังนี้
- สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบของ องกรณ์ ที่เป็นผู้รับได้
- มีระบบแจ้งเตือน ให้ผู้รับผิดชอบขององกรณ์ที่เป็น ผู้รับ/ผู้ส่ง ทราบ เมื่อมีเอกสารใหม่ หรือมีการเปลี่ยนสถานะ
### **3.3. การจัดกาแบบคู่สัญญา (Contract Drawing)**
- 3.3.1. วัตถุประสงค์: แบบคู่สัญญา (Contract Drawing) ใช้เพื่ออ้างอิงและใช้ในการตรวจสอบ
- 3.3.2. ประเภทเอกสาร: ไฟล์ PDF
- 3.3.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
- 3.3.4. การอ้างอิงและจัดกลุ่ม: ใช้สำหรับอ้างอิง ใน Shop Drawings, มีการจัดหมวดหมู่ของ Contract Drawing
### **3.4. การจัดกาแบบก่อสร้าง (Shop Drawing)**
- 3.4.1. วัตถุประสงค์: แบบก่อสร้าง (Shop Drawing) ใช้เในการตรวจสอบ โดยจัดส่งด้วย Request for Approval (RFA)
- 3.4.2. ประเภทเอกสาร: ไฟล์ PDF
- 3.4.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
- 3.4.4. การอ้างอิงและจัดกลุ่ม: ช้สำหรับอ้างอิง ใน Shop Drawings, มีการจัดหมวดหมู่ของ Shop Drawings
### **3.5. การจัดการเอกสารขออนุมัติ (Request for Approval & Workflow)**
- 3.5.1. วัตถุประสงค์: เอกสารขออนุมัติ (Request for Approval) ใช้ในการส่งเอกสารเพิอขออนุมัติ
- 3.5.2. ประเภทเอกสาร: Request for Approval (RFA) เป็นชนิดหนึ่งของ Correspondence ที่มีลักษณะเฉพาะที่ต้องได้รับการอนุมัติ มีประเภทดังนี้:
- Request for Drawing Approval (RFA_DWG)
- Request for Document Approval (RFA_DOC)
- Request for Method statement Approval (RFA_MES)
- Request for Material Approval (RFA_MAT)
- 3.5.2. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
- 3.5.3. การอ้างอิงและจัดกลุ่ม: การจัดการ Drawing (RFA_DWG):
- เอกสาร RFA_DWG จะประกอบไปด้วย Shop Drawing (shop_drawings) หลายแผ่น ซึ่งแต่ละแผ่นมี Revision ของตัวเอง
- Shop Drawing แต่ละ Revision สามารถอ้างอิงถึง Contract Drawing (Ccontract_drawings) หลายแผ่น หรือไม่อ้างถึงก็ได้
- ระบบต้องมีส่วนสำหรับจัดการข้อมูล Master Data ของทั้ง Shop Drawing และ Contract Drawing แยกจากกัน
- 3.5.4. Workflow การอนุมัติ: ต้องรองรับกระบวนการอนุมัติที่ซับซ้อนและเป็นลำดับ เช่น
- ส่งจาก Originator -> Organization 1 -> Organization 2 -> Organization 3 แล้วส่งผลกลับตามลำดับเดิม (โดยถ้า องกรณ์ใดใน Workflow ให้ส่งกลับ ก็สามารถส่งผลกลับตามลำดับเดิมโดยไม่ต้องรอให้ถึง องกรณืในลำดับถัดไป)
- 3.5.5. การจัดการ: มีการจัดการอย่างน้อยดังนี้
- สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบของ องกรณ์ ที่อยู่ใน Workflow ได้
- มีระบบแจ้งเตือน ให้ผู้รับผิดชอบของ องกรณ์ ที่อยู่ใน Workflow ทราบ เมื่อมี RFA ใหม่ หรือมีการเปลี่ยนสถานะ
### **3.6.การจัดการเอกสารนำส่ง (Transmittals)**
- 3.6.1. วัตถุประสงค์: เอกสารนำส่ง ใช้สำหรับ นำส่ง Request for Approval (RFAS) หลายฉบับ ไปยังองค์กรอื่น
- 3.6.2. ประเภทเอกสาร: ไฟล์ PDF
- 3.6.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
- 3.6.4. การอ้างอิงและจัดกลุ่ม: เอกสารนำส่ง เป็นส่วนหนึ่งใน Correspondence
### **3.7. ใบเวียนเอกสาร (Circulation Sheet)**
- 3.7.1. วัตถุประสงค์: การสื่อสาร เอกสาร (Correspondence) ทุกฉบับ จะมีใบเวียนเอกสารเพื่อควบคุมและมอบหมายงานภายในองค์กร (สามารถดูและแก้ไขได้เฉพาะคนในองค์กร)
- 3.7.2. ประเภทเอกสาร: ไฟล์ PDF
- 3.7.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ในองค์กรนั้น สามารถสร้างและแก้ไขได้
- 3.7.4. การอ้างอิงและจัดกลุ่ม: การระบุผู้รับผิดชอบ:
- ผู้รับผิดชอบหลัก (Main): มีได้หลายคน
- ผู้ร่วมปฏิบัติงาน (Action): มีได้หลายคน
- ผู้ที่ต้องรับทราบ (Information): มีได้หลายคน
- 3.7.5. การติดตามงาน:
- สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบประเภท Main และ Action ได้
- มีระบบแจ้งเตือนเมื่อมี Circulation ใหม่ และแจ้งเตือนล่วงหน้าก่อนถึงวันแล้วเสร็จ
- สามารถปิด Circulation ได้เมื่อดำเนินการตอบกลับไปยังองค์กรผู้ส่ง (Originator) แล้ว หรือ รับทราบแล้ว (For Information)
### **3.8. ประวัติการแก้ไข (Revisions):** ระบบจะเก็บประวัติการสร้างและแก้ไข เอกสารทั้งหมด
### **3.9. การจัดเก็บไฟล์ (File Handling - ปรับปรุงใหญ่)**
- **3.9.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.9.2 Security:**
- Virus Scan (ClamAV) ก่อนย้ายเข้า Permanent
- Whitelist File Types: PDF, DWG, DOCX, XLSX, ZIP
- Max Size: 50MB
- Access Control: ตรวจสอบสิทธิ์ผ่าน Junction Table ก่อนให้ Download Link
- **3.9.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.10. การจัดการเลขที่เอกสาร (Document Numbering - ปรับปรุง)**
- 3.10.1. ระบบต้องสามารถสร้างเลขที่เอกสาร (เช่น correspondence_number) ได้โดยอัตโนมัติ
- 3.10.2. การนับเลข Running Number (SEQ) จะต้องนับแยกตาม Key ดังนี้: **โครงการ (Project)**, **องค์กรผู้ส่ง (Originator Organization)**, **ประเภทเอกสาร (Document Type)** และ **ปีปัจจุบัน (Year)**
- 3.10.3. ผู้ดูแลระบบ (Admin) ต้องสามารถกำหนด "รูปแบบ" (Format Template) ของเลขที่เอกสารได้ (เช่น {ORG_CODE}-{TYPE_CODE}-{YEAR_SHORT}-{SEQ:4}) โดยกำหนดแยกตามโครงการและประเภทเอกสาร
- 3.10.4. **กลไก:** ใช้ **Redis Distributed Lock** เป็นด่านแรก
- 3.10.5. **Safety Net:** เพิ่ม **Optimistic Locking** (ตรวจสอบ Version/Last Number ใน DB ขณะ Update) เพื่อป้องกันกรณี Redis ล่ม หรือ Race Condition หลุดรอด
- 3.10.6. ต้องมี retry mechanism และ fallback strategy เมื่อการ generate เลขที่เอกสารล้มเหลว
### **3.11 การจัดการ JSON Details (JSON & Performance - ปรับปรุง)**
- **3.11.1 วัตถุประสงค์**
- จัดเก็บข้อมูลแบบไดนามิกที่เฉพาะเจาะจงกับแต่ละประเภทของเอกสาร
- รองรับการขยายตัวของระบบโดยไม่ต้องเปลี่ยนแปลง database schema
- จัดการ metadata และข้อมูลประกอบสำหรับ correspondence, routing, และ workflows
- **3.11.2 โครงสร้าง JSON Schema**
ระบบต้องมี predefined JSON schemas สำหรับประเภทเอกสารต่างๆ:
- **3.11.2.1 Correspondence Types**
- **GENERIC**: ข้อมูลพื้นฐานสำหรับเอกสารทั่วไป
- **RFI**: รายละเอียดคำถามและข้อมูลทางเทคนิค
- **RFA**: ข้อมูลการขออนุมัติแบบและวัสดุ
- **TRANSMITTAL**: รายการเอกสารที่ส่งต่อ
- **LETTER**: ข้อมูลจดหมายทางการ
- **EMAIL**: ข้อมูลอีเมล
- **3.11.2.2 Routing Types**
- **ROUTING_TEMPLATE**: กฎและเงื่อนไขการส่งต่อ
- **ROUTING_INSTANCE**: สถานะและประวัติการส่งต่อ
- **ROUTING_ACTION**: การดำเนินการในแต่ละขั้นตอน
- **3.11.2.3 Audit Types**
- **AUDIT_LOG**: ข้อมูลการตรวจสอบ
- **SECURITY_SCAN**: ผลการตรวจสอบความปลอดภัย
- **3.11.3 Virtual Columns (ใหม่):** สำหรับ Field ใน JSON ที่ต้องใช้ในการค้นหา (Search) หรือจัดเรียง (Sort) บ่อยๆ **ต้องสร้าง Generated Column (Virtual Column)** ใน Database และทำ Index ไว้ เพื่อประสิทธิภาพสูงสุด
- **3.11.4 Validation Rules**
- ต้องมี JSON schema validation สำหรับแต่ละประเภท
- ต้องรองรับ versioning ของ schema
- ต้องมี default values สำหรับ field ที่ไม่บังคับ
- ต้องตรวจสอบ data types และ format ให้ถูกต้อง
- **3.11.5 Performance Requirements**
- JSON field ต้องมีขนาดไม่เกิน 50KB
- ต้องรองรับ indexing สำหรับ field ที่ใช้ค้นหาบ่อย
- ต้องมี compression สำหรับ JSON ขนาดใหญ่
- **3.11.6 Security Requirements**
- ต้อง sanitize JSON input เพื่อป้องกัน injection attacks
- ต้อง validate JSON structure ก่อนบันทึก
- ต้อง encrypt sensitive data ใน JSON fields
### **3.12 ข้อกำหนดพิเศษ**
- **ผู้ใช้งานที่มีสิทธิ์ระดับสูง (Global) หรือผู้ได้รับอนุญาตเป็นกรณีพิเศษ**
- สามารถเลือก **สร้างในนามองค์กร (Create on behalf of)** ได้ เพื่อให้สามารถออกเลขที่เอกสาร (Running Number) ขององค์กรอื่นได้โดยไม่ต้องล็อกอินใหม่
- สามารถทำงานแทนผู้ใช้งานอื่นได้ Routing & Workflow ของ Correspondence, RFA, Circulation Sheet
## **🔐 4. ข้อกำหนดด้านสิทธิ์และการเข้าถึง (Access Control Requirements)**
### **4.1. ภาพรวม:** ผู้ใช้และองค์กรสามารถดูและแก้ไขเอกสารได้ตามสิทธิ์ที่ได้รับ โดยระบบสิทธิ์จะเป็นแบบ Role-Based Access Control (RBAC)
### **4.2. ลำดับชั้นของสิทธิ์ (Permission Hierarchy)**
- Global: สิทธิ์สูงสุดของระบบ
- Organization: สิทธิ์ภายในองค์กร เป็นสิทธิ์พื้นฐานของผู้ใช้
- Project: สิทธิ์เฉพาะในโครงการ จะถูกพิจารณาเมื่อผู้ใช้อยู่ในโครงการนั้น
- Contract: สิทธิ์เฉพาะในสัญญา จะถูกพิจารณาเมื่อผู้ใช้อยู่ในสัญญานั้น (สัญญาเป็นส่วนหนึ่งของโครงการ)
กฎการบังคับใช้: เมื่อตรวจสอบสิทธิ์ ระบบจะพิจารณาสิทธิ์จากทุกระดับที่ผู้ใช้มี และใช้ สิทธิ์ที่มากที่สุด (Most Permissive) เป็นตัวตัดสิน
ตัวอย่าง: ผู้ใช้ A เป็น Viewer ในองค์กร แต่ถูกมอบหมายเป็น Editor ในโครงการ X เมื่ออยู่ในโครงการ X ผู้ใช้ A จะมีสิทธิ์แก้ไขได้
### **4.3. การกำหนดบทบาท (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.4. Token Management (ปรับปรุง)**
- **Payload Optimization:** ใน JWT Access Token ให้เก็บเฉพาะ `userId` และ `scope` ปัจจุบันเท่านั้น
- **Permission Caching:** สิทธิ์ละเอียด (Permissions List) ให้เก็บใน **Redis** และดึงมาตรวจสอบเมื่อ Request เข้ามา เพื่อลดขนาด Token และเพิ่มความเร็ว
### **4.5. กระบวนการเริ่มต้นใช้งาน (Onboarding Workflow) ที่สมบูรณ์**
- **4.5.1. สร้างองค์กร (Organization)**
- **Superadmin** สร้างองค์กรใหม่ (เช่น บริษัท A)
- **Superadmin** แต่งตั้งผู้ใช้อย่างน้อย 1 คนให้เป็น **Org Admin** หรือ **Document Control** ของบริษัท A
- **4.5.2. เพิ่มผู้ใช้ในองค์กร**
- **Org Admin** ของบริษัท A เพิ่มผู้ใช้อื่นๆ (Editor, Viewer) เข้ามาในองค์กรของตน
- **4.5.3. มอบหมายผู้ใช้ให้กับโครงการ (Project)**
- **Project Manager** ของโครงการ X (ซึ่งอาจมาจากบริษัท A หรือบริษัทอื่น) ทำการ "เชิญ" หรือ "มอบหมาย" ผู้ใช้จากองค์กรต่างๆ ที่เกี่ยวข้องเข้ามาในโครงการ X
- ในขั้นตอนนี้ **Project Manager** จะกำหนด **บทบาทระดับโครงการ** (เช่น Project Member, หรืออาจไม่มีบทบาทพิเศษ ให้ใช้สิทธิ์จากระดับองค์กรไปก่อน)
- **4.5.4. เมอบหมายผู้ใช้ให้กับสัญญา (Contract)**
- **Contract Admin** ของสัญญา Y (ซึ่งเป็นส่วนหนึ่งของโครงการ X) ทำการเลือกผู้ใช้ที่อยู่ในโครงการ X แล้ว มอบหมายให้เข้ามาในสัญญา Y
- ในขั้นตอนนี้ **Contract Admin** จะกำหนด **บทบาทระดับสัญญา** (เช่น Contract Member) และสิทธิ์เฉพาะที่จำเป็น
- **4.5.5 Security Onboarding:**
- ต้องบังคับเปลี่ยน password ครั้งแรกสำหรับผู้ใช้ใหม่
- ต้องมี security awareness training สำหรับผู้ใช้ที่มีสิทธิ์สูง
- ต้องมี process สำหรับการรีเซ็ต password ที่ปลอดภัย
- ต้องบันทึก audit log ทุกครั้งที่มีการเปลี่ยนแปลง permissions
### **4.6. การจัดการข้อมูลหลัก (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 & Workflow):** ผู้ใช้สามารถดู RFA ในรูปแบบ Workflow ทั้งหมดได้ในหน้าเดียว, ขั้นตอนที่ยังไม่ถึงหรือผ่านไปแล้วจะเป็นรูปแบบ diable, สามารถดำเนินการได้เฉพาะในขั้นตอนที่ได้รับมอบหมายงาน (active) เช่น ตรวจสอบแล้ว เพื่อไปยังขั้นตอนต่อไป, สิทธิ์ Document Control ขึ้นไป สามรถกด ไปยังขั้นตอนต่อไป ได้ทุกขั้นตอน, การย้อนกลับ ไปขั้นตอนก่อนหน้า สามารถทำได้โดย สิทธิ์ Document Control ขึ้นไป
### **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 โดยไม่ได้ตั้งใจ
- **Graceful Degradation:** หาก Service รอง (เช่น Search, Notification) ล่ม ระบบหลัก (CRUD) ต้องยังทำงานต่อได้
## **🛡️ 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.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
- ต้องทดสอบ 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:**
- **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
## **📋 สรุปการปรับปรุงจากเวอร์ชันก่อนหน้า**
### **Security Enhancements:**
1. **File Upload Security** - Virus scanning, file type validation, access controls
2. **Input Validation** - OWASP Top 10 protection, XSS/CSRF prevention
3. **Rate Limiting** - Comprehensive rate limiting strategy
4. **Secrets Management** - Secure handling of sensitive configuration
### **Architecture Improvements:**
1. **Document Numbering** - Changed from Stored Procedure to Application-level Locking with Optimistic Locking safety net
2. **Resilience Patterns** - Circuit breaker, retry mechanisms, fallback strategies
3. **Monitoring & Observability** - Health checks, metrics, distributed tracing
4. **Caching Strategy** - Comprehensive caching with proper invalidation
5. **Two-Phase File Storage** - Temp -> Permanent storage with transaction safety
6. **Unified Workflow Engine** - Consolidated routing logic for better maintainability
### **Performance Targets:**
1. **API Response Time** - < 200ms (90th percentile)
2. **Search Performance** - < 500ms
3. **File Upload** - < 30 seconds for 50MB files
4. **Cache Hit Ratio** - > 80%
### **Operational Excellence:**
1. **Disaster Recovery** - RTO < 4 hours, RPO < 1 hour
2. **Backup Procedures** - Comprehensive backup and restoration
3. **Security Testing** - Penetration testing and security audits
4. **Performance Testing** - Load testing with realistic workloads
5. **Maintenance Mode** - Graceful system maintenance capabilities
### **User Experience Improvements:**
1. **Dynamic Form Generator** - Reduced code duplication and better schema support
2. **Mobile Responsiveness** - Card view for tables on mobile devices
3. **Auto-Save Draft** - LocalStorage integration for form resilience
4. **Notification Digest** - Reduced notification spam
### **Data Management:**
1. **Virtual Columns** - Improved JSON field search performance
2. **Table Partitioning** - Support for large-scale data growth
3. **Idempotency Keys** - Prevention of duplicate transactions
เอกสารนี้สะท้อนถึงความมุ่งมั่นในการสร้างระบบที่มีความปลอดภัย, มีความทนทาน, และมีประสิทธิภาพสูง พร้อมรองรับการเติบโตในอนาคตและความต้องการทางธุรกิจที่เปลี่ยนแปลงไป
**หมายเหตุ:** Requirements นี้จะถูกทบทวนและปรับปรุงเป็นระยะตาม feedback จากทีมพัฒนาและความต้องการทางธุรกิจที่เปลี่ยนแปลงไป
## **Document Control:**
- **Document:** Application Requirements Specification v1.4.3
- **Version:** 1.4
- **Date:** 2025-11-22
- **Author:** NAP LCBP3-DMS & Gemini
- **Status:** FINAL-Rev.01
- **Classification:** Internal Technical Documentation
- **Approved By:** Nattanin
---
`End of Requirements Specification v1.4.3`

803
infrastructure/Markdown/0_Requirements_V1_4_4.md Normal file
View File

@@ -0,0 +1,803 @@
# 📝 **Documents Management System Version 1.4.4: Application Requirements Specification**
**สถานะ:** FINAL-Rev.05
**วันที่:** 2025-11-26
**อ้างอิงพื้นฐาน:** 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 ลงในตาราง
- **2.4.2 Separation of Concerns:** Module ต่างๆ (RFA, Correspondence) จะเก็บเฉพาะข้อมูลของเอกสาร (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 หลายประเภท (Types) เช่น จดหมาย (Letter), อีเมล์ (Email), Request for Information (RFI), และสามารถเพิ่มประเภทใหม่ได้ในภายหลัง
- 3.2.3. การสร้างเอกสาร (Correspondence):
- ผู้ใช้ที่มีสิทธิ์ (เช่น Document Control) สามารถสร้างเอกสารรอไว้ในสถานะ ฉบับร่าง" (Draft) ได้ ซึ่งผู้ใช้งานต่างองค์กรจะมองไม่เห็น
- เมื่อกด "Submitted" แล้ว การแก้ไข, ถอนเอกสารกลับไปสถานะ Draft, หรือยกเลิก (Cancel) จะต้องทำโดยผู้ใช้ระดับ Admin ขึ้นไป พร้อมระบุเหตุผล
- 3.2.4. การอ้างอิงและจัดกลุ่ม:
- เอกสารสามารถอ้างถึง (Reference) เอกสารฉบับก่อนหน้าได้หลายฉบับ
- สามารถกำหนด Tag ได้หลาย Tag เพื่อจัดกลุ่มและใช้ในการค้นหาขั้นสูง
- 3.2.5. Correspondence Routing & Workflow
- 3.2.5.1 Routing Templates (แม่แบบการส่งต่อ)
- ผู้ดูแลระบบต้องสามารถสร้างแม่แบบการส่งต่อได้
- แม่แบบสามารถเป็นแบบทั่วไป (ใช้ได้ทุกโครงการ) หรือเฉพาะโครงการ
- แต่ละแม่แบบประกอบด้วยลำดับขั้นตอนการส่งต่อ
- การส่งจาก Originator -> Organization 1 -> Organization 2 -> Organization 3 แล้วส่งผลกลับตามลำดับเดิม (โดยถ้า องกรณ์ใดใน Wouting ให้ส่งกลับ ก็สามารถส่งผลกลับตามลำดับเดิมโดยไม่ต้องรอให้ถึง องกรณืในลำดับถัดไป)
- 3.2.5.2 Routing Steps (ขั้นตอนการส่งต่อ) แต่ละขั้นตอนในแม่แบบต้องกำหนด:
- **ลำดับขั้นตอน** (Sequence)
- **องค์กรผู้รับ** (To Organization)
- **วัตถุประสงค์** (Purpose): เพื่ออนุมัติ (FOR_APPROVAL), เพื่อตรวจสอบ (FOR_REVIEW), เพื่อทราบ (FOR_INFORMATION), เพื่อดำเนินการ (FOR_ACTION)
- **ระยะเวลาที่คาดหวัง** (Expected Duration)
- 3.2.5.3 Actual Routing Execution (การส่งต่อจริง) เมื่อสร้างเอกสารและเลือกใช้แม่แบบ ระบบต้อง:
- สร้างลำดับการส่งต่อตามแม่แบบ
- ติดตามสถานะของแต่ละขั้นตอน: ส่งแล้ว (SENT), กำลังดำเนินการ (IN_PROGRESS), ดำเนินการแล้ว (ACTIONED), ส่งต่อแล้ว (FORWARDED), ตอบกลับแล้ว (REPLIED)
- ระบุวันครบกำหนด (Due Date) สำหรับแต่ละขั้นตอน
- บันทึกผู้ดำเนินการและเวลาที่ดำเนินการ
- 3.2.5.4 Routing Flexibility (ความยืดหยุ่น)
- สามารถข้ามขั้นตอนได้ในกรณีพิเศษ (โดยผู้มีสิทธิ์)
- สามารถส่งกลับขั้นตอนก่อนหน้าได้
- สามารถเพิ่มความคิดเห็นในแต่ละขั้นตอน
- แจ้งเตือนอัตโนมัติเมื่อถึงขั้นตอนใหม่หรือใกล้ครบกำหนด
- 3.2.6. การจัดการ: มีการจัดการอย่างน้อยดังนี้
- สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบของ องกรณ์ ที่เป็นผู้รับได้
- มีระบบแจ้งเตือน ให้ผู้รับผิดชอบขององกรณ์ที่เป็น ผู้รับ/ผู้ส่ง ทราบ เมื่อมีเอกสารใหม่ หรือมีการเปลี่ยนสถานะ
### **3.3. การจัดกาแบบคู่สัญญา (Contract Drawing)**
- 3.3.1. วัตถุประสงค์: แบบคู่สัญญา (Contract Drawing) ใช้เพื่ออ้างอิงและใช้ในการตรวจสอบ
- 3.3.2. ประเภทเอกสาร: ไฟล์ PDF
- 3.3.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
- 3.3.4. การอ้างอิงและจัดกลุ่ม: ใช้สำหรับอ้างอิง ใน Shop Drawings, มีการจัดหมวดหมู่ของ Contract Drawing
### **3.4. การจัดกาแบบก่อสร้าง (Shop Drawing)**
- 3.4.1. วัตถุประสงค์: แบบก่อสร้าง (Shop Drawing) ใช้เในการตรวจสอบ โดยจัดส่งด้วย Request for Approval (RFA)
- 3.4.2. ประเภทเอกสาร: ไฟล์ PDF
- 3.4.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
- 3.4.4. การอ้างอิงและจัดกลุ่ม: ช้สำหรับอ้างอิง ใน Shop Drawings, มีการจัดหมวดหมู่ของ Shop Drawings
### **3.5. การจัดการ Workflow (Unified Workflow)**
- 3.5.1 Workflow Definition:
- Admin ต้องสามารถสร้าง/แก้ไข Workflow Rule ได้ผ่านหน้าจอ UI (DSL Editor) ร
- องรับการกำหนด State, Transition, Required Role, Condition (JS Expression)
- 3.5.2 Workflow Execution:
- ระบบต้องรองรับการสร้าง Instance ของ Workflow ผูกกับเอกสาร (Polymorphic)
- รองรับการเปลี่ยนสถานะ (Action) เช่น Approve, Reject, Comment, Return
- Auto-Action: รองรับการเปลี่ยนสถานะอัตโนมัติเมื่อครบเงื่อนไข (เช่น Review ครบทุกคน)
- 3.5.3 Flexibility:
- รองรับ Parallel Review (ส่งให้หลายคนตรวจพร้อมกัน)
- รองรับ Conditional Flow (เช่น ถ้ายอดเงิน > X ให้เพิ่มผู้อนุมัติ)
- 3.5.4 Workflow การอนุมัติ:
- ต้องรองรับกระบวนการอนุมัติที่ซับซ้อนและเป็นลำดับ เช่น ส่งจาก Originator -> Organization 1 -> Organization 2 -> Organization 3 แล้วส่งผลกลับตามลำดับเดิม (โดยถ้า องกรณ์ใดใน Workflow ให้ส่งกลับ ก็สามารถส่งผลกลับตามลำดับเดิมโดยไม่ต้องรอให้ถึง องกรณืในลำดับถัดไป)
- 3.5.5 การจัดการ:
- สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบของ องกรณ์ ที่อยู่ใน Workflow ได้
- มีระบบแจ้งเตือน ให้ผู้รับผิดชอบของ องกรณ์ ที่อยู่ใน Workflow ทราบ เมื่อมี RFA ใหม่ หรือมีการเปลี่ยนสถานะ
### **3.6.การจัดการเอกสารนำส่ง (Transmittals)**
- 3.6.1. วัตถุประสงค์: เอกสารนำส่ง ใช้สำหรับ นำส่ง Request for Approval (RFAS) หลายฉบับ ไปยังองค์กรอื่น
- 3.6.2. ประเภทเอกสาร: ไฟล์ PDF
- 3.6.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
- 3.6.4. การอ้างอิงและจัดกลุ่ม: เอกสารนำส่ง เป็นส่วนหนึ่งใน Correspondence
### **3.7. ใบเวียนเอกสาร (Circulation Sheet)**
- 3.7.1. วัตถุประสงค์: การสื่อสาร เอกสาร (Correspondence) ทุกฉบับ จะมีใบเวียนเอกสารเพื่อควบคุมและมอบหมายงานภายในองค์กร (สามารถดูและแก้ไขได้เฉพาะคนในองค์กร)
- 3.7.2. ประเภทเอกสาร: ไฟล์ PDF
- 3.7.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ในองค์กรนั้น สามารถสร้างและแก้ไขได้
- 3.7.4. การอ้างอิงและจัดกลุ่ม: การระบุผู้รับผิดชอบ:
- ผู้รับผิดชอบหลัก (Main): มีได้หลายคน
- ผู้ร่วมปฏิบัติงาน (Action): มีได้หลายคน
- ผู้ที่ต้องรับทราบ (Information): มีได้หลายคน
- 3.7.5. การติดตามงาน:
- สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบประเภท Main และ Action ได้
- มีระบบแจ้งเตือนเมื่อมี Circulation ใหม่ และแจ้งเตือนล่วงหน้าก่อนถึงวันแล้วเสร็จ
- สามารถปิด Circulation ได้เมื่อดำเนินการตอบกลับไปยังองค์กรผู้ส่ง (Originator) แล้ว หรือ รับทราบแล้ว (For Information)
### **3.8. ประวัติการแก้ไข (Revisions):** ระบบจะเก็บประวัติการสร้างและแก้ไข เอกสารทั้งหมด
### **3.9. การจัดเก็บไฟล์ (File Handling - ปรับปรุงใหญ่)**
- **3.9.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.9.2 Security:**
- Virus Scan (ClamAV) ก่อนย้ายเข้า Permanent
- Whitelist File Types: PDF, DWG, DOCX, XLSX, ZIP
- Max Size: 50MB
- Access Control: ตรวจสอบสิทธิ์ผ่าน Junction Table ก่อนให้ Download Link
- **3.9.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.10. การจัดการเลขที่เอกสาร (Document Numbering - ปรับปรุง)**
- 3.10.1. ระบบต้องสามารถสร้างเลขที่เอกสาร (Running Number) ได้โดยอัตโนมัติและยืดหยุ่นสูง
- 3.10.2. **Logic การนับเลข (Counter Logic):** การนับเลขจะต้องรองรับการแยกตาม Key ที่ซับซ้อนขึ้น:
- **Project** + **Originator** + **Type** + **Discipline** (ถ้ามี) + **Sub-Type** (ถ้ามี) + **Year**
- 3.10.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.10.4. **Transmittal Logic:** รองรับเงื่อนไขพิเศษสำหรับ Transmittal ที่เลขอาจเปลี่ยนตามผู้รับ (To Owner vs To Contractor)
- 3.10.5. **กลไกความปลอดภัย:** ยังคงใช้ Redis Distributed Lock และ Optimistic Locking เพื่อป้องกันเลขซ้ำหรือข้าม
- 3.10.6. ต้องมี retry mechanism และ fallback strategy เมื่อการ generate เลขที่เอกสารล้มเหลว
### **3.11 การจัดการ JSON Details (JSON & Performance - ปรับปรุง)**
- **3.11.1 วัตถุประสงค์**
- จัดเก็บข้อมูลแบบไดนามิกที่เฉพาะเจาะจงกับแต่ละประเภทของเอกสาร
- รองรับการขยายตัวของระบบโดยไม่ต้องเปลี่ยนแปลง database schema
- จัดการ metadata และข้อมูลประกอบสำหรับ correspondence, routing, และ workflows
- **3.11.2 โครงสร้าง JSON Schema**
ระบบต้องมี predefined JSON schemas สำหรับประเภทเอกสารต่างๆ:
- **3.11.2.1 Correspondence Types**
- **GENERIC**: ข้อมูลพื้นฐานสำหรับเอกสารทั่วไป
- **RFI**: รายละเอียดคำถามและข้อมูลทางเทคนิค
- **RFA**: ข้อมูลการขออนุมัติแบบและวัสดุ
- **TRANSMITTAL**: รายการเอกสารที่ส่งต่อ
- **LETTER**: ข้อมูลจดหมายทางการ
- **EMAIL**: ข้อมูลอีเมล
- **3.11.2.2 Rworkflow Types**
- **workflow_definitions**: กฎและเงื่อนไขการส่งต่อ
- **workflow_histories**: สถานะและประวัติการส่งต่อ
- **workflow_instances**: การดำเนินการในแต่ละขั้นตอน
- **3.11.2.3 Audit Types**
- **AUDIT_LOG**: ข้อมูลการตรวจสอบ
- **SECURITY_SCAN**: ผลการตรวจสอบความปลอดภัย
- **3.11.3 Virtual Columns (ใหม่):** สำหรับ Field ใน JSON ที่ต้องใช้ในการค้นหา (Search) หรือจัดเรียง (Sort) บ่อยๆ **ต้องสร้าง Generated Column (Virtual Column)** ใน Database และทำ Index ไว้ เพื่อประสิทธิภาพสูงสุด
- **3.11.4 Validation Rules**
- ต้องมี JSON schema validation สำหรับแต่ละประเภท
- ต้องรองรับ versioning ของ schema
- ต้องมี default values สำหรับ field ที่ไม่บังคับ
- ต้องตรวจสอบ data types และ format ให้ถูกต้อง
- **3.11.5 Performance Requirements**
- JSON field ต้องมีขนาดไม่เกิน 50KB
- ต้องรองรับ indexing สำหรับ field ที่ใช้ค้นหาบ่อย
- ต้องมี compression สำหรับ JSON ขนาดใหญ่
- **3.11.6 Security Requirements**
- ต้อง sanitize JSON input เพื่อป้องกัน injection attacks
- ต้อง validate JSON structure ก่อนบันทึก
- ต้อง encrypt sensitive data ใน JSON fields
### **3.12 ข้อกำหนดพิเศษ**
- **ผู้ใช้งานที่มีสิทธิ์ระดับสูง (Global) หรือผู้ได้รับอนุญาตเป็นกรณีพิเศษ**
- สามารถเลือก **สร้างในนามองค์กร (Create on behalf of)** ได้ เพื่อให้สามารถออกเลขที่เอกสาร (Running Number) ขององค์กรอื่นได้โดยไม่ต้องล็อกอินใหม่
- สามารถทำงานแทนผู้ใช้งานอื่นได้ Routing & Workflow ของ Correspondence, RFA, Circulation Sheet
### 3.13. การจัดการข้อมูลหลักขั้นสูง (Admin Panel for Master Data)
- 3.13.1. **Disciplines Management:** Admin ต้องสามารถ เพิ่ม/ลบ/แก้ไข สาขางาน (Disciplines) แยกตามสัญญา (Contract) ได้
- 3.13.2. **Sub-Type Mapping:** Admin ต้องสามารถกำหนด Correspondence Sub-types และ Mapping รหัสตัวเลข (เช่น MAT = 11) ได้
- 3.13.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: สิทธิ์เฉพาะในสัญญา จะถูกพิจารณาเมื่อผู้ใช้อยู่ในสัญญานั้น (สัญญาเป็นส่วนหนึ่งของโครงการ)
กฎการบังคับใช้: เมื่อตรวจสอบสิทธิ์ ระบบจะพิจารณาสิทธิ์จากทุกระดับที่ผู้ใช้มี และใช้ สิทธิ์ที่มากที่สุด (Most Permissive) เป็นตัวตัดสิน
ตัวอย่าง: ผู้ใช้ A เป็น Viewer ในองค์กร แต่ถูกมอบหมายเป็น Editor ในโครงการ X เมื่ออยู่ในโครงการ X ผู้ใช้ A จะมีสิทธิ์แก้ไขได้
### **4.3. การกำหนดบทบาท (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.4. Token Management (ปรับปรุง)**
- **Payload Optimization:** ใน JWT Access Token ให้เก็บเฉพาะ `userId` และ `scope` ปัจจุบันเท่านั้น
- **Permission Caching:** สิทธิ์ละเอียด (Permissions List) ให้เก็บใน **Redis** และดึงมาตรวจสอบเมื่อ Request เข้ามา เพื่อลดขนาด Token และเพิ่มความเร็ว
### **4.5. กระบวนการเริ่มต้นใช้งาน (Onboarding Workflow) ที่สมบูรณ์**
- **4.5.1. สร้างองค์กร (Organization)**
- **Superadmin** สร้างองค์กรใหม่ (เช่น บริษัท A)
- **Superadmin** แต่งตั้งผู้ใช้อย่างน้อย 1 คนให้เป็น **Org Admin** หรือ **Document Control** ของบริษัท A
- **4.5.2. เพิ่มผู้ใช้ในองค์กร**
- **Org Admin** ของบริษัท A เพิ่มผู้ใช้อื่นๆ (Editor, Viewer) เข้ามาในองค์กรของตน
- **4.5.3. มอบหมายผู้ใช้ให้กับโครงการ (Project)**
- **Project Manager** ของโครงการ X (ซึ่งอาจมาจากบริษัท A หรือบริษัทอื่น) ทำการ "เชิญ" หรือ "มอบหมาย" ผู้ใช้จากองค์กรต่างๆ ที่เกี่ยวข้องเข้ามาในโครงการ X
- ในขั้นตอนนี้ **Project Manager** จะกำหนด **บทบาทระดับโครงการ** (เช่น Project Member, หรืออาจไม่มีบทบาทพิเศษ ให้ใช้สิทธิ์จากระดับองค์กรไปก่อน)
- **4.5.4. เมอบหมายผู้ใช้ให้กับสัญญา (Contract)**
- **Contract Admin** ของสัญญา Y (ซึ่งเป็นส่วนหนึ่งของโครงการ X) ทำการเลือกผู้ใช้ที่อยู่ในโครงการ X แล้ว มอบหมายให้เข้ามาในสัญญา Y
- ในขั้นตอนนี้ **Contract Admin** จะกำหนด **บทบาทระดับสัญญา** (เช่น Contract Member) และสิทธิ์เฉพาะที่จำเป็น
- **4.5.5 Security Onboarding:**
- ต้องบังคับเปลี่ยน password ครั้งแรกสำหรับผู้ใช้ใหม่
- ต้องมี security awareness training สำหรับผู้ใช้ที่มีสิทธิ์สูง
- ต้องมี process สำหรับการรีเซ็ต password ที่ปลอดภัย
- ต้องบันทึก audit log ทุกครั้งที่มีการเปลี่ยนแปลง permissions
### **4.6. การจัดการข้อมูลหลัก (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 & Workflow):** ผู้ใช้สามารถดู RFA ในรูปแบบ Workflow ทั้งหมดได้ในหน้าเดียว, ขั้นตอนที่ยังไม่ถึงหรือผ่านไปแล้วจะเป็นรูปแบบ diable, สามารถดำเนินการได้เฉพาะในขั้นตอนที่ได้รับมอบหมายงาน (active) เช่น ตรวจสอบแล้ว เพื่อไปยังขั้นตอนต่อไป, สิทธิ์ Document Control ขึ้นไป สามรถกด ไปยังขั้นตอนต่อไป ได้ทุกขั้นตอน, การย้อนกลับ ไปขั้นตอนก่อนหน้า สามารถทำได้โดย สิทธิ์ Document Control ขึ้นไป
### **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 โดยไม่ได้ตั้งใจ
- **Graceful Degradation:** หาก Service รอง (เช่น Search, Notification) ล่ม ระบบหลัก (CRUD) ต้องยังทำงานต่อได้
## **🛡️ 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.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
- ต้องทดสอบ 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:**
- **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
## **📋 สรุปการปรับปรุงจากเวอร์ชันก่อนหน้า**
### **Security Enhancements:**
1. **File Upload Security** - Virus scanning, file type validation, access controls
2. **Input Validation** - OWASP Top 10 protection, XSS/CSRF prevention
3. **Rate Limiting** - Comprehensive rate limiting strategy
4. **Secrets Management** - Secure handling of sensitive configuration
### **Architecture Improvements:**
1. **Document Numbering** - Changed from Stored Procedure to Application-level Locking with Optimistic Locking safety net
2. **Resilience Patterns** - Circuit breaker, retry mechanisms, fallback strategies
3. **Monitoring & Observability** - Health checks, metrics, distributed tracing
4. **Caching Strategy** - Comprehensive caching with proper invalidation
5. **Two-Phase File Storage** - Temp -> Permanent storage with transaction safety
6. **Unified Workflow Engine** - Consolidated routing logic for better maintainability
### **Performance Targets:**
1. **API Response Time** - < 200ms (90th percentile)
2. **Search Performance** - < 500ms
3. **File Upload** - < 30 seconds for 50MB files
4. **Cache Hit Ratio** - > 80%
### **Operational Excellence:**
1. **Disaster Recovery** - RTO < 4 hours, RPO < 1 hour
2. **Backup Procedures** - Comprehensive backup and restoration
3. **Security Testing** - Penetration testing and security audits
4. **Performance Testing** - Load testing with realistic workloads
5. **Maintenance Mode** - Graceful system maintenance capabilities
### **User Experience Improvements:**
1. **Dynamic Form Generator** - Reduced code duplication and better schema support
2. **Mobile Responsiveness** - Card view for tables on mobile devices
3. **Auto-Save Draft** - LocalStorage integration for form resilience
4. **Notification Digest** - Reduced notification spam
### **Data Management:**
1. **Virtual Columns** - Improved JSON field search performance
2. **Table Partitioning** - Support for large-scale data growth
3. **Idempotency Keys** - Prevention of duplicate transactions
เอกสารนี้สะท้อนถึงความมุ่งมั่นในการสร้างระบบที่มีความปลอดภัย, มีความทนทาน, และมีประสิทธิภาพสูง พร้อมรองรับการเติบโตในอนาคตและความต้องการทางธุรกิจที่เปลี่ยนแปลงไป
**หมายเหตุ:** Requirements นี้จะถูกทบทวนและปรับปรุงเป็นระยะตาม feedback จากทีมพัฒนาและความต้องการทางธุรกิจที่เปลี่ยนแปลงไป
## **Document Control:**
- **Document:** Application Requirements Specification v1.4.4
- **Version:** 1.4
- **Date:** 2025-11-26
- **Author:** NAP LCBP3-DMS & Gemini
- **Status:** FINAL-Rev.04
- **Classification:** Internal Technical Documentation
- **Approved By:** Nattanin
---
`End of Requirements Specification v1.4.4`

970
infrastructure/Markdown/1_FullStackJS_V1_4_3.md Normal file
View File

@@ -0,0 +1,970 @@
# 📝 **Documents Management System Version 1.4.3: แนวทางการพัฒนา FullStackJS**
**สถานะ:** FINAL GUIDELINE Rev.01
**วันที่:** 2025-11-22
**อ้างอิง:** Requirements Specification v1.4.3
**Classification:** Internal Technical Documentation
## 🧠 **1. ปรัชญาทั่วไป (General Philosophy)**
แนวทางปฏิบัติที่ดีที่สุดแบบครบวงจรสำหรับการพัฒนา NestJS Backend, NextJS Frontend และ Tailwind-based UI/UX ในสภาพแวดล้อม TypeScript มุ่งเน้นที่ **"Data Integrity First"** (ความถูกต้องของข้อมูลต้องมาก่อน) ตามด้วย Security และ UX
* **ความชัดเจน (clarity), ความง่ายในการบำรุงรักษา (maintainability), ความสอดคล้องกัน (consistency) และ การเข้าถึงได้ (accessibility)** ตลอดทั้งสแต็ก
* **Strict Typing:** ใช้ TypeScript อย่างเคร่งครัด ห้าม `any`
* **Consistency:** ใช้ภาษาอังกฤษใน Code / ภาษาไทยใน Comment
* **Resilience:** ระบบต้องทนทานต่อ Network Failure และ Race Condition
## ⚙️ **2. แนวทางทั่วไปสำหรับ TypeScript**
### **2.1 หลักการพื้นฐาน**
* ใช้ **ภาษาอังกฤษ** สำหรับโค้ด
* ใช้ **ภาษาไทย** สำหรับ comment และเอกสารทั้งหมด
* กำหนดไทป์ (type) อย่างชัดเจนสำหรับตัวแปร, พารามิเตอร์ และค่าที่ส่งกลับ (return values) ทั้งหมด
* หลีกเลี่ยงการใช้ any; ให้สร้างไทป์ (types) หรืออินเทอร์เฟซ (interfaces) ที่กำหนดเอง
* ใช้ **JSDoc** สำหรับคลาส (classes) และเมธอด (methods) ที่เป็น public
* ส่งออก (Export) **สัญลักษณ์หลัก (main symbol) เพียงหนึ่งเดียว** ต่อไฟล์
* หลีกเลี่ยงบรรทัดว่างภายในฟังก์ชัน
* ระบุ // File: path/filename ในบรรทัดแรกของทุกไฟล์
* ระบุ // บันทึกการแก้ไข, หากมีการแก้ไขเพิ่มในอนาคต ให้เพิ่มบันทึก
### **2.2 Configuration & Secrets Management**
* **Production/Staging:** ห้ามใส่ Secrets (Password, Keys) ใน `docker-compose.yml` หลัก
* **Development:** ให้สร้างไฟล์ `docker-compose.override.yml` (เพิ่มใน `.gitignore`) เพื่อ Inject ตัวแปร Environment ที่เป็นความลับ
* **Validation:** ใช้ `joi` หรือ `zod` ในการ Validate Environment Variables ตอน Start App หากขาดตัวแปรสำคัญให้ Throw Error ทันที
### **2.3 Idempotency (ความสามารถในการทำซ้ำได้)**
* สำหรับการทำงานที่สำคัญ (Create Document, Approve, Transactional) **ต้อง** ออกแบบให้เป็น Idempotent
* Client **ต้อง** ส่ง Header `Idempotency-Key` (UUID) มากับ Request
* Server **ต้อง** ตรวจสอบว่า Key นี้เคยถูกประมวลผลสำเร็จไปแล้วหรือไม่ ถ้าใช่ ให้คืนค่าเดิมโดยไม่ทำซ้ำ
### **2.4 ข้อตกลงในการตั้งชื่อ (Naming Conventions)**
| Entity (สิ่งที่ตั้งชื่อ) | Convention (รูปแบบ) | Example (ตัวอย่าง) |
| :-------------------- | :----------------- | :--------------------------------- |
| Classes | PascalCase | UserService |
| Property | snake_case | user_id |
| Variables & Functions | camelCase | getUserInfo |
| Files & Folders | kebab-case | user-service.ts |
| Environment Variables | UPPERCASE | DATABASE_URL |
| Booleans | Verb + Noun | isActive, canDelete, hasPermission |
ใช้คำเต็ม — ไม่ใช้อักษรย่อ — ยกเว้นคำมาตรฐาน (เช่น API, URL, req, res, err, ctx)
### 🧩**2.5 ฟังก์ชัน (Functions)**
* เขียนฟังก์ชันให้สั้น และทำ **หน้าที่เพียงอย่างเดียว** (single-purpose) (\< 20 บรรทัด)
* ใช้ **early returns** เพื่อลดการซ้อน (nesting) ของโค้ด
* ใช้ **map**, **filter**, **reduce** แทนการใช้ loops เมื่อเหมาะสม
* ควรใช้ **arrow functions** สำหรับตรรกะสั้นๆ, และใช้ **named functions** ในกรณีอื่น
* ใช้ **default parameters** แทนการตรวจสอบค่า null
* จัดกลุ่มพารามิเตอร์หลายตัวให้เป็นอ็อบเจกต์เดียว (RO-RO pattern)
* ส่งค่ากลับ (Return) เป็นอ็อบเจกต์ที่มีไทป์กำหนด (typed objects) ไม่ใช่ค่าพื้นฐาน (primitives)
* รักษาระดับของสิ่งที่เป็นนามธรรม (abstraction level) ให้เป็นระดับเดียวในแต่ละฟังก์ชัน
### 🧱**2.6 การจัดการข้อมูล (Data Handling)**
* ห่อหุ้มข้อมูล (Encapsulate) ในไทป์แบบผสม (composite types)
* ใช้ **immutability** (การไม่เปลี่ยนแปลงค่า) ด้วย readonly และ as const
* ทำการตรวจสอบความถูกต้องของข้อมูล (Validations) ในคลาสหรือ DTOs ไม่ใช่ภายในฟังก์ชันทางธุรกิจ
* ตรวจสอบความถูกต้องของข้อมูลโดยใช้ DTOs ที่มีไทป์กำหนดเสมอ
### 🧰**2.7 คลาส (Classes)**
* ปฏิบัติตามหลักการ **SOLID**
* ควรใช้ **composition มากกว่า inheritance** (Prefer composition over inheritance)
* กำหนด **interfaces** สำหรับสัญญา (contracts)
* ให้คลาสมุ่งเน้นการทำงานเฉพาะอย่างและมีขนาดเล็ก (\< 200 บรรทัด, \< 10 เมธอด, \< 10 properties)
### 🚨**2.8 การจัดการข้อผิดพลาด (Error Handling)**
* ใช้ Exceptions สำหรับข้อผิดพลาดที่ไม่คาดคิด
* ดักจับ (Catch) ข้อผิดพลาดเพื่อแก้ไขหรือเพิ่มบริบท (context) เท่านั้น; หากไม่เช่นนั้น ให้ใช้ global error handlers
* ระบุข้อความข้อผิดพลาด (error messages) ที่มีความหมายเสมอ
### 🧪**2.9 การทดสอบ (ทั่วไป) (Testing (General))**
* ใช้รูปแบบ **Arrange–Act–Assert**
* ใช้ชื่อตัวแปรในการทดสอบที่สื่อความหมาย (inputData, expectedOutput)
* เขียน **unit tests** สำหรับ public methods ทั้งหมด
* จำลอง (Mock) การพึ่งพาภายนอก (external dependencies)
* เพิ่ม **acceptance tests** ต่อโมดูลโดยใช้รูปแบบ Given–When-Then
### **Testing Strategy โดยละเอียด**
* **Test Pyramid Structure**
/\
/ \ E2E Tests (10%)
/____\ Integration Tests (20%)
/ \ Unit Tests (70%)
/________\
* **Testing Tools Stack**
```typescript
// Backend Testing Stack
const backendTesting = {
unit: ['Jest', 'ts-jest', '@nestjs/testing'],
integration: ['Supertest', 'Testcontainers', 'Jest'],
e2e: ['Supertest', 'Jest', 'Database Seeds'],
security: ['Jest', 'Custom Security Test Helpers'],
performance: ['Jest', 'autocannon', 'artillery']
};
// Frontend Testing Stack
const frontendTesting = {
unit: ['Vitest', 'React Testing Library'],
integration: ['React Testing Library', 'MSW'],
e2e: ['Playwright', 'Jest'],
visual: ['Playwright', 'Loki']
};
```
* **Test Data Management**
```typescript
// Test Data Factories
interface TestDataFactory {
createUser(overrides?: Partial<User>): User;
createCorrespondence(overrides?: Partial<Correspondence>): Correspondence;
createRoutingTemplate(overrides?: Partial<RoutingTemplate>): RoutingTemplate;
}
// Test Scenarios
const testScenarios = {
happyPath: 'Normal workflow execution',
edgeCases: 'Boundary conditions and limits',
errorConditions: 'Error handling and recovery',
security: 'Authentication and authorization',
performance: 'Load and stress conditions'
};
```
## 🏗️ **3. แบ็กเอนด์ (NestJS) - Implementation Details**
### **3.1 หลักการ**
* **สถาปัตยกรรมแบบโมดูลาร์ (Modular architecture)**:
* หนึ่งโมดูลต่อหนึ่งโดเมน
* โครงสร้างแบบ Controller → Service → Repository (Model)
* API-First: มุ่งเน้นการสร้าง API ที่มีคุณภาพสูง มีเอกสารประกอบ (Swagger) ที่ชัดเจนสำหรับ Frontend Team
* DTOs ที่ตรวจสอบความถูกต้องด้วย **class-validator**
* ใช้ **MikroORM** (หรือ TypeORM/Prisma) สำหรับการคงอยู่ของข้อมูล (persistence) ซึ่งสอดคล้องกับสคีมา MariaDB
* ห่อหุ้มโค้ดที่ใช้ซ้ำได้ไว้ใน **common module** (@app/common):
* Configs, decorators, DTOs, guards, interceptors, notifications, shared services, types, validators
### **3.2 Database & Data Modeling (MariaDB + TypeORM)**
#### **3.2.1 Optimistic Locking & Versioning**
เพื่อป้องกัน Race Condition ในการแก้ไขข้อมูลพร้อมกัน (โดยเฉพาะการรันเลขที่เอกสาร) ให้เพิ่ม Column `@VersionColumn()` ใน Entity ที่สำคัญ
```typescript
@Entity()
export class DocumentCounter {
// ... fields
@Column()
last_number: number;
@VersionColumn() // เพิ่ม Versioning
version: number;
}
```
#### **3.2.2 Virtual Columns for JSON Performance**
เนื่องจากเราใช้ MariaDB 10.11 และมีการเก็บข้อมูล JSON (Details) ให้ใช้ **Generated Columns (Virtual)** สำหรับ Field ที่ต้อง Search/Sort บ่อยๆ และทำ Index บน Virtual Column นั้น
```sql
-- ตัวอย่าง SQL Migration
ALTER TABLE correspondence_revisions
ADD COLUMN ref_project_id INT GENERATED ALWAYS AS (JSON_UNQUOTE(JSON_EXTRACT(details, '$.projectId'))) VIRTUAL;
CREATE INDEX idx_ref_project_id ON correspondence_revisions(ref_project_id);
```
#### **3.2.3 Partitioning Strategy**
สำหรับตาราง `audit_logs` และ `notifications` ให้เตรียมออกแบบ Entity ให้รองรับ Partitioning (เช่น แยกตามปี) โดยใช้ Raw SQL Migration ในการสร้างตาราง
### **3.3 File Storage Service (Two-Phase Storage)**
ปรับปรุง Service จัดการไฟล์ให้รองรับ Transactional Integrity
1. **Upload (Phase 1):**
* รับไฟล์ → Scan Virus (ClamAV) → Save ลงโฟลเดอร์ `temp/`
* Return `temp_id` และ Metadata กลับไปให้ Client
2. **Commit (Phase 2):**
* เมื่อ Business Logic (เช่น Create Correspondence) ทำงานสำเร็จ
* Service จะย้ายไฟล์จาก `temp/` ไปยัง `permanent/{YYYY}/{MM}/`
* Update path ใน Database
* ทั้งหมดนี้ต้องอยู่ภายใต้ Database Transaction เดียวกัน (ถ้า DB Fail, ไฟล์จะค้างที่ Temp และถูกลบโดย Cron Job)
### **3.4 Document Numbering (Double-Lock Mechanism)**
การออกเลขที่เอกสารต้องใช้กลไกความปลอดภัย 2 ชั้น:
1. **Layer 1 (Redis Lock):** ใช้ `redlock` เพื่อ Block ไม่ให้ Process อื่นเข้ามายุ่งกับ Counter ของ Project/Type นั้นๆ ชั่วคราว
2. **Layer 2 (Optimistic Lock):** ตอน Update Database ให้เช็ค `version` ถ้า version เปลี่ยน (แสดงว่า Redis Lock หลุดหรือมีคนแทรก) ให้ Throw Error และ Retry ใหม่
### **3.5 Unified Workflow Engine**
ห้ามแยก Logic ระหว่าง `CorrespondenceRouting` และ `RfaWorkflow` ออกจากกันเด็ดขาด ให้สร้าง `WorkflowEngineService` ที่เป็น Generic:
* **Input:** `currentState`, `action`, `rules (Guard)`
* **Output:** `nextState`, `assignee`
* รองรับทั้ง Linear Flow (Routing) และ Complex Flow (RFA) ผ่าน Configuration
### **3.6 ฟังก์ชันหลัก (Core Functionalities)**
* Global **filters** สำหรับการจัดการ exception
* **Middlewares** สำหรับการจัดการ request
* **Guards** สำหรับการอนุญาต (permissions) และ RBAC
* **Interceptors** สำหรับการแปลงข้อมูล response และการบันทึก log
### **3.7 ข้อจำกัดในการ Deploy (QNAP Container Station)**
* **ห้ามใช้ไฟล์ .env** ในการตั้งค่า Environment Variables [cite: 2.1]
* การตั้งค่าทั้งหมด (เช่น Database connection string, JWT secret) **จะต้องถูกกำหนดผ่าน Environment Variable ใน docker-compose.yml โดยตรง** [cite: 6.5] ซึ่งจะจัดการผ่าน UI ของ QNAP Container Station [cite: 2.1]
### **3.8 ข้อจำกัดด้านความปลอดภัย (Security Constraints):**
* **File Upload Security:** ต้องมี virus scanning (ClamAV), file type validation (white-list), และ file size limits (50MB)
* **Input Validation:** ต้องป้องกัน OWASP Top 10 vulnerabilities (SQL Injection, XSS, CSRF)
* **Rate Limiting:** ต้อง implement rate limiting ตาม strategy ที่กำหนด
* **Secrets Management:** ต้องมี mechanism สำหรับจัดการ sensitive secrets อย่างปลอดภัย แม้จะใช้ docker-compose.yml
### **3.9 โครงสร้างโมดูลตามโดเมน (Domain-Driven Module Structure)**
เพื่อให้สอดคล้องกับสคีมา SQL (LCBP3-DMS) เราจะใช้โครงสร้างโมดูลแบบ **Domain-Driven (แบ่งตามขอบเขตธุรกิจ)** แทนการแบ่งตามฟังก์ชัน:
#### 3.9.1 **CommonModule:**
* เก็บ Services ที่ใช้ร่วมกัน เช่น DatabaseModule, FileStorageService (จัดการไฟล์ใน QNAP), AuditLogService, NotificationService
* จัดการ audit_logs
* NotificationService ต้องรองรับ Triggers ที่ระบุใน Requirement 6.7 [cite: 6.7]
#### 3.9.2 **AuthModule:**
* จัดการะการยืนยันตัวตน (JWT, Guards)
* **(สำคัญ)** ต้องรับผิดชอบการตรวจสอบสิทธิ์ **4 ระดับ** [cite: 4.2]: สิทธิ์ระดับระบบ (Global Role), สิทธิ์ระดับองกรณ์ (Organization Role), สิทธิ์ระดับโปรเจกต์ (Project Role), และ สิทธิ์ระดับสัญญา (Contract Role)
* **(สำคัญ)** ต้องมี API สำหรับ **Admin Panel** เพื่อ:
* สร้างและจัดการ Role และการจับคู่ Permission แบบไดนามิก [cite: 4.3]
* ให้ Superadmin สร้าง Organizations และกำหนด Org Admin ได้ [cite: 4.6]
* ให้ Superadmin/Admin จัดการ document_number_formats (รูปแบบเลขที่เอกสาร), document_number_counters (Running Number) [cite: 3.10]
#### 3.9.3 **UserModule:**
* จัดการ users, roles, permissions, global_default_roles, role_permissions, user_roles, user_project_roles
* **(สำคัญ)** ต้องมี API สำหรับ **Admin Panel** เพื่อ:
* สร้างและจัดการ Role และการจับคู่ Permission แบบไดนามิก [cite: 4.3]
#### 3.9.4 **ProjectModule:**
* จัดการ projects, organizations, contracts, project_parties, contract_parties
#### 3.9.5 **MasterModule:**
* จัดการ master data (correspondence_types, rfa_types, rfa_status_codes, rfa_approve_codes, circulation_status_codes, correspondence_types, correspondence_status, tags) [cite: 4.5]
#### 3.9.6 **CorrespondenceModule (โมดูลศูนย์กลาง):**
* จัดการ correspondences, correspondence_revisions, correspondence_tags
* **(สำคัญ)** Service นี้ต้อง Inject DocumentNumberingService เพื่อขอเลขที่เอกสารใหม่ก่อนการสร้าง
* **(สำคัญ)** ตรรกะการสร้าง/อัปเดต Revision จะอยู่ใน Service นี้
* จัดการ correspondence_attachments (ตารางเชื่อมไฟล์แนบ)
* รับผิดชอบ Routing **Correspondence Routing** (correspondence_routings, correspondence_routing_template_steps, correspondence_routing_templates, correspondence_status_transitions) สำหรับการส่งต่อเอกสารทั่วไประหว่างองค์กร
#### 3.9.7 **RfaModule:**
* จัดการ rfas, rfa_revisions, rfa_items
* รับผิดชอบเวิร์กโฟลว์ **"RFA Workflows"** (rfa_workflows, rfa_workflow_templates, rfa_workflow_template_steps, rfa_status_transitions) สำหรับการอนุมัติเอกสารทางเทคนิค
#### 3.9.8 **DrawingModule:**
* จัดการ shop_drawings, shop_drawing_revisions, contract_drawings, contract_drawing_volumes, contract_drawing_cats, contract_drawing_sub_cats, shop_drawing_main_categories, shop_drawing_sub_categories, contract_drawing_subcat_cat_maps, shop_drawing_revision_contract_refs
* จัดการ shop_drawing_revision_attachments และ contract_drawing_attachments(ตารางเชื่อมไฟล์แนบ)
#### 3.9.9 **CirculationModule:**
* จัดการ circulations, circulation_templates, circulation_assignees
* จัดการ circulation_attachments (ตารางเชื่อมไฟล์แนบ)
* รับผิดชอบเวิร์กโฟลว์ **"Circulations"** (circulation_status_transitions, circulation_template_assignees, circulation_assignees, circulation_recipients, circulation_actions, circulation_action_documents)สำหรับการเวียนเอกสาร **ภายในองค์กร**
#### 3.9.10 **TransmittalModule:**
* จัดการ transmittals และ transmittal_items
#### 3.9.11 **SearchModule:**
* ให้บริการค้นหาขั้นสูง (Advanced Search) [cite: 6.2] โดยใช้ **Elasticsearch** เพื่อรองรับการค้นหาแบบ Full-text จากชื่อเรื่อง, รายละเอียด, เลขที่เอกสาร, ประเภท, วันที่, และ Tags
* ระบบจะใช้ Elasticsearch Engine ในการจัดทำดัชนีเพื่อการค้นหาข้อมูลเชิงลึกจากเนื้อหาของเอกสาร โดยข้อมูลจะถูกส่งไปทำดัชนีจาก Backend (NestJS) ทุกครั้งที่มีการสร้างหรือแก้ไขเอกสาร
#### 3.9.12 **DocumentNumberingModule:**
* **สถานะ:** เป็น Module ภายใน (Internal Module) ไม่เปิด API สู่ภายนอก
* **หน้าที่:** ให้บริการ DocumentNumberingService ที่ Module อื่น (เช่น CorrespondenceModule) จะ Inject ไปใช้งาน
* **ตรรกะ:** รับผิดชอบการสร้างเลขที่เอกสารโดยใช้ **Redis distributed locking** แทน stored procedure
* **Features:**
* Application-level locking เพื่อป้องกัน race condition
* Retry mechanism ด้วย exponential backoff
* Fallback mechanism เมื่อการขอเลขล้มเหลว
* Audit log ทุกครั้งที่มีการ generate เลขที่เอกสารใหม่
#### 3.9.13 **CorrespondenceRoutingModule:**
* **สถานะ:** โมดูลหลักสำหรับจัดการการส่งต่อเอกสาร
* **หน้าที่:** จัดการแม่แบบการส่งต่อและการส่งต่อจริง
* **Entities:**
* CorrespondenceRoutingTemplate
* CorrespondenceRoutingTemplateStep
* CorrespondenceRouting
* **Features:**
* สร้างและจัดการแม่แบบการส่งต่อ
* ดำเนินการส่งต่อเอกสารตามแม่แบบ
* ติดตามสถานะการส่งต่อ
* คำนวณวันครบกำหนดอัตโนมัติ
* ส่งการแจ้งเตือนเมื่อมีการส่งต่อใหม่
#### 3.9.14 **WorkflowEngineModule:**
* **สถานะ:** Internal Module สำหรับจัดการ workflow logic
* **หน้าที่:** ประมวลผล state transitions และ business rules
* **Features:**
* State machine สำหรับสถานะเอกสาร
* Validation rules สำหรับการเปลี่ยนสถานะ
* Automatic status updates
* Deadline management และ escalation
#### 3.9.15 **JsonSchemaModule:**
* **สถานะ:** Internal Module สำหรับจัดการ JSON schemas
* **หน้าที่:** Validate, transform, และ manage JSON data structures
* **Features:**
* JSON schema validation ด้วย AJV
* Schema versioning และ migration
* Dynamic schema generation
* Data transformation และ sanitization
#### 3.9.16 **DetailsService:**
* **สถานะ:** Shared Service สำหรับจัดการ details fields
* **หน้าที่:** Centralized service สำหรับ JSON details operations
* **Methods:**
* validateDetails(type: string, data: any): ValidationResult
* transformDetails(input: any, targetVersion: string): any
* sanitizeDetails(data: any): any
* getDefaultDetails(type: string): any
### **3.10 สถาปัตยกรรมระบบ (System Architecture)**
โครงสร้างโมดูล (Module Structure)
```bash
📁 src
├── 📄 app.module.ts
├── 📄 main.ts
├── 📁 common # @app/common (โมดูลส่วนกลาง)
│ ├── 📁 auth # AuthModule (JWT, Guards)
│ ├── 📁 config # Configuration
│ ├── 📁 decorators # Custom Decorators (เช่น @RequirePermission)
│ ├── 📁 entities # Shared Entities (User, Role, Permission)
│ ├── 📁 exceptions # Global Exception Filters
│ ├── 📁 file-storage # FileStorageService (Virus Scanning, Security)
│ ├── 📁 guards # Custom Guards (RBAC Guard, RateLimitGuard)
│ ├── 📁 interceptors # Interceptors (Audit Log, Transform, Performance)
│ ├── 📁 resilience # Circuit Breaker, Retry Patterns
│ └── 📁 services # Shared Services (NotificationService, CachingService)
├── 📁 modules
│ ├── 📁 user # UserModule (จัดการ Users, Roles, Permissions)
│ ├── 📁 project # ProjectModule (จัดการ Projects, Organizations, Contracts)
│ ├── 📁 correspondence # CorrespondenceModule (จัดการเอกสารโต้ตอบ)
│ ├── 📁 rfa # RfaModule (จัดการเอกสารขออนุมัติ)
│ ├── 📁 drawing # DrawingModule (จัดการแบบแปลน)
│ ├── 📁 circulation # CirculationModule (จัดการใบเวียน)
│ ├── 📁 transmittal # TransmittalModule (จัดการเอกสารนำส่ง)
│ ├── 📁 search # SearchModule (ค้นหาขั้นสูงด้วย Elasticsearch)
│ ├── 📁 monitoring # MonitoringModule (Metrics, Health Checks)
│ └── 📁 document-numbering # DocumentNumberingModule (Internal Module)
└── 📁 database # Database Migration & Seeding Scripts
```
### **3.11 กลยุทธ์ความทนทานและการจัดการข้อผิดพลาด (Resilience & Error Handling Strategy)**
* **Circuit Breaker Pattern:** ใช้สำหรับ external service calls (Email, LINE, Elasticsearch)
* **Retry Mechanism:** ด้วย exponential backoff สำหรับ transient failures
* **Fallback Strategies:** Graceful degradation เมื่อบริการภายนอกล้มเหลว
* **Error Handling:** Error messages ต้องไม่เปิดเผยข้อมูล sensitive
* **Monitoring:** Centralized error monitoring และ alerting system
### **3.12 FileStorageService (ปรับปรุงใหม่):**
* **Virus Scanning:** Integrate ClamAV สำหรับ scan ไฟล์ที่อัปโหลดทั้งหมด
* **File Type Validation:** ใช้ white-list approach (PDF, DWG, DOCX, XLSX, ZIP)
* **File Size Limits:** 50MB ต่อไฟล์
* **Security Measures:**
* เก็บไฟล์นอก web root
* Download ผ่าน authenticated endpoint เท่านั้น
* Download links มี expiration time (24 ชั่วโมง)
* File integrity checks (checksum)
* Access control checks ก่อนดาวน์โหลด
### **3.13 เเทคโนโลยีที่ใช้ (Technology Stack)**
| ส่วน | Library/Tool | หมายเหตุ |
| ----------------------- | ---------------------------------------------------- | -------------------------------------- |
| **Framework** | `@nestjs/core`, `@nestjs/common` | Core Framework |
| **Language** | `TypeScript` | ใช้ TypeScript ทั้งระบบ |
| **Database** | `MariaDB 10.11` | ฐานข้อมูลหลัก |
| **ORM** | `@nestjs/typeorm`, `typeorm` | 🗃️จัดการการเชื่อมต่อและ Query ฐานข้อมูล |
| **Validation** | `class-validator`, `class-transformer` | 📦ตรวจสอบและแปลงข้อมูลใน DTO |
| **Auth** | `@nestjs/jwt`, `@nestjs/passport`, `passport-jwt` | 🔐การยืนยันตัวตนด้วย JWT |
| **Authorization** | `casl` | 🔐จัดการสิทธิ์แบบ RBAC |
| **File Upload** | `multer` | 📁จัดการการอัปโหลดไฟล์ |
| **Search** | `@nestjs/elasticsearch` | 🔍สำหรับการค้นหาขั้นสูง |
| **Notification** | `nodemailer` | 📬ส่งอีเมลแจ้งเตือน |
| **Scheduling** | `@nestjs/schedule` | 📬สำหรับ Cron Jobs (เช่น แจ้งเตือน Deadline) |
| **Logging** | `winston` | 📊บันทึก Log ที่มีประสิทธิภาพ |
| **Testing** | `@nestjs/testing`, `jest`, `supertest` | 🧪ทดสอบ Unit, Integration และ E2E |
| **Documentation** | `@nestjs/swagger` | 🌐สร้าง API Documentation อัตโนมัติ |
| **Security** | `helmet`, `rate-limiter-flexible` | 🛡️เพิ่มความปลอดภัยให้ API |
| **Resilience** | `@nestjs/circuit-breaker` | 🔄 Circuit breaker pattern |
| **Caching** | `@nestjs/cache-manager`, `cache-manager-redis-store` | 💾 Distributed caching |
| **Security** | `helmet`, `csurf`, `rate-limiter-flexible` | 🛡️ Security enhancements |
| **Validation** | `class-validator`, `class-transformer` | ✅ Input validation |
| **Monitoring** | `@nestjs/monitoring`, `winston` | 📊 Application monitoring |
| **File Processing** | `clamscan` | 🦠 Virus scanning |
| **Cryptography** | `bcrypt`, `crypto` | 🔐 Password hashing และ checksums |
| **JSON Validation** | `ajv`, `ajv-formats` | 🎯 JSON schema validation |
| **JSON Processing** | `jsonpath`, `json-schema-ref-parser` | 🔧 JSON manipulation |
| **Data Transformation** | `class-transformer` | 🔄 Object transformation |
| **Compression** | `compression` | 📦 JSON compression |
### **3.14 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
### **3.15 Performance Testing:**
* **Load Testing:** ทดสอบด้วย realistic workloads
* **Stress Testing:** หา breaking points ของระบบ
* **Endurance Testing:** ทดสอบการทำงานต่อเนื่องเป็นเวลานาน
### 🗄️**3.16 Backend State Management**
Backend (NestJS) ควรเป็น **Stateless** (ไม่เก็บสถานะ) "State" ทั้งหมดจะถูกจัดเก็บใน MariaDB
* **Request-Scoped State (สถานะภายใน Request เดียว):**
* **ปัญหา:** จะส่งต่อข้อมูล (เช่น User ที่ล็อกอิน) ระหว่าง Guard และ Service ใน Request เดียวกันได้อย่างไร?
* **วิธีแก้:** ใช้ **Request-Scoped Providers** ของ NestJS (เช่น AuthContextService) เพื่อเก็บข้อมูล User ปัจจุบันที่ได้จาก AuthGuard และให้ Service อื่น Inject ไปใช้
* **Application-Scoped State (การ Caching):**
* **ปัญหา:** ข้อมูล Master (เช่น roles, permissions, organizations) ถูกเรียกใช้บ่อย
* **วิธีแก้:** ใช้ **Caching** (เช่น @nestjs/cache-manager) เพื่อ Caching ข้อมูลเหล่านี้ และลดภาระ Database
### **3.17 Caching Strategy (ตามข้อ 6.4.2):**
* **Master Data Cache:** Roles, Permissions, Organizations (TTL: 1 hour)
* **User Session Cache:** User permissions และ profile (TTL: 30 minutes)
* **Search Result Cache:** Frequently searched queries (TTL: 15 minutes)
* **File Metadata Cache:** Attachment metadata (TTL: 1 hour)
* **Cache Invalidation:** Clear cache on update/delete operations
### **3.18 การไหลของข้อมูล (Data Flow)**
#### **3.18.1 Main Flow:**
1. Request: ผ่าน Nginx Proxy Manager -> NestJS Controller
2. **Rate Limiting:** RateLimitGuard ตรวจสอบ request limits
3. **Input Validation:** Validation Pipe ตรวจสอบและ sanitize inputs
4. Authentication: JWT Guard ตรวจสอบ Token และดึงข้อมูล User
5. Authorization: RBAC Guard ตรวจสอบสิทธิ์
6. **Security Checks:** Virus scanning (สำหรับ file upload), XSS protection
7. Business Logic: Service Layer ประมวลผลตรรกะทางธุรกิจ
8. **Resilience:** Circuit breaker และ retry logic สำหรับ external calls
9. Data Access: Repository Layer ติดต่อกับฐานข้อมูล
10. **Caching:** Cache frequently accessed data
11. **Audit Log:** บันทึกการกระทำสำคัญ
12. Response: ส่งกลับไปยัง Frontend
#### **3.18.2 Workflow Data Flow:**
1. User สร้างเอกสาร → เลือก routing template
2. System สร้าง routing instances ตาม template
3. สำหรับแต่ละ routing step:
- กำหนด due date (จาก expected_days)
- ส่ง notification ไปยังองค์กรผู้รับ
- อัพเดทสถานะเป็น SENT
4. เมื่อองค์กรผู้รับดำเนินการ:
- อัพเดทสถานะเป็น ACTIONED/FORWARDED/REPLIED
- บันทึก processed_by และ processed_at
- ส่ง notification ไปยังขั้นตอนต่อไป (ถ้ามี)
5. เมื่อครบทุกขั้นตอน → อัพเดทสถานะเอกสารเป็น COMPLETED
#### **3.18.3 JSON Details Processing Flow:**
1. **Receive Request** → Get JSON data from client
2. **Schema Validation** → Validate against predefined schema
3. **Data Sanitization** → Sanitize and transform data
4. **Version Check** → Handle schema version compatibility
5. **Storage** → Store validated JSON in database
6. **Retrieval** → Retrieve and transform on demand
### 📊**3.19 Monitoring & Observability (ตามข้อ 6.8)**
#### **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
#### **Performance Targets:**
* API Response Time: < 200ms (90th percentile)
* Search Query Performance: < 500ms
* File Upload Performance: < 30 seconds สำหรับไฟล์ 50MB
* Cache Hit Ratio: > 80%
## 🖥️ **4. ฟรอนต์เอนด์ (Next.js) - Implementation Details**
**โปรไฟล์นักพัฒนา (Developer Profile:** วิศวกร TypeScript + React/NextJS ระดับ Senior
เชี่ยวชาญ TailwindCSS, Shadcn/UI, และ Radix สำหรับการพัฒนา UI
### **4.1 State Management & Offline Support**
#### **4.1.1 Auto-Save Drafts**
ใช้ `zustand` ร่วมกับ middleware `persist` (ลง LocalStorage) สำหรับฟอร์มที่มีขนาดใหญ่ (RFA, Correspondence) เพื่อป้องกันข้อมูลหายเมื่อเน็ตหลุด
```typescript
// lib/stores/draft-store.ts
export const useDraftStore = create(
persist(
(set) => ({
drafts: {},
saveDraft: (key, data) => set((state) => ({ drafts: { ...state.drafts, [key]: data } })),
clearDraft: (key) => set((state) => {
const newDrafts = { ...state.drafts };
delete newDrafts[key];
return { drafts: newDrafts };
}),
}),
{ name: 'form-drafts' }
)
);
```
### **4.2 Dynamic Form Generator**
เพื่อรองรับ JSON Schema หลากหลายรูปแบบ ให้สร้าง Component กลางที่รับ Schema แล้ว Gen Form ออกมา (ลดการแก้ Code บ่อยๆ)
* **Libraries:** แนะนำ `react-jsonschema-form` หรือสร้าง Wrapper บน `react-hook-form` ที่ Recursively render field ตาม Type
* **Validation:** ใช้ `ajv` ที่ฝั่ง Client เพื่อ Validate JSON ก่อน Submit
### **4.3 Mobile Responsiveness (Card View)**
ตารางข้อมูล (`DataTable`) ต้องมีความฉลาดในการแสดงผล:
* **Desktop:** แสดงเป็น Table ปกติ
* **Mobile:** แปลงเป็น **Card View** โดยอัตโนมัติ (ซ่อน Header, แสดง Label คู่ Value ในแต่ละ Card)
```tsx
// components/ui/responsive-table.tsx
<div className="hidden md:block">
<Table>{/* Desktop View */}</Table>
</div>
<div className="md:hidden space-y-4">
{data.map((item) => (
<Card key={item.id}>
{/* Mobile View: Render cells as list items */}
</Card>
))}
</div>
```
### **4.4 Optimistic Updates**
ใช้ความสามารถของ **TanStack Query** (`onMutate`) เพื่ออัปเดต UI ทันที (เช่น เปลี่ยนสถานะจาก "รออ่าน" เป็น "อ่านแล้ว") แล้วค่อยส่ง Request ไป Server ถ้า Failed ค่อย Rollback
### **4.5 แนวทางการพัฒนาโค้ด (Code Implementation Guidelines)**
* ใช้ **early returns** เพื่อความชัดเจน
* ใช้คลาสของ **TailwindCSS** ในการกำหนดสไตล์เสมอ
* ควรใช้ class: syntax แบบมีเงื่อนไข (หรือ utility clsx) มากกว่าการใช้ ternary operators ใน class strings
* ใช้ **const arrow functions** สำหรับ components และ handlers
* Event handlers ให้ขึ้นต้นด้วย handle... (เช่น handleClick, handleSubmit)
* รวมแอตทริบิวต์สำหรับการเข้าถึง (accessibility) ด้วย:
tabIndex="0", aria-label, onKeyDown, ฯลฯ
* ตรวจสอบให้แน่ใจว่าโค้ดทั้งหมด **สมบูรณ์**, **ผ่านการทดสอบ**, และ **ไม่ซ้ำซ้อน (DRY)**
* ต้อง import โมดูลที่จำเป็นต้องใช้อย่างชัดเจนเสมอ
### **4.6 UI/UX ด้วย React**
* ใช้ **semantic HTML**
* ใช้คลาสของ **Tailwind** ที่รองรับ responsive (sm:, md:, lg:)
* รักษาลำดับชั้นของการมองเห็น (visual hierarchy) ด้วยการใช้ typography และ spacing
* ใช้ **Shadcn** components (Button, Input, Card, ฯลฯ) เพื่อ UI ที่สอดคล้องกัน
* ทำให้ components มีขนาดเล็กและมุ่งเน้นการทำงานเฉพาะอย่าง
* ใช้ utility classes สำหรับการจัดสไตล์อย่างรวดเร็ว (spacing, colors, text, ฯลฯ)
* ตรวจสอบให้แน่ใจว่าสอดคล้องกับ **ARIA** และใช้ semantic markup
### **4.7 การตรวจสอบฟอร์มและข้อผิดพลาด (Form Validation & Errors)**
* ใช้ไลบรารีฝั่ง client เช่น zod และ react-hook-form
* แสดงข้อผิดพลาดด้วย **alert components** หรือข้อความ inline
* ต้องมี labels, placeholders, และข้อความ feedback
### **🧪4.8 Frontend Testing**
เราจะใช้ **React Testing Library (RTL)** สำหรับการทดสอบ Component และ **Playwright** สำหรับ E2E:
* **Unit Tests (การทดสอบหน่วยย่อย):**
* **เครื่องมือ:** Vitest + RTL
* **เป้าหมาย:** ทดสอบ Component ขนาดเล็ก (เช่น Buttons, Inputs) หรือ Utility functions
* **Integration Tests (การทดสอบการบูรณาการ):**
* **เครื่องมือ:** RTL + **Mock Service Worker (MSW)**
* **เป้าหมาย:** ทดสอบว่า Component หรือ Page ทำงานกับ API (ที่จำลองขึ้น) ได้ถูกต้อง
* **เทคนิค:** ใช้ MSW เพื่อจำลอง NestJS API และทดสอบว่า Component แสดงผลข้อมูลจำลองได้ถูกต้องหรือไม่ (เช่น ทดสอบหน้า Dashboard [cite: 5.3] ที่ดึงข้อมูลจาก v_user_tasks)
* **E2E (End-to-End) Tests:**
* **เครื่องมือ:** **Playwright**
* **เป้าหมาย:** ทดสอบ User Flow ทั้งระบบโดยอัตโนมัติ (เช่น ล็อกอิน -> สร้าง RFA -> ตรวจสอบ Workflow Visualization [cite: 5.6])
### **🗄️4.9 Frontend State Management**
สำหรับ Next.js App Router เราจะแบ่ง State เป็น 4 ระดับ:
1. **Local UI State (สถานะ UI ชั่วคราว):**
* **เครื่องมือ:** useState, useReducer
* **ใช้เมื่อ:** จัดการสถานะเล็กๆ ที่จบใน Component เดียว (เช่น Modal เปิด/ปิด, ค่าใน Input)
2. **Server State (สถานะข้อมูลจากเซิร์ฟเวอร์):**
* **เครื่องมือ:** **React Query (TanStack Query)** หรือ SWR
* **ใช้เมื่อ:** จัดการข้อมูลที่ดึงมาจาก NestJS API (เช่น รายการ correspondences, rfas, drawings)
* **ทำไม:** React Query เป็น "Cache" ที่จัดการ Caching, Re-fetching, และ Invalidation ให้โดยอัตโนมัติ
3. **Global Client State (สถานะส่วนกลางฝั่ง Client):**
* **เครื่องมือ:** **Zustand** (แนะนำ) หรือ Context API
* **ใช้เมื่อ:** จัดการข้อมูลที่ต้องใช้ร่วมกันทั่วทั้งแอป และ *ไม่ใช่* ข้อมูลจากเซิร์ฟเวอร์ (เช่น ข้อมูล User ที่ล็อกอิน, สิทธิ์ Permissions)
4. **Form State (สถานะของฟอร์ม):**
* **เครื่องมือ:** **React Hook Form** + **Zod**
* **ใช้เมื่อ:** จัดการฟอร์มที่ซับซ้อน (เช่น ฟอร์มสร้าง RFA, ฟอร์ม Circulation [cite: 3.7])
## 🔐 **5. Security & Access Control (Full Stack Integration)**
### **5.1 CASL Integration (Shared Ability)**
* **Backend:** ใช้ CASL กำหนด Permission Rule
* **Frontend:** ให้ดึง Rule (JSON) จาก Backend มา Load ใส่ `@casl/react` เพื่อให้ Logic การ Show/Hide ปุ่ม ตรงกัน 100%
### **5.2 Maintenance Mode**
เพิ่ม Middleware (ทั้ง NestJS และ Next.js) เพื่อตรวจสอบ Flag ใน Redis:
* ถ้า `MAINTENANCE_MODE = true`
* **API:** Return `503 Service Unavailable` (ยกเว้น Admin IP)
* **Frontend:** Redirect ไปหน้า `/maintenance`
### **5.3 Idempotency Client**
สร้าง Axios Interceptor เพื่อ Generate `Idempotency-Key` สำหรับ POST/PUT/DELETE requests ทุกครั้ง
```typescript
// lib/api/client.ts
import { v4 as uuidv4 } from 'uuid';
apiClient.interceptors.request.use((config) => {
if (['post', 'put', 'delete'].includes(config.method)) {
config.headers['Idempotency-Key'] = uuidv4();
}
return config;
});
```
### **5.4 RBAC และการควบคุมสิทธิ์ (RBAC & Permission Control)**
ใช้ Decorators เพื่อบังคับใช้สิทธิ์การเข้าถึง โดยอ้างอิงสิทธิ์จากตาราง permissions
```typescript
@RequirePermission('rfas.respond') // ต้องตรงกับ 'permission_code'
@Put(':id')
updateRFA(@Param('id') id: string) {
return this.rfaService.update(id);
}
```
#### **5.4.1 Roles (บทบาท)**
* **Superadmin**: ไม่มีข้อจำกัดใดๆ [cite: 4.3]
* **Admin**: มีสิทธิ์เต็มที่ในองค์กร [cite: 4.3]
* **Document Control**: เพิ่ม/แก้ไข/ลบ เอกสารในองค์กร [cite: 4.3]
* **Editor**: สามารถ เพิ่ม/แก้ไข เอกสารที่กำหนด [cite: 4.3]
* **Viewer**: สามารถดู เอกสาร [cite: 4.3]
#### **5.4.2 ตัวอย่าง Permissions (จากตาราง permissions)**
* rfas.view, rfas.create, rfas.respond, rfas.delete
* drawings.view, drawings.upload, drawings.delete
* corr.view, corr.manage
* transmittals.manage
* cirs.manage
* project_parties.manage
การจับคู่ระหว่าง roles และ permissions **เริ่มต้น** จะถูก seed ผ่านสคริปต์ (ดังที่เห็นในไฟล์ SQL)**อย่างไรก็ตาม AuthModule/UserModule ต้องมี API สำหรับ Admin เพื่อสร้าง Role ใหม่และกำหนดสิทธิ์ (Permissions) เพิ่มเติมได้ในภายหลัง** [cite: 4.3]
## 📊 **6. Notification & Background Jobs**
### **6.1 Digest Notification**
ห้ามส่ง Email ทันทีที่เกิด Event ให้:
1. Push Event ลง Queue (Redis/BullMQ)
2. มี Processor รอเวลา (เช่น 5 นาที) เพื่อ Group Events ที่คล้ายกัน (เช่น "คุณมีเอกสารรออนุมัติ 5 ฉบับ")
3. ส่ง Email เดียว (Digest) เพื่อลด Spam
## 🔗 **7. แนวทางการบูรณาการ Full Stack (Full Stack Integration Guidelines)**
| Aspect (แง่มุม) | Backend (NestJS) | Frontend (NextJS) | UI Layer (Tailwind/Shadcn) |
| :----------------------- | :------------------------- | :---------------------------- | :------------------------------------- |
| API | REST / GraphQL Controllers | API hooks ผ่าน fetch/axios/SWR | Components ที่รับข้อมูล |
| Validation (การตรวจสอบ) | class-validator DTOs | zod / react-hook-form | สถานะของฟอร์ม/input ใน Shadcn |
| Auth (การยืนยันตัวตน) | Guards, JWT | NextAuth / cookies | สถานะ UI ของ Auth (loading, signed in) |
| Errors (ข้อผิดพลาด) | Global filters | Toasts / modals | Alerts / ข้อความ feedback |
| Testing (การทดสอบ) | Jest (unit/e2e) | Vitest / Playwright | Visual regression |
| Styles (สไตล์) | Scoped modules (ถ้าจำเป็น) | Tailwind / Shadcn | Tailwind utilities |
| Accessibility (การเข้าถึง) | Guards + filters | ARIA attributes | Semantic HTML |
## 🗂️ **8. ข้อตกลงเฉพาะสำหรับ DMS (LCBP3-DMS)**
ส่วนนี้ขยายแนวทาง FullStackJS ทั่วไปสำหรับโปรเจกต์ **LCBP3-DMS** โดยมุ่งเน้นไปที่เวิร์กโฟลว์การอนุมัติเอกสาร (Correspondence, RFA, Drawing, Contract, Transmittal, Circulation)
### 🧾**8.1 มาตรฐาน AuditLog (AuditLog Standard)**
บันทึกการดำเนินการ CRUD และการจับคู่ทั้งหมดลงในตาราง audit_logs
| Field (ฟิลด์) | Type (จาก SQL) | Description (คำอธิบาย) |
| :----------- | :------------- | :----------------------------------------------- |
| audit_id | BIGINT | Primary Key |
| user_id | INT | ผู้ใช้ที่ดำเนินการ (FK -> users) |
| action | VARCHAR(100) | rfa.create, correspondence.update, login.success |
| entity_type | VARCHAR(50) | ชื่อตาราง/โมดูล เช่น 'rfa', 'correspondence' |
| entity_id | VARCHAR(50) | Primary ID ของระเบียนที่ได้รับผลกระทบ |
| details_json | JSON | ข้อมูลบริบท (เช่น ฟิลด์ที่มีการเปลี่ยนแปลง) |
| ip_address | VARCHAR(45) | IP address ของผู้ดำเนินการ |
| user_agent | VARCHAR(255) | User Agent ของผู้ดำเนินการ |
| created_at | TIMESTAMP | Timestamp (UTC) |
### 📂**8.2 การจัดการไฟล์ (File Handling)**
#### **8.2.1 มาตรฐานการอัปโหลดไฟล์ (File Upload Standard)**
* **Security-First Approach:** การอัปโหลดไฟล์ทั้งหมดจะถูกจัดการโดย FileStorageService ที่มี security measures ครบถ้วน
* ไฟล์จะถูกเชื่อมโยงไปยัง Entity ที่ถูกต้องผ่าน **ตารางเชื่อม (Junction Tables)** เท่านั้น:
* correspondence_attachments (เชื่อม Correspondence กับ Attachments)
* circulation_attachments (เชื่อม Circulation กับ Attachments)
* shop_drawing_revision_attachments (เชื่อม Shop Drawing Revision กับ Attachments)
* contract_drawing_attachments (เชื่อม Contract Drawing กับ Attachments)
* เส้นทางจัดเก็บไฟล์ (Upload path): อ้างอิงจาก Requirement 2.1 คือ /share/dms-data [cite: 2.1] โดย FileStorageService จะสร้างโฟลเดอร์ย่อยแบบรวมศูนย์ (เช่น /share/dms-data/uploads/{YYYY}/{MM}/[stored_filename])
* ประเภทไฟล์ที่อนุญาต: pdf, dwg, docx, xlsx, zip (ผ่าน white-list validation)
* ขนาดสูงสุด: **50 MB**
* จัดเก็บนอก webroot
* ให้บริการไฟล์ผ่าน endpoint ที่ปลอดภัย /files/:attachment_id/download
#### **8.2.2 Security Controls สำหรับ File Access:**
การเข้าถึงไฟล์ไม่ใช่การเข้าถึงโดยตรง endpoint /files/:attachment_id/download จะต้อง:
1. ค้นหาระเบียน attachment
2. ตรวจสอบว่า attachment_id นี้ เชื่อมโยงกับ Entity ใด (เช่น correspondence, circulation, shop_drawing_revision, contract_drawing) ผ่านตารางเชื่อม
3. ตรวจสอบว่าผู้ใช้มีสิทธิ์ (permission) ในการดู Entity ต้นทางนั้นๆ หรือไม่
4. ตรวจสอบ download token expiration (24 ชั่วโมง)
5. บันทึก audit log การดาวน์โหลด
### 🔟**8.3 การจัดการเลขที่เอกสาร (Document Numbering) [cite: 3.10]**
* **เป้าหมาย:** สร้างเลขที่เอกสาร (เช่น correspondence_number) โดยอัตโนมัติ ตามรูปแบบที่กำหนด
* **ตรรกะการนับ:** การนับ Running number (SEQ) จะนับแยกตาม Key: **Project + Originator Organization + Document Type + Year**
* **ตาราง SQL:**
* document_number_formats: Admin ใช้กำหนด "รูปแบบ" (Template) ของเลขที่ (เช่น {ORG_CODE}-{TYPE_CODE}-{YEAR_SHORT}-{SEQ:4}) โดยกำหนดตาม **Project** และ **Document Type** [cite: 4.5]
* document_number_counters: ระบบใช้เก็บ "ตัวนับ" ล่าสุดของ Key (Project+Org+Type+Year)
* **การทำงาน (Backend):**
* DocumentNumberingModule จะให้บริการ DocumentNumberingService
* เมื่อ CorrespondenceModule ต้องการสร้างเอกสารใหม่, มันจะเรียก documentNumberingService.generateNextNumber(...)
* Service นี้จะใช้ **Redis distributed locking** แทน stored procedure ซึ่งจะจัดการ Database Transaction และ Row Locking ภายใน Application Layer เพื่อรับประกันการป้องกัน Race Condition
* มี retry mechanism และ fallback strategies
### 📊**8.4 การรายงานและการส่งออก (Reporting & Exports)**
#### **8.4.1 วิวสำหรับการรายงาน (Reporting Views) (จาก SQL)**
การรายงานควรสร้างขึ้นจาก Views ที่กำหนดไว้ล่วงหน้าในฐานข้อมูลเป็นหลัก:
* v_current_correspondences: สำหรับ revision ปัจจุบันทั้งหมดของเอกสารที่ไม่ใช่ RFA
* v_current_rfas: สำหรับ revision ปัจจุบันทั้งหมดของ RFA และข้อมูล master
* v_contract_parties_all: สำหรับการตรวจสอบความสัมพันธ์ของ project/contract/organization
* v_user_tasks: สำหรับ Dashboard "งานของฉัน"
* v_audit_log_details: สำหรับ Activity Feed
Views เหล่านี้ทำหน้าที่เป็นแหล่งข้อมูลหลักสำหรับการรายงานฝั่งเซิร์ฟเวอร์และการส่งออกข้อมูล
#### **8.4.2 กฎการส่งออก (Export Rules)**
* Export formats: CSV, Excel, PDF.
* จัดเตรียมมุมมองสำหรับพิมพ์ (Print view).
* รวมลิงก์ไปยังต้นทาง (เช่น /rfas/:id).
## 🧮 **9. ฟรอนต์เอนด์: รูปแบบ DataTable และฟอร์ม (Frontend: DataTable & Form Patterns)**
### **9.1 DataTable (Server‑Side)**
* Endpoint: /api/{module}?page=1&pageSize=20&sort=...&filter=...
* ต้องรองรับ: การแบ่งหน้า (pagination), การเรียงลำดับ (sorting), การค้นหา (search), การกรอง (filters)
* แสดง revision ล่าสุดแบบ inline เสมอ (สำหรับ RFA/Drawing)
### **9.2 มาตรฐานฟอร์ม (Form Standards)**
* ต้องมีการใช้งาน Dropdowns แบบขึ้นต่อกัน (Dependent dropdowns) (ตามที่สคีมารองรับ):
* Project → Contract Drawing Volumes
* Contract Drawing Category → Sub-Category
* RFA (ประเภท Shop Drawing) → Shop Drawing Revisions ที่เชื่อมโยงได้
* **File Upload Security:** ต้องรองรับ **Multi-file upload (Drag-and-Drop)** [cite: 5.7] พร้อม virus scanning feedback
* **File Type Indicators:** UI ต้องอนุญาตให้ผู้ใช้กำหนดว่าไฟล์ใดเป็น **"เอกสารหลัก"** หรือ "เอกสารแนบประกอบ" [cite: 5.7] พร้อมแสดง file type icons
* **Security Feedback:** แสดง security warnings สำหรับ file types ที่เสี่ยงหรือ files ที่ fail virus scan
* ส่ง (Submit) ผ่าน API พร้อม feedback แบบ toast
### **9.3 ข้อกำหนด Component เฉพาะ (Specific UI Requirements)**
* **Dashboard - My Tasks:** ต้องพัฒนา Component ตาราง "งานของฉัน" (My Tasks)ซึ่งดึงข้อมูลงานที่ผู้ใช้ล็อกอินอยู่ต้องรับผิดชอบ (Main/Action) จาก v_user_tasks [cite: 5.3]
* **Workflow Visualization:** ต้องพัฒนา Component สำหรับแสดงผล Workflow (โดยเฉพาะ RFA)ที่แสดงขั้นตอนทั้งหมดเป็นลำดับ โดยขั้นตอนปัจจุบัน (active) เท่านั้นที่ดำเนินการได้ และขั้นตอนอื่นเป็น disabled [cite: 5.6] ต้องมีตรรกะสำหรับ Admin ในการ override หรือย้อนกลับขั้นตอนได้ [cite: 5.6]
* **Admin Panel:** ต้องมีหน้า UI สำหรับ Superadmin/Admin เพื่อจัดการข้อมูลหลัก (Master Data [cite: 4.5]), การเริ่มต้นใช้งาน (Onboarding [cite: 4.6]), และ **รูปแบบเลขที่เอกสาร (Numbering Formats [cite: 3.10])**
* **Security Dashboard:** แสดง security metrics และ audit logs สำหรับ administrators
## 🧭 **10. แดชบอร์ดและฟีดกิจกรรม (Dashboard & Activity Feed)**
### **10.1 การ์ดบนแดชบอร์ด (Dashboard Cards)**
* แสดง Correspondences, RFAs, Circulations, Shop Drawing Revision ล่าสุด
* รวมสรุป KPI (เช่น "RFAs ที่รอการอนุมัติ", "Shop Drawing ที่รอการอนุมัติ") [cite: 5.3]
* รวมลิงก์ด่วนไปยังโมดูลต่างๆ
* **Security Metrics:** แสดงจำนวน files scanned, security incidents, failed login attempts
### **10.2 ฟีดกิจกรรม (Activity Feed)**
* แสดงรายการ v_audit_log_details ล่าสุด (10 รายการ) ที่เกี่ยวข้องกับผู้ใช้
* รวม security-related activities (failed logins, permission changes)
```typescript
// ตัวอย่าง API response
[
{ user: 'editor01', action: 'Updated RFA (LCBP3-RFA-001)', time: '2025-11-04T09:30Z' },
{ user: 'system', action: 'Virus scan completed - 0 threats found', time: '2025-11-04T09:25Z' }
]
```
## 🛡️ **11. ข้อกำหนดที่ไม่ใช่ฟังก์ชันการทำงาน (Non-Functional Requirements)**
ส่วนนี้สรุปข้อกำหนด Non-Functional จาก requirements.md เพื่อให้ทีมพัฒนาทาน
* **Audit Log [cite: 6.1]:** ทุกการกระทำที่สำคัญ (C/U/D) ต้องถูกบันทึกใน audit_logs
* **Performance [cite: 6.4]:** ต้องใช้ Caching สำหรับข้อมูลที่เรียกบ่อย และใช้ Pagination
* **Security [cite: 6.5]:** ต้องมี Rate Limiting และจัดการ Secret ผ่าน docker-compose.yml (ไม่ใช่ .env)
* **File Security [cite: 3.9.6]:** ต้องมี virus scanning, file type validation, access controls
* **Resilience [cite: 6.5.3]:** ต้องมี circuit breaker, retry mechanisms, graceful degradation
* **Backup & Recovery [cite: 6.6]:** ต้องมีแผนสำรองข้อมูลทั้ง Database (MariaDB) และ File Storage (/share/dms-data) อย่างน้อยวันละ 1 ครั้ง
* **Notification Strategy [cite: 6.7]:** ระบบแจ้งเตือน (Email/Line) ต้องถูก Trigger เมื่อมีเอกสารใหม่ส่งถึง, มีการมอบหมายงานใหม่ (Circulation), หรือ (ทางเลือก) เมื่องานเสร็จ/ใกล้ถึงกำหนด
* **Monitoring [cite: 6.8]:** ต้องมี health checks, metrics collection, alerting
## ✅ **12. มาตรฐานที่นำไปใช้แล้ว (จาก SQL v1.4.0) (Implemented Standards (from SQL v1.4.0))**
ส่วนนี้ยืนยันว่าแนวทางปฏิบัติที่ดีที่สุดต่อไปนี้เป็นส่วนหนึ่งของการออกแบบฐานข้อมูลอยู่แล้ว และควรถูกนำไปใช้ประโยชน์ ไม่ใช่สร้างขึ้นใหม่
* ✅ **Soft Delete:** นำไปใช้แล้วผ่านคอลัมน์ deleted_at ในตารางสำคัญ (เช่น correspondences, rfas, project_parties) ตรรกะการดึงข้อมูลต้องกรอง deleted_at IS NULL
* ✅ **Database Indexes:** สคีมาได้มีการทำ index ไว้อย่างหนักหน่วงบน foreign keys และคอลัมน์ที่ใช้ค้นหาบ่อย (เช่น idx_rr_rfa, idx_cor_project, idx_cr_is_current) เพื่อประสิทธิภาพ
* ✅ **โครงสร้าง RBAC:** มีระบบ users, roles, permissions, user_roles, และ user_project_roles ที่ครอบคลุมอยู่แล้ว
* ✅ **Data Seeding:** ข้อมูล Master (roles, permissions, organization_roles, initial users, project parties) ถูกรวมอยู่ในสคริปต์สคีมาแล้ว
* ✅ **Application-level Locking:** ใช้ Redis distributed lock แทน stored procedure
* ✅ **File Security:** Virus scanning, file type validation, access control
* ✅ **Resilience Patterns:** Circuit breaker, retry, fallback mechanisms
* ✅ **Security Measures:** Input validation, rate limiting, security headers
* ✅ **Monitoring:** Health checks, metrics collection, distributed tracing
## 🧩 **13. การปรับปรุงที่แนะนำ (สำหรับอนาคต) (Recommended Enhancements (Future))**
* ✅ สร้าง Background job (โดยใช้ **n8n** เพื่อเชื่อมต่อกับ **Line** [cite: 2.7] และ/หรือใช้สำหรับการแจ้งเตือน RFA ที่ใกล้ถึงกำหนด due_date [cite: 6.7])
* ✅ เพิ่ม job ล้างข้อมูลเป็นระยะสำหรับ attachments ที่ไม่ถูกเชื่อมโยงกับ Entity ใดๆ เลย (ไฟล์กำพร้า)
* 🔄 **AI-Powered Document Classification:** ใช้ machine learning สำหรับ automatic document categorization
* 🔄 **Advanced Analytics:** Predictive analytics สำหรับ workflow optimization
* 🔄 **Mobile App:** Native mobile application สำหรับ field workers
* 🔄 **Blockchain Integration:** สำหรับ document integrity verification ที่ต้องการความปลอดภัยสูงสุด
## ✅ **14. Summary Checklist for Developers**
ก่อนส่ง PR (Pull Request) นักพัฒนาต้องตรวจสอบหัวข้อต่อไปนี้:
* [ ] **Security:** ไม่มี Secrets ใน Code, ใช้ `docker-compose.override.yml` แล้ว
* [ ] **Concurrency:** ใช้ Optimistic Lock ใน Entity ที่เสี่ยง Race Condition แล้ว
* [ ] **Idempotency:** API รองรับ Idempotency Key แล้ว
* [ ] **File Upload:** ใช้ Flow Two-Phase (Temp -> Perm) แล้ว
* [ ] **Mobile:** หน้าจอแสดงผลแบบ Card View บนมือถือได้ถูกต้อง
* [ ] **Performance:** สร้าง Index สำหรับ JSON Virtual Columns แล้ว (ถ้ามี)
---
## 📋 **15. Summary of Key Changes from Previous Version**
### **Security Enhancements:**
1. **File Upload Security** - Virus scanning, file type validation, access controls
2. **Input Validation** - OWASP Top 10 protection, XSS/CSRF prevention
3. **Rate Limiting** - Comprehensive rate limiting strategy
4. **Secrets Management** - Secure handling of sensitive configuration
### **Architecture Improvements:**
1. **Document Numbering** - Changed from Stored Procedure to Application-level Locking
2. **Resilience Patterns** - Circuit breaker, retry mechanisms, fallback strategies
3. **Monitoring & Observability** - Health checks, metrics, distributed tracing
4. **Caching Strategy** - Comprehensive caching with proper invalidation
### **Performance Targets :**
1. **API Response Time** - < 200ms (90th percentile)
2. **Search Performance** - < 500ms
3. **File Upload** - < 30 seconds for 50MB files
4. **Cache Hit Ratio** - > 80%
### **Operational Excellence:**
1. **Disaster Recovery** - RTO < 4 hours, RPO < 1 hour
2. **Backup Procedures** - Comprehensive backup and restoration
3. **Security Testing** - Penetration testing and security audits
4. **Performance Testing** - Load testing with realistic workloads
เอกสารนี้สะท้อนถึงความมุ่งมั่นในการสร้างระบบที่มีความปลอดภัย, มีความทนทาน, และมีประสิทธิภาพสูง พร้อมรองรับการเติบโตในอนาคตและความต้องการทางธุรกิจที่เปลี่ยนแปลงไป
**หมายเหตุ:** แนวทางนี้จะถูกทบทวนและปรับปรุงเป็นระยะตาม feedback จากทีมพัฒนาและความต้องการทางธุรกิจที่เปลี่ยนแปลงไป
## **Document Control:**
* **Document:** FullStackJS v1.4.3
* **Version:** 1.4
* **Date:** 2025-11-22
* **Author:** NAP LCBP3-DMS & Gemini
* **Status:** FINAL
* **Classification:** Internal Technical Documentation
* **Approved By:** Nattanin
---
`End of FullStackJS Guidelines v1.4.3`

975
infrastructure/Markdown/1_FullStackJS_V1_4_4.md Normal file
View File

@@ -0,0 +1,975 @@
# 📝 **Documents Management System Version 1.4.4: แนวทางการพัฒนา FullStackJS**
**สถานะ:** FINAL GUIDELINE Rev.04
**วันที่:** 2025-11-26
**อ้างอิง:** Requirements Specification v1.4.3
**Classification:** Internal Technical Documentation
## 🧠 **1. ปรัชญาทั่วไป (General Philosophy)**
แนวทางปฏิบัติที่ดีที่สุดแบบครบวงจรสำหรับการพัฒนา NestJS Backend, NextJS Frontend และ Tailwind-based UI/UX ในสภาพแวดล้อม TypeScript มุ่งเน้นที่ **"Data Integrity First"** (ความถูกต้องของข้อมูลต้องมาก่อน) ตามด้วย Security และ UX
* **ความชัดเจน (clarity), ความง่ายในการบำรุงรักษา (maintainability), ความสอดคล้องกัน (consistency) และ การเข้าถึงได้ (accessibility)** ตลอดทั้งสแต็ก
* **Strict Typing:** ใช้ TypeScript อย่างเคร่งครัด ห้าม `any`
* **Consistency:** ใช้ภาษาอังกฤษใน Code / ภาษาไทยใน Comment
* **Resilience:** ระบบต้องทนทานต่อ Network Failure และ Race Condition
## ⚙️ **2. แนวทางทั่วไปสำหรับ TypeScript**
### **2.1 หลักการพื้นฐาน**
* ใช้ **ภาษาอังกฤษ** สำหรับโค้ด
* ใช้ **ภาษาไทย** สำหรับ comment และเอกสารทั้งหมด
* กำหนดไทป์ (type) อย่างชัดเจนสำหรับตัวแปร, พารามิเตอร์ และค่าที่ส่งกลับ (return values) ทั้งหมด
* หลีกเลี่ยงการใช้ any; ให้สร้างไทป์ (types) หรืออินเทอร์เฟซ (interfaces) ที่กำหนดเอง
* ใช้ **JSDoc** สำหรับคลาส (classes) และเมธอด (methods) ที่เป็น public
* ส่งออก (Export) **สัญลักษณ์หลัก (main symbol) เพียงหนึ่งเดียว** ต่อไฟล์
* หลีกเลี่ยงบรรทัดว่างภายในฟังก์ชัน
* ระบุ // File: path/filename ในบรรทัดแรกของทุกไฟล์
* ระบุ // บันทึกการแก้ไข, หากมีการแก้ไขเพิ่มในอนาคต ให้เพิ่มบันทึก
### **2.2 Configuration & Secrets Management**
* **Production/Staging:** ห้ามใส่ Secrets (Password, Keys) ใน `docker-compose.yml` หลัก
* **Development:** ให้สร้างไฟล์ `docker-compose.override.yml` (เพิ่มใน `.gitignore`) เพื่อ Inject ตัวแปร Environment ที่เป็นความลับ
* **Validation:** ใช้ `joi` หรือ `zod` ในการ Validate Environment Variables ตอน Start App หากขาดตัวแปรสำคัญให้ Throw Error ทันที
### **2.3 Idempotency (ความสามารถในการทำซ้ำได้)**
* สำหรับการทำงานที่สำคัญ (Create Document, Approve, Transactional) **ต้อง** ออกแบบให้เป็น Idempotent
* Client **ต้อง** ส่ง Header `Idempotency-Key` (UUID) มากับ Request
* Server **ต้อง** ตรวจสอบว่า Key นี้เคยถูกประมวลผลสำเร็จไปแล้วหรือไม่ ถ้าใช่ ให้คืนค่าเดิมโดยไม่ทำซ้ำ
### **2.4 ข้อตกลงในการตั้งชื่อ (Naming Conventions)**
| Entity (สิ่งที่ตั้งชื่อ) | Convention (รูปแบบ) | Example (ตัวอย่าง) |
| :-------------------- | :----------------- | :--------------------------------- |
| Classes | PascalCase | UserService |
| Property | snake_case | user_id |
| Variables & Functions | camelCase | getUserInfo |
| Files & Folders | kebab-case | user-service.ts |
| Environment Variables | UPPERCASE | DATABASE_URL |
| Booleans | Verb + Noun | isActive, canDelete, hasPermission |
ใช้คำเต็ม — ไม่ใช้อักษรย่อ — ยกเว้นคำมาตรฐาน (เช่น API, URL, req, res, err, ctx)
### 🧩**2.5 ฟังก์ชัน (Functions)**
* เขียนฟังก์ชันให้สั้น และทำ **หน้าที่เพียงอย่างเดียว** (single-purpose) (\< 20 บรรทัด)
* ใช้ **early returns** เพื่อลดการซ้อน (nesting) ของโค้ด
* ใช้ **map**, **filter**, **reduce** แทนการใช้ loops เมื่อเหมาะสม
* ควรใช้ **arrow functions** สำหรับตรรกะสั้นๆ, และใช้ **named functions** ในกรณีอื่น
* ใช้ **default parameters** แทนการตรวจสอบค่า null
* จัดกลุ่มพารามิเตอร์หลายตัวให้เป็นอ็อบเจกต์เดียว (RO-RO pattern)
* ส่งค่ากลับ (Return) เป็นอ็อบเจกต์ที่มีไทป์กำหนด (typed objects) ไม่ใช่ค่าพื้นฐาน (primitives)
* รักษาระดับของสิ่งที่เป็นนามธรรม (abstraction level) ให้เป็นระดับเดียวในแต่ละฟังก์ชัน
### 🧱**2.6 การจัดการข้อมูล (Data Handling)**
* ห่อหุ้มข้อมูล (Encapsulate) ในไทป์แบบผสม (composite types)
* ใช้ **immutability** (การไม่เปลี่ยนแปลงค่า) ด้วย readonly และ as const
* ทำการตรวจสอบความถูกต้องของข้อมูล (Validations) ในคลาสหรือ DTOs ไม่ใช่ภายในฟังก์ชันทางธุรกิจ
* ตรวจสอบความถูกต้องของข้อมูลโดยใช้ DTOs ที่มีไทป์กำหนดเสมอ
### 🧰**2.7 คลาส (Classes)**
* ปฏิบัติตามหลักการ **SOLID**
* ควรใช้ **composition มากกว่า inheritance** (Prefer composition over inheritance)
* กำหนด **interfaces** สำหรับสัญญา (contracts)
* ให้คลาสมุ่งเน้นการทำงานเฉพาะอย่างและมีขนาดเล็ก (\< 200 บรรทัด, \< 10 เมธอด, \< 10 properties)
### 🚨**2.8 การจัดการข้อผิดพลาด (Error Handling)**
* ใช้ Exceptions สำหรับข้อผิดพลาดที่ไม่คาดคิด
* ดักจับ (Catch) ข้อผิดพลาดเพื่อแก้ไขหรือเพิ่มบริบท (context) เท่านั้น; หากไม่เช่นนั้น ให้ใช้ global error handlers
* ระบุข้อความข้อผิดพลาด (error messages) ที่มีความหมายเสมอ
### 🧪**2.9 การทดสอบ (ทั่วไป) (Testing (General))**
* ใช้รูปแบบ **Arrange–Act–Assert**
* ใช้ชื่อตัวแปรในการทดสอบที่สื่อความหมาย (inputData, expectedOutput)
* เขียน **unit tests** สำหรับ public methods ทั้งหมด
* จำลอง (Mock) การพึ่งพาภายนอก (external dependencies)
* เพิ่ม **acceptance tests** ต่อโมดูลโดยใช้รูปแบบ Given–When-Then
### **Testing Strategy โดยละเอียด**
* **Test Pyramid Structure**
/\
/ \ E2E Tests (10%)
/____\ Integration Tests (20%)
/ \ Unit Tests (70%)
/________\
* **Testing Tools Stack**
```typescript
// Backend Testing Stack
const backendTesting = {
unit: ['Jest', 'ts-jest', '@nestjs/testing'],
integration: ['Supertest', 'Testcontainers', 'Jest'],
e2e: ['Supertest', 'Jest', 'Database Seeds'],
security: ['Jest', 'Custom Security Test Helpers'],
performance: ['Jest', 'autocannon', 'artillery']
};
// Frontend Testing Stack
const frontendTesting = {
unit: ['Vitest', 'React Testing Library'],
integration: ['React Testing Library', 'MSW'],
e2e: ['Playwright', 'Jest'],
visual: ['Playwright', 'Loki']
};
```
* **Test Data Management**
```typescript
// Test Data Factories
interface TestDataFactory {
createUser(overrides?: Partial<User>): User;
createCorrespondence(overrides?: Partial<Correspondence>): Correspondence;
createRoutingTemplate(overrides?: Partial<RoutingTemplate>): RoutingTemplate;
}
// Test Scenarios
const testScenarios = {
happyPath: 'Normal workflow execution',
edgeCases: 'Boundary conditions and limits',
errorConditions: 'Error handling and recovery',
security: 'Authentication and authorization',
performance: 'Load and stress conditions'
};
```
## 🏗️ **3. แบ็กเอนด์ (NestJS) - Implementation Details**
### **3.1 หลักการ**
* **สถาปัตยกรรมแบบโมดูลาร์ (Modular architecture)**:
* หนึ่งโมดูลต่อหนึ่งโดเมน
* โครงสร้างแบบ Controller → Service → Repository (Model)
* API-First: มุ่งเน้นการสร้าง API ที่มีคุณภาพสูง มีเอกสารประกอบ (Swagger) ที่ชัดเจนสำหรับ Frontend Team
* DTOs ที่ตรวจสอบความถูกต้องด้วย **class-validator**
* ใช้ **MikroORM** (หรือ TypeORM/Prisma) สำหรับการคงอยู่ของข้อมูล (persistence) ซึ่งสอดคล้องกับสคีมา MariaDB
* ห่อหุ้มโค้ดที่ใช้ซ้ำได้ไว้ใน **common module** (@app/common):
* Configs, decorators, DTOs, guards, interceptors, notifications, shared services, types, validators
### **3.2 Database & Data Modeling (MariaDB + TypeORM)**
#### **3.2.1 Optimistic Locking & Versioning**
เพื่อป้องกัน Race Condition ในการแก้ไขข้อมูลพร้อมกัน (โดยเฉพาะการรันเลขที่เอกสาร) ให้เพิ่ม Column `@VersionColumn()` ใน Entity ที่สำคัญ
```typescript
@Entity()
export class DocumentCounter {
// ... fields
@Column()
last_number: number;
@VersionColumn() // เพิ่ม Versioning
version: number;
}
```
#### **3.2.2 Virtual Columns for JSON Performance**
เนื่องจากเราใช้ MariaDB 10.11 และมีการเก็บข้อมูล JSON (Details) ให้ใช้ **Generated Columns (Virtual)** สำหรับ Field ที่ต้อง Search/Sort บ่อยๆ และทำ Index บน Virtual Column นั้น
```sql
-- ตัวอย่าง SQL Migration
ALTER TABLE correspondence_revisions
ADD COLUMN ref_project_id INT GENERATED ALWAYS AS (JSON_UNQUOTE(JSON_EXTRACT(details, '$.projectId'))) VIRTUAL;
CREATE INDEX idx_ref_project_id ON correspondence_revisions(ref_project_id);
```
#### **3.2.3 Partitioning Strategy**
สำหรับตาราง `audit_logs` และ `notifications` ให้เตรียมออกแบบ Entity ให้รองรับ Partitioning (เช่น แยกตามปี) โดยใช้ Raw SQL Migration ในการสร้างตาราง
### **3.3 File Storage Service (Two-Phase Storage)**
ปรับปรุง Service จัดการไฟล์ให้รองรับ Transactional Integrity
1. **Upload (Phase 1):**
* รับไฟล์ → Scan Virus (ClamAV) → Save ลงโฟลเดอร์ `temp/`
* Return `temp_id` และ Metadata กลับไปให้ Client
2. **Commit (Phase 2):**
* เมื่อ Business Logic (เช่น Create Correspondence) ทำงานสำเร็จ
* Service จะย้ายไฟล์จาก `temp/` ไปยัง `permanent/{YYYY}/{MM}/`
* Update path ใน Database
* ทั้งหมดนี้ต้องอยู่ภายใต้ Database Transaction เดียวกัน (ถ้า DB Fail, ไฟล์จะค้างที่ Temp และถูกลบโดย Cron Job)
### **3.4 Document Numbering (Double-Lock Mechanism)**
การออกเลขที่เอกสารต้องใช้กลไกความปลอดภัย 2 ชั้น:
1. **Layer 1 (Redis Lock):** ใช้ `redlock` เพื่อ Block ไม่ให้ Process อื่นเข้ามายุ่งกับ Counter ของ Project/Type นั้นๆ ชั่วคราว
2. **Layer 2 (Optimistic Lock):** ตอน Update Database ให้เช็ค `version` ถ้า version เปลี่ยน (แสดงว่า Redis Lock หลุดหรือมีคนแทรก) ให้ Throw Error และ Retry ใหม่
### **3.5 Unified Workflow Engine**
ห้ามแยก Logic ระหว่าง `CorrespondenceRouting` และ `RfaWorkflow` ออกจากกันเด็ดขาด ให้สร้าง `WorkflowEngineService` ที่เป็น Generic:
* **Input:** `currentState`, `action`, `rules (Guard)`
* **Output:** `nextState`, `assignee`
* รองรับทั้ง Linear Flow (Routing) และ Complex Flow (RFA) ผ่าน Configuration
### **3.6 ฟังก์ชันหลัก (Core Functionalities)**
* Global **filters** สำหรับการจัดการ exception
* **Middlewares** สำหรับการจัดการ request
* **Guards** สำหรับการอนุญาต (permissions) และ RBAC
* **Interceptors** สำหรับการแปลงข้อมูล response และการบันทึก log
### **3.7 ข้อจำกัดในการ Deploy (QNAP Container Station)**
* **ห้ามใช้ไฟล์ .env** ในการตั้งค่า Environment Variables [cite: 2.1]
* การตั้งค่าทั้งหมด (เช่น Database connection string, JWT secret) **จะต้องถูกกำหนดผ่าน Environment Variable ใน docker-compose.yml โดยตรง** [cite: 6.5] ซึ่งจะจัดการผ่าน UI ของ QNAP Container Station [cite: 2.1]
### **3.8 ข้อจำกัดด้านความปลอดภัย (Security Constraints):**
* **File Upload Security:** ต้องมี virus scanning (ClamAV), file type validation (white-list), และ file size limits (50MB)
* **Input Validation:** ต้องป้องกัน OWASP Top 10 vulnerabilities (SQL Injection, XSS, CSRF)
* **Rate Limiting:** ต้อง implement rate limiting ตาม strategy ที่กำหนด
* **Secrets Management:** ต้องมี mechanism สำหรับจัดการ sensitive secrets อย่างปลอดภัย แม้จะใช้ docker-compose.yml
### **3.9 โครงสร้างโมดูลตามโดเมน (Domain-Driven Module Structure)**
เพื่อให้สอดคล้องกับสคีมา SQL (LCBP3-DMS) เราจะใช้โครงสร้างโมดูลแบบ **Domain-Driven (แบ่งตามขอบเขตธุรกิจ)** แทนการแบ่งตามฟังก์ชัน:
#### 3.9.1 **CommonModule:**
* เก็บ Services ที่ใช้ร่วมกัน เช่น DatabaseModule, FileStorageService (จัดการไฟล์ใน QNAP), AuditLogService, NotificationService
* จัดการ audit_logs
* NotificationService ต้องรองรับ Triggers ที่ระบุใน Requirement 6.7 [cite: 6.7]
#### 3.9.2 **AuthModule:**
* จัดการะการยืนยันตัวตน (JWT, Guards)
* **(สำคัญ)** ต้องรับผิดชอบการตรวจสอบสิทธิ์ **4 ระดับ** [cite: 4.2]: สิทธิ์ระดับระบบ (Global Role), สิทธิ์ระดับองกรณ์ (Organization Role), สิทธิ์ระดับโปรเจกต์ (Project Role), และ สิทธิ์ระดับสัญญา (Contract Role)
* **(สำคัญ)** ต้องมี API สำหรับ **Admin Panel** เพื่อ:
* สร้างและจัดการ Role และการจับคู่ Permission แบบไดนามิก [cite: 4.3]
* ให้ Superadmin สร้าง Organizations และกำหนด Org Admin ได้ [cite: 4.6]
* ให้ Superadmin/Admin จัดการ document_number_formats (รูปแบบเลขที่เอกสาร), document_number_counters (Running Number) [cite: 3.10]
#### 3.9.3 **UserModule:**
* จัดการ users, roles, permissions, global_default_roles, role_permissions, user_roles, user_project_roles
* **(สำคัญ)** ต้องมี API สำหรับ **Admin Panel** เพื่อ:
* สร้างและจัดการ Role และการจับคู่ Permission แบบไดนามิก [cite: 4.3]
#### 3.9.4 **ProjectModule:**
* จัดการ projects, organizations, contracts, project_parties, contract_parties
#### 3.9.5 **MasterModule:**
* จัดการ master data (correspondence_types, rfa_types, rfa_status_codes, rfa_approve_codes, circulation_status_codes, correspondence_types, correspondence_status, tags) [cite: 4.5]
#### 3.9.6 **CorrespondenceModule (โมดูลศูนย์กลาง):**
* จัดการ correspondences, correspondence_revisions, correspondence_tags
* **(สำคัญ)** Service นี้ต้อง Inject DocumentNumberingService เพื่อขอเลขที่เอกสารใหม่ก่อนการสร้าง
* **(สำคัญ)** ตรรกะการสร้าง/อัปเดต Revision จะอยู่ใน Service นี้
* จัดการ correspondence_attachments (ตารางเชื่อมไฟล์แนบ)
* รับผิดชอบ Routing **Correspondence Routing** (correspondence_routings, correspondence_routing_template_steps, correspondence_routing_templates, correspondence_status_transitions) สำหรับการส่งต่อเอกสารทั่วไประหว่างองค์กร
#### 3.9.7 **RfaModule:**
* จัดการ rfas, rfa_revisions, rfa_items
* รับผิดชอบเวิร์กโฟลว์ **"RFA Workflows"** (rfa_workflows, rfa_workflow_templates, rfa_workflow_template_steps, rfa_status_transitions) สำหรับการอนุมัติเอกสารทางเทคนิค
#### 3.9.8 **DrawingModule:**
* จัดการ shop_drawings, shop_drawing_revisions, contract_drawings, contract_drawing_volumes, contract_drawing_cats, contract_drawing_sub_cats, shop_drawing_main_categories, shop_drawing_sub_categories, contract_drawing_subcat_cat_maps, shop_drawing_revision_contract_refs
* จัดการ shop_drawing_revision_attachments และ contract_drawing_attachments(ตารางเชื่อมไฟล์แนบ)
#### 3.9.9 **CirculationModule:**
* จัดการ circulations, circulation_templates, circulation_assignees
* จัดการ circulation_attachments (ตารางเชื่อมไฟล์แนบ)
* รับผิดชอบเวิร์กโฟลว์ **"Circulations"** (circulation_status_transitions, circulation_template_assignees, circulation_assignees, circulation_recipients, circulation_actions, circulation_action_documents)สำหรับการเวียนเอกสาร **ภายในองค์กร**
#### 3.9.10 **TransmittalModule:**
* จัดการ transmittals และ transmittal_items
#### 3.9.11 **SearchModule:**
* ให้บริการค้นหาขั้นสูง (Advanced Search) [cite: 6.2] โดยใช้ **Elasticsearch** เพื่อรองรับการค้นหาแบบ Full-text จากชื่อเรื่อง, รายละเอียด, เลขที่เอกสาร, ประเภท, วันที่, และ Tags
* ระบบจะใช้ Elasticsearch Engine ในการจัดทำดัชนีเพื่อการค้นหาข้อมูลเชิงลึกจากเนื้อหาของเอกสาร โดยข้อมูลจะถูกส่งไปทำดัชนีจาก Backend (NestJS) ทุกครั้งที่มีการสร้างหรือแก้ไขเอกสาร
#### 3.9.12 **DocumentNumberingModule:**
* **สถานะ:** เป็น Module ภายใน (Internal Module) ไม่เปิด API สู่ภายนอก
* **หน้าที่:** ให้บริการ `DocumentNumberingService` แบบ **Token-Based Generator**
* **Logic ใหม่ (v1.4.4):**
* รับ Context: `{ projectId, orgId, typeId, disciplineId?, subTypeId?, year }`
* ดึง Template จาก DB
* Parse Template เพื่อหาว่าต้องใช้ Key ใดบ้างในการทำ Grouping Counter (เช่น ถ้า Template มี `{DISCIPLINE}` ให้ใช้ `discipline_id` ในการ query counter)
* ใช้ **Double-Lock Mechanism** (Redis + Optimistic DB Lock) ในการดึงและอัพเดทค่า `last_number`
* **Features:**
* Application-level locking เพื่อป้องกัน race condition
* Retry mechanism ด้วย exponential backoff
* Fallback mechanism เมื่อการขอเลขล้มเหลว
* Audit log ทุกครั้งที่มีการ generate เลขที่เอกสารใหม่
#### 3.9.13 **CorrespondenceRoutingModule:**
* **สถานะ:** โมดูลหลักสำหรับจัดการการส่งต่อเอกสาร
* **หน้าที่:** จัดการแม่แบบการส่งต่อและการส่งต่อจริง
* **Entities:**
* CorrespondenceRoutingTemplate
* CorrespondenceRoutingTemplateStep
* CorrespondenceRouting
* **Features:**
* สร้างและจัดการแม่แบบการส่งต่อ
* ดำเนินการส่งต่อเอกสารตามแม่แบบ
* ติดตามสถานะการส่งต่อ
* คำนวณวันครบกำหนดอัตโนมัติ
* ส่งการแจ้งเตือนเมื่อมีการส่งต่อใหม่
#### 3.9.14 **WorkflowEngineModule:**
* **สถานะ:** Internal Module สำหรับจัดการ workflow logic
* **หน้าที่:** ประมวลผล state transitions และ business rules
* **Features:**
* State machine สำหรับสถานะเอกสาร
* Validation rules สำหรับการเปลี่ยนสถานะ
* Automatic status updates
* Deadline management และ escalation
#### 3.9.15 **JsonSchemaModule:**
* **สถานะ:** Internal Module สำหรับจัดการ JSON schemas
* **หน้าที่:** Validate, transform, และ manage JSON data structures
* **Features:**
* JSON schema validation ด้วย AJV
* Schema versioning และ migration
* Dynamic schema generation
* Data transformation และ sanitization
#### 3.9.16 **DetailsService:**
* **สถานะ:** Shared Service สำหรับจัดการ details fields
* **หน้าที่:** Centralized service สำหรับ JSON details operations
* **Methods:**
* validateDetails(type: string, data: any): ValidationResult
* transformDetails(input: any, targetVersion: string): any
* sanitizeDetails(data: any): any
* getDefaultDetails(type: string): any
### **3.10 สถาปัตยกรรมระบบ (System Architecture)**
โครงสร้างโมดูล (Module Structure)
```bash
📁 src
├── 📄 app.module.ts
├── 📄 main.ts
├── 📁 common # @app/common (โมดูลส่วนกลาง)
│ ├── 📁 auth # AuthModule (JWT, Guards)
│ ├── 📁 config # Configuration
│ ├── 📁 decorators # Custom Decorators (เช่น @RequirePermission)
│ ├── 📁 entities # Shared Entities (User, Role, Permission)
│ ├── 📁 exceptions # Global Exception Filters
│ ├── 📁 file-storage # FileStorageService (Virus Scanning, Security)
│ ├── 📁 guards # Custom Guards (RBAC Guard, RateLimitGuard)
│ ├── 📁 interceptors # Interceptors (Audit Log, Transform, Performance)
│ ├── 📁 resilience # Circuit Breaker, Retry Patterns
│ └── 📁 services # Shared Services (NotificationService, CachingService)
├── 📁 modules
│ ├── 📁 user # UserModule (จัดการ Users, Roles, Permissions)
│ ├── 📁 project # ProjectModule (จัดการ Projects, Organizations, Contracts)
│ ├── 📁 correspondence # CorrespondenceModule (จัดการเอกสารโต้ตอบ)
│ ├── 📁 rfa # RfaModule (จัดการเอกสารขออนุมัติ)
│ ├── 📁 drawing # DrawingModule (จัดการแบบแปลน)
│ ├── 📁 circulation # CirculationModule (จัดการใบเวียน)
│ ├── 📁 transmittal # TransmittalModule (จัดการเอกสารนำส่ง)
│ ├── 📁 search # SearchModule (ค้นหาขั้นสูงด้วย Elasticsearch)
│ ├── 📁 monitoring # MonitoringModule (Metrics, Health Checks)
│ └── 📁 document-numbering # DocumentNumberingModule (Internal Module)
└── 📁 database # Database Migration & Seeding Scripts
```
### **3.11 กลยุทธ์ความทนทานและการจัดการข้อผิดพลาด (Resilience & Error Handling Strategy)**
* **Circuit Breaker Pattern:** ใช้สำหรับ external service calls (Email, LINE, Elasticsearch)
* **Retry Mechanism:** ด้วย exponential backoff สำหรับ transient failures
* **Fallback Strategies:** Graceful degradation เมื่อบริการภายนอกล้มเหลว
* **Error Handling:** Error messages ต้องไม่เปิดเผยข้อมูล sensitive
* **Monitoring:** Centralized error monitoring และ alerting system
### **3.12 FileStorageService (ปรับปรุงใหม่):**
* **Virus Scanning:** Integrate ClamAV สำหรับ scan ไฟล์ที่อัปโหลดทั้งหมด
* **File Type Validation:** ใช้ white-list approach (PDF, DWG, DOCX, XLSX, ZIP)
* **File Size Limits:** 50MB ต่อไฟล์
* **Security Measures:**
* เก็บไฟล์นอก web root
* Download ผ่าน authenticated endpoint เท่านั้น
* Download links มี expiration time (24 ชั่วโมง)
* File integrity checks (checksum)
* Access control checks ก่อนดาวน์โหลด
### **3.13 เเทคโนโลยีที่ใช้ (Technology Stack)**
| ส่วน | Library/Tool | หมายเหตุ |
| ----------------------- | ---------------------------------------------------- | -------------------------------------- |
| **Framework** | `@nestjs/core`, `@nestjs/common` | Core Framework |
| **Language** | `TypeScript` | ใช้ TypeScript ทั้งระบบ |
| **Database** | `MariaDB 10.11` | ฐานข้อมูลหลัก |
| **ORM** | `@nestjs/typeorm`, `typeorm` | 🗃️จัดการการเชื่อมต่อและ Query ฐานข้อมูล |
| **Validation** | `class-validator`, `class-transformer` | 📦ตรวจสอบและแปลงข้อมูลใน DTO |
| **Auth** | `@nestjs/jwt`, `@nestjs/passport`, `passport-jwt` | 🔐การยืนยันตัวตนด้วย JWT |
| **Authorization** | `casl` | 🔐จัดการสิทธิ์แบบ RBAC |
| **File Upload** | `multer` | 📁จัดการการอัปโหลดไฟล์ |
| **Search** | `@nestjs/elasticsearch` | 🔍สำหรับการค้นหาขั้นสูง |
| **Notification** | `nodemailer` | 📬ส่งอีเมลแจ้งเตือน |
| **Scheduling** | `@nestjs/schedule` | 📬สำหรับ Cron Jobs (เช่น แจ้งเตือน Deadline) |
| **Logging** | `winston` | 📊บันทึก Log ที่มีประสิทธิภาพ |
| **Testing** | `@nestjs/testing`, `jest`, `supertest` | 🧪ทดสอบ Unit, Integration และ E2E |
| **Documentation** | `@nestjs/swagger` | 🌐สร้าง API Documentation อัตโนมัติ |
| **Security** | `helmet`, `rate-limiter-flexible` | 🛡️เพิ่มความปลอดภัยให้ API |
| **Resilience** | `@nestjs/circuit-breaker` | 🔄 Circuit breaker pattern |
| **Caching** | `@nestjs/cache-manager`, `cache-manager-redis-store` | 💾 Distributed caching |
| **Security** | `helmet`, `csurf`, `rate-limiter-flexible` | 🛡️ Security enhancements |
| **Validation** | `class-validator`, `class-transformer` | ✅ Input validation |
| **Monitoring** | `@nestjs/monitoring`, `winston` | 📊 Application monitoring |
| **File Processing** | `clamscan` | 🦠 Virus scanning |
| **Cryptography** | `bcrypt`, `crypto` | 🔐 Password hashing และ checksums |
| **JSON Validation** | `ajv`, `ajv-formats` | 🎯 JSON schema validation |
| **JSON Processing** | `jsonpath`, `json-schema-ref-parser` | 🔧 JSON manipulation |
| **Data Transformation** | `class-transformer` | 🔄 Object transformation |
| **Compression** | `compression` | 📦 JSON compression |
### **3.14 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
### **3.15 Performance Testing:**
* **Load Testing:** ทดสอบด้วย realistic workloads
* **Stress Testing:** หา breaking points ของระบบ
* **Endurance Testing:** ทดสอบการทำงานต่อเนื่องเป็นเวลานาน
### 🗄️**3.16 Backend State Management**
Backend (NestJS) ควรเป็น **Stateless** (ไม่เก็บสถานะ) "State" ทั้งหมดจะถูกจัดเก็บใน MariaDB
* **Request-Scoped State (สถานะภายใน Request เดียว):**
* **ปัญหา:** จะส่งต่อข้อมูล (เช่น User ที่ล็อกอิน) ระหว่าง Guard และ Service ใน Request เดียวกันได้อย่างไร?
* **วิธีแก้:** ใช้ **Request-Scoped Providers** ของ NestJS (เช่น AuthContextService) เพื่อเก็บข้อมูล User ปัจจุบันที่ได้จาก AuthGuard และให้ Service อื่น Inject ไปใช้
* **Application-Scoped State (การ Caching):**
* **ปัญหา:** ข้อมูล Master (เช่น roles, permissions, organizations) ถูกเรียกใช้บ่อย
* **วิธีแก้:** ใช้ **Caching** (เช่น @nestjs/cache-manager) เพื่อ Caching ข้อมูลเหล่านี้ และลดภาระ Database
### **3.17 Caching Strategy (ตามข้อ 6.4.2):**
* **Master Data Cache:** Roles, Permissions, Organizations (TTL: 1 hour)
* **User Session Cache:** User permissions และ profile (TTL: 30 minutes)
* **Search Result Cache:** Frequently searched queries (TTL: 15 minutes)
* **File Metadata Cache:** Attachment metadata (TTL: 1 hour)
* **Cache Invalidation:** Clear cache on update/delete operations
### **3.18 การไหลของข้อมูล (Data Flow)**
#### **3.18.1 Main Flow:**
1. Request: ผ่าน Nginx Proxy Manager -> NestJS Controller
2. **Rate Limiting:** RateLimitGuard ตรวจสอบ request limits
3. **Input Validation:** Validation Pipe ตรวจสอบและ sanitize inputs
4. Authentication: JWT Guard ตรวจสอบ Token และดึงข้อมูล User
5. Authorization: RBAC Guard ตรวจสอบสิทธิ์
6. **Security Checks:** Virus scanning (สำหรับ file upload), XSS protection
7. Business Logic: Service Layer ประมวลผลตรรกะทางธุรกิจ
8. **Resilience:** Circuit breaker และ retry logic สำหรับ external calls
9. Data Access: Repository Layer ติดต่อกับฐานข้อมูล
10. **Caching:** Cache frequently accessed data
11. **Audit Log:** บันทึกการกระทำสำคัญ
12. Response: ส่งกลับไปยัง Frontend
#### **3.18.2 Workflow Data Flow:**
1. User สร้างเอกสาร → เลือก routing template
2. System สร้าง routing instances ตาม template
3. สำหรับแต่ละ routing step:
- กำหนด due date (จาก expected_days)
- ส่ง notification ไปยังองค์กรผู้รับ
- อัพเดทสถานะเป็น SENT
4. เมื่อองค์กรผู้รับดำเนินการ:
- อัพเดทสถานะเป็น ACTIONED/FORWARDED/REPLIED
- บันทึก processed_by และ processed_at
- ส่ง notification ไปยังขั้นตอนต่อไป (ถ้ามี)
5. เมื่อครบทุกขั้นตอน → อัพเดทสถานะเอกสารเป็น COMPLETED
#### **3.18.3 JSON Details Processing Flow:**
1. **Receive Request** → Get JSON data from client
2. **Schema Validation** → Validate against predefined schema
3. **Data Sanitization** → Sanitize and transform data
4. **Version Check** → Handle schema version compatibility
5. **Storage** → Store validated JSON in database
6. **Retrieval** → Retrieve and transform on demand
### 📊**3.19 Monitoring & Observability (ตามข้อ 6.8)**
#### **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
#### **Performance Targets:**
* API Response Time: < 200ms (90th percentile)
* Search Query Performance: < 500ms
* File Upload Performance: < 30 seconds สำหรับไฟล์ 50MB
* Cache Hit Ratio: > 80%
## 🖥️ **4. ฟรอนต์เอนด์ (Next.js) - Implementation Details**
**โปรไฟล์นักพัฒนา (Developer Profile:** วิศวกร TypeScript + React/NextJS ระดับ Senior
เชี่ยวชาญ TailwindCSS, Shadcn/UI, และ Radix สำหรับการพัฒนา UI
### **4.1 State Management & Offline Support**
#### **4.1.1 Auto-Save Drafts**
ใช้ `zustand` ร่วมกับ middleware `persist` (ลง LocalStorage) สำหรับฟอร์มที่มีขนาดใหญ่ (RFA, Correspondence) เพื่อป้องกันข้อมูลหายเมื่อเน็ตหลุด
```typescript
// lib/stores/draft-store.ts
export const useDraftStore = create(
persist(
(set) => ({
drafts: {},
saveDraft: (key, data) => set((state) => ({ drafts: { ...state.drafts, [key]: data } })),
clearDraft: (key) => set((state) => {
const newDrafts = { ...state.drafts };
delete newDrafts[key];
return { drafts: newDrafts };
}),
}),
{ name: 'form-drafts' }
)
);
```
### **4.2 Dynamic Form Generator**
เพื่อรองรับ JSON Schema หลากหลายรูปแบบ ให้สร้าง Component กลางที่รับ Schema แล้ว Gen Form ออกมา (ลดการแก้ Code บ่อยๆ)
* **Libraries:** แนะนำ `react-jsonschema-form` หรือสร้าง Wrapper บน `react-hook-form` ที่ Recursively render field ตาม Type
* **Validation:** ใช้ `ajv` ที่ฝั่ง Client เพื่อ Validate JSON ก่อน Submit
### **4.3 Mobile Responsiveness (Card View)**
ตารางข้อมูล (`DataTable`) ต้องมีความฉลาดในการแสดงผล:
* **Desktop:** แสดงเป็น Table ปกติ
* **Mobile:** แปลงเป็น **Card View** โดยอัตโนมัติ (ซ่อน Header, แสดง Label คู่ Value ในแต่ละ Card)
```tsx
// components/ui/responsive-table.tsx
<div className="hidden md:block">
<Table>{/* Desktop View */}</Table>
</div>
<div className="md:hidden space-y-4">
{data.map((item) => (
<Card key={item.id}>
{/* Mobile View: Render cells as list items */}
</Card>
))}
</div>
```
### **4.4 Optimistic Updates**
ใช้ความสามารถของ **TanStack Query** (`onMutate`) เพื่ออัปเดต UI ทันที (เช่น เปลี่ยนสถานะจาก "รออ่าน" เป็น "อ่านแล้ว") แล้วค่อยส่ง Request ไป Server ถ้า Failed ค่อย Rollback
### **4.5 แนวทางการพัฒนาโค้ด (Code Implementation Guidelines)**
* ใช้ **early returns** เพื่อความชัดเจน
* ใช้คลาสของ **TailwindCSS** ในการกำหนดสไตล์เสมอ
* ควรใช้ class: syntax แบบมีเงื่อนไข (หรือ utility clsx) มากกว่าการใช้ ternary operators ใน class strings
* ใช้ **const arrow functions** สำหรับ components และ handlers
* Event handlers ให้ขึ้นต้นด้วย handle... (เช่น handleClick, handleSubmit)
* รวมแอตทริบิวต์สำหรับการเข้าถึง (accessibility) ด้วย:
tabIndex="0", aria-label, onKeyDown, ฯลฯ
* ตรวจสอบให้แน่ใจว่าโค้ดทั้งหมด **สมบูรณ์**, **ผ่านการทดสอบ**, และ **ไม่ซ้ำซ้อน (DRY)**
* ต้อง import โมดูลที่จำเป็นต้องใช้อย่างชัดเจนเสมอ
### **4.6 UI/UX ด้วย React**
* ใช้ **semantic HTML**
* ใช้คลาสของ **Tailwind** ที่รองรับ responsive (sm:, md:, lg:)
* รักษาลำดับชั้นของการมองเห็น (visual hierarchy) ด้วยการใช้ typography และ spacing
* ใช้ **Shadcn** components (Button, Input, Card, ฯลฯ) เพื่อ UI ที่สอดคล้องกัน
* ทำให้ components มีขนาดเล็กและมุ่งเน้นการทำงานเฉพาะอย่าง
* ใช้ utility classes สำหรับการจัดสไตล์อย่างรวดเร็ว (spacing, colors, text, ฯลฯ)
* ตรวจสอบให้แน่ใจว่าสอดคล้องกับ **ARIA** และใช้ semantic markup
### **4.7 การตรวจสอบฟอร์มและข้อผิดพลาด (Form Validation & Errors)**
* ใช้ไลบรารีฝั่ง client เช่น zod และ react-hook-form
* แสดงข้อผิดพลาดด้วย **alert components** หรือข้อความ inline
* ต้องมี labels, placeholders, และข้อความ feedback
### **🧪4.8 Frontend Testing**
เราจะใช้ **React Testing Library (RTL)** สำหรับการทดสอบ Component และ **Playwright** สำหรับ E2E:
* **Unit Tests (การทดสอบหน่วยย่อย):**
* **เครื่องมือ:** Vitest + RTL
* **เป้าหมาย:** ทดสอบ Component ขนาดเล็ก (เช่น Buttons, Inputs) หรือ Utility functions
* **Integration Tests (การทดสอบการบูรณาการ):**
* **เครื่องมือ:** RTL + **Mock Service Worker (MSW)**
* **เป้าหมาย:** ทดสอบว่า Component หรือ Page ทำงานกับ API (ที่จำลองขึ้น) ได้ถูกต้อง
* **เทคนิค:** ใช้ MSW เพื่อจำลอง NestJS API และทดสอบว่า Component แสดงผลข้อมูลจำลองได้ถูกต้องหรือไม่ (เช่น ทดสอบหน้า Dashboard [cite: 5.3] ที่ดึงข้อมูลจาก v_user_tasks)
* **E2E (End-to-End) Tests:**
* **เครื่องมือ:** **Playwright**
* **เป้าหมาย:** ทดสอบ User Flow ทั้งระบบโดยอัตโนมัติ (เช่น ล็อกอิน -> สร้าง RFA -> ตรวจสอบ Workflow Visualization [cite: 5.6])
### **🗄️4.9 Frontend State Management**
สำหรับ Next.js App Router เราจะแบ่ง State เป็น 4 ระดับ:
1. **Local UI State (สถานะ UI ชั่วคราว):**
* **เครื่องมือ:** useState, useReducer
* **ใช้เมื่อ:** จัดการสถานะเล็กๆ ที่จบใน Component เดียว (เช่น Modal เปิด/ปิด, ค่าใน Input)
2. **Server State (สถานะข้อมูลจากเซิร์ฟเวอร์):**
* **เครื่องมือ:** **React Query (TanStack Query)** หรือ SWR
* **ใช้เมื่อ:** จัดการข้อมูลที่ดึงมาจาก NestJS API (เช่น รายการ correspondences, rfas, drawings)
* **ทำไม:** React Query เป็น "Cache" ที่จัดการ Caching, Re-fetching, และ Invalidation ให้โดยอัตโนมัติ
3. **Global Client State (สถานะส่วนกลางฝั่ง Client):**
* **เครื่องมือ:** **Zustand** (แนะนำ) หรือ Context API
* **ใช้เมื่อ:** จัดการข้อมูลที่ต้องใช้ร่วมกันทั่วทั้งแอป และ *ไม่ใช่* ข้อมูลจากเซิร์ฟเวอร์ (เช่น ข้อมูล User ที่ล็อกอิน, สิทธิ์ Permissions)
4. **Form State (สถานะของฟอร์ม):**
* **เครื่องมือ:** **React Hook Form** + **Zod**
* **ใช้เมื่อ:** จัดการฟอร์มที่ซับซ้อน (เช่น ฟอร์มสร้าง RFA, ฟอร์ม Circulation [cite: 3.7])
## 🔐 **5. Security & Access Control (Full Stack Integration)**
### **5.1 CASL Integration (Shared Ability)**
* **Backend:** ใช้ CASL กำหนด Permission Rule
* **Frontend:** ให้ดึง Rule (JSON) จาก Backend มา Load ใส่ `@casl/react` เพื่อให้ Logic การ Show/Hide ปุ่ม ตรงกัน 100%
### **5.2 Maintenance Mode**
เพิ่ม Middleware (ทั้ง NestJS และ Next.js) เพื่อตรวจสอบ Flag ใน Redis:
* ถ้า `MAINTENANCE_MODE = true`
* **API:** Return `503 Service Unavailable` (ยกเว้น Admin IP)
* **Frontend:** Redirect ไปหน้า `/maintenance`
### **5.3 Idempotency Client**
สร้าง Axios Interceptor เพื่อ Generate `Idempotency-Key` สำหรับ POST/PUT/DELETE requests ทุกครั้ง
```typescript
// lib/api/client.ts
import { v4 as uuidv4 } from 'uuid';
apiClient.interceptors.request.use((config) => {
if (['post', 'put', 'delete'].includes(config.method)) {
config.headers['Idempotency-Key'] = uuidv4();
}
return config;
});
```
### **5.4 RBAC และการควบคุมสิทธิ์ (RBAC & Permission Control)**
ใช้ Decorators เพื่อบังคับใช้สิทธิ์การเข้าถึง โดยอ้างอิงสิทธิ์จากตาราง permissions
```typescript
@RequirePermission('rfas.respond') // ต้องตรงกับ 'permission_code'
@Put(':id')
updateRFA(@Param('id') id: string) {
return this.rfaService.update(id);
}
```
#### **5.4.1 Roles (บทบาท)**
* **Superadmin**: ไม่มีข้อจำกัดใดๆ [cite: 4.3]
* **Admin**: มีสิทธิ์เต็มที่ในองค์กร [cite: 4.3]
* **Document Control**: เพิ่ม/แก้ไข/ลบ เอกสารในองค์กร [cite: 4.3]
* **Editor**: สามารถ เพิ่ม/แก้ไข เอกสารที่กำหนด [cite: 4.3]
* **Viewer**: สามารถดู เอกสาร [cite: 4.3]
#### **5.4.2 ตัวอย่าง Permissions (จากตาราง permissions)**
* rfas.view, rfas.create, rfas.respond, rfas.delete
* drawings.view, drawings.upload, drawings.delete
* corr.view, corr.manage
* transmittals.manage
* cirs.manage
* project_parties.manage
การจับคู่ระหว่าง roles และ permissions **เริ่มต้น** จะถูก seed ผ่านสคริปต์ (ดังที่เห็นในไฟล์ SQL)**อย่างไรก็ตาม AuthModule/UserModule ต้องมี API สำหรับ Admin เพื่อสร้าง Role ใหม่และกำหนดสิทธิ์ (Permissions) เพิ่มเติมได้ในภายหลัง** [cite: 4.3]
## 📊 **6. Notification & Background Jobs**
### **6.1 Digest Notification**
ห้ามส่ง Email ทันทีที่เกิด Event ให้:
1. Push Event ลง Queue (Redis/BullMQ)
2. มี Processor รอเวลา (เช่น 5 นาที) เพื่อ Group Events ที่คล้ายกัน (เช่น "คุณมีเอกสารรออนุมัติ 5 ฉบับ")
3. ส่ง Email เดียว (Digest) เพื่อลด Spam
## 🔗 **7. แนวทางการบูรณาการ Full Stack (Full Stack Integration Guidelines)**
| Aspect (แง่มุม) | Backend (NestJS) | Frontend (NextJS) | UI Layer (Tailwind/Shadcn) |
| :----------------------- | :------------------------- | :---------------------------- | :------------------------------------- |
| API | REST / GraphQL Controllers | API hooks ผ่าน fetch/axios/SWR | Components ที่รับข้อมูล |
| Validation (การตรวจสอบ) | class-validator DTOs | zod / react-hook-form | สถานะของฟอร์ม/input ใน Shadcn |
| Auth (การยืนยันตัวตน) | Guards, JWT | NextAuth / cookies | สถานะ UI ของ Auth (loading, signed in) |
| Errors (ข้อผิดพลาด) | Global filters | Toasts / modals | Alerts / ข้อความ feedback |
| Testing (การทดสอบ) | Jest (unit/e2e) | Vitest / Playwright | Visual regression |
| Styles (สไตล์) | Scoped modules (ถ้าจำเป็น) | Tailwind / Shadcn | Tailwind utilities |
| Accessibility (การเข้าถึง) | Guards + filters | ARIA attributes | Semantic HTML |
## 🗂️ **8. ข้อตกลงเฉพาะสำหรับ DMS (LCBP3-DMS)**
ส่วนนี้ขยายแนวทาง FullStackJS ทั่วไปสำหรับโปรเจกต์ **LCBP3-DMS** โดยมุ่งเน้นไปที่เวิร์กโฟลว์การอนุมัติเอกสาร (Correspondence, RFA, Drawing, Contract, Transmittal, Circulation)
### 🧾**8.1 มาตรฐาน AuditLog (AuditLog Standard)**
บันทึกการดำเนินการ CRUD และการจับคู่ทั้งหมดลงในตาราง audit_logs
| Field (ฟิลด์) | Type (จาก SQL) | Description (คำอธิบาย) |
| :----------- | :------------- | :----------------------------------------------- |
| audit_id | BIGINT | Primary Key |
| user_id | INT | ผู้ใช้ที่ดำเนินการ (FK -> users) |
| action | VARCHAR(100) | rfa.create, correspondence.update, login.success |
| entity_type | VARCHAR(50) | ชื่อตาราง/โมดูล เช่น 'rfa', 'correspondence' |
| entity_id | VARCHAR(50) | Primary ID ของระเบียนที่ได้รับผลกระทบ |
| details_json | JSON | ข้อมูลบริบท (เช่น ฟิลด์ที่มีการเปลี่ยนแปลง) |
| ip_address | VARCHAR(45) | IP address ของผู้ดำเนินการ |
| user_agent | VARCHAR(255) | User Agent ของผู้ดำเนินการ |
| created_at | TIMESTAMP | Timestamp (UTC) |
### 📂**8.2 การจัดการไฟล์ (File Handling)**
#### **8.2.1 มาตรฐานการอัปโหลดไฟล์ (File Upload Standard)**
* **Security-First Approach:** การอัปโหลดไฟล์ทั้งหมดจะถูกจัดการโดย FileStorageService ที่มี security measures ครบถ้วน
* ไฟล์จะถูกเชื่อมโยงไปยัง Entity ที่ถูกต้องผ่าน **ตารางเชื่อม (Junction Tables)** เท่านั้น:
* correspondence_attachments (เชื่อม Correspondence กับ Attachments)
* circulation_attachments (เชื่อม Circulation กับ Attachments)
* shop_drawing_revision_attachments (เชื่อม Shop Drawing Revision กับ Attachments)
* contract_drawing_attachments (เชื่อม Contract Drawing กับ Attachments)
* เส้นทางจัดเก็บไฟล์ (Upload path): อ้างอิงจาก Requirement 2.1 คือ /share/dms-data [cite: 2.1] โดย FileStorageService จะสร้างโฟลเดอร์ย่อยแบบรวมศูนย์ (เช่น /share/dms-data/uploads/{YYYY}/{MM}/[stored_filename])
* ประเภทไฟล์ที่อนุญาต: pdf, dwg, docx, xlsx, zip (ผ่าน white-list validation)
* ขนาดสูงสุด: **50 MB**
* จัดเก็บนอก webroot
* ให้บริการไฟล์ผ่าน endpoint ที่ปลอดภัย /files/:attachment_id/download
#### **8.2.2 Security Controls สำหรับ File Access:**
การเข้าถึงไฟล์ไม่ใช่การเข้าถึงโดยตรง endpoint /files/:attachment_id/download จะต้อง:
1. ค้นหาระเบียน attachment
2. ตรวจสอบว่า attachment_id นี้ เชื่อมโยงกับ Entity ใด (เช่น correspondence, circulation, shop_drawing_revision, contract_drawing) ผ่านตารางเชื่อม
3. ตรวจสอบว่าผู้ใช้มีสิทธิ์ (permission) ในการดู Entity ต้นทางนั้นๆ หรือไม่
4. ตรวจสอบ download token expiration (24 ชั่วโมง)
5. บันทึก audit log การดาวน์โหลด
### 🔟**8.3 การจัดการเลขที่เอกสาร (Document Numbering) [cite: 3.10]**
* **เป้าหมาย:** สร้างเลขที่เอกสาร (เช่น correspondence_number) โดยอัตโนมัติ ตามรูปแบบที่กำหนด
* **ตรรกะการนับ:** การนับ Running number (SEQ) จะนับแยกตาม Key: **Project + Originator Organization + Document Type + Year**
* **ตาราง SQL (Updated):**
* `document_number_formats`: เก็บ Template String (เช่น `{CONTRACT}-{TYPE}-{DISCIPLINE}-{SEQ:4}`)
* `document_number_counters`: **Primary Key เปลี่ยนเป็น Composite Key ใหม่:** `(project_id, originator_id, type_id, discipline_id, current_year)` เพื่อรองรับการรันเลขแยกตามสาขา
* **การทำงาน:**
* Service ต้องรองรับการ Resolve Token พิเศษ เช่น `{SUBTYPE_NUM}` ที่ต้องไป Join กับตาราง `correspondence_sub_types`
* DocumentNumberingModule จะให้บริการ DocumentNumberingService
* เมื่อ CorrespondenceModule ต้องการสร้างเอกสารใหม่, มันจะเรียก documentNumberingService.generateNextNumber(...)
* Service นี้จะใช้ **Redis distributed locking** แทน stored procedure ซึ่งจะจัดการ Database Transaction และ Row Locking ภายใน Application Layer เพื่อรับประกันการป้องกัน Race Condition
* มี retry mechanism และ fallback strategies
### 📊**8.4 การรายงานและการส่งออก (Reporting & Exports)**
#### **8.4.1 วิวสำหรับการรายงาน (Reporting Views) (จาก SQL)**
การรายงานควรสร้างขึ้นจาก Views ที่กำหนดไว้ล่วงหน้าในฐานข้อมูลเป็นหลัก:
* v_current_correspondences: สำหรับ revision ปัจจุบันทั้งหมดของเอกสารที่ไม่ใช่ RFA
* v_current_rfas: สำหรับ revision ปัจจุบันทั้งหมดของ RFA และข้อมูล master
* v_contract_parties_all: สำหรับการตรวจสอบความสัมพันธ์ของ project/contract/organization
* v_user_tasks: สำหรับ Dashboard "งานของฉัน"
* v_audit_log_details: สำหรับ Activity Feed
Views เหล่านี้ทำหน้าที่เป็นแหล่งข้อมูลหลักสำหรับการรายงานฝั่งเซิร์ฟเวอร์และการส่งออกข้อมูล
#### **8.4.2 กฎการส่งออก (Export Rules)**
* Export formats: CSV, Excel, PDF.
* จัดเตรียมมุมมองสำหรับพิมพ์ (Print view).
* รวมลิงก์ไปยังต้นทาง (เช่น /rfas/:id).
## 🧮 **9. ฟรอนต์เอนด์: รูปแบบ DataTable และฟอร์ม (Frontend: DataTable & Form Patterns)**
### **9.1 DataTable (Server‑Side)**
* Endpoint: /api/{module}?page=1&pageSize=20&sort=...&filter=...
* ต้องรองรับ: การแบ่งหน้า (pagination), การเรียงลำดับ (sorting), การค้นหา (search), การกรอง (filters)
* แสดง revision ล่าสุดแบบ inline เสมอ (สำหรับ RFA/Drawing)
### **9.2 มาตรฐานฟอร์ม (Form Standards)**
* ต้องมีการใช้งาน Dropdowns แบบขึ้นต่อกัน (Dependent dropdowns) (ตามที่สคีมารองรับ):
* Project → Contract Drawing Volumes
* Contract Drawing Category → Sub-Category
* RFA (ประเภท Shop Drawing) → Shop Drawing Revisions ที่เชื่อมโยงได้
* **File Upload Security:** ต้องรองรับ **Multi-file upload (Drag-and-Drop)** [cite: 5.7] พร้อม virus scanning feedback
* **File Type Indicators:** UI ต้องอนุญาตให้ผู้ใช้กำหนดว่าไฟล์ใดเป็น **"เอกสารหลัก"** หรือ "เอกสารแนบประกอบ" [cite: 5.7] พร้อมแสดง file type icons
* **Security Feedback:** แสดง security warnings สำหรับ file types ที่เสี่ยงหรือ files ที่ fail virus scan
* ส่ง (Submit) ผ่าน API พร้อม feedback แบบ toast
### **9.3 ข้อกำหนด Component เฉพาะ (Specific UI Requirements)**
* **Dashboard - My Tasks:** ต้องพัฒนา Component ตาราง "งานของฉัน" (My Tasks)ซึ่งดึงข้อมูลงานที่ผู้ใช้ล็อกอินอยู่ต้องรับผิดชอบ (Main/Action) จาก v_user_tasks [cite: 5.3]
* **Workflow Visualization:** ต้องพัฒนา Component สำหรับแสดงผล Workflow (โดยเฉพาะ RFA)ที่แสดงขั้นตอนทั้งหมดเป็นลำดับ โดยขั้นตอนปัจจุบัน (active) เท่านั้นที่ดำเนินการได้ และขั้นตอนอื่นเป็น disabled [cite: 5.6] ต้องมีตรรกะสำหรับ Admin ในการ override หรือย้อนกลับขั้นตอนได้ [cite: 5.6]
* **Admin Panel:** ต้องมีหน้า UI สำหรับ Superadmin/Admin เพื่อจัดการข้อมูลหลัก (Master Data [cite: 4.5]), การเริ่มต้นใช้งาน (Onboarding [cite: 4.6]), และ **รูปแบบเลขที่เอกสาร (Numbering Formats [cite: 3.10])**
* **Security Dashboard:** แสดง security metrics และ audit logs สำหรับ administrators
## 🧭 **10. แดชบอร์ดและฟีดกิจกรรม (Dashboard & Activity Feed)**
### **10.1 การ์ดบนแดชบอร์ด (Dashboard Cards)**
* แสดง Correspondences, RFAs, Circulations, Shop Drawing Revision ล่าสุด
* รวมสรุป KPI (เช่น "RFAs ที่รอการอนุมัติ", "Shop Drawing ที่รอการอนุมัติ") [cite: 5.3]
* รวมลิงก์ด่วนไปยังโมดูลต่างๆ
* **Security Metrics:** แสดงจำนวน files scanned, security incidents, failed login attempts
### **10.2 ฟีดกิจกรรม (Activity Feed)**
* แสดงรายการ v_audit_log_details ล่าสุด (10 รายการ) ที่เกี่ยวข้องกับผู้ใช้
* รวม security-related activities (failed logins, permission changes)
```typescript
// ตัวอย่าง API response
[
{ user: 'editor01', action: 'Updated RFA (LCBP3-RFA-001)', time: '2025-11-04T09:30Z' },
{ user: 'system', action: 'Virus scan completed - 0 threats found', time: '2025-11-04T09:25Z' }
]
```
## 🛡️ **11. ข้อกำหนดที่ไม่ใช่ฟังก์ชันการทำงาน (Non-Functional Requirements)**
ส่วนนี้สรุปข้อกำหนด Non-Functional จาก requirements.md เพื่อให้ทีมพัฒนาทาน
* **Audit Log [cite: 6.1]:** ทุกการกระทำที่สำคัญ (C/U/D) ต้องถูกบันทึกใน audit_logs
* **Performance [cite: 6.4]:** ต้องใช้ Caching สำหรับข้อมูลที่เรียกบ่อย และใช้ Pagination
* **Security [cite: 6.5]:** ต้องมี Rate Limiting และจัดการ Secret ผ่าน docker-compose.yml (ไม่ใช่ .env)
* **File Security [cite: 3.9.6]:** ต้องมี virus scanning, file type validation, access controls
* **Resilience [cite: 6.5.3]:** ต้องมี circuit breaker, retry mechanisms, graceful degradation
* **Backup & Recovery [cite: 6.6]:** ต้องมีแผนสำรองข้อมูลทั้ง Database (MariaDB) และ File Storage (/share/dms-data) อย่างน้อยวันละ 1 ครั้ง
* **Notification Strategy [cite: 6.7]:** ระบบแจ้งเตือน (Email/Line) ต้องถูก Trigger เมื่อมีเอกสารใหม่ส่งถึง, มีการมอบหมายงานใหม่ (Circulation), หรือ (ทางเลือก) เมื่องานเสร็จ/ใกล้ถึงกำหนด
* **Monitoring [cite: 6.8]:** ต้องมี health checks, metrics collection, alerting
## ✅ **12. มาตรฐานที่นำไปใช้แล้ว (จาก SQL v1.4.0) (Implemented Standards (from SQL v1.4.0))**
ส่วนนี้ยืนยันว่าแนวทางปฏิบัติที่ดีที่สุดต่อไปนี้เป็นส่วนหนึ่งของการออกแบบฐานข้อมูลอยู่แล้ว และควรถูกนำไปใช้ประโยชน์ ไม่ใช่สร้างขึ้นใหม่
* ✅ **Soft Delete:** นำไปใช้แล้วผ่านคอลัมน์ deleted_at ในตารางสำคัญ (เช่น correspondences, rfas, project_parties) ตรรกะการดึงข้อมูลต้องกรอง deleted_at IS NULL
* ✅ **Database Indexes:** สคีมาได้มีการทำ index ไว้อย่างหนักหน่วงบน foreign keys และคอลัมน์ที่ใช้ค้นหาบ่อย (เช่น idx_rr_rfa, idx_cor_project, idx_cr_is_current) เพื่อประสิทธิภาพ
* ✅ **โครงสร้าง RBAC:** มีระบบ users, roles, permissions, user_roles, และ user_project_roles ที่ครอบคลุมอยู่แล้ว
* ✅ **Data Seeding:** ข้อมูล Master (roles, permissions, organization_roles, initial users, project parties) ถูกรวมอยู่ในสคริปต์สคีมาแล้ว
* ✅ **Application-level Locking:** ใช้ Redis distributed lock แทน stored procedure
* ✅ **File Security:** Virus scanning, file type validation, access control
* ✅ **Resilience Patterns:** Circuit breaker, retry, fallback mechanisms
* ✅ **Security Measures:** Input validation, rate limiting, security headers
* ✅ **Monitoring:** Health checks, metrics collection, distributed tracing
## 🧩 **13. การปรับปรุงที่แนะนำ (สำหรับอนาคต) (Recommended Enhancements (Future))**
* ✅ สร้าง Background job (โดยใช้ **n8n** เพื่อเชื่อมต่อกับ **Line** [cite: 2.7] และ/หรือใช้สำหรับการแจ้งเตือน RFA ที่ใกล้ถึงกำหนด due_date [cite: 6.7])
* ✅ เพิ่ม job ล้างข้อมูลเป็นระยะสำหรับ attachments ที่ไม่ถูกเชื่อมโยงกับ Entity ใดๆ เลย (ไฟล์กำพร้า)
* 🔄 **AI-Powered Document Classification:** ใช้ machine learning สำหรับ automatic document categorization
* 🔄 **Advanced Analytics:** Predictive analytics สำหรับ workflow optimization
* 🔄 **Mobile App:** Native mobile application สำหรับ field workers
* 🔄 **Blockchain Integration:** สำหรับ document integrity verification ที่ต้องการความปลอดภัยสูงสุด
## ✅ **14. Summary Checklist for Developers**
ก่อนส่ง PR (Pull Request) นักพัฒนาต้องตรวจสอบหัวข้อต่อไปนี้:
* [ ] **Security:** ไม่มี Secrets ใน Code, ใช้ `docker-compose.override.yml` แล้ว
* [ ] **Concurrency:** ใช้ Optimistic Lock ใน Entity ที่เสี่ยง Race Condition แล้ว
* [ ] **Idempotency:** API รองรับ Idempotency Key แล้ว
* [ ] **File Upload:** ใช้ Flow Two-Phase (Temp -> Perm) แล้ว
* [ ] **Mobile:** หน้าจอแสดงผลแบบ Card View บนมือถือได้ถูกต้อง
* [ ] **Performance:** สร้าง Index สำหรับ JSON Virtual Columns แล้ว (ถ้ามี)
---
## 📋 **15. Summary of Key Changes from Previous Version**
### **Security Enhancements:**
1. **File Upload Security** - Virus scanning, file type validation, access controls
2. **Input Validation** - OWASP Top 10 protection, XSS/CSRF prevention
3. **Rate Limiting** - Comprehensive rate limiting strategy
4. **Secrets Management** - Secure handling of sensitive configuration
### **Architecture Improvements:**
1. **Document Numbering** - Changed from Stored Procedure to Application-level Locking
2. **Resilience Patterns** - Circuit breaker, retry mechanisms, fallback strategies
3. **Monitoring & Observability** - Health checks, metrics, distributed tracing
4. **Caching Strategy** - Comprehensive caching with proper invalidation
### **Performance Targets :**
1. **API Response Time** - < 200ms (90th percentile)
2. **Search Performance** - < 500ms
3. **File Upload** - < 30 seconds for 50MB files
4. **Cache Hit Ratio** - > 80%
### **Operational Excellence:**
1. **Disaster Recovery** - RTO < 4 hours, RPO < 1 hour
2. **Backup Procedures** - Comprehensive backup and restoration
3. **Security Testing** - Penetration testing and security audits
4. **Performance Testing** - Load testing with realistic workloads
เอกสารนี้สะท้อนถึงความมุ่งมั่นในการสร้างระบบที่มีความปลอดภัย, มีความทนทาน, และมีประสิทธิภาพสูง พร้อมรองรับการเติบโตในอนาคตและความต้องการทางธุรกิจที่เปลี่ยนแปลงไป
**หมายเหตุ:** แนวทางนี้จะถูกทบทวนและปรับปรุงเป็นระยะตาม feedback จากทีมพัฒนาและความต้องการทางธุรกิจที่เปลี่ยนแปลงไป
## **Document Control:**
* **Document:** FullStackJS v1.4.4
* **Version:** 1.4
* **Date:** 2025-11-26
* **Author:** NAP LCBP3-DMS & Gemini
* **Status:** FINAL-Rev.04
* **Classification:** Internal Technical Documentation
* **Approved By:** Nattanin
---
`End of FullStackJS Guidelines v1.4.4`

397
infrastructure/Markdown/2_Backend_Plan_Phase6A_V1_4_3.md Normal file
View File

@@ -0,0 +1,397 @@
# “Phase 6A + Technical Design Document : Workflow DSL (Mini-Language)”**
ออกแบบสำหรับระบบ Workflow Engine กลางของโครงการ
**ไม่มีโค้ดผูกกับ Framework** เพื่อให้สามารถนำไป Implement ใน NestJS หรือ Microservice ใด ๆ ได้
---
## 📌 **Phase 6A – Workflow DSL Implementation Plan**
### 🎯 เป้าหมายของ Phase 6A
ใน Phase นี้ จะเริ่มสร้าง “Workflow DSL (Domain-Specific Language)” สำหรับนิยามกฎการเดินงาน (Workflow Transition Rules) ให้สามารถ:
* แยก **Business Workflow Logic** ออกจาก Source Code
* แก้ไขกฎ Workflow ได้โดย **ไม่ต้องแก้โค้ดและไม่ต้อง Deploy ใหม่**
* รองรับ Document หลายประเภท เช่น
* Correspondence
* RFA
* Internal Circulation
* Document Transmittal
* รองรับ Multi-step routing, skip, reject, rollback, parallel assignments
* สามารถนำไปใช้งานทั้งใน
* Backend (NestJS)
* Frontend (UI Driven)
* External Microservices
---
### 📅 ระยะเวลา
**1 สัปดาห์ (หลัง Phase 6.5)**
---
### 🧩 Output ของ Phase 6A
* DSL Specification (Grammar)
* JSON Schema for Workflow Definition
* Workflow Rule Interpreter (Parser + Executor)
* Validation Engine (Compile-time and Runtime)
* Storage (DB Table / Registry)
* Execution API:
| Action | Description |
| -------------------------------- | ------------------------------- |
| compile() | ตรวจ DSL → สร้าง Execution Tree |
| evaluate(state, action, context) | ประมวลผลและส่งสถานะใหม่ |
| preview(state) | คำนวณ Next Possible Transitions |
| validate() | ตรวจว่า DSL ถูกต้อง |
---
## 📘 **Technical Specification – Workflow DSL**
---
### 1️⃣ Requirements
#### Functional Requirements
* นิยาม Workflow เป็นภาษาคล้าย State Machine
* แต่ละเอกสารมี **State, Actions, Entry/Exit Events**
* สามารถมี:
* Required approvals
* Conditional transition
* Auto-transition
* Parallel approval
* Return/rollback
####
* Running time: < 20ms ต่อคำสั่ง
* Hot reload ไม่ต้อง Compile ใหม่ทั้ง Backend
* DSL ต้อง Debug ได้ง่าย
* ต้อง Versioned
* ต้องรองรับ Audit 100%
---
### 2️⃣ DSL Format (Human Friendly)
```yaml
workflow: RFA
version: 1.0
states:
- name: DRAFT
initial: true
on:
SUBMIT:
to: IN_REVIEW
require:
- role: ENGINEER
events:
- notify: reviewer
- name: IN_REVIEW
on:
APPROVE:
to: APPROVED
REJECT:
to: DRAFT
events:
- notify: creator
- name: APPROVED
terminal: true
```
---
### 3️⃣ Compiled Execution Model (Normalized JSON)
```json
{
"workflow": "RFA",
"version": "1.0",
"states": {
"DRAFT": {
"initial": true,
"transitions": {
"SUBMIT": {
"to": "IN_REVIEW",
"requirements": [
{ "role": "ENGINEER" }
],
"events": [
{ "type": "notify", "target": "reviewer" }
]
}
}
},
"IN_REVIEW": {
"transitions": {
"APPROVE": { "to": "APPROVED" },
"REJECT": {
"to": "DRAFT",
"events": [
{ "type": "notify", "target": "creator" }
]
}
}
},
"APPROVED": {
"terminal": true
}
}
}
```
Frontend และ Backend สามารถแชร์ JSON นี้ร่วมกันได้
---
### 4️⃣ DSL Grammar Definition (EBNF)
```ebnf
workflow = "workflow" ":" identifier ;
version = "version" ":" number ;
states = "states:" state_list ;
state_list = { state } ;
state = "- name:" identifier
[ "initial:" boolean ]
[ "terminal:" boolean ]
[ "on:" transition_list ] ;
transition_list = { transition } ;
transition = action ":"
indent "to:" identifier
[ indent "require:" requirements ]
[ indent "events:" event_list ] ;
requirements = "- role:" identifier | "- user:" identifier ;
event_list = { event } ;
event = "- notify:" identifier ;
```
---
### 5️⃣ Validation Rules (Compile-Time)
#### 5.1 State Rules
* ต้องมีอย่างน้อย 1 state ที่ `initial: true`
* หาก `terminal: true` → ต้องไม่มี transition ต่อไป
#### 5.2 Transition Rules
ตรวจสอบว่า:
* `to` ชี้ไปยัง state ที่มีอยู่
* `require.role` ต้องเป็น role ที่ระบบรู้จัก
* Action name ต้องเป็น **UPPER_CASE**
#### 5.3 Version Safety
* ทุกชุด Workflow DSL ต้องขึ้นกับ version
* แก้ไขต้องสร้าง version ใหม่
* ไม่ overwrite version เก่า
* “Document ที่กำลังอยู่ใน step เดิมยังต้องใช้กฎเดิมได้”
---
### 6️⃣ Runtime Validation Rules
เมื่อ execute(action):
```
input: current_state, action, context
1) ตรวจว่า state มี transition "action"
2) ตรวจว่าผู้ใช้มีสิทธิ์ตาม require[]
3) Compute next state
4) Execute events[]
5) Return next_state
```
---
### 7️⃣ Context Model
```ts
interface WorkflowContext {
userId: string;
roles: string[];
documentId: string;
now: Date;
payload?: any;
}
```
---
### 8️⃣ Execution API (Abstract)
```ts
class WorkflowEngine {
load(dsl: string | object): CompiledWorkflow
compile(dsl: string | object): CompiledWorkflow
evaluate(state: string, action: string, context: WorkflowContext): EvalResult
getAvailableActions(state: string, context: WorkflowContext): string[]
}
```
---
### 9️⃣ Interpreter Execution Flow
```mermaid
flowchart TD
A[Receive Action] --> B[Load Compiled Workflow]
B --> C[Check allowed actions]
C -->|Invalid| E[Return Error]
C --> D[Evaluate Requirements]
D --> F[Transition to Next State]
F --> G[Run Events]
G --> H[Return Success]
```
---
### 🔟 Events System
รองรับ event หลายประเภท:
| event.type | ตัวอย่าง |
| ----------- | ------------------------- |
| notify | ส่ง Email/Line |
| assign | เปลี่ยนผู้รับผิดชอบ |
| webhook | ยิง Webhook ไปยังระบบอื่น |
| auto_action | ทำ action ซ้ำโดยอัตโนมัติ |
---
### 11️⃣ Database Schema
#### Table: `workflow_definition`
| Field | Type | Description |
| ------------- | ----------- | --------------------- |
| id | UUID | PK |
| workflow_code | varchar(50) | เช่น `RFA`, `CORR` |
| version | int | Version number |
| dsl | JSON | YAML/JSON DSL เก็บดิบ |
| compiled | JSON | JSON ที่ Compile แล้ว |
| created_at | timestamp | |
| is_active | boolean | ใช้อยู่หรือไม่ |
#### Table: `workflow_history`
เก็บ audit แบบ immutable append-only
| Field | Description |
| ----------- | --------------- |
| workflow | Document Type |
| document_id | เอกสารไหน |
| from_state | เดิม |
| to_state | ใหม่ |
| action | คำสั่ง |
| user | ใครเป็นคนทำ |
| timestamp | เวลา |
| metadata | เหตุการณ์อื่น ๆ |
---
### 12️⃣ Error Codes
| Code | Meaning |
| ----------------------- | ---------------------- |
| WF_NO_TRANSITION | Action นี้ไม่ถูกต้อง |
| WF_RESTRICTED | User ไม่มีสิทธิ์ |
| WF_MISSING_REQUIREMENTS | ไม่ผ่านเงื่อนไข |
| WF_STATE_NOT_FOUND | ไม่มี state ที่อ้างอิง |
| WF_SYNTAX_ERROR | DSL ผิดรูปแบบ |
---
### 13️⃣ Testing Strategy
#### Unit Tests
* Parse DSL → JSON
* Invalid syntax → throw error
* Invalid transitions → throw error
#### Integration Tests
* Evaluate() ผ่าน 20+ cases
* RFA ย้อนกลับ
* Approve chain
* Parallel review
#### Load Tests
* 1,000 documents running workflow
* Evaluate < 20ms ต่อ action
---
### 14️⃣ Deployment Strategy
#### Hot Reload Options
* DSL stored in DB
* Cache in Redis
* Touched timestamp triggers:
```
invalidate cache → recompile
```
#### No downtime required
---
### 15️⃣ Microservice-Ready
DSL Engine แยกเป็น:
* `workflow-engine-core` → Pure JS library
* `workflow-service` → NestJS module
* API public:
```
POST /workflow/evaluate
GET /workflow/preview
POST /workflow/compile
```
ภายหลังสามารถนำไปวางบน:
* Kubernetes
* Worker Node
* API Gateway
---
## 🎉 Summary
### สิ่งที่ Phase 6A เพิ่มเข้าในระบบ
✔ Workflow DSL ที่แก้ไขได้โดยไม่ต้อง Deploy
✔ Parser + Validator + Runtime Interpreter
✔ Database storage + Versioning
✔ Execution API สำหรับ Backend และ Frontend
✔ รองรับ Business Workflow ซับซ้อนทั้งหมด
✔ Ready สำหรับ Microservice model ในอนาคต

552
infrastructure/Markdown/2_Backend_Plan_V1_4_3.md Normal file
View File

@@ -0,0 +1,552 @@
# 📋 **แผนการพัฒนา Backend (NestJS) - LCBP3-DMS v1.4.3 (ฉบับปรับปรุง)**
**สถานะ:** FINAL GUIDELINE Rev.01
**วันที่:** 2025-11-22
**อ้างอิง:** Requirements v1.4.3 & FullStackJS Guidelines v1.4.3
**Classification:** Internal Technical Documentation
-----
## 🎯 **ภาพรวมโครงการ**
พัฒนา Backend สำหรับระบบบริหารจัดการเอกสารโครงการ (Document Management System) ที่มีความปลอดภัยสูง รองรับการทำงานพร้อมกัน (Concurrency) ได้อย่างถูกต้องแม่นยำ มีสถาปัตยกรรมที่ยืดหยุ่นต่อการขยายตัว และรองรับการจัดการเอกสารที่ซับซ้อน มีระบบ Workflow การอนุมัติ และการควบคุมสิทธิ์แบบ RBAC 4 ระดับ พร้อมมาตรการความปลอดภัยที่ทันสมัย
-----
## 📐 **สถาปัตยกรรมระบบ**
### **Technology Stack (Updated)**
- **Framework:** NestJS (TypeScript, ESM)
- **Database:** MariaDB 10.11 (ใช้ Virtual Columns)
- **ORM:** TypeORM (ใช้ Optimistic Locking)
- **Authentication:** JWT + Passport
- **Authorization:** CASL (RBAC 4-level)
- **File Upload:** Multer + Virus Scanning (ClamAV) + Two-Phase Storage
- **Search:** Elasticsearch
- **Notification:** Nodemailer + n8n (Line Integration) + BullMQ Queue
- **Caching/Locking:** Redis (Redlock) สำหรับ Distributed Locking
- **Queue:** BullMQ (Redis) สำหรับ Notification Batching และ Async Jobs
- **Resilience:** Circuit Breaker, Retry Patterns
- **Security:** Helmet, CSRF Protection, Rate Limiting, Idempotency
- **Monitoring:** Winston, Health Checks, Metrics
- **Scheduling:** @nestjs/schedule (Cron Jobs)
- **Documentation:** Swagger
- **Validation:** Zod / Class-validator
### **โครงสร้างโมดูล (Domain-Driven)**
```tree
src/
├── common/ # Shared Module
│ ├── auth/ # JWT, Guards, RBAC
│ ├── config/ # Configuration Management
│ ├── decorators/ # @RequirePermission, @RateLimit
│ ├── entities/ # Base Entities
│ ├── exceptions/ # Global Filters
│ ├── file-storage/ # FileStorageService (Virus Scanning + Two-Phase)
│ ├── guards/ # RBAC Guard, RateLimitGuard
│ ├── interceptors/ # Audit, Transform, Performance, Idempotency
│ ├── resilience/ # Circuit Breaker, Retry Patterns
│ ├── security/ # Input Validation, XSS Protection
│ ├── idempotency/ # [New] Idempotency Logic
│ └── maintenance/ # [New] Maintenance Mode Guard
├── modules/
│ ├── user/ # Users, Roles, Permissions
│ ├── project/ # Projects, Contracts, Organizations
│ ├── master/ # Master Data Management
│ ├── correspondence/ # Correspondence Management
│ ├── rfa/ # RFA & Workflows
│ ├── drawing/ # Shop/Contract Drawings
│ ├── circulation/ # Internal Circulation
│ ├── transmittal/ # Transmittals
│ ├── search/ # Elasticsearch
│ ├── monitoring/ # Metrics, Health Checks
│ ├── workflow-engine/ # [New] Unified Workflow Logic
│ ├── document-numbering/ # [Update] Double-Locking Logic
│ ├── notification/ # [Update] Queue & Digest
│ └── file-storage/ # [Update] Two-Phase Commit
└── database/ # Migrations & Seeds
```
-----
## 🗓️ **แผนการพัฒนาแบบ Phase-Based**
- *(Dependency Diagram ถูกละไว้เพื่อประหยัดพื้นที่ เนื่องจากมีการอ้างอิงจากแผนเดิม)*
## **Phase 0: Infrastructure & Configuration (สัปดาห์ที่ 1)**
**Milestone:** โครงสร้างพื้นฐานพร้อม รองรับ Secrets ที่ปลอดภัย และ Redis พร้อมใช้งาน
### **Phase 0: Tasks**
- **[ ] T0.1 Secure Configuration Setup**
- [ ] ปรับปรุง `ConfigModule` ให้รองรับการอ่านค่าจาก Environment Variables
- [ ] สร้าง Template `docker-compose.override.yml.example` สำหรับ Dev
- [ ] Validate Config ด้วย Joi/Zod ตอน Start App (Throw error ถ้าขาด Secrets)
- [ ] **Security:** Setup network segmentation และ firewall rules
- [ ] **Deliverable:** Configuration Management พร้อมใช้งานอย่างปลอดภัย
- [ ] **Dependencies:** None (Task เริ่มต้น)
- **[ ] T0.2 Redis & Queue Infrastructure**
- [ ] Setup Redis Container
- [ ] Setup BullMQ Module ใน NestJS สำหรับจัดการ Background Jobs
- [ ] Setup Redis Client สำหรับ Distributed Lock (Redlock)
- [ ] **Security:** Setup Redis authentication และ encryption
- [ ] **Deliverable:** Redis และ Queue System พร้อมใช้งาน
- [ ] **Dependencies:** T0.1
- **[ ] T0.3 Setup Database Connection**
- [ ] Import SQL Schema v1.4.2 เข้า MariaDB
- [ ] Run Seed Data (organizations, users, roles, permissions)
- [ ] Configure TypeORM ใน AppModule
- [ ] **Security:** Setup database connection encryption
- [ ] ทดสอบ Connection
- [ ] **Deliverable:** Database พร้อมใช้งาน, มี Seed Data
- [ ] **Dependencies:** T0.1
- **[ ] T0.4 Setup Git Repository**
- [ ] สร้าง Repository ใน Gitea (git.np-dms.work)
- [ ] Setup .gitignore, README.md, SECURITY.md
- [ ] Commit Initial Project
- [ ] **Deliverable:** Code อยู่ใน Version Control
- [ ] **Dependencies:** T0.1, T0.2, T0.3
-----
## **Phase 1: Core Foundation & Security (สัปดาห์ที่ 2-3)**
**Milestone:** ระบบ Authentication, Authorization, Idempotency พื้นฐาน และ Security Baseline
### **Phase 1: Tasks**
- **[ ] T1.1 CommonModule - Base Infrastructure**
- [ ] สร้าง Base Entity (id, created_at, updated_at, deleted_at)
- [ ] สร้าง Global Exception Filter (ไม่เปิดเผย sensitive information)
- [ ] สร้าง Response Transform Interceptor
- [ ] สร้าง Audit Log Interceptor
- [ ] **[New] Idempotency Interceptor:** ตรวจสอบ Header `Idempotency-Key` และ Cache Response เดิมใน Redis
- [ ] **[New] Maintenance Mode Middleware:** ตรวจสอบ Flag ใน **Redis Key** เพื่อ Block API ระหว่างปรับปรุงระบบ **(Admin ใช้ Redis/Admin UI ในการ Toggle สถานะ)**
- [ ] สร้าง RequestContextService - สำหรับเก็บข้อมูลระหว่าง Request
- [ ] สร้าง ConfigService - Centralized configuration management
- [ ] สร้าง CryptoService - สำหรับ encryption/decryption
- [ ] **Security:** Implement input validation pipeline
- [ ] **Deliverable:** Common Services พร้อมใช้ รวมถึง Idempotency และ Maintenance Mode
- [ ] **Dependencies:** T0.2, T0.3
- **[ ] T1.2 AuthModule - JWT Authentication**
- [ ] สร้าง Entity: User
- [ ] สร้าง AuthService:
- [ ] login(username, password) → JWT Token
- [ ] validateUser(username, password) → User | null
- [ ] Password Hashing (bcrypt) + salt
- [ ] สร้าง JWT Strategy (Passport)
- [ ] สร้าง JwtAuthGuard
- [ ] สร้าง Controllers:
- [ ] POST /auth/login → { access_token, refresh_token }
- [ ] POST /auth/register → Create User (Admin only)
- [ ] POST /auth/refresh → Refresh token
- [ ] POST /auth/logout → Revoke token
- [ ] GET /auth/profile (Protected)
- [ ] **Security:** Implement rate limiting สำหรับ authentication endpoints
- [ ] **Deliverable:** ล็อกอิน/ล็อกเอาต์ทำงานได้อย่างปลอดภัย
- [ ] **Dependencies:** T1.1, T0.3
- **[ ] T1.3 UserModule - User Management**
- [ ] สร้าง Entities: User, Role, Permission, UserRole, UserAssignment, **UserPreference**
- [ ] สร้าง UserService CRUD (พร้อม soft delete)
- [ ] สร้าง RoleService CRUD
- [ ] สร้าง PermissionService (Read-Only, จาก Seed)
- [ ] สร้าง UserAssignmentService - สำหรับจัดการ user assignments ตาม scope
- [ ] สร้าง **UserPreferenceService** - สำหรับจัดการการตั้งค่า Notification และ UI
- [ ] สร้าง Controllers:
- [ ] GET /users → List Users (Paginated)
- [ ] GET /users/:id → User Detail
- [ ] POST /users → Create User (ต้องบังคับเปลี่ยน password ครั้งแรก)
- [ ] PUT /users/:id → Update User
- [ ] DELETE /users/:id → Soft Delete
- [ ] GET /roles → List Roles
- [ ] POST /roles → Create Role (Admin)
- [ ] PUT /roles/:id/permissions → Assign Permissions
- [ ] **Security:** Implement permission checks สำหรับ user management
- [ ] **Deliverable:** จัดการผู้ใช้, Role, และ Preferences ได้
- [ ] **Dependencies:** T1.1, T1.2
- **[ ] T1.4 RBAC Guard - 4-Level Authorization**
- [ ] สร้าง @RequirePermission() Decorator
- [ ] สร้าง RbacGuard ที่ตรวจสอบ 4 ระดับ:
- [ ] Global Permissions
- [ ] Organization Permissions
- [ ] Project Permissions
- [ ] Contract Permissions
- [ ] Permission Hierarchy Logic
- [ ] Integration กับ CASL
- [ ] **Security:** Implement audit logging สำหรับ permission checks
- [ ] **Deliverable:** ระบบสิทธิ์ทำงานได้ทั้ง 4 ระดับ
- [ ] **Dependencies:** T1.1, T1.3
- **[ ] T1.5 ProjectModule - Base Structures**
- [ ] สร้าง Entities:
- [ ] Organization
- [ ] Project
- [ ] Contract
- [ ] ProjectOrganization (Junction)
- [ ] ContractOrganization (Junction)
- [ ] สร้าง Services & Controllers:
- [ ] GET /organizations → List
- [ ] POST /projects → Create (Superadmin)
- [ ] GET /projects/:id/contracts → List Contracts
- [ ] POST /projects/:id/contracts → Create Contract
- [ ] **Security:** Implement data isolation ระหว่าง organizations
- [ ] **Deliverable:** จัดการโครงสร้างโปรเจกต์ได้
- [ ] **Dependencies:** T1.1, T1.2, T0.3
-----
## **Phase 2: High-Integrity Data & File Management (สัปดาห์ที่ 4)**
**Milestone:** Master Data, ระบบจัดการไฟล์แบบ Transactional, Document Numbering ที่ไม่มี Race Condition, JSON details system พร้อมใช้งาน
### **Phase 2: Tasks**
- **[ ] T2.1 Virtual Columns for JSON**
- [ ] ออกแบบ Migration Script สำหรับตารางที่มี JSON Details
- [ ] เพิ่ม **Generated Columns (Virtual)** สำหรับฟิลด์ที่ใช้ Search บ่อยๆ (เช่น `project_id`, `type`) พร้อม Index
- [ ] **Security:** Implement admin-only access สำหรับ master data
- [ ] **Deliverable:** JSON Data Search Performance ดีขึ้น
- [ ] **Dependencies:** T0.3, T1.1, T1.5
- **[ ] T2.2 FileStorageService - Two-Phase Storage**
- [ ] สร้าง Attachment Entity
- [ ] สร้าง FileStorageService:
- [ ] **Phase 1 (Upload):** API รับไฟล์ → Scan Virus → Save ลง `temp/` → Return `temp_id`
- [ ] **Phase 2 (Commit):** Method `commitFiles(tempIds[])` → ย้ายจาก `temp/` ไป `permanent/{YYYY}/{MM}/` → Update DB
- [ ] File type validation (white-list: PDF, DWG, DOCX, XLSX, PPTX, ZIP)
- [ ] File size check (max 50MB)
- [ ] Generate checksum (SHA-256)
- [ ] **Cleanup Job:** สร้าง Cron Job ลบไฟล์ใน `temp/` ที่ค้างเกิน 24 ชม. **โดยตรวจสอบจากคอลัมน์ `expires_at` ในตาราง `attachments`**
- [ ] สร้าง Controller:
- [ ] POST /files/upload → { temp_id } (Protected)
- [ ] POST /files/commit → { attachment_id, url } (Protected)
- [ ] GET /files/:id/download → File Stream (Protected + Expiration)
- [ ] **Security:** Access Control - ตรวจสอบสิทธิ์ผ่าน Junction Table
- [ ] **Deliverable:** อัปโหลด/ดาวน์โหลดไฟล์ได้อย่างปลอดภัย แบบ Transactional
- [ ] **Dependencies:** T1.1, T1.4
- **[ ] T2.3 DocumentNumberingModule - Double-Lock Mechanism**
- [ ] สร้าง Entities:
- [ ] DocumentNumberFormat
- [ ] DocumentNumberCounter
- [ ] สร้าง DocumentNumberingService:
- [ ] generateNextNumber(projectId, orgId, typeId, year) → string
- [ ] ใช้ **Double-Lock Mechanism**:
1. Acquire **Redis Lock** (Key: `doc_num:{project}:{type}`)
2. Read DB & Calculate Next Number
3. Update DB with **Optimistic Lock** Check (ใช้ `@VersionColumn()`)
4. Release Redis Lock
5. Retry on Failure ด้วย exponential backoff
- [ ] Fallback mechanism เมื่อการขอเลขล้มเหลว
- [ ] Format ตาม Template: {ORG_CODE}-{TYPE_CODE}-{YEAR_SHORT}-{SEQ:4}
- **ไม่มี Controller** (Internal Service เท่านั้น)
- [ ] **Security:** Implement audit log ทุกครั้งที่มีการ generate เลขที่
- [ ] **Deliverable:** Service สร้างเลขที่เอกสารได้ถูกต้องและปลอดภัย ไม่มี Race Condition
- [ ] **Dependencies:** T1.1, T0.3
- **[ ] T2.4 SecurityModule - Enhanced Security**
- [ ] สร้าง Input Validation Service:
- [ ] XSS Prevention
- [ ] SQL Injection Prevention
- [ ] CSRF Protection
- [ ] สร้าง RateLimitGuard:
- [ ] Implement rate limiting ตาม strategy (anonymous: 100/hr, authenticated: 500-5000/hr)
- [ ] Different limits สำหรับ endpoints ต่างๆ
- [ ] สร้าง Security Headers Middleware
- [ ] **Security:** Implement content security policy (CSP)
- [ ] **Deliverable:** Security layers ทำงานได้
- [ ] **Dependencies:** T1.1
- **[ ] T2.5 JSON Details & Schema Management**
- [ ] T2.5.1 JsonSchemaModule - Schema Management: สร้าง Service สำหรับ Validate, get, register JSON schemas
- [ ] T2.5.2 DetailsService - Data Processing: สร้าง Service สำหรับ sanitize, transform, compress/decompress JSON
- [ ] T2.5.3 JSON Security & Validation: Implement security checks และ validation rules
- [ ] **Deliverable:** JSON schema system ทำงานได้
- [ ] **Dependencies:** T1.1
-----
## **Phase 3: Unified Workflow Engine (สัปดาห์ที่ 5-6)**
**Milestone:** ระบบ Workflow กลางที่รองรับทั้ง Routing ปกติ และ RFA
### **Phase 3: Tasks**
- **[ ] T3.1 WorkflowEngineModule (New)**
- [ ] ออกแบบ Generic Schema สำหรับ Workflow State Machine
- [ ] Implement Service: `initializeWorkflow()`, `processAction()`, `getNextStep()`
- [ ] รองรับ Logic การ "ข้ามขั้นตอน" และ "ส่งกลับ" ภายใน Engine เดียว
- [ ] **Security:** Implement audit logging สำหรับ workflow actions
- [ ] **Deliverable:** Unified Workflow Engine พร้อมใช้งาน
- [ ] **Dependencies:** T1.1
- **[ ] T3.2 CorrespondenceModule - Basic CRUD**
- [ ] สร้าง Entities (Correspondence, Revision, Recipient, Tag, Reference, Attachment)
- [ ] สร้าง CorrespondenceService (Create with Document Numbering, Update with new Revision, Soft Delete)
- [ ] สร้าง Controllers (POST/GET/PUT/DELETE /correspondences)
- [ ] [New] Implement Impersonation Logic: ตรวจสอบ originatorId ใน DTO หากมีการส่งมา ต้องเช็คว่า User ปัจจุบันมีสิทธิ์กระทำการแทนหรือไม่ (Superadmin)
- [ ] **Security:** Implement permission checks สำหรับ document access
- [ ] **Deliverable:** สร้าง/แก้ไข/ดูเอกสารได้
- [ ] **Dependencies:** T1.1, T1.2, T1.3, T1.4, T1.5, T2.3, T2.2, T2.5
- **[ ] T3.3 CorrespondenceModule - Advanced Features**
- [ ] Implement Status Transitions (DRAFT → SUBMITTED)
- [ ] Implement References (Link Documents)
- [ ] Implement Search (Basic)
- [ ] **Security:** Implement state transition validation
- [ ] **Deliverable:** Workflow พื้นฐานทำงานได้
- [ ] **Dependencies:** T3.2
- **[ ] T3.4 Correspondence Integration with Workflow**
- [ ] เชื่อมต่อ `CorrespondenceService` เข้ากับ `WorkflowEngineModule`
- [ ] ย้าย Logic การ Routing เดิมมาใช้ Engine ใหม่
- [ ] สร้าง API endpoints สำหรับ Frontend (Templates, Pending Tasks, Bulk Action)
- [ ] **Security:** Implement permission checks สำหรับ workflow operations
- [ ] **Deliverable:** ระบบส่งต่อเอกสารทำงานได้สมบูรณ์ด้วย Unified Engine
- [ ] **Dependencies:** T3.1, T3.2
-----
## **Phase 4: Drawing & Advanced Workflows (สัปดาห์ที่ 7-8)**
**Milestone:** การจัดการแบบและ RFA โดยใช้ Unified Engine
### **Phase 4: Tasks**
- **[ ] T4.1 DrawingModule - Contract Drawings**
- [ ] สร้าง Entities (ContractDrawing, Volume, Category, SubCategory, Attachment)
- [ ] สร้าง ContractDrawingService CRUD
- [ ] สร้าง Controllers (GET/POST /drawings/contract)
- [ ] **Security:** Implement access control สำหรับ contract drawings
- [ ] **Deliverable:** จัดการ Contract Drawings ได้
- [ ] **Dependencies:** T1.1, T1.2, T1.4, T1.5, T2.2
- **[ ] T4.2 DrawingModule - Shop Drawings**
- [ ] สร้าง Entities (ShopDrawing, Revision, Main/SubCategory, ContractRef, RevisionAttachment)
- [ ] สร้าง ShopDrawingService CRUD (รวมการสร้าง Revision)
- [ ] สร้าง Controllers (GET/POST /drawings/shop, /drawings/shop/:id/revisions)
- [ ] Link Shop Drawing Revision → Contract Drawings
- [ ] **Security:** Implement virus scanning สำหรับ drawing files
- [ ] **Deliverable:** จัดการ Shop Drawings และ Revisions ได้
- [ ] **Dependencies:** T4.1
- **[ ] T5.1 RfaModule with Unified Workflow**
- [ ] สร้าง Entities (Rfa, RfaRevision, RfaItem, RfaWorkflowTemplate/Step)
- [ ] สร้าง RfaService (Create RFA, Link Shop Drawings)
- [ ] Implement RFA Workflow โดยใช้ Configuration ของ `WorkflowEngineModule`
- [ ] สร้าง Controllers (POST/GET /rfas, POST /rfas/:id/workflow/...)
- [ ] **Resilience:** Implement circuit breaker สำหรับ notification services
- [ ] **Deliverable:** RFA Workflow ทำงานได้ด้วย Unified Engine
- [ ] **Dependencies:** T3.2, T4.2, T2.5, T6.2
-----
## **Phase 5: Workflow Systems & Resilience (สัปดาห์ที่ 8-9)**
**Milestone:** ระบบ Workflow ทั้งหมดพร้อม Resilience Patterns
### **Phase 5: Tasks**
- **[ ] T5.2 CirculationModule - Internal Routing**
- [ ] สร้าง Entities (Circulation, Template, Routing, Attachment)
- [ ] สร้าง CirculationService (Create 1:1 with Correspondence, Assign User, Complete/Close Step)
- [ ] สร้าง Controllers (POST/GET /circulations, POST /circulations/:id/steps/...)
- [ ] **Resilience:** Implement retry mechanism สำหรับ assignment notifications
- [ ] **Deliverable:** ใบเวียนภายในองค์กรทำงานได้
- [ ] **Dependencies:** T3.2, T2.5, T6.2
- **[ ] T5.3 TransmittalModule - Document Forwarding**
- [ ] สร้าง Entities (Transmittal, TransmittalItem)
- [ ] สร้าง TransmittalService (Create Correspondence + Transmittal, Link Multiple Correspondences)
- [ ] สร้าง Controllers (POST/GET /transmittals)
- [ ] **Security:** Implement access control สำหรับ transmittal items
- [ ] **Deliverable:** สร้าง Transmittal ได้
- [ ] **Dependencies:** T3.2
-----
## **Phase 6: Notification & Resilience (สัปดาห์ที่ 9)**
**Milestone:** ระบบแจ้งเตือนแบบ Digest และการจัดการข้อมูลขนาดใหญ่
### **Phase 6: Tasks**
- **[ ] T6.1 SearchModule - Elasticsearch Integration**
- [ ] Setup Elasticsearch Container
- [ ] สร้าง SearchService (index/update/delete documents, search)
- [ ] Index ทุก Document Type
- [ ] สร้าง Controllers (GET /search)
- [ ] **Resilience:** Implement circuit breaker สำหรับ Elasticsearch
- [ ] **Deliverable:** ค้นหาขั้นสูงทำงานได้
- [ ] **Dependencies:** T3.2, T5.1, T4.2, T5.2, T5.3
- **[ ] T6.2 Notification Queue & Digest**
- [ ] สร้าง NotificationService (sendEmail/Line/System)
- [ ] **Producer:** Push Event ลง BullMQ Queue
- [ ] **Consumer:** จัดกลุ่ม Notification (Digest Message) และส่งผ่าน Email/Line
- [ ] Integrate กับ Workflow Events (แจ้ง Recipients, Assignees, Deadline)
- [ ] สร้าง Controllers (GET /notifications, PUT /notifications/:id/read)
- [ ] **Resilience:** Implement retry mechanism ด้วย exponential backoff
- [ ] **Deliverable:** ระบบแจ้งเตือนทำงานได้แบบ Digest
- [ ] **Dependencies:** T1.1, T6.4
- **[ ] T6.3 MonitoringModule - Observability**
- [ ] สร้าง Health Check Controller (GET /health)
- [ ] สร้าง Metrics Service (API response times, Error rates)
- [ ] สร้าง Performance Interceptor (Track request duration)
- [ ] สร้าง Logging Service (Structured logging)
- [ ] **Deliverable:** Monitoring system ทำงานได้
- [ ] **Dependencies:** T1.1
- **[ ] T6.4 ResilienceModule - Circuit Breaker & Retry**
- [ ] สร้าง Circuit Breaker Service (@CircuitBreaker() decorator)
- [ ] สร้าง Retry Service (@Retry() decorator)
- [ ] สร้าง Fallback Strategies
- [ ] Implement สำหรับ Email, LINE, Elasticsearch, Virus Scanning
- [ ] **Deliverable:** Resilience patterns ทำงานได้
- [ ] **Dependencies:** T1.1
- **[ ] T6.5 Data Partitioning Strategy**
- [ ] ออกแบบ Table Partitioning สำหรับ `audit_logs` และ `notifications` (แบ่งตาม Range: Year)
- [ ] เขียน Raw SQL Migration สำหรับสร้าง Partition Table
- [ ] **Deliverable:** Database Performance และ Scalability ดีขึ้น
- [ ] **Dependencies:** T0.3
-----
## **Phase 7: Testing & Hardening (สัปดาห์ที่ 10-12)**
**Milestone:** ทดสอบความทนทานต่อ Race Condition, Security, และ Performance
### **Phase 7: Tasks**
- **[ ] T7.1 Concurrency Testing**
- [ ] เขียน Test Scenarios ยิง Request ขอเลขที่เอกสารพร้อมกัน 100 Request (ต้องไม่ซ้ำและไม่ข้าม)
- [ ] ทดสอบ Optimistic Lock ทำงานถูกต้องเมื่อ Redis ถูกปิด
- [ ] ทดสอบ File Upload พร้อมกันหลายไฟล์
- [ ] **Deliverable:** ระบบทนทานต่อ Concurrency Issues
- **[ ] T7.2 Transaction Integrity Testing**
- [ ] ทดสอบ Upload ไฟล์แล้ว Kill Process ก่อน Commit
- [ ] ทดสอบ Two-Phase File Storage ทำงานถูกต้อง
- [ ] ทดสอบ Database Transaction Rollback Scenarios
- [ ] **Deliverable:** Data Integrity รับประกันได้
- **[ ] T7.3 Security & Idempotency Test**
- [ ] ทดสอบ Replay Attack โดยใช้ `Idempotency-Key` ซ้ำ
- [ ] ทดสอบ Maintenance Mode Block API ได้จริง
- [ ] ทดสอบ RBAC 4-Level ทำงานถูกต้อง 100%
- [ ] **Deliverable:** Security และ Idempotency ทำงานได้ตาม设计要求
- **[ ] T7.4 Unit Testing (80% Coverage)**
- **[ ] T7.5 Integration Testing**
- **[ ] T7.6 E2E Testing**
- **[ ] T7.7 Performance Testing**
- [ ] Load Testing: 100 concurrent users
- [ ] **(สำคัญ)** การจูนและทดสอบ Load Test จะต้องทำในสภาพแวดล้อมที่จำลอง Spec ของ QNAP Server (TS-473A, AMD Ryzen V1500B) เพื่อให้ได้ค่า Response Time และ Connection Pool ที่เที่ยงตรง
- [ ] Stress Testing
- [ ] Endurance Testing
- [ ] **Deliverable:** Performance targets บรรลุ
- **[ ] T7.8 Security Testing**
- [ ] Penetration Testing (OWASP Top 10)
- [ ] Security Audit (Code review, Dependency scanning)
- [ ] File Upload Security Testing
- [ ] **Deliverable:** Security tests ผ่าน
- **[ ] T7.9 Performance Optimization**
- [ ] Implement Caching (Master Data, User Permissions, Search Results)
- [ ] Database Optimization (Review Indexes, Query Optimization, Pagination)
- [ ] **Deliverable:** Response Time < 200ms (90th percentile)
-----
## **Phase 8: Documentation & Deployment (สัปดาห์ที่ 14)**
**Milestone:** เอกสารและ Deploy สู่ Production พร้อม Security Hardening
### **Phase 8: Tasks**
- **[ ] T8.1 API Documentation (Swagger)**
- **[ ] T8.2 Technical Documentation**
- **[ ] T8.3 Security Hardening**
- **[ ] T8.4 Deployment Preparation (QNAP Setup, Nginx Proxy Manager)**
- **[ ] T8.5 Production Deployment**
- **[ ] T8.6 Handover to Frontend Team**
-----
## 📊 **สรุป Timeline**
| Phase | ระยะเวลา | จำนวนงาน | Output หลัก |
| :------ | :----------- | :----------- | :--------------------------------------------- |
| Phase 0 | 1 สัปดาห์ | 4 | Infrastructure Ready + Security Base |
| Phase 1 | 2 สัปดาห์ | 5 | Auth & User Management + RBAC + Idempotency |
| Phase 2 | 1 สัปดาห์ | 5 | High-Integrity Data & File Management |
| Phase 3 | 2 สัปดาห์ | 4 | Unified Workflow Engine + Correspondence |
| Phase 4 | 2 สัปดาห์ | 3 | Drawing Management + RFA with Unified Workflow |
| Phase 5 | 2 สัปดาห์ | 2 | Workflow Systems + Resilience |
| Phase 6 | 1 สัปดาห์ | 5 | Notification & Resilience + Data Partitioning |
| Phase 7 | 3 สัปดาห์ | 9 | Testing & Hardening |
| Phase 8 | 1 สัปดาห์ | 6 | Documentation & Deploy |
| **รวม** | **15 สัปดาห์** | **39 Tasks** | **Production-Ready Backend v1.4.2** |
## **Document Control:**
- **Document:** Backend Development Plan v1.4.3
- **Version:** 1.4
- **Date:** 2025-11-22
- **Author:** NAP LCBP3-DMS & Gemini
- **Status:** FINAL
- **Classification:** Internal Technical Documentation
- **Approved By:** Nattanin
-----
`End of Backend Development Plan v1.4.3`

397
infrastructure/Markdown/2_Backend_Plan_V1_4_4.Phase6A.md Normal file
View File

@@ -0,0 +1,397 @@
# “Phase 6A + Technical Design Document : Workflow DSL (Mini-Language)”**
ออกแบบสำหรับระบบ Workflow Engine กลางของโครงการ
**ไม่มีโค้ดผูกกับ Framework** เพื่อให้สามารถนำไป Implement ใน NestJS หรือ Microservice ใด ๆ ได้
---
## 📌 **Phase 6A – Workflow DSL Implementation Plan**
### 🎯 เป้าหมายของ Phase 6A
ใน Phase นี้ จะเริ่มสร้าง “Workflow DSL (Domain-Specific Language)” สำหรับนิยามกฎการเดินงาน (Workflow Transition Rules) ให้สามารถ:
* แยก **Business Workflow Logic** ออกจาก Source Code
* แก้ไขกฎ Workflow ได้โดย **ไม่ต้องแก้โค้ดและไม่ต้อง Deploy ใหม่**
* รองรับ Document หลายประเภท เช่น
* Correspondence
* RFA
* Internal Circulation
* Document Transmittal
* รองรับ Multi-step routing, skip, reject, rollback, parallel assignments
* สามารถนำไปใช้งานทั้งใน
* Backend (NestJS)
* Frontend (UI Driven)
* External Microservices
---
### 📅 ระยะเวลา
**1 สัปดาห์ (หลัง Phase 6.5)**
---
### 🧩 Output ของ Phase 6A
* DSL Specification (Grammar)
* JSON Schema for Workflow Definition
* Workflow Rule Interpreter (Parser + Executor)
* Validation Engine (Compile-time and Runtime)
* Storage (DB Table / Registry)
* Execution API:
| Action | Description |
| -------------------------------- | ------------------------------- |
| compile() | ตรวจ DSL → สร้าง Execution Tree |
| evaluate(state, action, context) | ประมวลผลและส่งสถานะใหม่ |
| preview(state) | คำนวณ Next Possible Transitions |
| validate() | ตรวจว่า DSL ถูกต้อง |
---
## 📘 **Technical Specification – Workflow DSL**
---
### 1️⃣ Requirements
#### Functional Requirements
* นิยาม Workflow เป็นภาษาคล้าย State Machine
* แต่ละเอกสารมี **State, Actions, Entry/Exit Events**
* สามารถมี:
* Required approvals
* Conditional transition
* Auto-transition
* Parallel approval
* Return/rollback
####
* Running time: < 20ms ต่อคำสั่ง
* Hot reload ไม่ต้อง Compile ใหม่ทั้ง Backend
* DSL ต้อง Debug ได้ง่าย
* ต้อง Versioned
* ต้องรองรับ Audit 100%
---
### 2️⃣ DSL Format (Human Friendly)
```yaml
workflow: RFA
version: 1.0
states:
- name: DRAFT
initial: true
on:
SUBMIT:
to: IN_REVIEW
require:
- role: ENGINEER
events:
- notify: reviewer
- name: IN_REVIEW
on:
APPROVE:
to: APPROVED
REJECT:
to: DRAFT
events:
- notify: creator
- name: APPROVED
terminal: true
```
---
### 3️⃣ Compiled Execution Model (Normalized JSON)
```json
{
"workflow": "RFA",
"version": "1.0",
"states": {
"DRAFT": {
"initial": true,
"transitions": {
"SUBMIT": {
"to": "IN_REVIEW",
"requirements": [
{ "role": "ENGINEER" }
],
"events": [
{ "type": "notify", "target": "reviewer" }
]
}
}
},
"IN_REVIEW": {
"transitions": {
"APPROVE": { "to": "APPROVED" },
"REJECT": {
"to": "DRAFT",
"events": [
{ "type": "notify", "target": "creator" }
]
}
}
},
"APPROVED": {
"terminal": true
}
}
}
```
Frontend และ Backend สามารถแชร์ JSON นี้ร่วมกันได้
---
### 4️⃣ DSL Grammar Definition (EBNF)
```ebnf
workflow = "workflow" ":" identifier ;
version = "version" ":" number ;
states = "states:" state_list ;
state_list = { state } ;
state = "- name:" identifier
[ "initial:" boolean ]
[ "terminal:" boolean ]
[ "on:" transition_list ] ;
transition_list = { transition } ;
transition = action ":"
indent "to:" identifier
[ indent "require:" requirements ]
[ indent "events:" event_list ] ;
requirements = "- role:" identifier | "- user:" identifier ;
event_list = { event } ;
event = "- notify:" identifier ;
```
---
### 5️⃣ Validation Rules (Compile-Time)
#### 5.1 State Rules
* ต้องมีอย่างน้อย 1 state ที่ `initial: true`
* หาก `terminal: true` → ต้องไม่มี transition ต่อไป
#### 5.2 Transition Rules
ตรวจสอบว่า:
* `to` ชี้ไปยัง state ที่มีอยู่
* `require.role` ต้องเป็น role ที่ระบบรู้จัก
* Action name ต้องเป็น **UPPER_CASE**
#### 5.3 Version Safety
* ทุกชุด Workflow DSL ต้องขึ้นกับ version
* แก้ไขต้องสร้าง version ใหม่
* ไม่ overwrite version เก่า
* “Document ที่กำลังอยู่ใน step เดิมยังต้องใช้กฎเดิมได้”
---
### 6️⃣ Runtime Validation Rules
เมื่อ execute(action):
```
input: current_state, action, context
1) ตรวจว่า state มี transition "action"
2) ตรวจว่าผู้ใช้มีสิทธิ์ตาม require[]
3) Compute next state
4) Execute events[]
5) Return next_state
```
---
### 7️⃣ Context Model
```ts
interface WorkflowContext {
userId: string;
roles: string[];
documentId: string;
now: Date;
payload?: any;
}
```
---
### 8️⃣ Execution API (Abstract)
```ts
class WorkflowEngine {
load(dsl: string | object): CompiledWorkflow
compile(dsl: string | object): CompiledWorkflow
evaluate(state: string, action: string, context: WorkflowContext): EvalResult
getAvailableActions(state: string, context: WorkflowContext): string[]
}
```
---
### 9️⃣ Interpreter Execution Flow
```mermaid
flowchart TD
A[Receive Action] --> B[Load Compiled Workflow]
B --> C[Check allowed actions]
C -->|Invalid| E[Return Error]
C --> D[Evaluate Requirements]
D --> F[Transition to Next State]
F --> G[Run Events]
G --> H[Return Success]
```
---
### 🔟 Events System
รองรับ event หลายประเภท:
| event.type | ตัวอย่าง |
| ----------- | ------------------------- |
| notify | ส่ง Email/Line |
| assign | เปลี่ยนผู้รับผิดชอบ |
| webhook | ยิง Webhook ไปยังระบบอื่น |
| auto_action | ทำ action ซ้ำโดยอัตโนมัติ |
---
### 11️⃣ Database Schema
#### Table: `workflow_definition`
| Field | Type | Description |
| ------------- | ----------- | --------------------- |
| id | UUID | PK |
| workflow_code | varchar(50) | เช่น `RFA`, `CORR` |
| version | int | Version number |
| dsl | JSON | YAML/JSON DSL เก็บดิบ |
| compiled | JSON | JSON ที่ Compile แล้ว |
| created_at | timestamp | |
| is_active | boolean | ใช้อยู่หรือไม่ |
#### Table: `workflow_history`
เก็บ audit แบบ immutable append-only
| Field | Description |
| ----------- | --------------- |
| workflow | Document Type |
| document_id | เอกสารไหน |
| from_state | เดิม |
| to_state | ใหม่ |
| action | คำสั่ง |
| user | ใครเป็นคนทำ |
| timestamp | เวลา |
| metadata | เหตุการณ์อื่น ๆ |
---
### 12️⃣ Error Codes
| Code | Meaning |
| ----------------------- | ---------------------- |
| WF_NO_TRANSITION | Action นี้ไม่ถูกต้อง |
| WF_RESTRICTED | User ไม่มีสิทธิ์ |
| WF_MISSING_REQUIREMENTS | ไม่ผ่านเงื่อนไข |
| WF_STATE_NOT_FOUND | ไม่มี state ที่อ้างอิง |
| WF_SYNTAX_ERROR | DSL ผิดรูปแบบ |
---
### 13️⃣ Testing Strategy
#### Unit Tests
* Parse DSL → JSON
* Invalid syntax → throw error
* Invalid transitions → throw error
#### Integration Tests
* Evaluate() ผ่าน 20+ cases
* RFA ย้อนกลับ
* Approve chain
* Parallel review
#### Load Tests
* 1,000 documents running workflow
* Evaluate < 20ms ต่อ action
---
### 14️⃣ Deployment Strategy
#### Hot Reload Options
* DSL stored in DB
* Cache in Redis
* Touched timestamp triggers:
```
invalidate cache → recompile
```
#### No downtime required
---
### 15️⃣ Microservice-Ready
DSL Engine แยกเป็น:
* `workflow-engine-core` → Pure JS library
* `workflow-service` → NestJS module
* API public:
```
POST /workflow/evaluate
GET /workflow/preview
POST /workflow/compile
```
ภายหลังสามารถนำไปวางบน:
* Kubernetes
* Worker Node
* API Gateway
---
## 🎉 Summary
### สิ่งที่ Phase 6A เพิ่มเข้าในระบบ
✔ Workflow DSL ที่แก้ไขได้โดยไม่ต้อง Deploy
✔ Parser + Validator + Runtime Interpreter
✔ Database storage + Versioning
✔ Execution API สำหรับ Backend และ Frontend
✔ รองรับ Business Workflow ซับซ้อนทั้งหมด
✔ Ready สำหรับ Microservice model ในอนาคต

709
infrastructure/Markdown/2_Backend_Plan_V1_4_4.Phase_Addition.md Normal file
View File

@@ -0,0 +1,709 @@
# 🎯 **Admin Panel Comprehensive Analysis สำหรับ LCBP3-DMS v1.4.4**
จากการวิเคราะห์ Requirements และ Technical Design ทั้งหมด ขอนำเสนอ Admin Panel ที่สมบูรณ์สำหรับระบบ LCBP3-DMS
## 📊 **ภาพรวม Admin Panel Structure**
### **Role-Based Access Levels**
- **Superadmin:** Full system access
- **Org Admin:** Organization-level management
- **Project Manager:** Project-level administration
- **Contract Admin:** Contract-specific management
---
## 🛠️ **1. System Administration**
### **1.1 Global System Configuration**
```typescript
interface SystemConfig {
maintenance_mode: boolean;
session_timeout: number;
password_policy: {
min_length: number;
require_uppercase: boolean;
require_numbers: boolean;
require_special_chars: boolean;
expiry_days: number;
};
file_upload: {
max_size_mb: number;
allowed_types: string[];
virus_scan_enabled: boolean;
};
notification: {
email_enabled: boolean;
line_enabled: boolean;
digest_frequency: number; // minutes
};
}
```
**Features:**
- [ ] Toggle Maintenance Mode
- [ ] Configure Security Policies
- [ ] Manage File Upload Settings
- [ ] Configure Notification Channels
- [ ] System Health Monitoring Dashboard
### **1.2 Audit & Monitoring Center**
```typescript
interface AuditDashboard {
security_metrics: {
failed_logins: number;
file_scans: number;
virus_detections: number;
permission_changes: number;
};
user_activity: AuditLog[];
system_performance: PerformanceMetrics;
recent_errors: SystemError[];
}
```
**Features:**
- [ ] Real-time Activity Monitoring
- [ ] Security Incident Reporting
- [ ] Performance Metrics Dashboard
- [ ] Error Log Viewer
- [ ] Export Audit Reports
---
## 👥 **2. User & Organization Management**
### **2.1 User Management**
```typescript
interface UserManagement {
user_list: User[];
bulk_operations: {
import_users: FileUpload;
export_users: CSVExport;
bulk_assign_roles: RoleAssignment[];
};
user_lifecycle: {
onboarding_workflow: WorkflowConfig;
offboarding_checklist: ChecklistItem[];
};
}
```
**Features:**
- [ ] User CRUD Operations
- [ ] Bulk User Import/Export
- [ ] User Activity Tracking
- [ ] Password Reset Management
- [ ] User Session Management
### **2.2 Organization Hierarchy**
```typescript
interface OrganizationManagement {
organization_tree: Organization[];
department_structure: Department[];
contact_persons: Contact[];
organization_settings: {
document_retention_policy: RetentionPolicy;
notification_preferences: NotificationConfig;
};
}
```
**Features:**
- [ ] Organization CRUD
- [ ] Department Structure Management
- [ ] Contact Person Assignment
- [ ] Organization-specific Policies
### **2.3 Advanced RBAC Management**
```typescript
interface RBACManagement {
role_definitions: Role[];
permission_matrix: Permission[];
assignment_rules: {
automatic_assignments: AutoAssignmentRule[];
conditional_access: ConditionalRule[];
};
permission_audit: {
permission_usage: UsageStats[];
conflict_detection: Conflict[];
};
}
```
**Features:**
- [ ] Custom Role Creation
- [ ] Granular Permission Management
- [ ] Automatic Role Assignment Rules
- [ ] Permission Conflict Detection
- [ ] Role Usage Analytics
---
## 📁 **3. Project & Contract Administration**
### **3.1 Project Portfolio Management**
```typescript
interface ProjectManagement {
project_dashboard: ProjectOverview[];
project_phases: Phase[];
milestone_tracking: Milestone[];
resource_allocation: Resource[];
project_analytics: ProjectMetrics;
}
```
**Features:**
- [ ] Project Lifecycle Management
- [ ] Phase and Milestone Tracking
- [ ] Resource Allocation
- [ ] Project Performance Analytics
- [ ] Project Documentation Repository
### **3.2 Contract Administration**
```typescript
interface ContractManagement {
contract_register: Contract[];
party_management: ContractParty[];
amendment_tracking: Amendment[];
compliance_monitoring: ComplianceCheck[];
financial_tracking: FinancialMetrics;
}
```
**Features:**
- [ ] Contract CRUD Operations
- [ ] Contract Party Management
- [ ] Amendment History
- [ ] Compliance Monitoring
- [ ] Financial Tracking
### **3.3 Project-Organization Mapping**
```typescript
interface ProjectOrgMapping {
project_assignments: ProjectAssignment[];
access_control: AccessRule[];
collaboration_settings: CollaborationConfig;
}
```
**Features:**
- [ ] Organization Assignment to Projects
- [ ] Cross-Organization Collaboration Settings
- [ ] Access Control Configuration
---
## 📋 **4. Master Data Management**
### **4.1 Document Type Ecosystem**
```typescript
interface DocumentTypeManagement {
correspondence_types: DocumentType[];
rfa_types: RFAType[];
circulation_types: CirculationType[];
drawing_categories: DrawingCategory[];
type_hierarchy: TypeHierarchy;
}
```
**Features:**
- [ ] Document Type CRUD
- [ ] Type-Specific Workflow Configuration
- [ ] Category Hierarchy Management
- [ ] Template Association
### **4.2 Discipline & Classification System**
```typescript
interface DisciplineManagement {
disciplines: Discipline[];
sub_types: SubType[];
classification_rules: ClassificationRule[];
mapping_configurations: MappingConfig[];
}
```
**Features:**
- [ ] Discipline CRUD (ตาม Requirement 6B)
- [ ] Sub-Type Management with Number Mapping
- [ ] Automatic Classification Rules
- [ ] Cross-Reference Mapping
### **4.3 Status & Code Management**
```typescript
interface StatusManagement {
status_codes: StatusCode[];
transition_rules: TransitionRule[];
status_workflows: StatusWorkflow[];
automated_status_changes: AutoStatusChange[];
}
```
**Features:**
- [ ] Status Code Configuration
- [ ] State Transition Rules
- [ ] Automated Status Updates
- [ ] Status Change Analytics
---
## 🔢 **5. Document Numbering System Administration**
### **5.1 Numbering Format Configuration**
```typescript
interface NumberingFormatManagement {
format_templates: NumberingTemplate[];
token_library: TokenDefinition[];
format_preview: FormatPreview;
validation_rules: ValidationRule[];
}
```
**Features:**
- [ ] Template Editor with Live Preview
- [ ] Custom Token Definition
- [ ] Format Validation
- [ ] Bulk Template Application
### **5.2 Counter Management**
```typescript
interface CounterManagement {
counter_groups: CounterGroup[];
reset_schedules: ResetSchedule[];
counter_audit: CounterHistory[];
conflict_resolution: ConflictResolutionRule[];
}
```
**Features:**
- [ ] Counter Group Configuration
- [ ] Scheduled Reset Management
- [ ] Counter Audit Trail
- [ ] Conflict Resolution Rules
### **5.3 Numbering Rule Engine**
```typescript
interface NumberingRuleEngine {
conditional_rules: ConditionalRule[];
context_resolvers: ContextResolver[];
fallback_strategies: FallbackStrategy[];
performance_monitoring: PerformanceMetrics;
}
```
**Features:**
- [ ] Conditional Numbering Rules
- [ ] Context Variable Management
- [ ] Fallback Strategy Configuration
- [ ] Performance Optimization
---
## ⚙️ **6. Workflow & Routing Administration**
### **6.1 Workflow DSL Management**
```typescript
interface WorkflowDSLManagement {
workflow_library: WorkflowDefinition[];
dsl_editor: DSLEditor;
version_control: VersionHistory[];
deployment_pipeline: DeploymentConfig[];
}
```
**Features:**
- [ ] Visual Workflow Designer
- [ ] DSL Code Editor with Syntax Highlighting
- [ ] Version Control and Rollback
- [ ] Testing and Deployment Pipeline
### **6.2 Routing Template Administration**
```typescript
interface RoutingTemplateManagement {
template_library: RoutingTemplate[];
step_configurations: StepConfig[];
approval_chains: ApprovalChain[];
escalation_rules: EscalationRule[];
}
```
**Features:**
- [ ] Template CRUD Operations
- [ ] Drag-and-Drop Step Configuration
- [ ] Approval Chain Management
- [ ] Escalation Rule Setup
### **6.3 Workflow Analytics**
```typescript
interface WorkflowAnalytics {
performance_metrics: WorkflowMetrics[];
bottleneck_analysis: Bottleneck[];
compliance_reporting: ComplianceReport[];
optimization_recommendations: Recommendation[];
}
```
**Features:**
- [ ] Workflow Performance Dashboard
- [ ] Bottleneck Identification
- [ ] Compliance Reporting
- [ ] Optimization Suggestions
---
## 📊 **7. Reporting & Analytics Center**
### **7.1 Custom Report Builder**
```typescript
interface ReportBuilder {
data_sources: DataSource[];
visualization_types: VisualizationType[];
report_templates: ReportTemplate[];
scheduling: ScheduleConfig[];
}
```
**Features:**
- [ ] Drag-and-Drop Report Designer
- [ ] Multiple Visualization Options
- [ ] Template Library
- [ ] Automated Report Scheduling
### **7.2 Business Intelligence**
```typescript
interface BusinessIntelligence {
kpi_dashboard: KPIMetric[];
trend_analysis: TrendData[];
predictive_analytics: PredictiveModel[];
data_export: ExportConfig[];
}
```
**Features:**
- [ ] Real-time KPI Dashboard
- [ ] Trend Analysis Tools
- [ ] Predictive Analytics
- [ ] Data Export and Integration
### **7.3 Compliance Reporting**
```typescript
interface ComplianceReporting {
regulatory_reports: RegulatoryReport[];
audit_trails: AuditTrail[];
compliance_dashboard: ComplianceMetric[];
certification_tracking: Certification[];
}
```
**Features:**
- [ ] Pre-built Regulatory Reports
- [ ] Comprehensive Audit Trails
- [ ] Compliance Dashboard
- [ ] Certification Management
---
## 🔐 **8. Security & Compliance Center**
### **8.1 Security Policy Management**
```typescript
interface SecurityPolicyManagement {
access_policies: AccessPolicy[];
data_classification: DataClassification[];
encryption_settings: EncryptionConfig[];
security_incidents: SecurityIncident[];
}
```
**Features:**
- [ ] Access Policy Configuration
- [ ] Data Classification Scheme
- [ ] Encryption Management
- [ ] Security Incident Tracking
### **8.2 Compliance Framework**
```typescript
interface ComplianceFramework {
compliance_rules: ComplianceRule[];
control_testing: ControlTest[];
evidence_management: Evidence[];
compliance_calendar: ComplianceEvent[];
}
```
**Features:**
- [ ] Compliance Rule Engine
- [ ] Control Testing Framework
- [ ] Evidence Collection
- [ ] Compliance Calendar
### **8.3 Risk Management**
```typescript
interface RiskManagement {
risk_register: Risk[];
risk_assessments: RiskAssessment[];
mitigation_plans: MitigationPlan[];
risk_dashboard: RiskMetrics;
}
```
**Features:**
- [ ] Risk Identification and Registration
- [ ] Risk Assessment Tools
- [ ] Mitigation Planning
- [ ] Risk Monitoring Dashboard
---
## 📧 **9. Notification & Communication Management**
### **9.1 Notification Template System**
```typescript
interface NotificationTemplateManagement {
email_templates: EmailTemplate[];
line_templates: LineTemplate[];
system_notifications: SystemTemplate[];
template_variables: TemplateVariable[];
}
```
**Features:**
- [ ] Multi-channel Template Management
- [ ] Variable Substitution System
- [ ] Template Testing and Preview
- [ ] Bulk Template Operations
### **9.2 Subscription Management**
```typescript
interface SubscriptionManagement {
user_preferences: UserPreference[];
group_subscriptions: GroupSubscription[];
escalation_policies: EscalationPolicy[];
delivery_reports: DeliveryReport[];
}
```
**Features:**
- [ ] User Preference Management
- [ ] Group Subscription Configuration
- [ ] Escalation Policy Setup
- [ ] Delivery Monitoring
### **9.3 Digest Configuration**
```typescript
interface DigestConfiguration {
digest_rules: DigestRule[];
grouping_criteria: GroupingCriteria[];
timing_configurations: TimingConfig[];
content_prioritization: PriorityRule[];
}
```
**Features:**
- [ ] Digest Rule Engine
- [ ] Content Grouping Configuration
- [ ] Timing and Frequency Settings
- [ ] Content Prioritization Rules
---
## 🗃️ **10. Data Management & Maintenance**
### **10.1 Data Lifecycle Management**
```typescript
interface DataLifecycleManagement {
retention_policies: RetentionPolicy[];
archival_rules: ArchivalRule[];
purge_schedules: PurgeSchedule[];
data_governance: GovernancePolicy[];
}
```
**Features:**
- [ ] Retention Policy Configuration
- [ ] Automated Archival Rules
- [ ] Scheduled Data Purge
- [ ] Data Governance Framework
### **10.2 Backup & Recovery**
```typescript
interface BackupRecoveryManagement {
backup_configurations: BackupConfig[];
recovery_procedures: RecoveryProcedure[];
disaster_recovery: DisasterRecoveryPlan[];
backup_monitoring: BackupMonitor[];
}
```
**Features:**
- [ ] Backup Schedule Management
- [ ] Recovery Procedure Documentation
- [ ] Disaster Recovery Planning
- [ ] Backup Status Monitoring
### **10.3 System Maintenance**
```typescript
interface SystemMaintenance {
maintenance_windows: MaintenanceWindow[];
update_management: UpdateConfig[];
performance_tuning: TuningParameter[];
cleanup_jobs: CleanupJob[];
}
```
**Features:**
- [ ] Maintenance Window Scheduling
- [ ] Update Management
- [ ] Performance Tuning Parameters
- [ ] Automated Cleanup Jobs
---
## 🎯 **11. Dashboard & Overview**
### **11.1 Executive Dashboard**
```typescript
interface ExecutiveDashboard {
system_health: HealthMetric[];
business_metrics: BusinessMetric[];
user_engagement: EngagementMetric[];
security_posture: SecurityMetric[];
}
```
**Features:**
- [ ] Real-time System Health Monitoring
- [ ] Business Performance Metrics
- [ ] User Engagement Analytics
- [ ] Security Posture Assessment
### **11.2 Operational Dashboard**
```typescript
interface OperationalDashboard {
workflow_monitoring: WorkflowStatus[];
document_metrics: DocumentMetric[];
user_productivity: ProductivityMetric[];
system_utilization: UtilizationMetric[];
}
```
**Features:**
- [ ] Workflow Status Monitoring
- [ ] Document Processing Metrics
- [ ] User Productivity Analytics
- [ ] System Resource Utilization
---
## 🔄 **12. Integration & API Management**
### **12.1 API Gateway Administration**
```typescript
interface APIManagement {
api_endpoints: APIEndpoint[];
rate_limiting: RateLimitConfig[];
authentication_settings: AuthConfig[];
api_analytics: APIAnalytics[];
}
```
**Features:**
- [ ] API Endpoint Management
- [ ] Rate Limiting Configuration
- [ ] Authentication Settings
- [ ] API Usage Analytics
### **12.2 External Integration**
```typescript
interface ExternalIntegration {
webhook_configurations: WebhookConfig[];
third_party_connectors: Connector[];
data_sync_rules: SyncRule[];
integration_monitoring: IntegrationMonitor[];
}
```
**Features:**
- [ ] Webhook Management
- [ ] Third-party Connector Configuration
- [ ] Data Synchronization Rules
- [ ] Integration Health Monitoring
---
## 🎯 **Critical Success Factors**
1. **Unified Administration Experience** - Single pane of glass สำหรับทุกการจัดการ
2. **Role-Based Access Control** - แต่ละระดับเห็นและจัดการได้เฉพาะส่วนของตัวเอง
3. **Real-time Monitoring** - ระบบ monitoring แบบ real-time ทุกส่วน
4. **Audit Trail** - ทุกการเปลี่ยนแปลงใน Admin Panel ถูกบันทึกไว้
5. **Performance** - Admin operations ต้องรวดเร็วแม้มีข้อมูลจำนวนมาก
6. **User Experience** - Interface ใช้งานง่าย แม้สำหรับฟีเจอร์ที่ซับซ้อน
Admin Panel นี้จะทำให้ผู้ดูแลระบบสามารถจัดการ LCBP3-DMS ได้อย่างสมบูรณ์แบบ ตั้งแต่การตั้งค่าระดับพื้นฐานไปจนถึงการจัดการ workflow ที่ซับซ้อนและการวิเคราะห์ข้อมูลเชิงลึก

2120
infrastructure/Markdown/2_Backend_Plan_V1_4_4.md Normal file
View File

File diff suppressed because it is too large Load Diff

995
infrastructure/Markdown/3_Frontend_Plan_V1_4_3.md Normal file
View File

@@ -0,0 +1,995 @@
# 📋 **แผนการพัฒนา Frontend (Next.js) - LCBP3-DMS v1.4.3**
**สถานะ:** FINAL GUIDELINE Rev.01
**วันที่:** 2025-11-22
**อ้างอิง:** Requirements v1.4.3 & FullStackJS Guidelines v1.4.3
**Classification:** Internal Technical Documentation
## 🎯 **ภาพรวมโครงการ**
พัฒนา Frontend สำหรับระบบบริหารจัดการเอกสารโครงการ (Document Management System) ที่มีความทันสมัย รองรับการทำงานบนอุปกรณ์ต่างๆ ได้อย่างสมบูรณ์ มีประสบการณ์ผู้ใช้ที่ราบรื่น และรองรับการทำงานแบบ Offline เบื้องต้น
---
## 📐 **สถาปัตยกรรมระบบ**
### **Technology Stack**
- **Framework:** Next.js 14+ (App Router, React 18, TypeScript, ESM)
- **Styling:** Tailwind CSS + PostCSS
- **UI Components:** shadcn/ui + Radix UI Primitives
- **State Management:**
- **Server State:** TanStack Query (React Query)
- **Client State:** Zustand
- **Form State:** React Hook Form + Zod
- **API Client:** Axios (พร้อม Idempotency Interceptor)
- **Authentication:** NextAuth.js (รองรับ JWT)
- **File Upload:** Custom Hook + Drag & Drop
- **Testing:**
- **Unit/Integration:** Vitest + React Testing Library
- **E2E:** Playwright
- **Mocking:** MSW (Mock Service Worker)
- **Development:**
- **Package Manager:** pnpm
- **Linting:** ESLint + Prettier
- **Type Checking:** TypeScript Strict Mode
### **โครงสร้างโปรเจกต์**
```tree
app/
├── (auth)/
│ ├── login/
│ └── register/
├── (dashboard)/
│ ├── layout.tsx
│ ├── page.tsx
│ └── components/
├── admin/
│ ├── users/
│ ├── roles/
│ └── numbering-formats/
├── correspondences/
│ ├── page.tsx
│ ├── [id]/
│ └── new/
├── rfas/
│ ├── page.tsx
│ ├── [id]/
│ └── new/
├── drawings/
├── circulations/
├── transmittals/
├── search/
└── profile/
components/
├── ui/ # shadcn/ui components
├── forms/ # Dynamic form components
├── tables/ # Responsive data tables
├── workflow/ # Workflow visualization
├── file-upload/ # File upload with security
├── notifications/ # Notification system
└── layout/ # App layout components
lib/
├── api/ # API clients & interceptors
├── auth/ # Authentication utilities
├── stores/ # Zustand stores
├── hooks/ # Custom React hooks
├── utils/ # Utility functions
├── constants/ # App constants
└── types/ # TypeScript type definitions
styles/
├── globals.css
└── components/
__tests__/
├── unit/
├── integration/
└── e2e/
```
---
## 🗓️ **แผนการพัฒนาแบบ Phase-Based**
### **Dependency Diagram (ภาพรวม)**
```mermaid
%% Phase 0: Foundation Setup
subgraph Phase0 [Phase 0: Foundation & Configuration]
F0_1[F0.1: Project Setup & Tooling]
F0_2[F0.2: Design System & UI Components]
F0_3[F0.3: API Client & Authentication]
F0_4[F0.4: State Management Setup]
end
%% Phase 1: Core Layout & Navigation
subgraph Phase1 [Phase 1: Core Application Structure]
F1_1[F1.1: Main Layout & Navigation]
F1_2[F1.2: Authentication Pages]
F1_3[F1.3: Dashboard & Landing]
F1_4[F1.4: Responsive Design System]
end
%% Phase 2: User Management & Profile
subgraph Phase2 [Phase 2: User Management & Security]
F2_1[F2.1: User Profile & Settings]
F2_2[F2.2: Admin Panel - User Management]
F2_3[F2.3: Admin Panel - Role Management]
F2_4[F2.4: Permission Integration]
end
%% Phase 3: Project & Organization Management
subgraph Phase3 [Phase 3: Project Structure]
F3_1[F3.1: Project Management UI]
F3_2[F3.2: Organization Management]
F3_3[F3.3: Contract Management]
end
%% Phase 4: Correspondence Management
subgraph Phase4 [Phase 4: Correspondence System]
F4_1[F4.1: Correspondence List & Search]
F4_2[F4.2: Correspondence Creation Form]
F4_3[F4.3: Correspondence Detail View]
F4_4[F4.4: File Upload Integration]
end
%% Phase 5: Workflow & Routing System
subgraph Phase5 [Phase 5: Workflow Management]
F5_1[F5.1: Workflow Visualization Component]
F5_2[F5.2: Routing Template Management]
F5_3[F5.3: Workflow Step Actions]
F5_4[F5.4: Real-time Status Updates]
end
%% Phase 6: Drawing Management
subgraph Phase6 [Phase 6: Drawing System]
F6_1[F6.1: Contract Drawings Management]
F6_2[F6.2: Shop Drawings Management]
F6_3[F6.3: Drawing Revision System]
F6_4[F6.4: Drawing References]
end
%% Phase 7: RFA & Approval Workflows
subgraph Phase7 [Phase 7: RFA System]
F7_1[F7.1: RFA List & Dashboard]
F7_2[F7.2: RFA Creation with Dynamic Forms]
F7_3[F7.3: RFA Workflow Integration]
F7_4[F7.4: RFA Approval Interface]
end
%% Phase 8: Circulation & Internal Routing
subgraph Phase8 [Phase 8: Internal Workflows]
F8_1[F8.1: Circulation Management]
F8_2[F8.2: Task Assignment Interface]
F8_3[F8.3: Internal Approval Flows]
end
%% Phase 9: Advanced Features
subgraph Phase9 [Phase 9: Advanced Features]
F9_1[F9.1: Advanced Search Interface]
F9_2[F9.2: Notification System]
F9_3[F9.3: Reporting & Analytics]
F9_4[F9.4: Mobile Optimization]
end
%% Phase 10: Testing & Optimization
subgraph Phase10 [Phase 10: Testing & Polish]
F10_1[F10.1: Comprehensive Testing]
F10_2[F10.2: Performance Optimization]
F10_3[F10.3: Security Hardening]
F10_4[F10.4: Documentation]
end
%% Dependencies
F0_1 --> F0_2
F0_1 --> F0_3
F0_1 --> F0_4
F0_2 --> F1_1
F0_3 --> F1_1
F0_4 --> F1_1
F1_1 --> F1_2
F1_1 --> F1_3
F1_1 --> F1_4
F1_1 --> F2_1
F1_3 --> F2_1
F0_3 --> F2_1
F2_1 --> F2_2
F2_2 --> F2_3
F2_3 --> F2_4
F1_1 --> F3_1
F2_4 --> F3_1
F3_1 --> F3_2
F3_2 --> F3_3
F1_1 --> F4_1
F3_1 --> F4_1
F4_1 --> F4_2
F4_2 --> F4_3
F4_2 --> F4_4
F4_1 --> F5_1
F4_2 --> F5_2
F4_3 --> F5_3
F5_1 --> F5_4
F3_1 --> F6_1
F4_4 --> F6_1
F6_1 --> F6_2
F6_2 --> F6_3
F6_3 --> F6_4
F4_1 --> F7_1
F5_1 --> F7_1
F6_2 --> F7_1
F7_1 --> F7_2
F7_2 --> F7_3
F7_3 --> F7_4
F4_1 --> F8_1
F5_3 --> F8_1
F8_1 --> F8_2
F8_2 --> F8_3
F4_1 --> F9_1
F7_1 --> F9_1
F1_3 --> F9_2
F5_4 --> F9_2
F1_3 --> F9_3
F1_4 --> F9_4
F1_1 --> F10_1
F4_1 --> F10_1
F7_1 --> F10_1
F10_1 --> F10_2
F10_2 --> F10_3
F10_3 --> F10_4
```
## **Phase 0: Foundation & Configuration (สัปดาห์ที่ 1)**
**Milestone:** โครงสร้างพื้นฐานพร้อม รองรับ Development Workflow ที่มีประสิทธิภาพ
### **Phase 0: Tasks**
- **[ ] F0.1 Project Setup & Tooling**
- [ ] Initialize Next.js 14+ project with TypeScript
- [ ] Configure pnpm workspace
- [ ] Setup ESLint, Prettier, and pre-commit hooks
- [ ] Configure Tailwind CSS with PostCSS
- [ ] Setup shadcn/ui components
- [ ] Configure absolute imports and path aliases
- [ ] **Deliverable:** Development environment ready
- [ ] **Dependencies:** None
- **[ ] F0.2 Design System & UI Components**
- [ ] Setup color palette and design tokens
- [ ] Create responsive design breakpoints
- [ ] Implement core shadcn/ui components:
- [ ] Button, Input, Label, Form
- [ ] Card, Table, Badge
- [ ] Dialog, Dropdown, Select
- [ ] Tabs, Accordion
- [ ] Create custom design system components:
- [ ] DataTable (responsive)
- [ ] FileUpload zone
- [ ] Workflow visualization
- [ ] **Deliverable:** Consistent UI component library
- [ ] **Dependencies:** F0.1
- **[ ] F0.3 API Client & Authentication**
- [ ] Setup Axios client with interceptors:
- [ ] Idempotency-Key header injection
- [ ] Authentication token management
- [ ] Error handling and retry logic
- [ ] Configure NextAuth.js for JWT authentication
- [ ] Create auth hooks (useAuth, usePermissions)
- [ ] Setup API route handlers for auth callbacks
- [ ] **Security:** Implement secure token storage
- [ ] **Deliverable:** Secure API communication layer
- [ ] **Dependencies:** F0.1
- **[ ] F0.4 State Management Setup**
- [ ] Configure TanStack Query for server state:
- [ ] Query client setup
- [ ] Default configurations
- [ ] Error boundaries
- [ ] Create Zustand stores:
- [ ] Auth store (user, permissions)
- [ ] UI store (theme, sidebar state)
- [ ] Draft store (form auto-save)
- [ ] Setup React Hook Form with Zod integration
- [ ] Create form validation schemas
- [ ] **Deliverable:** Robust state management system
- [ ] **Dependencies:** F0.1, F0.3
### **Phase 0: Testing - Foundation**
#### **F0.T1 Component Test Suite**
- [ ] **Unit Tests:** Core UI components (Button, Input, Card)
- [ ] **Integration Tests:** Form validation, API client interceptors
- [ ] **Visual Tests:** Component styling and responsive behavior
#### **F0.T2 Authentication Test Suite**
- [ ] **Unit Tests:** Auth hooks, token management
- [ ] **Integration Tests:** Login/logout flow, permission checks
- [ ] **Security Tests:** Token security, API authentication
---
## **Phase 1: Core Application Structure (สัปดาห์ที่ 2)**
**Milestone:** Layout หลักพร้อมใช้งาน การนำทางและ Authentication ทำงานได้
### **Phase 1: Tasks**
- **[ ] F1.1 Main Layout & Navigation**
- [ ] Create App Shell layout:
- [ ] Navbar with user menu and notifications
- [ ] Collapsible sidebar with navigation
- [ ] Main content area with responsive design
- [ ] Implement navigation menu structure:
- [ ] Dashboard, Correspondences, RFAs, Drawings, etc.
- [ ] Dynamic menu based on user permissions
- [ ] Create breadcrumb navigation component
- [ ] Implement mobile-responsive sidebar (drawer)
- [ ] Maintenance Mode Integration:
- [ ] Implement a Global Middleware/Wrapper ที่ตรวจสอบสถานะ Maintenance Mode ผ่าน API/Service ก่อนการ Render หน้า หากสถานะเป็น true ให้ Redirect ผู้ใช้ (ยกเว้น Admin) ไปยังหน้า /maintenance ทันที เพื่อให้สอดคล้องกับ Logic ของ Backend.
- [ ] **Accessibility:** Ensure keyboard navigation and screen reader support
- [ ] **Deliverable:** Fully functional application layout
- [ ] **Dependencies:** F0.2, F0.3
- **[ ] F1.2 Authentication Pages**
- [ ] Create login page with form validation
- [ ] Implement forgot password flow
- [ ] Create registration page (admin-only)
- [ ] Setup protected route middleware
- [ ] Implement route-based permission checks
- [ ] **Security:** Rate limiting on auth attempts, secure password requirements
- [ ] **Deliverable:** Complete authentication flow
- [ ] **Dependencies:** F0.3, F1.1
- **[ ] F1.3 Dashboard & Landing**
- [ ] Create public landing page for non-authenticated users
- [ ] Implement main dashboard with:
- [ ] KPI cards (document counts, pending tasks)
- [ ] "My Tasks" table from v_user_tasks
- [ ] Recent activity feed
- [ ] Security metrics display
- [ ] Create dashboard widgets system
- [ ] Implement data fetching with TanStack Query
- [ ] **Performance:** Optimize dashboard data loading
- [ ] **Deliverable:** Functional dashboard with real data
- [ ] **Dependencies:** F0.4, F1.1
- **[ ] F1.4 Responsive Design System**
- [ ] Implement mobile-first responsive design
- [ ] Create card view components for mobile tables
- [ ] Setup touch-friendly interactions
- [ ] Optimize images and assets for mobile
- [ ] Test across multiple device sizes
- [ ] **UX:** Ensure seamless mobile experience
- [ ] **Deliverable:** Fully responsive application
- [ ] **Dependencies:** F0.2, F1.1
### **Phase 1: Testing - Core Structure**
#### **F1.T1 Layout Test Suite**
- [ ] **Unit Tests:** Navigation components, layout responsiveness
- [ ] **Integration Tests:** Route protection, permission-based navigation
- [ ] **E2E Tests:** Complete user navigation flow
#### **F1.T2 Dashboard Test Suite**
- [ ] **Unit Tests:** Dashboard components, data formatting
- [ ] **Integration Tests:** Data fetching and display, real-time updates
- [ ] **Performance Tests:** Dashboard loading performance
---
## **Phase 2: User Management & Security (สัปดาห์ที่ 3)**
**Milestone:** การจัดการผู้ใช้และสิทธิ์แบบสมบูรณ์
### **Phase 2: Tasks**
- **[ ] F2.1 User Profile & Settings**
- [ ] Create user profile page:
- [ ] Personal information display/edit
- [ ] Password change functionality
- [ ] Notification preferences
- [ ] Implement profile picture upload
- [ ] Create user settings page
- [ ] **Security:** Secure password change with current password verification
- [ ] **Deliverable:** Complete user self-service management
- [ ] **Dependencies:** F1.1, F0.4
- **[ ] F2.2 Admin Panel - User Management**
- [ ] Create user list with search and filters
- [ ] Implement user creation form
- [ ] Create user edit interface
- [ ] Implement bulk user operations
- [ ] Add user activity tracking display
- [ ] **Security:** Admin-only access enforcement
- [ ] **Deliverable:** Comprehensive user management interface
- [ ] **Dependencies:** F1.1, F2.1
- **[ ] F2.3 Admin Panel - Role Management**
- [ ] Create role list and management interface
- [ ] Implement role creation and editing
- [ ] Create permission assignment interface
- [ ] Implement role-based access control visualization
- [ ] Add role usage statistics
- [ ] **Security:** Permission hierarchy enforcement
- [ ] **Deliverable:** Complete RBAC management system
- [ ] **Dependencies:** F2.2
- **[ ] F2.4 Permission Integration**
- [ ] Implement CASL ability integration
- [ ] Create permission-based UI components:
- [ ] ProtectedButton, ProtectedLink
- [ ] Conditional rendering based on permissions
- [ ] Setup real-time permission updates
- [ ] Implement permission debugging tools
- [ ] **Security:** Frontend-backend permission consistency
- [ ] **Deliverable:** Seamless permission enforcement throughout app
- [ ] **Dependencies:** F0.3, F2.3
### **Phase 2: Testing - User Management**
#### **F2.T1 User Management Test Suite**
- [ ] **Unit Tests:** User CRUD operations, form validation
- [ ] **Integration Tests:** User-role assignment, permission propagation
- [ ] **Security Tests:** Permission escalation attempts, admin access control
#### **F2.T2 RBAC Test Suite**
- [ ] **Unit Tests:** Permission checks, role validation
- [ ] **Integration Tests:** Multi-level permission enforcement, UI element protection
- [ ] **E2E Tests:** Complete role-based workflow testing
---
## **Phase 3: Project Structure (สัปดาห์ที่ 4)**
**Milestone:** การจัดการโครงสร้างโปรเจกต์และองค์กร
### **Phase 3: Tasks**
- **[ ] F3.1 Project Management UI**
- [ ] Create project list with search and filters
- [ ] Implement project creation and editing
- [ ] Create project detail view
- [ ] Implement project dashboard with statistics
- [ ] Add project member management
- [ ] **UX:** Intuitive project navigation and management
- [ ] **Deliverable:** Complete project management interface
- [ ] **Dependencies:** F1.1, F2.4
- **[ ] F3.2 Organization Management**
- [ ] Create organization list and management
- [ ] Implement organization creation and editing
- [ ] Create organization detail view
- [ ] Add organization user management
- [ ] Implement organization hierarchy visualization
- [ ] **Business Logic:** Proper organization-project relationships
- [ ] **Deliverable:** Comprehensive organization management
- [ ] **Dependencies:** F3.1
- **[ ] F3.3 Contract Management**
- [ ] Create contract list within projects
- [ ] Implement contract creation and editing
- [ ] Create contract detail view
- [ ] Add contract party management
- [ ] Implement contract document associations
- [ ] **Business Logic:** Contract-project-organization relationships
- [ ] **Deliverable:** Complete contract management system
- [ ] **Dependencies:** F3.1, F3.2
### **Phase 3: Testing - Project Structure**
#### **F3.T1 Project Management Test Suite**
- [ ] **Unit Tests:** Project CRUD operations, validation
- [ ] **Integration Tests:** Project-organization relationships, member management
- [ ] **Business Logic Tests:** Project hierarchy, access control
---
## **Phase 4: Correspondence System (สัปดาห์ที่ 5-6)**
**Milestone:** ระบบจัดการเอกสารโต้ตอบแบบสมบูรณ์
### **Phase 4: Tasks**
- **[ ] F4.1 Correspondence List & Search**
- [ ] Create correspondence list with advanced filtering:
- [ ] Filter by type, status, project, organization
- [ ] Search by title, document number, content
- [ ] Date range filtering
- [ ] Implement responsive data table:
- [ ] Desktop: Full table view
- [ ] Mobile: Card view conversion
- [ ] Add bulk operations (export, status change)
- [ ] Implement real-time updates
- [ ] **Performance:** Virtual scrolling for large datasets
- [ ] **Deliverable:** High-performance correspondence listing
- [ ] **Dependencies:** F1.1, F3.1
- **[ ] F4.2 Correspondence Creation Form**
- [ ] Create dynamic form generator based on JSON schema
- [ ] Implement form with multiple sections:
- [ ] Basic information (type, title, recipients)
- [ ] Content and details (JSON schema-based)
- [ ] File attachments
- [ ] Routing template selection
- [ ] [New] Implement "Originator Selector" component: Dropdown สำหรับเลือกองค์กรผู้ส่ง (แสดงเฉพาะเมื่อผู้ใช้มีสิทธิ์ system.manage_all หรือสิทธิ์พิเศษ) หากไม่เลือกให้ใช้ Organization ของผู้ใช้ตามปกติ
- [ ] Add draft auto-save functionality
- [ ] Implement form validation with Zod
- [ ] **UX:** Intuitive form with progress indication
- [ ] **Deliverable:** Flexible correspondence creation interface
- [ ] **Dependencies:** F0.4, F4.1
- **[ ] F4.3 Correspondence Detail View**
- [ ] Create comprehensive detail page:
- [ ] Document header with metadata
- [ ] Content display based on type
- [ ] Revision history
- [ ] Related documents
- [ ] Workflow status visualization
- [ ] Implement document actions:
- [ ] Edit, withdraw, cancel (with permissions)
- [ ] Download, print
- [ ] Create related documents
- [ ] Add comments and activity timeline
- [ ] **UX:** Clean, readable document presentation
- [ ] **Deliverable:** Complete document detail experience
- [ ] **Dependencies:** F4.1, F4.2
- **[ ] F4.4 File Upload Integration**
- [ ] Create drag-and-drop file upload component
- [ ] Implement file type validation and preview
- [ ] Add virus scan status indication
- [ ] Create file management interface:
- [ ] Mark files as main/supporting documents
- [ ] Reorder and manage attachments
- [ ] File security status display
- [ ] Implement two-phase upload progress
- [ ] **Security:** File type restrictions, size limits, virus scan integration
- [ ] **Deliverable:** Secure and user-friendly file management
- [ ] **Dependencies:** F0.2, F4.2
### **Phase 4: Testing - Correspondence System**
#### **F4.T1 Correspondence Test Suite**
- [ ] **Unit Tests:** Form validation, file upload components
- [ ] **Integration Tests:** Complete document lifecycle, file attachment flow
- [ ] **E2E Tests:** End-to-end correspondence creation and management
#### **F4.T2 File Upload Test Suite**
- [ ] **Unit Tests:** File validation, type checking
- [ ] **Integration Tests:** Two-phase upload process, virus scan integration
- [ ] **Security Tests:** Malicious file upload attempts, security feedback
---
## **Phase 5: Workflow Management (สัปดาห์ที่ 7)**
**Milestone:** ระบบ Visualization และจัดการ Workflow
### **Phase 5: Tasks**
- **[ ] F5.1 Workflow Visualization Component**
- [ ] Create horizontal workflow progress visualization
- [ ] Implement step status indicators (pending, active, completed, skipped)
- [ ] Add due date and assignee information
- [ ] Create interactive workflow diagram
- [ ] Implement workflow history timeline
- [ ] **UX:** Clear visual representation of complex workflows
- [ ] **Deliverable:** Intuitive workflow visualization
- [ ] **Dependencies:** F4.3
- **[ ] F5.2 Routing Template Management**
- [ ] Create routing template list and editor
- [ ] Implement drag-and-drop step configuration
- [ ] Add step configuration (purpose, duration, assignee rules)
- [ ] Create template preview functionality
- [ ] Implement template versioning
- [ ] **Business Logic:** Proper step sequencing and validation
- [ ] **Deliverable:** Comprehensive routing template management
- [ ] **Dependencies:** F3.1, F4.2
- **[ ] F5.3 Workflow Step Actions**
- [ ] Create step action interface:
- [ ] Approve, reject, request changes
- [ ] Add comments and attachments
- [ ] Forward to other users
- [ ] Implement bulk step actions
- [ ] Add action confirmation with reason required
- [ ] Create step delegation functionality
- [ ] **UX:** Streamlined step completion process
- [ ] **Deliverable:** Efficient workflow step management
- [ ] **Dependencies:** F5.1
- **[ ] F5.4 Real-time Status Updates**
- [ ] Implement WebSocket connections for real-time updates
- [ ] Create status change notifications
- [ ] Add auto-refresh for workflow states
- [ ] Implement optimistic updates for better UX
- [ ] Create update history and audit trail
- [ ] **Performance:** Efficient real-time data synchronization
- [ ] **Deliverable:** Real-time workflow monitoring
- [ ] **Dependencies:** F5.1, F9.2
### **Phase 5: Testing - Workflow Management**
#### **F5.T1 Workflow Test Suite**
- [ ] **Unit Tests:** Workflow visualization, step status logic
- [ ] **Integration Tests:** Complete workflow execution, real-time updates
- [ ] **E2E Tests:** Multi-step workflow with different user roles
---
## **Phase 6: Drawing System (สัปดาห์ที่ 8)**
**Milestone:** ระบบจัดการแบบแปลนแบบสมบูรณ์
### **Phase 6: Tasks**
- **[ ] F6.1 Contract Drawings Management**
- [ ] Create contract drawing list with categorization
- [ ] Implement drawing upload and metadata management
- [ ] Create drawing preview and viewer
- [ ] Add drawing version control
- [ ] Implement drawing search and filtering
- [ ] **UX:** Efficient drawing navigation and access
- [ ] **Deliverable:** Comprehensive contract drawing management
- [ ] **Dependencies:** F3.1, F4.4
- **[ ] F6.2 Shop Drawings Management**
- [ ] Create shop drawing list with revision tracking
- [ ] Implement shop drawing creation and revision system
- [ ] Create drawing comparison interface
- [ ] Add drawing approval status tracking
- [ ] Implement bulk drawing operations
- [ ] **Business Logic:** Proper revision control and approval workflows
- [ ] **Deliverable:** Complete shop drawing management system
- [ ] **Dependencies:** F6.1
- **[ ] F6.3 Drawing Revision System**
- [ ] Create revision history interface
- [ ] Implement revision comparison functionality
- [ ] Add revision notes and change tracking
- [ ] Create revision approval workflow
- [ ] Implement revision rollback capability
- [ ] **UX:** Clear visualization of changes between revisions
- [ ] **Deliverable:** Robust drawing revision control
- [ ] **Dependencies:** F6.2
- **[ ] F6.4 Drawing References**
- [ ] Create drawing reference management
- [ ] Implement cross-drawing references
- [ ] Add reference validation and integrity checks
- [ ] Create reference visualization
- [ ] Implement reference impact analysis
- [ ] **Business Logic:** Maintain reference integrity during changes
- [ ] **Deliverable:** Comprehensive drawing reference system
- [ ] **Dependencies:** F6.2, F6.3
### **Phase 6: Testing - Drawing System**
#### **F6.T1 Drawing Management Test Suite**
- [ ] **Unit Tests:** Drawing CRUD operations, revision logic
- [ ] **Integration Tests:** Drawing approval workflows, reference management
- [ ] **E2E Tests:** Complete drawing lifecycle with revisions
---
## **Phase 7: RFA System (สัปดาห์ที่ 9-10)**
**Milestone:** ระบบขออนุมัติแบบสมบูรณ์พร้อม Dynamic Forms
### **Phase 7: Tasks**
- **[ ] F7.1 RFA List & Dashboard**
- [ ] Create RFA dashboard with status overview
- [ ] Implement advanced RFA filtering and search
- [ ] Create RFA calendar view for deadlines
- [ ] Add RFA statistics and reporting
- [ ] Implement RFA bulk operations
- [ ] **UX:** Comprehensive RFA overview and management
- [ ] **Deliverable:** Complete RFA dashboard and listing
- [ ] **Dependencies:** F4.1, F5.1
- **[ ] F7.2 RFA Creation with Dynamic Forms**
- [ ] Create RFA type-specific form generator
- [ ] Implement dynamic form fields based on RFA type:
- [ ] RFA_DWG: Shop drawing selection
- [ ] RFA_DOC: Document specifications
- [ ] RFA_MES: Method statement details
- [ ] RFA_MAT: Material specifications
- [ ] Add form validation with JSON schema
- [ ] Implement form data persistence and recovery
- [ ] **UX:** Intuitive form experience for complex RFA types
- [ ] Dynamic Form & Schema Validation: สร้าง Component Dynamic Form Generator ที่:
- [ ] Fetch Schema: ดึงโครงสร้าง JSON Schema ที่ถูกต้องตาม rfa_type จาก Backend (ตาราง json_schemas ที่สร้างใหม่) ก่อนการ Render Form.
- [ ] Client-side Validation: Implement AJV (Another JSON Schema Validator) หรือไลบรารีที่เทียบเท่า เพื่อทำ Client-side Validation บนข้อมูล JSON ก่อนส่ง Submit.
- [ ] Implement dynamic form fields based on RFA type: RFA_DWG, RFA_DOC, RFA_MES, RFA_MAT.
- [ ] Add form data persistence and recovery.
- [ ] **Deliverable:** Flexible RFA creation system
- [ ] **Dependencies:** F4.2, F6.2
- **[ ] F7.3 RFA Workflow Integration**
- [ ] Integrate RFA with unified workflow engine
- [ ] Create RFA-specific workflow steps and actions
- [ ] Implement RFA approval interface
- [ ] Add RFA workflow history and tracking
- [ ] Create RFA workflow templates
- [ ] **Business Logic:** Proper RFA approval sequencing and validation
- [ ] **Deliverable:** Seamless RFA workflow integration
- [ ] **Dependencies:** F5.1, F7.2
- **[ ] F7.4 RFA Approval Interface**
- [ ] Create RFA review and approval interface
- [ ] Implement side-by-side document comparison
- [ ] Add approval comments and attachments
- [ ] Create conditional approval workflows
- [ ] Implement approval delegation and escalation
- [ ] **UX:** Efficient approval process for technical reviews
- [ ] **Deliverable:** Comprehensive RFA approval system
- [ ] **Dependencies:** F7.1, F7.3
### **Phase 7: Testing - RFA System**
#### **F7.T1 RFA Test Suite**
- [ ] **Unit Tests:** RFA form generation, validation logic
- [ ] **Integration Tests:** Complete RFA lifecycle, workflow integration
- [ ] **E2E Tests:** Multi-type RFA creation and approval workflows
---
## **Phase 8: Internal Workflows (สัปดาห์ที่ 11)**
**Milestone:** ระบบใบเวียนและการจัดการงานภายใน
### **Phase 8: Tasks**
- **[ ] F8.1 Circulation Management**
- [ ] Create circulation list and management interface
- [ ] Implement circulation creation from correspondence
- [ ] Create circulation template management
- [ ] Add circulation status tracking
- [ ] Implement circulation search and filtering
- [ ] **Business Logic:** Proper circulation-correspondence relationships
- [ ] **Deliverable:** Comprehensive circulation management
- [ ] **Dependencies:** F4.1, F5.2
- **[ ] F8.2 Task Assignment Interface**
- [ ] Create task assignment interface with user selection
- [ ] Implement task priority and deadline setting
- [ ] Add task dependency management
- [ ] Create task progress tracking
- [ ] Implement task reassignment and delegation
- [ ] **UX:** Intuitive task management and assignment
- [ ] **Deliverable:** Efficient task assignment system
- [ ] **Dependencies:** F8.1
- **[ ] F8.3 Internal Approval Flows**
- [ ] Create internal approval workflow interface
- [ ] Implement multi-level approval processes
- [ ] Add approval chain visualization
- [ ] Create approval delegation system
- [ ] Implement approval deadline management
- [ ] **Business Logic:** Proper approval hierarchy and escalation
- [ ] **Deliverable:** Robust internal approval system
- [ ] **Dependencies:** F8.1, F8.2
### **Phase 8: Testing - Internal Workflows**
#### **F8.T1 Circulation Test Suite**
- [ ] **Unit Tests:** Circulation creation, task assignment logic
- [ ] **Integration Tests:** Complete circulation workflow, internal approvals
- [ ] **E2E Tests:** End-to-end circulation with task completion
---
## **Phase 9: Advanced Features (สัปดาห์ที่ 12)**
**Milestone:** ฟีเจอร์ขั้นสูงและการปรับปรุงประสบการณ์ผู้ใช้
### **Phase 9: Tasks**
- **[ ] F9.1 Advanced Search Interface**
- [ ] Create unified search interface across all document types
- [ ] Implement faceted search with multiple filters
- [ ] Add search result highlighting and relevance scoring
- [ ] Create saved search and search templates
- [ ] Implement search result export functionality
- [ ] **Performance:** Efficient search with large datasets
- [ ] **Deliverable:** Powerful cross-document search system
- [ ] **Dependencies:** F4.1, F7.1
- **[ ] F9.2 Notification System**
- [ ] Create notification center with real-time updates
- [ ] Implement notification preferences management
- [ ] Add notification grouping and digest views
- [ ] Create actionable notifications with quick actions
- [ ] Implement notification read/unread status
- [ ] **UX:** Non-intrusive but effective notification delivery
- [ ] **Deliverable:** Comprehensive notification management
- [ ] **Dependencies:** F1.3, F5.4
- **[ ] F9.3 Reporting & Analytics**
- [ ] Create reporting dashboard with customizable widgets
- [ ] Implement data visualization components (charts, graphs)
- [ ] Add report scheduling and export
- [ ] Create ad-hoc reporting interface
- [ ] Implement performance metrics tracking
- [ ] **Business Logic:** Accurate data aggregation and reporting
- [ ] **Deliverable:** Powerful reporting and analytics system
- [ ] **Dependencies:** F1.3, F7.1
- **[ ] F9.4 Mobile Optimization**
- [ ] Implement touch-optimized interactions
- [ ] Create mobile-specific navigation patterns
- [ ] Add offline capability for critical functions
- [ ] Optimize images and assets for mobile networks
- [ ] Implement mobile-specific performance optimizations
- [ ] **UX:** Seamless mobile experience comparable to desktop
- [ ] **Deliverable:** Fully optimized mobile application
- [ ] **Dependencies:** F1.4
### **Phase 9: Testing - Advanced Features**
#### **F9.T1 Advanced Features Test Suite**
- [ ] **Unit Tests:** Search algorithms, notification logic
- [ ] **Integration Tests:** Cross-module search, real-time notifications
- [ ] **Performance Tests:** Search performance, mobile responsiveness
---
## **Phase 10: Testing & Polish (สัปดาห์ที่ 13-14)**
**Milestone:** แอปพลิเคชันที่ผ่านการทดสอบและปรับปรุงอย่างสมบูรณ์
### **Phase 10: Tasks**
- **[ ] F10.1 Comprehensive Testing**
- [ ] Idempotency Testing: เพิ่มการทดสอบเฉพาะสำหรับ Axios Interceptor เพื่อจำลองการส่ง Request POST/PUT/DELETE ที่มี Idempotency-Key ซ้ำไปยัง Mock API (MSW) เพื่อยืนยันว่า Client-side ไม่ส่ง Key ซ้ำในการทำงานปกติ และไม่เกิด Side Effect จากการ Replay Attack.
- [ ] Write unit tests for all components and utilities
- [ ] Create integration tests for critical user flows
- [ ] Implement E2E tests for complete workflows
- [ ] Perform cross-browser compatibility testing
- [ ] Conduct accessibility testing (WCAG 2.1 AA)
- [ ] **Quality:** 80%+ test coverage, all critical paths tested
- [ ] **Deliverable:** Fully tested application
- [ ] **Dependencies:** All previous phases
- **[ ] F10.2 Performance Optimization**
- [ ] Implement code splitting and lazy loading
- [ ] Optimize bundle size and asset delivery
- [ ] Add performance monitoring and metrics
- [ ] Implement caching strategies for static assets
- [ ] Optimize API call patterns and reduce over-fetching
- [ ] **Performance:** Core Web Vitals targets met
- [ ] **Deliverable:** High-performance application
- [ ] **Dependencies:** F10.1
- **[ ] F10.3 Security Hardening**
- [ ] Conduct security audit and penetration testing
- [ ] Implement Content Security Policy (CSP)
- [ ] Add security headers and protections
- [ ] Conduct dependency vulnerability scanning
- [ ] Implement secure coding practices review
- [ ] **Security:** No critical security vulnerabilities
- [ ] **Deliverable:** Security-hardened application
- [ ] **Dependencies:** F10.1
- **[ ] F10.4 Documentation**
- [ ] Create user documentation and guides
- [ ] Write technical documentation for developers
- [ ] Create API integration documentation
- [ ] Add inline code documentation
- [ ] Create deployment and maintenance guides
- [ ] **Quality:** Comprehensive and up-to-date documentation
- [ ] **Deliverable:** Complete documentation suite
- [ ] **Dependencies:** F10.1
### **Phase 10: Testing - Final Validation**
#### **F10.T1 Final Test Suite**
- [ ] **Performance Tests:** Load testing, stress testing
- [ ] **Security Tests:** Final security audit, vulnerability assessment
- [ ] **User Acceptance Tests:** Real user testing, feedback incorporation
- [ ] **Compatibility Tests:** Cross-browser, cross-device testing
---
## 📊 **สรุป Timeline**
| Phase | ระยะเวลา | จำนวนงาน | Output หลัก |
| -------- | ------------ | ------------ | ------------------------------------ |
| Phase 0 | 1 สัปดาห์ | 4 | Foundation & Tooling Ready |
| Phase 1 | 1 สัปดาห์ | 4 | Core Application Structure |
| Phase 2 | 1 สัปดาห์ | 4 | User Management & Security |
| Phase 3 | 1 สัปดาห์ | 3 | Project Structure Management |
| Phase 4 | 2 สัปดาห์ | 4 | Correspondence System |
| Phase 5 | 1 สัปดาห์ | 4 | Workflow Management |
| Phase 6 | 1 สัปดาห์ | 4 | Drawing System |
| Phase 7 | 2 สัปดาห์ | 4 | RFA System (Dynamic Forms) |
| Phase 8 | 1 สัปดาห์ | 3 | Internal Workflows |
| Phase 9 | 1 สัปดาห์ | 4 | Advanced Features |
| Phase 10 | 2 สัปดาห์ | 4 | Testing & Polish (Idempotency Test) |
| **รวม** | **14 สัปดาห์** | **39 Tasks** | **Production-Ready Frontend v1.4.2** |
---
## 🎯 **Critical Success Factors**
1. **User Experience First:** ทุกฟีเจอร์ต้องออกแบบเพื่อประสบการณ์ผู้ใช้ที่ดี
2. **Responsive Design:** รองรับการใช้งานบนอุปกรณ์ทุกรูปแบบ
3. **Performance:** Core Web Vitals ต้องอยู่ในเกณฑ์ที่ดี
4. **Accessibility:** ต้องเป็นไปตามมาตรฐาน WCAG 2.1 AA
5. **Security:** ป้องกัน XSS, CSRF และความเสี่ยงด้านความปลอดภัยอื่นๆ
6. **Offline Support:** รองรับการทำงานแบบ Offline เบื้องต้น
7. **Real-time Updates:** การอัปเดตสถานะแบบ Real-time
8. **Testing Coverage:** ครอบคลุมการทดสอบทุก Critical Path
9. **Documentation:** เอกสารครบถ้วนสำหรับผู้ใช้และนักพัฒนา
---
## 📋 **Quality Assurance Checklist**
### **ก่อน Production Deployment**
- [ ] **Performance:** Core Web Vitals ผ่านเกณฑ์
- [ ] **Accessibility:** WCAG 2.1 AA compliant
- [ ] **Security:** Security audit ผ่าน
- [ ] **Testing:** Test coverage ≥ 80%
- [ ] **Browser Compatibility:** ทำงานได้บนเบราว์เซอร์หลัก
- [ ] **Mobile Responsive:** ใช้งานได้ดีบนมือถือ
- [ ] **Documentation:** เอกสารครบถ้วน
- [ ] **User Acceptance:** ได้รับการยอมรับจากผู้ใช้
---
## 🚀 **ขั้นตอนถัดไป**
1. **Approve แผนนี้** → ปรับแต่งตาม Feedback
2. **Coordinate กับ Backend Team** → Sync API Specifications
3. **เริ่มพัฒนา Phase 0** → Setup Foundation
4. **Regular Sync** → ประสานงานกับ Backend ทุกสัปดาห์
5. **User Testing** → ทดสอบกับผู้ใช้จริงระหว่างพัฒนา
6. **Deploy to Production** → Week 15 (พร้อม Backend)
## **Document Control:**
- **Document:** Frontend Development Plan v1.4.3
- **Version:** 1.4
- **Date:** 2025-11-22
- **Author:** NAP LCBP3-DMS & Gemini
- **Status:** FINAL
- **Classification:** Internal Technical Documentation
- **Approved By:** Nattanin
---
`End of Frontend Development Plan v1.4.3 (ฉบับปรับปรุง)`

978
infrastructure/Markdown/3_Frontend_Plan_V1_4_4.md Normal file
View File

@@ -0,0 +1,978 @@
# 📋 **แผนการพัฒนา Frontend (Next.js) - LCBP3-DMS v1.4.4**
**สถานะ:** FINAL GUIDELINE Rev.04
**วันที่:** 2025-11-26
**อ้างอิง:** Requirements v1.4.3 & FullStackJS Guidelines v1.4.3
**Classification:** Internal Technical Documentation
## 🎯 **ภาพรวมโครงการ**
พัฒนา Frontend สำหรับระบบบริหารจัดการเอกสารโครงการ (Document Management System) ที่มีความทันสมัย รองรับการทำงานบนอุปกรณ์ต่างๆ ได้อย่างสมบูรณ์ มีประสบการณ์ผู้ใช้ที่ราบรื่น และรองรับการทำงานแบบ Offline เบื้องต้น
---
## 📐 **สถาปัตยกรรมระบบ**
### **Technology Stack**
- **Framework:** Next.js 14+ (App Router, React 18, TypeScript, ESM)
- **Styling:** Tailwind CSS + PostCSS
- **UI Components:** shadcn/ui + Radix UI Primitives
- **State Management:**
- **Server State:** TanStack Query (React Query)
- **Client State:** Zustand
- **Form State:** React Hook Form + Zod
- **API Client:** Axios (พร้อม Idempotency Interceptor)
- **Authentication:** NextAuth.js (รองรับ JWT)
- **File Upload:** Custom Hook + Drag & Drop
- **Testing:**
- **Unit/Integration:** Vitest + React Testing Library
- **E2E:** Playwright
- **Mocking:** MSW (Mock Service Worker)
- **Development:**
- **Package Manager:** pnpm
- **Linting:** ESLint + Prettier
- **Type Checking:** TypeScript Strict Mode
### **โครงสร้างโปรเจกต์**
```
📁frontend
├── .env.local
├── .eslintrc.json
├── .gitignore
├── components.json
├── middleware.ts
├── next-env.d.ts
├── next.config.mjs
├── package.json
├── pnpm-lock.yaml
├── postcss.config.mjs
├── README.md
├── tailwind.config.ts
├── tsconfig.json
├── 📁app
│ ├── 📁(auth)
│ │ └── 📁login
│ │ │ └── page.tsx
│ │ └── layout.tsx
│ ├── 📁(dashboard)
│ │ └── 📁admin
│ │ ├──📁users
│ │ │ └── page.tsx
│ │ ├──📁correspondences
│ │ │ └── 📁new
│ │ │ │ └── page.tsx
│ │ │ └── page.tsx
│ │ ├──📁dashboard
│ │ │ └── page.tsx
│ │ ├──📁profile
│ │ │ └── page.tsx
│ │ ├──📁projects
│ │ │ ├──📁new
│ │ │ │ └── page.tsx
│ │ │ └── page.tsx
│ │ └── layout.tsx
│ ├── 📁api
│ │ └── 📁auth
│ │ └── 📁[...nextauth]
│ │ └── route.ts
│ ├── 📁demo
│ │ └── page.tsx
│ ├── 📁fonts
│ │ ├── GeistMonoVF.woff
│ │ └── GeistVF.woff
│ ├── favicon.ico
│ ├── globals copy.css
│ ├── globals.css
│ ├── layout copy.tsx
│ ├── layout.tsx
│ └── page.tsx
├── 📁components
│ ├── 📁custom
│ │ ├── file-upload-zone.tsx
│ │ ├── responsive-data-table.tsx
│ │ └── workflow-visualizer.tsx
│ ├── 📁dashboard
│ │ └── recent-activity.tsx
│ ├── 📁forms
│ │ └── file-upload.tsx
│ ├── 📁layout
│ │ ├── dashboard-shell.tsx
│ │ ├── navbar.tsx
│ │ ├── sidebar.tsx
│ │ └── user-nav.tsx
│ ├── 📁tables
│ └── 📁ui
│ ├── avatar.tsx
│ ├── badge.tsx
│ ├── button.tsx
│ ├── calendar.tsx
│ ├── card.tsx
│ ├── checkbox.tsx
│ ├── dropdown-menu.tsx
│ ├── input.tsx
│ ├── label.tsx
│ ├── popover.tsx
│ ├── progress.tsx
│ ├── scroll-area.tsx
│ ├── select.tsx
│ ├── switch.tsx
│ ├── table.tsx
│ ├── tabs.tsx
│ └── textarea.tsx
├── 📁config
│ └── menu.ts
├── 📁lib
│ ├── 📁api
│ │ └── client.ts
│ ├── 📁auth
│ ├── 📁hooks
│ ├── 📁services
│ │ ├── circulation.service.ts
│ │ ├── contract-drawing.service.ts
│ │ ├── correspondence.service.ts
│ │ ├── index.ts
│ │ ├── json-schema.service.ts
│ │ ├── master-data.service.ts
│ │ ├── monitoring.service.ts
│ │ ├── notification.service.ts
│ │ ├── project.service.ts
│ │ ├── rfa.service.ts
│ │ ├── search.service.ts
│ │ ├── shop-drawing.service.ts
│ │ ├── transmittal.service.ts
│ │ ├── user.service.ts
│ │ └── workflow-engine.service.ts
│ ├── 📁stores
│ │ ├── draft-store.ts
│ │ └── ui-store.ts
│ ├── auth.ts
│ └── utils.ts
├── 📁providers
│ ├── query-provider.tsx
│ └── session-provider.tsx
├── 📁public
├── 📁styles
└── 📁types
└── 📁dto
└── next-auth.d.ts
├── 📁circulation
│ ├── create-circulation.dto.ts
│ ├── search-circulation.dto.ts
│ └── update-circulation-routing.dto.ts
├── 📁correspondence
│ ├── add-reference.dto.ts
│ ├── create-correspondence.dto.ts
│ ├── search-correspondence.dto.ts
│ ├── submit-correspondence.dto.ts
│ └── workflow-action.dto.ts
├── 📁drawing
│ ├── contract-drawing.dto.ts
│ └── shop-drawing.dto.ts
├── 📁json-schema
│ └── json-schema.dto.ts
├── 📁master
│ ├── discipline.dto.ts
│ ├── number-format.dto.ts
│ ├── sub-type.dto.ts
│ └── tag.dto.ts
├── 📁monitoring
│ └── set-maintenance.dto.ts
├── 📁notification
│ └── notification.dto.ts
├── 📁project
│ └── project.dto.ts
├── 📁rfa
│ └── rfa.dto.ts
├── 📁search
│ └── search-query.dto.ts
├── 📁transmittal
│ └── transmittal.dto.ts
├── 📁user
│ └── user.dto.ts
└── 📁workflow-engine
└── workflow-engine.dto.ts
```
---
## 🗓️ **แผนการพัฒนาแบบ Phase-Based**
### **Phase 0: Foundation & Configuration (สัปดาห์ที่ 1)**
**Milestone:** โครงสร้างพื้นฐานพร้อม รองรับ Development Workflow ที่มีประสิทธิภาพ
### **Phase 0: Tasks**
- **[ ] F0.1 Project Setup & Tooling**
- [ ] Initialize Next.js 14+ project with TypeScript
- [ ] Configure pnpm workspace
- [ ] Setup ESLint, Prettier, and pre-commit hooks
- [ ] Configure Tailwind CSS with PostCSS
- [ ] Setup shadcn/ui components
- [ ] Configure absolute imports and path aliases
- [ ] **Deliverable:** Development environment ready
- [ ] **Dependencies:** None
- **[ ] F0.2 Design System & UI Components**
- [ ] Setup color palette and design tokens
- [ ] Create responsive design breakpoints
- [ ] Implement core shadcn/ui components:
- [ ] Button, Input, Label, Form
- [ ] Card, Table, Badge
- [ ] Dialog, Dropdown, Select
- [ ] Tabs, Accordion
- [ ] Create custom design system components:
- [ ] DataTable (responsive)
- [ ] FileUpload **zone**
- [ ] Workflow visualization
- [ ] **Deliverable:** Consistent UI component library
- [ ] **Dependencies:** F0.1
- **[ ] F0.3 API Client & Authentication**
- [ ] Setup Axios client with interceptors:
- [ ] Idempotency-Key header injection
- [ ] Authentication token management
- [ ] Error handling and retry logic
- [ ] Configure NextAuth.js for JWT authentication
- [ ] Create auth hooks (useAuth, usePermissions)
- [ ] Setup API route handlers for auth callbacks
- [ ] **Security:** Implement secure token storage
- [ ] **Deliverable:** Secure API communication layer
- [ ] **Dependencies:** F0.1
- **[ ] F0.4 State Management Setup**
- [ ] Configure TanStack Query for server state:
- [ ] Query client setup
- [ ] Default configurations
- [ ] Error boundaries
- [ ] Create Zustand stores:
- [ ] Auth store (user, permissions)
- [ ] UI store (theme, sidebar state)
- [ ] Draft store (form auto-save)
- [ ] Setup React Hook Form with Zod integration
- [ ] Create form validation schemas
- [ ] **Deliverable:** Robust state management system
- [ ] **Dependencies:** F0.1, F0.3
### **Phase 0: Testing - Foundation**
#### **F0.T1 Component Test Suite**
- [ ] **Unit Tests:** Core UI components (Button, Input, Card)
- [ ] **Integration Tests:** Form validation, API client interceptors
- [ ] **Visual Tests:** Component styling and responsive behavior
#### **F0.T2 Authentication Test Suite**
- [ ] **Unit Tests:** Auth hooks, token management
- [ ] **Integration Tests:** Login/logout flow, permission checks
- [ ] **Security Tests:** Token security, API authentication
---
### **Phase 1: Core Application Structure (สัปดาห์ที่ 2)**
**Milestone:** Layout หลักพร้อมใช้งาน การนำทางและ Authentication ทำงานได้
### **Phase 1: Tasks**
- **[ ] F1.1 Main Layout & Navigation**
- [ ] Create App Shell layout:
- [ ] Navbar with user menu and notifications
- [ ] Collapsible sidebar with navigation
- [ ] Main content area with responsive design
- [ ] Implement navigation menu structure:
- [ ] Dashboard, Correspondences, RFAs, Drawings, etc.
- [ ] Dynamic menu based on user permissions
- [ ] Create breadcrumb navigation component
- [ ] Implement mobile-responsive sidebar (drawer)
- [ ] Maintenance Mode Integration:
- [ ] Implement a Global Middleware/Wrapper ที่ตรวจสอบสถานะ Maintenance Mode ผ่าน API/Service ก่อนการ Render หน้า หากสถานะเป็น true ให้ Redirect ผู้ใช้ (ยกเว้น Admin) ไปยังหน้า /maintenance ทันที เพื่อให้สอดคล้องกับ Logic ของ Backend.
- [ ] **Accessibility:** Ensure keyboard navigation and screen reader support
- [ ] **Deliverable:** Fully functional application layout
- [ ] **Dependencies:** F0.2, F0.3
- **[ ] F1.2 Authentication Pages**
- [ ] Create login page with form validation
- [ ] Implement forgot password flow
- [ ] Create registration page (admin-only)
- [ ] Setup protected route middleware
- [ ] Implement route-based permission checks
- [ ] **Security:** Rate limiting on auth attempts, secure password requirements
- [ ] **Deliverable:** Complete authentication flow
- [ ] **Dependencies:** F0.3, F1.1
- **[ ] F1.3 Dashboard & Landing**
- [ ] Create public landing page for non-authenticated users
- [ ] Implement main dashboard with:
- [ ] KPI cards (document counts, pending tasks)
- [ ] "My Tasks" table from v_user_tasks
- [ ] Recent activity feed
- [ ] Security metrics display
- [ ] Create dashboard widgets system
- [ ] Implement data fetching with TanStack Query
- [ ] **Performance:** Optimize dashboard data loading
- [ ] **Deliverable:** Functional dashboard with real data
- [ ] **Dependencies:** F0.4, F1.1
- **[ ] F1.4 Responsive Design System**
- [ ] Implement mobile-first responsive design
- [ ] Create card view components for mobile tables
- [ ] Setup touch-friendly interactions
- [ ] Optimize images and assets for mobile
- [ ] Test across multiple device sizes
- [ ] **UX:** Ensure seamless mobile experience
- [ ] **Deliverable:** Fully responsive application
- [ ] **Dependencies:** F0.2, F1.1
### **Phase 1: Testing - Core Structure**
- **[ ] F1.T1 Layout Test Suite**
- [ ] **Unit Tests:** Navigation components, layout responsiveness
- [ ] **Integration Tests:** Route protection, permission-based navigation
- [ ] **E2E Tests:** Complete user navigation flow
- **[ ] F1.T2 Dashboard Test Suite**
- [ ] **Unit Tests:** Dashboard components, data formatting
- [ ] **Integration Tests:** Data fetching and display, real-time updates
- [ ] **Performance Tests:** Dashboard loading performance
---
### **Phase 2: User Management & Security (สัปดาห์ที่ 3)**
**Milestone:** การจัดการผู้ใช้และสิทธิ์แบบสมบูรณ์
### **Phase 2: Tasks**
- **[ ] F2.1 User Profile & Settings**
- [ ] Create user profile page:
- [ ] Personal information display/edit
- [ ] Password change functionality
- [ ] Notification preferences
- [ ] Implement profile picture upload
- [ ] Create user settings page
- [ ] **Security:** Secure password change with current password verification
- [ ] **Deliverable:** Complete user self-service management
- [ ] **Dependencies:** F1.1, F0.4
- **[ ] F2.2 Admin Panel - User Management**
- [ ] Create user list with search and filters
- [ ] Implement user creation form
- [ ] Create user edit interface
- [ ] Implement bulk user operations
- [ ] Add user activity tracking display
- [ ] **Security:** Admin-only access enforcement
- [ ] **Deliverable:** Comprehensive user management interface
- [ ] **Dependencies:** F1.1, F2.1
- **[ ] F2.3 Admin Panel - Role Management**
- [ ] Create role list and management interface
- [ ] Implement role creation and editing
- [ ] Create permission assignment interface
- [ ] Implement role-based access control visualization
- [ ] Add role usage statistics
- [ ] **Security:** Permission hierarchy enforcement
- [ ] **Deliverable:** Complete RBAC management system
- [ ] **Dependencies:** F2.2
- **[ ] F2.4 Permission Integration**
- [ ] Implement CASL ability integration
- [ ] Create permission-based UI components:
- [ ] ProtectedButton, ProtectedLink
- [ ] Conditional rendering based on permissions
- [ ] Setup real-time permission updates
- [ ] Implement permission debugging tools
- [ ] **Security:** Frontend-backend permission consistency
- [ ] **Deliverable:** Seamless permission enforcement throughout app
- [ ] **Dependencies:** F0.3, F2.3
### **Phase 2: User Management & Admin Panel (สัปดาห์ที่ 3)**
- **[ ] F2.5 Admin Panel - Master Data Management (Req 6B)** (New)
- [ ] Create "Disciplines Management" page (CRUD)
- [ ] Create "Sub-Types Management" page (CRUD + Mapping Number)
- [ ] Create "Numbering Format" configuration page (Template Editor)
- [ ] **Deliverable:** UI for Admin to configure system master data
- [ ] **Dependencies:** F2.1
### **Phase 2: Testing - User Management**
- **[ ] F2.T1 User Management Test Suite**
- [ ] **Unit Tests:** User CRUD operations, form validation
- [ ] **Integration Tests:** User-role assignment, permission propagation
- [ ] **Security Tests:** Permission escalation attempts, admin access control
- **[ ] F2.T2 RBAC Test Suite**
- [ ] **Unit Tests:** Permission checks, role validation
- [ ] **Integration Tests:** Multi-level permission enforcement, UI element protection
- [ ] **E2E Tests:** Complete role-based workflow testing
---
### **Phase 3: Project Structure (สัปดาห์ที่ 4)**
**Milestone:** การจัดการโครงสร้างโปรเจกต์และองค์กร
### **Phase 3: Tasks**
- **[ ] F3.1 Project Management UI**
- [ ] Create project list with search and filters
- [ ] Implement project creation and editing
- [ ] Create project detail view
- [ ] Implement project dashboard with statistics
- [ ] Add project member management
- [ ] **UX:** Intuitive project navigation and management
- [ ] **Deliverable:** Complete project management interface
- [ ] **Dependencies:** F1.1, F2.4
- **[ ] F3.2 Organization Management**
- [ ] Create organization list and management
- [ ] Implement organization creation and editing
- [ ] Create organization detail view
- [ ] Add organization user management
- [ ] Implement organization hierarchy visualization
- [ ] **Business Logic:** Proper organization-project relationships
- [ ] **Deliverable:** Comprehensive organization management
- [ ] **Dependencies:** F3.1
- **[ ] F3.3 Contract Management**
- [ ] Create contract list within projects
- [ ] Implement contract creation and editing
- [ ] Create contract detail view
- [ ] Add contract party management
- [ ] Implement contract document associations
- [ ] **Business Logic:** Contract-project-organization relationships
- [ ] **Deliverable:** Complete contract management system
- [ ] **Dependencies:** F3.1, F3.2
### **Phase 3: Testing - Project Structure**
- **[ ] F3.T1 Project Management Test Suite**
- [ ] **Unit Tests:** Project CRUD operations, validation
- [ ] **Integration Tests:** Project-organization relationships, member management
- [ ] **Business Logic Tests:** Project hierarchy, access control
---
### **Phase 4: Correspondence System (สัปดาห์ที่ 5-6)**
**Milestone:** ระบบจัดการเอกสารโต้ตอบแบบสมบูรณ์
### **Phase 4: Tasks**
- **[ ] F4.1 Correspondence List & Search**
- [ ] Create correspondence list with advanced filtering:
- [ ] Filter by type, status, project, organization
- [ ] Search by title, document number, content
- [ ] Date range filtering
- [ ] Implement responsive data table:
- [ ] Desktop: Full table view
- [ ] Mobile: Card view conversion
- [ ] Add bulk operations (export, status change)
- [ ] Implement real-time updates
- [ ] **Performance:** Virtual scrolling for large datasets
- [ ] **Deliverable:** High-performance correspondence listing
- [ ] **Dependencies:** F1.1, F3.1
- **[ ] F4.2 Correspondence Creation Form**
- [ ] Create dynamic form generator based on JSON schema
- [ ] Implement form with multiple sections:
- [ ] Basic information (type, title, recipients)
- [ ] Content and details (JSON schema-based)
- [ ] File attachments
- [ ] Routing template selection
- [ ] [New] Implement "Originator Selector" component: Dropdown สำหรับเลือกองค์กรผู้ส่ง (แสดงเฉพาะเมื่อผู้ใช้มีสิทธิ์ system.manage_all หรือสิทธิ์พิเศษ) หากไม่เลือกให้ใช้ Organization ของผู้ใช้ตามปกติ
- [ ] **[New] Discipline Selector:** Add Dropdown for Disciplines (Dependent on Contract/Project)
- [ ] **[New] Sub-Type Selector:** Add Dropdown for Sub-types (Dependent on Type)
- [ ] Logic: Show/Hide selectors based on Document Type configuration
- [ ] Add draft auto-save functionality
- [ ] Implement form validation with Zod
- [ ] **UX:** Intuitive form with progress indication
- [ ] **Deliverable:** Flexible correspondence creation interface
- [ ] **Dependencies:** F0.4, F4.1
- **[ ] F4.3 Correspondence Detail View**
- [ ] Create comprehensive detail page:
- [ ] Document header with metadata
- [ ] Content display based on type
- [ ] Revision history
- [ ] Related documents
- [ ] Workflow status visualization
- [ ] Implement document actions:
- [ ] Edit, withdraw, cancel (with permissions)
- [ ] Download, print
- [ ] Create related documents
- [ ] Add comments and activity timeline
- [ ] **UX:** Clean, readable document presentation
- [ ] **Deliverable:** Complete document detail experience
- [ ] **Dependencies:** F4.1, F4.2
- **[ ] F4.4 File Upload Integration**
- [ ] Create drag-and-drop file upload component
- [ ] Implement file type validation and preview
- [ ] Add virus scan status indication
- [ ] Create file management interface:
- [ ] Mark files as main/supporting documents
- [ ] Reorder and manage attachments
- [ ] File security status display
- [ ] Implement two-phase upload progress
- [ ] **Security:** File type restrictions, size limits, virus scan integration
- [ ] **Deliverable:** Secure and user-friendly file management
- [ ] **Dependencies:** F0.2, F4.2
### **Phase 4: Testing - Correspondence System**
- **[ ] F4.T1 Correspondence Test Suite**
- [ ] **Unit Tests:** Form validation, file upload components
- [ ] **Integration Tests:** Complete document lifecycle, file attachment flow
- [ ] **E2E Tests:** End-to-end correspondence creation and management
- **[ ] F4.T2 File Upload Test Suite**
- [ ] **Unit Tests:** File validation, type checking
- [ ] **Integration Tests:** Two-phase upload process, virus scan integration
- [ ] **Security Tests:** Malicious file upload attempts, security feedback
---
### **Phase 5: Workflow Management (สัปดาห์ที่ 7)**
**Milestone:** ระบบ Visualization และจัดการ Workflow
### **Phase 5: Tasks**
- **[ ] F5.1 Workflow Visualization Component**
- [ ] Create horizontal workflow progress visualization
- [ ] Implement step status indicators (pending, active, completed, skipped)
- [ ] Add due date and assignee information
- [ ] Create interactive workflow diagram
- [ ] Implement workflow history timeline
- [ ] **UX:** Clear visual representation of complex workflows
- [ ] **Deliverable:** Intuitive workflow visualization
- [ ] **Dependencies:** F4.3
- **[ ] F5.2 Routing Template Management**
- [ ] Create routing template list and editor
- [ ] Implement drag-and-drop step configuration
- [ ] Add step configuration (purpose, duration, assignee rules)
- [ ] Create template preview functionality
- [ ] Implement template versioning
- [ ] **Business Logic:** Proper step sequencing and validation
- [ ] **Deliverable:** Comprehensive routing template management
- [ ] **Dependencies:** F3.1, F4.2
- **[ ] F5.3 Workflow Step Actions**
- [ ] Create step action interface:
- [ ] Approve, reject, request changes
- [ ] Add comments and attachments
- [ ] Forward to other users
- [ ] Implement bulk step actions
- [ ] Add action confirmation with reason required
- [ ] Create step delegation functionality
- [ ] **UX:** Streamlined step completion process
- [ ] **Deliverable:** Efficient workflow step management
- [ ] **Dependencies:** F5.1
- **[ ] F5.4 Real-time Status Updates**
- [ ] Implement WebSocket connections for real-time updates
- [ ] Create status change notifications
- [ ] Add auto-refresh for workflow states
- [ ] Implement optimistic updates for better UX
- [ ] Create update history and audit trail
- [ ] **Performance:** Efficient real-time data synchronization
- [ ] **Deliverable:** Real-time workflow monitoring
- [ ] **Dependencies:** F5.1, F9.2
### **Phase 5: Testing - Workflow Management**
- **[ ] F5.T1 Workflow Test Suite**
- [ ] **Unit Tests:** Workflow visualization, step status logic
- [ ] **Integration Tests:** Complete workflow execution, real-time updates
- [ ] **E2E Tests:** Multi-step workflow with different user roles
---
### **Phase 6: Drawing System (สัปดาห์ที่ 8)**
**Milestone:** ระบบจัดการแบบแปลนแบบสมบูรณ์
### **Phase 6: Tasks**
- **[ ] F6.1 Contract Drawings Management**
- [ ] Create contract drawing list with categorization
- [ ] Implement drawing upload and metadata management
- [ ] Create drawing preview and viewer
- [ ] Add drawing version control
- [ ] Implement drawing search and filtering
- [ ] **UX:** Efficient drawing navigation and access
- [ ] **Deliverable:** Comprehensive contract drawing management
- [ ] **Dependencies:** F3.1, F4.4
- **[ ] F6.2 Shop Drawings Management**
- [ ] Create shop drawing list with revision tracking
- [ ] Implement shop drawing creation and revision system
- [ ] Create drawing comparison interface
- [ ] Add drawing approval status tracking
- [ ] Implement bulk drawing operations
- [ ] **Business Logic:** Proper revision control and approval workflows
- [ ] **Deliverable:** Complete shop drawing management system
- [ ] **Dependencies:** F6.1
- **[ ] F6.3 Drawing Revision System**
- [ ] Create revision history interface
- [ ] Implement revision comparison functionality
- [ ] Add revision notes and change tracking
- [ ] Create revision approval workflow
- [ ] Implement revision rollback capability
- [ ] **UX:** Clear visualization of changes between revisions
- [ ] **Deliverable:** Robust drawing revision control
- [ ] **Dependencies:** F6.2
- **[ ] F6.4 Drawing References**
- [ ] Create drawing reference management
- [ ] Implement cross-drawing references
- [ ] Add reference validation and integrity checks
- [ ] Create reference visualization
- [ ] Implement reference impact analysis
- [ ] **Business Logic:** Maintain reference integrity during changes
- [ ] **Deliverable:** Comprehensive drawing reference system
- [ ] **Dependencies:** F6.2, F6.3
### **Phase 6: Testing - Drawing System**
- **[ ] F6.T1 Drawing Management Test Suite**
- [ ] **Unit Tests:** Drawing CRUD operations, revision logic
- [ ] **Integration Tests:** Drawing approval workflows, reference management
- [ ] **E2E Tests:** Complete drawing lifecycle with revisions
---
### **Phase 7: RFA System (สัปดาห์ที่ 9-10)**
**Milestone:** ระบบขออนุมัติแบบสมบูรณ์พร้อม Dynamic Forms
### **Phase 7: Tasks**
- **[ ] F7.1 RFA List & Dashboard**
- [ ] Create RFA dashboard with status overview
- [ ] Implement advanced RFA filtering and search
- [ ] Create RFA calendar view for deadlines
- [ ] Add RFA statistics and reporting
- [ ] Implement RFA bulk operations
- [ ] **UX:** Comprehensive RFA overview and management
- [ ] **Deliverable:** Complete RFA dashboard and listing
- [ ] **Dependencies:** F4.1, F5.1
- **[ ] F7.2 RFA Creation with Dynamic Forms**
- [ ] Create RFA type-specific form generator
- [ ] Implement dynamic form fields based on RFA type:
- [ ] RFA_DWG: Shop drawing selection
- [ ] RFA_DOC: Document specifications
- [ ] RFA_MES: Method statement details
- [ ] RFA_MAT: Material specifications
- [ ] Add form validation with JSON schema
- [ ] Implement form data persistence and recovery
- [ ] **UX:** Intuitive form experience for complex RFA types
- [ ] Dynamic Form & Schema Validation: สร้าง Component Dynamic Form Generator ที่:
- [ ] Fetch Schema: ดึงโครงสร้าง JSON Schema ที่ถูกต้องตาม rfa_type จาก Backend (ตาราง json_schemas ที่สร้างใหม่) ก่อนการ Render Form.
- [ ] Client-side Validation: Implement AJV (Another JSON Schema Validator) หรือไลบรารีที่เทียบเท่า เพื่อทำ Client-side Validation บนข้อมูล JSON ก่อนส่ง Submit.
- [ ] Implement dynamic form fields based on RFA type: RFA_DWG, RFA_DOC, RFA_MES, RFA_MAT.
- [ ] Add form data persistence and recovery.
- [ ] **[New] Discipline & Sub-Type Integration:** Ensure RFA forms capture these fields correctly for numbering generation.
- [ ] **Deliverable:** Flexible RFA creation system
- [ ] **Dependencies:** F4.2, F6.2
- **[ ] F7.3 RFA Workflow Integration**
- [ ] Integrate RFA with unified workflow engine
- [ ] Create RFA-specific workflow steps and actions
- [ ] Implement RFA approval interface
- [ ] Add RFA workflow history and tracking
- [ ] Create RFA workflow templates
- [ ] **Business Logic:** Proper RFA approval sequencing and validation
- [ ] **Deliverable:** Seamless RFA workflow integration
- [ ] **Dependencies:** F5.1, F7.2
- **[ ] F7.4 RFA Approval Interface**
- [ ] Create RFA review and approval interface
- [ ] Implement side-by-side document comparison
- [ ] Add approval comments and attachments
- [ ] Create conditional approval workflows
- [ ] Implement approval delegation and escalation
- [ ] **UX:** Efficient approval process for technical reviews
- [ ] **Deliverable:** Comprehensive RFA approval system
- [ ] **Dependencies:** F7.1, F7.3
### **Phase 7: Testing - RFA System**
- **[ ] F7.T1 RFA Test Suite**
- [ ] **Unit Tests:** RFA form generation, validation logic
- [ ] **Integration Tests:** Complete RFA lifecycle, workflow integration
- [ ] **E2E Tests:** Multi-type RFA creation and approval workflows
---
### **Phase 8: Internal Workflows (สัปดาห์ที่ 11)**
**Milestone:** ระบบใบเวียนและการจัดการงานภายใน
### **Phase 8: Tasks**
- **[ ] F8.1 Circulation Management**
- [ ] Create circulation list and management interface
- [ ] Implement circulation creation from correspondence
- [ ] Create circulation template management
- [ ] Add circulation status tracking
- [ ] Implement circulation search and filtering
- [ ] **Business Logic:** Proper circulation-correspondence relationships
- [ ] **Deliverable:** Comprehensive circulation management
- [ ] **Dependencies:** F4.1, F5.2
- **[ ] F8.2 Task Assignment Interface**
- [ ] Create task assignment interface with user selection
- [ ] Implement task priority and deadline setting
- [ ] Add task dependency management
- [ ] Create task progress tracking
- [ ] Implement task reassignment and delegation
- [ ] **UX:** Intuitive task management and assignment
- [ ] **Deliverable:** Efficient task assignment system
- [ ] **Dependencies:** F8.1
- **[ ] F8.3 Internal Approval Flows**
- [ ] Create internal approval workflow interface
- [ ] Implement multi-level approval processes
- [ ] Add approval chain visualization
- [ ] Create approval delegation system
- [ ] Implement approval deadline management
- [ ] **Business Logic:** Proper approval hierarchy and escalation
- [ ] **Deliverable:** Robust internal approval system
- [ ] **Dependencies:** F8.1, F8.2
### **Phase 8: Testing - Internal Workflows**
- **[ ] F8.T1 Circulation Test Suite**
- [ ] **Unit Tests:** Circulation creation, task assignment logic
- [ ] **Integration Tests:** Complete circulation workflow, internal approvals
- [ ] **E2E Tests:** End-to-end circulation with task completion
---
### **Phase 9: Advanced Features (สัปดาห์ที่ 12)**
**Milestone:** ฟีเจอร์ขั้นสูงและการปรับปรุงประสบการณ์ผู้ใช้
### **Phase 9: Tasks**
- **[ ] F9.1 Advanced Search Interface**
- [ ] Create unified search interface across all document types
- [ ] Implement faceted search with multiple filters
- [ ] Add search result highlighting and relevance scoring
- [ ] Create saved search and search templates
- [ ] Implement search result export functionality
- [ ] **Performance:** Efficient search with large datasets
- [ ] **Deliverable:** Powerful cross-document search system
- [ ] **Dependencies:** F4.1, F7.1
- **[ ] F9.2 Notification System**
- [ ] Create notification center with real-time updates
- [ ] Implement notification preferences management
- [ ] Add notification grouping and digest views
- [ ] Create actionable notifications with quick actions
- [ ] Implement notification read/unread status
- [ ] **UX:** Non-intrusive but effective notification delivery
- [ ] **Deliverable:** Comprehensive notification management
- [ ] **Dependencies:** F1.3, F5.4
- **[ ] F9.3 Reporting & Analytics**
- [ ] Create reporting dashboard with customizable widgets
- [ ] Implement data visualization components (charts, graphs)
- [ ] Add report scheduling and export
- [ ] Create ad-hoc reporting interface
- [ ] Implement performance metrics tracking
- [ ] **Business Logic:** Accurate data aggregation and reporting
- [ ] **Deliverable:** Powerful reporting and analytics system
- [ ] **Dependencies:** F1.3, F7.1
- **[ ] F9.4 Mobile Optimization**
- [ ] Implement touch-optimized interactions
- [ ] Create mobile-specific navigation patterns
- [ ] Add offline capability for critical functions
- [ ] Optimize images and assets for mobile networks
- [ ] Implement mobile-specific performance optimizations
- [ ] **UX:** Seamless mobile experience comparable to desktop
- [ ] **Deliverable:** Fully optimized mobile application
- [ ] **Dependencies:** F1.4
### **Phase 9: Testing - Advanced Features**
- **[ ] F9.T1 Advanced Features Test Suite**
- [ ] **Unit Tests:** Search algorithms, notification logic
- [ ] **Integration Tests:** Cross-module search, real-time notifications
- [ ] **Performance Tests:** Search performance, mobile responsiveness
---
### **Phase 10: Testing & Polish (สัปดาห์ที่ 13-14)**
**Milestone:** แอปพลิเคชันที่ผ่านการทดสอบและปรับปรุงอย่างสมบูรณ์
### **Phase 10: Tasks**
- **[ ] F10.1 Comprehensive Testing**
- [ ] Idempotency Testing: เพิ่มการทดสอบเฉพาะสำหรับ Axios Interceptor เพื่อจำลองการส่ง Request POST/PUT/DELETE ที่มี Idempotency-Key ซ้ำไปยัง Mock API (MSW) เพื่อยืนยันว่า Client-side ไม่ส่ง Key ซ้ำในการทำงานปกติ และไม่เกิด Side Effect จากการ Replay Attack.
- [ ] Write unit tests for all components and utilities
- [ ] Create integration tests for critical user flows
- [ ] Implement E2E tests for complete workflows
- [ ] Perform cross-browser compatibility testing
- [ ] Conduct accessibility testing (WCAG 2.1 AA)
- [ ] **Quality:** 80%+ test coverage, all critical paths tested
- [ ] **Deliverable:** Fully tested application
- [ ] **Dependencies:** All previous phases
- **[ ] F10.2 Performance Optimization**
- [ ] Implement code splitting and lazy loading
- [ ] Optimize bundle size and asset delivery
- [ ] Add performance monitoring and metrics
- [ ] Implement caching strategies for static assets
- [ ] Optimize API call patterns and reduce over-fetching
- [ ] **Performance:** Core Web Vitals targets met
- [ ] **Deliverable:** High-performance application
- [ ] **Dependencies:** F10.1
- **[ ] F10.3 Security Hardening**
- [ ] Conduct security audit and penetration testing
- [ ] Implement Content Security Policy (CSP)
- [ ] Add security headers and protections
- [ ] Conduct dependency vulnerability scanning
- [ ] Implement secure coding practices review
- [ ] **Security:** No critical security vulnerabilities
- [ ] **Deliverable:** Security-hardened application
- [ ] **Dependencies:** F10.1
- **[ ] F10.4 Documentation**
- [ ] Create user documentation and guides
- [ ] Write technical documentation for developers
- [ ] Create API integration documentation
- [ ] Add inline code documentation
- [ ] Create deployment and maintenance guides
- [ ] **Quality:** Comprehensive and up-to-date documentation
- [ ] **Deliverable:** Complete documentation suite
- [ ] **Dependencies:** F10.1
### **Phase 10: Testing - Final Validation**
- **[ ] F10.T1 Final Test Suite**
- [ ] **Performance Tests:** Load testing, stress testing
- [ ] **Security Tests:** Final security audit, vulnerability assessment
- [ ] **User Acceptance Tests:** Real user testing, feedback incorporation
- [ ] **Compatibility Tests:** Cross-browser, cross-device testing
---
## 📊 **สรุป Timeline**
| Phase | ระยะเวลา | จำนวนงาน | Output หลัก |
| -------- | -------------- | ------------ | ------------------------------------ |
| Phase 0 | 1 สัปดาห์ | 4 | Foundation & Tooling Ready |
| Phase 1 | 1 สัปดาห์ | 4 | Core Application Structure |
| Phase 2 | 1 สัปดาห์ | 4 | User Management & Security |
| Phase 3 | 1 สัปดาห์ | 3 | Project Structure Management |
| Phase 4 | 2 สัปดาห์ | 4 | Correspondence System |
| Phase 5 | 1 สัปดาห์ | 4 | Workflow Management |
| Phase 6 | 1 สัปดาห์ | 4 | Drawing System |
| Phase 7 | 2 สัปดาห์ | 4 | RFA System (Dynamic Forms) |
| Phase 8 | 1 สัปดาห์ | 3 | Internal Workflows |
| Phase 9 | 1 สัปดาห์ | 4 | Advanced Features |
| Phase 10 | 2 สัปดาห์ | 4 | Testing & Polish (Idempotency Test) |
| **รวม** | **14 สัปดาห์** | **39 Tasks** | **Production-Ready Frontend v1.4.2** |
---
## 🎯 **Critical Success Factors**
1. **User Experience First:** ทุกฟีเจอร์ต้องออกแบบเพื่อประสบการณ์ผู้ใช้ที่ดี
2. **Responsive Design:** รองรับการใช้งานบนอุปกรณ์ทุกรูปแบบ
3. **Performance:** Core Web Vitals ต้องอยู่ในเกณฑ์ที่ดี
4. **Accessibility:** ต้องเป็นไปตามมาตรฐาน WCAG 2.1 AA
5. **Security:** ป้องกัน XSS, CSRF และความเสี่ยงด้านความปลอดภัยอื่นๆ
6. **Offline Support:** รองรับการทำงานแบบ Offline เบื้องต้น
7. **Real-time Updates:** การอัปเดตสถานะแบบ Real-time
8. **Testing Coverage:** ครอบคลุมการทดสอบทุก Critical Path
9. **Documentation:** เอกสารครบถ้วนสำหรับผู้ใช้และนักพัฒนา
---
## 📋 **Quality Assurance Checklist**
### **ก่อน Production Deployment**
- [ ] **Performance:** Core Web Vitals ผ่านเกณฑ์
- [ ] **Accessibility:** WCAG 2.1 AA compliant
- [ ] **Security:** Security audit ผ่าน
- [ ] **Testing:** Test coverage ≥ 80%
- [ ] **Browser Compatibility:** ทำงานได้บนเบราว์เซอร์หลัก
- [ ] **Mobile Responsive:** ใช้งานได้ดีบนมือถือ
- [ ] **Documentation:** เอกสารครบถ้วน
- [ ] **User Acceptance:** ได้รับการยอมรับจากผู้ใช้
---
## 🚀 **ขั้นตอนถัดไป**
1. **Approve แผนนี้** → ปรับแต่งตาม Feedback
2. **Coordinate กับ Backend Team** → Sync API Specifications
3. **เริ่มพัฒนา Phase 0** → Setup Foundation
4. **Regular Sync** → ประสานงานกับ Backend ทุกสัปดาห์
5. **User Testing** → ทดสอบกับผู้ใช้จริงระหว่างพัฒนา
6. **Deploy to Production** → Week 15 (พร้อม Backend)
## **Document Control:**
- **Document:** Frontend Development Plan v1.4.3
- **Version:** 1.4
- **Date:** 2025-11-26
- **Author:** NAP LCBP3-DMS & Gemini
- **Status:** FINAL-Rev.04
- **Classification:** Internal Technical Documentation
- **Approved By:** Nattanin
---
`End of Frontend Development Plan v1.4.4 (ฉบับปรับปรุง)`

2840
infrastructure/Markdown/4_Data_Dictionary_V1_4_3.md Normal file
View File

File diff suppressed because it is too large Load Diff

2923
infrastructure/Markdown/4_Data_Dictionary_V1_4_4.md Normal file
View File

File diff suppressed because it is too large Load Diff

192
infrastructure/Markdown/FullStackJS_Guidelines.md Normal file
View File

@@ -0,0 +1,192 @@
# FullStackJS Development Guidelines
## 🧠 General Philosophy
Unified best practices for **NestJS Backend**, **NextJS Frontend**, and **Bootstrap-based UI/UX** development in TypeScript environments.
Focus on **clarity**, **maintainability**, **consistency**, and **accessibility** across the entire stack.
---
## ⚙️ TypeScript General Guidelines
### Basic Principles
- Use **English** for all code and documentation.
- Explicitly type all variables, parameters, and return values.
- Avoid `any`; create custom types or interfaces.
- Use **JSDoc** for public classes and methods.
- Export only **one main symbol** per file.
- Avoid blank lines within functions.
### Naming Conventions
| Entity | Convention | Example |
|:--|:--|:--|
| Classes | PascalCase | `UserService` |
| Variables & Functions | camelCase | `getUserInfo` |
| Files & Folders | kebab-case | `user-service.ts` |
| Environment Variables | UPPERCASE | `DATABASE_URL` |
| Booleans | Verb + Noun | `isActive`, `canDelete`, `hasPermission` |
Use full words — no abbreviations — except for standard ones (`API`, `URL`, `req`, `res`, `err`, `ctx`).
---
## 🧩 Functions
- Write short, single-purpose functions (<20 lines).
- Use **early returns** to reduce nesting.
- Use **map**, **filter**, **reduce** instead of loops when suitable.
- Prefer **arrow functions** for short logic, **named functions** otherwise.
- Use **default parameters** over null checks.
- Group multiple parameters into a single object (RO-RO pattern).
- Return typed objects, not primitives.
- Maintain a single abstraction level per function.
---
## 🧱 Data Handling
- Encapsulate data in composite types.
- Use **immutability** with `readonly` and `as const`.
- Perform validations in classes or DTOs, not within business functions.
- Always validate data using typed DTOs.
---
## 🧰 Classes
- Follow **SOLID** principles.
- Prefer **composition over inheritance**.
- Define **interfaces** for contracts.
- Keep classes focused and small (<200 lines, <10 methods, <10 properties).
---
## 🚨 Error Handling
- Use exceptions for unexpected errors.
- Catch only to fix or add context; otherwise, use global error handlers.
- Always provide meaningful error messages.
---
## 🧪 Testing (General)
- Use the **Arrange–Act–Assert** pattern.
- Use descriptive test variable names (`inputData`, `expectedOutput`).
- Write **unit tests** for all public methods.
- Mock external dependencies.
- Add **acceptance tests** per module using Given–When–Then.
---
# 🏗️ Backend (NestJS)
### Principles
- **Modular architecture**:
- One module per domain.
- Controller → Service → Model structure.
- DTOs validated with **class-validator**.
- Use **MikroORM** or equivalent for persistence.
- Encapsulate reusable code in a **common module** (`@app/common`):
- Configs, decorators, DTOs, guards, interceptors, notifications, shared services, types, validators.
### Core Functionalities
- Global **filters** for exception handling.
- **Middlewares** for request handling.
- **Guards** for permissions and RBAC.
- **Interceptors** for response transformation and logging.
### Testing
- Use **Jest** for testing.
- Test each controller and service.
- Add `admin/test` endpoint as a smoke test.
---
# 🖥️ Frontend (NextJS / React)
### Developer Profile
Senior-level TypeScript + React/NextJS engineer.
Expert in **TailwindCSS**, **Shadcn/UI**, and **Radix** for UI development.
### Code Implementation Guidelines
- Use **early returns** for clarity.
- Always style with **TailwindCSS** classes.
- Prefer `class:` conditional syntax over ternary operators.
- Use **const arrow functions** for components and handlers.
- Event handlers start with `handle...` (e.g., `handleClick`, `handleSubmit`).
- Include accessibility attributes:
`tabIndex="0"`, `aria-label`, `onKeyDown`, etc.
- Ensure all code is **complete**, **tested**, and **DRY**.
- Always import required modules explicitly.
### UI/UX with React
- Use **semantic HTML**.
- Apply **responsive Tailwind** classes.
- Maintain visual hierarchy with typography and spacing.
- Use **Shadcn** components for consistent UI.
- Keep components small and focused.
---
# 🎨 UI/UX (Bootstrap Integration)
### Key Principles
- Use **Bootstrap 5+** for responsive design and consistent UI.
- Focus on **maintainability**, **readability**, and **accessibility**.
- Use clear and descriptive class names.
### Bootstrap Usage
- Structure layout with **container**, **row**, **col**.
- Use built-in **components** (buttons, modals, alerts, etc.) instead of custom CSS.
- Apply **utility classes** for quick styling (spacing, colors, text, etc.).
- Ensure **ARIA compliance** and semantic markup.
### Form Validation & Errors
- Use Bootstrap’s built-in validation states.
- Show errors with **alert components**.
- Include labels, placeholders, and feedback messages.
### Dependencies
- Bootstrap (latest CSS + JS)
- Optionally jQuery (for legacy interactive components)
### Bootstrap-Specific Guidelines
- Customize Bootstrap via **Sass variables** and **mixins**.
- Use responsive visibility utilities.
- Avoid overriding Bootstrap; extend it.
- Follow official documentation for examples.
### Performance Optimization
- Include only necessary Bootstrap modules.
- Use CDN for assets and caching.
- Optimize images and assets for mobile.
### Key Conventions
1. Follow Bootstrap’s naming and structure.
2. Prioritize **responsiveness** and **accessibility**.
3. Keep the file structure organized and modular.
---
# 🔗 Full Stack Integration Guidelines
| Aspect | Backend (NestJS) | Frontend (NextJS) | UI Layer (Bootstrap/Tailwind) |
|:--|:--|:--|:--|
| API | REST / GraphQL Controllers | API hooks via fetch/axios | Components consuming data |
| Validation | `class-validator` DTOs | `zod` / form-level validation | Bootstrap validation feedback |
| Auth | Guards, JWT | NextAuth / cookies | Auth UI states |
| Errors | Global filters | Toasts / modals | Alerts / feedback |
| Testing | Jest (unit/e2e) | Vitest / Playwright | Visual regression |
| Styles | Scoped modules | Tailwind / Shadcn | Bootstrap utilities |
| Accessibility | Guards + filters | ARIA attributes | Semantic HTML |
---
# ✅ Final Notes
- Use a **shared types package** (`@types/shared`) for consistent interfaces.
- Document your modules and APIs.
- Run lint, type-check, and tests before commit.
- Use **Prettier + ESLint** for consistent formatting.
- Prefer **clarity over cleverness** — readable code wins.

364
infrastructure/Markdown/FullStackJS_Guidelines01.md Normal file
View File

@@ -0,0 +1,364 @@
# FullStackJS Development Guidelines
## 🧠 General Philosophy
Unified best practices for **NestJS Backend**, **NextJS Frontend**, and **Bootstrap-based UI/UX** development in TypeScript environments.
Focus on **clarity**, **maintainability**, **consistency**, and **accessibility** across the entire stack.
---
## ⚙️ TypeScript General Guidelines
### Basic Principles
- Use **English** for all code and documentation.
- Explicitly type all variables, parameters, and return values.
- Avoid `any`; create custom types or interfaces.
- Use **JSDoc** for public classes and methods.
- Export only **one main symbol** per file.
- Avoid blank lines within functions.
### Naming Conventions
| Entity | Convention | Example |
|:--|:--|:--|
| Classes | PascalCase | `UserService` |
| Variables & Functions | camelCase | `getUserInfo` |
| Files & Folders | kebab-case | `user-service.ts` |
| Environment Variables | UPPERCASE | `DATABASE_URL` |
| Booleans | Verb + Noun | `isActive`, `canDelete`, `hasPermission` |
Use full words — no abbreviations — except for standard ones (`API`, `URL`, `req`, `res`, `err`, `ctx`).
---
## 🧩 Functions
- Write short, single-purpose functions (<20 lines).
- Use **early returns** to reduce nesting.
- Use **map**, **filter**, **reduce** instead of loops when suitable.
- Prefer **arrow functions** for short logic, **named functions** otherwise.
- Use **default parameters** over null checks.
- Group multiple parameters into a single object (RO-RO pattern).
- Return typed objects, not primitives.
- Maintain a single abstraction level per function.
---
## 🧱 Data Handling
- Encapsulate data in composite types.
- Use **immutability** with `readonly` and `as const`.
- Perform validations in classes or DTOs, not within business functions.
- Always validate data using typed DTOs.
---
## 🧰 Classes
- Follow **SOLID** principles.
- Prefer **composition over inheritance**.
- Define **interfaces** for contracts.
- Keep classes focused and small (<200 lines, <10 methods, <10 properties).
---
## 🚨 Error Handling
- Use exceptions for unexpected errors.
- Catch only to fix or add context; otherwise, use global error handlers.
- Always provide meaningful error messages.
---
## 🧪 Testing (General)
- Use the **Arrange–Act–Assert** pattern.
- Use descriptive test variable names (`inputData`, `expectedOutput`).
- Write **unit tests** for all public methods.
- Mock external dependencies.
- Add **acceptance tests** per module using Given–When–Then.
---
# 🏗️ Backend (NestJS)
### Principles
- **Modular architecture**:
- One module per domain.
- Controller → Service → Model structure.
- DTOs validated with **class-validator**.
- Use **MikroORM** or equivalent for persistence.
- Encapsulate reusable code in a **common module** (`@app/common`):
- Configs, decorators, DTOs, guards, interceptors, notifications, shared services, types, validators.
### Core Functionalities
- Global **filters** for exception handling.
- **Middlewares** for request handling.
- **Guards** for permissions and RBAC.
- **Interceptors** for response transformation and logging.
### Testing
- Use **Jest** for testing.
- Test each controller and service.
- Add `admin/test` endpoint as a smoke test.
---
# 🖥️ Frontend (NextJS / React)
### Developer Profile
Senior-level TypeScript + React/NextJS engineer.
Expert in **TailwindCSS**, **Shadcn/UI**, and **Radix** for UI development.
### Code Implementation Guidelines
- Use **early returns** for clarity.
- Always style with **TailwindCSS** classes.
- Prefer `class:` conditional syntax over ternary operators.
- Use **const arrow functions** for components and handlers.
- Event handlers start with `handle...` (e.g., `handleClick`, `handleSubmit`).
- Include accessibility attributes:
`tabIndex="0"`, `aria-label`, `onKeyDown`, etc.
- Ensure all code is **complete**, **tested**, and **DRY**.
- Always import required modules explicitly.
### UI/UX with React
- Use **semantic HTML**.
- Apply **responsive Tailwind** classes.
- Maintain visual hierarchy with typography and spacing.
- Use **Shadcn** components for consistent UI.
- Keep components small and focused.
---
# 🎨 UI/UX (Bootstrap Integration)
### Key Principles
- Use **Bootstrap 5+** for responsive design and consistent UI.
- Focus on **maintainability**, **readability**, and **accessibility**.
- Use clear and descriptive class names.
### Bootstrap Usage
- Structure layout with **container**, **row**, **col**.
- Use built-in **components** (buttons, modals, alerts, etc.) instead of custom CSS.
- Apply **utility classes** for quick styling (spacing, colors, text, etc.).
- Ensure **ARIA compliance** and semantic markup.
### Form Validation & Errors
- Use Bootstrap’s built-in validation states.
- Show errors with **alert components**.
- Include labels, placeholders, and feedback messages.
### Dependencies
- Bootstrap (latest CSS + JS)
- Optionally jQuery (for legacy interactive components)
### Bootstrap-Specific Guidelines
- Customize Bootstrap via **Sass variables** and **mixins**.
- Use responsive visibility utilities.
- Avoid overriding Bootstrap; extend it.
- Follow official documentation for examples.
### Performance Optimization
- Include only necessary Bootstrap modules.
- Use CDN for assets and caching.
- Optimize images and assets for mobile.
### Key Conventions
1. Follow Bootstrap’s naming and structure.
2. Prioritize **responsiveness** and **accessibility**.
3. Keep the file structure organized and modular.
---
# 🔗 Full Stack Integration Guidelines
| Aspect | Backend (NestJS) | Frontend (NextJS) | UI Layer (Bootstrap/Tailwind) |
|:--|:--|:--|:--|
| API | REST / GraphQL Controllers | API hooks via fetch/axios | Components consuming data |
| Validation | `class-validator` DTOs | `zod` / form-level validation | Bootstrap validation feedback |
| Auth | Guards, JWT | NextAuth / cookies | Auth UI states |
| Errors | Global filters | Toasts / modals | Alerts / feedback |
| Testing | Jest (unit/e2e) | Vitest / Playwright | Visual regression |
| Styles | Scoped modules | Tailwind / Shadcn | Bootstrap utilities |
| Accessibility | Guards + filters | ARIA attributes | Semantic HTML |
---
# ✅ Final Notes
- Use a **shared types package** (`@types/shared`) for consistent interfaces.
- Document your modules and APIs.
- Run lint, type-check, and tests before commit.
- Use **Prettier + ESLint** for consistent formatting.
- Prefer **clarity over cleverness** — readable code wins.
---
# 🗂️ DMS-Specific Conventions (Document Management System)
This section extends the general FullStackJS guidelines for projects similar to **np‑dms.work**, focusing on document approval workflows (RFA, Drawing, Contract, Revision, Transmittal, Report).
## 🧱 Backend Domain Modules
Use modular domain structure per document type:
```
src/
├─ modules/
│ ├─ rfas/
│ ├─ drawings/
│ ├─ contracts/
│ ├─ transmittals/
│ ├─ audit-log/
│ ├─ users/
│ └─ common/
```
### Naming Convention
| Entity | Example |
|:--|:--|
| Table | `rfa_revisions`, `drawing_contracts` |
| DTO | `CreateRfaDto`, `UpdateContractDto` |
| Controller | `rfas.controller.ts` |
| Service | `rfas.service.ts` |
---
## 🧩 RBAC & Permission Control
Use decorators to enforce access rights:
```ts
@RequirePermission('rfa.update')
@Put(':id')
updateRFA(@Param('id') id: string) {
return this.rfaService.update(id);
}
```
### Roles
- **Admin**: Full access to all modules.
- **Editor**: Modify data within assigned modules.
- **Viewer**: Read‑only access.
### Permissions
- `rfa.create`, `rfa.update`, `rfa.delete`, `rfa.view`
- `drawing.upload`, `drawing.map`, `drawing.view`
- `contract.assign`, `contract.view`
Seed mapping between roles and permissions via seeder scripts.
---
## 🧾 AuditLog Standard
Log all CRUD and mapping operations:
| Field | Description |
|:--|:--|
| `actor_id` | user performing the action |
| `module_name` | e.g. `rfa`, `drawing` |
| `action` | `create`, `update`, `delete`, `map` |
| `target_id` | primary id of the record |
| `timestamp` | UTC timestamp |
| `description` | contextual note |
Example implementation:
```ts
await this.auditLogService.log({
actorId: user.id,
moduleName: 'rfa',
action: 'update',
targetId: rfa.id,
description: `Updated revision ${rev}`,
});
```
---
## 📂 File Handling
### File Upload Standard
- Upload path: `/storage/{year}/{month}/`
- File naming: `{drawing_code}_{revision}_{timestamp}.pdf`
- Allowed types: `pdf, dwg, docx, xlsx, zip`
- Max size: **50 MB**
- Store outside webroot.
- Serve via secure endpoint `/files/:id/download`.
### Access Control
Each file download must verify user permission (`hasPermission('drawing.view')`).
---
## 📊 Reporting & Exports
| Report | Description |
|:--|:--|
| **Report A** | RFA → Drawings → All Drawing Revisions |
| **Report B** | RFA Revision Timeline vs Drawing Revision |
| **Dashboard KPI** | RFAs, Drawings, Revisions, Transmittals summary |
### Export Rules
- Export formats: CSV, Excel, PDF.
- Provide print view.
- Include source entity link (e.g., `/rfas/:id`).
---
## 🧮 Frontend: DataTable & Form Patterns
### DataTable (Server‑Side)
- Endpoint: `/api/{module}?page=1&pageSize=20`
- Must support: pagination, sorting, search, filters.
- Always display latest revision inline (for RFA/Drawing).
### Form Standards
- Dependent dropdowns:
- Contract → Subcategory
- RFA → Related Drawing
- File upload: preview + validation.
- Submit via API with toast feedback.
---
## 🧭 Dashboard & Activity Feed
### Dashboard Cards
- Show latest RFA, Drawing, Transmittal, KPI summary.
- Include quick links to modules.
### Activity Feed
- Display recent AuditLog actions (10 latest).
```ts
// Example response
[
{ user: 'admin', action: 'Updated RFA 023-Rev02', time: '2025‑11‑04T09:30Z' }
]
```
---
## ✅ Integration Summary
| Aspect | Backend | Frontend | Description |
|:--|:--|:--|
| **File Handling** | Secure storage, token check | Upload/Preview UI | Consistent standard path |
| **RBAC** | `RequirePermission` guard | Hide/disable UI actions | Unified permission logic |
| **AuditLog** | Persist actions | Show in dashboard | Traceable user activity |
| **Reports** | Aggregation queries | Export + Print | Consistent data pipeline |
| **DataTables** | Server‑side paging | Filter/Search UI | Scalable dataset management |
---
## 🧩 Recommended Enhancements
- ✅ Add `deleted_at` for soft delete + restore.
- ✅ Fulltext search + date filters.
- ✅ Background job for RFA deadline reminders.
- ✅ Optimize DB with indexes on `rfa_id`, `drawing_id`, `contract_id`.
- ✅ Periodic cleanup for unused file uploads.
---

588
infrastructure/Markdown/LCBP3-DMS Backend Documentation (ฉบับสมบูรณ์) Normal file
View File

File diff suppressed because one or more lines are too long

584
infrastructure/Markdown/LCBP3-DMS Frontend Documentation (ฉบับสมบูรณ์) Normal file
View File

File diff suppressed because one or more lines are too long

1196
infrastructure/Markdown/LCBP3-DMS Requirements Specification (v2.0) Normal file
View File

File diff suppressed because one or more lines are too long

136
infrastructure/Markdown/LCBP3-DMS Requirements Specification.bak Normal file
View File

@@ -0,0 +1,136 @@
# LCBP3-DMS: Requirements Specification
เอกสารนี้สรุปข้อกำหนดของโปรเจ็ค LCBP3-DMS (Document Management System), สถาปัตยกรรมทางเทคนิค, และรายละเอียดการนำไปใช้ (Implementation) สำหรับระบบบริหารจัดการเอกสารโครงการ (Document Management System)
## 1. สถาปัตยกรรมและเทคโนโลยี (System Architecture & Technology Stack)
ระบบใช้สถาปัตยกรรมแบบ Headless/API-First ที่ทันสมัย ทำงานทั้งหมดบน QNAP Server ผ่าน Container Station เพื่อความสะดวกในการจัดการและบำรุงรักษา
- 1.1 Infrastructure & Environment:
Server: QNAP (Model: TS-473A, RAM: 32GB, CPU: AMD Ryzen V1500B)
Containerization: Container Station (Docker & Docker Compose) ใช้ UI ของ Container Station เป็นหลัก ในการ configuration, debug
Development Environment: VS Code on Windows 11
Domain: np-dms.work, www.np-dms.work (มี Fixed IP)
Docker Network: ทุก Service จะเชื่อมต่อผ่านเครือข่ายกลางชื่อ lcbp3 เพื่อให้สามารถสื่อสารกันได้
Data Storage: /share/dms-data บน QNAP
ข้อจำกัด: ไม่สามารถใช้ .env ในการกำหนดตัวแปรภายนอกได้ ต้องกำหนดใน docker-compose.yml เท่านั้น
- 1.2 Code Hosting:
Service: Gitea (Self-hosted on QNAP)
Service name: gitea
Domain: git.np-dms.work
หน้าที่: เป็นศูนย์กลางในการเก็บและจัดการเวอร์ชันของโค้ด (Source Code) สำหรับทุกส่วน
- 1.3 Backend / Data Platform:
Service: NestJS
Service name: backend
Domain: backend.np-dms.work
Framework: NestJS (Node.js, TypeScript, ESM)
หน้าที่: จัดการโครงสร้างข้อมูล (Data Models), สร้าง API, จัดการสิทธิ์ผู้ใช้ (Roles & Permissions), และสร้าง Workflow ทั้งหมดของระบบ
- 1.4 Database:
Service: mariadb:10.11
Service name: mariadb
Domain: db.np-dms.work
หน้าที่: ฐานข้อมูลหลักสำหรับเก็บข้อมูลทั้งหมด
Tooling: DBeaver (Community Edition), phpmyadmin สำหรับการออกแบบและจัดการฐานข้อมูล
- 1.5 Database management:
Service: phpmyadmin:5-apache
Service name: pma
Domain: pma.np-dms.work
หน้าที่: จัดการฐานข้อมูล mariadb ผ่าน Web UI
- 1.6 Frontend:
Service: next.js
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
- 1.7 Workflow automation:
Service: n8nio/n8n:latest
Service name: n8n
Domain: n8n.np-dms.work
หน้าที่: จัดการ workflow ระหว่าง Backend และ Line
- 1.8 Reverse Proxy:
Service: Nginx Proxy Manager (nginx-proxy-manage: latest)
Service name: npm
Domain: npm.np-dms.work
หน้าที่: เป็นด่านหน้าในการรับ-ส่งข้อมูล จัดการโดเมนทั้งหมด, ทำหน้าที่เป็น Proxy ชี้ไปยัง Service ที่ถูกต้อง, และจัดการ SSL Certificate (HTTPS) ให้อัตโนมัติ
## 2. ข้อกำหนดด้านฟังก์ชันการทำงาน (Functional Requirements)
- 2.1. การจัดการโครงสร้างโครงการและองค์กร
- 2.1.1 โครงการ (Projects): ระบบต้องสามารถจัดการเอกสารภายในหลายโครงการได้ (ปัจจุบันมี 4 โครงการ และจะเพิ่มขึ้นในอนาคต)
- 2.1.2 สัญญา (Contracts): ในแต่ละโครงการ มีได้หลายสัญญา หรืออย่างน้อย 1 สัญญา
- 2.1.3 องค์กร (Organizations):
- มีหลายองค์กรในโครงการ บางองค์กรเช่น Owner, Designer และ Consultant สามารถอยู่ในหลายโครงการและหลายสัญญาได้
- Contractor จะถือ 1 สัญญา และอยู่ใน 1 โครงการเท่านั้น
- 2.2. การจัดการเอกสาร (Correspondence Management)
- 2.2.1 ประเภทเอกสาร: ระบบต้องรองรับเอกสารหลายประเภท (Types) เช่น จดหมาย (Letter), อีเมล์ (Email), Request for Information (RFI), และสามารถเพิ่มประเภทใหม่ได้ในภายหลัง
- 2.2.2 การสร้างเอกสาร (Correspondence):
- ผู้ใช้ที่มีสิทธิ์ (เช่น Document Control) สามารถสร้างเอกสารรอไว้ในสถานะ "ฉบับร่าง" (Draft) ได้ ซึ่งผู้ใช้งานต่างองค์กรจะมองไม่เห็น
- เมื่อกด "Submitted" แล้ว การแก้ไข, ถอนเอกสารกลับไปสถานะ Draft, หรือยกเลิก (Cancel) จะต้องทำโดยผู้ใช้ระดับ Admin ขึ้นไป พร้อมระบุเหตุผล
- 2.2.3 การอ้างอิงและจัดกลุ่ม:
- เอกสารสามารถอ้างถึง (Reference) เอกสารฉบับก่อนหน้าได้หลายฉบับ
- สามารถกำหนด Tag ได้หลาย Tag เพื่อจัดกลุ่มและใช้ในการค้นหาขั้นสูง
- 2.2.4 ประวัติการแก้ไข (Revisions): เอกสารสามารถมีได้หลาย Revision โดยระบบจะเก็บประวัติการแก้ไขทั้งหมด
- 2.2.5 การจัดเก็บ: เอกสารและไฟล์แนบจะถูกจัดเก็บในโฟลเดอร์บน Server (/share/dms-data/) โดยมีการอ้างอิงข้อมูล (Metadata) ในฐานข้อมูล และสามารถจัดเรียงตามวันที่ออกเอกสาร (Issue Date) ได้
- 2.3. การจัดการเอกสารนำส่ง (Transmittals)
- 2.3.1 วัตถุประสงค์: เอกสารนำส่ง ใช้สำหรับ นำส่ง Technical Documents (RFAS) หลายฉบับ ไปยังองค์กรอื่น
- 2.3.2 การอ้างอิง: เอกสารนำส่ง เป็นส่วนหนึ่งใน Correspondence และสามารถมี Technical Documents (RFAS) หลายฉบับ
- 2.4 ใบเวียนเอกสารภายใน (Internal Circulation Sheet)
- 2.4.1 วัตถุประสงค์: การสื่อสาร เอกสาร (Correspondence) ทุกฉบับ จะมีใบเวียนเอกสารเพื่อควบคุมและมอบหมายงานภายในองค์กร (สามารถดูและแก้ไขได้เฉพาะคนในองค์กร)
- 2.4.2 การระบุผู้รับผิดชอบ:
- ผู้รับผิดชอบหลัก (Main): มีได้หลายคน
- ผู้ร่วมปฏิบัติงาน (Action): มีได้หลายคน
- ผู้ที่ต้องรับทราบ (Information): มีได้หลายคน
- 2.4.3 การติดตามงาน:
- สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบประเภท Main และ Action ได้
- มีระบบแจ้งเตือนเมื่อมี Circulation ใหม่ และแจ้งเตือนล่วงหน้าก่อนถึงวันแล้วเสร็จ
- สามารถปิด Circulation ได้เมื่อดำเนินการตอบกลับไปยังองค์กรผู้ส่ง (Originator) แล้ว
- 2.5. การจัดการเอกสารทางเทคนิค (Technical Documents & Workflow)
- 2.5.1 ประเภท: Technical Documents (RFAS) เป็นชนิดหนึ่งของ Correspondence ที่มีลักษณะเฉพาะที่ต้องได้รับการอนุมัติ มีประเภทดังนี้:
- Request for Drawing Approval (RFA_DWG)
- Request for Document Approval (RFA_DOC)
- Request for Method statement Approval (RFA_MES)
- Request for Material Approval (RFA_MAT)
- 2.5.2 Workflow การอนุมัติ: ต้องรองรับกระบวนการอนุมัติที่ซับซ้อนและเป็นลำดับ เช่น ส่งจาก Originator -> Org1 -> Org2 -> Org3 แล้วส่งผลกลับตามลำดับเดิม
- 2.5.3 การจัดการ Drawing (RFA_DWG):
- เอกสาร RFA_DWG จะประกอบไปด้วย Shop Drawing (shop_drawings) หลายแผ่น ซึ่งแต่ละแผ่นมี Revision ของตัวเอง
- Shop Drawing แต่ละ Revision สามารถอ้างอิงถึง Contract Drawing (Ccontract_drawings) หลายแผ่น หรือไม่อ้างถึงก็ได้
- ระบบต้องมีส่วนสำหรับจัดการข้อมูล Master Data ของทั้ง Shop Drawing และ Contract Drawing แยกจากกัน
## 3. ข้อกำหนดด้านสิทธิ์และการเข้าถึง (Access Control Requirements)
- 3.1 ภาพรวม: ผู้ใช้และองค์กรสามารถดูและแก้ไขเอกสารได้ตามสิทธิ์ที่ได้รับ โดยระบบสิทธิ์จะเป็นแบบ Role-Based Access Control (RBAC)
- 3.2 ระดับของสิทธิ์:
- Global Roles: สิทธิ์ในภาพรวมของระบบ
- Project-Specific Roles: สิทธิ์ที่ถูกกำหนดให้ผู้ใช้สำหรับโครงการนั้นๆ โดยเฉพาะ (เช่น เป็น Editor ในโครงการ A แต่เป็น Viewer ในโครงการ B)
- 3.3 บทบาท (Roles) พื้นฐาน:
- Superadmin: ไม่มีข้อจำกัดใดๆ สามารถจัดการได้ทุกอย่างข้ามองค์กร
- Admin: มีสิทธิ์เต็มที่ แต่จำกัดเฉพาะในองค์กรที่ตัวเองสังกัด สามารถจัดการผู้ใช้ในองค์กรได้
- Document Control / Editor: สามารถ เพิ่ม/แก้ไข เอกสาร เฉพาะในองค์กรที่ตัวเองสังกัด ไม่สามารถจัดการผู้ใช้ได้
- สามารถสร้าง Role ใหม่และกำหนดสิทธิ์ (Permissions) เพิ่มเติมได้ในภายหลังผ่านหน้า Admin Panel
- 3.4 การบังคับใช้สิทธิ์: สิทธิ์ขององค์กรจะครอบคลุมสิทธิ์ของผู้ใช้ และการเข้าถึงข้อมูลที่เกี่ยวข้องกับโครงการ (เช่น การแก้ไขเอกสาร) จะถูกตรวจสอบเทียบกับสิทธิ์ที่ผู้ใช้มีในโครงการนั้นๆ โดยเฉพาะ
## 4. ข้อกำหนดด้านผู้ใช้งาน (User Interface & Experience)
- 4.1 Layout หลัก: หน้าเว็บใช้รูปแบบ App Shell ที่ประกอบด้วย:
- Navbar (ส่วนบน): แสดงชื่อระบบ, เมนูผู้ใช้ (Profile), เมนูสำหรับ Admin/Superadmin (จัดการผู้ใช้, จัดการสิทธิ์), และปุ่ม Login/Logout
- Sidebar (ด้านข้าง): เป็นเมนูหลักสำหรับเข้าถึงส่วนที่เกี่ยวกับเอกสารทั้งหมด เช่น Dashboard, Correspondences, RFA, Drawings
- Main Content Area: พื้นที่สำหรับแสดงเนื้อหาหลักของหน้าที่เลือก
- 4.2 หน้า Landing Page: เป็นหน้าแรกที่แสดงข้อมูลบางส่วนของโครงการสำหรับผู้ใช้ที่ยังไม่ได้ล็อกอิน
- 4.3 หน้า Dashboard: เป็นหน้าแรกหลังจากล็อกอิน ประกอบด้วย:
- การ์ดสรุปภาพรวม (KPI Cards): แสดงข้อมูลสรุปที่สำคัญขององค์กร เช่น จำนวนเอกสาร, งานที่เกินกำหนด
- ตาราง "งานของฉัน" (My Tasks Table): แสดงรายการงานทั้งหมดจาก Circulation ที่ผู้ใช้ต้องดำเนินการ
- 4.4 การติดตามสถานะ: องค์กรสามารถติดตามสถานะเอกสารทั้งของตนเอง (Originator) และสถานะเอกสารที่ส่งมาถึงตนเอง (Recipient)
- 4.5 การจัดการข้อมูลส่วนตัว (Profile Page): ผู้ใช้สามารถจัดการข้อมูลส่วนตัวและเปลี่ยนรหัสผ่านของตนเองได้
- 4.6 การจัดการเอกสารทางเทคนิค (Technical Documents & Workflow): ผู้ใช้สามารถดู Technical Document ในรูปแบบ Workflow ทั้งหมดได้ในหน้าเดียว, ขั้นตอนที่ยังไม่ถึงหรือผ่านไปแล้วจะเป็นรูปแบบ diable, สามารถดำเนินการได้เฉพาะในขั้นตอนที่ได้รับมอบหมายงาน (active) เช่น ตรวจสอบแล้ว เพื่อไปยังขั้นตอนต่อไป, สิทธิ์ admin ขึ้นไป สามรถกด ไปยังขั้นตอนต่อไป ได้ทุกขั้นตอน, การย้อนกลับ ไปขั้นตอนก่อนหน้า สามารถทำได้โดย สิทธิ์ admin ขึ้นไป
## 5. ข้อกำหนดที่ไม่ใช่ฟังก์ชันการทำงาน (Non-Functional Requirements)
- 5.1 การบันทึกการกระทำ (Audit Log): ทุกการกระทำที่สำคัญของผู้ใช้ (สร้าง, แก้ไข, ลบ, ส่ง) จะถูกบันทึกไว้ใน audit_logs เพื่อการตรวจสอบย้อนหลัง
- 5.2 การค้นหา (Search): ระบบต้องมีฟังก์ชันการค้นหาขั้นสูง ที่สามารถค้นหาเอกสารจากหลายเงื่อนไขพร้อมกันได้ เช่น ค้นหาจากชื่อเรื่อง, ประเภท, วันที่, และ Tag
- 5.3 การทำรายงาน (Reporting): สามารถจัดทำรายงานสรุปแยกประเภทของ Correspondence ประจำวัน, สัปดาห์, เดือน, และปีได้
- 5.4 ประสิทธิภาพ (Performance): มีการใช้ Caching กับข้อมูลที่เรียกใช้บ่อย และใช้ Pagination ในตารางข้อมูลเพื่อจัดการข้อมูลจำนวนมาก
- 5.5 ความปลอดภัย (Security):
- มีระบบ Rate Limiting เพื่อป้องกันการโจมตีแบบ Brute-force
- การจัดการ Secret (เช่น รหัสผ่าน DB, JWT Secret) จะต้องทำผ่าน Environment Variable ของ Docker เพื่อความปลอดภัยสูงสุด

197
infrastructure/Markdown/LCBP3-DMS V1_1_0_application _requirements.md Normal file
View File

@@ -0,0 +1,197 @@
# 📝 Documents Management Sytem Version 1.1.0: Application Requirements Specification
## 📌 1. วัตถุประสงค์
สร้างเว็บแอปพลิเคชั่นสำหรับระบบบริหารจัดการเอกสารโครงการ (Document Management System) ที่สามารถจัดการและควบคุม การสื่อสารด้วยเอกสารที่ซับซ้อน อย่างมีประสิทธิภาพ
* มีฟังก์ชันหลักในการอัปโหลด จัดเก็บ ค้นหา แชร์ และควบคุมสิทธิ์การเข้าถึงเอกสาร
* ช่วยลดการใช้เอกสารกระดาษ เพิ่มความปลอดภัยในการจัดเก็บข้อมูล
* เพิ่มความสะดวกในการทำงานร่วมกันระหว่างองกรณ์
## 🛠️ 2. สถาปัตยกรรมและเทคโนโลยี (System Architecture & Technology Stack)
ใช้สถาปัตยกรรมแบบ Headless/API-First ที่ทันสมัย ทำงานทั้งหมดบน QNAP Server ผ่าน Container Station เพื่อความสะดวกในการจัดการและบำรุงรักษา, Domain: np-dms.work, มี fix ip, รัน docker command ใน application ของ Container Station ได้โดยตรง, ประกอบด้วย
* 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 on Windows 11
- Domain: np-dms.work, www.np-dms.work
- ip: 159.192.126.103
- Docker Network: ทุก Service จะเชื่อมต่อผ่านเครือข่ายกลางชื่อ lcbp3 เพื่อให้สามารถสื่อสารกันได้
- Data Storage: /share/dms-data บน QNAP
- ข้อจำกัด: ไม่สามารถใช้ .env ในการกำหนดตัวแปรภายนอกได้ ต้องกำหนดใน docker-compose.yml เท่านั้น
* 2.2. Code Hosting:
- Application name: git
- Service: Gitea (Self-hosted on QNAP)
- Service name: gitea
- Domain: git.np-dms.work
- หน้าที่: เป็นศูนย์กลางในการเก็บและจัดการเวอร์ชันของโค้ด (Source Code) สำหรับทุกส่วน
* 2.3. Backend / Data Platform:
- Application name: lcbp3-backend
- Service: NestJS
- Service name: backend
- Domain: backend.np-dms.work
- Framework: NestJS (Node.js, TypeScript, ESM)
- หน้าที่: จัดการโครงสร้างข้อมูล (Data Models), สร้าง API, จัดการสิทธิ์ผู้ใช้ (Roles & Permissions), และสร้าง Workflow ทั้งหมดของระบบ
* 2.4. Database:
- Application name: lcbp3-db
- Service: mariadb:10.11
- Service name: mariadb
- Domain: db.np-dms.work
- หน้าที่: ฐานข้อมูลหลักสำหรับเก็บข้อมูลทั้งหมด
- Tooling: DBeaver (Community Edition), phpmyadmin สำหรับการออกแบบและจัดการฐานข้อมูล
* 2.5. Database management:
- Application name: lcbp3-db
- Service: phpmyadmin:5-apache
- Service name: pma
- Domain: pma.np-dms.work
- หน้าที่: จัดการฐานข้อมูล mariadb ผ่าน Web UI
* 2.6. Frontend:
- Application name: lcbp3-frontend
- Service: next.js
- 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
* 2.7. Workflow automation:
- Application name: lcbp3-n8n
- Service: n8nio/n8n:latest
- Service name: n8n
- Domain: n8n.np-dms.work
- หน้าที่: จัดการ workflow ระหว่าง Backend และ Line
* 2.8. Reverse Proxy:
- 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) ให้อัตโนมัติ
## 📦 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)
- 3.2.2. ประเภทเอกสาร: ระบบต้องรองรับเอกสารรูปแบบ ไฟล์ PDF หลายประเภท (Types) เช่น จดหมาย (Letter), อีเมล์ (Email), Request for Information (RFI), และสามารถเพิ่มประเภทใหม่ได้ในภายหลัง
- 3.2.3. การสร้างเอกสาร (Correspondence):
- ผู้ใช้ที่มีสิทธิ์ (เช่น Document Control) สามารถสร้างเอกสารรอไว้ในสถานะ ฉบับร่าง" (Draft) ได้ ซึ่งผู้ใช้งานต่างองค์กรจะมองไม่เห็น
- เมื่อกด "Submitted" แล้ว การแก้ไข, ถอนเอกสารกลับไปสถานะ Draft, หรือยกเลิก (Cancel) จะต้องทำโดยผู้ใช้ระดับ Admin ขึ้นไป พร้อมระบุเหตุผล
- 3.2.4. การอ้างอิงและจัดกลุ่ม:
- เอกสารสามารถอ้างถึง (Reference) เอกสารฉบับก่อนหน้าได้หลายฉบับ
- สามารถกำหนด Tag ได้หลาย Tag เพื่อจัดกลุ่มและใช้ในการค้นหาขั้นสูง
- 3.2.5. การจัดการ: มีการจัดการอย่างน้อยดังนี้
0 - สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบของ องกรณ์ ที่อเป็นผู้รับ ได้
- มีระบบแจ้งเตือน ให้ผู้รับผิดชอบขององกรณ์ที่เป็น ผู้รับ/ผู้ส่ง ทราบ เมื่อมีเอกสารใหม่ หรือมีการเปลี่ยนสถานะ
* 3.3. การจัดกาแบบคู่สัญญา (Contract Drawing)
- 3.3.1. วัตถุประสงค์: แบบคู่สัญญา (Contract Drawing) ใช้เพื่ออ้างอิงและใช้ในการตรวจสอบ
- 3.3.2. ประเภทเอกสาร: ไฟล์ PDF
- 3.3.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
- 3.3.4. การอ้างอิงและจัดกลุ่ม: ใช้สำหรับอ้างอิง ใน Shop Drawings, มีการจัดหมวดหมู่ของ Contract Drawing
* 3.4. การจัดกาแบบก่อสร้าง (Shop Drawing)
- 3.4.1. วัตถุประสงค์: แบบก่อสร้าง (Shop Drawing) ใช้เในการตรวจสอบ โดยจัดส่งด้วย Request for Approval (RFA)
- 3.4.2. ประเภทเอกสาร: ไฟล์ PDF
- 3.4.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
- 3.4.4. การอ้างอิงและจัดกลุ่ม: ช้สำหรับอ้างอิง ใน Shop Drawings, มีการจัดหมวดหมู่ของ Shop Drawings
* 3.5. การจัดการเอกสารขออนุมัติ (Request for Approval & Workflow)
- 3.5.1. วัตถุประสงค์: เอกสารขออนุมัติ (Request for Approval) ใช้ในการส่งเอกสารเพิอขออนุมัติ
- 3.5.2. ประเภทเอกสาร: Request for Approval (RFA) เป็นชนิดหนึ่งของ Correspondence ที่มีลักษณะเฉพาะที่ต้องได้รับการอนุมัติ มีประเภทดังนี้:
- Request for Drawing Approval (RFA_DWG)
- Request for Document Approval (RFA_DOC)
- Request for Method statement Approval (RFA_MES)
- Request for Material Approval (RFA_MAT)
- 3.5.2. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
- 3.5.4. การอ้างอิงและจัดกลุ่ม: การจัดการ Drawing (RFA_DWG):
- เอกสาร RFA_DWG จะประกอบไปด้วย Shop Drawing (shop_drawings) หลายแผ่น ซึ่งแต่ละแผ่นมี Revision ของตัวเอง
- Shop Drawing แต่ละ Revision สามารถอ้างอิงถึง Contract Drawing (Ccontract_drawings) หลายแผ่น หรือไม่อ้างถึงก็ได้
- ระบบต้องมีส่วนสำหรับจัดการข้อมูล Master Data ของทั้ง Shop Drawing และ Contract Drawing แยกจากกัน
- 3.6.5. Workflow การอนุมัติ: ต้องรองรับกระบวนการอนุมัติที่ซับซ้อนและเป็นลำดับ เช่น
- ส่งจาก Originator -> Organization 1 -> Organization 2 -> Organization 3 แล้วส่งผลกลับตามลำดับเดิม (โดยถ้า องกรณ์ใดใน Workflow ให้ส่งกลับ ก็สามารถส่งผลกลับตามลำดับเดิมโดยไม่ต้องรอให้ถึง องกรณืในลำดับถัดไป)
- 3.6.6. การจัดการ: มีการจัดการอย่างน้อยดังนี้
0 - สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบของ องกรณ์ ที่อยู่ใน Workflow ได้
- มีระบบแจ้งเตือน ให้ผู้รับผิดชอบของ องกรณ์ ที่อยู่ใน Workflow ทราบ เมื่อมี RFA ใหม่ หรือมีการเปลี่ยนสถานะ
* 3.6.การจัดการเอกสารนำส่ง (Transmittals)
- 3.6.1. วัตถุประสงค์: เอกสารนำส่ง ใช้สำหรับ นำส่ง Request for Approval (RFAS) หลายฉบับ ไปยังองค์กรอื่น
- 3.6.2. ประเภทเอกสาร: ไฟล์ PDF
- 3.6.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
- 3.6.4. การอ้างอิงและจัดกลุ่ม: เอกสารนำส่ง เป็นส่วนหนึ่งใน Correspondence
* 3.7. ใบเวียนเอกสารภายใน (Internal Circulation Sheet)
- 3.7.1. วัตถุประสงค์: การสื่อสาร เอกสาร (Correspondence) ทุกฉบับ จะมีใบเวียนเอกสารเพื่อควบคุมและมอบหมายงานภายในองค์กร (สามารถดูและแก้ไขได้เฉพาะคนในองค์กร)
- 3.7.2. ประเภทเอกสาร: ไฟล์ PDF
- 3.7.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ในองค์กรนั้น สามารถสร้างและแก้ไขได้
- 3.7.4. การอ้างอิงและจัดกลุ่ม: การระบุผู้รับผิดชอบ:
- ผู้รับผิดชอบหลัก (Main): มีได้หลายคน
- ผู้ร่วมปฏิบัติงาน (Action): มีได้หลายคน
- ผู้ที่ต้องรับทราบ (Information): มีได้หลายคน
- 3.7.5. การติดตามงาน:
- สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบประเภท Main และ Action ได้
- มีระบบแจ้งเตือนเมื่อมี Circulation ใหม่ และแจ้งเตือนล่วงหน้าก่อนถึงวันแล้วเสร็จ
- สามารถปิด Circulation ได้เมื่อดำเนินการตอบกลับไปยังองค์กรผู้ส่ง (Originator) แล้ว หรือ รับทราบแล้ว (For Information)
* 3.8. ประวัติการแก้ไข (Revisions): ระบบจะเก็บประวัติการสร้างและแก้ไข เอกสารทั้งหมด
* 3.9. การจัดเก็บ: เอกสารและไฟล์แนบจะถูกจัดเก็บในโฟลเดอร์บน Server (/share/dms-data/) โดยมีการอ้างอิงข้อมูล (Metadata) ในฐานข้อมูล และสามารถจัดเรียงตามวันที่ในเอกสาร (Document Date) ได้ ตัวอย่างเช่น
- Correspondence จัดเก็บใน /share/dms-data/correspondences/YYMMDD/ชื่อไฟล์.pdf
- Request for Approval จัดเก็บใน /share/dms-data/rfas/YYMMDD/ชื่อไฟล์.pdf
- Shop Drawings จัดเก็บใน /share/dms-data/shop_drawings/YYMMDD/ชื่อไฟล์.pdf
## 🔐 4. ข้อกำหนดด้านสิทธิ์และการเข้าถึง (Access Control Requirements)
* 4.1. ภาพรวม: ผู้ใช้และองค์กรสามารถดูและแก้ไขเอกสารได้ตามสิทธิ์ที่ได้รับ โดยระบบสิทธิ์จะเป็นแบบ Role-Based Access Control (RBAC)
* 4.2. ระดับของสิทธิ์:
- Global Roles: สิทธิ์ในภาพรวมของระบบ
- Project-Specific Roles: สิทธิ์ที่ถูกกำหนดให้ผู้ใช้สำหรับโครงการนั้นๆ โดยเฉพาะ (เช่น เป็น Editor ในโครงการ A แต่เป็น Viewer ในโครงการ B)
- Contract-Specific Roles: สิทธิ์ที่ถูกกำหนดให้โครงการสำหรับสัญญานั้นๆ (เช่น เป็น Admin ในสัญญา 1 จะเป็น Admin ใน โครงการ A และ ฺB ที่อยู่ในสัญญา 1)
* 4.3. บทบาท (Roles) พื้นฐาน:
- Superadmin: ไม่มีข้อจำกัดใดๆ สามารถจัดการได้ทุกอย่างข้ามองค์กร
- Admin: มีสิทธิ์เต็มที่ แต่จำกัดเฉพาะในองค์กรที่ตัวเองสังกัด สามารถจัดการผู้ใช้ในองค์กรได้ สามารถสร้าง Role ใหม่และกำหนดสิทธิ์ (Permissions) เพิ่มเติมได้ในภายหลังผ่านหน้า Admin
- Document Control สามารถ เพิ่ม/แก้ไข/ลบ เอกสาร เฉพาะในองค์กรที่ตัวเองสังกัด ไม่สามารถจัดการผู้ใช้ได้
- Editor: สามารถ เพิ่ม/แก้ไข เอกสารที่กำหนดไว้ เฉพาะในองค์กรที่ตัวเองสังกัด
- Viewer: สามารถดู เอกสาร เฉพาะในองค์กรที่ตัวเองสังกัด
* 4.4. การบังคับใช้สิทธิ์: สิทธิ์ขององค์กรจะครอบคลุมสิทธิ์ของผู้ใช้ และการเข้าถึงข้อมูลที่เกี่ยวข้องกับโครงการ (เช่น การแก้ไขเอกสาร) จะถูกตรวจสอบเทียบกับสิทธิ์ที่ผู้ใช้มีในโครงการนั้นๆ โดยเฉพาะ
## 👥 5. ข้อกำหนดด้านผู้ใช้งาน (User Interface & Experience)
* 5.1. Layout หลัก: หน้าเว็บใช้รูปแบบ App Shell ที่ประกอบด้วย:
- Navbar (ส่วนบน): แสดงชื่อระบบ, เมนูผู้ใช้ (Profile), เมนูสำหรับ 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 ที่ผู้ใช้ต้องดำเนินการ
* 5.4. การติดตามสถานะ: องค์กรสามารถติดตามสถานะเอกสารทั้งของตนเอง (Originator) และสถานะเอกสารที่ส่งมาถึงตนเอง (Recipient)
* 5.5. การจัดการข้อมูลส่วนตัว (Profile Page): ผู้ใช้สามารถจัดการข้อมูลส่วนตัวและเปลี่ยนรหัสผ่านของตนเองได้
* 5.6. การจัดการเอกสารทางเทคนิค (Technical Documents & Workflow): ผู้ใช้สามารถดู Technical Document ในรูปแบบ Workflow ทั้งหมดได้ในหน้าเดียว, ขั้นตอนที่ยังไม่ถึงหรือผ่านไปแล้วจะเป็นรูปแบบ diable, สามารถดำเนินการได้เฉพาะในขั้นตอนที่ได้รับมอบหมายงาน (active) เช่น ตรวจสอบแล้ว เพื่อไปยังขั้นตอนต่อไป, สิทธิ์ admin ขึ้นไป สามรถกด ไปยังขั้นตอนต่อไป ได้ทุกขั้นตอน, การย้อนกลับ ไปขั้นตอนก่อนหน้า สามารถทำได้โดย สิทธิ์ admin ขึ้นไป
## 6. ข้อกำหนดที่ไม่ใช่ฟังก์ชันการทำงาน (Non-Functional Requirements)
* 6.1. การบันทึกการกระทำ (Audit Log): ทุกการกระทำที่สำคัญของผู้ใช้ (สร้าง, แก้ไข, ลบ, ส่ง) จะถูกบันทึกไว้ใน audit_logs เพื่อการตรวจสอบย้อนหลัง
* 6.2. การค้นหา (Search): ระบบต้องมีฟังก์ชันการค้นหาขั้นสูง ที่สามารถค้นหาเอกสารจากหลายเงื่อนไขพร้อมกันได้ เช่น ค้นหาจากชื่อเรื่อง, ประเภท, วันที่, และ Tag
* 6.3. การทำรายงาน (Reporting): สามารถจัดทำรายงานสรุปแยกประเภทของ Correspondence ประจำวัน, สัปดาห์, เดือน, และปีได้
* 6.4. ประสิทธิภาพ (Performance): มีการใช้ Caching กับข้อมูลที่เรียกใช้บ่อย และใช้ Pagination ในตารางข้อมูลเพื่อจัดการข้อมูลจำนวนมาก
* 6.5. ความปลอดภัย (Security):
- มีระบบ Rate Limiting เพื่อป้องกันการโจมตีแบบ Brute-force
- การจัดการ Secret (เช่น รหัสผ่าน DB, JWT Secret) จะต้องทำผ่าน Environment Variable ของ Docker เพื่อความปลอดภัยสูงสุด
## 📈 7.
## 🧩 8.
🎯
📤
📊
✅
🔄

456
infrastructure/Markdown/LCBP3-DMS V1_1_1_FullStackJS.md Normal file
View File

@@ -0,0 +1,456 @@
# แนวทางการพัฒนา FullStackJS
## 🧠 ปรัชญาทั่วไป
แนวทางปฏิบัติที่ดีที่สุดแบบครบวงจรสำหรับการพัฒนา **NestJS Backend**, **NextJS Frontend** และ **Tailwind-based UI/UX** ในสภาพแวดล้อม TypeScript
มุ่งเน้นที่ **ความชัดเจน (clarity)**, **ความง่ายในการบำรุงรักษา (maintainability)**, **ความสอดคล้องกัน (consistency)** และ **การเข้าถึงได้ (accessibility)** ตลอดทั้งสแต็ก
-----
## ⚙️ แนวทางทั่วไปสำหรับ TypeScript
### หลักการพื้นฐาน
- ใช้ **ภาษาอังกฤษ** สำหรับโค้ดและเอกสารทั้งหมด
- กำหนดไทป์ (type) อย่างชัดเจนสำหรับตัวแปร, พารามิเตอร์ และค่าที่ส่งกลับ (return values) ทั้งหมด
- หลีกเลี่ยงการใช้ `any`; ให้สร้างไทป์ (types) หรืออินเทอร์เฟซ (interfaces) ที่กำหนดเอง
- ใช้ **JSDoc** สำหรับคลาส (classes) และเมธอด (methods) ที่เป็น public
- ส่งออก (Export) **สัญลักษณ์หลัก (main symbol) เพียงหนึ่งเดียว** ต่อไฟล์
- หลีกเลี่ยงบรรทัดว่างภายในฟังก์ชัน
### ข้อตกลงในการตั้งชื่อ (Naming Conventions)
| Entity (สิ่งที่ตั้งชื่อ) | Convention (รูปแบบ) | Example (ตัวอย่าง) |
|:--|:--|:--|
| Classes | PascalCase | `UserService` |
| Variables & Functions | camelCase | `getUserInfo` |
| Files & Folders | kebab-case | `user-service.ts` |
| Environment Variables | UPPERCASE | `DATABASE_URL` |
| Booleans | Verb + Noun | `isActive`, `canDelete`, `hasPermission` |
ใช้คำเต็ม — ไม่ใช้อักษรย่อ — ยกเว้นคำมาตรฐาน (เช่น `API`, `URL`, `req`, `res`, `err`, `ctx`)
-----
## 🧩 ฟังก์ชัน (Functions)
- เขียนฟังก์ชันให้สั้น และทำ **หน้าที่เพียงอย่างเดียว** (single-purpose) (\< 20 บรรทัด)
- ใช้ **early returns** เพื่อลดการซ้อน (nesting) ของโค้ด
- ใช้ **map**, **filter**, **reduce** แทนการใช้ loops เมื่อเหมาะสม
- ควรใช้ **arrow functions** สำหรับตรรกะสั้นๆ, และใช้ **named functions** ในกรณีอื่น
- ใช้ **default parameters** แทนการตรวจสอบค่า null
- จัดกลุ่มพารามิเตอร์หลายตัวให้เป็นอ็อบเจกต์เดียว (RO-RO pattern)
- ส่งค่ากลับ (Return) เป็นอ็อบเจกต์ที่มีไทป์กำหนด (typed objects) ไม่ใช่ค่าพื้นฐาน (primitives)
- รักษาระดับของสิ่งที่เป็นนามธรรม (abstraction level) ให้เป็นระดับเดียวในแต่ละฟังก์ชัน
-----
## 🧱 การจัดการข้อมูล (Data Handling)
- ห่อหุ้มข้อมูล (Encapsulate) ในไทป์แบบผสม (composite types)
- ใช้ **immutability** (การไม่เปลี่ยนแปลงค่า) ด้วย `readonly` และ `as const`
- ทำการตรวจสอบความถูกต้องของข้อมูล (Validations) ในคลาสหรือ DTOs ไม่ใช่ภายในฟังก์ชันทางธุรกิจ
- ตรวจสอบความถูกต้องของข้อมูลโดยใช้ DTOs ที่มีไทป์กำหนดเสมอ
-----
## 🧰 คลาส (Classes)
- ปฏิบัติตามหลักการ **SOLID**
- ควรใช้ **composition มากกว่า inheritance** (Prefer composition over inheritance)
- กำหนด **interfaces** สำหรับสัญญา (contracts)
- ให้คลาสมุ่งเน้นการทำงานเฉพาะอย่างและมีขนาดเล็ก (\< 200 บรรทัด, \< 10 เมธอด, \< 10 properties)
-----
## 🚨 การจัดการข้อผิดพลาด (Error Handling)
- ใช้ Exceptions สำหรับข้อผิดพลาดที่ไม่คาดคิด
- ดักจับ (Catch) ข้อผิดพลาดเพื่อแก้ไขหรือเพิ่มบริบท (context) เท่านั้น; หากไม่เช่นนั้น ให้ใช้ global error handlers
- ระบุข้อความข้อผิดพลาด (error messages) ที่มีความหมายเสมอ
-----
## 🧪 การทดสอบ (ทั่วไป) (Testing (General))
- ใช้รูปแบบ **Arrange–Act–Assert**
- ใช้ชื่อตัวแปรในการทดสอบที่สื่อความหมาย (`inputData`, `expectedOutput`)
- เขียน **unit tests** สำหรับ public methods ทั้งหมด
- จำลอง (Mock) การพึ่งพาภายนอก (external dependencies)
- เพิ่ม **acceptance tests** ต่อโมดูลโดยใช้รูปแบบ Given–When–Then
-----
# 🏗️ แบ็กเอนด์ (NestJS) (Backend (NestJS))
### หลักการ
- **สถาปัตยกรรมแบบโมดูลาร์ (Modular architecture)**:
- หนึ่งโมดูลต่อหนึ่งโดเมน
- โครงสร้างแบบ Controller → Service → Repository (Model)
- DTOs ที่ตรวจสอบความถูกต้องด้วย **class-validator**
- ใช้ **MikroORM** (หรือ TypeORM/Prisma) สำหรับการคงอยู่ของข้อมูล (persistence) ซึ่งสอดคล้องกับสคีมา MariaDB
- ห่อหุ้มโค้ดที่ใช้ซ้ำได้ไว้ใน **common module** (`@app/common`):
- Configs, decorators, DTOs, guards, interceptors, notifications, shared services, types, validators
### ฟังก์ชันหลัก (Core Functionalities)
- Global **filters** สำหรับการจัดการ exception
- **Middlewares** สำหรับการจัดการ request
- **Guards** สำหรับการอนุญาต (permissions) และ RBAC
- **Interceptors** สำหรับการแปลงข้อมูล response และการบันทึก log
### ข้อจำกัดในการ Deploy (QNAP Container Station)
- **ห้ามใช้ไฟล์ `.env`** ในการตั้งค่า Environment Variables
- การตั้งค่าทั้งหมด (เช่น Database connection string, JWT secret) **จะต้องถูกกำหนดผ่าน Environment Variable ใน `docker-compose.yml` โดยตรง** ซึ่งจะจัดการผ่าน UI ของ QNAP Container Station
### โครงสร้างโมดูลตามโดเมน (Domain-Driven Module Structure)
เพื่อให้สอดคล้องกับสคีมา SQL (LCBP3-DMS) เราจะใช้โครงสร้างโมดูลแบบ **Domain-Driven (แบ่งตามขอบเขตธุรกิจ)** แทนการแบ่งตามฟังก์ชัน:
1. **CoreModule / CommonModule:**
* เก็บ Services ที่ใช้ร่วมกัน เช่น `DatabaseModule`, `FileStorageService` (จัดการไฟล์ใน QNAP), `AuditLogService`, และ `NotificationService`
2. **AuthModule / UserModule:**
* จัดการ `users`, `roles`, `permissions` และการยืนยันตัวตน (JWT, Guards)
* **(สำคัญ)** ต้องรับผิดชอบการตรวจสอบสิทธิ์ **3 ระดับ**: สิทธิ์ระดับระบบ (Global Role), สิทธิ์ระดับโปรเจกต์ (Project Role), และ **สิทธิ์ระดับสัญญา (Contract Role)**
* **(สำคัญ)** ต้องมี API สำหรับ Admin เพื่อ **สร้างและจัดการ Role และการจับคู่ Permission แบบไดนามิก** (ไม่ใช่แค่ seed ข้อมูลเริ่มต้น)
3. **ProjectModule:**
* จัดการ `projects`, `organizations`, `contracts`, `project_parties`, `contract_parties`
4. **CorrespondenceModule (โมดูลศูนย์กลาง):**
* จัดการ `correspondences`, `correspondence_revisions`
* จัดการ `correspondence_attachments` (ตารางเชื่อมไฟล์แนบ)
* รับผิดชอบเวิร์กโฟลว์ **"Correspondence Routings"** (`correspondence_routings`) สำหรับการส่งต่อเอกสารทั่วไประหว่างองค์กร
5. **RfaModule:**
* จัดการ `rfas`, `rfa_revisions`, `rfa_items`
* รับผิดชอบเวิร์กโฟลว์ **"RFA Workflows"** (`rfa_workflows`) สำหรับการอนุมัติเอกสารทางเทคนิค
6. **DrawingModule:**
* จัดการ `shop_drawings`, `shop_drawing_revisions`, `contract_drawings` และหมวดหมู่ต่างๆ
* จัดการ `shop_drawing_revision_attachments` (ตารางเชื่อมไฟล์แนบ)
7. **CirculationModule:**
* จัดการ `circulations`, `circulation_templates`, `circulation_assignees`
* จัดการ `circulation_attachments` (ตารางเชื่อมไฟล์แนบ)
* รับผิดชอบเวิร์กโฟลGว์ **"Circulations"** สำหรับการเวียนเอกสาร **ภายในองค์กร**
8. **TransmittalModule:**
* จัดการ `transmittals` และ `transmittal_items`
9. **SearchModule:**
* **(สำหรับ V1)** ให้บริการค้นหาขั้นสูง (Advanced Search) โดยต้องรองรับการกรองจาก ชื่อเรื่อง (LIKE), ประเภท, วันที่, และ **Tags** (ผ่านการ Join ตาราง) โดยค้นหาผ่าน Views (`v_current_rfas`, `v_current_correspondences`)
### เครื่องมือและไลบรารีที่แนะนำ (Recommended Tools & Libraries)
🔐 **Authentication & Authorization**
* `@nestjs/passport`
* `@nestjs/jwt`
* `casl` – สำหรับ RBAC (Role-Based Access Control)
🗃️ **Database & ORM**
* `@nestjs/typeorm` – ORM สำหรับ SQL (หรือ `Prisma` เป็นทางเลือก)
* `typeorm-seeding` – สำหรับสร้างข้อมูลจำลอง (seeding)
📦 **Validation & Transformation**
* `class-validator`
* `class-transformer`
📁 **File Upload & Storage**
* `@nestjs/platform-express`
* `multer` – สำหรับจัดการไฟล์
🔍 **Search**
* **(สำหรับ V1)** เน้นการค้นหาขั้นสูงตาม Requirement 6.2 (Full-text search/Elasticsearch จะพิจารณาใน V2)
📬 **Notification**
* `nodemailer` – สำหรับส่งอีเมล
* `@nestjs/schedule` – สำหรับ cron job หรือแจ้งเตือนตามเวลา
📊 **Logging & Monitoring**
* `winston` หรือ `nestjs-pino` – ระบบ log ที่ยืดหยุ่น
* `@nestjs/terminus` – สำหรับ health check
🧪 **Testing**
* `@nestjs/testing`
* `jest` – สำหรับ unit/integration test
🌐 **API Documentation**
* `@nestjs/swagger` – **(สำคัญมาก)** สร้าง Swagger UI อัตโนมัติ ต้องใช้ DTOs อย่างเคร่งครัดเพื่อความชัดเจนของ API สำหรับทีม Frontend
🛡️ **Security**
* `helmet` – ป้องกันช่องโหว่ HTTP
* `rate-limiter-flexible` – ป้องกัน brute force
### การทดสอบ (Testing)
- ใช้ **Jest** สำหรับการทดสอบ
- ทดสอบทุก controller และ service
- เพิ่ม endpoint `admin/test` เพื่อใช้เป็น smoke test
-----
# 🖥️ ฟรอนต์เอนด์ (NextJS / React / UI) (Frontend (NextJS / React / UI))
### โปรไฟล์นักพัฒนา (Developer Profile)
วิศวกร TypeScript + React/NextJS ระดับ Senior
เชี่ยวชาญ **TailwindCSS**, **Shadcn/UI**, และ **Radix** สำหรับการพัฒนา UI
### แนวทางการพัฒนาโค้ด (Code Implementation Guidelines)
- ใช้ **early returns** เพื่อความชัดเจน
- ใช้คลาสของ **TailwindCSS** ในการกำหนดสไตล์เสมอ
- ควรใช้ `class:` syntax แบบมีเงื่อนไข (หรือ utility `clsx`) มากกว่าการใช้ ternary operators ใน class strings
- ใช้ **const arrow functions** สำหรับ components และ handlers
- Event handlers ให้ขึ้นต้นด้วย `handle...` (เช่น `handleClick`, `handleSubmit`)
- รวมแอตทริบิวต์สำหรับการเข้าถึง (accessibility) ด้วย:
`tabIndex="0"`, `aria-label`, `onKeyDown`, ฯลฯ
- ตรวจสอบให้แน่ใจว่าโค้ดทั้งหมด **สมบูรณ์**, **ผ่านการทดสอบ**, และ **ไม่ซ้ำซ้อน (DRY)**
- ต้อง import โมดูลที่จำเป็นต้องใช้อย่างชัดเจนเสมอ
### UI/UX ด้วย React
- ใช้ **semantic HTML**
- ใช้คลาสของ **Tailwind** ที่รองรับ responsive (`sm:`, `md:`, `lg:`)
- รักษาลำดับชั้นของการมองเห็น (visual hierarchy) ด้วยการใช้ typography และ spacing
- ใช้ **Shadcn** components (Button, Input, Card, ฯลฯ) เพื่อ UI ที่สอดคล้องกัน
- ทำให้ components มีขนาดเล็กและมุ่งเน้นการทำงานเฉพาะอย่าง
- ใช้ utility classes สำหรับการจัดสไตล์อย่างรวดเร็ว (spacing, colors, text, ฯลฯ)
- ตรวจสอบให้แน่ใจว่าสอดคล้องกับ **ARIA** และใช้ semantic markup
### การตรวจสอบฟอร์มและข้อผิดพลาด (Form Validation & Errors)
- ใช้ไลบรารีฝั่ง client เช่น `zod` และ `react-hook-form`
- แสดงข้อผิดพลาดด้วย **alert components** หรือข้อความ inline
- ต้องมี labels, placeholders, และข้อความ feedback
-----
# 🔗 แนวทางการบูรณาการ Full Stack (Full Stack Integration Guidelines)
| Aspect (แง่มุม) | Backend (NestJS) | Frontend (NextJS) | UI Layer (Tailwind/Shadcn) |
|:--|:--|:--|:--|
| API | REST / GraphQL Controllers | API hooks ผ่าน fetch/axios/SWR | Components ที่รับข้อมูล |
| Validation (การตรวจสอบ) | `class-validator` DTOs | `zod` / `react-hook-form` | สถานะของฟอร์ม/input ใน Shadcn |
| Auth (การยืนยันตัวตน) | Guards, JWT | NextAuth / cookies | สถานะ UI ของ Auth (loading, signed in) |
| Errors (ข้อผิดพลาด) | Global filters | Toasts / modals | Alerts / ข้อความ feedback |
| Testing (การทดสอบ) | Jest (unit/e2e) | Vitest / Playwright | Visual regression |
| Styles (สไตล์) | Scoped modules (ถ้าจำเป็น) | Tailwind / Shadcn | Tailwind utilities |
| Accessibility (การเข้าถึง) | Guards + filters | ARIA attributes | Semantic HTML |
-----
# 🗂️ ข้อตกลงเฉพาะสำหรับ DMS (LCBP3-DMS)
ส่วนนี้ขยายแนวทาง FullStackJS ทั่วไปสำหรับโปรเจกต์ **LCBP3-DMS** โดยมุ่งเน้นไปที่เวิร์กโฟลว์การอนุมัติเอกสาร (Correspondence, RFA, Drawing, Contract, Transmittal, Circulation)
## 🧱 โมดูลโดเมนฝั่งแบ็กเอนด์ (Backend Domain Modules)
ใช้โครงสร้างโดเมนแบบโมดูลาร์ที่สะท้อนสคีมา SQL โดย `correspondences` จะทำหน้าที่เป็นศูนย์กลาง (โครงสร้างนี้จะอยู่ภายใต้ "Functional Modules" ที่กล่าวถึงข้างต้น)
```
src/
├─ modules/
│ ├─ correspondences/ (Core: Master documents, Revisions, correspondence_attachments)
│ ├─ rfas/ (RFA logic, Revisions, Workflows, Items)
│ ├─ drawings/ (ShopDrawings, Revisions, shop_drawing_revision_attachments)
│ ├─ circulations/ (Internal circulation, Templates, circulation_attachments)
│ ├─ transmittals/ (Transmittal logic, Items)
│ ├─ projects-contracts/ (Projects, Contracts, Organizations, Parties)
│ ├─ users-auth/ (Users, Roles, Permissions, Auth)
│ ├─ audit-log/
│ └─ common/
```
### ข้อตกลงการตั้งชื่อ (Naming Convention)
| Entity (สิ่งที่ตั้งชื่อ) | Example (ตัวอย่างจาก SQL) |
|:--|:--|
| Table | `correspondences`, `rfa_revisions`, `contract_parties` |
| Column | `correspondence_id`, `created_by`, `is_current` |
| DTO | `CreateRfaDto`, `UpdateCorrespondenceDto` |
| Controller | `rfas.controller.ts` |
| Service | `correspondences.service.ts` |
-----
## 🧩 RBAC และการควบคุมสิทธิ์ (RBAC & Permission Control)
ใช้ Decorators เพื่อบังคับใช้สิทธิ์การเข้าถึง โดยอ้างอิงสิทธิ์จากตาราง `permissions`
```ts
@RequirePermission('rfas.respond') // ต้องตรงกับ 'permission_code'
@Put(':id')
updateRFA(@Param('id') id: string) {
return this.rfaService.update(id);
}
```
### Roles (บทบาท)
- **Superadmin**: ไม่มีข้อจำกัดใดๆ
- **Admin**: มีสิทธิ์เต็มที่ในองค์กร
- **Document Control**: เพิ่ม/แก้ไข/ลบ เอกสารในองค์กร
- **Editor**: สามารถ เพิ่ม/แก้ไข เอกสารที่กำหนด
- **Viewer**: สามารถดู เอกสาร
### ตัวอย่าง Permissions (จากตาราง `permissions`)
- `rfas.view`, `rfas.create`, `rfas.respond`, `rfas.delete`
- `drawings.view`, `drawings.upload`, `drawings.delete`
- `corr.view`, `corr.manage`
- `transmittals.manage`
- `cirs.manage`
- `project_parties.manage`
การจับคู่ระหว่าง roles และ permissions **เริ่มต้น** จะถูก seed ผ่านสคริปต์ (ดังที่เห็นในไฟล์ SQL) **อย่างไรก็ตาม `AuthModule`/`UserModule` ต้องมี API สำหรับ Admin เพื่อสร้าง Role ใหม่และกำหนดสิทธิ์ (Permissions) เพิ่มเติมได้ในภายหลัง**
-----
## 🧾 มาตรฐาน AuditLog (AuditLog Standard)
บันทึกการดำเนินการ CRUD และการจับคู่ทั้งหมดลงในตาราง `audit_logs`
| Field (ฟิลด์) | Type (จาก SQL) | Description (คำอธิบาย) |
|:--|:--|:--|
| `audit_id` | `BIGINT` | Primary Key |
| `user_id` | `INT` | ผู้ใช้ที่ดำเนินการ (FK -\> users) |
| `action` | `VARCHAR(100)` | `rfa.create`, `correspondence.update`, `login.success` |
| `entity_type`| `VARCHAR(50)` | ชื่อตาราง/โมดูล เช่น 'rfa', 'correspondence' |
| `entity_id` | `VARCHAR(50)` | Primary ID ของระเบียนที่ได้รับผลกระทบ |
| `details_json`| `JSON` | ข้อมูลบริบท (เช่น ฟิลด์ที่มีการเปลี่ยนแปลง) |
| `ip_address` | `VARCHAR(45)` | IP address ของผู้ดำเนินการ |
| `user_agent` | `VARCHAR(255)`| User Agent ของผู้ดำเนินการ |
| `created_at` | `TIMESTAMP` | Timestamp (UTC) |
ตัวอย่างการใช้งาน:
```ts
await this.auditLogService.log({
userId: user.id,
action: 'rfa.update_status',
entityType: 'rfa_revisions',
entityId: rfaRevision.id,
detailsJson: { from: 'DFT', to: 'FAP' },
ipAddress: req.ip,
});
```
-----
## 📂 การจัดการไฟล์ (File Handling) (ปรับปรุงใหม่)
### มาตรฐานการอัปโหลดไฟล์ (File Upload Standard)
- **ตรรกะใหม่:** การอัปโหลดไฟล์ทั้งหมดจะถูกจัดการโดย `FileStorageService` และบันทึกข้อมูลไฟล์ลงในตาราง `attachments` (ตารางกลาง)
- ไฟล์จะถูกเชื่อมโยงไปยัง Entity ที่ถูกต้องผ่าน **ตารางเชื่อม (Junction Tables)** เท่านั้น:
- `correspondence_attachments` (เชื่อม Correspondence กับ Attachments)
- `circulation_attachments` (เชื่อม Circulation กับ Attachments)
- `shop_drawing_revision_attachments` (เชื่อม Drawing Revision กับ Attachments)
- **(สำคัญ)** คอลัมน์ `file_path` ถูกลบออกจาก `shop_drawing_revisions` แล้ว ต้องใช้ระบบตารางเชื่อมใหม่นี้เท่านั้น
- เส้นทางจัดเก็บไฟล์ (Upload path): อ้างอิงจาก Requirement 2.1 คือ `/share/dms-data` โดย `FileStorageService` จะสร้างโฟลเดอร์ย่อยแบบรวมศูนย์ (เช่น `/share/dms-data/uploads/{YYYY}/{MM}/[stored_filename]`)
- **(หมายเหตุ)**: โครงสร้างนี้ *แทนที่* โครงสร้างแบบแยกโมดูลที่ระบุใน Requirement 3.9 เนื่องจากการออกแบบใหม่ได้รวมศูนย์ไฟล์ไว้ที่ตาราง `attachments` กลางแล้ว
- ประเภทไฟล์ที่อนุญาต: `pdf, dwg, docx, xlsx, zip`
- ขนาดสูงสุด: **50 MB**
- จัดเก็บนอก webroot
- ให้บริการไฟล์ผ่าน endpoint ที่ปลอดภัย `/files/:attachment_id/download`
### การควบคุมการเข้าถึง (Access Control)
การเข้าถึงไฟล์ไม่ใช่การเข้าถึงโดยตรง endpoint `/files/:attachment_id/download` จะต้อง:
1. ค้นหาระเบียน `attachment`
2. ตรวจสอบว่า `attachment_id` นี้ เชื่อมโยงกับ Entity ใด (เช่น `correspondence`, `circulation`, `shop_drawing_revision`) ผ่านตารางเชื่อม
3. ตรวจสอบว่าผู้ใช้มีสิทธิ์ (permission) ในการดู Entity ต้นทางนั้นๆ หรือไม่
-----
## 📊 การรายงานและการส่งออก (Reporting & Exports)
### วิวสำหรับการรายงาน (Reporting Views) (จาก SQL)
การรายงานควรสร้างขึ้นจาก Views ที่กำหนดไว้ล่วงหน้าในฐานข้อมูลเป็นหลัก:
- `v_current_correspondences`: สำหรับ revision ปัจจุบันทั้งหมดของเอกสารที่ไม่ใช่ RFA
- `v_current_rfas`: สำหรับ revision ปัจจุบันทั้งหมดของ RFA และข้อมูล master
- `v_contract_parties_all`: สำหรับการตรวจสอบความสัมพันธ์ของ project/contract/organization
Views เหล่านี้ทำหน้าที่เป็นแหล่งข้อมูลหลักสำหรับการรายงานฝั่งเซิร์ฟเวอร์และการส่งออกข้อมูล
### กฎการส่งออก (Export Rules)
- Export formats: CSV, Excel, PDF.
- จัดเตรียมมุมมองสำหรับพิมพ์ (Print view).
- รวมลิงก์ไปยังต้นทาง (เช่น `/rfas/:id`).
-----
## 🧮 ฟรอนต์เอนด์: รูปแบบ DataTable และฟอร์ม (Frontend: DataTable & Form Patterns)
### DataTable (Server‑Side)
- Endpoint: `/api/{module}?page=1&pageSize=20&sort=...&filter=...`
- ต้องรองรับ: การแบ่งหน้า (pagination), การเรียงลำดับ (sorting), การค้นหา (search), การกรอง (filters)
- แสดง revision ล่าสุดแบบ inline เสมอ (สำหรับ RFA/Drawing)
### มาตรฐานฟอร์ม (Form Standards)
- ต้องมีการใช้งาน Dropdowns แบบขึ้นต่อกัน (Dependent dropdowns) (ตามที่สคีมารองรับ):
- Project → Contract Drawing Volumes
- Contract Drawing Category → Sub-Category
- RFA (ประเภท Shop Drawing) → Shop Drawing Revisions ที่เชื่อมโยงได้
- การอัปโหลดไฟล์: ต้องมี preview + validation (ผ่านตรรกะของ `attachments` และตารางเชื่อมใหม่)
- ส่ง (Submit) ผ่าน API พร้อม feedback แบบ toast
### ข้อกำหนด Component เฉพาะ (Specific UI Requirements)
- **Dashboard - My Tasks:** ต้องพัฒนา Component ตาราง "งานของฉัน" (My Tasks) ซึ่งดึงข้อมูลงานที่ผู้ใช้ล็อกอินอยู่ต้องรับผิดชอบ (Main/Action) จากโมดูล `Circulations`
- **Workflow Visualization:** ต้องพัฒนา Component สำหรับแสดงผล Workflow (โดยเฉพาะ RFA) ที่แสดงขั้นตอนทั้งหมดเป็นลำดับ โดยขั้นตอนปัจจุบัน (active) เท่านั้นที่ดำเนินการได้ และขั้นตอนอื่นเป็น `disabled` ต้องมีตรรกะสำหรับ Admin ในการ override หรือย้อนกลับขั้นตอนได้
-----
## 🧭 แดชบอร์ดและฟีดกิจกรรม (Dashboard & Activity Feed)
### การ์ดบนแดชบอร์ด (Dashboard Cards)
- แสดง Correspondences, RFAs, Circulations ล่าสุด
- รวมสรุป KPI (เช่น "RFAs ที่รอการอนุมัติ")
- รวมลิงก์ด่วนไปยังโมดูลต่างๆ
### ฟีดกิจกรรม (Activity Feed)
- แสดงรายการ `audit_logs` ล่าสุด (10 รายการ) ที่เกี่ยวข้องกับผู้ใช้
<!-- end list -->
```ts
// ตัวอย่าง API response
[
{ user: 'editor01', action: 'Updated RFA (LCBP3-RFA-001)', time: '2025-11-04T09:30Z' }
]
```
-----
## ✅ มาตรฐานที่นำไปใช้แล้ว (จาก SQL v1.1.0) (Implemented Standards (from SQL v1.1.0))
ส่วนนี้ยืนยันว่าแนวทางปฏิบัติที่ดีที่สุดต่อไปนี้เป็นส่วนหนึ่งของการออกแบบฐานข้อมูลอยู่แล้ว และควรถูกนำไปใช้ประโยชน์ ไม่ใช่สร้างขึ้นใหม่
- ✅ **Soft Delete:** นำไปใช้แล้วผ่านคอลัมน์ `deleted_at` ในตารางสำคัญ (เช่น `correspondences`, `rfas`, `project_parties`) ตรรกะการดึงข้อมูลต้องกรอง `deleted_at IS NULL`
- ✅ **Database Indexes:** สคีมาได้มีการทำ index ไว้อย่างหนักหน่วงบน foreign keys และคอลัมน์ที่ใช้ค้นหาบ่อย (เช่น `idx_rr_rfa`, `idx_cor_project`, `idx_cr_is_current`) เพื่อประสิทธิภาพ
- ✅ **โครงสร้าง RBAC:** มีระบบ `users`, `roles`, `permissions`, `user_roles`, และ `user_project_roles` ที่ครอบคลุมอยู่แล้ว
- ✅ **Data Seeding:** ข้อมูล Master (roles, permissions, organization\_roles, initial users, project parties) ถูกรวมอยู่ในสคริปต์สคีมาแล้ว
## 🧩 การปรับปรุงที่แนะนำ (สำหรับอนาคต) (Recommended Enhancements (Future))
- ✅ **(V2)** นำ Fulltext search หรือ Elasticsearch มาใช้กับฟิลด์เช่น `correspondence_revisions.title` หรือ `details`
- ✅ สร้าง Background job (โดยใช้ **n8n** เพื่อเชื่อมต่อกับ **Line** และ/หรือใช้สำหรับการแจ้งเตือน RFA ที่ใกล้ถึงกำหนด `due_date`)
- ✅ เพิ่ม job ล้างข้อมูลเป็นระยะสำหรับ `attachments` ที่ไม่ถูกเชื่อมโยงกับ Entity ใดๆ เลย (ไฟล์กำพร้า)
-----

201
infrastructure/Markdown/LCBP3-DMS V1_1_1_application _requirements.md Normal file
View File

@@ -0,0 +1,201 @@
# 📝 Documents Management Sytem Version 1.1.0: Application Requirements Specification
## 📌 1. วัตถุประสงค์
สร้างเว็บแอปพลิเคชั่นสำหรับระบบบริหารจัดการเอกสารโครงการ (Document Management System) ที่สามารถจัดการและควบคุม การสื่อสารด้วยเอกสารที่ซับซ้อน อย่างมีประสิทธิภาพ
* มีฟังก์ชันหลักในการอัปโหลด จัดเก็บ ค้นหา แชร์ และควบคุมสิทธิ์การเข้าถึงเอกสาร
* ช่วยลดการใช้เอกสารกระดาษ เพิ่มความปลอดภัยในการจัดเก็บข้อมูล
* เพิ่มความสะดวกในการทำงานร่วมกันระหว่างองกรณ์
## 🛠️ 2. สถาปัตยกรรมและเทคโนโลยี (System Architecture & Technology Stack)
ใช้สถาปัตยกรรมแบบ Headless/API-First ที่ทันสมัย ทำงานทั้งหมดบน QNAP Server ผ่าน Container Station เพื่อความสะดวกในการจัดการและบำรุงรักษา, Domain: np-dms.work, มี fix ip, รัน docker command ใน application ของ Container Station ได้โดยตรง, ประกอบด้วย
* 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 on Windows 11
- Domain: np-dms.work, www.np-dms.work
- ip: 159.192.126.103
- Docker Network: ทุก Service จะเชื่อมต่อผ่านเครือข่ายกลางชื่อ lcbp3 เพื่อให้สามารถสื่อสารกันได้
- Data Storage: /share/dms-data บน QNAP
- ข้อจำกัด: ไม่สามารถใช้ .env ในการกำหนดตัวแปรภายนอกได้ ต้องกำหนดใน docker-compose.yml เท่านั้น
* 2.2. Code Hosting:
- Application name: git
- Service: Gitea (Self-hosted on QNAP)
- Service name: gitea
- Domain: git.np-dms.work
- หน้าที่: เป็นศูนย์กลางในการเก็บและจัดการเวอร์ชันของโค้ด (Source Code) สำหรับทุกส่วน
* 2.3. Backend / Data Platform:
- Application name: lcbp3-backend
- Service: NestJS
- Service name: backend
- Domain: backend.np-dms.work
- Framework: NestJS (Node.js, TypeScript, ESM)
- หน้าที่: จัดการโครงสร้างข้อมูล (Data Models), สร้าง API, จัดการสิทธิ์ผู้ใช้ (Roles & Permissions), และสร้าง Workflow ทั้งหมดของระบบ
* 2.4. Database:
- Application name: lcbp3-db
- Service: mariadb:10.11
- Service name: mariadb
- Domain: db.np-dms.work
- หน้าที่: ฐานข้อมูลหลักสำหรับเก็บข้อมูลทั้งหมด
- Tooling: DBeaver (Community Edition), phpmyadmin สำหรับการออกแบบและจัดการฐานข้อมูล
* 2.5. Database management:
- Application name: lcbp3-db
- Service: phpmyadmin:5-apache
- Service name: pma
- Domain: pma.np-dms.work
- หน้าที่: จัดการฐานข้อมูล mariadb ผ่าน Web UI
* 2.6. Frontend:
- Application name: lcbp3-frontend
- Service: next.js
- 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
* 2.7. Workflow automation:
- Application name: lcbp3-n8n
- Service: n8nio/n8n:latest
- Service name: n8n
- Domain: n8n.np-dms.work
- หน้าที่: จัดการ workflow ระหว่าง Backend และ Line
* 2.8. Reverse Proxy:
- 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) ให้อัตโนมัติ
## 📦 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)
- 3.2.2. ประเภทเอกสาร: ระบบต้องรองรับเอกสารรูปแบบ ไฟล์ PDF หลายประเภท (Types) เช่น จดหมาย (Letter), อีเมล์ (Email), Request for Information (RFI), และสามารถเพิ่มประเภทใหม่ได้ในภายหลัง
- 3.2.3. การสร้างเอกสาร (Correspondence):
- ผู้ใช้ที่มีสิทธิ์ (เช่น Document Control) สามารถสร้างเอกสารรอไว้ในสถานะ ฉบับร่าง" (Draft) ได้ ซึ่งผู้ใช้งานต่างองค์กรจะมองไม่เห็น
- เมื่อกด "Submitted" แล้ว การแก้ไข, ถอนเอกสารกลับไปสถานะ Draft, หรือยกเลิก (Cancel) จะต้องทำโดยผู้ใช้ระดับ Admin ขึ้นไป พร้อมระบุเหตุผล
- 3.2.4. การอ้างอิงและจัดกลุ่ม:
- เอกสารสามารถอ้างถึง (Reference) เอกสารฉบับก่อนหน้าได้หลายฉบับ
- สามารถกำหนด Tag ได้หลาย Tag เพื่อจัดกลุ่มและใช้ในการค้นหาขั้นสูง
- 3.2.5. การจัดการ: มีการจัดการอย่างน้อยดังนี้
- สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบของ องกรณ์ ที่อเป็นผู้รับ ได้
- มีระบบแจ้งเตือน ให้ผู้รับผิดชอบขององกรณ์ที่เป็น ผู้รับ/ผู้ส่ง ทราบ เมื่อมีเอกสารใหม่ หรือมีการเปลี่ยนสถานะ
* 3.3. การจัดกาแบบคู่สัญญา (Contract Drawing)
- 3.3.1. วัตถุประสงค์: แบบคู่สัญญา (Contract Drawing) ใช้เพื่ออ้างอิงและใช้ในการตรวจสอบ
- 3.3.2. ประเภทเอกสาร: ไฟล์ PDF
- 3.3.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
- 3.3.4. การอ้างอิงและจัดกลุ่ม: ใช้สำหรับอ้างอิง ใน Shop Drawings, มีการจัดหมวดหมู่ของ Contract Drawing
* 3.4. การจัดกาแบบก่อสร้าง (Shop Drawing)
- 3.4.1. วัตถุประสงค์: แบบก่อสร้าง (Shop Drawing) ใช้เในการตรวจสอบ โดยจัดส่งด้วย Request for Approval (RFA)
- 3.4.2. ประเภทเอกสาร: ไฟล์ PDF
- 3.4.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
- 3.4.4. การอ้างอิงและจัดกลุ่ม: ช้สำหรับอ้างอิง ใน Shop Drawings, มีการจัดหมวดหมู่ของ Shop Drawings
* 3.5. การจัดการเอกสารขออนุมัติ (Request for Approval & Workflow)
- 3.5.1. วัตถุประสงค์: เอกสารขออนุมัติ (Request for Approval) ใช้ในการส่งเอกสารเพิอขออนุมัติ
- 3.5.2. ประเภทเอกสาร: Request for Approval (RFA) เป็นชนิดหนึ่งของ Correspondence ที่มีลักษณะเฉพาะที่ต้องได้รับการอนุมัติ มีประเภทดังนี้:
- Request for Drawing Approval (RFA\_DWG)
- Request for Document Approval (RFA\_DOC)
- Request for Method statement Approval (RFA\_MES)
- Request for Material Approval (RFA\_MAT)
- 3.5.2. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
- 3.5.4. การอ้างอิงและจัดกลุ่ม: การจัดการ Drawing (RFA\_DWG):
- เอกสาร RFA\_DWG จะประกอบไปด้วย Shop Drawing (shop\_drawings) หลายแผ่น ซึ่งแต่ละแผ่นมี Revision ของตัวเอง
- Shop Drawing แต่ละ Revision สามารถอ้างอิงถึง Contract Drawing (Ccontract\_drawings) หลายแผ่น หรือไม่อ้างถึงก็ได้
- ระบบต้องมีส่วนสำหรับจัดการข้อมูล Master Data ของทั้ง Shop Drawing และ Contract Drawing แยกจากกัน
- 3.6.5. Workflow การอนุมัติ: ต้องรองรับกระบวนการอนุมัติที่ซับซ้อนและเป็นลำดับ เช่น
- ส่งจาก Originator -\> Organization 1 -\> Organization 2 -\> Organization 3 แล้วส่งผลกลับตามลำดับเดิม (โดยถ้า องกรณ์ใดใน Workflow ให้ส่งกลับ ก็สามารถส่งผลกลับตามลำดับเดิมโดยไม่ต้องรอให้ถึง องกรณืในลำดับถัดไป)
- 3.6.6. การจัดการ: มีการจัดการอย่างน้อยดังนี้
- สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบของ องกรณ์ ที่อยู่ใน Workflow ได้
- มีระบบแจ้งเตือน ให้ผู้รับผิดชอบของ องกรณ์ ที่อยู่ใน Workflow ทราบ เมื่อมี RFA ใหม่ หรือมีการเปลี่ยนสถานะ
* 3.6.การจัดการเอกสารนำส่ง (Transmittals)
- 3.6.1. วัตถุประสงค์: เอกสารนำส่ง ใช้สำหรับ นำส่ง Request for Approval (RFAS) หลายฉบับ ไปยังองค์กรอื่น
- 3.6.2. ประเภทเอกสาร: ไฟล์ PDF
- 3.6.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
- 3.6.4. การอ้างอิงและจัดกลุ่ม: เอกสารนำส่ง เป็นส่วนหนึ่งใน Correspondence
* 3.7. ใบเวียนเอกสารภายใน (Internal Circulation Sheet)
- 3.7.1. วัตถุประสงค์: การสื่อสาร เอกสาร (Correspondence) ทุกฉบับ จะมีใบเวียนเอกสารเพื่อควบคุมและมอบหมายงานภายในองค์กร (สามารถดูและแก้ไขได้เฉพาะคนในองค์กร)
- 3.7.2. ประเภทเอกสาร: ไฟล์ PDF
- 3.7.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ในองค์กรนั้น สามารถสร้างและแก้ไขได้
- 3.7.4. การอ้างอิงและจัดกลุ่ม: การระบุผู้รับผิดชอบ:
- ผู้รับผิดชอบหลัก (Main): มีได้หลายคน
- ผู้ร่วมปฏิบัติงาน (Action): มีได้หลายคน
- ผู้ที่ต้องรับทราบ (Information): มีได้หลายคน
- 3.7.5. การติดตามงาน:
- สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบประเภท Main และ Action ได้
- มีระบบแจ้งเตือนเมื่อมี Circulation ใหม่ และแจ้งเตือนล่วงหน้าก่อนถึงวันแล้วเสร็จ
- สามารถปิด Circulation ได้เมื่อดำเนินการตอบกลับไปยังองค์กรผู้ส่ง (Originator) แล้ว หรือ รับทราบแล้ว (For Information)
* 3.8. ประวัติการแก้ไข (Revisions): ระบบจะเก็บประวัติการสร้างและแก้ไข เอกสารทั้งหมด
* **3.9. การจัดเก็บ: (ปรับปรุงตามสถาปัตยกรรมใหม่)**
- เอกสารและไฟล์แนบทั้งหมดจะถูกจัดเก็บในโฟลเดอร์บน Server (`/share/dms-data/`)
- ข้อมูล Metadata ของไฟล์ (เช่น ชื่อไฟล์, ขนาด, path) จะถูกเก็บในตาราง `attachments` (ตารางกลาง)
- ไฟล์จะถูกเชื่อมโยงกับเอกสารประเภทต่างๆ ผ่านตารางเชื่อม (Junction tables) เช่น `correspondence_attachments`, `circulation_attachments`, และ `shop_drawing_revision_attachments`
- สถาปัตยกรรมแบบรวมศูนย์นี้ *แทนที่* แนวคิดเดิมที่จะแยกโฟลเดอร์ตามประเภทเอกสาร เพื่อรองรับการขยายระบบที่ดีกว่า
## 🔐 4. ข้อกำหนดด้านสิทธิ์และการเข้าถึง (Access Control Requirements)
* 4.1. ภาพรวม: ผู้ใช้และองค์กรสามารถดูและแก้ไขเอกสารได้ตามสิทธิ์ที่ได้รับ โดยระบบสิทธิ์จะเป็นแบบ Role-Based Access Control (RBAC)
* 4.2. ระดับของสิทธิ์:
- Global Roles: สิทธิ์ในภาพรวมของระบบ
- Project-Specific Roles: สิทธิ์ที่ถูกกำหนดให้ผู้ใช้สำหรับโครงการนั้นๆ โดยเฉพาะ (เช่น เป็น Editor ในโครงการ A แต่เป็น Viewer ในโครงการ B)
- Contract-Specific Roles: สิทธิ์ที่ถูกกำหนดให้โครงการสำหรับสัญญานั้นๆ (เช่น เป็น Admin ในสัญญา 1 จะเป็น Admin ใน โครงการ A และ ฺB ที่อยู่ในสัญญา 1)
* 4.3. บทบาท (Roles) พื้นฐาน:
- Superadmin: ไม่มีข้อจำกัดใดๆ สามารถจัดการได้ทุกอย่างข้ามองค์กร
- Admin: มีสิทธิ์เต็มที่ แต่จำกัดเฉพาะในองค์กรที่ตัวเองสังกัด สามารถจัดการผู้ใช้ในองค์กรได้ สามารถสร้าง Role ใหม่และกำหนดสิทธิ์ (Permissions) เพิ่มเติมได้ในภายหลังผ่านหน้า Admin
- Document Control สามารถ เพิ่ม/แก้ไข/ลบ เอกสาร เฉพาะในองค์กรที่ตัวเองสังกัด ไม่สามารถจัดการผู้ใช้ได้
- Editor: สามารถ เพิ่ม/แก้ไข เอกสารที่กำหนดไว้ เฉพาะในองค์กรที่ตัวเองสังกัด
- Viewer: สามารถดู เอกสาร เฉพาะในองค์กรที่ตัวเองสังกัด
* 4.4. การบังคับใช้สิทธิ์: สิทธิ์ขององค์กรจะครอบคลุมสิทธิ์ของผู้ใช้ และการเข้าถึงข้อมูลที่เกี่ยวข้องกับโครงการ (เช่น การแก้ไขเอกสาร) จะถูกตรวจสอบเทียบกับสิทธิ์ที่ผู้ใช้มีในโครงการนั้นๆ โดยเฉพาะ
## 👥 5. ข้อกำหนดด้านผู้ใช้งาน (User Interface & Experience)
* 5.1. Layout หลัก: หน้าเว็บใช้รูปแบบ App Shell ที่ประกอบด้วย:
- Navbar (ส่วนบน): แสดงชื่อระบบ, เมนูผู้ใช้ (Profile), เมนูสำหรับ 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 ที่ผู้ใช้ต้องดำเนินการ
* 5.4. การติดตามสถานะ: องค์กรสามารถติดตามสถานะเอกสารทั้งของตนเอง (Originator) และสถานะเอกสารที่ส่งมาถึงตนเอง (Recipient)
* 5.5. การจัดการข้อมูลส่วนตัว (Profile Page): ผู้ใช้สามารถจัดการข้อมูลส่วนตัวและเปลี่ยนรหัสผ่านของตนเองได้
* 5.6. การจัดการเอกสารทางเทคนิค (Technical Documents & Workflow): ผู้ใช้สามารถดู Technical Document ในรูปแบบ Workflow ทั้งหมดได้ในหน้าเดียว, ขั้นตอนที่ยังไม่ถึงหรือผ่านไปแล้วจะเป็นรูปแบบ diable, สามารถดำเนินการได้เฉพาะในขั้นตอนที่ได้รับมอบหมายงาน (active) เช่น ตรวจสอบแล้ว เพื่อไปยังขั้นตอนต่อไป, สิทธิ์ admin ขึ้นไป สามรถกด ไปยังขั้นตอนต่อไป ได้ทุกขั้นตอน, การย้อนกลับ ไปขั้นตอนก่อนหน้า สามารถทำได้โดย สิทธิ์ admin ขึ้นไป
## 6\. ข้อกำหนดที่ไม่ใช่ฟังก์ชันการทำงาน (Non-Functional Requirements)
* 6.1. การบันทึกการกระทำ (Audit Log): ทุกการกระทำที่สำคัญของผู้ใช้ (สร้าง, แก้ไข, ลบ, ส่ง) จะถูกบันทึกไว้ใน `audit_logs` เพื่อการตรวจสอบย้อนหลัง
* 6.2. การค้นหา (Search): ระบบต้องมีฟังก์ชันการค้นหาขั้นสูง ที่สามารถค้นหาเอกสารจากหลายเงื่อนไขพร้อมกันได้ เช่น ค้นหาจากชื่อเรื่อง, ประเภท, วันที่, และ Tag
* 6.3. การทำรายงาน (Reporting): สามารถจัดทำรายงานสรุปแยกประเภทของ Correspondence ประจำวัน, สัปดาห์, เดือน, และปีได้
* 6.4. ประสิทธิภาพ (Performance): มีการใช้ Caching กับข้อมูลที่เรียกใช้บ่อย และใช้ Pagination ในตารางข้อมูลเพื่อจัดการข้อมูลจำนวนมาก
* 6.5. ความปลอดภัย (Security):
- มีระบบ Rate Limiting เพื่อป้องกันการโจมตีแบบ Brute-force
- การจัดการ Secret (เช่น รหัสผ่าน DB, JWT Secret) จะต้องทำผ่าน Environment Variable ของ Docker เพื่อความปลอดภัยสูงสุด

234
infrastructure/Markdown/LCBP3-DMS — Task Breakdown สำหรับ Phase 2A–2C (v1.4.2).md Normal file
View File

@@ -0,0 +1,234 @@
# LCBP3-DMS — Task Breakdown สำหรับ Phase 2A–2C (v1.4.2)
เอกสารนี้เป็นรายละเอียด Task Breakdown เชิงลึกของ Phase 2A, 2B, 2C ที่ถูกแยกออกตามสถาปัตยกรรม v1.4.2
โครงสร้างประกอบด้วย:
* Objectives
* Deliverables
* Task Breakdown (ละเอียดเป็นลำดับงาน)
* Developer Checklist
* Test Coverage
* Dependencies & Risks
---
# 🟦 Phase 2A — Security Layer
**Objective:** วาง Security Foundation ให้ระบบทั้งหมดใช้ร่วมกัน: Validation Pipeline, Security Headers, Rate Limiting, Request Guards
## ✔ Deliverables
* Global ValidationPipe
* Sanitization Layer
* Rate Limit Rules (anonymous/authenticated)
* Security Headers (Helmet)
* XSS / SQL Injection safeguards
* Security Tests
## 🛠 Task Breakdown
### 2A.1 Validation Pipeline
* ตั้งค่า Global ValidationPipe
* เปิด whitelist, forbidNonWhitelisted
* เพิ่ม custom exception mapping → ErrorModel
* เชื่อม RequestIdInterceptor
### 2A.2 Input Sanitization Layer
* ติดตั้ง sanitize-html หรือ DOMPurify server-side
* เพิ่ม sanitization middleware สำหรับ:
* query params
* body JSON
* form inputs
* เพิ่ม unit test: sanitized input → safe output
### 2A.3 Security Headers (Helmet)
* เปิดใช้งาน Helmet ทั้งระบบ
* ปรับ policy: `contentSecurityPolicy`, `xssFilter`, `noSniff`
* เพิ่ม config per environment
### 2A.4 Rate Limiting
* Rate limit แบบ 2 ชั้น:
* anonymous (เช่น 30 req/min)
* authenticated (100 req/min)
* สร้าง Redis key pattern: `ratelimit:{ip}`
* สร้าง RateLimitGuard + decorator
* ทดสอบ burst traffic (locust หรือ autocannon)
### 2A.5 SQL Injection / XSS Protection
* เปิด TypeORM parameterized queries
* Sanitizer ตรวจจับ script tags
* เขียน test ที่ inject payload จำลอง
### 2A.6 Logging + Error Model Integration
* ผูก SecurityException → Error Model
* เพิ่ม request_id logging
## ✔ Developer Checklist (Phase 2A)
* [ ] ทุก controller มี ValidationPipe ครอบ
* [ ] Sanitization ทำงานในทุก input source
* [ ] Error ทั้งหมดออกตาม Error Model กลาง
* [ ] RateLimitGuard ทำงานผ่าน Redis
* [ ] มี security test อย่างน้อย 10 ชุด
## ✔ Test Coverage (Phase 2A)
* Input injection tests
* Rate limit tests
* Validation rejects undefined fields
* ErrorModel mapping
---
# 🟪 Phase 2B — JSON Schema System
**Objective:** จัดการ JSON Schema แบบ versioned, ตรวจสอบ payload, บังคับใช้ format ก่อนเก็บ DB
## ✔ Deliverables
* Schema Registry
* Schema Versioning
* Schema Validation Service
* Compatibility Rules
* Schema Migration Tests
## 🛠 Task Breakdown
### 2B.1 Schema Registry
* Entity: `json_schemas`, `json_schema_versions`
* Endpoint: `POST /json-schemas`
* ฟิลด์สำคัญ: schema_id, version, schema_json
* สร้าง SchemaStore class
### 2B.2 Schema Versioning
* Version rule: semantic versioning (major.minor.patch)
* Migration notes per version
* นโยบาย: Breaking change → major bump
* API: `GET /json-schemas/:id?version=`
### 2B.3 Schema Validation Service
* ใช้ AJV หรือ Fastest-Validator
* preload schema เมื่อ boot server
* mapping validation error → Error Model
* เพิ่ม test: invalid schema / missing fields / wrong types
### 2B.4 Compatibility Rules
* ตรวจสอบ backward compatibility:
* field removal → major version
* enum shrink → major version
* เพิ่ม script ตรวจ schema diff
### 2B.5 Schema Migration Tests
* ทดสอบ schema upgrade (v1 → v2)
* ทดสอบ payload ที่ใช้ version เก่า
## ✔ Developer Checklist (Phase 2B)
* [ ] ทุก JSON field อ้างอิง schema version
* [ ] ทุก schema ผ่าน validation
* [ ] Schema diff pass
* [ ] Schema test ครอบครบทุก field
## ✔ Test Coverage (Phase 2B)
* Schema version switch tests
* Incompatible payload rejection
* Schema registry CRUD
---
# 🟧 Phase 2C — JSON Processing
**Objective:** จัดการ JSON payload: sanitization, compression, encryption, size limits
## ✔ Deliverables
* JSON size validator
* JSON sanitizer
* JSON compressor (gzip/deflate)
* Sensitive fields encryption
* JSON transformation layer
## 🛠 Task Breakdown
### 2C.1 JSON Size Controls
* ตั้ง global limit (เช่น 2MB ต่อฟิลด์)
* เพิ่ม JSONSizeGuard
* เขียน test: oversize JSON → error_code: `JSON.TOO_LARGE`
### 2C.2 JSON Sanitization (ลึกกว่า Phase 2A)
* ล้าง nested fields
* ล้าง `<script>`, `<iframe>`, inline JS
* รองรับ JSON array sanitization
### 2C.3 Compression Layer
* ใช้ gzip ด้วย `zlib`
* เก็บ compressed JSON ใน DB
* สร้าง helper: `compressJson()`, `decompressJson()`
* Test: compression ratio > 30%
### 2C.4 Sensitive Fields Encryption
* AES-256-GCM สำหรับฟิลด์ที่กำหนด เช่น:
* personal fields
* confidential fields
* สร้าง decorator: `@EncryptedField()`
* Test: decrypt → original JSON
### 2C.5 JSON Transformation Layer
* Map JSON fields → internal format
* ใช้กับ Correspondence / RFA
* รองรับ schema version migration (เชื่อมกับ Phase 2B)
## ✔ Developer Checklist (Phase 2C)
* [ ] JSON size guard ครอบทุก endpoint
* [ ] Compression + encryption ทำงานก่อน persist
* [ ] Sanitizer ผ่าน nested objects
* [ ] Transform layer มี test ครบ
## ✔ Test Coverage (Phase 2C)
* Oversize JSON tests
* Encryption/decryption tests
* Compression tests
* Schema-versioned transformation tests
---
# 🔗 Dependencies
* Phase 2A → จำเป็นก่อน 2B, 2C
* Phase 2B → ต้องเสร็จเพื่อให้ 2C ทำ transformation
---
# ⚠ Risks
* Schema versioning อาจกระทบ payload เดิม → ต้องมี migration plan
* Compression/encryption ทำให้ debug ยาก → ต้องพึ่ง request_id + audit logs
* Rate limiting ไม่เหมาะสมอาจ block ผู้ใช้จริง
---
เอกสารนี้พร้อมใช้วางแผน Sprint สำหรับทีมพัฒนา หรือสร้าง Gantt Chart ต่อได้ทันที

55
infrastructure/Markdown/LCBP3-DMS_V1_1_0_application _database.md Normal file
View File

@@ -0,0 +1,55 @@
# Documents Management Sytem Version 1.1.0: Application Databases Specification
## 1. วัตถุประสงค์
## 2. สถาปัตยกรรมและเทคโนโลยี (System Architecture & Technology Stack)
correspondences ตารางเอกสารโต้ตอบ
-- 2.7.5 : n.n.5 for shop_drawing
shop_drawings;
-- 2.6.6 : n.n.6 for contract_drawing
contract_drawings;
-- 2.5.2 : n.n.2 for rfa
rfas;
-- 2.4.4 : n.n.4 for transmittal
transmittals;
-- 2.3.3: n.n.3 for circulation
circulations;
users;
-- 4.7
projects ตารางโครงการ
-- 4.6
contracts ตารางสัญญา
-- 4.2
permissions;
-- 4.1
roles;
-- Level 5: ตารางที่เป็นรากฐานที่สุด
-- 5.2
organizations ตารางองกรณ์;
-- 5.1
organization_roles;
-- 1.2
attachments;
-- 1.1
global_default_roles;
audit_logs;
ใช้สถาปัตยกรรมแบบ Headless/API-First ที่ทันสมัย ทำงานทั้งหมดบน QNAP Server ผ่าน Container Station เพื่อความสะดวกในการจัดการและบำรุงรักษา, Domain: np-dms.work, มี fix ip, รัน docker command ใน application ของ Container Station ได้โดยตรง, ประกอบด้วย
* 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 on Windows 11
- Domain: np-dms.work, www.np-dms.work
- ip: 159.192.126.103
- Docker Network: ทุก Service จะเชื่อมต่อผ่านเครือข่ายกลางชื่อ lcbp3 เพื่อให้สามารถสื่อสารกันได้
- Data Storage: /share/dms-data บน QNAP
- ข้อจำกัด: ไม่สามารถใช้ .env ในการกำหนดตัวแปรภายนอกได้ ต้องกำหนดใน docker-compose.yml เท่านั้น
*

682
infrastructure/Markdown/LCBP3-DMS_V1_2_0_Data_Dictionary.ิbak Normal file
View File

@@ -0,0 +1,682 @@
# **สรุปตารางฐานข้อมูล (Data Dictionary) \- LCBP3-DMS**
เอกสารนี้สรุปโครงสร้างตาราง, Foreign Keys (FK), และ Constraints ที่สำคัญทั้งหมดในฐานข้อมูล LCBP3-DMS (v1.1.1) เพื่อใช้เป็นเอกสารอ้างอิงสำหรับทีมพัฒนา Backend (NestJS) และ Frontend (Next.js)
## **1\. 🏢 Core & Master Data (องค์กร, โครงการ, สัญญา)**
#### **1.1. organization\_roles**
ตาราง Master เก็บประเภทบทบาทขององค์กร (เช่น OWNER, CONTRACTOR)
| Column | Type | Key | Description |
| :---- | :---- | :---- | :---- |
| id | INT | **PK** | ID ของตาราง |
| role\_name | VARCHAR(20) | UK | ชื่อบทบาท (OWNER, DESIGNER, CONSULTANT, CONTRACTOR, THIRD PARTY) |
* **Unique Keys (UK):** ux\_roles\_name (role\_name)
#### **1.2. organizations**
ตาราง Master เก็บข้อมูลองค์กรทั้งหมดที่เกี่ยวข้องในระบบ
| Column | Type | Key | Description |
| :---- | :---- | :---- | :---- |
| id | INT | **PK** | ID ของตาราง |
| organization\_code | VARCHAR(20) | UK | รหัสองค์กร |
| organization\_name | VARCHAR(255) | | ชื่อองค์กร |
| role\_id | INT | FK | บทบาทขององค์กร (FK \-\> organization\_roles(id)) |
| is\_active | BOOLEAN | | สถานะการใช้งาน |
* **Foreign Keys (FK):**
* role\_id \-\> organization\_roles(id) (ON DELETE SET NULL)
* **Unique Keys (UK):** ux\_organizations\_code (organization\_code)
#### **1.3. projects**
ตาราง Master เก็บข้อมูลโครงการ (เช่น LCBP3C1, LCBP3C2)
| Column | Type | Key | Description |
| :---- | :---- | :---- | :---- |
| id | INT | **PK** | ID ของตาราง |
| project\_code | VARCHAR(50) | UK | รหัสโครงการ |
| project\_name | VARCHAR(255) | | ชื่อโครงการ |
| parent\_project\_id | INT | FK | รหัสโครงการหลัก (ถ้ามี) (FK \-\> projects(id)) |
| contractor\_organization\_id | INT | FK | รหัสองค์กรผู้รับเหมา (ถ้ามี) (FK \-\> organizations(id)) |
| is\_active | TINYINT(1) | | สถานะการใช้งาน |
* **Foreign Keys (FK):**
* parent\_project\_id \-\> projects(id) (ON DELETE SET NULL)
* contractor\_organization\_id \-\> organizations(id) (ON DELETE SET NULL)
* **Unique Keys (UK):** uq\_pro\_code (project\_code)
#### **1.4. contracts**
ตาราง Master เก็บข้อมูลสัญญา
| Column | Type | Key | Description |
| :---- | :---- | :---- | :---- |
| id | INT | **PK** | ID ของตาราง |
| contract\_code | VARCHAR(50) | UK | รหัสสัญญา |
| contract\_name | VARCHAR(255) | | ชื่อสัญญา |
| description | TEXT | | คำอธิบายสัญญา |
* **Unique Keys (UK):** ux\_contracts\_code (contract\_code)
#### **1.5. project\_parties (ตารางเชื่อม)**
ตารางเชื่อมความสัมพันธ์ระหว่าง โครงการ, องค์กร, และบทบาท (M:N)
| Column | Type | Key | Description |
| :---- | :---- | :---- | :---- |
| project\_id | INT | **PK**, FK | ID ของโครงการ (FK \-\> projects(id)) |
| organization\_id | INT | **PK**, FK | ID ขององค์กร (FK \-\> organizations(id)) |
| role | ENUM(...) | **PK** | บทบาทในโครงการ (OWNER, DESIGNER, CONSULTANT, CONTRACTOR, THIRD\_PARTY) |
| is\_contractor | TINYINT(1) | UK | (Generated) \= 1 ถ้า role \= 'CONTRACTOR' |
* **Foreign Keys (FK):**
* project\_id \-\> projects(id) (ON DELETE CASCADE)
* organization\_id \-\> organizations(id) (ON DELETE RESTRICT)
* **Unique Keys (UK):**
* uq\_project\_parties\_contractor (project\_id, is\_contractor) \- **(Constraint สำคัญ)** บังคับว่า 1 โครงการมี CONTRACTOR ได้เพียง 1 องค์กร (ตาม Req 3.1.3)
#### **1.6. contract\_parties (ตารางเชื่อม)**
ตารางเชื่อมความสัมพันธ์ระหว่าง สัญญา, โครงการ, และองค์กร (M:N)
| Column | Type | Key | Description |
| :---- | :---- | :---- | :---- |
| contract\_id | INT | **PK**, FK | ID ของสัญญา (FK \-\> contracts(id)) |
| project\_id | INT | **PK**, FK | ID ของโครงการ (FK \-\> projects(id)) |
| organization\_id | INT | **PK**, FK | ID ขององค์กร (FK \-\> organizations(id)) |
* **Foreign Keys (FK):**
* contract\_id \-\> contracts(id) (ON DELETE CASCADE)
* project\_id \-\> projects(id) (ON DELETE CASCADE)
* organization\_id \-\> organizations(id) (ON DELETE CASCADE)
## **2\. 👥 Users & RBAC (ผู้ใช้, สิทธิ์, บทบาท)**
#### **2.1. users**
ตาราง Master เก็บข้อมูลผู้ใช้งาน (User)
| Column | Type | Key | Description |
| :---- | :---- | :---- | :---- |
| user\_id | INT | **PK** | ID ของตาราง |
| username | VARCHAR(50) | UK | ชื่อผู้ใช้งาน |
| password\_hash | VARCHAR(255) | | รหัสผ่าน (Hashed) |
| first\_name | VARCHAR(50) | | ชื่อจริง |
| last\_name | VARCHAR(50) | | นามสกุล |
| email | VARCHAR(100) | UK | อีเมล |
| organization\_id | INT | FK | สังกัดองค์กร (FK \-\> organizations(id)) |
| is\_active | TINYINT(1) | | สถานะการใช้งาน |
* **Foreign Keys (FK):**
* organization\_id \-\> organizations(id) (ON DELETE SET NULL)
* **Unique Keys (UK):** ux\_users\_username (username), ux\_users\_email (email)
#### **2.2. roles**
ตาราง Master เก็บ "บทบาท" ของผู้ใช้ในระบบ (เช่น SUPER\_ADMIN, ADMIN, EDITOR)
| Column | Type | Key | Description |
| :---- | :---- | :---- | :---- |
| role\_id | INT | **PK** | ID ของตาราง |
| role\_code | VARCHAR(50) | UK | รหัสบทบาท (เช่น SUPER\_ADMIN, ADMIN, EDITOR, VIEWER) |
| role\_name | VARCHAR(100) | | ชื่อบทบาท |
| is\_system | BOOLEAN | | (1 \= บทบาทของระบบ ลบไม่ได้) |
* **Unique Keys (UK):** role\_code
#### **2.3. permissions**
ตาราง Master เก็บ "สิทธิ์" (Permission) หรือ "การกระทำ" ทั้งหมดในระบบ
| Column | Type | Key | Description |
| :---- | :---- | :---- | :---- |
| permission\_id | INT | **PK** | ID ของตาราง |
| permission\_code | VARCHAR(100) | UK | รหัสสิทธิ์ (เช่น rfas.create, rfas.view) |
| module | VARCHAR(50) | | โมดูลที่เกี่ยวข้อง |
| scope\_level | ENUM(...) | | ระดับของสิทธิ์ (GLOBAL, ORG, PROJECT) |
* **Unique Keys (UK):** ux\_permissions\_code (permission\_code)
#### **2.4. role\_permissions (ตารางเชื่อม)**
ตารางเชื่อมระหว่าง roles และ permissions (M:N)
| Column | Type | Key | Description |
| :---- | :---- | :---- | :---- |
| role\_id | INT | **PK**, FK | ID ของบทบาท (FK \-\> roles(role\_id)) |
| permission\_id | INT | **PK**, FK | ID ของสิทธิ์ (FK \-\> permissions(permission\_id)) |
* **Foreign Keys (FK):**
* role\_id \-\> roles(role\_id) (ON DELETE CASCADE)
* permission\_id \-\> permissions(permission\_id) (ON DELETE CASCADE)
#### **2.5. user\_roles (ตารางเชื่อม)**
ตารางเชื่อมผู้ใช้ (users) กับบทบาท (roles) ในระดับ **Global** (M:N)
| Column | Type | Key | Description |
| :---- | :---- | :---- | :---- |
| user\_id | INT | **PK**, FK | ID ของผู้ใช้ (FK \-\> users(user\_id)) |
| role\_id | INT | **PK**, FK | ID ของบทบาท (FK \-\> roles(role\_id)) |
* **Foreign Keys (FK):**
* user\_id \-\> users(user\_id) (ON DELETE CASCADE)
* role\_id \-\> roles(role\_id) (ON DELETE CASCADE)
#### **2.6. user\_project\_roles (ตารางเชื่อม)**
ตารางเชื่อมผู้ใช้ (users) กับบทบาท (roles) ในระดับ **Project-Specific** (M:N) (Req 4.2)
| Column | Type | Key | Description |
| :---- | :---- | :---- | :---- |
| user\_id | INT | **PK**, FK | ID ของผู้ใช้ (FK \-\> users(user\_id)) |
| project\_id | INT | **PK**, FK | ID ของโครงการ (FK \-\> projects(id)) |
| role\_id | INT | **PK**, FK | ID ของบทบาท (FK \-\> roles(role\_id)) |
* **Foreign Keys (FK):**
* user\_id \-\> users(user\_id) (ON DELETE CASCADE)
* project\_id \-\> projects(id) (ON DELETE CASCADE)
* role\_id \-\> roles(role\_id) (ON DELETE CASCADE)
## **3\. ✉️ Correspondences (เอกสารหลัก, Revisions)**
#### **3.1. correspondence\_types**
ตาราง Master เก็บประเภทเอกสารโต้ตอบ (เช่น RFA, RFI, LETTER, MOM)
| Column | Type | Key | Description |
| :---- | :---- | :---- | :---- |
| id | INT | **PK** | ID ของตาราง |
| type\_code | VARCHAR(50) | UK | รหัสประเภท (เช่น RFA, RFI) |
| type\_name | VARCHAR(255) | | ชื่อประเภท |
* **Unique Keys (UK):** type\_code
#### **3.2. correspondence\_status**
ตาราง Master เก็บสถานะของเอกสาร (เช่น DRAFT, SUBMITTED, CLOSED)
| Column | Type | Key | Description |
| :---- | :---- | :---- | :---- |
| id | INT | **PK** | ID ของตาราง |
| status\_code | VARCHAR(50) | UK | รหัสสถานะ (เช่น DRAFT, SUBOWN) |
| status\_name | VARCHAR(255) | | ชื่อสถานะ |
* **Unique Keys (UK):** status\_code
#### **3.3. correspondences (Master)**
ตาราง "แม่" ของเอกสารโต้ตอบ เก็บข้อมูลที่ไม่เปลี่ยนแปลงตาม Revision (เช่น เลขที่เอกสาร)
| Column | Type | Key | Description |
| :---- | :---- | :---- | :---- |
| id | INT | **PK** | ID ของตาราง (นี่คือ "Master ID" ที่ใช้เชื่อมโยง) |
| correspondence\_number | VARCHAR(100) | UK | เลขที่เอกสาร (สร้างจาก DocumentNumberingModule) |
| correspondence\_type\_id | INT | FK | ประเภทเอกสาร (FK \-\> correspondence\_types(id)) |
| is\_internal\_communication | TINYINT(1) | | (1 \= ภายใน, 0 \= ภายนอก) |
| project\_id | INT | FK | อยู่ในโครงการ (FK \-\> projects(id)) |
| originator\_id | INT | FK | องค์กรผู้ส่ง (FK \-\> organizations(id)) |
| recipient\_id | INT | FK | องค์กรผู้รับ (FK \-\> organizations(id)) |
| created\_by | INT | FK | ผู้สร้าง (FK \-\> users(user\_id)) |
| deleted\_at | DATETIME | | สำหรับ Soft Delete |
* **Foreign Keys (FK):**
* correspondence\_type\_id \-\> correspondence\_types(id) (ON DELETE RESTRICT)
* project\_id \-\> projects(id) (ON DELETE CASCADE)
* originator\_id \-\> organizations(id) (ON DELETE SET NULL)
* recipient\_id \-\> organizations(id) (ON DELETE SET NULL)
* created\_by \-\> users(user\_id) (ON DELETE SET NULL)
* **Unique Keys (UK):** uq\_corr\_no\_per\_project (project\_id, correspondence\_number)
#### **3.4. correspondence\_revisions (Revisions)**
ตาราง "ลูก" เก็บประวัติการแก้ไข (Revisions) ของ correspondences (1:N) **(ปรับปรุง)** id เป็น PK ใหม่ เพื่อรองรับ 1:N
| Column | Type | Key | Description |
| :---- | :---- | :---- | :---- |
| id | INT | **PK** | **ID ของ Revision** |
| correspondence\_id | INT | FK, UK | Master ID (FK \-\> correspondences(id)) |
| revision\_number | INT | UK | หมายเลข Revision (0, 1, 2...) |
| revision\_label | VARCHAR(10) | | Revision ที่แสดง (เช่น A, B, 1.1) |
| is\_current | BOOLEAN | UK | (1 \= Revision ปัจจุบัน) |
| correspondence\_status\_id | INT | FK | สถานะของ Revision นี้ (FK \-\> correspondence\_status(id)) |
| title | VARCHAR(255) | | เรื่อง |
| document\_date | DATE | | วันที่ในเอกสาร |
| issued\_date | DATETIME | | วันที่ออกเอกสาร |
| received\_date | DATETIME | | วันที่ลงรับ |
| due\_date | DATETIME | | **(ไม่สอดคล้องกับ Req 3.2.5)** วันที่ครบกำหนด (ควรย้ายไป correspondence\_recipients) |
| details | JSON | | ข้อมูลเฉพาะ (เช่น RFI details) |
| created\_by | INT | FK | ผู้สร้าง (FK \-\> users(user\_id)) |
* **Foreign Keys (FK):**
* correspondence\_id \-\> correspondences(id) (ON DELETE CASCADE)
* correspondence\_status\_id \-\> correspondence\_status(id) (ON DELETE RESTRICT)
* created\_by \-\> users(user\_id) (ON DELETE SET NULL)
* **Unique Keys (UK):**
* uq\_master\_revision\_number (correspondence\_id, revision\_number) (ป้องกัน Rev ซ้ำใน Master เดียว)
* uq\_master\_current (correspondence\_id, is\_current) (ป้องกันการมี is\_current \= TRUE ซ้ำใน Master เดียว)
* **Check Constraints (CHK):** chk\_rev\_format (ตรวจสอบรูปแบบ revision\_label)
#### **3.5. correspondence\_recipients (ตารางเชื่อม)**
ตารางเชื่อมผู้รับ (TO/CC) สำหรับเอกสารแต่ละฉบับ (M:N)
| Column | Type | Key | Description |
| :---- | :---- | :---- | :---- |
| correspondence\_id | INT | **PK**, FK | ID ของเอกสาร (FK \-\> correspondence\_revisions(correspondence\_id)) |
| recipient\_organization\_id | INT | **PK**, FK | ID องค์กรผู้รับ (FK \-\> organizations(id)) |
| recipient\_type | ENUM('TO', 'CC') | **PK** | ประเภทผู้รับ (TO หรือ CC) |
* **Foreign Keys (FK):**
* correspondence\_id \-\> correspondence\_revisions(correspondence\_id) (ON DELETE CASCADE)
* recipient\_organization\_id \-\> organizations(id) (ON DELETE RESTRICT)
#### **3.6. correspondence\_references (ตารางเชื่อม)**
ตารางเชื่อมการอ้างอิงระหว่างเอกสาร (M:N) (Req 3.2.4)
| Column | Type | Key | Description |
| :---- | :---- | :---- | :---- |
| src\_correspondence\_id | INT | **PK**, FK | ID เอกสารต้นทาง (FK \-\> correspondences(id)) |
| tgt\_correspondence\_id | INT | **PK**, FK | ID เอกสารเป้าหมาย (FK \-\> correspondences(id)) |
* **Foreign Keys (FK):**
* src\_correspondence\_id \-\> correspondences(id) (ON DELETE CASCADE)
* tgt\_correspondence\_id \-\> correspondences(id) (ON DELETE CASCADE)
#### **3.7. correspondence\_routing\_templates / ...\_steps / ...\_routings**
ตารางที่เกี่ยวข้องกับ Workflow การส่งต่อเอกสาร (Req 3.5.4)
* **correspondence\_routing\_templates:** ตาราง Master เก็บแม่แบบสายงาน (เช่น "ส่งให้ CSC ตรวจสอบ")
* **correspondence\_routing\_template\_steps:** ตารางลูก เก็บขั้นตอนในแม่แบบ (เช่น Step 1: ส่งไป Org A, Step 2: ส่งไป Org B)
* **correspondence\_routings:** ตารางประวัติ (Log) การส่งต่อของเอกสารจริงตาม Workflow
## **4\. approval: RFA (เอกสารขออนุมัติ, Workflows)**
#### **4.1. rfa\_types / ...\_status\_codes / ...\_approve\_codes**
ตาราง Master สำหรับ RFA
* **rfa\_types:** ประเภท RFA (เช่น DWG, DOC, MAT) (Req 3.5.2)
* **rfa\_status\_codes:** สถานะ RFA (เช่น DFT \- Draft, FAP \- For Approve)
* **rfa\_approve\_codes:** รหัสผลการอนุมัติ (เช่น 1A \- Approved, 3R \- Revise and Resubmit)
#### **4.2. rfas (Master)**
ตาราง "แม่" ของ RFA (มีความสัมพันธ์ 1:N กับ rfa\_revisions)
| Column | Type | Key | Description |
| :---- | :---- | :---- | :---- |
| id | INT | **PK** | ID ของตาราง (RFA Master ID) |
| rfa\_type\_id | INT | FK | ประเภท RFA (FK \-\> rfa\_types(id)) |
| revision\_number | INT | | หมายเลข Revision ล่าสุด (ควรย้ายไป rfa\_revisions) |
| created\_by | INT | FK | ผู้สร้าง (FK \-\> users(user\_id)) |
| deleted\_at | DATETIME | | สำหรับ Soft Delete |
* **Foreign Keys (FK):**
* rfa\_type\_id \-\> rfa\_types(id)
* created\_by \-\> users(user\_id) (ON DELETE SET NULL)
#### **4.3. rfa\_revisions (Revisions)**
ตาราง "ลูก" เก็บประวัติ (Revisions) ของ rfas (1:N) **(ปรับปรุง)** id เป็น PK ใหม่ เพื่อรองรับ 1:N
| Column | Type | Key | Description |
| :---- | :---- | :---- | :---- |
| id | INT | **PK** | **ID ของ Revision** |
| correspondence\_id | INT | FK | Master ID ของ Correspondence (FK \-\> correspondences(id)) |
| rfa\_id | INT | FK, UK | Master ID ของ RFA (FK \-\> rfas(id)) |
| revision\_number | INT | UK | หมายเลข Revision (0, 1, 2...) |
| is\_current | BOOLEAN | UK | (1 \= Revision ปัจจุบัน) |
| rfa\_status\_code\_id | INT | FK | สถานะ RFA (FK \-\> rfa\_status\_codes(id)) |
| rfa\_approve\_code\_id | INT | FK | ผลการอนุมัติ (FK \-\> rfa\_approve\_codes(id)) |
| title | VARCHAR(255) | | เรื่อง |
| due\_date | DATETIME | | **(ไม่สอดคล้องกับ Req 3.6.6)** วันที่ครบกำหนด (ควรย้ายไป rfa\_workflows) |
| created\_by | INT | FK | ผู้สร้าง (FK \-\> users(user\_id)) |
* **Foreign Keys (FK):**
* correspondence\_id \-\> correspondences(id) (ON DELETE CASCADE)
* rfa\_id \-\> rfas(id) (ON DELETE CASCADE)
* rfa\_status\_code\_id \-\> rfa\_status\_codes(id)
* rfa\_approve\_code\_id \-\> rfa\_approve\_codes(id) (ON DELETE SET NULL)
* created\_by \-\> users(user\_id) (ON DELETE SET NULL)
* **Unique Keys (UK):**
* uq\_rr\_rev\_number (rfa\_id, revision\_number) (ป้องกัน Rev ซ้ำใน Master เดียว)
* uq\_rr\_current (rfa\_id, is\_current) (ป้องกัน is\_current=TRUE ซ้ำใน Master เดียว)
#### **4.4. rfa\_items (ตารางเชื่อม)**
ตารางเชื่อมระหว่าง rfa\_revisions (ที่เป็นประเภท DWG) กับ shop\_drawing\_revisions (M:N) (Req 3.5.4)
| Column | Type | Key | Description |
| :---- | :---- | :---- | :---- |
| rfarev\_correspondence\_id | INT | **PK**, FK | ID ของ RFA Revision (FK \-\> rfa\_revisions(correspondence\_id)) |
| shop\_drawing\_revision\_id | INT | **PK**, UK, FK | ID ของ Shop Drawing Revision (FK \-\> shop\_drawing\_revisions(id)) |
* **Foreign Keys (FK):**
* rfarev\_correspondence\_id \-\> rfa\_revisions(correspondence\_id) (ON DELETE CASCADE)
* shop\_drawing\_revision\_id \-\> shop\_drawing\_revisions(id) (ON DELETE CASCADE)
#### **4.5. rfa\_workflow\_templates / ...\_steps / ...\_workflows**
ตารางที่เกี่ยวข้องกับ Workflow การอนุมัติ RFA (Req 3.6.5)
* **rfa\_workflow\_templates:** ตาราง Master เก็บแม่แบบสายอนุมัติ (เช่น "สายอนุมัติ 3 ขั้นตอน")
* **rfa\_workflow\_template\_steps:** ตารางลูก เก็บขั้นตอนในแม่แบบ (เช่น Step 1: Org A (Review), Step 2: Org B (Approve))
* **rfa\_workflows:** ตารางประวัติ (Log) การอนุมัติของ RFA จริงตามสายงาน
## **5\. 📐 Drawings (แบบ, หมวดหมู่)**
#### **5.1. contract\_drawing\_volumes / ...\_cats / ...\_sub\_cats / ...\_subcat\_cat\_maps**
ตาราง Master สำหรับ "แบบคู่สัญญา" (Contract Drawings) (Req 3.3)
* **contract\_drawing\_volumes:** เก็บ "เล่ม" ของแบบ
* **contract\_drawing\_cats:** เก็บ "หมวดหมู่หลัก" ของแบบ
* **contract\_drawing\_sub\_cats:** เก็บ "หมวดหมู่ย่อย" ของแบบ
* **contract\_drawing\_subcat\_cat\_maps:** ตารางเชื่อมระหว่าง หมวดหมู่หลัก-ย่อย (M:N)
#### **5.2. contract\_drawings (Master)**
ตาราง Master เก็บข้อมูล "แบบคู่สัญญา" (Req 3.3.4)
| Column | Type | Key | Description |
| :---- | :---- | :---- | :---- |
| id | INT | **PK** | ID ของตาราง |
| project\_id | INT | FK, UK | โครงการ (FK \-\> projects(id)) |
| condwg\_no | VARCHAR(255) | UK | เลขที่แบบสัญญา |
| title | VARCHAR(255) | | ชื่อแบบ |
| sub\_cat\_id | INT | FK | หมวดหมู่ย่อย (FK \-\> contract\_drawing\_sub\_cats(id)) |
| volume\_id | INT | FK | เล่ม (FK \-\> contract\_drawing\_volumes(id)) |
* **Foreign Keys (FK):**
* fk\_condwg\_project (project\_id) \-\> projects(id) (ON DELETE CASCADE)
* fk\_condwg\_subcat\_same\_project (project\_id, sub\_cat\_id) \-\> contract\_drawing\_sub\_cats(project\_id, id)
* fk\_condwg\_volume\_same\_project (project\_id, volume\_id) \-\> contract\_drawing\_volumes(project\_id, id)
* **Unique Keys (UK):** ux\_condwg\_no\_project (project\_id, condwg\_no)
#### **5.3. shop\_drawing\_main\_categories / ...\_sub\_categories**
ตาราง Master สำหรับ "แบบก่อสร้าง" (Shop Drawings) (Req 3.4)
* **shop\_drawing\_main\_categories:** เก็บ "หมวดหมู่หลัก" (เช่น ARCH, STR)
* **shop\_drawing\_sub\_categories:** เก็บ "หมวดหมู่ย่อย" (เช่น STR-COLUMN)
#### **5.4. shop\_drawings (Master)**
ตาราง Master เก็บข้อมูล "แบบก่อสร้าง" (Req 3.4.4)
| Column | Type | Key | Description |
| :---- | :---- | :---- | :---- |
| id | INT | **PK** | ID ของตาราง |
| project\_id | INT | FK | โครงการ (FK \-\> projects(id)) |
| drawing\_number | VARCHAR(100) | UK | เลขที่ Shop Drawing |
| title | VARCHAR(500) | | ชื่อแบบ |
| main\_category\_id | INT | FK | หมวดหมู่หลัก (FK \-\> shop\_drawing\_main\_categories(id)) |
| sub\_category\_id | INT | FK | หมวดหมู่ย่อย (FK \-\> shop\_drawing\_sub\_categories(id)) |
* **Foreign Keys (FK):** project\_id, main\_category\_id, sub\_category\_id
* **Unique Keys (UK):** ux\_sd\_drawing\_number (drawing\_number)
#### **5.5. shop\_drawing\_revisions (Revisions)**
ตาราง "ลูก" เก็บประวัติ (Revisions) ของ shop\_drawings (1:N) **(ปรับปรุง)** ลบ file\_path ออกแล้ว
| Column | Type | Key | Description |
| :---- | :---- | :---- | :---- |
| id | INT | **PK** | ID ของ Revision |
| shop\_drawing\_id | INT | FK, UK | Master ID (FK \-\> shop\_drawings(id)) |
| revision\_number | VARCHAR(10) | UK | หมายเลข Revision (เช่น A, B, 0, 1\) |
| revision\_date | DATE | | วันที่ของ Revision |
| description | TEXT | | คำอธิบายการแก้ไข |
* **Foreign Keys (FK):**
* shop\_drawing\_id \-\> shop\_drawings(id) (ON DELETE CASCADE)
* **Unique Keys (UK):** ux\_sd\_rev\_drawing\_revision (shop\_drawing\_id, revision\_number)
#### **5.6. shop\_drawing\_revision\_contract\_refs (ตารางเชื่อม)**
ตารางเชื่อมระหว่าง shop\_drawing\_revisions กับ contract\_drawings (M:N) (Req 3.5.4)
| Column | Type | Key | Description |
| :---- | :---- | :---- | :---- |
| shop\_drawing\_revision\_id | INT | FK | ID ของ Shop Drawing Revision (FK \-\> shop\_drawing\_revisions(id)) |
| contract\_drawing\_id | INT | FK | ID ของ Contract Drawing (FK \-\> contract\_drawings(id)) |
* **Foreign Keys (FK):** shop\_drawing\_revision\_id, contract\_drawing\_id
## **6\. 🔄 Circulations (ใบเวียนภายใน)**
#### **6.1. circulation\_status\_codes**
ตาราง Master เก็บสถานะใบเวียน (เช่น OPEN, IN\_REVIEW, COMPLETED)
#### **6.2. circulations (Master)**
ตาราง "แม่" ของใบเวียนเอกสารภายใน (Req 3.7)
| Column | Type | Key | Description |
| :---- | :---- | :---- | :---- |
| id | INT | **PK** | ID ของตาราง |
| correspondence\_id | INT | UK, FK | เอกสารที่ใช้อ้างอิง (FK \-\> correspondences(id)) |
| organization\_id | INT | FK, UK | องค์กรเจ้าของใบเวียน (FK \-\> organizations(id)) |
| circulation\_no | VARCHAR(100) | UK | เลขที่ใบเวียน |
| circulation\_subject | VARCHAR(500) | | เรื่อง |
| circulation\_status\_code | VARCHAR(20) | FK | สถานะใบเวียน (FK \-\> circulation\_status\_codes(code)) |
| created\_by\_user\_id | INT | FK | ผู้สร้าง (FK \-\> users(user\_id)) |
* **Foreign Keys (FK):** correspondence\_id, organization\_id, circulation\_status\_code, created\_by\_user\_id
* **Unique Keys (UK):**
* correspondence\_id (1 ใบเวียน ต่อ 1 เอกสาร)
* uq\_cir\_org\_no (organization\_id, circulation\_no) (เลขที่ใบเวียนห้ามซ้ำในองค์กร)
#### **6.3. circulation\_recipients / ...\_assignees / ...\_actions**
ตาราง "ลูก" ของ circulations
* **circulation\_recipients:** รายชื่อผู้รับ (TO/CC) ภายในองค์กร
* **circulation\_assignees:** รายชื่อผู้รับผิดชอบ (MAIN, ACTION, INFO) (Req 3.7.4) และเก็บ deadline (Req 3.7.5)
* **circulation\_actions:** ประวัติการดำเนินการ (เช่น Comment, Forward, Close)
* **circulation\_action\_documents:** ตารางเชื่อม circulation\_actions กับ attachments (ไฟล์แนบระหว่างดำเนินการ)
#### **6.4. circulation\_templates / ...\_assignees**
ตารางสำหรับแม่แบบใบเวียน (Templates)
* **circulation\_templates:** ตาราง Master เก็บแม่แบบใบเวียน
* **circulation\_template\_assignees:** ตารางลูก เก็บผู้รับผิดชอบที่กำหนดไว้ล่วงหน้าในแม่แบบ
## **7\. 📤 Transmittals (เอกสารนำส่ง)**
#### **7.1. transmittals**
ตารางข้อมูลเฉพาะของเอกสารนำส่ง (เป็นตารางลูก 1:1 ของ correspondences) (Req 3.6)
| Column | Type | Key | Description |
| :---- | :---- | :---- | :---- |
| correspondence\_id | INT | **PK**, FK | ID ของเอกสาร (FK \-\> correspondences(id)) |
| purpose | ENUM(...) | | วัตถุประสงค์ (FOR\_APPROVAL, FOR\_INFORMATION, ...) |
| remarks | TEXT | | หมายเหตุ |
* **Foreign Keys (FK):** correspondence\_id \-\> correspondences(id) (ON DELETE CASCADE)
#### **7.2. transmittal\_items (ตารางเชื่อม)**
ตารางเชื่อมระหว่าง transmittals และ rfa\_revisions (M:N) (Req 3.6.1)
| Column | Type | Key | Description |
| :---- | :---- | :---- | :---- |
| transmittal\_id | INT | **PK**, FK | ID ของ Transmittal (FK \-\> transmittals(correspondence\_id)) |
| rfarev\_id | INT | **PK**, FK | ID ของ RFA Revision (FK \-\> rfa\_revisions(correspondence\_id)) |
* **Foreign Keys (FK):**
* transmittal\_id \-\> transmittals(correspondence\_id) (ON DELETE CASCADE)
* rfarev\_id \-\> rfa\_revisions(correspondence\_id) (ON DELETE CASCADE)
* **Unique Keys (UK):** ux\_transmittal\_item (transmittal\_id, rfarev\_id)
## **8\. 📎 File Management (ไฟล์แนบ)**
#### **8.1. attachments (Master)**
ตาราง "กลาง" เก็บไฟล์แนบทั้งหมดของระบบ **(ปรับปรุง)** เป็นตารางกลาง ไม่มี FK ไปยังตารางอื่น
| Column | Type | Key | Description |
| :---- | :---- | :---- | :---- |
| id | INT | **PK** | ID ของไฟล์แนบ |
| original\_filename | VARCHAR(255) | | ชื่อไฟล์ดั้งเดิม |
| stored\_filename | VARCHAR(255) | | ชื่อไฟล์ที่เก็บจริง (ป้องกันซ้ำ) |
| file\_path | VARCHAR(500) | | Path ที่เก็บไฟล์ (บน QNAP /share/dms-data/) |
| mime\_type | VARCHAR(100) | | ประเภทไฟล์ (เช่น application/pdf) |
| file\_size | INT | | ขนาดไฟล์ (bytes) |
| uploaded\_by\_user\_id | INT | FK | ผู้อัปโหลด (FK \-\> users(user\_id)) |
* **Foreign Keys (FK):** uploaded\_by\_user\_id \-\> users(user\_id) (ON DELETE CASCADE)
#### **8.2. correspondence\_attachments (ตารางเชื่อม \- ใหม่)**
ตารางเชื่อม correspondences กับ attachments (M:N)
| Column | Type | Key | Description |
| :---- | :---- | :---- | :---- |
| correspondence\_id | INT | **PK**, FK | ID ของเอกสาร (FK \-\> correspondences(id)) |
| attachment\_id | INT | **PK**, FK | ID ของไฟล์แนบ (FK \-\> attachments(id)) |
| is\_main\_document | BOOLEAN | | (1 \= ไฟล์หลัก) (Req 5.7) |
* **Foreign Keys (FK):** correspondence\_id, attachment\_id
#### **8.3. circulation\_attachments (ตารางเชื่อม \- ใหม่)**
ตารางเชื่อม circulations กับ attachments (M:N)
| Column | Type | Key | Description |
| :---- | :---- | :---- | :---- |
| circulation\_id | INT | **PK**, FK | ID ของใบเวียน (FK \-\> circulations(id)) |
| attachment\_id | INT | **PK**, FK | ID ของไฟล์แนบ (FK \-\> attachments(id)) |
| is\_main\_document | BOOLEAN | | (1 \= ไฟล์หลัก) |
* **Foreign Keys (FK):** circulation\_id, attachment\_id
#### **8.4. shop\_drawing\_revision\_attachments (ตารางเชื่อม \- ใหม่)**
ตารางเชื่อม shop\_drawing\_revisions กับ attachments (M:N)
| Column | Type | Key | Description |
| :---- | :---- | :---- | :---- |
| shop\_drawing\_revision\_id | INT | **PK**, FK | ID ของ Drawing Revision (FK \-\> shop\_drawing\_revisions(id)) |
| attachment\_id | INT | **PK**, FK | ID ของไฟล์แนบ (FK \-\> attachments(id)) |
| file\_type | ENUM(...) | | ประเภทไฟล์ (PDF, DWG, SOURCE, OTHER) (Req 5.7) |
* **Foreign Keys (FK):** shop\_drawing\_revision\_id, attachment\_id
## **9\. 🔢 Document Numbering (การสร้างเลขที่เอกสาร)**
#### **9.1. document\_number\_formats (ตารางตั้งค่า \- ใหม่)**
ตาราง Master เก็บ "รูปแบบ" Template ของเลขที่เอกสาร (Req 3.10)
| Column | Type | Key | Description |
| :---- | :---- | :---- | :---- |
| id | INT | **PK** | ID ของตาราง |
| project\_id | INT | FK, UK | โครงการ (FK \-\> projects(id)) |
| correspondence\_type\_id | INT | FK, UK | ประเภทเอกสาร (FK \-\> correspondence\_types(id)) |
| format\_template | VARCHAR(255) | | รูปแบบ Template (เช่น {ORG\_CODE}-{TYPE\_CODE}-{SEQ:4}) |
* **Foreign Keys (FK):** project\_id, correspondence\_type\_id
* **Unique Keys (UK):** uk\_project\_type (project\_id, correspondence\_type\_id)
#### **9.2. document\_number\_counters (ตารางตัวนับ \- ใหม่)**
ตารางเก็บ "ตัวนับ" (Running Number) ล่าสุด (Req 3.10.2)
| Column | Type | Key | Description |
| :---- | :---- | :---- | :---- |
| project\_id | INT | **PK**, FK | โครงการ (FK \-\> projects(id)) |
| originator\_organization\_id | INT | **PK**, FK | องค์กรผู้ส่ง (FK \-\> organizations(id)) |
| correspondence\_type\_id | INT | **PK**, FK | ประเภทเอกสาร (FK \-\> correspondence\_types(id)) |
| current\_year | INT | **PK** | ปี ค.ศ. ของตัวนับ |
| last\_number | INT | | เลขที่ล่าสุดที่ใช้ไป |
* **Foreign Keys (FK):** project\_id, originator\_organization\_id, correspondence\_type\_id
## **10\. ⚙️ System & Logs (ระบบและ Log)**
#### **10.1. tags**
ตาราง Master เก็บ Tags ทั้งหมดที่ใช้ในระบบ (Req 6.2)
| Column | Type | Key | Description |
| :---- | :---- | :---- | :---- |
| id | INT | **PK** | ID ของตาราง |
| tag\_name | VARCHAR(100) | UK | ชื่อ Tag |
* **Unique Keys (UK):** ux\_tag\_name (tag\_name)
#### **10.2. correspondence\_tags (ตารางเชื่อม)**
ตารางเชื่อมระหว่าง correspondences และ tags (M:N) (Req 3.2.4)
| Column | Type | Key | Description |
| :---- | :---- | :---- | :---- |
| correspondence\_id | INT | **PK**, FK | ID ของเอกสาร (FK \-\> correspondences(id)) |
| tag\_id | INT | **PK**, FK | ID ของ Tag (FK \-\> tags(id)) |
* **Foreign Keys (FK):** correspondence\_id, tag\_id
#### **10.3. audit\_logs**
ตารางเก็บบันทึกการกระทำของผู้ใช้ (Req 6.1)
| Column | Type | Key | Description |
| :---- | :---- | :---- | :---- |
| audit\_id | BIGINT | **PK** | ID ของ Log |
| user\_id | INT | FK | ผู้กระทำ (FK \-\> users(user\_id)) |
| action | VARCHAR(100) | | การกระทำ (เช่น rfa.create) |
| entity\_type | VARCHAR(50) | | ตาราง/โมดูล (เช่น rfas) |
| entity\_id | VARCHAR(50) | | ID ของสิ่งที่ถูกกระทำ |
| details\_json | JSON | | ข้อมูลเพิ่มเติม |
| ip\_address | VARCHAR(45) | | IP Address |
| created\_at | TIMESTAMP | | เวลาที่กระทำ |
* **Foreign Keys (FK):** user\_id \-\> users(user\_id) (ON DELETE SET NULL)
## **11\. 📋 Views & Procedures (วิว และ โปรซีเดอร์)**
#### **11.1. sp\_get\_next\_document\_number (Procedure)**
**(ใหม่)** Stored Procedure เดียวที่ใช้ในระบบ (Req 2.9.3)
* **หน้าที่:** ดึงเลขที่เอกสารถัดไป (Next Running Number) จากตาราง document\_number\_counters
* **ตรรกะ:** ใช้ SELECT ... FOR UPDATE เพื่อ "ล็อก" แถว ป้องกัน Race Condition (การที่ผู้ใช้ 2 คนได้เลขที่ซ้ำกัน)
#### **11.2. v\_current\_correspondences (View)**
* **หน้าที่:** แสดง Revision "ปัจจุบัน" (is\_current \= TRUE) ของ correspondences ทั้งหมด (ที่ไม่ใช่ RFA)
#### **11.3. v\_current\_rfas (View)**
* **หน้าที่:** แสดง Revision "ปัจจุบัน" (is\_current \= TRUE) ของ rfa\_revisions ทั้งหมด
#### **11.4. v\_user\_tasks (View)**
**(ใหม่)**
* **หน้าที่:** แสดงรายการ "งานของฉัน" (My Tasks) ที่ยังไม่เสร็จ (Req 5.3)
* **ตรรกะ:** JOIN ตาราง circulations กับ circulation\_assignees (ที่ is\_completed \= FALSE)
#### **11.5. v\_audit\_log\_details (View)**
**(ใหม่)**
* **หน้าที่:** แสดง audit\_logs พร้อมข้อมูล username และ email ของผู้กระทำ (Req 6.1)
#### **11.6. v\_user\_all\_permissions (View)**
**(ใหม่)**
* **หน้าที่:** รวมสิทธิ์ทั้งหมด (Global \+ Project) ของผู้ใช้ทุกคน เพื่อให้ Backend ตรวจสอบสิทธิ์ได้ง่าย (Req 4.2)
* **ตรรกะ:** UNION ข้อมูลจาก user\_roles และ user\_project\_roles

777
infrastructure/Markdown/LCBP3-DMS_V1_2_1_Data_Dictionary.md Normal file
View File

@@ -0,0 +1,777 @@
---
# **สรุปตารางฐานข้อมูล (Data Dictionary) - LCBP3-DMS (V1.2.1)**
เอกสารนี้สรุปโครงสร้างตาราง, Foreign Keys (FK), และ Constraints ที่สำคัญทั้งหมดในฐานข้อมูล LCBP3-DMS (v1.2.0) เพื่อใช้เป็นเอกสารอ้างอิงสำหรับทีมพัฒนา Backend (NestJS) และ Frontend (Next.js)
## **1\. 🏢 Core & Master Data (องค์กร, โครงการ, สัญญา)**
#### **1.1. organization\_roles**
ตาราง Master เก็บประเภทบทบาทขององค์กร (เช่น OWNER, CONTRACTOR)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| id | INT | **PK** | ID ของตาราง |
| role\_name | VARCHAR(20) | UK | ชื่อบทบาท (OWNER, DESIGNER, CONSULTANT, CONTRACTOR, THIRD PARTY) |
* **Unique Keys (UK):** ux\_roles\_name (role\_name)
#### **1.2. organizations**
ตาราง Master เก็บข้อมูลองค์กรทั้งหมดที่เกี่ยวข้องในระบบ
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| id | INT | **PK** | ID ของตาราง |
| organization\_code | VARCHAR(20) | UK | รหัสองค์กร |
| organization\_name | VARCHAR(255) | | ชื่อองค์กร |
| role\_id | INT | FK | บทบาทขององค์กร (FK \-> organization\_roles(id)) |
| is\_active | BOOLEAN | | สถานะการใช้งาน |
* **Foreign Keys (FK):**
* role\_id \-> organization\_roles(id) (ON DELETE SET NULL)
* **Unique Keys (UK):** ux\_organizations\_code (organization\_code)
#### **1.3. projects**
ตาราง Master เก็บข้อมูลโครงการ (เช่น LCBP3C1, LCBP3C2)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| id | INT | **PK** | ID ของตาราง |
| project\_code | VARCHAR(50) | UK | รหัสโครงการ |
| project\_name | VARCHAR(255) | | ชื่อโครงการ |
| parent\_project\_id | INT | FK | รหัสโครงการหลัก (ถ้ามี) (FK \-> projects(id)) |
| contractor\_organization\_id | INT | FK | รหัสองค์กรผู้รับเหมา (ถ้ามี) (FK \-> organizations(id)) |
| is\_active | TINYINT(1) | | สถานะการใช้งาน |
* **Foreign Keys (FK):**
* parent\_project\_id \-> projects(id) (ON DELETE SET NULL)
* contractor\_organization\_id \-> organizations(id) (ON DELETE SET NULL)
* **Unique Keys (UK):** uq\_pro\_code (project\_code)
#### **1.4. contracts**
ตาราง Master เก็บข้อมูลสัญญา
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| id | INT | **PK** | ID ของตาราง |
| contract\_code | VARCHAR(50) | UK | รหัสสัญญา |
| contract\_name | VARCHAR(255) | | ชื่อสัญญา |
| description | TEXT | | คำอธิบายสัญญา |
* **Unique Keys (UK):** ux\_contracts\_code (contract\_code)
#### **1.5. project\_parties (ตารางเชื่อม)**
ตารางเชื่อมความสัมพันธ์ระหว่าง โครงการ, องค์กร, และบทบาท (M:N)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| project\_id | INT | **PK**, FK | ID ของโครงการ (FK \-> projects(id)) |
| organization\_id | INT | **PK**, FK | ID ขององค์กร (FK \-> organizations(id)) |
| role | ENUM(...) | **PK** | บทบาทในโครงการ (OWNER, DESIGNER, CONSULTANT, CONTRACTOR, THIRD\_PARTY) |
| is\_contractor | TINYINT(1) | UK | (Generated) \= 1 ถ้า role \= 'CONTRACTOR' |
| deleted\_at | DATETIME | | สำหรับ Soft Delete |
* **Foreign Keys (FK):**
* project\_id \-> projects(id) (ON DELETE CASCADE)
* organization\_id \-> organizations(id) (ON DELETE RESTRICT)
* **Unique Keys (UK):**
* uq\_project\_parties\_contractor (project\_id, is\_contractor) \- **(Constraint สำคัญ)** บังคับว่า 1 โครงการมี CONTRACTOR ได้เพียง 1 องค์กร
#### **1.6. contract\_parties (ตารางเชื่อม)**
ตารางเชื่อมความสัมพันธ์ระหว่าง สัญญา, โครงการ, และองค์กร (M:N)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| contract\_id | INT | **PK**, FK | ID ของสัญญา (FK \-> contracts(id)) |
| project\_id | INT | **PK**, FK | ID ของโครงการ (FK \-> projects(id)) |
| organization\_id | INT | **PK**, FK | ID ขององค์กร (FK \-> organizations(id)) |
* **Foreign Keys (FK):**
* contract\_id \-> contracts(id) (ON DELETE CASCADE)
* project\_id \-> projects(id) (ON DELETE CASCADE)
* organization\_id \-> organizations(id) (ON DELETE CASCADE)
---
## **2\. 👥 Users & RBAC (ผู้ใช้, สิทธิ์, บทบาท)**
#### **2.1. users**
ตาราง Master เก็บข้อมูลผู้ใช้งาน (User)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| user\_id | INT | **PK** | ID ของตาราง |
| username | VARCHAR(50) | UK | ชื่อผู้ใช้งาน |
| password\_hash | VARCHAR(255) | | รหัสผ่าน (Hashed) |
| first\_name | VARCHAR(50) | | ชื่อจริง |
| last\_name | VARCHAR(50) | | นามสกุล |
| email | VARCHAR(100) | UK | อีเมล |
| organization\_id | INT | FK | สังกัดองค์กร (FK \-> organizations(id)) |
| is\_active | TINYINT(1) | | สถานะการใช้งาน |
* **Foreign Keys (FK):**
* organization\_id \-> organizations(id) (ON DELETE SET NULL)
* **Unique Keys (UK):** ux\_users\_username (username), ux\_users\_email (email)
#### **2.2. roles**
ตาราง Master เก็บ "บทบาท" ของผู้ใช้ในระบบ (เช่น SUPER\_ADMIN, ADMIN, EDITOR)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| role\_id | INT | **PK** | ID ของตาราง |
| role\_code | VARCHAR(50) | UK | รหัสบทบาท (เช่น SUPER\_ADMIN, ADMIN, EDITOR, VIEWER) |
| role\_name | VARCHAR(100) | | ชื่อบทบาท |
| is\_system | BOOLEAN | | (1 \= บทบาทของระบบ ลบไม่ได้) |
* **Unique Keys (UK):** role\_code
#### **2.3. permissions**
ตาราง Master เก็บ "สิทธิ์" (Permission) หรือ "การกระทำ" ทั้งหมดในระบบ
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| permission\_id | INT | **PK** | ID ของตาราง |
| permission\_code | VARCHAR(100) | UK | รหัสสิทธิ์ (เช่น rfas.create, rfas.view) |
| module | VARCHAR(50) | | โมดูลที่เกี่ยวข้อง |
| scope\_level | ENUM(...) | | ระดับของสิทธิ์ (GLOBAL, ORG, PROJECT) |
* **Unique Keys (UK):** ux\_permissions\_code (permission\_code)
#### **2.4. role\_permissions (ตารางเชื่อม)**
ตารางเชื่อมระหว่าง roles และ permissions (M:N)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| role\_id | INT | **PK**, FK | ID ของบทบาท (FK \-> roles(role\_id)) |
| permission\_id | INT | **PK**, FK | ID ของสิทธิ์ (FK \-> permissions(permission\_id)) |
* **Foreign Keys (FK):**
* role\_id \-> roles(role\_id) (ON DELETE CASCADE)
* permission\_id \-> permissions(permission\_id) (ON DELETE CASCADE)
#### **2.5. user\_roles (ตารางเชื่อม)**
ตารางเชื่อมผู้ใช้ (users) กับบทบาท (roles) ในระดับ **Global** (M:N)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| user\_id | INT | **PK**, FK | ID ของผู้ใช้ (FK \-> users(user\_id)) |
| role\_id | INT | **PK**, FK | ID ของบทบาท (FK \-> roles(role\_id)) |
* **Foreign Keys (FK):**
* user\_id \-> users(user\_id) (ON DELETE CASCADE)
* role\_id \-> roles(role\_id) (ON DELETE CASCADE)
#### **2.6. user\_project\_roles (ตารางเชื่อม)**
ตารางเชื่อมผู้ใช้ (users) กับบทบาท (roles) ในระดับ **Project-Specific** (M:N)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| user\_id | INT | **PK**, FK | ID ของผู้ใช้ (FK \-> users(user\_id)) |
| project\_id | INT | **PK**, FK | ID ของโครงการ (FK \-> projects(id)) |
| role\_id | INT | **PK**, FK | ID ของบทบาท (FK \-> roles(role\_id)) |
* **Foreign Keys (FK):**
* user\_id \-> users(user\_id) (ON DELETE CASCADE)
* project\_id \-> projects(id) (ON DELETE CASCADE)
* role\_id \-> roles(role\_id) (ON DELETE CASCADE)
---
## **3\. ✉️ Correspondences (เอกสารหลัก, Revisions)**
#### **3.1. correspondence\_types**
ตาราง Master เก็บประเภทเอกสารโต้ตอบ (เช่น RFA, RFI, LETTER, MOM)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| id | INT | **PK** | ID ของตาราง |
| type\_code | VARCHAR(50) | UK | รหัสประเภท (เช่น RFA, RFI) |
| type\_name | VARCHAR(255) | | ชื่อประเภท |
* **Unique Keys (UK):** type\_code
#### **3.2. correspondence\_status**
ตาราง Master เก็บสถานะของเอกสาร (เช่น DRAFT, SUBMITTED, CLOSED)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| id | INT | **PK** | ID ของตาราง |
| status\_code | VARCHAR(50) | UK | รหัสสถานะ (เช่น DRAFT, SUBOWN) |
| status\_name | VARCHAR(255) | | ชื่อสถานะ |
* **Unique Keys (UK):** status\_code
#### **3.3. correspondences (Master)**
ตาราง "แม่" ของเอกสารโต้ตอบ เก็บข้อมูลที่ไม่เปลี่ยนแปลงตาม Revision (เช่น เลขที่เอกสาร)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| id | INT | **PK** | ID ของตาราง (นี่คือ "Master ID" ที่ใช้เชื่อมโยง) |
| correspondence\_number | VARCHAR(100) | UK | เลขที่เอกสาร (สร้างจาก DocumentNumberingModule) |
| correspondence\_type\_id | INT | FK | ประเภทเอกสาร (FK \-> correspondence\_types(id)) |
| is\_internal\_communication | TINYINT(1) | | (1 \= ภายใน, 0 \= ภายนอก) |
| project\_id | INT | FK | อยู่ในโครงการ (FK \-> projects(id)) |
| originator\_id | INT | FK | องค์กรผู้ส่ง (FK \-> organizations(id)) |
| recipient\_id | INT | FK | องค์กรผู้รับ (FK \-> organizations(id)) |
| created\_by | INT | FK | ผู้สร้าง (FK \-> users(user\_id)) |
| deleted\_at | DATETIME | | สำหรับ Soft Delete |
* **Foreign Keys (FK):**
* correspondence\_type\_id \-> correspondence\_types(id) (ON DELETE RESTRICT)
* project\_id \-> projects(id) (ON DELETE CASCADE)
* originator\_id \-> organizations(id) (ON DELETE SET NULL)
* recipient\_id \-> organizations(id) (ON DELETE SET NULL)
* created\_by \-> users(user\_id) (ON DELETE SET NULL)
* **Unique Keys (UK):** uq\_corr\_no\_per\_project (project\_id, correspondence\_number)
#### **3.4. correspondence\_revisions (Revisions)**
ตาราง "ลูก" เก็บประวัติการแก้ไข (Revisions) ของ correspondences (1:N) **(ปรับปรุง V1.2.0)**
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| id | INT | **PK** | **ID ของ Revision** |
| correspondence\_id | INT | FK, UK | Master ID (FK \-> correspondences(id)) |
| revision\_number | INT | UK | หมายเลข Revision (0, 1, 2...) |
| **revision\_label** | **VARCHAR(10)** | | **(ใหม่)** Revision ที่แสดง (เช่น A, B, 1.1) |
| is\_current | BOOLEAN | UK | (1 \= Revision ปัจจุบัน) |
| correspondence\_status\_id | INT | FK | สถานะของ Revision นี้ (FK \-> correspondence\_status(id)) |
| title | VARCHAR(255) | | เรื่อง |
| document\_date | DATE | | วันที่ในเอกสาร |
| issued\_date | DATETIME | | วันที่ออกเอกสาร |
| received\_date | DATETIME | | วันที่ลงรับ |
| **description** | **TEXT** | | **(ใหม่)** คำอธิบายการแก้ไขใน Revision นี้ |
| details | JSON | | ข้อมูลเฉพาะ (เช่น RFI details) |
| **created\_at** | **DATETIME** | | **(ใหม่)** วันที่สร้างเอกสาร |
| created\_by | INT | FK | ผู้สร้าง (FK \-> users(user\_id)) |
| **updated\_by** | **INT** | **FK** | **(ใหม่)** ผู้แก้ไขล่าสุด (FK \-> users(user\_id)) |
* **Foreign Keys (FK):**
* correspondence\_id \-> correspondences(id) (ON DELETE CASCADE)
* correspondence\_status\_id \-> correspondence\_status(id) (ON DELETE RESTRICT)
* created\_by \-> users(user\_id) (ON DELETE SET NULL)
* **updated\_by \-> users(user\_id) (ON DELETE SET NULL)**
* **Unique Keys (UK):**
* uq\_master\_revision\_number (correspondence\_id, revision\_number) (ป้องกัน Rev ซ้ำใน Master เดียว)
* uq\_master\_current (correspondence\_id, is\_current) (ป้องกันการมี is\_current \= TRUE ซ้ำใน Master เดียว)
* **Check Constraints (CHK):** chk\_rev\_format (ตรวจสอบรูปแบบ revision\_label)
#### **3.5. correspondence\_recipients (ตารางเชื่อม)**
ตารางเชื่อมผู้รับ (TO/CC) สำหรับเอกสารแต่ละฉบับ (M:N)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| correspondence\_id | INT | **PK**, FK | ID ของเอกสาร (FK \-> correspondence\_revisions(correspondence\_id)) |
| recipient\_organization\_id | INT | **PK**, FK | ID องค์กรผู้รับ (FK \-> organizations(id)) |
| recipient\_type | ENUM('TO', 'CC') | **PK** | ประเภทผู้รับ (TO หรือ CC) |
* **Foreign Keys (FK):**
* correspondence\_id \-> correspondence\_revisions(correspondence\_id) (ON DELETE CASCADE)
* recipient\_organization\_id \-> organizations(id) (ON DELETE RESTRICT)
#### **3.6. correspondence\_references (ตารางเชื่อม)**
ตารางเชื่อมการอ้างอิงระหว่างเอกสาร (M:N)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| src\_correspondence\_id | INT | **PK**, FK | ID เอกสารต้นทาง (FK \-> correspondences(id)) |
| tgt\_correspondence\_id | INT | **PK**, FK | ID เอกสารเป้าหมาย (FK \-> correspondences(id)) |
* **Foreign Keys (FK):**
* src\_correspondence\_id \-> correspondences(id) (ON DELETE CASCADE)
* tgt\_correspondence\_id \-> correspondences(id) (ON DELETE CASCADE)
#### **3.7. correspondence\_routing\_templates / ...\_steps / ...\_routings**
ตารางที่เกี่ยวข้องกับ Workflow การส่งต่อเอกสาร (Req 3.5.4)
* **correspondence\_routing\_templates:** ตาราง Master เก็บแม่แบบสายงาน (เช่น "ส่งให้ CSC ตรวจสอบ")
* **correspondence\_routing\_template\_steps:** ตารางลูก เก็บขั้นตอนในแม่แบบ (เช่น Step 1: ส่งไป Org A, Step 2: ส่งไป Org B)
* **correspondence\_routings:** ตารางประวัติ (Log) การส่งต่อของเอกสารจริงตาม Workflow
---
## **4\. approval: RFA (เอกสารขออนุมัติ, Workflows)**
#### **4.1. rfa\_types / ...\_status\_codes / ...\_approve\_codes**
ตาราง Master สำหรับ RFA
* **rfa\_types:** ประเภท RFA (เช่น DWG, DOC, MAT)
* **rfa\_status\_codes:** สถานะ RFA (เช่น DFT \- Draft, FAP \- For Approve)
* **rfa\_approve\_codes:** รหัสผลการอนุมัติ (เช่น 1A \- Approved, 3R \- Revise and Resubmit)
#### **4.2. rfas (Master)**
ตาราง "แม่" ของ RFA (มีความสัมพันธ์ 1:N กับ rfa\_revisions)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| id | INT | **PK** | ID ของตาราง (RFA Master ID) |
| rfa\_type\_id | INT | FK | ประเภท RFA (FK \-> rfa\_types(id)) |
| revision\_number | INT | | หมายเลข Revision ล่าสุด (ข้อมูลนี้ถูกย้ายไป rfa\_revisions) |
| created\_by | INT | FK | ผู้สร้าง (FK \-> users(user\_id)) |
| deleted\_at | DATETIME | | สำหรับ Soft Delete |
* **Foreign Keys (FK):**
* rfa\_type\_id \-> rfa\_types(id)
* created\_by \-> users(user\_id) (ON DELETE SET NULL)
#### **4.3. rfa\_revisions (Revisions)**
ตาราง "ลูก" เก็บประวัติ (Revisions) ของ rfas (1:N) **(ปรับปรุง V1.2.0)**
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| id | INT | **PK** | **ID ของ Revision** |
| correspondence\_id | INT | FK | Master ID ของ Correspondence (FK \-> correspondences(id)) |
| rfa\_id | INT | FK, UK | Master ID ของ RFA (FK \-> rfas(id)) |
| revision\_number | INT | UK | หมายเลข Revision (0, 1, 2...) |
| **revision\_label** | **VARCHAR(10)** | | **(ใหม่)** Revision ที่แสดง (เช่น A, B, 1.1) |
| is\_current | BOOLEAN | UK | (1 \= Revision ปัจจุบัน) |
| rfa\_status\_code\_id | INT | FK | สถานะ RFA (FK \-> rfa\_status\_codes(id)) |
| rfa\_approve\_code\_id | INT | FK | ผลการอนุมัติ (FK \-> rfa\_approve\_codes(id)) |
| title | VARCHAR(255) | | เรื่อง |
| **document\_date** | **DATE** | | **(ใหม่)** วันที่ในเอกสาร |
| **issued\_date** | **DATE** | | **(ใหม่)** วันที่ส่งขออนุมัติ |
| **received\_date** | **DATETIME** | | **(ใหม่)** วันที่ลงรับเอกสาร |
| **approved\_date** | **DATE** | | **(ใหม่)** วันที่อนุมัติ |
| **description** | **TEXT** | | **(ใหม่)** คำอธิบายการแก้ไขใน Revision นี้ |
| **created\_at** | **DATETIME** | | **(ใหม่)** วันที่สร้างเอกสาร |
| created\_by | INT | FK | ผู้สร้าง (FK \-> users(user\_id)) |
| **updated\_by** | **INT** | **FK** | **(ใหม่)** ผู้แก้ไขล่าสุด (FK \-> users(user\_id)) |
* **Foreign Keys (FK):**
* correspondence\_id \-> correspondences(id) (ON DELETE CASCADE)
* rfa\_id \-> rfas(id) (ON DELETE CASCADE)
* rfa\_status\_code\_id \-> rfa\_status\_codes(id)
* rfa\_approve\_code\_id \-> rfa\_approve\_codes(id) (ON DELETE SET NULL)
* created\_by \-> users(user\_id) (ON DELETE SET NULL)
* **updated\_by \-> users(user\_id) (ON DELETE SET NULL)**
* **Unique Keys (UK):**
* uq\_rr\_rev\_number (rfa\_id, revision\_number) (ป้องกัน Rev ซ้ำใน Master เดียว)
* uq\_rr\_current (rfa\_id, is\_current) (ป้องกัน is\_current=TRUE ซ้ำใน Master เดียว)
#### **4.4. rfa\_items (ตารางเชื่อม)**
ตารางเชื่อมระหว่าง rfa\_revisions (ที่เป็นประเภท DWG) กับ shop\_drawing\_revisions (M:N)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| rfarev\_correspondence\_id | INT | **PK**, FK | ID ของ RFA Revision (FK \-> rfa\_revisions(correspondence\_id)) |
| shop\_drawing\_revision\_id | INT | **PK**, UK, FK | ID ของ Shop Drawing Revision (FK \-> shop\_drawing\_revisions(id)) |
* **Foreign Keys (FK):**
* rfarev\_correspondence\_id \-> rfa\_revisions(correspondence\_id) (ON DELETE CASCADE)
* shop\_drawing\_revision\_id \-> shop\_drawing\_revisions(id) (ON DELETE CASCADE)
#### **4.5. rfa\_workflow\_templates / ...\_steps / ...\_workflows**
ตารางที่เกี่ยวข้องกับ Workflow การอนุมัติ RFA
* **rfa\_workflow\_templates:** ตาราง Master เก็บแม่แบบสายอนุมัติ (เช่น "สายอนุมัติ 3 ขั้นตอน")
* **rfa\_workflow\_template\_steps:** ตารางลูก เก็บขั้นตอนในแม่แบบ (เช่น Step 1: Org A (Review), Step 2: Org B (Approve))
* **rfa\_workflows:** ตารางประวัติ (Log) การอนุมัติของ RFA จริงตามสายงาน
---
## **5\. 📐 Drawings (แบบ, หมวดหมู่)**
#### **5.1. contract\_drawing\_volumes / ...\_cats / ...\_sub\_cats**
ตาราง Master สำหรับ "แบบคู่สัญญา" (Contract Drawings)
* **contract\_drawing\_volumes:** เก็บ "เล่ม" ของแบบ
* **contract\_drawing\_cats:** เก็บ "หมวดหมู่หลัก" ของแบบ
* **contract\_drawing\_sub\_cats:** เก็บ "หมวดหมู่ย่อย" ของแบบ
#### **5.2. contract\_drawing\_subcat\_cat\_maps (ตารางเชื่อม - ใหม่)**
**(ใหม่)** ตารางเชื่อมระหว่าง หมวดหมู่หลัก-ย่อย (M:N)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| project\_id | INT | **PK**, FK | ID ของโครงการ |
| sub\_cat\_id | INT | **PK**, FK | ID ของหมวดหมู่ย่อย |
| cat\_id | INT | **PK**, FK | ID ของหมวดหมู่หลัก |
* **Foreign Keys (FK) (ตามเจตนา):**
* (project\_id, sub\_cat\_id) \-> contract\_drawing\_sub\_cats(project\_id, id)
* (project\_id, cat\_id) \-> contract\_drawing\_cats(project\_id, id)
* **Unique Keys (UK):**
* ux\_map\_unique (project\_id, sub\_cat\_id, cat\_id)
* ***ข้อสังเกตจาก DBA:*** *สคริปต์ SQL (1.3.6) มีการอ้างอิง FK ไปยังตารางและคอลัมน์ (`contract_dwg_sub_cat(project_id, sub_cat_id)`) ที่ไม่มีอยู่จริง ตารางนี้แสดงตามเจตนาที่ถูกต้อง*
#### **5.3. contract\_drawings (Master)**
ตาราง Master เก็บข้อมูล "แบบคู่สัญญา"
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| id | INT | **PK** | ID ของตาราง |
| project\_id | INT | FK, UK | โครงการ (FK \-> projects(id)) |
| condwg\_no | VARCHAR(255) | UK | เลขที่แบบสัญญา |
| title | VARCHAR(255) | | ชื่อแบบ |
| sub\_cat\_id | INT | FK | หมวดหมู่ย่อย (FK \-> contract\_drawing\_sub\_cats(id)) |
| volume\_id | INT | FK | เล่ม (FK \-> contract\_drawing\_volumes(id)) |
* **Foreign Keys (FK):**
* fk\_condwg\_project (project\_id) \-> projects(id) (ON DELETE CASCADE)
* fk\_condwg\_subcat\_same\_project (project\_id, sub\_cat\_id) \-> contract\_drawing\_sub\_cats(project\_id, id)
* fk\_condwg\_volume\_same\_project (project\_id, volume\_id) \-> contract\_drawing\_volumes(project\_id, id)
* **Unique Keys (UK):** ux\_condwg\_no\_project (project\_id, condwg\_no)
#### **5.4. shop\_drawing\_main\_categories / ...\_sub\_categories**
ตาราง Master สำหรับ "แบบก่อสร้าง" (Shop Drawings)
* **shop\_drawing\_main\_categories:** เก็บ "หมวดหมู่หลัก" (เช่น ARCH, STR)
* **shop\_drawing\_sub\_categories:** เก็บ "หมวดหมู่ย่อย" (เช่น STR-COLUMN)
#### **5.5. shop\_drawings (Master)**
ตาราง Master เก็บข้อมูล "แบบก่อสร้าง"
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| id | INT | **PK** | ID ของตาราง |
| project\_id | INT | FK | โครงการ (FK \-> projects(id)) |
| drawing\_number | VARCHAR(100) | UK | เลขที่ Shop Drawing |
| title | VARCHAR(500) | | ชื่อแบบ |
| main\_category\_id | INT | FK | หมวดหมู่หลัก (FK \-> shop\_drawing\_main\_categories(id)) |
| sub\_category\_id | INT | FK | หมวดหมู่ย่อย (FK \-> shop\_drawing\_sub\_categories(id)) |
* **Foreign Keys (FK):** project\_id, main\_category\_id, sub\_category\_id
* **Unique Keys (UK):** ux\_sd\_drawing\_number (drawing\_number)
#### **5.6. shop\_drawing\_revisions (Revisions)**
ตาราง "ลูก" เก็บประวัติ (Revisions) ของ shop\_drawings (1:N)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| id | INT | **PK** | ID ของ Revision |
| shop\_drawing\_id | INT | FK, UK | Master ID (FK \-> shop\_drawings(id)) |
| revision\_number | VARCHAR(10) | UK | หมายเลข Revision (เช่น A, B, 0, 1) |
| revision\_date | DATE | | วันที่ของ Revision |
| description | TEXT | | คำอธิบายการแก้ไข |
* **Foreign Keys (FK):**
* shop\_drawing\_id \-> shop\_drawings(id) (ON DELETE CASCADE)
* **Unique Keys (UK):** ux\_sd\_rev\_drawing\_revision (shop\_drawing\_id, revision\_number)
#### **5.7. shop\_drawing\_revision\_contract\_refs (ตารางเชื่อม)**
ตารางเชื่อมระหว่าง shop\_drawing\_revisions กับ contract\_drawings (M:N)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| shop\_drawing\_revision\_id | INT | FK | ID ของ Shop Drawing Revision (FK \-> shop\_drawing\_revisions(id)) |
| contract\_drawing\_id | INT | FK | ID ของ Contract Drawing (FK \-> contract\_drawings(id)) |
* **Foreign Keys (FK):** shop\_drawing\_revision\_id, contract\_drawing\_id
---
## **6\. 🔄 Circulations (ใบเวียนภายใน)**
#### **6.1. circulation\_status\_codes**
ตาราง Master เก็บสถานะใบเวียน (เช่น OPEN, IN\_REVIEW, COMPLETED)
#### **6.2. circulations (Master)**
ตาราง "แม่" ของใบเวียนเอกสารภายใน
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| id | INT | **PK** | ID ของตาราง |
| correspondence\_id | INT | UK, FK | เอกสารที่ใช้อ้างอิง (FK \-> correspondences(id)) |
| organization\_id | INT | FK, UK | องค์กรเจ้าของใบเวียน (FK \-> organizations(id)) |
| circulation\_no | VARCHAR(100) | UK | เลขที่ใบเวียน |
| circulation\_subject | VARCHAR(500) | | เรื่อง |
| circulation\_status\_code | VARCHAR(20) | FK | สถานะใบเวียน (FK \-> circulation\_status\_codes(code)) |
| created\_by\_user\_id | INT | FK | ผู้สร้าง (FK \-> users(user\_id)) |
* **Foreign Keys (FK):** correspondence\_id, organization\_id, circulation\_status\_code, created\_by\_user\_id
* **Unique Keys (UK):**
* correspondence\_id (1 ใบเวียน ต่อ 1 เอกสาร)
* uq\_cir\_org\_no (organization\_id, circulation\_no) (เลขที่ใบเวียนห้ามซ้ำในองค์กร)
#### **6.3. circulation\_recipients / ...\_assignees / ...\_actions**
ตาราง "ลูก" ของ circulations
* **circulation\_recipients:** รายชื่อผู้รับ (TO/CC) ภายในองค์กร
* **circulation\_assignees:** รายชื่อผู้รับผิดชอบ (MAIN, ACTION, INFO) และเก็บ deadline
* **circulation\_actions:** ประวัติการดำเนินการ (เช่น Comment, Forward, Close)
* **circulation\_action\_documents:** ตารางเชื่อม circulation\_actions กับ attachments (ไฟล์แนบระหว่างดำเนินการ)
#### **6.4. circulation\_templates / ...\_assignees**
ตารางสำหรับแม่แบบใบเวียน (Templates)
* **circulation\_templates:** ตาราง Master เก็บแม่แบบใบเวียน
* **circulation\_template\_assignees:** ตารางลูก เก็บผู้รับผิดชอบที่กำหนดไว้ล่วงหน้าในแม่แบบ
---
## **7\. 📤 Transmittals (เอกสารนำส่ง)**
#### **7.1. transmittals**
ตารางข้อมูลเฉพาะของเอกสารนำส่ง (เป็นตารางลูก 1:1 ของ correspondences)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| correspondence\_id | INT | **PK**, FK | ID ของเอกสาร (FK \-> correspondences(id)) |
| purpose | ENUM(...) | | วัตถุประสงค์ (FOR\_APPROVAL, FOR\_INFORMATION, ...) |
| remarks | TEXT | | หมายเหตุ |
* **Foreign Keys (FK):** correspondence\_id \-> correspondences(id) (ON DELETE CASCADE)
#### **7.2. transmittal\_items (ตารางเชื่อม)**
ตารางเชื่อมระหว่าง transmittals และเอกสารที่นำส่ง (M:N) **(ปรับปรุง V1.2.0)**
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| **id** | **INT** | **PK** | **(ใหม่)** ID ของรายการ |
| transmittal\_id | INT | **FK**, UK | ID ของ Transmittal (FK \-> transmittals(correspondence\_id)) |
| **item\_correspondence\_id** | **INT** | **FK**, UK | **(เปลี่ยน)** ID ของเอกสารที่แนบไป (FK \-> correspondences(id)) |
| **quantity** | **INT** | | **(ใหม่)** จำนวน |
| **remarks** | **VARCHAR(255)** | | **(ใหม่)** หมายเหตุสำหรับรายการนี้ |
* **Foreign Keys (FK):**
* transmittal\_id \-> transmittals(correspondence\_id) (ON DELETE CASCADE)
* **item\_correspondence\_id \-> correspondences(id) (ON DELETE CASCADE)**
* **Unique Keys (UK):** ux\_transmittal\_item (transmittal\_id, item\_correspondence\_id)
---
## **8\. 📎 File Management (ไฟล์แนบ)**
#### **8.1. attachments (Master)**
ตาราง "กลาง" เก็บไฟล์แนบทั้งหมดของระบบ
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| id | INT | **PK** | ID ของไฟล์แนบ |
| original\_filename | VARCHAR(255) | | ชื่อไฟล์ดั้งเดิม |
| stored\_filename | VARCHAR(255) | | ชื่อไฟล์ที่เก็บจริง (ป้องกันซ้ำ) |
| file\_path | VARCHAR(500) | | Path ที่เก็บไฟล์ (บน QNAP /share/dms-data/) |
| mime\_type | VARCHAR(100) | | ประเภทไฟล์ (เช่น application/pdf) |
| file\_size | INT | | ขนาดไฟล์ (bytes) |
| uploaded\_by\_user\_id | INT | FK | ผู้อัปโหลด (FK \-> users(user\_id)) |
* **Foreign Keys (FK):** uploaded\_by\_user\_id \-> users(user\_id) (ON DELETE CASCADE)
#### **8.2. correspondence\_attachments (ตารางเชื่อม - ใหม่)**
ตารางเชื่อม correspondences กับ attachments (M:N)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| correspondence\_id | INT | **PK**, FK | ID ของเอกสาร (FK \-> correspondences(id)) |
| attachment\_id | INT | **PK**, FK | ID ของไฟล์แนบ (FK \-> attachments(id)) |
| is\_main\_document | BOOLEAN | | (1 \= ไฟล์หลัก) |
* **Foreign Keys (FK):** correspondence\_id, attachment\_id
#### **8.3. circulation\_attachments (ตารางเชื่อม - ใหม่)**
ตารางเชื่อม circulations กับ attachments (M:N)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| circulation\_id | INT | **PK**, FK | ID ของใบเวียน (FK \-> circulations(id)) |
| attachment\_id | INT | **PK**, FK | ID ของไฟล์แนบ (FK \-> attachments(id)) |
| is\_main\_document | BOOLEAN | | (1 \= ไฟล์หลัก) |
* **Foreign Keys (FK):** circulation\_id, attachment\_id
#### **8.4. shop\_drawing\_revision\_attachments (ตารางเชื่อม - ใหม่)**
ตารางเชื่อม shop\_drawing\_revisions กับ attachments (M:N) **(ปรับปรุง V1.2.0)**
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| shop\_drawing\_revision\_id | INT | **PK**, FK | ID ของ Drawing Revision (FK \-> shop\_drawing\_revisions(id)) |
| attachment\_id | INT | **PK**, FK | ID ของไฟล์แนบ (FK \-> attachments(id)) |
| file\_type | ENUM(...) | | ประเภทไฟล์ (PDF, DWG, SOURCE, OTHER) |
| **is\_main\_document** | **BOOLEAN** | | **(ใหม่)** (1 \= ไฟล์หลัก) |
* **Foreign Keys (FK):** shop\_drawing\_revision\_id, attachment\_id
#### **8.5. contract\_drawing\_attachments (ตารางเชื่อม - ใหม่)**
**(ใหม่)** ตารางเชื่อม contract\_drawings กับ attachments (M:N)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| contract\_drawing\_id | INT | **PK**, FK | ID ของ Contract Drawing (FK \-> contract\_drawings(id)) |
| attachment\_id | INT | **PK**, FK | ID ของไฟล์แนบ (FK \-> attachments(id)) |
| file\_type | ENUM(...) | | ประเภทไฟล์ (PDF, DWG, SOURCE, OTHER) |
| is\_main\_document | BOOLEAN | | (1 \= ไฟล์หลัก) |
* **Foreign Keys (FK):**
* contract\_drawing\_id \-> contract\_drawings(id) (ON DELETE CASCADE)
* attachment\_id \-> attachments(id) (ON DELETE CASCADE)
---
## **9\. 🔢 Document Numbering (การสร้างเลขที่เอกสาร)**
#### **9.1. document\_number\_formats (ตารางตั้งค่า - ใหม่)**
ตาราง Master เก็บ "รูปแบบ" Template ของเลขที่เอกสาร
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| id | INT | **PK** | ID ของตาราง |
| project\_id | INT | FK, UK | โครงการ (FK \-> projects(id)) |
| correspondence\_type\_id | INT | FK, UK | ประเภทเอกสาร (FK \-> correspondence\_types(id)) |
| format\_template | VARCHAR(255) | | รูปแบบ Template (เช่น {ORG\_CODE}-{TYPE\_CODE}-{SEQ:4}) |
* **Foreign Keys (FK):** project\_id, correspondence\_type\_id
* **Unique Keys (UK):** uk\_project\_type (project\_id, correspondence\_type\_id)
#### **9.2. document\_number\_counters (ตารางตัวนับ - ใหม่)**
ตารางเก็บ "ตัวนับ" (Running Number) ล่าสุด
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| project\_id | INT | **PK**, FK | โครงการ (FK \-> projects(id)) |
| originator\_organization\_id | INT | **PK**, FK | องค์กรผู้ส่ง (FK \-> organizations(id)) |
| correspondence\_type\_id | INT | **PK**, FK | ประเภทเอกสาร (FK \-> correspondence\_types(id)) |
| current\_year | INT | **PK** | ปี ค.ศ. ของตัวนับ |
| last\_number | INT | | เลขที่ล่าสุดที่ใช้ไป |
* **Foreign Keys (FK):** project\_id, originator\_organization\_id, correspondence\_type\_id
---
## **10\. ⚙️ System & Logs (ระบบและ Log)**
#### **10.1. tags**
ตาราง Master เก็บ Tags ทั้งหมดที่ใช้ในระบบ
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| id | INT | **PK** | ID ของตาราง |
| tag\_name | VARCHAR(100) | UK | ชื่อ Tag |
* **Unique Keys (UK):** ux\_tag\_name (tag\_name)
#### **10.2. correspondence\_tags (ตารางเชื่อม)**
ตารางเชื่อมระหว่าง correspondences และ tags (M:N)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| correspondence\_id | INT | **PK**, FK | ID ของเอกสาร (FK \-> correspondences(id)) |
| tag\_id | INT | **PK**, FK | ID ของ Tag (FK \-> tags(id)) |
* **Foreign Keys (FK):** correspondence\_id, tag\_id
#### **10.3. audit\_logs**
ตารางเก็บบันทึกการกระทำของผู้ใช้
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| audit\_id | BIGINT | **PK** | ID ของ Log |
| user\_id | INT | FK | ผู้กระทำ (FK \-> users(user\_id)) |
| action | VARCHAR(100) | | การกระทำ (เช่น rfa.create) |
| entity\_type | VARCHAR(50) | | ตาราง/โมดูล (เช่น rfas) |
| entity\_id | VARCHAR(50) | | ID ของสิ่งที่ถูกกระทำ |
| details\_json | JSON | | ข้อมูลเพิ่มเติม |
| ip\_address | VARCHAR(45) | | IP Address |
| created\_at | TIMESTAMP | | เวลาที่กระทำ |
* **Foreign Keys (FK):** user\_id \-> users(user\_id) (ON DELETE SET NULL)
#### **10.4. global\_default\_roles (ใหม่)**
ตารางเก็บค่าเริ่มต้นของบทบาทองค์กร (เช่น OWNER, DESIGNER)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| id | TINYINT | **PK** | ID คงที่ ( \= 1) |
| role | ENUM(...) | **PK** | บทบาท (OWNER, DESIGNER, CONSULTANT) |
| position | TINYINT | **PK** | ลำดับที่ในบทบาท (1..n) |
| organization\_id | INT | FK, UK | ID องค์กร (FK \-> organizations(id)) |
* **Foreign Keys (FK):** organization\_id \-> organizations(id) (ON DELETE RESTRICT)
* **Unique Keys (UK):** ux\_gdr\_unique\_org\_per\_role (id, role, organization\_id)
#### **10.5. Workflow Transition Rules (ใหม่)**
ตารางกำหนด Business Rules สำหรับการเปลี่ยนสถานะ
* **correspondence\_status\_transitions:** (ใหม่) กฎการเปลี่ยนสถานะของ Correspondences (ทั่วไป)
* **rfa\_status\_transitions:** (ใหม่) กฎการเปลี่ยนสถานะของ RFA
* **circulation\_status\_transitions:** (ใหม่) กฎการเปลี่ยนสถานะของ Circulations (ใบเวียน)
---
## **11\. 📋 Views & Procedures (วิว และ โปรซีเดอร์)**
#### **11.1. sp\_get\_next\_document\_number (Procedure)**
**(ใหม่)** Stored Procedure เดียวที่ใช้ในระบบ
* **หน้าที่:** ดึงเลขที่เอกสารถัดไป (Next Running Number) จากตาราง document\_number\_counters
* **ตรรกะ:** ใช้ `SELECT ... FOR UPDATE` เพื่อ "ล็อก" แถว ป้องกัน Race Condition (การที่ผู้ใช้ 2 คนได้เลขที่ซ้ำกัน)
#### **11.2. v\_current\_correspondences (View)**
* **หน้าที่:** แสดง Revision "ปัจจุบัน" (is\_current \= TRUE) ของ correspondences ทั้งหมด (ที่ไม่ใช่ RFA)
#### **11.3. v\_current\_rfas (View)**
* **หน้าที่:** แสดง Revision "ปัจจุบัน" (is\_current \= TRUE) ของ rfa\_revisions ทั้งหมด
#### **11.4. v\_contract\_parties\_all (View)**
* **หน้าที่:** แสดงความสัมพันธ์ทั้งหมดระหว่าง Contract, Project, และ Organization
#### **11.5. v\_user\_tasks (View)**
**(ใหม่)**
* **หน้าที่:** แสดงรายการ "งานของฉัน" (My Tasks) ที่ยังไม่เสร็จ
* **ตรรกะ:** JOIN ตาราง circulations กับ circulation\_assignees (ที่ is\_completed \= FALSE)
#### **11.6. v\_audit\_log\_details (View)**
**(ใหม่)**
* **หน้าที่:** แสดง audit\_logs พร้อมข้อมูล username และ email ของผู้กระทำ
#### **11.7. v\_user\_all\_permissions (View)**
**(ใหม่)**
* **หน้าที่:** รวมสิทธิ์ทั้งหมด (Global \+ Project) ของผู้ใช้ทุกคน เพื่อให้ Backend ตรวจสอบสิทธิ์ได้ง่าย
* **ตรรกะ:** UNION ข้อมูลจาก user\_roles และ user\_project\_roles

459
infrastructure/Markdown/LCBP3-DMS_V1_2_1_FullStackJS.md Normal file
View File

@@ -0,0 +1,459 @@
# **Documents Management Sytem Version 1.2.1: แนวทางการพัฒนา FullStackJS**
## **🧠 ปรัชญาทั่วไป**
แนวทางปฏิบัติที่ดีที่สุดแบบครบวงจรสำหรับการพัฒนา NestJS Backend, NextJS Frontend และ Tailwind-based UI/UX ในสภาพแวดล้อม TypeScript มุ่งเน้นที่ ความชัดเจน (clarity), ความง่ายในการบำรุงรักษา (maintainability), ความสอดคล้องกัน (consistency) และ การเข้าถึงได้ (accessibility) ตลอดทั้งสแต็ก
## **⚙️ แนวทางทั่วไปสำหรับ TypeScript**
### **หลักการพื้นฐาน**
* ใช้ **ภาษาอังกฤษ** สำหรับโค้ดและเอกสารทั้งหมด
* กำหนดไทป์ (type) อย่างชัดเจนสำหรับตัวแปร, พารามิเตอร์ และค่าที่ส่งกลับ (return values) ทั้งหมด
* หลีกเลี่ยงการใช้ any; ให้สร้างไทป์ (types) หรืออินเทอร์เฟซ (interfaces) ที่กำหนดเอง
* ใช้ **JSDoc** สำหรับคลาส (classes) และเมธอด (methods) ที่เป็น public
* ส่งออก (Export) **สัญลักษณ์หลัก (main symbol) เพียงหนึ่งเดียว** ต่อไฟล์
* หลีกเลี่ยงบรรทัดว่างภายในฟังก์ชัน
### **ข้อตกลงในการตั้งชื่อ (Naming Conventions)**
| Entity (สิ่งที่ตั้งชื่อ) | Convention (รูปแบบ) | Example (ตัวอย่าง) |
| :---- | :---- | :---- |
| Classes | PascalCase | UserService |
| Variables & Functions | camelCase | getUserInfo |
| Files & Folders | kebab-case | user-service.ts |
| Environment Variables | UPPERCASE | DATABASE\URL |
| Booleans | Verb \+ Noun | isActive, canDelete, hasPermission |
ใช้คำเต็ม — ไม่ใช้อักษรย่อ — ยกเว้นคำมาตรฐาน (เช่น API, URL, req, res, err, ctx)
## **🧩 ฟังก์ชัน (Functions)**
* เขียนฟังก์ชันให้สั้น และทำ **หน้าที่เพียงอย่างเดียว** (single-purpose) (\< 20 บรรทัด)
* ใช้ **early returns** เพื่อลดการซ้อน (nesting) ของโค้ด
* ใช้ **map**, **filter**, **reduce** แทนการใช้ loops เมื่อเหมาะสม
* ควรใช้ **arrow functions** สำหรับตรรกะสั้นๆ, และใช้ **named functions** ในกรณีอื่น
* ใช้ **default parameters** แทนการตรวจสอบค่า null
* จัดกลุ่มพารามิเตอร์หลายตัวให้เป็นอ็อบเจกต์เดียว (RO-RO pattern)
* ส่งค่ากลับ (Return) เป็นอ็อบเจกต์ที่มีไทป์กำหนด (typed objects) ไม่ใช่ค่าพื้นฐาน (primitives)
* รักษาระดับของสิ่งที่เป็นนามธรรม (abstraction level) ให้เป็นระดับเดียวในแต่ละฟังก์ชัน
## **🧱 การจัดการข้อมูล (Data Handling)**
* ห่อหุ้มข้อมูล (Encapsulate) ในไทป์แบบผสม (composite types)
* ใช้ **immutability** (การไม่เปลี่ยนแปลงค่า) ด้วย readonly และ as const
* ทำการตรวจสอบความถูกต้องของข้อมูล (Validations) ในคลาสหรือ DTOs ไม่ใช่ภายในฟังก์ชันทางธุรกิจ
* ตรวจสอบความถูกต้องของข้อมูลโดยใช้ DTOs ที่มีไทป์กำหนดเสมอ
## **🧰 คลาส (Classes)**
* ปฏิบัติตามหลักการ **SOLID**
* ควรใช้ **composition มากกว่า inheritance** (Prefer composition over inheritance)
* กำหนด **interfaces** สำหรับสัญญา (contracts)
* ให้คลาสมุ่งเน้นการทำงานเฉพาะอย่างและมีขนาดเล็ก (\< 200 บรรทัด, \< 10 เมธอด, \< 10 properties)
## **🚨 การจัดการข้อผิดพลาด (Error Handling)**
* ใช้ Exceptions สำหรับข้อผิดพลาดที่ไม่คาดคิด
* ดักจับ (Catch) ข้อผิดพลาดเพื่อแก้ไขหรือเพิ่มบริบท (context) เท่านั้น; หากไม่เช่นนั้น ให้ใช้ global error handlers
* ระบุข้อความข้อผิดพลาด (error messages) ที่มีความหมายเสมอ
## **🧪 การทดสอบ (ทั่วไป) (Testing (General))**
* ใช้รูปแบบ **Arrange–Act–Assert**
* ใช้ชื่อตัวแปรในการทดสอบที่สื่อความหมาย (inputData, expectedOutput)
* เขียน **unit tests** สำหรับ public methods ทั้งหมด
* จำลอง (Mock) การพึ่งพาภายนอก (external dependencies)
* เพิ่ม **acceptance tests** ต่อโมดูลโดยใช้รูปแบบ Given–When-Then
# **🏗️ แบ็กเอนด์ (NestJS) (Backend (NestJS))**
### **หลักการ**
* **สถาปัตยกรรมแบบโมดูลาร์ (Modular architecture)**:
* หนึ่งโมดูลต่อหนึ่งโดเมน
* โครงสร้างแบบ Controller → Service → Repository (Model)
* DTOs ที่ตรวจสอบความถูกต้องด้วย **class-validator**
* ใช้ **MikroORM** (หรือ TypeORM/Prisma) สำหรับการคงอยู่ของข้อมูล (persistence) ซึ่งสอดคล้องกับสคีมา MariaDB
* ห่อหุ้มโค้ดที่ใช้ซ้ำได้ไว้ใน **common module** (@app/common):
* Configs, decorators, DTOs, guards, interceptors, notifications, shared services, types, validators
### **ฟังก์ชันหลัก (Core Functionalities)**
* Global **filters** สำหรับการจัดการ exception
* **Middlewares** สำหรับการจัดการ request
* **Guards** สำหรับการอนุญาต (permissions) และ RBAC
* **Interceptors** สำหรับการแปลงข้อมูล response และการบันทึก log
### **ข้อจำกัดในการ Deploy (QNAP Container Station)**
* **ห้ามใช้ไฟล์ .env** ในการตั้งค่า Environment Variables [cite: 2.1]
* การตั้งค่าทั้งหมด (เช่น Database connection string, JWT secret) **จะต้องถูกกำหนดผ่าน Environment Variable ใน docker-compose.yml โดยตรง** [cite: 6.5] ซึ่งจะจัดการผ่าน UI ของ QNAP Container Station [cite: 2.1]
### **โครงสร้างโมดูลตามโดเมน (Domain-Driven Module Structure)**
เพื่อให้สอดคล้องกับสคีมา SQL (LCBP3-DMS) เราจะใช้โครงสร้างโมดูลแบบ **Domain-Driven (แบ่งตามขอบเขตธุรกิจ)** แทนการแบ่งตามฟังก์ชัน:
1. **CoreModule / CommonModule:**
* เก็บ Services ที่ใช้ร่วมกัน เช่น DatabaseModule, FileStorageService (จัดการไฟล์ใน QNAP), AuditLogService, NotificationService
* NotificationService ต้องรองรับ Triggers ที่ระบุใน Requirement 6.7 [cite: 6.7]
2. **AuthModule / UserModule:**
* จัดการ users, roles, permissions และการยืนยันตัวตน (JWT, Guards)
* **(สำคัญ)** ต้องรับผิดชอบการตรวจสอบสิทธิ์ **3 ระดับ** [cite: 4.2]: สิทธิ์ระดับระบบ (Global Role), สิทธิ์ระดับโปรเจกต์ (Project Role), และ **สิทธิ์ระดับสัญญา (Contract Role)**
* **(สำคัญ)** ต้องมี API สำหรับ **Admin Panel** เพื่อ:
* สร้างและจัดการ Role และการจับคู่ Permission แบบไดนามิก [cite: 4.3]
* จัดการ Master Data (เช่น correspondence_types, tags) [cite: 4.5]
* ให้ Superadmin สร้าง Organizations และกำหนด Org Admin ได้ [cite: 4.6]
* ให้ Superadmin/Admin จัดการ document_number_formats (รูปแบบเลขที่เอกสาร) [cite: 3.10]
3. **ProjectModule:**
* จัดการ projects, organizations, contracts, project_parties, contract_parties
4. **CorrespondenceModule (โมดูลศูนย์กลาง):**
* จัดการ correspondences, correspondence\revisions
* **(สำคัญ)** Service นี้ต้อง Inject DocumentNumberingService เพื่อขอเลขที่เอกสารใหม่ก่อนการสร้าง
* **(สำคัญ)** ตรรกะการสร้าง/อัปเดต Revision จะอยู่ใน Service นี้
* จัดการ correspondence_attachments (ตารางเชื่อมไฟล์แนบ)
* รับผิดชอบเวิร์กโฟลว์ **"Correspondence Routings"** (correspondence\routings) สำหรับการส่งต่อเอกสารทั่วไประหว่างองค์กร
5. **RfaModule:**
* จัดการ rfas, rfa_revisions, rfa_items
* รับผิดชอบเวิร์กโฟลว์ **"RFA Workflows"** (rfa_workflows) สำหรับการอนุมัติเอกสารทางเทคนิค
6. **DrawingModule:**
* จัดการ shop_drawings, shop_drawing_revisions, contract_drawings และหมวดหมู่ต่างๆ
* จัดการ shop_drawing_revision_attachments และ contract_drawing_attachments(ตารางเชื่อมไฟล์แนบ)
7. **CirculationModule:**
* จัดการ circulations, circulation_templates, circulation_assignees
* จัดการ circulation_attachments (ตารางเชื่อมไฟล์แนบ)
* รับผิดชอบเวิร์กโฟลว์ **"Circulations"** สำหรับการเวียนเอกสาร **ภายในองค์กร**
8. **TransmittalModule:**
* จัดการ transmittals และ transmittal_items
9. **SearchModule:**
* ให้บริการค้นหาขั้นสูง (Advanced Search) [cite: 6.2] โดยใช้ **Elasticsearch** เพื่อรองรับการค้นหาแบบ Full-text จากชื่อเรื่อง, รายละเอียด, เลขที่เอกสาร, ประเภท, วันที่, และ Tags
10. **DocumentNumberingModule:**
* **สถานะ:** เป็น Module ภายใน (Internal Module) ไม่เปิด API สู่ภายนอก
* **หน้าที่:** ให้บริการ DocumentNumberingService ที่ Module อื่น (เช่น CorrespondenceModule) จะ Inject ไปใช้งาน
* **ตรรกะ:** รับผิดชอบการสร้างเลขที่เอกสาร โดยการเรียกใช้ Stored Procedure *sp_get_next_document_number** เพื่อป้องกัน Race Condition
### **เครื่องมือและไลบรารีที่แนะนำ (Recommended Tools & Libraries)**
🔐 **Authentication & Authorization**
* @nestjs/passport
* @nestjs/jwt
* casl – สำหรับ RBAC (Role-Based Access Control)
🗃️ **Database & ORM**
* @nestjs/typeorm – ORM สำหรับ SQL (หรือ Prisma เป็นทางเลือก)
* typeorm-seeding – สำหรับสร้างข้อมูลจำลอง (seeding)
📦 **Validation & Transformation**
* class-validator
* class-transformer
📁 **File Upload & Storage**
* @nestjs/platform-express
* multer – สำหรับจัดการไฟล์
🔍 **Search**
* @nestjs/elasticsearch – สำหรับ Full-text search [cite: 6.2]
📬 **Notification**
* nodemailer – สำหรับส่งอีเมล
* @nestjs/schedule – สำหรับ cron job หรือแจ้งเตือนตามเวลา
📊 **Logging & Monitoring**
* winston หรือ nestjs-pino – ระบบ log ที่ยืดหยุ่น
* @nestjs/terminus – สำหรับ health check
🧪 **Testing**
* @nestjs/testing
* jest – สำหรับ unit/integration test
🌐 **API Documentation**
* @nestjs/swagger – **(สำคัญมาก)** สร้าง Swagger UI อัตโนมัติ ต้องใช้ DTOs อย่างเคร่งครัดเพื่อความชัดเจนของ API สำหรับทีม Frontend
🛡️ **Security**
* helmet – ป้องกันช่องโหว่ HTTP
* rate-limiter-flexible – ป้องกัน brute force
### **🧪 Backend Testing**
เราจะแบ่งการทดสอบเป็น 3 ระดับ โดยใช้ **Jest** และ @nestjs/testing:
* **Unit Tests (การทดสอบหน่วยย่อย):**
* **เป้าหมาย:** ทดสอบ Logic ภายใน Service, Guard, หรือ Pipe โดยจำลอง (Mock) Dependencies ทั้งหมด
* **สิ่งที่ต้องทดสอบ:** Business Logic (เช่น การเปลี่ยนสถานะ Workflow, การตรวจสอบ Deadline) [cite: 2.9.1], ตรรกะการตรวจสอบสิทธิ์ (Auth Guard) ทั้ง 3 ระดับ
* **Integration Tests (การทดสอบการบูรณาการ):**
* **เป้าหมาย:** ทดสอบการทำงานร่วมกันของ Controller -> Service -> Repository (Database)
* **เทคนิค:** ใช้ **Test Database แยกต่างหาก** (ห้ามใช้ Dev DB) และใช้ supertest เพื่อยิง HTTP Request จริงไปยัง App
* **สิ่งที่ต้องทดสอบ:** การเรียก sp\get\next\document\number [cite: 2.9.3] และการทำงานของ Views (เช่น v_user_tasks)
* **E2E (End-to-End) Tests:**
* **เป้าหมาย:** ทดสอบ API Contract ว่า Response Body Shape ตรงตามเอกสาร Swagger เพื่อรับประกันทีม Frontend
### **🗄️ Backend State Management**
Backend (NestJS) ควรเป็น **Stateless** (ไม่เก็บสถานะ) "State" ทั้งหมดจะถูกจัดเก็บใน MariaDB
* **Request-Scoped State (สถานะภายใน Request เดียว):**
* **ปัญหา:** จะส่งต่อข้อมูล (เช่น User ที่ล็อกอิน) ระหว่าง Guard และ Service ใน Request เดียวกันได้อย่างไร?
* **วิธีแก้:** ใช้ **Request-Scoped Providers** ของ NestJS (เช่น AuthContextService) เพื่อเก็บข้อมูล User ปัจจุบันที่ได้จาก AuthGuard และให้ Service อื่น Inject ไปใช้
* **Application-Scoped State (การ Caching):**
* **ปัญหา:** ข้อมูล Master (เช่น roles, permissions, organizations) ถูกเรียกใช้บ่อย
* **วิธีแก้:** ใช้ **Caching** (เช่น @nestjs/cache-manager) เพื่อ Caching ข้อมูลเหล่านี้ และลดภาระ Database
# **🖥️ ฟรอนต์เอนด์ (NextJS / React / UI) (Frontend (NextJS / React / UI))**
### **โปรไฟล์นักพัฒนา (Developer Profile)**
วิศวกร TypeScript + React/NextJS ระดับ Senior
เชี่ยวชาญ TailwindCSS, Shadcn/UI, และ Radix สำหรับการพัฒนา UI
### **แนวทางการพัฒนาโค้ด (Code Implementation Guidelines)**
* ใช้ **early returns** เพื่อความชัดเจน
* ใช้คลาสของ **TailwindCSS** ในการกำหนดสไตล์เสมอ
* ควรใช้ class: syntax แบบมีเงื่อนไข (หรือ utility clsx) มากกว่าการใช้ ternary operators ใน class strings
* ใช้ **const arrow functions** สำหรับ components และ handlers
* Event handlers ให้ขึ้นต้นด้วย handle... (เช่น handleClick, handleSubmit)
* รวมแอตทริบิวต์สำหรับการเข้าถึง (accessibility) ด้วย:
tabIndex="0", aria-label, onKeyDown, ฯลฯ
* ตรวจสอบให้แน่ใจว่าโค้ดทั้งหมด **สมบูรณ์**, **ผ่านการทดสอบ**, และ **ไม่ซ้ำซ้อน (DRY)**
* ต้อง import โมดูลที่จำเป็นต้องใช้อย่างชัดเจนเสมอ
### **UI/UX ด้วย React**
* ใช้ **semantic HTML**
* ใช้คลาสของ **Tailwind** ที่รองรับ responsive (sm:, md:, lg:)
* รักษาลำดับชั้นของการมองเห็น (visual hierarchy) ด้วยการใช้ typography และ spacing
* ใช้ **Shadcn** components (Button, Input, Card, ฯลฯ) เพื่อ UI ที่สอดคล้องกัน
* ทำให้ components มีขนาดเล็กและมุ่งเน้นการทำงานเฉพาะอย่าง
* ใช้ utility classes สำหรับการจัดสไตล์อย่างรวดเร็ว (spacing, colors, text, ฯลฯ)
* ตรวจสอบให้แน่ใจว่าสอดคล้องกับ **ARIA** และใช้ semantic markup
### **การตรวจสอบฟอร์มและข้อผิดพลาด (Form Validation & Errors)**
* ใช้ไลบรารีฝั่ง client เช่น zod และ react-hook-form
* แสดงข้อผิดพลาดด้วย **alert components** หรือข้อความ inline
* ต้องมี labels, placeholders, และข้อความ feedback
### **🧪 Frontend Testing**
เราจะใช้ **React Testing Library (RTL)** สำหรับการทดสอบ Component และ **Playwright** สำหรับ E2E:
* **Unit Tests (การทดสอบหน่วยย่อย):**
* **เครื่องมือ:** Vitest + RTL
* **เป้าหมาย:** ทดสอบ Component ขนาดเล็ก (เช่น Buttons, Inputs) หรือ Utility functions
* **Integration Tests (การทดสอบการบูรณาการ):**
* **เครื่องมือ:** RTL + **Mock Service Worker (MSW)**
* **เป้าหมาย:** ทดสอบว่า Component หรือ Page ทำงานกับ API (ที่จำลองขึ้น) ได้ถูกต้อง
* **เทคนิค:** ใช้ MSW เพื่อจำลอง NestJS API และทดสอบว่า Component แสดงผลข้อมูลจำลองได้ถูกต้องหรือไม่ (เช่น ทดสอบหน้า Dashboard [cite: 5.3] ที่ดึงข้อมูลจาก v_user_tasks)
* **E2E (End-to-End) Tests:**
* **เครื่องมือ:** **Playwright**
* **เป้าหมาย:** ทดสอบ User Flow ทั้งระบบโดยอัตโนมัติ (เช่น ล็อกอิน -> สร้าง RFA -> ตรวจสอบ Workflow Visualization [cite: 5.6])
### **🗄️ Frontend State Management**
สำหรับ Next.js App Router เราจะแบ่ง State เป็น 4 ระดับ:
1. **Local UI State (สถานะ UI ชั่วคราว):**
* **เครื่องมือ:** useState, useReducer
* **ใช้เมื่อ:** จัดการสถานะเล็กๆ ที่จบใน Component เดียว (เช่น Modal เปิด/ปิด, ค่าใน Input)
2. **Server State (สถานะข้อมูลจากเซิร์ฟเวอร์):**
* **เครื่องมือ:** **React Query (TanStack Query)** หรือ SWR
* **ใช้เมื่อ:** จัดการข้อมูลที่ดึงมาจาก NestJS API (เช่น รายการ correspondences, rfas, drawings)
* **ทำไม:** React Query เป็น "Cache" ที่จัดการ Caching, Re-fetching, และ Invalidation ให้โดยอัตโนมัติ
3. **Global Client State (สถานะส่วนกลางฝั่ง Client):**
* **เครื่องมือ:** **Zustand** (แนะนำ) หรือ Context API
* **ใช้เมื่อ:** จัดการข้อมูลที่ต้องใช้ร่วมกันทั่วทั้งแอป และ *ไม่ใช่* ข้อมูลจากเซิร์ฟเวอร์ (เช่น ข้อมูล User ที่ล็อกอิน, สิทธิ์ Permissions)
4. **Form State (สถานะของฟอร์ม):**
* **เครื่องมือ:** **React Hook Form** + **Zod**
* **ใช้เมื่อ:** จัดการฟอร์มที่ซับซ้อน (เช่น ฟอร์มสร้าง RFA, ฟอร์ม Circulation [cite: 3.7])
# **🔗 แนวทางการบูรณาการ Full Stack (Full Stack Integration Guidelines)**
| Aspect (แง่มุม) | Backend (NestJS) | Frontend (NextJS) | UI Layer (Tailwind/Shadcn) |
| :---- | :---- | :---- | :---- |
| API | REST / GraphQL Controllers | API hooks ผ่าน fetch/axios/SWR | Components ที่รับข้อมูล |
| Validation (การตรวจสอบ) | class-validator DTOs | zod / react-hook-form | สถานะของฟอร์ม/input ใน Shadcn |
| Auth (การยืนยันตัวตน) | Guards, JWT | NextAuth / cookies | สถานะ UI ของ Auth (loading, signed in) |
| Errors (ข้อผิดพลาด) | Global filters | Toasts / modals | Alerts / ข้อความ feedback |
| Testing (การทดสอบ) | Jest (unit/e2e) | Vitest / Playwright | Visual regression |
| Styles (สไตล์) | Scoped modules (ถ้าจำเป็น) | Tailwind / Shadcn | Tailwind utilities |
| Accessibility (การเข้าถึง) | Guards + filters | ARIA attributes | Semantic HTML |
# **🗂️ ข้อตกลงเฉพาะสำหรับ DMS (LCBP3-DMS)**
ส่วนนี้ขยายแนวทาง FullStackJS ทั่วไปสำหรับโปรเจกต์ **LCBP3-DMS** โดยมุ่งเน้นไปที่เวิร์กโฟลว์การอนุมัติเอกสาร (Correspondence, RFA, Drawing, Contract, Transmittal, Circulation)
## **🧩 RBAC และการควบคุมสิทธิ์ (RBAC & Permission Control)**
ใช้ Decorators เพื่อบังคับใช้สิทธิ์การเข้าถึง โดยอ้างอิงสิทธิ์จากตาราง permissions
@RequirePermission('rfas.respond') // ต้องตรงกับ 'permission\code'
@Put(':id')
updateRFA(@Param('id') id: string) {
return this.rfaService.update(id);
}
### **Roles (บทบาท)**
* **Superadmin**: ไม่มีข้อจำกัดใดๆ [cite: 4.3]
* **Admin**: มีสิทธิ์เต็มที่ในองค์กร [cite: 4.3]
* **Document Control**: เพิ่ม/แก้ไข/ลบ เอกสารในองค์กร [cite: 4.3]
* **Editor**: สามารถ เพิ่ม/แก้ไข เอกสารที่กำหนด [cite: 4.3]
* **Viewer**: สามารถดู เอกสาร [cite: 4.3]
### **ตัวอย่าง Permissions (จากตาราง permissions)**
* rfas.view, rfas.create, rfas.respond, rfas.delete
* drawings.view, drawings.upload, drawings.delete
* corr.view, corr.manage
* transmittals.manage
* cirs.manage
* project\parties.manage
การจับคู่ระหว่าง roles และ permissions **เริ่มต้น** จะถูก seed ผ่านสคริปต์ (ดังที่เห็นในไฟล์ SQL)**อย่างไรก็ตาม AuthModule/UserModule ต้องมี API สำหรับ Admin เพื่อสร้าง Role ใหม่และกำหนดสิทธิ์ (Permissions) เพิ่มเติมได้ในภายหลัง** [cite: 4.3]
## **🧾 มาตรฐาน AuditLog (AuditLog Standard)**
บันทึกการดำเนินการ CRUD และการจับคู่ทั้งหมดลงในตาราง audit_logs
| Field (ฟิลด์) | Type (จาก SQL) | Description (คำอธิบาย) |
| :---- | :---- | :---- |
| audit_id | BIGINT | Primary Key |
| user_id | INT | ผู้ใช้ที่ดำเนินการ (FK -> users) |
| action | VARCHAR(100) | rfa.create, correspondence.update, login.success |
| entity_type | VARCHAR(50) | ชื่อตาราง/โมดูล เช่น 'rfa', 'correspondence' |
| entity_id | VARCHAR(50) | Primary ID ของระเบียนที่ได้รับผลกระทบ |
| details_json | JSON | ข้อมูลบริบท (เช่น ฟิลด์ที่มีการเปลี่ยนแปลง) |
| ip_address | VARCHAR(45) | IP address ของผู้ดำเนินการ |
| user_agent | VARCHAR(255) | User Agent ของผู้ดำเนินการ |
| created_at | TIMESTAMP | Timestamp (UTC) |
## **📂 การจัดการไฟล์ (File Handling) (ปรับปรุงใหม่)**
### **มาตรฐานการอัปโหลดไฟล์ (File Upload Standard)**
* **ตรรกะใหม่:** การอัปโหลดไฟล์ทั้งหมดจะถูกจัดการโดย FileStorageService และบันทึกข้อมูลไฟล์ลงในตาราง attachments (ตารางกลาง)
* ไฟล์จะถูกเชื่อมโยงไปยัง Entity ที่ถูกต้องผ่าน **ตารางเชื่อม (Junction Tables)** เท่านั้น:
* correspondence_attachments (เชื่อม Correspondence กับ Attachments)
* circulation_attachments (เชื่อม Circulation กับ Attachments)
* shop_drawing_revision_attachments (เชื่อม Shop Drawing Revision กับ Attachments)
* contract_drawing_attachments (เชื่อม Contract Drawing กับ Attachments)
* เส้นทางจัดเก็บไฟล์ (Upload path): อ้างอิงจาก Requirement 2.1 คือ /share/dms-data [cite: 2.1] โดย FileStorageService จะสร้างโฟลเดอร์ย่อยแบบรวมศูนย์ (เช่น /share/dms-data/uploads/{YYYY}/{MM}/[stored\filename])
* ประเภทไฟล์ที่อนุญาต: pdf, dwg, docx, xlsx, zip
* ขนาดสูงสุด: **50 MB**
* จัดเก็บนอก webroot
* ให้บริการไฟล์ผ่าน endpoint ที่ปลอดภัย /files/:attachment_id/download
### **การควบคุมการเข้าถึง (Access Control)**
การเข้าถึงไฟล์ไม่ใช่การเข้าถึงโดยตรง endpoint /files/:attachment_id/download จะต้อง:
1. ค้นหาระเบียน attachment
2. ตรวจสอบว่า attachment_id นี้ เชื่อมโยงกับ Entity ใด (เช่น correspondence, circulation, shop_drawing_revision, contract_drawing) ผ่านตารางเชื่อม
3. ตรวจสอบว่าผู้ใช้มีสิทธิ์ (permission) ในการดู Entity ต้นทางนั้นๆ หรือไม่
## **🔟 การจัดการเลขที่เอกสาร (Document Numbering) [cite: 3.10]**
* **เป้าหมาย:** สร้างเลขที่เอกสาร (เช่น correspondence\number) โดยอัตโนมัติ ตามรูปแบบที่กำหนด
* **ตรรกะการนับ:** การนับ Running number (SEQ) จะนับแยกตาม Key: **Project + Originator Organization + Document Type + Year**
* **ตาราง SQL:**
* document_number_formats: Admin ใช้กำหนด "รูปแบบ" (Template) ของเลขที่ (เช่น {ORG\CODE}-{TYPE\CODE}-{YEAR\SHORT}-{SEQ:4}) โดยกำหนดตาม **Project** และ **Document Type** [cite: 4.5]
* document_number_counters: ระบบใช้เก็บ "ตัวนับ" ล่าสุดของ Key (Project+Org+Type+Year)
* **การทำงาน (Backend):**
* DocumentNumberingModule จะให้บริการ DocumentNumberingService
* เมื่อ CorrespondenceModule ต้องการสร้างเอกสารใหม่, มันจะเรียก documentNumberingService.generateNextNumber(...)
* Service นี้จะเรียกใช้ Stored Procedure **sp_get_next_document_number** [cite: 2.9.3] ซึ่ง Procedure นี้จะจัดการ Database Transaction และ Row Lock (FOR UPDATE) ภายใน DB เพื่อรับประกันการป้องกัน Race Condition
## **📊 การรายงานและการส่งออก (Reporting & Exports)**
### **วิวสำหรับการรายงาน (Reporting Views) (จาก SQL)**
การรายงานควรสร้างขึ้นจาก Views ที่กำหนดไว้ล่วงหน้าในฐานข้อมูลเป็นหลัก:
* v_current_correspondences: สำหรับ revision ปัจจุบันทั้งหมดของเอกสารที่ไม่ใช่ RFA
* v_current_rfas: สำหรับ revision ปัจจุบันทั้งหมดของ RFA และข้อมูล master
* v_contract_parties_all: สำหรับการตรวจสอบความสัมพันธ์ของ project/contract/organization
* v_user_tasks: สำหรับ Dashboard "งานของฉัน"
* v_audit_log_details: สำหรับ Activity Feed
Views เหล่านี้ทำหน้าที่เป็นแหล่งข้อมูลหลักสำหรับการรายงานฝั่งเซิร์ฟเวอร์และการส่งออกข้อมูล
### **กฎการส่งออก (Export Rules)**
* Export formats: CSV, Excel, PDF.
* จัดเตรียมมุมมองสำหรับพิมพ์ (Print view).
* รวมลิงก์ไปยังต้นทาง (เช่น /rfas/:id).
## **🧮 ฟรอนต์เอนด์: รูปแบบ DataTable และฟอร์ม (Frontend: DataTable & Form Patterns)**
### **DataTable (Server‑Side)**
* Endpoint: /api/{module}?page=1\&pageSize=20\&sort=...\&filter=...
* ต้องรองรับ: การแบ่งหน้า (pagination), การเรียงลำดับ (sorting), การค้นหา (search), การกรอง (filters)
* แสดง revision ล่าสุดแบบ inline เสมอ (สำหรับ RFA/Drawing)
### **มาตรฐานฟอร์ม (Form Standards)**
* ต้องมีการใช้งาน Dropdowns แบบขึ้นต่อกัน (Dependent dropdowns) (ตามที่สคีมารองรับ):
* Project → Contract Drawing Volumes
* Contract Drawing Category → Sub-Category
* RFA (ประเภท Shop Drawing) → Shop Drawing Revisions ที่เชื่อมโยงได้
* **(ใหม่)** การอัปโหลดไฟล์: ต้องรองรับ **Multi-file upload (Drag-and-Drop)** [cite: 5.7]
* **(ใหม่)** UI ต้องอนุญาตให้ผู้ใช้กำหนดว่าไฟล์ใดเป็น **"เอกสารหลัก"** หรือ "เอกสารแนบประกอบ" [cite: 5.7]
* ส่ง (Submit) ผ่าน API พร้อม feedback แบบ toast
### **ข้อกำหนด Component เฉพาะ (Specific UI Requirements)**
* **Dashboard \- My Tasks:** ต้องพัฒนา Component ตาราง "งานของฉัน" (My Tasks)ซึ่งดึงข้อมูลงานที่ผู้ใช้ล็อกอินอยู่ต้องรับผิดชอบ (Main/Action) จาก v\user\tasks [cite: 5.3]
* **Workflow Visualization:** ต้องพัฒนา Component สำหรับแสดงผล Workflow (โดยเฉพาะ RFA)ที่แสดงขั้นตอนทั้งหมดเป็นลำดับ โดยขั้นตอนปัจจุบัน (active) เท่านั้นที่ดำเนินการได้ และขั้นตอนอื่นเป็น disabled [cite: 5.6] ต้องมีตรรกะสำหรับ Admin ในการ override หรือย้อนกลับขั้นตอนได้ [cite: 5.6]
* ** Admin Panel:** ต้องมีหน้า UI สำหรับ Superadmin/Admin เพื่อจัดการข้อมูลหลัก (Master Data [cite: 4.5]), การเริ่มต้นใช้งาน (Onboarding [cite: 4.6]), และ **รูปแบบเลขที่เอกสาร (Numbering Formats [cite: 3.10])**
## **🧭 แดชบอร์ดและฟีดกิจกรรม (Dashboard & Activity Feed)**
### **การ์ดบนแดชบอร์ด (Dashboard Cards)**
* แสดง Correspondences, RFAs, Circulations, Shop Drawing Revision ล่าสุด
* รวมสรุป KPI (เช่น "RFAs ที่รอการอนุมัติ", "Shop Drawing ที่รอการอนุมัติ") [cite: 5.3]
* รวมลิงก์ด่วนไปยังโมดูลต่างๆ
### **ฟีดกิจกรรม (Activity Feed)**
* แสดงรายการ v\audit\log\details ล่าสุด (10 รายการ) ที่เกี่ยวข้องกับผู้ใช้
// ตัวอย่าง API response
[
{ user: 'editor01', action: 'Updated RFA (LCBP3-RFA-001)', time: '2025-11-04T09:30Z' }
]
## **🛡️ ข้อกำหนดที่ไม่ใช่ฟังก์ชันการทำงาน (Non-Functional Requirements)**
ส่วนนี้สรุปข้อกำหนด Non-Functional จาก requirements.md เพื่อให้ทีมพัฒนาทราบ
* **Audit Log [cite: 6.1]:** ทุกการกระทำที่สำคัญ (C/U/D) ต้องถูกบันทึกใน audit_logs
* **Performance [cite: 6.4]:** ต้องใช้ Caching สำหรับข้อมูลที่เรียกบ่อย และใช้ Pagination
* **Security [cite: 6.5]:** ต้องมี Rate Limiting และจัดการ Secret ผ่าน docker-compose.yml (ไม่ใช่ .env)
* **(ใหม่) Backup & Recovery [cite: 6.6]:** ต้องมีแผนสำรองข้อมูลทั้ง Database (MariaDB) และ File Storage (/share/dms-data) อย่างน้อยวันละ 1 ครั้ง
* **(ใหม่) Notification Strategy [cite: 6.7]:** ระบบแจ้งเตือน (Email/Line) ต้องถูก Trigger เมื่อมีเอกสารใหม่ส่งถึง, มีการมอบหมายงานใหม่ (Circulation), หรือ (ทางเลือก) เมื่องานเสร็จ/ใกล้ถึงกำหนด
## **✅ มาตรฐานที่นำไปใช้แล้ว (จาก SQL v1.1.0) (Implemented Standards (from SQL v1.1.0))**
ส่วนนี้ยืนยันว่าแนวทางปฏิบัติที่ดีที่สุดต่อไปนี้เป็นส่วนหนึ่งของการออกแบบฐานข้อมูลอยู่แล้ว และควรถูกนำไปใช้ประโยชน์ ไม่ใช่สร้างขึ้นใหม่
* ✅ **Soft Delete:** นำไปใช้แล้วผ่านคอลัมน์ deleted_at ในตารางสำคัญ (เช่น correspondences, rfas, project_parties) ตรรกะการดึงข้อมูลต้องกรอง deleted_at IS NULL
* ✅ **Database Indexes:** สคีมาได้มีการทำ index ไว้อย่างหนักหน่วงบน foreign keys และคอลัมน์ที่ใช้ค้นหาบ่อย (เช่น idx_rr_rfa, idx_cor_project, idx_cr_is_current) เพื่อประสิทธิภาพ
* ✅ **โครงสร้าง RBAC:** มีระบบ users, roles, permissions, user_roles, และ user_project_roles ที่ครอบคลุมอยู่แล้ว
* ✅ **Data Seeding:** ข้อมูล Master (roles, permissions, organization_roles, initial users, project parties) ถูกรวมอยู่ในสคริปต์สคีมาแล้ว
## **🧩 การปรับปรุงที่แนะนำ (สำหรับอนาคต) (Recommended Enhancements (Future))**
* ✅ สร้าง Background job (โดยใช้ **n8n** เพื่อเชื่อมต่อกับ **Line** [cite: 2.7] และ/หรือใช้สำหรับการแจ้งเตือน RFA ที่ใกล้ถึงกำหนด due_date [cite: 6.7])
* ✅ เพิ่ม job ล้างข้อมูลเป็นระยะสำหรับ attachments ที่ไม่ถูกเชื่อมโยงกับ Entity ใดๆ เลย (ไฟล์กำพร้า)

210
infrastructure/Markdown/LCBP3-DMS_V1_2_1_application _requirements.md Normal file
View File

@@ -0,0 +1,210 @@
# **📝 Documents Management Sytem Version 1.2.1: Application Requirements Specification**
## **📌 1. วัตถุประสงค์**
สร้างเว็บแอปพลิเคชั่นสำหรับระบบบริหารจัดการเอกสารโครงการ (Document Management System)ที่สามารถจัดการและควบคุม การสื่อสารด้วยเอกสารที่ซับซ้อน อย่างมีประสิทธิภาพ
* มีฟังก์ชันหลักในการอัปโหลด จัดเก็บ ค้นหา แชร์ และควบคุมสิทธิ์การเข้าถึงเอกสาร
* ช่วยลดการใช้เอกสารกระดาษ เพิ่มความปลอดภัยในการจัดเก็บข้อมูล
* เพิ่มความสะดวกในการทำงานร่วมกันระหว่างองกรณ์
## **🛠️ 2. สถาปัตยกรรมและเทคโนโลยี (System Architecture & Technology Stack)**
ใช้สถาปัตยกรรมแบบ Headless/API-First ที่ทันสมัย ทำงานทั้งหมดบน QNAP Server ผ่าน Container Station เพื่อความสะดวกในการจัดการและบำรุงรักษา, Domain: np-dms.work, มี fix ip, รัน docker command ใน application ของ Container Station ได้โดยตรง, ประกอบด้วย
* 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 on Windows 11
* Domain: np-dms.work, www.np-dms.work
* ip: 159.192.126.103
* Docker Network: ทุก Service จะเชื่อมต่อผ่านเครือข่ายกลางชื่อ lcbp3 เพื่อให้สามารถสื่อสารกันได้
* Data Storage: /share/dms-data บน QNAP
* ข้อจำกัด: ไม่สามารถใช้ .env ในการกำหนดตัวแปรภายนอกได้ ต้องกำหนดใน docker-compose.yml เท่านั้น
* 2.2. Code Hosting:
* Application name: git
* Service: Gitea (Self-hosted on QNAP)
* Service name: gitea
* Domain: git.np-dms.work
* หน้าที่: เป็นศูนย์กลางในการเก็บและจัดการเวอร์ชันของโค้ด (Source Code) สำหรับทุกส่วน
* 2.3. Backend / Data Platform:
* Application name: lcbp3-backend
* Service: NestJS
* Service name: backend
* Domain: backend.np-dms.work
* Framework: NestJS (Node.js, TypeScript, ESM)
* หน้าที่: จัดการโครงสร้างข้อมูล (Data Models), สร้าง API, จัดการสิทธิ์ผู้ใช้ (Roles & Permissions), และสร้าง Workflow ทั้งหมดของระบบ
* 2.4. Database:
* Application name: lcbp3-db
* Service: mariadb:10.11
* Service name: mariadb
* Domain: db.np-dms.work
* หน้าที่: ฐานข้อมูลหลักสำหรับเก็บข้อมูลทั้งหมด
* Tooling: DBeaver (Community Edition), phpmyadmin สำหรับการออกแบบและจัดการฐานข้อมูล
* 2.5. Database management:
* Application name: lcbp3-db
* Service: phpmyadmin:5-apache
* Service name: pma
* Domain: pma.np-dms.work
* หน้าที่: จัดการฐานข้อมูล mariadb ผ่าน Web UI
* 2.6. Frontend:
* Application name: lcbp3-frontend
* Service: next.js
* 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
* 2.7. Workflow automation:
* Application name: lcbp3-n8n
* Service: n8nio/n8n:latest
* Service name: n8n
* Domain: n8n.np-dms.work
* หน้าที่: จัดการ workflow ระหว่าง Backend และ Line
* 2.8. Reverse Proxy:
* 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) ให้อัตโนมัติ
* **2.9. การจัดการตรรกะทางธุรกิจ (Business Logic Implementation):**
* 2.9.1. ตรรกะทางธุรกิจที่ซับซ้อนทั้งหมด (เช่น การเปลี่ยนสถานะ Workflow [cite: 3.5.4, 3.6.5], การบังคับใช้สิทธิ์ [cite: 4.4], การตรวจสอบ Deadline [cite: 3.2.5]) **จะถูกจัดการในฝั่ง Backend (NestJS)** [cite: 2.3] เพื่อให้สามารถบำรุงรักษาและทดสอบได้ง่าย (Testability)
* 2.9.2. **จะไม่มีการใช้ SQL Triggers** เพื่อป้องกันตรรกะซ่อนเร้น (Hidden Logic) และความซับซ้อนในการดีบัก
* 2.9.3. **ข้อยกเว้น:** ตรรกะเดียวที่จะอยู่ในฐานข้อมูลคือ **Stored Procedure** สำหรับการสร้างเลขที่เอกสาร (Document Numbering) [cite: 3.10] เพื่อป้องกันการซ้ำซ้อนของข้อมูล (Race Condition)
## **📦 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 หลายประเภท (Types) เช่น จดหมาย (Letter), อีเมล์ (Email), Request for Information (RFI), และสามารถเพิ่มประเภทใหม่ได้ในภายหลัง
* 3.2.3. การสร้างเอกสาร (Correspondence):
* ผู้ใช้ที่มีสิทธิ์ (เช่น Document Control) สามารถสร้างเอกสารรอไว้ในสถานะ ฉบับร่าง" (Draft) ได้ ซึ่งผู้ใช้งานต่างองค์กรจะมองไม่เห็น
* เมื่อกด "Submitted" แล้ว การแก้ไข, ถอนเอกสารกลับไปสถานะ Draft, หรือยกเลิก (Cancel) จะต้องทำโดยผู้ใช้ระดับ Admin ขึ้นไป พร้อมระบุเหตุผล
* 3.2.4. การอ้างอิงและจัดกลุ่ม:
* เอกสารสามารถอ้างถึง (Reference) เอกสารฉบับก่อนหน้าได้หลายฉบับ
* สามารถกำหนด Tag ได้หลาย Tag เพื่อจัดกลุ่มและใช้ในการค้นหาขั้นสูง
* 3.2.5. การจัดการ: มีการจัดการอย่างน้อยดังนี้
* สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบของ องกรณ์ ที่เป็นผู้รับได้
* มีระบบแจ้งเตือน ให้ผู้รับผิดชอบขององกรณ์ที่เป็น ผู้รับ/ผู้ส่ง ทราบ เมื่อมีเอกสารใหม่ หรือมีการเปลี่ยนสถานะ
* 3.3. การจัดกาแบบคู่สัญญา (Contract Drawing)
* 3.3.1. วัตถุประสงค์: แบบคู่สัญญา (Contract Drawing) ใช้เพื่ออ้างอิงและใช้ในการตรวจสอบ
* 3.3.2. ประเภทเอกสาร: ไฟล์ PDF
* 3.3.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
* 3.3.4. การอ้างอิงและจัดกลุ่ม: ใช้สำหรับอ้างอิง ใน Shop Drawings, มีการจัดหมวดหมู่ของ Contract Drawing
* 3.4. การจัดกาแบบก่อสร้าง (Shop Drawing)
* 3.4.1. วัตถุประสงค์: แบบก่อสร้าง (Shop Drawing) ใช้เในการตรวจสอบ โดยจัดส่งด้วย Request for Approval (RFA)
* 3.4.2. ประเภทเอกสาร: ไฟล์ PDF
* 3.4.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
* 3.4.4. การอ้างอิงและจัดกลุ่ม: ช้สำหรับอ้างอิง ใน Shop Drawings, มีการจัดหมวดหมู่ของ Shop Drawings
* 3.5. การจัดการเอกสารขออนุมัติ (Request for Approval & Workflow)
* 3.5.1. วัตถุประสงค์: เอกสารขออนุมัติ (Request for Approval) ใช้ในการส่งเอกสารเพิอขออนุมัติ
* 3.5.2. ประเภทเอกสาร: Request for Approval (RFA) เป็นชนิดหนึ่งของ Correspondence ที่มีลักษณะเฉพาะที่ต้องได้รับการอนุมัติ มีประเภทดังนี้:
* Request for Drawing Approval (RFA_DWG)
* Request for Document Approval (RFA_DOC)
* Request for Method statement Approval (RFA_MES)
* Request for Material Approval (RFA_MAT)
* 3.5.2. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
* 3.5.4. การอ้างอิงและจัดกลุ่ม: การจัดการ Drawing (RFA_DWG):
* เอกสาร RFA_DWG จะประกอบไปด้วย Shop Drawing (shop_drawings) หลายแผ่น ซึ่งแต่ละแผ่นมี Revision ของตัวเอง
* Shop Drawing แต่ละ Revision สามารถอ้างอิงถึง Contract Drawing (Ccontract_drawings) หลายแผ่น หรือไม่อ้างถึงก็ได้
* ระบบต้องมีส่วนสำหรับจัดการข้อมูล Master Data ของทั้ง Shop Drawing และ Contract Drawing แยกจากกัน
* 3.6.5. Workflow การอนุมัติ: ต้องรองรับกระบวนการอนุมัติที่ซับซ้อนและเป็นลำดับ เช่น
* ส่งจาก Originator -> Organization 1 -> Organization 2 -> Organization 3 แล้วส่งผลกลับตามลำดับเดิม (โดยถ้า องกรณ์ใดใน Workflow ให้ส่งกลับ ก็สามารถส่งผลกลับตามลำดับเดิมโดยไม่ต้องรอให้ถึง องกรณืในลำดับถัดไป)
* 3.6.6. การจัดการ: มีการจัดการอย่างน้อยดังนี้
* สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบของ องกรณ์ ที่อยู่ใน Workflow ได้
* มีระบบแจ้งเตือน ให้ผู้รับผิดชอบของ องกรณ์ ที่อยู่ใน Workflow ทราบ เมื่อมี RFA ใหม่ หรือมีการเปลี่ยนสถานะ
* 3.6.การจัดการเอกสารนำส่ง (Transmittals)
* 3.6.1. วัตถุประสงค์: เอกสารนำส่ง ใช้สำหรับ นำส่ง Request for Approval (RFAS) หลายฉบับ ไปยังองค์กรอื่น
* 3.6.2. ประเภทเอกสาร: ไฟล์ PDF
* 3.6.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
* 3.6.4. การอ้างอิงและจัดกลุ่ม: เอกสารนำส่ง เป็นส่วนหนึ่งใน Correspondence
* 3.7. ใบเวียนเอกสารภายใน (Internal Circulation Sheet)
* 3.7.1. วัตถุประสงค์: การสื่อสาร เอกสาร (Correspondence) ทุกฉบับ จะมีใบเวียนเอกสารเพื่อควบคุมและมอบหมายงานภายในองค์กร (สามารถดูและแก้ไขได้เฉพาะคนในองค์กร)
* 3.7.2. ประเภทเอกสาร: ไฟล์ PDF
* 3.7.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ในองค์กรนั้น สามารถสร้างและแก้ไขได้
* 3.7.4. การอ้างอิงและจัดกลุ่ม: การระบุผู้รับผิดชอบ:
* ผู้รับผิดชอบหลัก (Main): มีได้หลายคน
* ผู้ร่วมปฏิบัติงาน (Action): มีได้หลายคน
* ผู้ที่ต้องรับทราบ (Information): มีได้หลายคน
* 3.7.5. การติดตามงาน:
* สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบประเภท Main และ Action ได้
* มีระบบแจ้งเตือนเมื่อมี Circulation ใหม่ และแจ้งเตือนล่วงหน้าก่อนถึงวันแล้วเสร็จ
* สามารถปิด Circulation ได้เมื่อดำเนินการตอบกลับไปยังองค์กรผู้ส่ง (Originator) แล้ว หรือ รับทราบแล้ว (For Information)
* 3.8. ประวัติการแก้ไข (Revisions): ระบบจะเก็บประวัติการสร้างและแก้ไข เอกสารทั้งหมด
* 3.9. การจัดเก็บ: (ปรับปรุงตามสถาปัตยกรรมใหม่)
* เอกสารและไฟล์แนบทั้งหมดจะถูกจัดเก็บในโฟลเดอร์บน Server (/share/dms-data/) [cite: 2.1]
* ข้อมูล Metadata ของไฟล์ (เช่น ชื่อไฟล์, ขนาด, path) จะถูกเก็บในตาราง attachments (ตารางกลาง)
* ไฟล์จะถูกเชื่อมโยงกับเอกสารประเภทต่างๆ ผ่านตารางเชื่อม (Junction tables) เช่น correspondence_attachments, circulation_attachments, shop_drawing_revision_attachments ,และ contracy_drawing_attachments
* สถาปัตยกรรมแบบรวมศูนย์นี้ *แทนที่* แนวคิดเดิมที่จะแยกโฟลเดอร์ตามประเภทเอกสาร เพื่อรองรับการขยายระบบที่ดีกว่า
* 3.10. การจัดการเลขที่เอกสาร (Document Numbering):
* 3.10.1. ระบบต้องสามารถสร้างเลขที่เอกสาร (เช่น correspondence_number) ได้โดยอัตโนมัติ
* 3.10.2. การนับเลข Running Number (SEQ) จะต้องนับแยกตาม Key ดังนี้: **โครงการ (Project)**, **องค์กรผู้ส่ง (Originator Organization)**, **ประเภทเอกสาร (Document Type)** และ **ปีปัจจุบัน (Year)**
* 3.10.3. ผู้ดูแลระบบ (Admin) ต้องสามารถกำหนด "รูปแบบ" (Format Template) ของเลขที่เอกสารได้ (เช่น {ORG_CODE}-{TYPE_CODE}-{YEAR_SHORT}-{SEQ:4}) โดยกำหนดแยกตามโครงการและประเภทเอกสาร
## **🔐 4. ข้อกำหนดด้านสิทธิ์และการเข้าถึง (Access Control Requirements)**
* 4.1. ภาพรวม: ผู้ใช้และองค์กรสามารถดูและแก้ไขเอกสารได้ตามสิทธิ์ที่ได้รับ โดยระบบสิทธิ์จะเป็นแบบ Role-Based Access Control (RBAC)
* 4.2. ระดับของสิทธิ์:
* Global Roles: สิทธิ์ในภาพรวมของระบบ
* Project-Specific Roles: สิทธิ์ที่ถูกกำหนดให้ผู้ใช้สำหรับโครงการนั้นๆ โดยเฉพาะ (เช่น เป็น Editor ในโครงการ A แต่เป็น Viewer ในโครงการ B)
* 4.3. บทบาท (Roles) พื้นฐาน:
* Superadmin: ไม่มีข้อจำกัดใดๆ สามารถจัดการได้ทุกอย่างข้ามองค์กรณ์
* Admin: มีสิทธิ์เต็มที่ แต่จำกัดเฉพาะในองค์กรที่ตัวเองสังกัด สามารถจัดการผู้ใช้ในองค์กรณ์ได้ สามารถสร้าง Role ใหม่และกำหนดสิทธิ์ (Permissions) เพิ่มเติมได้ในภายหลังผ่านหน้า Admin
* Document Control สามารถ เพิ่ม/แก้ไข/ลบ เอกสาร เฉพาะในองค์กรณ์ที่ตัวเองสังกัด ไม่สามารถจัดการผู้ใช้ได้
* Editor: สามารถ เพิ่ม/แก้ไข เอกสารที่กำหนดไว้ เฉพาะในองค์กรณ์ที่ตัวเองสังกัด
* Viewer: สามารถดู เอกสาร เฉพาะในองค์กรณ์ที่ตัวเองสังกัด
* 4.4. การบังคับใช้สิทธิ์: สิทธิ์ขององค์กรจะครอบคลุมสิทธิ์ของผู้ใช้ และการเข้าถึงข้อมูลที่เกี่ยวข้องกับโครงการ (เช่น การแก้ไขเอกสาร) จะถูกตรวจสอบเทียบกับสิทธิ์ที่ผู้ใช้มีในโครงการนั้นๆ โดยเฉพาะ
* 4.5. (ใหม่) การจัดการข้อมูลหลัก (Master Data Management):
* ระบบจะต้องมีส่วน "Admin Panel" (สำหรับ Superadmin และ Admin) เพื่อใช้จัดการข้อมูลหลัก (Master Data) ของระบบ
* ข้อมูลหลักที่ต้องจัดการได้เป็นอย่างน้อย:
* ประเภทเอกสาร (เช่น correspondence_types, rfa_types)
* หมวดหมู่แบบ (เช่น shop_drawing_categories)
* Tags ที่ใช้ในระบบ
* สถานะเอกสาร (หากจำเป็นต้องเพิ่มในอนาคต)
* 4.6. (ใหม่) การเริ่มต้นใช้งาน (User & Organization Onboarding):
* การเพิ่มองค์กรณ์ใหม่ (Organizations) เข้าสู่ระบบ จะต้องดำเนินการโดย Superadmin เท่านั้น
* เมื่อ Superadmin สร้างองค์กรณ์ใหม่ จะต้องสามารถกำหนดผู้ใช้ (User) อย่างน้อย 1 คน ให้เป็น "Admin" ประจำองค์กรณ์นั้นๆ
* Admin ประจำองค์กณ์รจึงจะสามารถเพิ่มผู้ใช้ (Editor, Viewer, Document Control) คนอื่นๆ เข้าสู่องค์กรของตนเองได้
## **👥 5\. ข้อกำหนดด้านผู้ใช้งาน (User Interface & Experience)**
* 5.1. Layout หลัก: หน้าเว็บใช้รูปแบบ App Shell ที่ประกอบด้วย:
* Navbar (ส่วนบน): แสดงชื่อระบบ, เมนูผู้ใช้ (Profile), เมนูสำหรับ 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 ที่ผู้ใช้ต้องดำเนินการ
* 5.4. การติดตามสถานะ: องค์กรสามารถติดตามสถานะเอกสารทั้งของตนเอง (Originator) และสถานะเอกสารที่ส่งมาถึงตนเอง (Recipient)
* 5.5. การจัดการข้อมูลส่วนตัว (Profile Page): ผู้ใช้สามารถจัดการข้อมูลส่วนตัวและเปลี่ยนรหัสผ่านของตนเองได้
* 5.6. การจัดการเอกสารทางเทคนิค (Technical Documents & Workflow): ผู้ใช้สามารถดู Technical Document ในรูปแบบ Workflow ทั้งหมดได้ในหน้าเดียว, ขั้นตอนที่ยังไม่ถึงหรือผ่านไปแล้วจะเป็นรูปแบบ diable, สามารถดำเนินการได้เฉพาะในขั้นตอนที่ได้รับมอบหมายงาน (active) เช่น ตรวจสอบแล้ว เพื่อไปยังขั้นตอนต่อไป, สิทธิ์ admin ขึ้นไป สามรถกด ไปยังขั้นตอนต่อไป ได้ทุกขั้นตอน, การย้อนกลับ ไปขั้นตอนก่อนหน้า สามารถทำได้โดย สิทธิ์ admin ขึ้นไป
* 5.7. ข้อกำหนด UI/UX การแนบไฟล์ (File Attachment UX):
* ระบบต้องรองรับการอัปโหลดไฟล์หลายไฟล์พร้อมกัน (Multi-file upload) เช่น การลากและวาง (Drag-and-Drop)
* ในหน้าอัปโหลด (เช่น สร้าง RFA หรือ Correspondence) ผู้ใช้ต้องสามารถกำหนดได้ว่าไฟล์ใดเป็น "เอกสารหลัก" (Main Document เช่น PDF) และไฟล์ใดเป็น "เอกสารแนบประกอบ" (Supporting Attachments เช่น .dwg, .docx, .zip)
## **6. ข้อกำหนดที่ไม่ใช่ฟังก์ชันการทำงาน (Non-Functional Requirements)**
* 6.1. การบันทึกการกระทำ (Audit Log): ทุกการกระทำที่สำคัญของผู้ใช้ (สร้าง, แก้ไข, ลบ, ส่ง) จะถูกบันทึกไว้ใน audit_logs เพื่อการตรวจสอบย้อนหลัง
* 6.2. การค้นหา (Search): ระบบต้องมีฟังก์ชันการค้นหาขั้นสูง ที่สามารถค้นหาเอกสาร **correspondence**, **rfa**, **shop_drawing**, **contract-drawing**, **transmittal** และ **ใบเวียน (Circulations)** จากหลายเงื่อนไขพร้อมกันได้ เช่น ค้นหาจากชื่อเรื่อง, ประเภท, วันที่, และ Tag
* 6.3. การทำรายงาน (Reporting): สามารถจัดทำรายงานสรุปแยกประเภทของ Correspondence ประจำวัน, สัปดาห์, เดือน, และปีได้
* 6.4. ประสิทธิภาพ (Performance): มีการใช้ Caching กับข้อมูลที่เรียกใช้บ่อย และใช้ Pagination ในตารางข้อมูลเพื่อจัดการข้อมูลจำนวนมาก
* 6.5. ความปลอดภัย (Security):
* มีระบบ Rate Limiting เพื่อป้องกันการโจมตีแบบ Brute-force
* การจัดการ Secret (เช่น รหัสผ่าน DB, JWT Secret) จะต้องทำผ่าน Environment Variable ของ Docker เพื่อความปลอดภัยสูงสุด
* 6.6. (ใหม่) การสำรองข้อมูลและการกู้คืน (Backup & Recovery):
* ระบบจะต้องมีกลไกการสำรองข้อมูลอัตโนมัติสำหรับฐานข้อมูล MariaDB [cite: 2.4] และไฟล์เอกสารทั้งหมดใน /share/dms-data [cite: 2.1] (เช่น ใช้ HBS 3 ของ QNAP หรือสคริปต์สำรองข้อมูล) อย่างน้อยวันละ 1 ครั้ง
* ต้องมีแผนการกู้คืนระบบ (Disaster Recovery Plan) ในกรณีที่ Server หลัก (QNAP) ใช้งานไม่ได้
* 6.7. (ใหม่) กลยุทธ์การแจ้งเตือน (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]

775
infrastructure/Markdown/LCBP3-DMS_V1_3_0_Data_Dictionary.md Normal file
View File

@@ -0,0 +1,775 @@
---
# **สรุปตารางฐานข้อมูล (Data Dictionary) - LCBP3-DMS (V1.3.00**
เอกสารนี้สรุปโครงสร้างตาราง, Foreign Keys (FK), และ Constraints ที่สำคัญทั้งหมดในฐานข้อมูล LCBP3-DMS (v1.3.0) เพื่อใช้เป็นเอกสารอ้างอิงสำหรับทีมพัฒนา Backend (NestJS) และ Frontend (Next.js)
## **1\. 🏢 Core & Master Data (องค์กร, โครงการ, สัญญา)**
#### **1.1. organization\_roles**
ตาราง Master เก็บประเภทบทบาทขององค์กร (เช่น OWNER, CONTRACTOR)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| id | INT | **PK** | ID ของตาราง |
| role\_name | VARCHAR(20) | UK | ชื่อบทบาท (OWNER, DESIGNER, CONSULTANT, CONTRACTOR, THIRD PARTY) |
* **Unique Keys (UK):** ux\_roles\_name (role\_name)
#### **1.2. organizations**
ตาราง Master เก็บข้อมูลองค์กรทั้งหมดที่เกี่ยวข้องในระบบ
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| id | INT | **PK** | ID ของตาราง |
| organization\_code | VARCHAR(20) | UK | รหัสองค์กร |
| organization\_name | VARCHAR(255) | | ชื่อองค์กร |
| role\_id | INT | FK | บทบาทขององค์กร (FK \-> organization\_roles(id)) |
| is\_active | BOOLEAN | | สถานะการใช้งาน |
* **Foreign Keys (FK):**
* role\_id \-> organization\_roles(id) (ON DELETE SET NULL)
* **Unique Keys (UK):** ux\_organizations\_code (organization\_code)
#### **1.3. projects**
ตาราง Master เก็บข้อมูลโครงการ (เช่น LCBP3C1, LCBP3C2)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| id | INT | **PK** | ID ของตาราง |
| project\_code | VARCHAR(50) | UK | รหัสโครงการ |
| project\_name | VARCHAR(255) | | ชื่อโครงการ |
| parent\_project\_id | INT | FK | รหัสโครงการหลัก (ถ้ามี) (FK \-> projects(id)) |
| contractor\_organization\_id | INT | FK | รหัสองค์กรผู้รับเหมา (ถ้ามี) (FK \-> organizations(id)) |
| is\_active | TINYINT(1) | | สถานะการใช้งาน |
* **Foreign Keys (FK):**
* parent\_project\_id \-> projects(id) (ON DELETE SET NULL)
* contractor\_organization\_id \-> organizations(id) (ON DELETE SET NULL)
* **Unique Keys (UK):** uq\_pro\_code (project\_code)
#### **1.4. contracts**
ตาราง Master เก็บข้อมูลสัญญา
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| id | INT | **PK** | ID ของตาราง |
| contract\_code | VARCHAR(50) | UK | รหัสสัญญา |
| contract\_name | VARCHAR(255) | | ชื่อสัญญา |
| description | TEXT | | คำอธิบายสัญญา |
* **Unique Keys (UK):** ux\_contracts\_code (contract\_code)
#### **1.5. project\_parties (ตารางเชื่อม)**
ตารางเชื่อมความสัมพันธ์ระหว่าง โครงการ, องค์กร, และบทบาท (M:N)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| project\_id | INT | **PK**, FK | ID ของโครงการ (FK \-> projects(id)) |
| organization\_id | INT | **PK**, FK | ID ขององค์กร (FK \-> organizations(id)) |
| role | ENUM(...) | **PK** | บทบาทในโครงการ (OWNER, DESIGNER, CONSULTANT, CONTRACTOR, THIRD\_PARTY) |
| is\_contractor | TINYINT(1) | UK | (Generated) \= 1 ถ้า role \= 'CONTRACTOR' |
| deleted\_at | DATETIME | | สำหรับ Soft Delete |
* **Foreign Keys (FK):**
* project\_id \-> projects(id) (ON DELETE CASCADE)
* organization\_id \-> organizations(id) (ON DELETE RESTRICT)
* **Unique Keys (UK):**
* uq\_project\_parties\_contractor (project\_id, is\_contractor) \- **(Constraint สำคัญ)** บังคับว่า 1 โครงการมี CONTRACTOR ได้เพียง 1 องค์กร
#### **1.6. contract\_parties (ตารางเชื่อม)**
ตารางเชื่อมความสัมพันธ์ระหว่าง สัญญา, โครงการ, และองค์กร (M:N)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| contract\_id | INT | **PK**, FK | ID ของสัญญา (FK \-> contracts(id)) |
| project\_id | INT | **PK**, FK | ID ของโครงการ (FK \-> projects(id)) |
| organization\_id | INT | **PK**, FK | ID ขององค์กร (FK \-> organizations(id)) |
* **Foreign Keys (FK):**
* contract\_id \-> contracts(id) (ON DELETE CASCADE)
* project\_id \-> projects(id) (ON DELETE CASCADE)
* organization\_id \-> organizations(id) (ON DELETE CASCADE)
---
## **2. 👥 Users & RBAC (ผู้ใช้, สิทธิ์, บทบาท)**
### **2.1. users**
ตาราง Master เก็บข้อมูลผู้ใช้งาน (User)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| user\_id | INT | **PK** | ID ของตาราง |
| username | VARCHAR(50) | UK | ชื่อผู้ใช้งาน |
| password\_hash | VARCHAR(255) | | รหัสผ่าน (Hashed) |
| first\_name | VARCHAR(50) | | ชื่อจริง |
| last\_name | VARCHAR(50) | | นามสกุล |
| email | VARCHAR(100) | UK | อีเมล |
| organization\_id | INT | FK | สังกัดองค์กร (FK \-> organizations(id)) |
| is\_active | TINYINT(1) | | สถานะการใช้งาน |
* **Foreign Keys (FK):**
* organization\_id \-> organizations(id) (ON DELETE SET NULL)
* **Unique Keys (UK):** ux\_users\_username (username), ux\_users\_email (email)
#### **2.2. roles**
ตาราง Master เก็บ "บทบาท" ของผู้ใช้ในระบบ (เช่น SUPER\_ADMIN, ADMIN, EDITOR)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| role\_id | INT | **PK** | ID ของตาราง |
| role\_code | VARCHAR(50) | UK | รหัสบทบาท (เช่น SUPER\_ADMIN, ADMIN, EDITOR, VIEWER) |
| role\_name | VARCHAR(100) | | ชื่อบทบาท |
| is\_system | BOOLEAN | | (1 \= บทบาทของระบบ ลบไม่ได้) |
* **Unique Keys (UK):** role\_code
#### **2.3. permissions**
ตาราง Master เก็บ "สิทธิ์" (Permission) หรือ "การกระทำ" ทั้งหมดในระบบ
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| permission\_id | INT | **PK** | ID ของตาราง |
| permission\_code | VARCHAR(100) | UK | รหัสสิทธิ์ (เช่น rfas.create, rfas.view) |
| module | VARCHAR(50) | | โมดูลที่เกี่ยวข้อง |
| scope\_level | ENUM(...) | | ระดับของสิทธิ์ (GLOBAL, ORG, PROJECT) |
* **Unique Keys (UK):** ux\_permissions\_code (permission\_code)
#### **2.4. role\_permissions (ตารางเชื่อม)**
ตารางเชื่อมระหว่าง roles และ permissions (M:N)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| role\_id | INT | **PK**, FK | ID ของบทบาท (FK \-> roles(role\_id)) |
| permission\_id | INT | **PK**, FK | ID ของสิทธิ์ (FK \-> permissions(permission\_id)) |
* **Foreign Keys (FK):**
* role\_id \-> roles(role\_id) (ON DELETE CASCADE)
* permission\_id \-> permissions(permission\_id) (ON DELETE CASCADE)
#### **2.5. user\_roles (ตารางเชื่อม)**
ตารางเชื่อมผู้ใช้ (users) กับบทบาท (roles) ในระดับ **Global** (M:N)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| user\_id | INT | **PK**, FK | ID ของผู้ใช้ (FK \-> users(user\_id)) |
| role\_id | INT | **PK**, FK | ID ของบทบาท (FK \-> roles(role\_id)) |
* **Foreign Keys (FK):**
* user\_id \-> users(user\_id) (ON DELETE CASCADE)
* role\_id \-> roles(role\_id) (ON DELETE CASCADE)
#### **2.6. user\_project\_roles (ตารางเชื่อม)**
ตารางเชื่อมผู้ใช้ (users) กับบทบาท (roles) ในระดับ **Project-Specific** (M:N)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| user\_id | INT | **PK**, FK | ID ของผู้ใช้ (FK \-> users(user\_id)) |
| project\_id | INT | **PK**, FK | ID ของโครงการ (FK \-> projects(id)) |
| role\_id | INT | **PK**, FK | ID ของบทบาท (FK \-> roles(role\_id)) |
* **Foreign Keys (FK):**
* user\_id \-> users(user\_id) (ON DELETE CASCADE)
* project\_id \-> projects(id) (ON DELETE CASCADE)
* role\_id \-> roles(role\_id) (ON DELETE CASCADE)
---
## **3\. ✉️ Correspondences (เอกสารหลัก, Revisions)**
#### **3.1. correspondence\_types**
ตาราง Master เก็บประเภทเอกสารโต้ตอบ (เช่น RFA, RFI, LETTER, MOM)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| id | INT | **PK** | ID ของตาราง |
| type\_code | VARCHAR(50) | UK | รหัสประเภท (เช่น RFA, RFI) |
| type\_name | VARCHAR(255) | | ชื่อประเภท |
* **Unique Keys (UK):** type\_code
#### **3.2. correspondence\_status**
ตาราง Master เก็บสถานะของเอกสาร (เช่น DRAFT, SUBMITTED, CLOSED)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| id | INT | **PK** | ID ของตาราง |
| status\_code | VARCHAR(50) | UK | รหัสสถานะ (เช่น DRAFT, SUBOWN) |
| status\_name | VARCHAR(255) | | ชื่อสถานะ |
* **Unique Keys (UK):** status\_code
#### **3.3. correspondences (Master)**
ตาราง "แม่" ของเอกสารโต้ตอบ เก็บข้อมูลที่ไม่เปลี่ยนแปลงตาม Revision (เช่น เลขที่เอกสาร)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| id | INT | **PK** | ID ของตาราง (นี่คือ "Master ID" ที่ใช้เชื่อมโยง) |
| correspondence\_number | VARCHAR(100) | UK | เลขที่เอกสาร (สร้างจาก DocumentNumberingModule) |
| correspondence\_type\_id | INT | FK | ประเภทเอกสาร (FK \-> correspondence\_types(id)) |
| is\_internal\_communication | TINYINT(1) | | (1 \= ภายใน, 0 \= ภายนอก) |
| project\_id | INT | FK | อยู่ในโครงการ (FK \-> projects(id)) |
| originator\_id | INT | FK | องค์กรผู้ส่ง (FK \-> organizations(id)) |
| recipient\_id | INT | FK | องค์กรผู้รับ (FK \-> organizations(id)) |
| created\_by | INT | FK | ผู้สร้าง (FK \-> users(user\_id)) |
| deleted\_at | DATETIME | | สำหรับ Soft Delete |
* **Foreign Keys (FK):**
* correspondence\_type\_id \-> correspondence\_types(id) (ON DELETE RESTRICT)
* project\_id \-> projects(id) (ON DELETE CASCADE)
* originator\_id \-> organizations(id) (ON DELETE SET NULL)
* recipient\_id \-> organizations(id) (ON DELETE SET NULL)
* created\_by \-> users(user\_id) (ON DELETE SET NULL)
* **Unique Keys (UK):** uq\_corr\_no\_per\_project (project\_id, correspondence\_number)
#### **3.4. correspondence\_revisions (Revisions)**
ตาราง "ลูก" เก็บประวัติการแก้ไข (Revisions) ของ correspondences (1:N) **(ปรับปรุง V1.2.0)**
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| id | INT | **PK** | **ID ของ Revision** |
| correspondence\_id | INT | FK, UK | Master ID (FK \-> correspondences(id)) |
| revision\_number | INT | UK | หมายเลข Revision (0, 1, 2...) |
| **revision\_label** | **VARCHAR(10)** | | **(ใหม่)** Revision ที่แสดง (เช่น A, B, 1.1) |
| is\_current | BOOLEAN | UK | (1 \= Revision ปัจจุบัน) |
| correspondence\_status\_id | INT | FK | สถานะของ Revision นี้ (FK \-> correspondence\_status(id)) |
| title | VARCHAR(255) | | เรื่อง |
| document\_date | DATE | | วันที่ในเอกสาร |
| issued\_date | DATETIME | | วันที่ออกเอกสาร |
| received\_date | DATETIME | | วันที่ลงรับ |
| **description** | **TEXT** | | **(ใหม่)** คำอธิบายการแก้ไขใน Revision นี้ |
| details | JSON | | ข้อมูลเฉพาะ (เช่น RFI details) |
| **created\_at** | **DATETIME** | | **(ใหม่)** วันที่สร้างเอกสาร |
| created\_by | INT | FK | ผู้สร้าง (FK \-> users(user\_id)) |
| **updated\_by** | **INT** | **FK** | **(ใหม่)** ผู้แก้ไขล่าสุด (FK \-> users(user\_id)) |
* **Foreign Keys (FK):**
* correspondence\_id \-> correspondences(id) (ON DELETE CASCADE)
* correspondence\_status\_id \-> correspondence\_status(id) (ON DELETE RESTRICT)
* created\_by \-> users(user\_id) (ON DELETE SET NULL)
* **updated\_by \-> users(user\_id) (ON DELETE SET NULL)**
* **Unique Keys (UK):**
* uq\_master\_revision\_number (correspondence\_id, revision\_number) (ป้องกัน Rev ซ้ำใน Master เดียว)
* uq\_master\_current (correspondence\_id, is\_current) (ป้องกันการมี is\_current \= TRUE ซ้ำใน Master เดียว)
* **Check Constraints (CHK):** chk\_rev\_format (ตรวจสอบรูปแบบ revision\_label)
#### **3.5. correspondence\_recipients (ตารางเชื่อม)**
ตารางเชื่อมผู้รับ (TO/CC) สำหรับเอกสารแต่ละฉบับ (M:N)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| correspondence\_id | INT | **PK**, FK | ID ของเอกสาร (FK \-> correspondence\_revisions(correspondence\_id)) |
| recipient\_organization\_id | INT | **PK**, FK | ID องค์กรผู้รับ (FK \-> organizations(id)) |
| recipient\_type | ENUM('TO', 'CC') | **PK** | ประเภทผู้รับ (TO หรือ CC) |
* **Foreign Keys (FK):**
* correspondence\_id \-> correspondence\_revisions(correspondence\_id) (ON DELETE CASCADE)
* recipient\_organization\_id \-> organizations(id) (ON DELETE RESTRICT)
#### **3.6. correspondence\_references (ตารางเชื่อม)**
ตารางเชื่อมการอ้างอิงระหว่างเอกสาร (M:N)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| src\_correspondence\_id | INT | **PK**, FK | ID เอกสารต้นทาง (FK \-> correspondences(id)) |
| tgt\_correspondence\_id | INT | **PK**, FK | ID เอกสารเป้าหมาย (FK \-> correspondences(id)) |
* **Foreign Keys (FK):**
* src\_correspondence\_id \-> correspondences(id) (ON DELETE CASCADE)
* tgt\_correspondence\_id \-> correspondences(id) (ON DELETE CASCADE)
#### **3.7. correspondence\_routing\_templates / ...\_steps / ...\_routings**
ตารางที่เกี่ยวข้องกับ Workflow การส่งต่อเอกสาร (Req 3.5.4)
* **correspondence\_routing\_templates:** ตาราง Master เก็บแม่แบบสายงาน (เช่น "ส่งให้ CSC ตรวจสอบ")
* **correspondence\_routing\_template\_steps:** ตารางลูก เก็บขั้นตอนในแม่แบบ (เช่น Step 1: ส่งไป Org A, Step 2: ส่งไป Org B)
* **correspondence\_routings:** ตารางประวัติ (Log) การส่งต่อของเอกสารจริงตาม Workflow
---
## **4\. approval: RFA (เอกสารขออนุมัติ, Workflows)**
#### **4.1. rfa\_types / ...\_status\_codes / ...\_approve\_codes**
ตาราง Master สำหรับ RFA
* **rfa\_types:** ประเภท RFA (เช่น DWG, DOC, MAT)
* **rfa\_status\_codes:** สถานะ RFA (เช่น DFT \- Draft, FAP \- For Approve)
* **rfa\_approve\_codes:** รหัสผลการอนุมัติ (เช่น 1A \- Approved, 3R \- Revise and Resubmit)
#### **4.2. rfas (Master)**
ตาราง "แม่" ของ RFA (มีความสัมพันธ์ 1:N กับ rfa\_revisions)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| id | INT | **PK** | ID ของตาราง (RFA Master ID) |
| rfa\_type\_id | INT | FK | ประเภท RFA (FK \-> rfa\_types(id)) |
| revision\_number | INT | | หมายเลข Revision ล่าสุด (ข้อมูลนี้ถูกย้ายไป rfa\_revisions) |
| created\_by | INT | FK | ผู้สร้าง (FK \-> users(user\_id)) |
| deleted\_at | DATETIME | | สำหรับ Soft Delete |
* **Foreign Keys (FK):**
* rfa\_type\_id \-> rfa\_types(id)
* created\_by \-> users(user\_id) (ON DELETE SET NULL)
#### **4.3. rfa\_revisions (Revisions)**
ตาราง "ลูก" เก็บประวัติ (Revisions) ของ rfas (1:N) **(ปรับปรุง V1.2.0)**
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| id | INT | **PK** | **ID ของ Revision** |
| correspondence\_id | INT | FK | Master ID ของ Correspondence (FK \-> correspondences(id)) |
| rfa\_id | INT | FK, UK | Master ID ของ RFA (FK \-> rfas(id)) |
| revision\_number | INT | UK | หมายเลข Revision (0, 1, 2...) |
| **revision\_label** | **VARCHAR(10)** | | **(ใหม่)** Revision ที่แสดง (เช่น A, B, 1.1) |
| is\_current | BOOLEAN | UK | (1 \= Revision ปัจจุบัน) |
| rfa\_status\_code\_id | INT | FK | สถานะ RFA (FK \-> rfa\_status\_codes(id)) |
| rfa\_approve\_code\_id | INT | FK | ผลการอนุมัติ (FK \-> rfa\_approve\_codes(id)) |
| title | VARCHAR(255) | | เรื่อง |
| **document\_date** | **DATE** | | **(ใหม่)** วันที่ในเอกสาร |
| **issued\_date** | **DATE** | | **(ใหม่)** วันที่ส่งขออนุมัติ |
| **received\_date** | **DATETIME** | | **(ใหม่)** วันที่ลงรับเอกสาร |
| **approved\_date** | **DATE** | | **(ใหม่)** วันที่อนุมัติ |
| **description** | **TEXT** | | **(ใหม่)** คำอธิบายการแก้ไขใน Revision นี้ |
| **created\_at** | **DATETIME** | | **(ใหม่)** วันที่สร้างเอกสาร |
| created\_by | INT | FK | ผู้สร้าง (FK \-> users(user\_id)) |
| **updated\_by** | **INT** | **FK** | **(ใหม่)** ผู้แก้ไขล่าสุด (FK \-> users(user\_id)) |
* **Foreign Keys (FK):**
* correspondence\_id \-> correspondences(id) (ON DELETE CASCADE)
* rfa\_id \-> rfas(id) (ON DELETE CASCADE)
* rfa\_status\_code\_id \-> rfa\_status\_codes(id)
* rfa\_approve\_code\_id \-> rfa\_approve\_codes(id) (ON DELETE SET NULL)
* created\_by \-> users(user\_id) (ON DELETE SET NULL)
* **updated\_by \-> users(user\_id) (ON DELETE SET NULL)**
* **Unique Keys (UK):**
* uq\_rr\_rev\_number (rfa\_id, revision\_number) (ป้องกัน Rev ซ้ำใน Master เดียว)
* uq\_rr\_current (rfa\_id, is\_current) (ป้องกัน is\_current=TRUE ซ้ำใน Master เดียว)
#### **4.4. rfa\_items (ตารางเชื่อม)**
ตารางเชื่อมระหว่าง rfa\_revisions (ที่เป็นประเภท DWG) กับ shop\_drawing\_revisions (M:N)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| rfarev\_correspondence\_id | INT | **PK**, FK | ID ของ RFA Revision (FK \-> rfa\_revisions(correspondence\_id)) |
| shop\_drawing\_revision\_id | INT | **PK**, UK, FK | ID ของ Shop Drawing Revision (FK \-> shop\_drawing\_revisions(id)) |
* **Foreign Keys (FK):**
* rfarev\_correspondence\_id \-> rfa\_revisions(correspondence\_id) (ON DELETE CASCADE)
* shop\_drawing\_revision\_id \-> shop\_drawing\_revisions(id) (ON DELETE CASCADE)
#### **4.5. rfa\_workflow\_templates / ...\_steps / ...\_workflows**
ตารางที่เกี่ยวข้องกับ Workflow การอนุมัติ RFA
* **rfa\_workflow\_templates:** ตาราง Master เก็บแม่แบบสายอนุมัติ (เช่น "สายอนุมัติ 3 ขั้นตอน")
* **rfa\_workflow\_template\_steps:** ตารางลูก เก็บขั้นตอนในแม่แบบ (เช่น Step 1: Org A (Review), Step 2: Org B (Approve))
* **rfa\_workflows:** ตารางประวัติ (Log) การอนุมัติของ RFA จริงตามสายงาน
---
## **5\. 📐 Drawings (แบบ, หมวดหมู่)**
#### **5.1. contract\_drawing\_volumes / ...\_cats / ...\_sub\_cats**
ตาราง Master สำหรับ "แบบคู่สัญญา" (Contract Drawings)
* **contract\_drawing\_volumes:** เก็บ "เล่ม" ของแบบ
* **contract\_drawing\_cats:** เก็บ "หมวดหมู่หลัก" ของแบบ
* **contract\_drawing\_sub\_cats:** เก็บ "หมวดหมู่ย่อย" ของแบบ
#### **5.2. contract\_drawing\_subcat\_cat\_maps (ตารางเชื่อม - ใหม่)**
**(ใหม่)** ตารางเชื่อมระหว่าง หมวดหมู่หลัก-ย่อย (M:N)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| project\_id | INT | **PK**, FK | ID ของโครงการ |
| sub\_cat\_id | INT | **PK**, FK | ID ของหมวดหมู่ย่อย |
| cat\_id | INT | **PK**, FK | ID ของหมวดหมู่หลัก |
* **Foreign Keys (FK) (ตามเจตนา):**
* (project\_id, sub\_cat\_id) \-> contract\_drawing\_sub\_cats(project\_id, id)
* (project\_id, cat\_id) \-> contract\_drawing\_cats(project\_id, id)
* **Unique Keys (UK):**
* ux\_map\_unique (project\_id, sub\_cat\_id, cat\_id)
* ***ข้อสังเกตจาก DBA:*** *สคริปต์ SQL (1.3.6) มีการอ้างอิง FK ไปยังตารางและคอลัมน์ (`contract_dwg_sub_cat(project_id, sub_cat_id)`) ที่ไม่มีอยู่จริง ตารางนี้แสดงตามเจตนาที่ถูกต้อง*
#### **5.3. contract\_drawings (Master)**
ตาราง Master เก็บข้อมูล "แบบคู่สัญญา"
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| id | INT | **PK** | ID ของตาราง |
| project\_id | INT | FK, UK | โครงการ (FK \-> projects(id)) |
| condwg\_no | VARCHAR(255) | UK | เลขที่แบบสัญญา |
| title | VARCHAR(255) | | ชื่อแบบ |
| sub\_cat\_id | INT | FK | หมวดหมู่ย่อย (FK \-> contract\_drawing\_sub\_cats(id)) |
| volume\_id | INT | FK | เล่ม (FK \-> contract\_drawing\_volumes(id)) |
* **Foreign Keys (FK):**
* fk\_condwg\_project (project\_id) \-> projects(id) (ON DELETE CASCADE)
* fk\_condwg\_subcat\_same\_project (project\_id, sub\_cat\_id) \-> contract\_drawing\_sub\_cats(project\_id, id)
* fk\_condwg\_volume\_same\_project (project\_id, volume\_id) \-> contract\_drawing\_volumes(project\_id, id)
* **Unique Keys (UK):** ux\_condwg\_no\_project (project\_id, condwg\_no)
#### **5.4. shop\_drawing\_main\_categories / ...\_sub\_categories**
ตาราง Master สำหรับ "แบบก่อสร้าง" (Shop Drawings)
* **shop\_drawing\_main\_categories:** เก็บ "หมวดหมู่หลัก" (เช่น ARCH, STR)
* **shop\_drawing\_sub\_categories:** เก็บ "หมวดหมู่ย่อย" (เช่น STR-COLUMN)
#### **5.5. shop\_drawings (Master)**
ตาราง Master เก็บข้อมูล "แบบก่อสร้าง"
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| id | INT | **PK** | ID ของตาราง |
| project\_id | INT | FK | โครงการ (FK \-> projects(id)) |
| drawing\_number | VARCHAR(100) | UK | เลขที่ Shop Drawing |
| title | VARCHAR(500) | | ชื่อแบบ |
| main\_category\_id | INT | FK | หมวดหมู่หลัก (FK \-> shop\_drawing\_main\_categories(id)) |
| sub\_category\_id | INT | FK | หมวดหมู่ย่อย (FK \-> shop\_drawing\_sub\_categories(id)) |
* **Foreign Keys (FK):** project\_id, main\_category\_id, sub\_category\_id
* **Unique Keys (UK):** ux\_sd\_drawing\_number (drawing\_number)
#### **5.6. shop\_drawing\_revisions (Revisions)**
ตาราง "ลูก" เก็บประวัติ (Revisions) ของ shop\_drawings (1:N)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| id | INT | **PK** | ID ของ Revision |
| shop\_drawing\_id | INT | FK, UK | Master ID (FK \-> shop\_drawings(id)) |
| revision\_number | VARCHAR(10) | UK | หมายเลข Revision (เช่น A, B, 0, 1) |
| revision\_date | DATE | | วันที่ของ Revision |
| description | TEXT | | คำอธิบายการแก้ไข |
* **Foreign Keys (FK):**
* shop\_drawing\_id \-> shop\_drawings(id) (ON DELETE CASCADE)
* **Unique Keys (UK):** ux\_sd\_rev\_drawing\_revision (shop\_drawing\_id, revision\_number)
#### **5.7. shop\_drawing\_revision\_contract\_refs (ตารางเชื่อม)**
ตารางเชื่อมระหว่าง shop\_drawing\_revisions กับ contract\_drawings (M:N)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| shop\_drawing\_revision\_id | INT | FK | ID ของ Shop Drawing Revision (FK \-> shop\_drawing\_revisions(id)) |
| contract\_drawing\_id | INT | FK | ID ของ Contract Drawing (FK \-> contract\_drawings(id)) |
* **Foreign Keys (FK):** shop\_drawing\_revision\_id, contract\_drawing\_id
---
## **6\. 🔄 Circulations (ใบเวียนภายใน)**
#### **6.1. circulation\_status\_codes**
ตาราง Master เก็บสถานะใบเวียน (เช่น OPEN, IN\_REVIEW, COMPLETED)
#### **6.2. circulations (Master)**
ตาราง "แม่" ของใบเวียนเอกสารภายใน
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| id | INT | **PK** | ID ของตาราง |
| correspondence\_id | INT | UK, FK | เอกสารที่ใช้อ้างอิง (FK \-> correspondences(id)) |
| organization\_id | INT | FK, UK | องค์กรเจ้าของใบเวียน (FK \-> organizations(id)) |
| circulation\_no | VARCHAR(100) | UK | เลขที่ใบเวียน |
| circulation\_subject | VARCHAR(500) | | เรื่อง |
| circulation\_status\_code | VARCHAR(20) | FK | สถานะใบเวียน (FK \-> circulation\_status\_codes(code)) |
| created\_by\_user\_id | INT | FK | ผู้สร้าง (FK \-> users(user\_id)) |
* **Foreign Keys (FK):** correspondence\_id, organization\_id, circulation\_status\_code, created\_by\_user\_id
* **Unique Keys (UK):**
* correspondence\_id (1 ใบเวียน ต่อ 1 เอกสาร)
* uq\_cir\_org\_no (organization\_id, circulation\_no) (เลขที่ใบเวียนห้ามซ้ำในองค์กร)
#### **6.3. circulation\_recipients / ...\_assignees / ...\_actions**
ตาราง "ลูก" ของ circulations
* **circulation\_recipients:** รายชื่อผู้รับ (TO/CC) ภายในองค์กร
* **circulation\_assignees:** รายชื่อผู้รับผิดชอบ (MAIN, ACTION, INFO) และเก็บ deadline
* **circulation\_actions:** ประวัติการดำเนินการ (เช่น Comment, Forward, Close)
* **circulation\_action\_documents:** ตารางเชื่อม circulation\_actions กับ attachments (ไฟล์แนบระหว่างดำเนินการ)
#### **6.4. circulation\_templates / ...\_assignees**
ตารางสำหรับแม่แบบใบเวียน (Templates)
* **circulation\_templates:** ตาราง Master เก็บแม่แบบใบเวียน
* **circulation\_template\_assignees:** ตารางลูก เก็บผู้รับผิดชอบที่กำหนดไว้ล่วงหน้าในแม่แบบ
---
## **7\. 📤 Transmittals (เอกสารนำส่ง)**
#### **7.1. transmittals**
ตารางข้อมูลเฉพาะของเอกสารนำส่ง (เป็นตารางลูก 1:1 ของ correspondences)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| correspondence\_id | INT | **PK**, FK | ID ของเอกสาร (FK \-> correspondences(id)) |
| purpose | ENUM(...) | | วัตถุประสงค์ (FOR\_APPROVAL, FOR\_INFORMATION, ...) |
| remarks | TEXT | | หมายเหตุ |
* **Foreign Keys (FK):** correspondence\_id \-> correspondences(id) (ON DELETE CASCADE)
#### **7.2. transmittal\_items (ตารางเชื่อม)**
ตารางเชื่อมระหว่าง transmittals และเอกสารที่นำส่ง (M:N) **(ปรับปรุง V1.2.0)**
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| **id** | **INT** | **PK** | **(ใหม่)** ID ของรายการ |
| transmittal\_id | INT | **FK**, UK | ID ของ Transmittal (FK \-> transmittals(correspondence\_id)) |
| **item\_correspondence\_id** | **INT** | **FK**, UK | **(เปลี่ยน)** ID ของเอกสารที่แนบไป (FK \-> correspondences(id)) |
| **quantity** | **INT** | | **(ใหม่)** จำนวน |
| **remarks** | **VARCHAR(255)** | | **(ใหม่)** หมายเหตุสำหรับรายการนี้ |
* **Foreign Keys (FK):**
* transmittal\_id \-> transmittals(correspondence\_id) (ON DELETE CASCADE)
* **item\_correspondence\_id \-> correspondences(id) (ON DELETE CASCADE)**
* **Unique Keys (UK):** ux\_transmittal\_item (transmittal\_id, item\_correspondence\_id)
---
## **8\. 📎 File Management (ไฟล์แนบ)**
#### **8.1. attachments (Master)**
ตาราง "กลาง" เก็บไฟล์แนบทั้งหมดของระบบ
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| id | INT | **PK** | ID ของไฟล์แนบ |
| original\_filename | VARCHAR(255) | | ชื่อไฟล์ดั้งเดิม |
| stored\_filename | VARCHAR(255) | | ชื่อไฟล์ที่เก็บจริง (ป้องกันซ้ำ) |
| file\_path | VARCHAR(500) | | Path ที่เก็บไฟล์ (บน QNAP /share/dms-data/) |
| mime\_type | VARCHAR(100) | | ประเภทไฟล์ (เช่น application/pdf) |
| file\_size | INT | | ขนาดไฟล์ (bytes) |
| uploaded\_by\_user\_id | INT | FK | ผู้อัปโหลด (FK \-> users(user\_id)) |
* **Foreign Keys (FK):** uploaded\_by\_user\_id \-> users(user\_id) (ON DELETE CASCADE)
#### **8.2. correspondence\_attachments (ตารางเชื่อม - ใหม่)**
ตารางเชื่อม correspondences กับ attachments (M:N)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| correspondence\_id | INT | **PK**, FK | ID ของเอกสาร (FK \-> correspondences(id)) |
| attachment\_id | INT | **PK**, FK | ID ของไฟล์แนบ (FK \-> attachments(id)) |
| is\_main\_document | BOOLEAN | | (1 \= ไฟล์หลัก) |
* **Foreign Keys (FK):** correspondence\_id, attachment\_id
#### **8.3. circulation\_attachments (ตารางเชื่อม - ใหม่)**
ตารางเชื่อม circulations กับ attachments (M:N)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| circulation\_id | INT | **PK**, FK | ID ของใบเวียน (FK \-> circulations(id)) |
| attachment\_id | INT | **PK**, FK | ID ของไฟล์แนบ (FK \-> attachments(id)) |
| is\_main\_document | BOOLEAN | | (1 \= ไฟล์หลัก) |
* **Foreign Keys (FK):** circulation\_id, attachment\_id
#### **8.4. shop\_drawing\_revision\_attachments (ตารางเชื่อม - ใหม่)**
ตารางเชื่อม shop\_drawing\_revisions กับ attachments (M:N) **(ปรับปรุง V1.2.0)**
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| shop\_drawing\_revision\_id | INT | **PK**, FK | ID ของ Drawing Revision (FK \-> shop\_drawing\_revisions(id)) |
| attachment\_id | INT | **PK**, FK | ID ของไฟล์แนบ (FK \-> attachments(id)) |
| file\_type | ENUM(...) | | ประเภทไฟล์ (PDF, DWG, SOURCE, OTHER) |
| **is\_main\_document** | **BOOLEAN** | | **(ใหม่)** (1 \= ไฟล์หลัก) |
* **Foreign Keys (FK):** shop\_drawing\_revision\_id, attachment\_id
#### **8.5. contract\_drawing\_attachments (ตารางเชื่อม - ใหม่)**
**(ใหม่)** ตารางเชื่อม contract\_drawings กับ attachments (M:N)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| contract\_drawing\_id | INT | **PK**, FK | ID ของ Contract Drawing (FK \-> contract\_drawings(id)) |
| attachment\_id | INT | **PK**, FK | ID ของไฟล์แนบ (FK \-> attachments(id)) |
| file\_type | ENUM(...) | | ประเภทไฟล์ (PDF, DWG, SOURCE, OTHER) |
| is\_main\_document | BOOLEAN | | (1 \= ไฟล์หลัก) |
* **Foreign Keys (FK):**
* contract\_drawing\_id \-> contract\_drawings(id) (ON DELETE CASCADE)
* attachment\_id \-> attachments(id) (ON DELETE CASCADE)
---
## **9\. 🔢 Document Numbering (การสร้างเลขที่เอกสาร)**
#### **9.1. document\_number\_formats (ตารางตั้งค่า - ใหม่)**
ตาราง Master เก็บ "รูปแบบ" Template ของเลขที่เอกสาร
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| id | INT | **PK** | ID ของตาราง |
| project\_id | INT | FK, UK | โครงการ (FK \-> projects(id)) |
| correspondence\_type\_id | INT | FK, UK | ประเภทเอกสาร (FK \-> correspondence\_types(id)) |
| format\_template | VARCHAR(255) | | รูปแบบ Template (เช่น {ORG\_CODE}-{TYPE\_CODE}-{SEQ:4}) |
* **Foreign Keys (FK):** project\_id, correspondence\_type\_id
* **Unique Keys (UK):** uk\_project\_type (project\_id, correspondence\_type\_id)
#### **9.2. document\_number\_counters (ตารางตัวนับ - ใหม่)**
ตารางเก็บ "ตัวนับ" (Running Number) ล่าสุด
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| project\_id | INT | **PK**, FK | โครงการ (FK \-> projects(id)) |
| originator\_organization\_id | INT | **PK**, FK | องค์กรผู้ส่ง (FK \-> organizations(id)) |
| correspondence\_type\_id | INT | **PK**, FK | ประเภทเอกสาร (FK \-> correspondence\_types(id)) |
| current\_year | INT | **PK** | ปี ค.ศ. ของตัวนับ |
| last\_number | INT | | เลขที่ล่าสุดที่ใช้ไป |
* **Foreign Keys (FK):** project\_id, originator\_organization\_id, correspondence\_type\_id
---
## **10\. ⚙️ System & Logs (ระบบและ Log)**
#### **10.1. tags**
ตาราง Master เก็บ Tags ทั้งหมดที่ใช้ในระบบ
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| id | INT | **PK** | ID ของตาราง |
| tag\_name | VARCHAR(100) | UK | ชื่อ Tag |
* **Unique Keys (UK):** ux\_tag\_name (tag\_name)
#### **10.2. correspondence\_tags (ตารางเชื่อม)**
ตารางเชื่อมระหว่าง correspondences และ tags (M:N)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| correspondence\_id | INT | **PK**, FK | ID ของเอกสาร (FK \-> correspondences(id)) |
| tag\_id | INT | **PK**, FK | ID ของ Tag (FK \-> tags(id)) |
* **Foreign Keys (FK):** correspondence\_id, tag\_id
#### **10.3. audit\_logs**
ตารางเก็บบันทึกการกระทำของผู้ใช้
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| audit\_id | BIGINT | **PK** | ID ของ Log |
| user\_id | INT | FK | ผู้กระทำ (FK \-> users(user\_id)) |
| action | VARCHAR(100) | | การกระทำ (เช่น rfa.create) |
| entity\_type | VARCHAR(50) | | ตาราง/โมดูล (เช่น rfas) |
| entity\_id | VARCHAR(50) | | ID ของสิ่งที่ถูกกระทำ |
| details\_json | JSON | | ข้อมูลเพิ่มเติม |
| ip\_address | VARCHAR(45) | | IP Address |
| created\_at | TIMESTAMP | | เวลาที่กระทำ |
* **Foreign Keys (FK):** user\_id \-> users(user\_id) (ON DELETE SET NULL)
#### **10.4. global\_default\_roles (ใหม่)**
ตารางเก็บค่าเริ่มต้นของบทบาทองค์กร (เช่น OWNER, DESIGNER)
| Column | Type | Key | Description |
| :--- | :--- | :--- | :--- |
| id | TINYINT | **PK** | ID คงที่ ( \= 1) |
| role | ENUM(...) | **PK** | บทบาท (OWNER, DESIGNER, CONSULTANT) |
| position | TINYINT | **PK** | ลำดับที่ในบทบาท (1..n) |
| organization\_id | INT | FK, UK | ID องค์กร (FK \-> organizations(id)) |
* **Foreign Keys (FK):** organization\_id \-> organizations(id) (ON DELETE RESTRICT)
* **Unique Keys (UK):** ux\_gdr\_unique\_org\_per\_role (id, role, organization\_id)
#### **10.5. Workflow Transition Rules (ใหม่)**
ตารางกำหนด Business Rules สำหรับการเปลี่ยนสถานะ
* **correspondence\_status\_transitions:** (ใหม่) กฎการเปลี่ยนสถานะของ Correspondences (ทั่วไป)
* **rfa\_status\_transitions:** (ใหม่) กฎการเปลี่ยนสถานะของ RFA
* **circulation\_status\_transitions:** (ใหม่) กฎการเปลี่ยนสถานะของ Circulations (ใบเวียน)
---
## **11\. 📋 Views & Procedures (วิว และ โปรซีเดอร์)**
#### **11.1. sp\_get\_next\_document\_number (Procedure)**
**(ใหม่)** Stored Procedure เดียวที่ใช้ในระบบ
* **หน้าที่:** ดึงเลขที่เอกสารถัดไป (Next Running Number) จากตาราง document\_number\_counters
* **ตรรกะ:** ใช้ `SELECT ... FOR UPDATE` เพื่อ "ล็อก" แถว ป้องกัน Race Condition (การที่ผู้ใช้ 2 คนได้เลขที่ซ้ำกัน)
#### **11.2. v\_current\_correspondences (View)**
* **หน้าที่:** แสดง Revision "ปัจจุบัน" (is\_current \= TRUE) ของ correspondences ทั้งหมด (ที่ไม่ใช่ RFA)
#### **11.3. v\_current\_rfas (View)**
* **หน้าที่:** แสดง Revision "ปัจจุบัน" (is\_current \= TRUE) ของ rfa\_revisions ทั้งหมด
#### **11.4. v\_contract\_parties\_all (View)**
* **หน้าที่:** แสดงความสัมพันธ์ทั้งหมดระหว่าง Contract, Project, และ Organization
#### **11.5. v\_user\_tasks (View)**
**(ใหม่)**
* **หน้าที่:** แสดงรายการ "งานของฉัน" (My Tasks) ที่ยังไม่เสร็จ
* **ตรรกะ:** JOIN ตาราง circulations กับ circulation\_assignees (ที่ is\_completed \= FALSE)
#### **11.6. v\_audit\_log\_details (View)**
**(ใหม่)**
* **หน้าที่:** แสดง audit\_logs พร้อมข้อมูล username และ email ของผู้กระทำ
#### **11.7. v\_user\_all\_permissions (View)**
**(ใหม่)**
* **หน้าที่:** รวมสิทธิ์ทั้งหมด (Global \+ Project) ของผู้ใช้ทุกคน เพื่อให้ Backend ตรวจสอบสิทธิ์ได้ง่าย
* **ตรรกะ:** UNION ข้อมูลจาก user\_roles และ user\_project\_roles

478
infrastructure/Markdown/LCBP3-DMS_V1_3_0_FullStackJS.md Normal file
View File

@@ -0,0 +1,478 @@
# **Documents Management Sytem Version 1.3.0: แนวทางการพัฒนา FullStackJS**
## **🧠 ปรัชญาทั่วไป**
แนวทางปฏิบัติที่ดีที่สุดแบบครบวงจรสำหรับการพัฒนา NestJS Backend, NextJS Frontend และ Tailwind-based UI/UX ในสภาพแวดล้อม TypeScript มุ่งเน้นที่ ความชัดเจน (clarity), ความง่ายในการบำรุงรักษา (maintainability), ความสอดคล้องกัน (consistency) และ การเข้าถึงได้ (accessibility) ตลอดทั้งสแต็ก
## **⚙️ แนวทางทั่วไปสำหรับ TypeScript**
### **หลักการพื้นฐาน**
* ใช้ **ภาษาอังกฤษ** สำหรับโค้ด
* ใช้ **ภาษาไทย** สำหรับ comment และเอกสารทั้งหมด
* กำหนดไทป์ (type) อย่างชัดเจนสำหรับตัวแปร, พารามิเตอร์ และค่าที่ส่งกลับ (return values) ทั้งหมด
* หลีกเลี่ยงการใช้ any; ให้สร้างไทป์ (types) หรืออินเทอร์เฟซ (interfaces) ที่กำหนดเอง
* ใช้ **JSDoc** สำหรับคลาส (classes) และเมธอด (methods) ที่เป็น public
* ส่งออก (Export) **สัญลักษณ์หลัก (main symbol) เพียงหนึ่งเดียว** ต่อไฟล์
* หลีกเลี่ยงบรรทัดว่างภายในฟังก์ชัน
* ระบุ // File: path/filename ในบรรทัดแรกของทุกไฟล์
* ระบุ // บันทึกการแก้ไข, หากมีการแก้ไขเพิ่มในอนาคต ให้เพิ่มบันทึก
### **ข้อตกลงในการตั้งชื่อ (Naming Conventions)**
| Entity (สิ่งที่ตั้งชื่อ) | Convention (รูปแบบ) | Example (ตัวอย่าง) |
| :---- | :---- | :---- |
| Classes | PascalCase | UserService |
| Property | snake_sase | user_id |
| Variables & Functions | camelCase | getUserInfo |
| Files & Folders | kebab-case | user-service.ts |
| Environment Variables | UPPERCASE | DATABASE\URL |
| Booleans | Verb \+ Noun | isActive, canDelete, hasPermission |
ใช้คำเต็ม — ไม่ใช้อักษรย่อ — ยกเว้นคำมาตรฐาน (เช่น API, URL, req, res, err, ctx)
## **🧩 ฟังก์ชัน (Functions)**
* เขียนฟังก์ชันให้สั้น และทำ **หน้าที่เพียงอย่างเดียว** (single-purpose) (\< 20 บรรทัด)
* ใช้ **early returns** เพื่อลดการซ้อน (nesting) ของโค้ด
* ใช้ **map**, **filter**, **reduce** แทนการใช้ loops เมื่อเหมาะสม
* ควรใช้ **arrow functions** สำหรับตรรกะสั้นๆ, และใช้ **named functions** ในกรณีอื่น
* ใช้ **default parameters** แทนการตรวจสอบค่า null
* จัดกลุ่มพารามิเตอร์หลายตัวให้เป็นอ็อบเจกต์เดียว (RO-RO pattern)
* ส่งค่ากลับ (Return) เป็นอ็อบเจกต์ที่มีไทป์กำหนด (typed objects) ไม่ใช่ค่าพื้นฐาน (primitives)
* รักษาระดับของสิ่งที่เป็นนามธรรม (abstraction level) ให้เป็นระดับเดียวในแต่ละฟังก์ชัน
## **🧱 การจัดการข้อมูล (Data Handling)**
* ห่อหุ้มข้อมูล (Encapsulate) ในไทป์แบบผสม (composite types)
* ใช้ **immutability** (การไม่เปลี่ยนแปลงค่า) ด้วย readonly และ as const
* ทำการตรวจสอบความถูกต้องของข้อมูล (Validations) ในคลาสหรือ DTOs ไม่ใช่ภายในฟังก์ชันทางธุรกิจ
* ตรวจสอบความถูกต้องของข้อมูลโดยใช้ DTOs ที่มีไทป์กำหนดเสมอ
## **🧰 คลาส (Classes)**
* ปฏิบัติตามหลักการ **SOLID**
* ควรใช้ **composition มากกว่า inheritance** (Prefer composition over inheritance)
* กำหนด **interfaces** สำหรับสัญญา (contracts)
* ให้คลาสมุ่งเน้นการทำงานเฉพาะอย่างและมีขนาดเล็ก (\< 200 บรรทัด, \< 10 เมธอด, \< 10 properties)
## **🚨 การจัดการข้อผิดพลาด (Error Handling)**
* ใช้ Exceptions สำหรับข้อผิดพลาดที่ไม่คาดคิด
* ดักจับ (Catch) ข้อผิดพลาดเพื่อแก้ไขหรือเพิ่มบริบท (context) เท่านั้น; หากไม่เช่นนั้น ให้ใช้ global error handlers
* ระบุข้อความข้อผิดพลาด (error messages) ที่มีความหมายเสมอ
## **🧪 การทดสอบ (ทั่วไป) (Testing (General))**
* ใช้รูปแบบ **Arrange–Act–Assert**
* ใช้ชื่อตัวแปรในการทดสอบที่สื่อความหมาย (inputData, expectedOutput)
* เขียน **unit tests** สำหรับ public methods ทั้งหมด
* จำลอง (Mock) การพึ่งพาภายนอก (external dependencies)
* เพิ่ม **acceptance tests** ต่อโมดูลโดยใช้รูปแบบ Given–When-Then
## **🏗️ แบ็กเอนด์ (NestJS) (Backend (NestJS))**
### **หลักการ**
* **สถาปัตยกรรมแบบโมดูลาร์ (Modular architecture)**:
* หนึ่งโมดูลต่อหนึ่งโดเมน
* โครงสร้างแบบ Controller → Service → Repository (Model)
* API-First: มุ่งเน้นการสร้าง API ที่มีคุณภาพสูง มีเอกสารประกอบ (Swagger) ที่ชัดเจนสำหรับ Frontend Team
* DTOs ที่ตรวจสอบความถูกต้องด้วย **class-validator**
* ใช้ **MikroORM** (หรือ TypeORM/Prisma) สำหรับการคงอยู่ของข้อมูล (persistence) ซึ่งสอดคล้องกับสคีมา MariaDB
* ห่อหุ้มโค้ดที่ใช้ซ้ำได้ไว้ใน **common module** (@app/common):
* Configs, decorators, DTOs, guards, interceptors, notifications, shared services, types, validators
### **ฟังก์ชันหลัก (Core Functionalities)**
* Global **filters** สำหรับการจัดการ exception
* **Middlewares** สำหรับการจัดการ request
* **Guards** สำหรับการอนุญาต (permissions) และ RBAC
* **Interceptors** สำหรับการแปลงข้อมูล response และการบันทึก log
### **ข้อจำกัดในการ Deploy (QNAP Container Station)**
* **ห้ามใช้ไฟล์ .env** ในการตั้งค่า Environment Variables [cite: 2.1]
* การตั้งค่าทั้งหมด (เช่น Database connection string, JWT secret) **จะต้องถูกกำหนดผ่าน Environment Variable ใน docker-compose.yml โดยตรง** [cite: 6.5] ซึ่งจะจัดการผ่าน UI ของ QNAP Container Station [cite: 2.1]
### **โครงสร้างโมดูลตามโดเมน (Domain-Driven Module Structure)**
เพื่อให้สอดคล้องกับสคีมา SQL (LCBP3-DMS) เราจะใช้โครงสร้างโมดูลแบบ **Domain-Driven (แบ่งตามขอบเขตธุรกิจ)** แทนการแบ่งตามฟังก์ชัน:
1. **CommonModule:**
* เก็บ Services ที่ใช้ร่วมกัน เช่น DatabaseModule, FileStorageService (จัดการไฟล์ใน QNAP), AuditLogService, NotificationService
* จัดการ audit_logs
* NotificationService ต้องรองรับ Triggers ที่ระบุใน Requirement 6.7 [cite: 6.7]
2. **AuthModule:**
* จัดการะการยืนยันตัวตน (JWT, Guards)
* **(สำคัญ)** ต้องรับผิดชอบการตรวจสอบสิทธิ์ **3 ระดับ** [cite: 4.2]: สิทธิ์ระดับระบบ (Global Role), สิทธิ์ระดับโปรเจกต์ (Project Role), และ **สิทธิ์ระดับสัญญา (Contract Role)**
* **(สำคัญ)** ต้องมี API สำหรับ **Admin Panel** เพื่อ:
* สร้างและจัดการ Role และการจับคู่ Permission แบบไดนามิก [cite: 4.3]
* ให้ Superadmin สร้าง Organizations และกำหนด Org Admin ได้ [cite: 4.6]
* ให้ Superadmin/Admin จัดการ document_number_formats (รูปแบบเลขที่เอกสาร), document_number_counters (Running Number) [cite: 3.10]
3. **UserModule:**
* จัดการ users, roles, permissions, global_default_roles, role_permissions, user_roles, user_project_roles
* **(สำคัญ)** ต้องมี API สำหรับ **Admin Panel** เพื่อ:
* สร้างและจัดการ Role และการจับคู่ Permission แบบไดนามิก [cite: 4.3]
4. **ProjectModule:**
* จัดการ projects, organizations, contracts, project_parties, contract_parties
5. **MasterModule:**
* จัดการ master data (correspondence_types, rfa_types, rfa_status_codes, rfa_approve_codes, circulation_status_codes, correspondence_types, correspondence_status, tags) [cite: 4.5]
6. **CorrespondenceModule (โมดูลศูนย์กลาง):**
* จัดการ correspondences, correspondence_revisions, correspondence_tags
* **(สำคัญ)** Service นี้ต้อง Inject DocumentNumberingService เพื่อขอเลขที่เอกสารใหม่ก่อนการสร้าง
* **(สำคัญ)** ตรรกะการสร้าง/อัปเดต Revision จะอยู่ใน Service นี้
* จัดการ correspondence_attachments (ตารางเชื่อมไฟล์แนบ)
* รับผิดชอบเวิร์กโฟลว์ **"Correspondence Routings"** (correspondence_routings, correspondence_routing_templates) สำหรับการส่งต่อเอกสารทั่วไประหว่างองค์กร
7. **RfaModule:**
* จัดการ rfas, rfa_revisions, rfa_items
* รับผิดชอบเวิร์กโฟลว์ **"RFA Workflows"** (rfa_workflows, rfa_workflow_templates, rfa_workflow_template_steps, rfa_status_transitions) สำหรับการอนุมัติเอกสารทางเทคนิค
8. **DrawingModule:**
* จัดการ shop_drawings, shop_drawing_revisions, contract_drawings, contract_drawing_volumes, contract_drawing_cats, contract_drawing_sub_cats, shop_drawing_main_categories, shop_drawing_sub_categories, contract_drawing_subcat_cat_maps, shop_drawing_revision_contract_refs
* จัดการ shop_drawing_revision_attachments และ contract_drawing_attachments(ตารางเชื่อมไฟล์แนบ)
9. **CirculationModule:**
* จัดการ circulations, circulation_templates, circulation_assignees
* จัดการ circulation_attachments (ตารางเชื่อมไฟล์แนบ)
* รับผิดชอบเวิร์กโฟลว์ **"Circulations"** (circulation_status_transitions, circulation_template_assignees, circulation_assignees, circulation_recipients, circulation_actions, circulation_action_documents)สำหรับการเวียนเอกสาร **ภายในองค์กร**
10. **TransmittalModule:**
* จัดการ transmittals และ transmittal_items
11. **SearchModule:**
* ให้บริการค้นหาขั้นสูง (Advanced Search) [cite: 6.2] โดยใช้ **Elasticsearch** เพื่อรองรับการค้นหาแบบ Full-text จากชื่อเรื่อง, รายละเอียด, เลขที่เอกสาร, ประเภท, วันที่, และ Tags
12. **DocumentNumberingModule:**
* **สถานะ:** เป็น Module ภายใน (Internal Module) ไม่เปิด API สู่ภายนอก
* **หน้าที่:** ให้บริการ DocumentNumberingService ที่ Module อื่น (เช่น CorrespondenceModule) จะ Inject ไปใช้งาน
* **ตรรกะ:** รับผิดชอบการสร้างเลขที่เอกสาร โดยการเรียกใช้ Stored Procedure *sp_get_next_document_number** เพื่อป้องกัน Race Condition
### **สถาปัตยกรรมระบบ (System Architecture)**
โครงสร้างโมดูล (Module Structure)
```bash
📁 src
├── 📄 app.module.ts
├── 📄 main.ts
├── 📁 common # @app/common (โมดูลส่วนกลาง)
│ ├── 📁 auth # AuthModule (JWT, Guards)
│ ├── 📁 config # Configuration
│ ├── 📁 decorators # Custom Decorators (เช่น @RequirePermission)
│ ├── 📁 entities # Shared Entities (User, Role, Permission)
│ ├── 📁 exceptions # Global Exception Filters
│ ├── 📁 file-storage # FileStorageService
│ ├── 📁 guards # Custom Guards (RBAC Guard)
│ ├── 📁 interceptors # Interceptors (Audit Log, Transform)
│ └── 📁 services # Shared Services (NotificationService)
├── 📁 modules
│ ├── 📁 user # UserModule (จัดการ Users, Roles, Permissions)
│ ├── 📁 project # ProjectModule (จัดการ Projects, Organizations, Contracts)
│ ├── 📁 correspondence # CorrespondenceModule (จัดการเอกสารโต้ตอบ)
│ ├── 📁 rfa # RfaModule (จัดการเอกสารขออนุมัติ)
│ ├── 📁 drawing # DrawingModule (จัดการแบบแปลน)
│ ├── 📁 circulation # CirculationModule (จัดการใบเวียน)
│ ├── 📁 transmittal # TransmittalModule (จัดการเอกสารนำส่ง)
│ ├── 📁 search # SearchModule (ค้นหาขั้นสูงด้วย Elasticsearch)
│ └── 📁 document-numbering # DocumentNumberingModule (Internal Module)
└── 📁 database # Database Migration & Seeding Scripts
```
### **เเทคโนโลยีที่ใช้ (Technology Stack)**
| ส่วน | Library/Tool | หมายเหตุ |
|---|---|---|
| **Framework** | `@nestjs/core`, `@nestjs/common` | Core Framework |
| **Language** | `TypeScript` | ใช้ TypeScript ทั้งระบบ |
| **Database** | `MariaDB 10.11` | ฐานข้อมูลหลัก |
| **ORM** | `@nestjs/typeorm`, `typeorm` | 🗃️จัดการการเชื่อมต่อและ Query ฐานข้อมูล |
| **Validation** | `class-validator`, `class-transformer` | 📦ตรวจสอบและแปลงข้อมูลใน DTO |
| **Auth** | `@nestjs/jwt`, `@nestjs/passport`, `passport-jwt` | 🔐การยืนยันตัวตนด้วย JWT |
|**Authorization** | `casl` | 🔐จัดการสิทธิ์แบบ RBAC |
| **File Upload** | `multer` | 📁จัดการการอัปโหลดไฟล์ |
| **Search** | `@nestjs/elasticsearch` | 🔍สำหรับการค้นหาขั้นสูง |
| **Notification** | `nodemailer` | 📬ส่งอีเมลแจ้งเตือน |
| **Scheduling** | `@nestjs/schedule` | 📬สำหรับ Cron Jobs (เช่น แจ้งเตือน Deadline) |
| **Logging** | `winston` | 📊บันทึก Log ที่มีประสิทธิภาพ |
| **Testing** | `@nestjs/testing`, `jest`, `supertest` | 🧪ทดสอบ Unit, Integration และ E2E |
| **Documentation** | `@nestjs/swagger` | 🌐สร้าง API Documentation อัตโนมัติ |
| **Security** | `helmet`, `rate-limiter-flexible` | 🛡️เพิ่มความปลอดภัยให้ API |
เราจะแบ่งการทดสอบเป็น 3 ระดับ โดยใช้ **Jest** และ @nestjs/testing:
* **Unit Tests (การทดสอบหน่วยย่อย):**
* **เป้าหมาย:** ทดสอบ Logic ภายใน Service, Guard, หรือ Pipe โดยจำลอง (Mock) Dependencies ทั้งหมด
* **สิ่งที่ต้องทดสอบ:** Business Logic (เช่น การเปลี่ยนสถานะ Workflow, การตรวจสอบ Deadline) [cite: 2.9.1], ตรรกะการตรวจสอบสิทธิ์ (Auth Guard) ทั้ง 3 ระดับ
* **Integration Tests (การทดสอบการบูรณาการ):**
* **เป้าหมาย:** ทดสอบการทำงานร่วมกันของ Controller -> Service -> Repository (Database)
* **เทคนิค:** ใช้ **Test Database แยกต่างหาก** (ห้ามใช้ Dev DB) และใช้ supertest เพื่อยิง HTTP Request จริงไปยัง App
* **สิ่งที่ต้องทดสอบ:** การเรียก sp\get\next\document\number [cite: 2.9.3] และการทำงานของ Views (เช่น v_user_tasks)
* **E2E (End-to-End) Tests:**
* **เป้าหมาย:** ทดสอบ API Contract ว่า Response Body Shape ตรงตามเอกสาร Swagger เพื่อรับประกันทีม Frontend
### **🗄️ Backend State Management**
Backend (NestJS) ควรเป็น **Stateless** (ไม่เก็บสถานะ) "State" ทั้งหมดจะถูกจัดเก็บใน MariaDB
* **Request-Scoped State (สถานะภายใน Request เดียว):**
* **ปัญหา:** จะส่งต่อข้อมูล (เช่น User ที่ล็อกอิน) ระหว่าง Guard และ Service ใน Request เดียวกันได้อย่างไร?
* **วิธีแก้:** ใช้ **Request-Scoped Providers** ของ NestJS (เช่น AuthContextService) เพื่อเก็บข้อมูล User ปัจจุบันที่ได้จาก AuthGuard และให้ Service อื่น Inject ไปใช้
* **Application-Scoped State (การ Caching):**
* **ปัญหา:** ข้อมูล Master (เช่น roles, permissions, organizations) ถูกเรียกใช้บ่อย
* **วิธีแก้:** ใช้ **Caching** (เช่น @nestjs/cache-manager) เพื่อ Caching ข้อมูลเหล่านี้ และลดภาระ Database
### **การไหลของข้อมูล (Data Flow)**
1. Request: ผ่าน Nginx Proxy Manager -> NestJS Controller
2. Authentication: JWT Guard ตรวจสอบ Token และดึงข้อมูล User
3. Authorization: RBAC Guard (ใช้ CASL) ตรวจสอบสิทธิ์จาก Decorators (@RequirePermission)
4. Validation: Validation Pipe (ใช้ class-validator) ตรวจสอบ DTO
5. Business Logic: Service Layer ประมวลผลตรรกะทางธุรกิจ
6. Data Access: Repository Layer (ใช้ TypeORM) ติดต่อกับฐานข้อมูล MariaDB
7. Response: ส่งกลับไปยัง Frontend พร้อมสถานะและข้อมูลที่เหมาะสม
# **🖥️ ฟรอนต์เอนด์ (NextJS / React / UI) (Frontend (NextJS / React / UI))**
### **โปรไฟล์นักพัฒนา (Developer Profile)**
วิศวกร TypeScript + React/NextJS ระดับ Senior
เชี่ยวชาญ TailwindCSS, Shadcn/UI, และ Radix สำหรับการพัฒนา UI
### **แนวทางการพัฒนาโค้ด (Code Implementation Guidelines)**
* ใช้ **early returns** เพื่อความชัดเจน
* ใช้คลาสของ **TailwindCSS** ในการกำหนดสไตล์เสมอ
* ควรใช้ class: syntax แบบมีเงื่อนไข (หรือ utility clsx) มากกว่าการใช้ ternary operators ใน class strings
* ใช้ **const arrow functions** สำหรับ components และ handlers
* Event handlers ให้ขึ้นต้นด้วย handle... (เช่น handleClick, handleSubmit)
* รวมแอตทริบิวต์สำหรับการเข้าถึง (accessibility) ด้วย:
tabIndex="0", aria-label, onKeyDown, ฯลฯ
* ตรวจสอบให้แน่ใจว่าโค้ดทั้งหมด **สมบูรณ์**, **ผ่านการทดสอบ**, และ **ไม่ซ้ำซ้อน (DRY)**
* ต้อง import โมดูลที่จำเป็นต้องใช้อย่างชัดเจนเสมอ
### **UI/UX ด้วย React**
* ใช้ **semantic HTML**
* ใช้คลาสของ **Tailwind** ที่รองรับ responsive (sm:, md:, lg:)
* รักษาลำดับชั้นของการมองเห็น (visual hierarchy) ด้วยการใช้ typography และ spacing
* ใช้ **Shadcn** components (Button, Input, Card, ฯลฯ) เพื่อ UI ที่สอดคล้องกัน
* ทำให้ components มีขนาดเล็กและมุ่งเน้นการทำงานเฉพาะอย่าง
* ใช้ utility classes สำหรับการจัดสไตล์อย่างรวดเร็ว (spacing, colors, text, ฯลฯ)
* ตรวจสอบให้แน่ใจว่าสอดคล้องกับ **ARIA** และใช้ semantic markup
### **การตรวจสอบฟอร์มและข้อผิดพลาด (Form Validation & Errors)**
* ใช้ไลบรารีฝั่ง client เช่น zod และ react-hook-form
* แสดงข้อผิดพลาดด้วย **alert components** หรือข้อความ inline
* ต้องมี labels, placeholders, และข้อความ feedback
### **🧪 Frontend Testing**
เราจะใช้ **React Testing Library (RTL)** สำหรับการทดสอบ Component และ **Playwright** สำหรับ E2E:
* **Unit Tests (การทดสอบหน่วยย่อย):**
* **เครื่องมือ:** Vitest + RTL
* **เป้าหมาย:** ทดสอบ Component ขนาดเล็ก (เช่น Buttons, Inputs) หรือ Utility functions
* **Integration Tests (การทดสอบการบูรณาการ):**
* **เครื่องมือ:** RTL + **Mock Service Worker (MSW)**
* **เป้าหมาย:** ทดสอบว่า Component หรือ Page ทำงานกับ API (ที่จำลองขึ้น) ได้ถูกต้อง
* **เทคนิค:** ใช้ MSW เพื่อจำลอง NestJS API และทดสอบว่า Component แสดงผลข้อมูลจำลองได้ถูกต้องหรือไม่ (เช่น ทดสอบหน้า Dashboard [cite: 5.3] ที่ดึงข้อมูลจาก v_user_tasks)
* **E2E (End-to-End) Tests:**
* **เครื่องมือ:** **Playwright**
* **เป้าหมาย:** ทดสอบ User Flow ทั้งระบบโดยอัตโนมัติ (เช่น ล็อกอิน -> สร้าง RFA -> ตรวจสอบ Workflow Visualization [cite: 5.6])
### **🗄️ Frontend State Management**
สำหรับ Next.js App Router เราจะแบ่ง State เป็น 4 ระดับ:
1. **Local UI State (สถานะ UI ชั่วคราว):**
* **เครื่องมือ:** useState, useReducer
* **ใช้เมื่อ:** จัดการสถานะเล็กๆ ที่จบใน Component เดียว (เช่น Modal เปิด/ปิด, ค่าใน Input)
2. **Server State (สถานะข้อมูลจากเซิร์ฟเวอร์):**
* **เครื่องมือ:** **React Query (TanStack Query)** หรือ SWR
* **ใช้เมื่อ:** จัดการข้อมูลที่ดึงมาจาก NestJS API (เช่น รายการ correspondences, rfas, drawings)
* **ทำไม:** React Query เป็น "Cache" ที่จัดการ Caching, Re-fetching, และ Invalidation ให้โดยอัตโนมัติ
3. **Global Client State (สถานะส่วนกลางฝั่ง Client):**
* **เครื่องมือ:** **Zustand** (แนะนำ) หรือ Context API
* **ใช้เมื่อ:** จัดการข้อมูลที่ต้องใช้ร่วมกันทั่วทั้งแอป และ *ไม่ใช่* ข้อมูลจากเซิร์ฟเวอร์ (เช่น ข้อมูล User ที่ล็อกอิน, สิทธิ์ Permissions)
4. **Form State (สถานะของฟอร์ม):**
* **เครื่องมือ:** **React Hook Form** + **Zod**
* **ใช้เมื่อ:** จัดการฟอร์มที่ซับซ้อน (เช่น ฟอร์มสร้าง RFA, ฟอร์ม Circulation [cite: 3.7])
# **🔗 แนวทางการบูรณาการ Full Stack (Full Stack Integration Guidelines)**
| Aspect (แง่มุม) | Backend (NestJS) | Frontend (NextJS) | UI Layer (Tailwind/Shadcn) |
| :---- | :---- | :---- | :---- |
| API | REST / GraphQL Controllers | API hooks ผ่าน fetch/axios/SWR | Components ที่รับข้อมูล |
| Validation (การตรวจสอบ) | class-validator DTOs | zod / react-hook-form | สถานะของฟอร์ม/input ใน Shadcn |
| Auth (การยืนยันตัวตน) | Guards, JWT | NextAuth / cookies | สถานะ UI ของ Auth (loading, signed in) |
| Errors (ข้อผิดพลาด) | Global filters | Toasts / modals | Alerts / ข้อความ feedback |
| Testing (การทดสอบ) | Jest (unit/e2e) | Vitest / Playwright | Visual regression |
| Styles (สไตล์) | Scoped modules (ถ้าจำเป็น) | Tailwind / Shadcn | Tailwind utilities |
| Accessibility (การเข้าถึง) | Guards + filters | ARIA attributes | Semantic HTML |
## **🗂️ ข้อตกลงเฉพาะสำหรับ DMS (LCBP3-DMS)**
ส่วนนี้ขยายแนวทาง FullStackJS ทั่วไปสำหรับโปรเจกต์ **LCBP3-DMS** โดยมุ่งเน้นไปที่เวิร์กโฟลว์การอนุมัติเอกสาร (Correspondence, RFA, Drawing, Contract, Transmittal, Circulation)
### **🧩 RBAC และการควบคุมสิทธิ์ (RBAC & Permission Control)**
ใช้ Decorators เพื่อบังคับใช้สิทธิ์การเข้าถึง โดยอ้างอิงสิทธิ์จากตาราง permissions
@RequirePermission('rfas.respond') // ต้องตรงกับ 'permission\code'
@Put(':id')
updateRFA(@Param('id') id: string) {
return this.rfaService.update(id);
}
### **Roles (บทบาท)**
* **Superadmin**: ไม่มีข้อจำกัดใดๆ [cite: 4.3]
* **Admin**: มีสิทธิ์เต็มที่ในองค์กร [cite: 4.3]
* **Document Control**: เพิ่ม/แก้ไข/ลบ เอกสารในองค์กร [cite: 4.3]
* **Editor**: สามารถ เพิ่ม/แก้ไข เอกสารที่กำหนด [cite: 4.3]
* **Viewer**: สามารถดู เอกสาร [cite: 4.3]
### **ตัวอย่าง Permissions (จากตาราง permissions)**
* rfas.view, rfas.create, rfas.respond, rfas.delete
* drawings.view, drawings.upload, drawings.delete
* corr.view, corr.manage
* transmittals.manage
* cirs.manage
* project\parties.manage
การจับคู่ระหว่าง roles และ permissions **เริ่มต้น** จะถูก seed ผ่านสคริปต์ (ดังที่เห็นในไฟล์ SQL)**อย่างไรก็ตาม AuthModule/UserModule ต้องมี API สำหรับ Admin เพื่อสร้าง Role ใหม่และกำหนดสิทธิ์ (Permissions) เพิ่มเติมได้ในภายหลัง** [cite: 4.3]
## **🧾 มาตรฐาน AuditLog (AuditLog Standard)**
บันทึกการดำเนินการ CRUD และการจับคู่ทั้งหมดลงในตาราง audit_logs
| Field (ฟิลด์) | Type (จาก SQL) | Description (คำอธิบาย) |
| :---- | :---- | :---- |
| audit_id | BIGINT | Primary Key |
| user_id | INT | ผู้ใช้ที่ดำเนินการ (FK -> users) |
| action | VARCHAR(100) | rfa.create, correspondence.update, login.success |
| entity_type | VARCHAR(50) | ชื่อตาราง/โมดูล เช่น 'rfa', 'correspondence' |
| entity_id | VARCHAR(50) | Primary ID ของระเบียนที่ได้รับผลกระทบ |
| details_json | JSON | ข้อมูลบริบท (เช่น ฟิลด์ที่มีการเปลี่ยนแปลง) |
| ip_address | VARCHAR(45) | IP address ของผู้ดำเนินการ |
| user_agent | VARCHAR(255) | User Agent ของผู้ดำเนินการ |
| created_at | TIMESTAMP | Timestamp (UTC) |
## **📂 การจัดการไฟล์ (File Handling) (ปรับปรุงใหม่)**
### **มาตรฐานการอัปโหลดไฟล์ (File Upload Standard)**
* **ตรรกะใหม่:** การอัปโหลดไฟล์ทั้งหมดจะถูกจัดการโดย FileStorageService และบันทึกข้อมูลไฟล์ลงในตาราง attachments (ตารางกลาง)
* ไฟล์จะถูกเชื่อมโยงไปยัง Entity ที่ถูกต้องผ่าน **ตารางเชื่อม (Junction Tables)** เท่านั้น:
* correspondence_attachments (เชื่อม Correspondence กับ Attachments)
* circulation_attachments (เชื่อม Circulation กับ Attachments)
* shop_drawing_revision_attachments (เชื่อม Shop Drawing Revision กับ Attachments)
* contract_drawing_attachments (เชื่อม Contract Drawing กับ Attachments)
* เส้นทางจัดเก็บไฟล์ (Upload path): อ้างอิงจาก Requirement 2.1 คือ /share/dms-data [cite: 2.1] โดย FileStorageService จะสร้างโฟลเดอร์ย่อยแบบรวมศูนย์ (เช่น /share/dms-data/uploads/{YYYY}/{MM}/[stored\filename])
* ประเภทไฟล์ที่อนุญาต: pdf, dwg, docx, xlsx, zip
* ขนาดสูงสุด: **50 MB**
* จัดเก็บนอก webroot
* ให้บริการไฟล์ผ่าน endpoint ที่ปลอดภัย /files/:attachment_id/download
### **การควบคุมการเข้าถึง (Access Control)**
การเข้าถึงไฟล์ไม่ใช่การเข้าถึงโดยตรง endpoint /files/:attachment_id/download จะต้อง:
1. ค้นหาระเบียน attachment
2. ตรวจสอบว่า attachment_id นี้ เชื่อมโยงกับ Entity ใด (เช่น correspondence, circulation, shop_drawing_revision, contract_drawing) ผ่านตารางเชื่อม
3. ตรวจสอบว่าผู้ใช้มีสิทธิ์ (permission) ในการดู Entity ต้นทางนั้นๆ หรือไม่
## **🔟 การจัดการเลขที่เอกสาร (Document Numbering) [cite: 3.10]**
* **เป้าหมาย:** สร้างเลขที่เอกสาร (เช่น correspondence\number) โดยอัตโนมัติ ตามรูปแบบที่กำหนด
* **ตรรกะการนับ:** การนับ Running number (SEQ) จะนับแยกตาม Key: **Project + Originator Organization + Document Type + Year**
* **ตาราง SQL:**
* document_number_formats: Admin ใช้กำหนด "รูปแบบ" (Template) ของเลขที่ (เช่น {ORG\CODE}-{TYPE\CODE}-{YEAR\SHORT}-{SEQ:4}) โดยกำหนดตาม **Project** และ **Document Type** [cite: 4.5]
* document_number_counters: ระบบใช้เก็บ "ตัวนับ" ล่าสุดของ Key (Project+Org+Type+Year)
* **การทำงาน (Backend):**
* DocumentNumberingModule จะให้บริการ DocumentNumberingService
* เมื่อ CorrespondenceModule ต้องการสร้างเอกสารใหม่, มันจะเรียก documentNumberingService.generateNextNumber(...)
* Service นี้จะเรียกใช้ Stored Procedure **sp_get_next_document_number** [cite: 2.9.3] ซึ่ง Procedure นี้จะจัดการ Database Transaction และ Row Lock (FOR UPDATE) ภายใน DB เพื่อรับประกันการป้องกัน Race Condition
## **📊 การรายงานและการส่งออก (Reporting & Exports)**
### **วิวสำหรับการรายงาน (Reporting Views) (จาก SQL)**
การรายงานควรสร้างขึ้นจาก Views ที่กำหนดไว้ล่วงหน้าในฐานข้อมูลเป็นหลัก:
* v_current_correspondences: สำหรับ revision ปัจจุบันทั้งหมดของเอกสารที่ไม่ใช่ RFA
* v_current_rfas: สำหรับ revision ปัจจุบันทั้งหมดของ RFA และข้อมูล master
* v_contract_parties_all: สำหรับการตรวจสอบความสัมพันธ์ของ project/contract/organization
* v_user_tasks: สำหรับ Dashboard "งานของฉัน"
* v_audit_log_details: สำหรับ Activity Feed
Views เหล่านี้ทำหน้าที่เป็นแหล่งข้อมูลหลักสำหรับการรายงานฝั่งเซิร์ฟเวอร์และการส่งออกข้อมูล
### **กฎการส่งออก (Export Rules)**
* Export formats: CSV, Excel, PDF.
* จัดเตรียมมุมมองสำหรับพิมพ์ (Print view).
* รวมลิงก์ไปยังต้นทาง (เช่น /rfas/:id).
## **🧮 ฟรอนต์เอนด์: รูปแบบ DataTable และฟอร์ม (Frontend: DataTable & Form Patterns)**
### **DataTable (Server‑Side)**
* Endpoint: /api/{module}?page=1\&pageSize=20\&sort=...\&filter=...
* ต้องรองรับ: การแบ่งหน้า (pagination), การเรียงลำดับ (sorting), การค้นหา (search), การกรอง (filters)
* แสดง revision ล่าสุดแบบ inline เสมอ (สำหรับ RFA/Drawing)
### **มาตรฐานฟอร์ม (Form Standards)**
* ต้องมีการใช้งาน Dropdowns แบบขึ้นต่อกัน (Dependent dropdowns) (ตามที่สคีมารองรับ):
* Project → Contract Drawing Volumes
* Contract Drawing Category → Sub-Category
* RFA (ประเภท Shop Drawing) → Shop Drawing Revisions ที่เชื่อมโยงได้
* **(ใหม่)** การอัปโหลดไฟล์: ต้องรองรับ **Multi-file upload (Drag-and-Drop)** [cite: 5.7]
* **(ใหม่)** UI ต้องอนุญาตให้ผู้ใช้กำหนดว่าไฟล์ใดเป็น **"เอกสารหลัก"** หรือ "เอกสารแนบประกอบ" [cite: 5.7]
* ส่ง (Submit) ผ่าน API พร้อม feedback แบบ toast
### **ข้อกำหนด Component เฉพาะ (Specific UI Requirements)**
* **Dashboard \- My Tasks:** ต้องพัฒนา Component ตาราง "งานของฉัน" (My Tasks)ซึ่งดึงข้อมูลงานที่ผู้ใช้ล็อกอินอยู่ต้องรับผิดชอบ (Main/Action) จาก v\user\tasks [cite: 5.3]
* **Workflow Visualization:** ต้องพัฒนา Component สำหรับแสดงผล Workflow (โดยเฉพาะ RFA)ที่แสดงขั้นตอนทั้งหมดเป็นลำดับ โดยขั้นตอนปัจจุบัน (active) เท่านั้นที่ดำเนินการได้ และขั้นตอนอื่นเป็น disabled [cite: 5.6] ต้องมีตรรกะสำหรับ Admin ในการ override หรือย้อนกลับขั้นตอนได้ [cite: 5.6]
* ** Admin Panel:** ต้องมีหน้า UI สำหรับ Superadmin/Admin เพื่อจัดการข้อมูลหลัก (Master Data [cite: 4.5]), การเริ่มต้นใช้งาน (Onboarding [cite: 4.6]), และ **รูปแบบเลขที่เอกสาร (Numbering Formats [cite: 3.10])**
## **🧭 แดชบอร์ดและฟีดกิจกรรม (Dashboard & Activity Feed)**
### **การ์ดบนแดชบอร์ด (Dashboard Cards)**
* แสดง Correspondences, RFAs, Circulations, Shop Drawing Revision ล่าสุด
* รวมสรุป KPI (เช่น "RFAs ที่รอการอนุมัติ", "Shop Drawing ที่รอการอนุมัติ") [cite: 5.3]
* รวมลิงก์ด่วนไปยังโมดูลต่างๆ
### **ฟีดกิจกรรม (Activity Feed)**
* แสดงรายการ v\audit\log\details ล่าสุด (10 รายการ) ที่เกี่ยวข้องกับผู้ใช้
// ตัวอย่าง API response
[
{ user: 'editor01', action: 'Updated RFA (LCBP3-RFA-001)', time: '2025-11-04T09:30Z' }
]
## **🛡️ ข้อกำหนดที่ไม่ใช่ฟังก์ชันการทำงาน (Non-Functional Requirements)**
ส่วนนี้สรุปข้อกำหนด Non-Functional จาก requirements.md เพื่อให้ทีมพัฒนาทราบ
* **Audit Log [cite: 6.1]:** ทุกการกระทำที่สำคัญ (C/U/D) ต้องถูกบันทึกใน audit_logs
* **Performance [cite: 6.4]:** ต้องใช้ Caching สำหรับข้อมูลที่เรียกบ่อย และใช้ Pagination
* **Security [cite: 6.5]:** ต้องมี Rate Limiting และจัดการ Secret ผ่าน docker-compose.yml (ไม่ใช่ .env)
* **(ใหม่) Backup & Recovery [cite: 6.6]:** ต้องมีแผนสำรองข้อมูลทั้ง Database (MariaDB) และ File Storage (/share/dms-data) อย่างน้อยวันละ 1 ครั้ง
* **(ใหม่) Notification Strategy [cite: 6.7]:** ระบบแจ้งเตือน (Email/Line) ต้องถูก Trigger เมื่อมีเอกสารใหม่ส่งถึง, มีการมอบหมายงานใหม่ (Circulation), หรือ (ทางเลือก) เมื่องานเสร็จ/ใกล้ถึงกำหนด
## **✅ มาตรฐานที่นำไปใช้แล้ว (จาก SQL v1.1.0) (Implemented Standards (from SQL v1.1.0))**
ส่วนนี้ยืนยันว่าแนวทางปฏิบัติที่ดีที่สุดต่อไปนี้เป็นส่วนหนึ่งของการออกแบบฐานข้อมูลอยู่แล้ว และควรถูกนำไปใช้ประโยชน์ ไม่ใช่สร้างขึ้นใหม่
* ✅ **Soft Delete:** นำไปใช้แล้วผ่านคอลัมน์ deleted_at ในตารางสำคัญ (เช่น correspondences, rfas, project_parties) ตรรกะการดึงข้อมูลต้องกรอง deleted_at IS NULL
* ✅ **Database Indexes:** สคีมาได้มีการทำ index ไว้อย่างหนักหน่วงบน foreign keys และคอลัมน์ที่ใช้ค้นหาบ่อย (เช่น idx_rr_rfa, idx_cor_project, idx_cr_is_current) เพื่อประสิทธิภาพ
* ✅ **โครงสร้าง RBAC:** มีระบบ users, roles, permissions, user_roles, และ user_project_roles ที่ครอบคลุมอยู่แล้ว
* ✅ **Data Seeding:** ข้อมูล Master (roles, permissions, organization_roles, initial users, project parties) ถูกรวมอยู่ในสคริปต์สคีมาแล้ว
## **🧩 การปรับปรุงที่แนะนำ (สำหรับอนาคต) (Recommended Enhancements (Future))**
* ✅ สร้าง Background job (โดยใช้ **n8n** เพื่อเชื่อมต่อกับ **Line** [cite: 2.7] และ/หรือใช้สำหรับการแจ้งเตือน RFA ที่ใกล้ถึงกำหนด due_date [cite: 6.7])
* ✅ เพิ่ม job ล้างข้อมูลเป็นระยะสำหรับ attachments ที่ไม่ถูกเชื่อมโยงกับ Entity ใดๆ เลย (ไฟล์กำพร้า)

79
infrastructure/Markdown/LCBP3-DMS_V1_3_0_Test_Plan_TH.md Normal file
View File

@@ -0,0 +1,79 @@
# **🧪 แผนการทดสอบระบบ (Test Plan) \- DMS v1.3.0 Backend**
เอกสารนี้สรุปแผนการทดสอบ, ขั้นตอน, และเครื่องมือที่ใช้ในการตรวจสอบความถูกต้องของ NestJS Backend API (DMS v1.3.0) ก่อนการ Deploy ใช้งานจริงร่วมกับ Frontend
## **1\. วัตถุประสงค์ (Objectives)**
* เพื่อให้มั่นใจว่า API ทั้งหมดทำงานตรงตาม requirements.md
* เพื่อตรวจสอบว่าระบบรักษาความปลอดภัย (RBAC และ Security) ทำงานได้ถูกต้อง 100%
* เพื่อค้นหาและแก้ไขข้อบกพร่อง (Bugs) ที่เกี่ยวข้องกับการเชื่อมต่อฐานข้อมูลและ Business Logic
* เพื่อยืนยันว่าระบบทนทานต่อการใช้งานพร้อมกัน (Concurrency) และมีประสิทธิภาพ (Performance)
* เพื่อส่งมอบ API ที่เสถียรและมีเอกสาร (Swagger) ครบถ้วนให้แก่ทีม Frontend
## **2\. ขอบเขตการทดสอบ (Scope)**
### **สิ่งที่อยู่ในขอบเขต (In-Scope)**
* **API Functionality:** การทดสอบ Endpoints ทั้งหมด (CRUD, Search, Upload)
* **Business Logic:** ตรรกะการสร้างเอกสาร (RFA, Correspondence), การสร้างเลขที่, และ Workflow
* **Security:** การยืนยันตัวตน (JWT), การจัดการสิทธิ์ (RBAC Guard), การป้องกัน (Helmet, Rate Limiter)
* **Data Integrity:** การตรวจสอบความถูกต้องของข้อมูลที่บันทึกลง MariaDB
* **Performance:** การทดสอบ Concurrency (การสร้างเลขที่) และการตอบสนองของ API
* **Error Handling:** การตรวจสอบว่า Global Exception Filter ทำงานได้ถูกต้อง
### **สิ่งที่อยู่นอกขอบเขต (Out-of-Scope)**
* การทดสอบ Next.js Frontend (UI/UX)
* การทดสอบตรรกะภายในของ N8N (เราทดสอบแค่ว่า Backend *ยิง* Webhook ไปหรือไม่)
* การทดสอบ Penetration Test ขั้นสูง (เน้น Functional & Security พื้นฐาน)
## **3\. สภาพแวดล้อมและเครื่องมือ (Environment & Tools)**
| ประเภท | เครื่องมือ/สภาพแวดล้อม | วัตถุประสงค์ |
| :---- | :---- | :---- |
| **สภาพแวดล้อม** | **Staging (QNAP)** | สภาพแวดล้อมจำลอง (บน Docker) ที่เหมือน Production ที่สุด ประกอบด้วย backend, mariadb, elasticsearch, n8n (Mock Receiver) |
| **ฐานข้อมูล** | **DBeaver** | ใช้สำหรับเชื่อมต่อ MariaDB (Staging) เพื่อตรวจสอบผลลัพธ์ (Data Verification) |
| **API (Manual)** | **Postman / Insomnia** | ใช้สำหรับการทดสอบ API ด้วยตนเอง, สำรวจ Endpoints, และสร้าง Test Case |
| **API (Automation)** | **Postman (Newman) / Supertest** | (E2E) ใช้รัน Test Case อัตโนมัติเพื่อตรวจสอบ API Contract |
| **Unit/Integration** | **Jest / @nestjs/testing** | (Developer) ใช้สำหรับทดสอบ Logic ภายใน Service และ Guard (ตามตัวอย่าง spec.ts ที่สร้างไว้) |
| **Concurrency** | **k6 (แนะนำ) / Node.js Script** | ใช้สำหรับทดสอบ Stress Test และ Concurrency (โดยเฉพาะ TC-CON-01) |
| **Webhook** | **N8N (Webhook Node)** | ใช้ N8N จริง (Staging) ตั้งค่า Webhook Node เพื่อรับ Event จาก NotificationService |
## **4\. รายละเอียดสถานการณ์ทดสอบ (Detailed Test Scenarios)**
นี่คือ Test Case ที่สำคัญที่สุด โดยแบ่งตามความเสี่ยงและ Function
### **T1: การรักษาความปลอดภัย (Security & RBAC) \- (ความเสี่ยงสูงมาก)**
| ID | สถานการณ์ | ขั้นตอนการทดสอบ (Steps) | ผลลัพธ์ที่คาดหวัง (Expected) | เครื่องมือ |
| :---- | :---- | :---- | :---- | :---- |
| **TC-SEC-01** | **(RBAC) ห้าม Viewer สร้างเอกสาร** | 1\. (Postman) เรียก POST /api/v1/auth/login ด้วย User "Viewer" 2\. คัดลอก access\_token 3\. เรียก POST /api/v1/correspondence (ใน Auth Header) พร้อม Body ที่ถูกต้อง | 403 Forbidden (RBACGuard ทำงาน) | Postman |
| **TC-SEC-02** | **(RBAC) Editor ข้าม Project** | 1\. (Postman) Login User "Editor" ที่มีสิทธิ์เฉพาะ Project A 2\. (DBeaver) หา ID เอกสาร (เช่น corr\_id: 99\) ที่อยู่ใน Project B 3\. (Postman) เรียก GET /api/v1/correspondence/99 ด้วย Token ของ Editor | 403 Forbidden หรือ 404 Not Found | Postman, DBeaver |
| **TC-SEC-03** | **(RBAC) Super Admin** | 1\. (Postman) Login User "Super Admin" 2\. เรียก Endpoint ที่จำกัดสิทธิ์สูง (เช่น POST /api/v1/admin/users) | 201 Created (Super Admin ต้องผ่านทุกการตรวจสอบ) | Postman |
| **TC-SEC-04** | **(Rate Limit) Brute-force** | 1\. (Postman Runner หรือ k6) ตั้งค่าให้เรียก POST /api/v1/auth/login (ด้วยรหัสผ่านผิด) 110 ครั้ง (Limit คือ 100\) 2\. สังเกตผลลัพธ์ | Request ที่ 1-100: 401 Unauthorized Request ที่ 101+: 429 Too Many Requests | k6, Postman |
| **TC-SEC-05** | **(Security) Helmet** | 1\. (Postman) เรียก Endpoint ใดก็ได้ (เช่น GET /api/v1/health) 2\. ตรวจสอบ Response Headers | ต้องมี Headers เช่น X-Content-Type-Options: nosniff, Strict-Transport-Security, X-Frame-Options: SAMEORIGIN | Postman |
### **T2: ตรรกะหลัก (Core Logic & Concurrency) \- (ความเสี่ยงสูง)**
| ID | สถานการณ์ | ขั้นตอนการทดสอบ (Steps) | ผลลัพธ์ที่คาดหวัง (Expected) | เครื่องมือ |
| :---- | :---- | :---- | :---- | :---- |
| **TC-CON-01** | **(Concurrency) สร้างเลขที่เอกสาร** | 1\. (k6/Script) สร้าง Script ที่เรียก POST /api/v1/correspondence (สร้างเอกสารใหม่) 50 ครั้ง *พร้อมกัน* (Simultaneously) 2\. (Postman) Login Admin 3\. (DBeaver) ตรวจสอบตาราง correspondences และ document\_number\_counters | 1\. Script ทั้ง 50 ครั้งสำเร็จ (201 Created) 2\. (DBeaver) document\_number\_counters มี last\_number: 50 3\. correspondences มีเอกสาร 50 ฉบับ โดย *ไม่มี* correspondence\_number ซ้ำกันเลย | k6, DBeaver |
| **TC-FUNC-01** | **(Data) สร้าง RFA (Complex)** | 1\. (Postman) Login User (เช่น "Editor") 2\. เรียก POST /api/v1/rfa พร้อม DTO ที่ซับซ้อน (มี rfa\_type\_id, title, attachments, shop\_drawings) | 1\. 201 Created 2\. (DBeaver) ตรวจสอบว่ามีข้อมูลถูกสร้างขึ้นใน 3 ตารางหลัก: \- correspondences (ตารางแม่) \- rfas (ตารางแม่ RFA) \- rfa\_revisions (ตารางลูก Revision 0\) | Postman, DBeaver |
### **T3: การทำงานของโมดูล (Module Functionality)**
| ID | สถานการณ์ | ขั้นตอนการทดสอบ (Steps) | ผลลัพธ์ที่คาดหวัง (Expected) | เครื่องมือ |
| :---- | :---- | :---- | :---- | :---- |
| **TC-FUNC-02** | **(File) อัปโหลดไฟล์** | 1\. (Postman) Login User 2\. เรียก POST /api/v1/files/upload (ประเภท form-data, key file) 3\. (DBeaver) ตรวจสอบตาราง attachments | 1\. 201 Created คืนค่าข้อมูล Attachment (เช่น ID, stored\_filename) 2\. (DBeaver) มีแถวใหม่ในตาราง attachments 3\. (ถ้าทำได้) ตรวจสอบ QNAP /share/dms-data/... ว่ามีไฟล์จริง | Postman, DBeaver |
| **TC-FUNC-03** | **(File) ดาวน์โหลด (ผ่าน Auth)** | 1\. (Postman) ทำ TC-FUNC-02 เพื่ออัปโหลดไฟล์ (สมมติได้ attachment\_id: 123\) 2\. เรียก GET /api/v1/files/download/123 (ต้องใส่ Auth Header) | 200 OK และได้ข้อมูลไฟล์กลับมา | Postman |
| **TC-FUNC-04** | **(Search) Elasticsearch** | 1\. (Postman) สร้างเอกสารใหม่ POST /api/v1/correspondence (จดจำ Title ไว้) 2\. (รอ 10 วินาที ให้ Elastic Index) 3\. เรียก GET /api/v1/search?query=\[Title ที่จดไว้\] | 200 OK และผลลัพธ์การค้นหาต้องมีเอกสารที่เพิ่งสร้าง | Postman |
| **TC-FUNC-05** | **(Notification) N8N Webhook** | 1\. (N8N) สร้าง Workflow ใหม่, ใช้ "Webhook" Node (เปิด Test Mode) 2\. (Postman) Login User 3\. เรียก POST /api/v1/circulation (สร้างใบเวียนใหม่) | 1\. (Postman) 201 Created 2\. (N8N) Webhook Node ได้รับข้อมูล Payload ({ event: 'NEW\_CIRCULATION\_TASK', ... }) | Postman, N8N |
| **TC-FUNC-06** | **(Audit) Audit Log** | 1\. (Postman) Login Admin 2\. เรียก DELETE /api/v1/admin/roles/10 (ลบ Role สมมติ) 3\. (DBeaver) ตรวจสอบ audit\_logs | 1\. (DBeaver) มีแถวใหม่ใน audit\_logs 2\. ข้อมูลถูกต้อง: action: 'role.delete', entity\_type: 'role', entity\_id: '10', user\_id: \[Admin ID\] | Postman, DBeaver |
### **T4: การ Deploy (NFR)**
| ID | สถานการณ์ | ขั้นตอนการทดสอบ (Steps) | ผลลัพธ์ที่คาดหวัง (Expected) | เครื่องมือ |
| :---- | :---- | :---- | :---- | :---- |
| **TC-NFR-01** | **(Health) Health Check** | 1\. (Browser/Postman) เรียก GET /api/v1/health (จาก Staging URL) | 200 OK และ JSON Response แสดง status: "ok" และสถานะ DB | Postman, Browser |
| **TC-NFR-02** | **(Error) Global Filter** | 1\. (Postman) เรียก Endpoint ที่ไม่มีอยู่จริง (เช่น GET /api/v1/invalid\_path) | 404 Not Found Response Body ต้องมีโครงสร้าง JSON ที่กำหนดไว้ (เช่น { "statusCode": 404, "message": "Cannot GET /api/v1/invalid\_path", ... }) | Postman |

117
infrastructure/Markdown/LCBP3-DMS_V1_3_0_backend_dev_plan.md Normal file
View File

@@ -0,0 +1,117 @@
# แผนการพัฒนา Backend NestJS สำหรับ DMS v1.3.0
## การเตรียมความพร้อมและการติดตั้ง (Prerequisites & Setup)
- [ ] สร้าง NestJS Project ใหม่ (backend/src)
- [✅] ติดตั้ง Dependencies หลักๆ ตาม Technology Stack
- [✅] `@nestjs/core`, `@nestjs/common`
- [✅] `@nestjs/typeorm`, `typeorm`
- [✅] `@nestjs/jwt`, `@nestjs/passport`, `passport-jwt`
- [✅] `casl`
- [✅] `class-validator`, `class-transformer`
- [✅] `@nestjs/swagger`
- [✅] `winston`, `helmet`, `rate-limiter-flexible`
- [✅] ตั้งค่า `tsconfig.json`, `nest-cli.json` และไฟล์ config อื่นๆ
- [ ] ตั้งค่าการเชื่อมต่อ MariaDB ผ่าน TypeORM
- [ ] **(สำคัญ)** กำหนดค่าตัวแปรสภาพแวดล้อม (DATABASE_URL, JWT_SECRET) ผ่าน `docker-compose.yml`
---
## Phase 1: การสร้างรากฐาน (Foundation) - สัปดาห์ที่ 1-2
- [ ] พัฒนา Core Auth Module (`AuthModule`)
- [✅] สร้าง Entities: `Users`, `Roles`, `Permissions`
- [✅] สร้าง `AuthService` สำหรับ Login, Register, JWT Generation
- [✅] สร้าง `JwtStrategy` สำหรับ Passport
- [✅] สร้าง `RBACGuard` โดยใช้ CASL
- [✅] สร้าง API Endpoints: `/auth/login`, `/auth/me`
- [✅] พัฒนา Common Module (`@app/common`)
- [✅] สร้าง `FileStorageService` สำหรับจัดการไฟล์ (อัปโหลด/ดาวน์โหลด)
- [✅] สร้าง `AuditLogInterceptor` สำหรับบันทึกการกระทำโดยอัตโนมัติ
- [✅] สร้าง Global Exception Filter
- [✅] สร้าง DTOs และ Interfaces พื้นฐาน
---
## Phase 2: พัฒนาเอนทิตีหลัก (Core Entities) - สัปดาห์ที่ 3-4
- [✅] พัฒนา Project Module (`ProjectModule`)
- [✅] สร้าง Entities: `Project`, `Organization`, `Contract`, `ProjectParty`
- [✅] สร้าง Services สำหรับ CRUD และจัดการความสัมพันธ์
- [✅] สร้าง Controller พร้อม Swagger Decorators
- [ ] พัฒนา Correspondence Module (`CorrespondenceModule`)
- [ ] สร้าง Entities: `Correspondence`, `CorrespondenceRevision`, `CorrespondenceAttachment`
- [ ] สร้าง Services สำหรับจัดการเอกสาร การสร้าง Revision
- [ ] เชื่อมโยงกับ `FileStorageService` และ `DocumentNumberingService`
- [ ] พัฒนา Attachment Management
- [ ] พัฒนา API อัปโหลดไฟล์ (`POST /correspondences/:id/attachments`)
- [ ] พัฒนา API ดาวน์โหลดไฟล์ (`GET /attachments/:id/download`)
- [ ] ใช้ Junction Tables (`correspondence_attachments`) ในการเชื่อมโยง
---
## Phase 3: พัฒนาเวิร์กโฟลว์เฉพาะทาง (Specialized Workflows) - สัปดาห์ที่ 5-7
- [ ] พัฒนา RFA Module (`RfaModule`)
- [ ] สร้าง Entities: `Rfa`, `RfaRevision`, `RfaWorkflow`, `RfaItem`
- [ ] สร้าง Service สำหรับจัดการ Workflow การอนุมัติ (ส่ง -> อนุมัติ/ปฏิเสธ -> ส่งกลับ)
- [ ] จัดการ State Transitions ตาม `rfa_status_transitions`
- [ ] พัฒนา Drawing Module (`DrawingModule`)
- [ ] สร้าง Entities: `ShopDrawing`, `ShopDrawingRevision`, `ContractDrawing`
- [ ] สร้าง Services สำหรับจัดการแบบแปลนและการอ้างอิงระหว่าง Shop และ Contract Drawing
- [ ] พัฒนา Circulation Module (`CirculationModule`)
- [ ] สร้าง Entities: `Circulation`, `CirculationAssignee`
- [ ] สร้าง Service สำหรับการสร้างใบเวียน มอบหมายงาน และติดตามสถานะ
- [ ] พัฒนา Transmittal Module (`TransmittalModule`)
- [ ] สร้าง Entities: `Transmittal`, `TransmittalItem`
- [ ] สร้าง Service สำหรับการสร้างเอกสารนำส่ง
---
## Phase 4: คุณสมบัติขั้นสูงและการเชื่อมโยง (Advanced Features) - สัปดาห์ที่ 8-9
- [ ] พัฒนา Document Numbering Module (`DocumentNumberingModule`)
- [ ] สร้าง `DocumentNumberingService` (Internal Module)
- [ ] Implement การเรียกใช้ Stored Procedure `sp_get_next_document_number`
- [ ] ให้บริการแก่ `CorrespondenceModule` และโมดูลอื่นๆ
- [ ] พัฒนา Search Module (`SearchModule`)
- [ ] ตั้งค่า Elasticsearch
- [ ] สร้าง Service สำหรับ Index ข้อมูลจาก Views (`v_current_correspondences`, `v_current_rfas`)
- [ ] สร้าง API ค้นหาขั้นสูง (`/search`)
- [ ] พัฒนา Notification Service
- [ ] สร้าง `NotificationService` ใน `CommonModule`
- [ ] Implement การส่ง Email ผ่าน `nodemailer`
- [ ] สร้าง Trigger สำหรับส่งการแจ้งเตือน (เอกสารใหม่, เปลี่ยนสถานะ, ใกล้ถึง Deadline)
- [ ] เตรียมพร้อมสำหรับการเชื่อมต่อกับ N8N สำหรับ Line Notification
---
## Phase 5: การทดสอบและเพิ่มประสิทธิภาพ (Testing & Optimization) - สัปดาห์ที่ 10
- [ ] ดำเนินการทดสอบ (Testing)
- [ ] เขียน Unit Tests สำหรับ Business Logic ใน Services และ Guards
- [ ] เขียน Integration Tests สำหรับ Controller -> Service -> Repository (โดยใช้ Test Database)
- [ ] เขียน E2E Tests สำหรับตรวจสอบ API Contract ว่าตรงตาม Swagger
- [ ] ปรับปรุงประสิทธิภาพ (Performance)
- [ ] ใช้ Caching (`@nestjs/cache-manager`) สำหรับข้อมูลที่ถูกเรียกบ่อย (Roles, Permissions)
- [ ] ตรวจสอบ Query และใช้ Database Indexes ให้เป็นประโยชน์ (มีอยู่แล้วใน SQL)
- [ ] ใช้ Pagination สำหรับข้อมูลจำนวนมาก
- [ ] เพิ่มความปลอดภัย (Security)
- [ ] ติดตั้ง `helmet` สำหรับตั้งค่า HTTP Headers
- [ ] ติดตั้ง `rate-limiter-flexible` สำหรับป้องกัน Brute-force
- [ ] จัดเตรียมเอกสาร (Documentation)
- [ ] ตรวจสอบความสมบูรณ์ของ Swagger Documentation
- [ ] เพิ่ม JSDoc Comments สำหรับ Methods และ Classes ที่สำคัญ
---
## การ Deploy บน QNAP Container Station
- [ ] เตรียมการ Deploy บน QNAP Container Station
- [ ] สร้าง `Dockerfile` สำหรับ NestJS App
- [ ] สร้างไฟล์ `docker-compose.yml` สำหรับ `backend` service
- [ ] กำหนด `environment` สำหรับ `DATABASE_HOST`, `DATABASE_USER`, `DATABASE_PASSWORD`, `JWT_SECRET`
- [ ] เชื่อมต่อกับ `lcbp3` network
- [ ] ทดสอบ Build และ Run บน Container Station UI
- [ ] ตั้งค่า Health Check endpoint (`/health`) โดยใช้ `@nestjs/terminus`

169
infrastructure/Markdown/LCBP3-DMS_V1_3_0_frontend_dev_plan.md Normal file
View File

@@ -0,0 +1,169 @@
# แผนการพัฒนา Frontend Next.js สำหรับ DMS v1.3.0
## การเตรียมความพร้อมและการติดตั้ง (Prerequisites & Setup)
- [ ] สร้าง Next.js Project ใหม่ (App Router)
```bash
npx create-next-app@latest frontend --typescript --tailwind --eslint --app
```
- [ ] ติดตั้ง Dependencies หลักๆ ตามเอกสาร FullStackJS
- [ ] UI Library: `@shadcn/ui` และ dependencies ที่เกี่ยวข้อง
- [ ] State Management: `zustand`
- [ ] Server State: `@tanstack/react-query`
- [ ] Form Handling: `react-hook-form`, `zod`, `@hookform/resolvers`
- [ ] File Upload: `react-dropzone`
- [ ] Icons: `lucide-react`
- [ ] Testing: `vitest`, `@testing-library/react`, `@testing-library/jest-dom`, `@playwright/test`
- [ ] ตั้งค่าโครงสร้างโปรเจกต์
```
src/
├── app/ # App Router
│ ├── (dashboard)/ # Route Groups
│ ├── api/ # API Routes (ถ้าจำเป็น)
│ ├── globals.css
│ ├── layout.tsx
│ └── page.tsx
├── components/ # Reusable UI Components
│ ├── ui/ # shadcn/ui components
│ ├── forms/ # Form Components
│ └── features/ # Feature-specific Components
├── lib/ # Utility functions
│ ├── api.ts # Axios/Fetch wrapper
│ ├── auth.ts # Auth helpers
│ └── utils.ts
├── hooks/ # Custom React Hooks
├── store/ # Zustand stores
└── types/ # TypeScript type definitions
```
- [ ] ตั้งค่า Tailwind CSS และ shadcn/ui
- [ ] ตั้งค่า React Query ใน `app/providers.tsx` และครอบใน `layout.tsx`
- [ ] ตั้งค่า Zustand store สำหรับ Global State (เช่น User, Auth)
---
## Phase 1: การสร้างรากฐานและการยืนยันตัวตน (Foundation & Authentication) - สัปดาห์ที่ 1-2
- [ ] พัฒนา Layout หลัก (App Shell - Req 5.1)
- [ ] สร้าง `Navbar` Component (ชื่อระบบ, เมนูผู้ใช้, ปุ่ม Logout)
- [ ] สร้าง `Sidebar` Component (เมนูการนำทางหลัก)
- [ ] สร้าง `MainContent` Component สำหรับแสดงผลหน้าต่างๆ
- [ ] ประกอบ Component ทั้งหมดใน `layout.tsx`
- [ ] พัฒนาระบบ Authentication
- [ ] สร้าง `LoginPage` Component (ใช้ `react-hook-form` + `zod`)
- [ ] สร้าง Auth Store ด้วย Zustand (เก็บ User, Token, สถานะการล็อกอิน)
- [ ] สร้าง `useAuth` Hook สำหรับเข้าถึง Auth State
- [ ] สร้าง API functions สำหรับ Login, Logout, Get Profile
- [ ] สร้าง Middleware สำหรับป้องกัน Route ที่ต้องการ Login
- [ ] สร้าง `ProfilePage` (Req 5.5)
- [ ] แสดงข้อมูลผู้ใช้
- [ ] ฟอร์มแก้ไขข้อมูลส่วนตัว
- [ ] ฟอร์มเปลี่ยนรหัสผ่าน
---
## Phase 2: พัฒนาคอมโพเนนต์หลักและหน้า Dashboard (Core Components & Dashboard) - สัปดาห์ที่ 3-4
- [ ] พัฒนา Reusable Components พื้นฐาน
- [ ] `DataTable` Component (รองรับ Server-side Pagination, Sorting, Filtering)
- [ ] `FormSelect`, `FormInput`, `FormTextarea` (ครอบด้วย `react-hook-form`)
- [ ] `LoadingSpinner`, `ErrorAlert` Components
- [ ] `ConfirmDialog` Component
- [ ] พัฒนา `FileUpload` Component (Req 5.7)
- [ ] ใช้ `react-dropzone` สำหรับ Drag-and-Drop
- [ ] รองรับการอัปโหลดหลายไฟล์
- [ ] มี Checkbox ให้เลือก "เอกสารหลัก" (Main Document)
- [ ] แสดงรายการไฟล์ที่เลือกพร้อมตัวเลือกลบ
- [ ] พัฒนา `AttachmentList` Component
- [ ] แสดงรายการไฟล์แนบที่เชื่อมโยงกับเอกสาร
- [ ] แสดง Badge "เอกสารหลัก"
- [ ] ปุ่มดาวน์โหลดแต่ละไฟล์
- [ ] พัฒนา `DashboardPage` (Req 5.3)
- [ ] สร้าง `KpiCard` Component สำหรับแสดงข้อมูลสรุป
- [ ] สร้าง `MyTasksTable` Component
- [ ] ดึงข้อมูลจาก API endpoint ที่เชื่อมต่อกับ View `v_user_tasks`
- [ ] แสดงคอลัมน์: ชื่อเอกสาร, ประเภท, วันครบกำหนด, สถานะ
- [ ] ปุ่ม "ดำเนินการ" ที่นำไปยังหน้าที่เกี่ยวข้อง
---
## Phase 3: พัฒนาโมดูลเอกสารโต้ตอบและเวิร์กโฟลว์ (Correspondence & Workflow Modules) - สัปดาห์ที่ 5-7
- [ ] พัฒนา `CorrespondenceModule` (Req 3.2)
- [ ] หน้ารายการเอกสาร (`/correspondences`)
- [ ] `DataTable` พร้อม Filter: โครงการ, ประเภทเอกสาร, ช่วงวันที่, ผู้ส่ง/ผู้รับ
- [ ] ปุ่ม "สร้างใหม่", "ดู", "แก้ไข" (ตามสิทธิ์)
- [ ] หน้าสร้าง/แก้ไขเอกสาร (`/correspondences/new`, `/correspondences/[id]/edit`)
- [ ] ฟอร์มสร้างเอกสาร (ใช้ `react-hook-form`)
- [ ] Dropdowns ที่เชื่อมโยงกัน (Project -> Contract)
- [ ] การเลือกผู้รับ (To/CC) หลายองค์กร
- [ ] การใส่ Tag
- [ ] การเชื่อมโยงเอกสารอ้างอิง
- [ ] ใช้ `FileUpload` และ `AttachmentList` Components
- [ ] หน้ารายละเอียดเอกสาร (`/correspondences/[id]`)
- [ ] แสดงข้อมูลทั้งหมดของเอกสาร
- [ ] แสดงประวัติการแก้ไข (Revisions)
- [ ] แสดงสถานะการส่งต่อ (Routings)
- [ ] พัฒนา `RfaModule` (Req 3.5, 5.6)
- [ ] ฟังก์ชันพื้นฐานคล้ายกับ CorrespondenceModule
- [ ] พัฒนา `WorkflowVisualization` Component **(สำคัญ)**
- [ ] ดึงข้อมูลจาก `rfa_workflows` table
- [ ] แสดงขั้นตอนทั้งหมดเป็นลำดับ (เช่น การ์ดหรือไลน์)
- [ ] ขั้นตอนปัจจุบัน (Active) สามารถดำเนินการได้
- [ ] ขั้นตอนอื่นๆ แสดงเป็น Disabled
- [ ] มีปุ่มสำหรับ Action: "อนุมัติ", "ปฏิเสธ", "ขอแก้ไข"
- [ ] สำหรับ Admin: ปุ่ม "บังคับไปขั้นตอนถัดไป", "ย้อนกลับ"
- [ ] แสดงความคิดเห็นในแต่ละขั้นตอน
---
## Phase 4: พัฒนาโมดูลแบบแปลนและคุณสมบัติขั้นสูง (Drawings & Advanced Features) - สัปดาห์ที่ 8-9
- [ ] พัฒนา `DrawingModule` (Req 3.3, 3.4)
- [ ] แยกระหว่าง `ContractDrawingPage` และ `ShopDrawingPage`
- [ ] ฟอร์มสร้าง/แก้ไขแบบแปลน
- [ ] การจัดการ Revision (เช่น การสร้าง Revision ใหม่จาก Revision ปัจจุบัน)
- [ ] การเชื่อมโยง Shop Drawing Revision กับ Contract Drawing
- [ ] พัฒนา `CirculationModule` (Req 3.7)
- [ ] หน้ารายการใบเวียนภายใน
- [ ] ฟอร์มสร้างใบเวียน
- [ ] การมอบหมายงานให้ผู้รับผิดชอบ (Main, Action, Info)
- [ ] หน้ารายละเอียดสำหรับผู้รับผิดชอบกระทำ (แสดงความคิดเห็น, ปุ่มปิดงาน)
- [ ] พัฒนา `AdminPanel` (Req 4.5, 4.6)
- [ ] หน้าจัดการผู้ใช้ (Create/Edit/Delete Users ในองค์กร)
- [ ] หน้าจัดการ Roles และ Permissions
- [ ] หน้าจัดการ Master Data (Tags, Document Types, Categories)
- [ ] หน้าจัดการรูปแบบเลขที่เอกสาร (Document Numbering Formats)
- [ ] พัฒนา `AdvancedSearchPage` (Req 6.2)
- [ ] ฟอร์มค้นหาขั้นสูงพร้อมฟิลด์ต่างๆ
- [ ] ส่งคำขอไปยัง Search API (Elasticsearch)
- [ ] แสดงผลลัพธ์ใน `DataTable`
---
## Phase 5: การทดสอบ ปรับปรุงประสิทธิภาพ และเตรียม Deploy (Testing, Optimization & Deployment) - สัปดาห์ที่ 10
- [ ] ดำเนินการทดสอบ (Testing)
- [ ] **Unit/Integration Tests:**
- [ ] เขียนทดสอบสำหรับ `FileUpload` Component (Vitest + RTL)
- [ ] เขียนทดสอบสำหรับ `DataTable` Component
- [ ] เขียนทดสอบสำหรับ Custom Hooks (เช่น `useAuth`)
- [ ] **E2E Tests:**
- [ ] เขียนทดสอบ User Flow: Login -> สร้าง RFA -> อนุมัติ (Playwright)
- [ ] เขียนทดสอบ User Flow: สร้างใบเวียน -> มอบหมายงาน -> ตอบกลับ
- [ ] ปรับปรุงประสิทธิภาพ (Performance)
- [ ] ใช้ `next/dynamic` สำหรับ lazy loading ของ Components ที่ใหญ่
- [ ] ตรวจสอบการใช้ React Query เพื่อให้แน่ใจว่ามีการ Caching และ Re-fetching ที่เหมาะสม
- [ ] ใช้ Image Optimization ของ Next.js
- [ ] การเตรียม Deploy
- [ ] สร้าง `Dockerfile` สำหรับ Frontend (Multi-stage build)
- [ ] สร้างไฟล์ `docker-compose.yml` สำหรับ `frontend` service
- [ ] กำหนด `build` จาก `Dockerfile`
- [ ] กำหนด `environment` สำหรับ `NEXT_PUBLIC_API_URL`
- [ ] เชื่อมต่อกับ `lcbp3` network
- [ ] ทดสอบ Build และ Run บน Container Station UI
- [ ] ตั้งค่า Nginx Proxy Manager ให้ชี้ `lcbp3.np-dms.work` มายัง Frontend Container

210
infrastructure/Markdown/LCBP3-DMS_V1_3_0_requirements.md Normal file
View File

@@ -0,0 +1,210 @@
# **📝 Documents Management Sytem Version 1.2.1: Application Requirements Specification**
## **📌 1. วัตถุประสงค์**
สร้างเว็บแอปพลิเคชั่นสำหรับระบบบริหารจัดการเอกสารโครงการ (Document Management System)ที่สามารถจัดการและควบคุม การสื่อสารด้วยเอกสารที่ซับซ้อน อย่างมีประสิทธิภาพ
* มีฟังก์ชันหลักในการอัปโหลด จัดเก็บ ค้นหา แชร์ และควบคุมสิทธิ์การเข้าถึงเอกสาร
* ช่วยลดการใช้เอกสารกระดาษ เพิ่มความปลอดภัยในการจัดเก็บข้อมูล
* เพิ่มความสะดวกในการทำงานร่วมกันระหว่างองกรณ์
## **🛠️ 2. สถาปัตยกรรมและเทคโนโลยี (System Architecture & Technology Stack)**
ใช้สถาปัตยกรรมแบบ Headless/API-First ที่ทันสมัย ทำงานทั้งหมดบน QNAP Server ผ่าน Container Station เพื่อความสะดวกในการจัดการและบำรุงรักษา, Domain: np-dms.work, มี fix ip, รัน docker command ใน application ของ Container Station ได้โดยตรง, ประกอบด้วย
* 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 on Windows 11
* Domain: np-dms.work, www.np-dms.work
* ip: 159.192.126.103
* Docker Network: ทุก Service จะเชื่อมต่อผ่านเครือข่ายกลางชื่อ lcbp3 เพื่อให้สามารถสื่อสารกันได้
* Data Storage: /share/dms-data บน QNAP
* ข้อจำกัด: ไม่สามารถใช้ .env ในการกำหนดตัวแปรภายนอกได้ ต้องกำหนดใน docker-compose.yml เท่านั้น
* 2.2. Code Hosting:
* Application name: git
* Service: Gitea (Self-hosted on QNAP)
* Service name: gitea
* Domain: git.np-dms.work
* หน้าที่: เป็นศูนย์กลางในการเก็บและจัดการเวอร์ชันของโค้ด (Source Code) สำหรับทุกส่วน
* 2.3. Backend / Data Platform:
* Application name: lcbp3-backend
* Service: NestJS
* Service name: backend
* Domain: backend.np-dms.work
* Framework: NestJS (Node.js, TypeScript, ESM)
* หน้าที่: จัดการโครงสร้างข้อมูล (Data Models), สร้าง API, จัดการสิทธิ์ผู้ใช้ (Roles & Permissions), และสร้าง Workflow ทั้งหมดของระบบ
* 2.4. Database:
* Application name: lcbp3-db
* Service: mariadb:10.11
* Service name: mariadb
* Domain: db.np-dms.work
* หน้าที่: ฐานข้อมูลหลักสำหรับเก็บข้อมูลทั้งหมด
* Tooling: DBeaver (Community Edition), phpmyadmin สำหรับการออกแบบและจัดการฐานข้อมูล
* 2.5. Database management:
* Application name: lcbp3-db
* Service: phpmyadmin:5-apache
* Service name: pma
* Domain: pma.np-dms.work
* หน้าที่: จัดการฐานข้อมูล mariadb ผ่าน Web UI
* 2.6. Frontend:
* Application name: lcbp3-frontend
* Service: next.js
* 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
* 2.7. Workflow automation:
* Application name: lcbp3-n8n
* Service: n8nio/n8n:latest
* Service name: n8n
* Domain: n8n.np-dms.work
* หน้าที่: จัดการ workflow ระหว่าง Backend และ Line
* 2.8. Reverse Proxy:
* 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) ให้อัตโนมัติ
* **2.9. การจัดการตรรกะทางธุรกิจ (Business Logic Implementation):**
* 2.9.1. ตรรกะทางธุรกิจที่ซับซ้อนทั้งหมด (เช่น การเปลี่ยนสถานะ Workflow [cite: 3.5.4, 3.6.5], การบังคับใช้สิทธิ์ [cite: 4.4], การตรวจสอบ Deadline [cite: 3.2.5]) **จะถูกจัดการในฝั่ง Backend (NestJS)** [cite: 2.3] เพื่อให้สามารถบำรุงรักษาและทดสอบได้ง่าย (Testability)
* 2.9.2. **จะไม่มีการใช้ SQL Triggers** เพื่อป้องกันตรรกะซ่อนเร้น (Hidden Logic) และความซับซ้อนในการดีบัก
* 2.9.3. **ข้อยกเว้น:** ตรรกะเดียวที่จะอยู่ในฐานข้อมูลคือ **Stored Procedure** สำหรับการสร้างเลขที่เอกสาร (Document Numbering) [cite: 3.10] เพื่อป้องกันการซ้ำซ้อนของข้อมูล (Race Condition)
## **📦 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 หลายประเภท (Types) เช่น จดหมาย (Letter), อีเมล์ (Email), Request for Information (RFI), และสามารถเพิ่มประเภทใหม่ได้ในภายหลัง
* 3.2.3. การสร้างเอกสาร (Correspondence):
* ผู้ใช้ที่มีสิทธิ์ (เช่น Document Control) สามารถสร้างเอกสารรอไว้ในสถานะ ฉบับร่าง" (Draft) ได้ ซึ่งผู้ใช้งานต่างองค์กรจะมองไม่เห็น
* เมื่อกด "Submitted" แล้ว การแก้ไข, ถอนเอกสารกลับไปสถานะ Draft, หรือยกเลิก (Cancel) จะต้องทำโดยผู้ใช้ระดับ Admin ขึ้นไป พร้อมระบุเหตุผล
* 3.2.4. การอ้างอิงและจัดกลุ่ม:
* เอกสารสามารถอ้างถึง (Reference) เอกสารฉบับก่อนหน้าได้หลายฉบับ
* สามารถกำหนด Tag ได้หลาย Tag เพื่อจัดกลุ่มและใช้ในการค้นหาขั้นสูง
* 3.2.5. การจัดการ: มีการจัดการอย่างน้อยดังนี้
* สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบของ องกรณ์ ที่เป็นผู้รับได้
* มีระบบแจ้งเตือน ให้ผู้รับผิดชอบขององกรณ์ที่เป็น ผู้รับ/ผู้ส่ง ทราบ เมื่อมีเอกสารใหม่ หรือมีการเปลี่ยนสถานะ
* 3.3. การจัดกาแบบคู่สัญญา (Contract Drawing)
* 3.3.1. วัตถุประสงค์: แบบคู่สัญญา (Contract Drawing) ใช้เพื่ออ้างอิงและใช้ในการตรวจสอบ
* 3.3.2. ประเภทเอกสาร: ไฟล์ PDF
* 3.3.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
* 3.3.4. การอ้างอิงและจัดกลุ่ม: ใช้สำหรับอ้างอิง ใน Shop Drawings, มีการจัดหมวดหมู่ของ Contract Drawing
* 3.4. การจัดกาแบบก่อสร้าง (Shop Drawing)
* 3.4.1. วัตถุประสงค์: แบบก่อสร้าง (Shop Drawing) ใช้เในการตรวจสอบ โดยจัดส่งด้วย Request for Approval (RFA)
* 3.4.2. ประเภทเอกสาร: ไฟล์ PDF
* 3.4.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
* 3.4.4. การอ้างอิงและจัดกลุ่ม: ช้สำหรับอ้างอิง ใน Shop Drawings, มีการจัดหมวดหมู่ของ Shop Drawings
* 3.5. การจัดการเอกสารขออนุมัติ (Request for Approval & Workflow)
* 3.5.1. วัตถุประสงค์: เอกสารขออนุมัติ (Request for Approval) ใช้ในการส่งเอกสารเพิอขออนุมัติ
* 3.5.2. ประเภทเอกสาร: Request for Approval (RFA) เป็นชนิดหนึ่งของ Correspondence ที่มีลักษณะเฉพาะที่ต้องได้รับการอนุมัติ มีประเภทดังนี้:
* Request for Drawing Approval (RFA_DWG)
* Request for Document Approval (RFA_DOC)
* Request for Method statement Approval (RFA_MES)
* Request for Material Approval (RFA_MAT)
* 3.5.2. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
* 3.5.4. การอ้างอิงและจัดกลุ่ม: การจัดการ Drawing (RFA_DWG):
* เอกสาร RFA_DWG จะประกอบไปด้วย Shop Drawing (shop_drawings) หลายแผ่น ซึ่งแต่ละแผ่นมี Revision ของตัวเอง
* Shop Drawing แต่ละ Revision สามารถอ้างอิงถึง Contract Drawing (Ccontract_drawings) หลายแผ่น หรือไม่อ้างถึงก็ได้
* ระบบต้องมีส่วนสำหรับจัดการข้อมูล Master Data ของทั้ง Shop Drawing และ Contract Drawing แยกจากกัน
* 3.6.5. Workflow การอนุมัติ: ต้องรองรับกระบวนการอนุมัติที่ซับซ้อนและเป็นลำดับ เช่น
* ส่งจาก Originator -> Organization 1 -> Organization 2 -> Organization 3 แล้วส่งผลกลับตามลำดับเดิม (โดยถ้า องกรณ์ใดใน Workflow ให้ส่งกลับ ก็สามารถส่งผลกลับตามลำดับเดิมโดยไม่ต้องรอให้ถึง องกรณืในลำดับถัดไป)
* 3.6.6. การจัดการ: มีการจัดการอย่างน้อยดังนี้
* สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบของ องกรณ์ ที่อยู่ใน Workflow ได้
* มีระบบแจ้งเตือน ให้ผู้รับผิดชอบของ องกรณ์ ที่อยู่ใน Workflow ทราบ เมื่อมี RFA ใหม่ หรือมีการเปลี่ยนสถานะ
* 3.6.การจัดการเอกสารนำส่ง (Transmittals)
* 3.6.1. วัตถุประสงค์: เอกสารนำส่ง ใช้สำหรับ นำส่ง Request for Approval (RFAS) หลายฉบับ ไปยังองค์กรอื่น
* 3.6.2. ประเภทเอกสาร: ไฟล์ PDF
* 3.6.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
* 3.6.4. การอ้างอิงและจัดกลุ่ม: เอกสารนำส่ง เป็นส่วนหนึ่งใน Correspondence
* 3.7. ใบเวียนเอกสารภายใน (Internal Circulation Sheet)
* 3.7.1. วัตถุประสงค์: การสื่อสาร เอกสาร (Correspondence) ทุกฉบับ จะมีใบเวียนเอกสารเพื่อควบคุมและมอบหมายงานภายในองค์กร (สามารถดูและแก้ไขได้เฉพาะคนในองค์กร)
* 3.7.2. ประเภทเอกสาร: ไฟล์ PDF
* 3.7.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ในองค์กรนั้น สามารถสร้างและแก้ไขได้
* 3.7.4. การอ้างอิงและจัดกลุ่ม: การระบุผู้รับผิดชอบ:
* ผู้รับผิดชอบหลัก (Main): มีได้หลายคน
* ผู้ร่วมปฏิบัติงาน (Action): มีได้หลายคน
* ผู้ที่ต้องรับทราบ (Information): มีได้หลายคน
* 3.7.5. การติดตามงาน:
* สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบประเภท Main และ Action ได้
* มีระบบแจ้งเตือนเมื่อมี Circulation ใหม่ และแจ้งเตือนล่วงหน้าก่อนถึงวันแล้วเสร็จ
* สามารถปิด Circulation ได้เมื่อดำเนินการตอบกลับไปยังองค์กรผู้ส่ง (Originator) แล้ว หรือ รับทราบแล้ว (For Information)
* 3.8. ประวัติการแก้ไข (Revisions): ระบบจะเก็บประวัติการสร้างและแก้ไข เอกสารทั้งหมด
* 3.9. การจัดเก็บ: (ปรับปรุงตามสถาปัตยกรรมใหม่)
* เอกสารและไฟล์แนบทั้งหมดจะถูกจัดเก็บในโฟลเดอร์บน Server (/share/dms-data/) [cite: 2.1]
* ข้อมูล Metadata ของไฟล์ (เช่น ชื่อไฟล์, ขนาด, path) จะถูกเก็บในตาราง attachments (ตารางกลาง)
* ไฟล์จะถูกเชื่อมโยงกับเอกสารประเภทต่างๆ ผ่านตารางเชื่อม (Junction tables) เช่น correspondence_attachments, circulation_attachments, shop_drawing_revision_attachments ,และ contracy_drawing_attachments
* สถาปัตยกรรมแบบรวมศูนย์นี้ *แทนที่* แนวคิดเดิมที่จะแยกโฟลเดอร์ตามประเภทเอกสาร เพื่อรองรับการขยายระบบที่ดีกว่า
* 3.10. การจัดการเลขที่เอกสาร (Document Numbering):
* 3.10.1. ระบบต้องสามารถสร้างเลขที่เอกสาร (เช่น correspondence_number) ได้โดยอัตโนมัติ
* 3.10.2. การนับเลข Running Number (SEQ) จะต้องนับแยกตาม Key ดังนี้: **โครงการ (Project)**, **องค์กรผู้ส่ง (Originator Organization)**, **ประเภทเอกสาร (Document Type)** และ **ปีปัจจุบัน (Year)**
* 3.10.3. ผู้ดูแลระบบ (Admin) ต้องสามารถกำหนด "รูปแบบ" (Format Template) ของเลขที่เอกสารได้ (เช่น {ORG_CODE}-{TYPE_CODE}-{YEAR_SHORT}-{SEQ:4}) โดยกำหนดแยกตามโครงการและประเภทเอกสาร
## **🔐 4. ข้อกำหนดด้านสิทธิ์และการเข้าถึง (Access Control Requirements)**
* 4.1. ภาพรวม: ผู้ใช้และองค์กรสามารถดูและแก้ไขเอกสารได้ตามสิทธิ์ที่ได้รับ โดยระบบสิทธิ์จะเป็นแบบ Role-Based Access Control (RBAC)
* 4.2. ระดับของสิทธิ์:
* Global Roles: สิทธิ์ในภาพรวมของระบบ
* Project-Specific Roles: สิทธิ์ที่ถูกกำหนดให้ผู้ใช้สำหรับโครงการนั้นๆ โดยเฉพาะ (เช่น เป็น Editor ในโครงการ A แต่เป็น Viewer ในโครงการ B)
* 4.3. บทบาท (Roles) พื้นฐาน:
* Superadmin: ไม่มีข้อจำกัดใดๆ สามารถจัดการได้ทุกอย่างข้ามองค์กรณ์
* Admin: มีสิทธิ์เต็มที่ แต่จำกัดเฉพาะในองค์กรที่ตัวเองสังกัด สามารถจัดการผู้ใช้ในองค์กรณ์ได้ สามารถสร้าง Role ใหม่และกำหนดสิทธิ์ (Permissions) เพิ่มเติมได้ในภายหลังผ่านหน้า Admin
* Document Control สามารถ เพิ่ม/แก้ไข/ลบ เอกสาร เฉพาะในองค์กรณ์ที่ตัวเองสังกัด ไม่สามารถจัดการผู้ใช้ได้
* Editor: สามารถ เพิ่ม/แก้ไข เอกสารที่กำหนดไว้ เฉพาะในองค์กรณ์ที่ตัวเองสังกัด
* Viewer: สามารถดู เอกสาร เฉพาะในองค์กรณ์ที่ตัวเองสังกัด
* 4.4. การบังคับใช้สิทธิ์: สิทธิ์ขององค์กรจะครอบคลุมสิทธิ์ของผู้ใช้ และการเข้าถึงข้อมูลที่เกี่ยวข้องกับโครงการ (เช่น การแก้ไขเอกสาร) จะถูกตรวจสอบเทียบกับสิทธิ์ที่ผู้ใช้มีในโครงการนั้นๆ โดยเฉพาะ
* 4.5. (ใหม่) การจัดการข้อมูลหลัก (Master Data Management):
* ระบบจะต้องมีส่วน "Admin Panel" (สำหรับ Superadmin และ Admin) เพื่อใช้จัดการข้อมูลหลัก (Master Data) ของระบบ
* ข้อมูลหลักที่ต้องจัดการได้เป็นอย่างน้อย:
* ประเภทเอกสาร (เช่น correspondence_types, rfa_types)
* หมวดหมู่แบบ (เช่น shop_drawing_categories)
* Tags ที่ใช้ในระบบ
* สถานะเอกสาร (หากจำเป็นต้องเพิ่มในอนาคต)
* 4.6. (ใหม่) การเริ่มต้นใช้งาน (User & Organization Onboarding):
* การเพิ่มองค์กรณ์ใหม่ (Organizations) เข้าสู่ระบบ จะต้องดำเนินการโดย Superadmin เท่านั้น
* เมื่อ Superadmin สร้างองค์กรณ์ใหม่ จะต้องสามารถกำหนดผู้ใช้ (User) อย่างน้อย 1 คน ให้เป็น "Admin" ประจำองค์กรณ์นั้นๆ
* Admin ประจำองค์กณ์รจึงจะสามารถเพิ่มผู้ใช้ (Editor, Viewer, Document Control) คนอื่นๆ เข้าสู่องค์กรของตนเองได้
## **👥 5\. ข้อกำหนดด้านผู้ใช้งาน (User Interface & Experience)**
* 5.1. Layout หลัก: หน้าเว็บใช้รูปแบบ App Shell ที่ประกอบด้วย:
* Navbar (ส่วนบน): แสดงชื่อระบบ, เมนูผู้ใช้ (Profile), เมนูสำหรับ 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 ที่ผู้ใช้ต้องดำเนินการ
* 5.4. การติดตามสถานะ: องค์กรสามารถติดตามสถานะเอกสารทั้งของตนเอง (Originator) และสถานะเอกสารที่ส่งมาถึงตนเอง (Recipient)
* 5.5. การจัดการข้อมูลส่วนตัว (Profile Page): ผู้ใช้สามารถจัดการข้อมูลส่วนตัวและเปลี่ยนรหัสผ่านของตนเองได้
* 5.6. การจัดการเอกสารทางเทคนิค (Technical Documents & Workflow): ผู้ใช้สามารถดู Technical Document ในรูปแบบ Workflow ทั้งหมดได้ในหน้าเดียว, ขั้นตอนที่ยังไม่ถึงหรือผ่านไปแล้วจะเป็นรูปแบบ diable, สามารถดำเนินการได้เฉพาะในขั้นตอนที่ได้รับมอบหมายงาน (active) เช่น ตรวจสอบแล้ว เพื่อไปยังขั้นตอนต่อไป, สิทธิ์ admin ขึ้นไป สามรถกด ไปยังขั้นตอนต่อไป ได้ทุกขั้นตอน, การย้อนกลับ ไปขั้นตอนก่อนหน้า สามารถทำได้โดย สิทธิ์ admin ขึ้นไป
* 5.7. ข้อกำหนด UI/UX การแนบไฟล์ (File Attachment UX):
* ระบบต้องรองรับการอัปโหลดไฟล์หลายไฟล์พร้อมกัน (Multi-file upload) เช่น การลากและวาง (Drag-and-Drop)
* ในหน้าอัปโหลด (เช่น สร้าง RFA หรือ Correspondence) ผู้ใช้ต้องสามารถกำหนดได้ว่าไฟล์ใดเป็น "เอกสารหลัก" (Main Document เช่น PDF) และไฟล์ใดเป็น "เอกสารแนบประกอบ" (Supporting Attachments เช่น .dwg, .docx, .zip)
## **6. ข้อกำหนดที่ไม่ใช่ฟังก์ชันการทำงาน (Non-Functional Requirements)**
* 6.1. การบันทึกการกระทำ (Audit Log): ทุกการกระทำที่สำคัญของผู้ใช้ (สร้าง, แก้ไข, ลบ, ส่ง) จะถูกบันทึกไว้ใน audit_logs เพื่อการตรวจสอบย้อนหลัง
* 6.2. การค้นหา (Search): ระบบต้องมีฟังก์ชันการค้นหาขั้นสูง ที่สามารถค้นหาเอกสาร **correspondence**, **rfa**, **shop_drawing**, **contract-drawing**, **transmittal** และ **ใบเวียน (Circulations)** จากหลายเงื่อนไขพร้อมกันได้ เช่น ค้นหาจากชื่อเรื่อง, ประเภท, วันที่, และ Tag
* 6.3. การทำรายงาน (Reporting): สามารถจัดทำรายงานสรุปแยกประเภทของ Correspondence ประจำวัน, สัปดาห์, เดือน, และปีได้
* 6.4. ประสิทธิภาพ (Performance): มีการใช้ Caching กับข้อมูลที่เรียกใช้บ่อย และใช้ Pagination ในตารางข้อมูลเพื่อจัดการข้อมูลจำนวนมาก
* 6.5. ความปลอดภัย (Security):
* มีระบบ Rate Limiting เพื่อป้องกันการโจมตีแบบ Brute-force
* การจัดการ Secret (เช่น รหัสผ่าน DB, JWT Secret) จะต้องทำผ่าน Environment Variable ของ Docker เพื่อความปลอดภัยสูงสุด
* 6.6. (ใหม่) การสำรองข้อมูลและการกู้คืน (Backup & Recovery):
* ระบบจะต้องมีกลไกการสำรองข้อมูลอัตโนมัติสำหรับฐานข้อมูล MariaDB [cite: 2.4] และไฟล์เอกสารทั้งหมดใน /share/dms-data [cite: 2.1] (เช่น ใช้ HBS 3 ของ QNAP หรือสคริปต์สำรองข้อมูล) อย่างน้อยวันละ 1 ครั้ง
* ต้องมีแผนการกู้คืนระบบ (Disaster Recovery Plan) ในกรณีที่ Server หลัก (QNAP) ใช้งานไม่ได้
* 6.7. (ใหม่) กลยุทธ์การแจ้งเตือน (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]

655
infrastructure/Markdown/LCBP3-DMS_V1_4_0_Backend_Development_Plan.md Normal file
View File

@@ -0,0 +1,655 @@
# 📋 แผนการพัฒนา Backend (NestJS) - LCBP3-DMS v1.4.0
## 🎯 ภาพรวมโครงการ
พัฒนา Backend สำหรับระบบบริหารจัดการเอกสารโครงการ (Document Management System) ที่รองรับการจัดการเอกสารที่ซับซ้อน มีระบบ Workflow การอนุมัติ และการควบคุมสิทธิ์แบบ RBAC 3 ระดับ
---
## 📐 สถาปัตยกรรมระบบ
### Technology Stack
- **Framework:** NestJS (TypeScript, ESM)
- **Database:** MariaDB 10.11
- **ORM:** TypeORM
- **Authentication:** JWT + Passport
- **Authorization:** CASL (RBAC)
- **File Upload:** Multer
- **Search:** Elasticsearch
- **Notification:** Nodemailer + n8n (Line Integration)
- **Scheduling:** @nestjs/schedule (Cron Jobs)
- **Documentation:** Swagger
### โครงสร้างโมดูล (Domain-Driven)
```tree
src/
├── common/ # Shared Module
│ ├── auth/ # JWT, Guards
│ ├── config/ # Configuration
│ ├── decorators/ # @RequirePermission
│ ├── entities/ # Base Entities
│ ├── exceptions/ # Global Filters
│ ├── file-storage/ # FileStorageService
│ ├── guards/ # RBAC Guard
│ ├── interceptors/ # Audit, Transform
│ └── services/ # Notification, etc.
├── modules/
│ ├── user/ # Users, Roles, Permissions
│ ├── project/ # Projects, Contracts, Organizations
│ ├── master/ # Master Data
│ ├── correspondence/ # Correspondence Management
│ ├── rfa/ # RFA & Workflows
│ ├── drawing/ # Shop/Contract Drawings
│ ├── circulation/ # Internal Circulation
│ ├── transmittal/ # Transmittals
│ ├── search/ # Elasticsearch
│ └── document-numbering/ # Internal Service
└── database/ # Migrations & Seeds
```
---
## 🗓️ แผนการพัฒนาแบบ Phase-Based
## **Phase 0: Infrastructure Setup (สัปดาห์ที่ 1)**
Milestone: สร้างโครงสร้างพื้นฐานและเชื่อมต่อ Services
### Phase 0: Tasks
- **[✅]T0.1 Setup QNAP Container Station**
- สร้าง Docker Network: `lcbp3`
- Setup docker-compose.yml สำหรับ:
- MariaDB (db.np-dms.work)
- PHPMyAdmin (pma.np-dms.work)
- Backend (backend.np-dms.work)
- Nginx Proxy Manager (npm.np-dms.work)
- กำหนด Environment Variables ใน docker-compose.yml (ไม่ใช้ .env)
- Deliverable: Services ทั้งหมดรันได้และเชื่อมต่อกันผ่าน Network
- **[✅]T0.2 Initialize NestJS Project**
- สร้างโปรเจกต์ใหม่ด้วย Nest CLI
- ติดตั้ง Dependencies:
```bash
npm install @nestjs/typeorm typeorm mysql2
npm install @nestjs/config
npm install class-validator class-transformer
npm install @nestjs/jwt @nestjs/passport passport passport-jwt
npm install casl
npm install @nestjs/platform-express multer
npm install @nestjs/swagger
npm install helmet rate-limiter-flexible
npm install bcrypt
npm install --save-dev @nestjs/testing jest @types/jest @types/passport-jwt @types/multer supertest
npm install @nestjs/cache-manager cache-manager
npm install @nestjs/schedule
npm install @nestjs/config
npm install @nestjs/elasticsearch @elastic/elasticsearch
npm install nodemailer @types/nodemailer
npm install uuid @types/uuid
```
````
- Setup โครงสร้างโฟลเดอร์ตาม Domain-Driven Architecture
- Deliverable: Project Structure พร้อม, แสดง Swagger ที่ `/api`
- **[✅]T0.3 Setup Database Connection**
- Import SQL Schema v1.4.0 เข้า MariaDB
- Run Seed Data (organizations, users, roles, permissions)
- Configure TypeORM ใน AppModule
- ทดสอบ Connection
- Deliverable: Database พร้อมใช้งาน, มี Seed Data
- **[✅]T0.4 Setup Git Repository**
- สร้าง Repository ใน Gitea (git.np-dms.work)
- Setup .gitignore, README.md
- Commit Initial Project
- Deliverable: Code อยู่ใน Version Control
---
## **Phase 1: Core Foundation (สัปดาห์ที่ 2-3)**
Milestone: ระบบ Authentication, Authorization และ Base Entities
### Phase 1: Tasks
- **[ ] T1.1 CommonModule - Base Infrastructure**
- [ ] สร้าง Base Entity (id, created_at, updated_at, deleted_at)
- [ ] สร้าง Global Exception Filter
- [ ] สร้าง Response Transform Interceptor
- [ ] สร้าง Audit Log Interceptor
- [ ] สร้าง RequestContextService - สำหรับเก็บข้อมูลระหว่าง Request
- [ ] สร้าง ConfigService - Centralized configuration management
- [ ] สร้าง CryptoService - สำหรับ encryption/decryption
- [ ] Deliverable: Common Services พร้อมใช้
- **[ ] T1.2 AuthModule - JWT Authentication**
- [ ] สร้าง Entity: User
- [ ] สร้าง AuthService:
- [ ] `login(username, password)` → JWT Token
- [ ] `validateUser(username, password)` → User | null
- [ ] Password Hashing (bcrypt)
- [ ] สร้าง JWT Strategy (Passport)
- [ ] สร้าง JwtAuthGuard
- [ ] สร้าง Controllers:
- [ ] `POST /auth/login` → { access_token }
- [ ] `POST /auth/register` (Admin only)
- [ ] `GET /auth/profile` (Protected)
- [ ] Deliverable: ล็อกอิน/ล็อกเอาต์ทำงานได้
- **[ ] T1.3 UserModule - User Management**
- [ ] สร้าง Entities: User, Role, Permission, UserRole
- [ ] สร้าง UserService CRUD
- [ ] สร้าง RoleService CRUD
- [ ] สร้าง PermissionService (Read-Only, จาก Seed)
- [ ] สร้าง Controllers:
- [ ] `GET /users` → List Users (Paginated)
- [ ] `GET /users/:id` → User Detail
- [ ] `POST /users` → Create User
- [ ] `PUT /users/:id` → Update User
- [ ] `DELETE /users/:id` → Soft Delete
- [ ] `GET /roles` → List Roles
- [ ] `POST /roles` → Create Role (Admin)
- [ ] `PUT /roles/:id/permissions` → Assign Permissions
- [ ] Deliverable: จัดการผู้ใช้และ Role ได้
- **[ ] T1.4 RBAC Guard - Authorization**
- [ ] สร้าง `@RequirePermission()` Decorator
- [ ] สร้าง RbacGuard ที่ตรวจสอบ:
- [ ] Global Permissions
- [ ] Organization Permissions
- [ ] Project Permissions
- [ ] Contract Permissions
- [ ] Permission Hierarchy Logic
```bash
// Current: 3-level hierarchy
// Recommended: 4-level hierarchy (Global → Organization → Project → Contract)
@Injectable()
export class RbacGuard implements CanActivate {
async canActivate(context: ExecutionContext): Promise<boolean> {
const requiredPermission = this.getRequiredPermission(context);
const user = this.getUser(context);
// Check permissions in order: Global → Org → Project → Contract
return await this.checkGlobalPermissions(user, requiredPermission) ||
await this.checkOrgPermissions(user, requiredPermission) ||
await this.checkProjectPermissions(user, requiredPermission) ||
await this.checkContractPermissions(user, requiredPermission);
}
}
````
- [ ] Integration กับ CASL
- [ ] Deliverable: ระบบสิทธิ์ทำงานได้ทั้ง 4 ระดับ
- **T1.5 ProjectModule - Base Structures**
- [ ] สร้าง Entities:
- [ ] Organization
- [ ] Project
- [ ] Contract
- [ ] ProjectOrganization (Junction)
- [ ] ContractOrganization (Junction)
- [ ] UserAssignment Entity - สำหรับจัดการ user assignments ตาม scope
- [ ] สร้าง Services & Controllers:
- [ ] `GET /organizations` → List
- [ ] `POST /projects` → Create (Superadmin)
- [ ] `GET /projects/:id/contracts` → List Contracts
- [ ] `POST /projects/:id/contracts` → Create Contract
- [ ] UserAssignment - สำหรับจัดการ user assignments ตาม scope
- [ ] ProjectOrganization - สำหรับจัดการความสัมพันธ์ project-organization
- [ ] ContractOrganization - สำหรับจัดการความสัมพันธ์ contract-organization
- [ ] Deliverable: จัดการโครงสร้างโปรเจกต์ได้
---
## **Phase 2: Master Data & File Management (สัปดาห์ที่ 4)**
Milestone: Master Data และระบบจัดการไฟล์
### Phase 2: Tasks
- **[ ] T2.1 MasterModule - Master Data Management**
- [ ] สร้าง Entities:
- [ ] CorrespondenceType
- [ ] CorrespondenceStatus
- [ ] RfaType
- [ ] RfaStatusCode
- [ ] RfaApproveCode
- [ ] CirculationStatusCode
- [ ] Tag
- [ ] สร้าง Services & Controllers (CRUD):
- [ ] `GET /master/correspondence-types`
- [ ] `POST /master/tags` → Create Tag
- [ ] `GET /master/tags` → List Tags (Autocomplete)
- [ ] Deliverable: Admin จัดการ Master Data ได้
- **[ ] T2.2 FileStorageService - Central File Management**
- [ ] สร้าง Attachment Entity
- [ ] สร้าง FileStorageService: (การจัดเก็บไฟล์ในรูปแบบ centralized storage, ครอบคลุมการจัดการไฟล์แนบทั้งหมด, Security Measures)
- [ ] `uploadFile(file: Express.Multer.File)` → Attachment
- [ ] `getFilePath(attachmentId)` → string
- [ ] `deleteFile(attachmentId)` → boolean
- [ ] จัดเก็บไฟล์ใน `/share/dms-data/uploads/{YYYY}/{MM}/`
- [ ] สร้าง Controller:
- [ ] `POST /files/upload` → { attachment_id, url }
- [ ] `GET /files/:id/download` → File Stream (Protected)
- [ ] Access Control: ตรวจสอบสิทธิ์ผ่าน Junction Table
- [ ] Deliverable: อัปโหลด/ดาวน์โหลดไฟล์ได้อย่างปลอดภัย
- **[ ] T2.3 DocumentNumberingModule - Internal Service**
- [ ] สร้าง Entities:
- [ ] DocumentNumberFormat
- [ ] DocumentNumberCounter
- [ ] สร้าง DocumentNumberingService: รวม Stored Procedure (sp_get_next_document_number), Error Handling และ Retry Logic
- [ ] `generateNextNumber(projectId, orgId, typeId, year)` → string
- [ ] เรียก Stored Procedure: `sp_get_next_document_number`
- [ ] Format ตาม Template: `{ORG_CODE}-{TYPE_CODE}-{YEAR_SHORT}-{SEQ:4}`
- **ไม่มี Controller** (Internal Service เท่านั้น)
- [ ] Deliverable: Service สร้างเลขที่เอกสารได้ถูกต้อง
---
## **Phase 3: Correspondence & RFA Core (สัปดาห์ที่ 5-6)**
Milestone: ระบบเอกสารโต้ตอบและ RFA
### Phase 3: Tasks
- **[ ] T3.1 CorrespondenceModule - Basic CRUD**
- [ ] สร้าง Entities:
- [ ] Correspondence
- [ ] CorrespondenceRevision
- [ ] CorrespondenceRecipient
- [ ] CorrespondenceTag
- [ ] CorrespondenceReference
- [ ] CorrespondenceAttachment
- [ ] สร้าง CorrespondenceService: Complex Business Rules, State Machine สำหรับ Status Transitions
- [ ] `create(dto)` → Correspondence
- [ ] สร้าง Correspondence + Revision แรก (rev 0)
- [ ] เรียก DocumentNumberingService
- [ ] สร้าง Recipients (TO/CC)
- [ ] สร้าง Tags
- [ ] สร้าง Attachments
- [ ] `update(id, dto)` → Correspondence
- [ ] สร้าง Revision ใหม่
- [ ] Update `is_current` flag
- [ ] `findAll(filters)` → Paginated List
- [ ] `findById(id)` → Correspondence with Current Revision
- [ ] สร้าง Controllers:
- [ ] `POST /correspondences` → Create
- [ ] `GET /correspondences` → List (Filter by type, status, org)
- [ ] `GET /correspondences/:id` → Detail
- [ ] `PUT /correspondences/:id` → Update (Create new revision)
- [ ] `DELETE /correspondences/:id` → Soft Delete (Admin only)
- [ ] Deliverable: สร้าง/แก้ไข/ดูเอกสารได้
- **[ ] T3.2 CorrespondenceModule - Advanced Features**
- [ ] Implement Status Transitions:
- [ ] `DRAFT` → `SUBMITTED` (Document Control)
- [ ] `SUBMITTED` → `CLOSED` (Admin)
- [ ] `SUBMITTED` → `CANCELLED` (Admin + Reason)
- [ ] Implement References:
- [ ] `POST /correspondences/:id/references` → Link Documents
- [ ] Implement Search (Basic):
- `GET /correspondences/search?q=...`
- [ ] Deliverable: Workflow พื้นฐานทำงานได้
- **[ ] T3.3 RfaModule - Basic CRUD**
- [ ] สร้าง Entities:
- [ ] Rfa
- [ ] RfaRevision
- [ ] RfaItem (Junction to Shop Drawings)
- [ ] สร้าง RfaService: Complex Business Rules
- [ ] `create(dto)` → Rfa
- [ ] สร้าง Correspondence + Rfa + RfaRevision
- [ ] เชื่อม Shop Drawing Revisions (สำหรับ RFA_DWG)
- [ ] `findAll(filters)` → Paginated List
- [ ] `findById(id)` → Rfa with Items
- [ ] สร้าง Controllers:
- [ ] `POST /rfas` → Create
- [ ] `GET /rfas` → List
- [ ] `GET /rfas/:id` → Detail
- [ ] Deliverable: สร้าง RFA และเชื่อม Shop Drawings ได้
---
## **Phase 4: Drawing Management (สัปดาห์ที่ 7)**
Milestone: ระบบจัดการแบบ
### Phase 4: Tasks
- **[ ] T4.1 DrawingModule - Contract Drawings**
- [ ] สร้าง Entities:
- [ ] ContractDrawing
- [ ] ContractDrawingVolume
- [ ] ContractDrawingCat
- [ ] ContractDrawingSubCat
- [ ] ContractDrawingSubcatCatMap
- [ ] ContractDrawingAttachment
- [ ] สร้าง ContractDrawingService CRUD
- [ ] สร้าง Controllers:
- [ ] `GET /drawings/contract` → List
- [ ] `POST /drawings/contract` → Create (Admin)
- [ ] `GET /drawings/contract/:id` → Detail
- [ ] Deliverable: จัดการ Contract Drawings ได้
- **[ ] T4.2 DrawingModule - Shop Drawings**
- [ ] สร้าง Entities:
- [ ] ShopDrawing
- [ ] ShopDrawingRevision
- [ ] ShopDrawingMainCategory
- [ ] ShopDrawingSubCategory
- [ ] ShopDrawingRevisionContractRef
- [ ] ShopDrawingRevisionAttachment
- [ ] สร้าง ShopDrawingService CRUD
- [ ] สร้าง Controllers:
- [ ] `GET /drawings/shop` → List
- [ ] `POST /drawings/shop` → Create
- [ ] `POST /drawings/shop/:id/revisions` → Create Revision
- [ ] `GET /drawings/shop/:id` → Detail with Revisions
- [ ] Link Shop Drawing Revision → Contract Drawings
- [ ] Deliverable: จัดการ Shop Drawings และ Revisions ได้
---
## **Phase 5: Workflow Systems (สัปดาห์ที่ 8-9)**
Milestone: ระบบ Workflow ทั้งหมด
### Phase 5: Tasks
- **[ ] T5.1 RfaModule - Workflow Implementation**
- [ ] สร้าง Entities:
- [ ] RfaWorkflowTemplate
- [ ] RfaWorkflowTemplateStep
- [ ] RfaWorkflow (Transaction Log)
- [ ] สร้าง RfaWorkflowService: Advanced Workflow Features
- [ ] `initiateWorkflow(rfaId, templateId)` → void
- [ ] สร้าง RfaWorkflow records ตาม Template
- [ ] กำหนด Step 1 เป็น PENDING
- [ ] `completeStep(rfaId, stepNumber, action, comments)` → void
- [ ] Update Status → COMPLETED
- [ ] Set Next Step → PENDING
- [ ] Send Notifications
- [ ] `rejectStep(rfaId, stepNumber, reason)` → void
- [ ] Update Status → REJECTED
- [ ] Send back to Originator
- [ ] สร้าง Controllers:
- [ ] `POST /rfas/:id/workflow/start` → Start Workflow
- [ ] `POST /rfas/:id/workflow/steps/:stepNumber/complete` → Complete Step
- [ ] `GET /rfas/:id/workflow` → Get Workflow Status
- [ ] Deliverable: RFA Workflow ทำงานได้
- **[ ] T5.2 CirculationModule - Internal Routing**
- [ ] สร้าง Entities:
- [ ] Circulation
- [ ] CirculationTemplate
- [ ] CirculationTemplateAssignee
- [ ] CirculationRouting (Transaction Log)
- [ ] CirculationAttachment
- [ ] สร้าง CirculationService:
- [ ] `create(correspondenceId, dto)` → Circulation
- [ ] สร้าง Circulation (1:1 กับ Correspondence)
- [ ] สร้าง Routing ตาม Template
- [ ] `assignUser(circulationId, stepNumber, userId)` → void
- [ ] `completeStep(circulationId, stepNumber, comments)` → void
- [ ] `close(circulationId)` → void (เมื่อตอบกลับองค์กรผู้ส่งแล้ว)
- สร้าง Controllers:
- [ ] `POST /circulations` → Create
- [ ] `GET /circulations/:id` → Detail
- [ ] `POST /circulations/:id/steps/:stepNumber/complete` → Complete
- [ ] `POST /circulations/:id/close` → Close
- [ ] Deliverable: ใบเวียนภายในองค์กรทำงานได้
- **[ ] T5.3 TransmittalModule - Document Forwarding**
- [ ] สร้าง Entities:
- [ ] Transmittal
- [ ] TransmittalItem
- [ ] สร้าง TransmittalService:
- [ ] `create(dto)` → Transmittal
- [ ] สร้าง Correspondence + Transmittal
- [ ] เชื่อม Multiple Correspondences เป็น Items
- [ ] สร้าง Controllers:
- [ ] `POST /transmittals` → Create
- [ ] `GET /transmittals` → List
- [ ] `GET /transmittals/:id` → Detail with Items
- [ ] Deliverable: สร้าง Transmittal ได้
---
## **Phase 6: Advanced Features (สัปดาห์ที่ 10-11)**
Milestone: ฟีเจอร์ขั้นสูง
### Phase 6: Tasks
- **[ ] T6.1 SearchModule - Elasticsearch Integration**
- [ ] Setup Elasticsearch Container ใน docker-compose.yml
- [ ] สร้าง SearchService:
- [ ] `indexDocument(entity)` → void
- [ ] `updateDocument(entity)` → void
- [ ] `deleteDocument(entity)` → void
- [ ] `search(query, filters)` → SearchResult[]
- [ ] Index ทุกครั้งที่ Create/Update:
- [ ] Correspondence
- [ ] RFA
- [ ] Shop Drawing
- [ ] Contract Drawing
- [ ] Circulation
- [ ] Transmittal
- [ ] สร้าง Controllers:
- [ ] `GET /search?q=...&type=...&from=...&to=...` → Results
- [ ] Deliverable: ค้นหาขั้นสูงทำงานได้
- **[ ] T6.2 NotificationModule - Email & Line**
- [ ] สร้าง NotificationService:
- [ ] `sendEmail(to, subject, body)` → void (Nodemailer)
- [ ] `sendLine(userId, message)` → void (ผ่าน n8n Webhook)
- [ ] `createSystemNotification(userId, message, entityType, entityId)` → void
- [ ] Integrate กับ Workflow Events:
- [ ] เมื่อสร้าง Correspondence ใหม่ → แจ้ง Recipients
- [ ] เมื่อสร้าง Circulation → แจ้ง Assignees
- [ ] เมื่อ RFA Workflow ถึง Step → แจ้ง Responsible Org
- [ ] เมื่อใกล้ถึง Deadline → แจ้ง (Optional)
- [ ] สร้าง Controllers:
- [ ] `GET /notifications` → List User's Notifications
- [ ] `PUT /notifications/:id/read` → Mark as Read
- [ ] Deliverable: ระบบแจ้งเตือนทำงานได้
- **[ ] T6.3 Reporting & Analytics**
- [ ] สร้าง ReportService:
- [ ] `getCorrespondenceSummary(projectId, from, to)` → Report
- [ ] `getRfaSummary(projectId, from, to)` → Report
- [ ] `getActivityLog(userId, from, to)` → Report
- [ ] ใช้ Views จาก Database:
- [ ] `v_current_correspondences`
- [ ] `v_current_rfas`
- [ ] `v_user_tasks`
- [ ] `v_audit_log_details`
- [ ] สร้าง Controllers:
- [ ] `GET /reports/correspondence` → Summary (CSV, PDF)
- [ ] `GET /reports/rfa` → Summary
- [ ] `GET /reports/activity` → User Activity
- [ ] Deliverable: สร้างรายงานได้
- **T6.4 Audit Log & Activity Feed**
- [ ] AuditLogInterceptor ทำงานอัตโนมัติแล้ว (Phase 1)
- [ ] สร้าง AuditLogService:
- [ ] `log(userId, action, entityType, entityId, details)` → void
- [ ] `getUserActivity(userId, limit)` → AuditLog[]
- [ ] สร้าง Controllers:
- [ ] `GET /audit-logs` → List (Admin only)
- [ ] `GET /audit-logs/user/:userId` → User's Activity
- [ ] Deliverable: ดู Audit Log ได้
---
## **Phase 7: Testing & Optimization (สัปดาห์ที่ 12-13)**
Milestone: ทดสอบและปรับปรุงประสิทธิภาพ
### Phase 7: Tasks
- **[ ] T7.1 Unit Testing**
- [ ] เขียน Unit Tests สำหรับ Services สำคัญ:
- [ ] AuthService (login, validateUser)
- [ ] RbacGuard (permission checks)
- [ ] DocumentNumberingService (number generation)
- [ ] CorrespondenceService (create, update)
- [ ] RfaWorkflowService (workflow logic)
- [ ] Target: 70% Code Coverage
- [ ] Deliverable: Unit Tests ผ่านทั้งหมด
- **[ ] T7.2 Integration Testing**
- [ ] เขียน Integration Tests:
- [ ] Authentication Flow (login → access protected route)
- [ ] Document Creation Flow (create correspondence → attach files)
- [ ] RFA Workflow Flow (start → step 1 → step 2 → complete)
- [ ] Circulation Flow (create → assign → complete → close)
- [ ] ทดสอบ SQL Views (v_user_all_permissions, v_user_tasks)
- [ ] ใช้ Test Database แยกต่างหาก
- [ ] Deliverable: Integration Tests ผ่าน
- **[ ] T7.3 E2E Testing**
- [ ] เขียน E2E Tests:
- [ ] User Registration & Login
- [ ] Create Correspondence (Full Flow)
- [ ] Create RFA with Shop Drawings
- [ ] Complete RFA Workflow
- [ ] Search Documents
- [ ] Deliverable: E2E Tests ผ่าน
- **[ ] T7.4 Performance Optimization**
- [ ] Implement Caching:
- [ ] Cache Master Data (Roles, Permissions)
- [ ] Cache User Permissions (ใช้ @nestjs/cache-manager)
- [ ] Database Optimization:
- [ ] Review Indexes
- [ ] Optimize Queries (N+1 Problem)
- I[ ] mplement Pagination ทุก List Endpoint
- [ ] Deliverable: Response Time < 200ms (90th percentile)
- **[ ] T7.5 Security Hardening**
- [ ] Implement Rate Limiting (ใช้ rate-limiter-flexible)
- [ ] Setup Helmet (Security Headers)
- [ ] Review CORS Configuration
- [ ] Input Validation (ตรวจสอบ DTOs ทั้งหมด)
- [ ] Deliverable: Security Checklist ผ่าน
---
## **Phase 8: Documentation & Deployment (สัปดาห์ที่ 14)**
Milestone: เอกสารและ Deploy สู่ Production
### Phase 8: Tasks
- **[ ] T8.1 API Documentation**
- [ ] ครบทุก Endpoint ใน Swagger:
- [ ] ใส่ Description, Example Request/Response
- [ ] ระบุ Required Permissions
- [ ] ใส่ Error Responses
- [ ] Export Swagger JSON → Frontend Team
- [ ] Deliverable: Swagger Docs สมบูรณ์
- **[ ] T8.2 Technical Documentation**
- [ ] เขียนเอกสาร:
- [ ] Architecture Overview
- [ ] Module Structure
- [ ] Database Schema Diagram
- [ ] API Design Patterns
- [ ] Deployment Guide
- [ ] Deliverable: Technical Docs พร้อม
- **[ ] T8.3 Deployment Preparation**
- [ ] สร้าง Production docker-compose.yml
- [ ] Setup Environment Variables ใน QNAP
- [ ] Setup Nginx Proxy Manager (SSL Certificate)
- [ ] Setup Backup Scripts (Database + Files)
- [ ] Deliverable: Deployment Guide พร้อม
- **[ ] T8.4 Production Deployment**
- [ ] Deploy Backend ไปยัง backend.np-dms.work
- [ ] ทดสอบ API ผ่าน Postman
- [ ] Monitor Logs (Winston)
- [ ] Setup Health Check Endpoint (`GET /health`)
- [ ] Deliverable: Backend รันบน Production
- **T8.5 Handover to Frontend Team**
- [ ] Demo API ให้ Frontend Team
- [ ] ส่งมอบ Swagger Documentation
- [ ] ส่งมอบ Postman Collection
- [ ] Workshop: วิธีใช้ Authentication & RBAC
- [ ] Deliverable: Frontend เริ่มพัฒนาได้
---
## 📊 สรุป Timeline
| Phase | ระยะเวลา | จำนวนงาน | Output หลัก |
| ------- | -------------- | ------------ | ---------------------------- |
| Phase 0 | 1 สัปดาห์ | 4 | Infrastructure Ready |
| Phase 1 | 2 สัปดาห์ | 5 | Auth & User Management |
| Phase 2 | 1 สัปดาห์ | 3 | Master Data & File Storage |
| Phase 3 | 2 สัปดาห์ | 3 | Correspondence & RFA Core |
| Phase 4 | 1 สัปดาห์ | 2 | Drawing Management |
| Phase 5 | 2 สัปดาห์ | 3 | Workflow Systems |
| Phase 6 | 2 สัปดาห์ | 4 | Advanced Features |
| Phase 7 | 2 สัปดาห์ | 5 | Testing & Optimization |
| Phase 8 | 1 สัปดาห์ | 5 | Documentation & Deploy |
| **รวม** | **14 สัปดาห์** | **34 Tasks** | **Production-Ready Backend** |
---
## 🎯 Critical Success Factors
1. **Database First**: ใช้ Schema v1.4.0 เป็นหลัก ไม่แก้ไข Schema โดยไม่จำเป็น
2. **Emphasizing Soft Delete**: Service ทั้งหมดที่ทำการ Query ข้อมูล (เช่น findAll, findById) ต้อง ใช้ Global Filter หรือ Default Scope ของ TypeORM เพื่อกรอง WHERE deleted_at IS NULL เสมอ
3. **API Contract**: ทุก Endpoint ต้องมี Swagger Documentation สมบูรณ์
4. **Security**: RBAC ต้องทำงานถูกต้อง 100% ก่อน Deploy
5. **Testing**: Code Coverage อย่างน้อย 70% ก่อน Production
6. **Performance**: Response Time < 200ms (90th percentile)
7. **Documentation**: เอกสารต้องครบถ้วนเพื่อ Handover ให้ Frontend Team
---
## 🚀 ขั้นตอนถัดไป
1. **Approve แผนนี้** → ปรับแต่งตาม Feedback
2. **Setup Phase 0** → เริ่มสร้าง Infrastructure
3. **Daily Standup** → รายงานความก้าวหน้าทุกวัน
4. **Weekly Review** → ทบทวนความก้าวหน้าทุกสัปดาห์
5. **Deploy to Production** → Week 14
---
**หมายเหตุ:** แผนนี้สามารถปรับแต่งได้ตามความต้องการและข้อจำกัดของทีม หาก Phase ใดใช้เวลามากกว่าที่คาดการณ์ ควรปรับ Timeline ให้เหมาะสม

900
infrastructure/Markdown/LCBP3-DMS_V1_4_0_Data_Dictionary.bak.md Normal file
View File

@@ -0,0 +1,900 @@
# **สรุปตารางฐานข้อมูล (Data Dictionary) - LCBP3-DMS (V1.4.0)**
เอกสารนี้สรุปโครงสร้างตาราง, Foreign Keys (FK), และ Constraints ที่สำคัญทั้งหมดในฐานข้อมูล LCBP3-DMS (v1.4.0) เพื่อใช้เป็นเอกสารอ้างอิงสำหรับทีมพัฒนา Backend (NestJS) และ Frontend (Next.js) โดยอิงจาก Requirements และ SQL Script ล่าสุด
## **1. 🏢 Core & Master Data (องค์กร, โครงการ, สัญญา)**
#### **1.1. organization_roles**
ตาราง Master เก็บประเภทบทบาทขององค์กร (เช่น OWNER, CONTRACTOR)
| Column | Type | Key | Description |
| :-------- | :---------- | :----- | :--------------------------------------------------------------- |
| id | INT | **PK** | ID ของตาราง |
| role_name | VARCHAR(20) | UK | ชื่อบทบาท (OWNER, DESIGNER, CONSULTANT, CONTRACTOR, THIRD PARTY) |
- **Unique Keys (UK):** ux_roles_name (role_name)
---
#### **1.2. organizations**
ตาราง Master เก็บข้อมูลองค์กรทั้งหมดที่เกี่ยวข้องในระบบ
| Column | Type | Key | Description |
| :---------------- | :----------- | :----- | :--------------------------------------------- |
| id | INT | **PK** | ID ของตาราง |
| organization_code | VARCHAR(20) | UK | รหัสองค์กร |
| organization_name | VARCHAR(255) | | ชื่อองค์กร |
| role_id | INT | FK | บทบาทขององค์กร (FK \-> organization_roles(id)) |
| is_active | BOOLEAN | | สถานะการใช้งาน |
| created_at | TIMESTAMP | | วันที่สร้าง |
| updated_at | TIMESTAMP | | วันที่แก้ไขล่าสุด |
- **Foreign Keys (FK):**
- role_id -> organization_roles(id) (ON DELETE SET NULL)
- **Unique Keys (UK):** ux_organizations_code (organization_code)
---
#### **1.3. projects**
ตาราง Master เก็บข้อมูลโครงการ (เช่น LCBP3C1, LCBP3C2)
| Column | Type | Key | Description |
| :------------------------- | :----------- | :----- | :------------------------------------------------------ |
| id | INT | **PK** | ID ของตาราง |
| project_code | VARCHAR(50) | UK | รหัสโครงการ |
| project_name | VARCHAR(255) | | ชื่อโครงการ |
| parent_project_id | INT | FK | รหัสโครงการหลัก (ถ้ามี) (FK \-> projects(id)) |
| contractor_organization_id | INT | FK | รหัสองค์กรผู้รับเหมา (ถ้ามี) (FK \-> organizations(id)) |
| is_active | TINYINT(1) | | สถานะการใช้งาน |
- **Foreign Keys (FK):**
- parent_project_id -> projects(id) (ON DELETE SET NULL)
- contractor_organization_id -> organizations(id) (ON DELETE SET NULL)
- **Unique Keys (UK):** uq_pro_code (project_code)
---
#### **1.4. contracts**
ตาราง Master เก็บข้อมูลสัญญา
| Column | Type | Key | Description |
| :------------ | :----------- | :----- | :----------------- |
| id | INT | **PK** | ID ของตาราง |
| contract_code | VARCHAR(50) | UK | รหัสสัญญา |
| contract_name | VARCHAR(255) | | ชื่อสัญญา |
| description | TEXT | | คำอธิบายสัญญา |
| start_date | DATE | | วันที่เริ่มสัญญา |
| end_date | DATE | | วันที่สิ้นสุดสัญญา |
| created_at | TIMESTAMP | | วันที่สร้าง |
| updated_at | TIMESTAMP | | วันที่แก้ไขล่าสุด |
- **Unique Keys (UK):** ux_contracts_code (contract_code)
---
## **2. 👥 Users & RBAC (ผู้ใช้, สิทธิ์, บทบาท)**
#### **2.1. users**
ตาราง Master เก็บข้อมูลผู้ใช้งาน (User)
| Column | Type | Key | Description |
| :-------------- | :----------- | :----- | :-------------------------------------- |
| user_id | INT | **PK** | ID ของตาราง |
| username | VARCHAR(50) | UK | ชื่อผู้ใช้งาน |
| password_hash | VARCHAR(255) | | รหัสผ่าน (Hashed) |
| first_name | VARCHAR(50) | | ชื่อจริง |
| last_name | VARCHAR(50) | | นามสกุล |
| email | VARCHAR(100) | UK | อีเมล |
| line_id | VARCHAR(100) | | LINE ID |
| organization_id | INT | FK | สังกัดองค์กร (FK \-> organizations(id)) |
| is_active | TINYINT(1) | | สถานะการใช้งาน |
| failed_attempts | INT | | จำนวนครั้งที่ล็อกอินล้มเหลว |
| locked_until | DATETIME | | ล็อกอินไม่ได้จนถึงเวลา |
| last_login_at | TIMESTAMP | | วันที่และเวลาที่ล็อกอินล่าสุด |
| created_at | TIMESTAMP | | วันที่สร้าง |
| updated_at | TIMESTAMP | | วันที่แก้ไขล่าสุด |
- **Foreign Keys (FK):**
- organization_id -> organizations(id) (ON DELETE SET NULL)
- **Unique Keys (UK):** ux_users_username (username), ux_users_email (email)
---
#### **2.2. roles**
ตาราง Master เก็บ "บทบาท" ของผู้ใช้ในระบบ (เช่น SUPER_ADMIN, ADMIN, EDITOR)
| Column | Type | Key | Description |
| :---------- | :----------- | :----- | :-------------------------------------------------- |
| role_id | INT | **PK** | ID ของตาราง |
| role_code | VARCHAR(50) | UK | รหัสบทบาท (เช่น SUPER_ADMIN, ADMIN, EDITOR, VIEWER) |
| role_name | VARCHAR(100) | | ชื่อบทบาท |
| description | TEXT | | คำอธิบายบทบาท |
| is_system | BOOLEAN | | (1 = บทบาทของระบบ ลบไม่ได้) |
- **Unique Keys (UK):** role_code
---
#### **2.3. permissions**
ตาราง Master เก็บ "สิทธิ์" (Permission) หรือ "การกระทำ" ทั้งหมดในระบบ
| Column | Type | Key | Description |
| :-------------- | :----------- | :----- | :------------------------------------------ |
| permission_id | INT | **PK** | ID ของตาราง |
| permission_code | VARCHAR(100) | UK | รหัสสิทธิ์ (เช่น rfas.create, rfas.view) |
| description | TEXT | | คำอธิบายสิทธิ์ |
| module | VARCHAR(50) | | โมดูลที่เกี่ยวข้อง |
| scope_level | ENUM(...) | | ระดับขอบเขตของสิทธิ์ (GLOBAL, ORG, PROJECT) |
| is_active | TINYINT(1) | | สถานะการใช้งาน |
- **Unique Keys (UK):** ux_permissions_code (permission_code)
---
#### **2.4. role_permissions (ตารางเชื่อม)**
ตารางเชื่อมระหว่าง roles และ permissions (M:N)
| Column | Type | Key | Description |
| :------------ | :--- | :--------- | :----------------------------------------------- |
| role_id | INT | **PK**, FK | ID ของบทบาท (FK \-> roles(role_id)) |
| permission_id | INT | **PK**, FK | ID ของสิทธิ์ (FK \-> permissions(permission_id)) |
- **Foreign Keys (FK):**
- role_id -> roles(role_id) (ON DELETE CASCADE)
- permission_id -> permissions(permission_id) (ON DELETE CASCADE)
---
#### **2.5. user_roles (ตารางเชื่อม)**
ตารางเชื่อมผู้ใช้ (users) กับบทบาท (roles) ในระดับ **Global** (M:N)
| Column | Type | Key | Description |
| :------ | :--- | :--------- | :----------------------------------- |
| user_id | INT | **PK**, FK | ID ของผู้ใช้ (FK \-> users(user_id)) |
| role_id | INT | **PK**, FK | ID ของบทบาท (FK \-> roles(role_id)) |
- **Foreign Keys (FK):**
- user_id -> users(user_id) (ON DELETE CASCADE)
- role_id -> roles(role_id) (ON DELETE CASCADE)
---
#### **2.6. user_project_roles (ตารางเชื่อม)**
ตารางเชื่อมผู้ใช้ (users) กับบทบาท (roles) ในระดับ **Project-Specific** (M:N)
| Column | Type | Key | Description |
| :--------- | :--- | :--------- | :----------------------------------- |
| user_id | INT | **PK**, FK | ID ของผู้ใช้ (FK \-> users(user_id)) |
| project_id | INT | **PK**, FK | ID ของโครงการ (FK \-> projects(id)) |
| role_id | INT | **PK**, FK | ID ของบทบาท (FK \-> roles(role_id)) |
- **Foreign Keys (FK):**
- user_id -> users(user_id) (ON DELETE CASCADE)
- project_id -> projects(id) (ON DELETE CASCADE)
- role_id -> roles(role_id) (ON DELETE CASCADE)
---
## **3. ✉️ Correspondences (เอกสารหลัก, Revisions)**
#### **3.1. correspondence_types**
ตาราง Master เก็บประเภทเอกสารโต้ตอบ (เช่น RFA, RFI, LETTER, MOM)
| Column | Type | Key | Description |
| :--------- | :----------- | :----- | :------------------------- |
| id | INT | **PK** | ID ของตาราง |
| type_code | VARCHAR(50) | UK | รหัสประเภท (เช่น RFA, RFI) |
| type_name | VARCHAR(255) | | ชื่อประเภท |
| sort_order | INT | | ลำดับการแสดงผล |
| is_active | TINYINT(1) | | สถานะการใช้งาน |
- **Unique Keys (UK):** type_code
---
#### **3.2. correspondence_status**
ตาราง Master เก็บสถานะของเอกสาร (เช่น DRAFT, SUBMITTED, CLOSED)
| Column | Type | Key | Description |
| :---------- | :----------- | :----- | :------------------------------------ |
| id | INT | **PK** | ID ของตาราง |
| status_code | VARCHAR(50) | UK | รหัสสถานะหนังสือ (เช่น DRAFT, SUBOWN) |
| status_name | VARCHAR(255) | | ชื่อสถานะหนังสือ |
| sort_order | INT | | ลำดับการแสดงผล |
| is_active | TINYINT(1) | | สถานะการใช้งาน |
- **Unique Keys (UK):** status_code
---
#### **3.3. correspondences (Master)**
ตาราง "แม่" ของเอกสารโต้ตอบ เก็บข้อมูลที่ไม่เปลี่ยนตาม Revision (เช่น เลขที่เอกสาร)
| Column | Type | Key | Description |
| :------------------------ | :----------- | :----- | :----------------------------------------------- |
| id | INT | **PK** | ID ของตาราง (นี่คือ "Master ID" ที่ใช้เชื่อมโยง) |
| correspondence_number | VARCHAR(100) | UK | เลขที่เอกสาร (สร้างจาก DocumentNumberingModule) |
| correspondence_type_id | INT | FK | ประเภทเอกสาร (FK \-> correspondence_types(id)) |
| is_internal_communication | TINYINT(1) | | (1 = ภายใน, 0 = ภายนอก) |
| project_id | INT | FK | อยู่ในโครงการ (FK \-> projects(id)) |
| originator_id | INT | FK | องค์กรผู้ส่ง (FK \-> organizations(id)) |
| created_at | DATETIME | | วันที่สร้าง |
| created_by | INT | FK | ผู้สร้าง (FK \-> users(user_id)) |
| deleted_at | DATETIME | | สำหรับ Soft Delete |
- **Foreign Keys (FK):**
- correspondence_type_id -> correspondence_types(id) (ON DELETE RESTRICT)
- project_id -> projects(id) (ON DELETE CASCADE)
- originator_id -> organizations(id) (ON DELETE SET NULL)
- created_by -> users(user_id) (ON DELETE SET NULL)
- **Unique Keys (UK):** uq_corr_no_per_project (project_id, correspondence_number)
---
#### **3.4. correspondence_revisions (Revisions)**
ตาราง "ลูก" เก็บประวัติการแก้ไข (Revisions) ของ correspondences (1:N) **(ปรับปรุง V1.4.0)**
| Column | Type | Key | Description |
| :----------------------- | :----------- | :----- | :------------------------------------------------------- |
| id | INT | **PK** | **ID ของ Revision** |
| correspondence_id | INT | FK, UK | Master ID (FK \-> correspondences(id)) |
| revision_number | INT | UK | หมายเลข Revision (0, 1, 2...) |
| revision_label | VARCHAR(10) | | **(ใหม่)** Revision ที่แสดง (เช่น A, B, 1.1) |
| is_current | BOOLEAN | UK | (1 = Revision ปัจจุบัน) |
| correspondence_status_id | INT | FK | สถานะของ Revision นี้ (FK \-> correspondence_status(id)) |
| title | VARCHAR(255) | | เรื่อง |
| document_date | DATE | | วันที่ในเอกสาร |
| issued_date | DATETIME | | วันที่ออกเอกสาร |
| received_date | DATETIME | | วันที่ลงรับเอกสาร |
| due_date | DATETIME | | **(ใหม่)** วันที่ครบกำหนด (ตาม Requirements 3.2.5) |
| description | TEXT | | **(ใหม่)** คำอธิบายการแก้ไขใน Revision นี้ |
| details | JSON | | ข้อมูลเฉพาะ (เช่น RFI details) |
| created_at | DATETIME | | **(ใหม่)** วันที่สร้างเอกสาร |
| created_by | INT | FK | ผู้สร้าง (FK \-> users(user_id)) |
| updated_by | INT | **FK** | **(ใหม่)** ผู้แก้ไขล่าสุด (FK \-> users(user_id)) |
- **Foreign Keys (FK):**
- correspondence_id -> correspondences(id) (ON DELETE CASCADE)
- correspondence_status_id -> correspondence_status(id) (ON DELETE RESTRICT)
- created_by -> users(user_id) (ON DELETE SET NULL)
- updated_by -> users(user_id) (ON DELETE SET NULL)
- **Unique Keys (UK):**
- uq_master_revision_number (correspondence_id, revision_number) (ป้องกัน Rev ซ้ำใน Master เดียว)
- uq_master_current (correspondence_id, is_current) (ป้องกัน is_current = TRUE ซ้ำใน Master เดียว)
- **Check Constraints (CHK):** chk_rev_format (ตรวจสอบรูปแบบ revision_label)
---
#### **3.5. correspondence_recipients (ตารางเชื่อม)**
ตารางเชื่อมผู้รับ (TO/CC) สำหรับเอกสารแต่ละฉบับ (M:N)
| Column | Type | Key | Description |
| :------------------------ | :--------------- | :--------- | :---------------------------------------------------------------- |
| correspondence_id | INT | **PK**, FK | ID ของเอกสาร (FK \-> correspondence_revisions(correspondence_id)) |
| recipient_organization_id | INT | **PK**, FK | ID องค์กรผู้รับ (FK \-> organizations(id)) |
| recipient_type | ENUM('TO', 'CC') | **PK** | ประเภทผู้รับ (TO หรือ CC) |
- **Foreign Keys (FK):**
- correspondence_id -> correspondence_revisions(correspondence_id) (ON DELETE CASCADE)
- recipient_organization_id -> organizations(id) (ON DELETE RESTRICT)
---
#### **3.6. correspondence_tags (ตารางเชื่อม)**
ตารางเชื่อมระหว่าง correspondences และ tags (M:N)
| Column | Type | Key | Description |
| :---------------- | :--- | :--------- | :---------------------------------------- |
| correspondence_id | INT | **PK**, FK | ID ของเอกสาร (FK \-> correspondences(id)) |
| tag_id | INT | **PK**, FK | ID ของ Tag (FK \-> tags(id)) |
- **Foreign Keys (FK):**
- correspondence_id -> correspondences(id) (ON DELETE CASCADE)
- tag_id -> tags(id) (ON DELETE CASCADE)
---
#### **3.7. correspondence_references (ตารางเชื่อม)**
ตารางเชื่อมการอ้างอิงระหว่างเอกสาร (M:N)
| Column | Type | Key | Description |
| :-------------------- | :--- | :--------- | :--------------------------------------------- |
| src_correspondence_id | INT | **PK**, FK | ID เอกสารต้นทาง (FK \-> correspondences(id)) |
| tgt_correspondence_id | INT | **PK**, FK | ID เอกสารเป้าหมาย (FK \-> correspondences(id)) |
- **Foreign Keys (FK):**
- src_correspondence_id -> correspondences(id) (ON DELETE CASCADE)
- tgt_correspondence_id -> correspondences(id) (ON DELETE CASCADE)
---
## **4. 📐 approval: RFA (เอกสารขออนุมัติ, Workflows)**
#### **4.1. rfa_types / ...\_status_codes / ...\_approve_codes**
ตาราง Master สำหรับ RFA
- **rfa_types:** ประเภท RFA (เช่น DWG, DOC, MAT)
- **rfa_status_codes:** สถานะ RFA (เช่น DFT \- Draft, FAP \- For Approve)
- **rfa_approve_codes:** รหัสผลการอนุมัติ (เช่น 1A \- Approved, 3R \- Revise and Resubmit)
---
#### **4.2. rfas (Master)**
ตาราง "แม่" ของ RFA (มีความสัมพันธ์ 1:N กับ rfa_revisions)
| Column | Type | Key | Description |
| :---------- | :------- | :----- | :-------------------------------- |
| id | INT | **PK** | ID ของตาราง (RFA Master ID) |
| rfa_type_id | INT | FK | ประเภท RFA (FK \-> rfa_types(id)) |
| created_at | DATETIME | | วันที่สร้าง |
| created_by | INT | FK | ผู้สร้าง (FK \-> users(user_id)) |
| deleted_at | DATETIME | | สำหรับ Soft Delete |
- **Foreign Keys (FK):**
- rfa_type_id -> rfa_types(id)
- created_by -> users(user_id) (ON DELETE SET NULL)
---
#### **4.3. rfa_revisions (Revisions)**
ตาราง "ลูก" เก็บประวัติ (Revisions) ของ rfas (1:N) **(ปรับปรุง V1.4.0)**
| Column | Type | Key | Description |
| :------------------ | :----------- | :----- | :-------------------------------------------------------- |
| id | INT | **PK** | **ID ของ Revision** |
| correspondence_id | INT | FK | Master ID ของ Correspondence (FK \-> correspondences(id)) |
| rfa_id | INT | FK, UK | Master ID ของ RFA (FK \-> rfas(id)) |
| revision_number | INT | UK | หมายเลข Revision (0, 1, 2...) |
| revision_label | VARCHAR(10) | | **(ใหม่)** Revision ที่แสดง (เช่น A, B, 1.1) |
| is_current | BOOLEAN | UK | (1 = Revision ปัจจุบัน) |
| rfa_status_code_id | INT | FK | สถานะ RFA (FK \-> rfa_status_codes(id)) |
| rfa_approve_code_id | INT | FK | ผลการอนุมัติ (FK \-> rfa_approve_codes(id)) |
| title | VARCHAR(255) | | เรื่อง |
| document_date | DATE | | **(ใหม่)** วันที่ในเอกสาร |
| issued_date | DATE | | **(ใหม่)** วันที่ส่งขออนุมัติ |
| received_date | DATETIME | | **(ใหม่)** วันที่ลงรับเอกสาร |
| approved_date | DATE | | **(ใหม่)** วันที่อนุมัติ |
| description | TEXT | | **(ใหม่)** คำอธิบายการแก้ไขใน Revision นี้ |
| created_at | DATETIME | | **(ใหม่)** วันที่สร้างเอกสาร |
| created_by | INT | FK | ผู้สร้าง (FK \-> users(user_id)) |
| updated_by | INT | **FK** | **(ใหม่)** ผู้แก้ไขล่าสุด (FK \-> users(user_id)) |
- **Foreign Keys (FK):**
- correspondence_id -> correspondences(id) (ON DELETE CASCADE)
- rfa_id -> rfas(id) (ON DELETE CASCADE)
- rfa_status_code_id -> rfa_status_codes(id)
- rfa_approve_code_id -> rfa_approve_codes(id) (ON DELETE SET NULL)
- created_by -> users(user_id) (ON DELETE SET NULL)
- updated_by -> users(user_id) (ON DELETE SET NULL)
- **Unique Keys (UK):**
- uq_rr_rev_number (rfa_id, revision_number) (ป้องกัน Rev ซ้ำใน Master เดียว)
- uq_rr_current (rfa_id, is_current) (ป้องกัน is_current=TRUE ซ้ำใน Master เดียว)
---
#### **4.4. rfa_items (ตารางเชื่อม)**
ตารางเชื่อมระหว่าง rfa_revisions (ที่เป็นประเภท DWG) กับ shop_drawing_revisions (M:N)
| Column | Type | Key | Description |
| :----------------------- | :--- | :------------- | :--------------------------------------------------------------- |
| rfarev_correspondence_id | INT | **PK**, FK | ID ของ RFA Revision (FK \-> rfa_revisions(correspondence_id)) |
| shop_drawing_revision_id | INT | **PK**, UK, FK | ID ของ Shop Drawing Revision (FK \-> shop_drawing_revisions(id)) |
- **Foreign Keys (FK):**
- rfarev_correspondence_id -> rfa_revisions(correspondence_id) (ON DELETE CASCADE)
- shop_drawing_revision_id -> shop_drawing_revisions(id) (ON DELETE CASCADE)
---
#### **4.5. rfa_workflow_templates / ...\_steps / ...\_workflows**
ตารางที่เกี่ยวข้องกับ Workflow การอนุมัติ RFA
- **rfa_workflow_templates:** ตาราง Master เก็บแม่แบบสายอนุมัติ (เช่น "สายอนุมัติ 3 ขั้นตอน")
- **rfa_workflow_template_steps:** ตารางลูก เก็บขั้นตอนในแม่แบบ (เช่น Step 1: Org A (Review), Step 2: Org B (Approve))
- **rfa_workflows:** ตารางประวัติ (Log) การอนุมัติของ RFA จริงตามสายงงาน
---
## **5. 📐 Drawings (แบบ, หมวดหมู่)**
#### **5.1. contract_drawing_volumes / ...\_cats / ...\_sub_cats**
ตาราง Master สำหรับ "แบบคู่สัญญา" (Contract Drawings)
- **contract_drawing_volumes:** เก็บ "เล่ม" ของแบบ
- **contract_drawing_cats:** เก็บ "หมวดหมู่หลัก" ของแบบ
- **contract_drawing_sub_cats:** เก็บ "หมวดหมู่ย่อย" ของแบบ
---
#### **5.2. contract_drawing_subcat_cat_maps (ตารางเชื่อม - ใหม่)**
**(ใหม่)** ตารางเชื่อมระหว่าง หมวดหมู่หลัก-ย่อย (M:N)
| Column | Type | Key | Description |
| :--------- | :--- | :--------- | :----------------- |
| project_id | INT | **PK**, FK | ID ของโครงการ |
| sub_cat_id | INT | **PK**, FK | ID ของหมวดหมู่ย่อย |
| cat_id | INT | **PK**, FK | ID ของหมวดหมู่หลัก |
- **Foreign Keys (FK) (ตามเจตนา):**
- (project_id, sub_cat_id) -> contract_drawing_sub_cats(project_id, id)
- (project_id, cat_id) -> contract_drawing_cats(project_id, id)
- **Unique Keys (UK):**
- ux_map_unique (project_id, sub_cat_id, cat_id)
---
#### **5.3. contract_drawings (Master)**
ตาราง Master เก็บข้อมูล "แบบคู่สัญญา"
| Column | Type | Key | Description |
| :--------- | :----------- | :----- | :-------------------------------------------------- |
| id | INT | **PK** | ID ของตาราง |
| project_id | INT | FK, UK | โครงการ (FK \-> projects(id)) |
| condwg_no | VARCHAR(255) | UK | เลขที่แบบสัญญา |
| title | VARCHAR(255) | | ชื่อแบบสัญญา |
| sub_cat_id | INT | FK | หมวดหมู่ย่อย (FK \-> contract_drawing_sub_cats(id)) |
| volume_id | INT | FK | เล่ม (FK \-> contract_drawing_volumes(id)) |
| created_at | TIMESTAMP | | วันที่สร้าง |
| updated_at | TIMESTAMP | | วันที่แก้ไขล่าสุด |
| deleted_at | DATETIME | | **(ใหม่)** วันที่ลบ |
| updated_by | INT | FK | **(ใหม่)** ผู้แก้ไขล่าสุด |
- **Foreign Keys (FK):**
- fk_condwg_project (project_id) -> projects(id) (ON DELETE CASCADE)
- fk_condwg_subcat_same_project (project_id, sub_cat_id) -> contract_drawing_sub_cats(project_id, id) (ON DELETE RESTRICT)
- fk_condwg_volume_same_project (project_id, volume_id) -> contract_drawing_volumes(project_id, id) (ON DELETE RESTRICT)
- **Unique Keys (UK):** ux_condwg_no_project (project_id, condwg_no)
---
#### **5.4. shop_drawing_main_categories / ...\_sub_categories**
ตาราง Master สำหรับ "แบบก่อสร้าง" (Shop Drawings)
- **shop_drawing_main_categories:** เก็บ "หมวดหมู่หลัก" (เช่น ARCH, STR)
- **shop_drawing_sub_categories:** เก็บ "หมวดหมู่ย่อย" (เช่น STR-COLUMN)
---
#### **5.5. shop_drawings (Master)**
ตาราง Master เก็บข้อมูล "แบบก่อสร้าง"
| Column | Type | Key | Description |
| :--------------- | :----------- | :----- | :----------------------------------------------------- |
| id | INT | **PK** | ID ของตาราง |
| project_id | INT | FK | โครงการ (FK \-> projects(id)) |
| drawing_number | VARCHAR(100) | UK | เลขที่ Shop Drawing |
| title | VARCHAR(500) | | ชื่อแบบ |
| main_category_id | INT | FK | หมวดหมู่หลัก (FK \-> shop_drawing_main_categories(id)) |
| sub_category_id | INT | FK | หมวดหมู่ย่อย (FK \-> shop_drawing_sub_categories(id)) |
| created_at | TIMESTAMP | | วันที่สร้าง |
| updated_at | TIMESTAMP | | วันที่แก้ไขล่าสุด |
| deleted_at | DATETIME | | **(ใหม่)** วันที่ลบ |
| updated_by | INT | FK | **(ใหม่)** ผู้แก้ไขล่าสุด |
- **Foreign Keys (FK):** project_id, main_category_id, sub_category_id
- **Unique Keys (UK):** ux_sd_drawing_number (drawing_number)
---
#### **5.6. shop_drawing_revisions (Revisions)**
ตาราง "ลูก" เก็บประวัติ (Revisions) ของ shop_drawings (1:N)
| Column | Type | Key | Description |
| :-------------- | :---------- | :----- | :------------------------------------------------ |
| id | INT | **PK** | ID ของ Revision |
| shop_drawing_id | INT | FK, UK | Master ID (FK \-> shop_drawings(id)) |
| revision_number | INT | UK | **(ปรับปรุง)** หมายเลข Revision (เช่น 0, 1, 2...) |
| revision_label | VARCHAR(10) | | **(ปรับปรุง)** Revision ที่แสดง (เช่น A, B, 1.1) |
| revision_date | DATE | | วันที่ของ Revision |
| description | TEXT | | คำอธิบายการแก้ไข |
| created_at | TIMESTAMP | | วันที่สร้าง |
- **Foreign Keys (FK):**
- shop_drawing_id -> shop_drawings(id) (ON DELETE CASCADE)
- **Unique Keys (UK):** ux_sd_rev_drawing_revision (shop_drawing_id, revision_number)
---
#### **5.7. shop_drawing_revision_contract_refs (ตารางเชื่อม)**
ตารางเชื่อมระหว่าง shop_drawing_revisions กับ contract_drawings (M:N)
| Column | Type | Key | Description |
| :----------------------- | :--- | :--------- | :--------------------------------------------------------------- |
| shop_drawing_revision_id | INT | **PK**, FK | ID ของ Shop Drawing Revision (FK \-> shop_drawing_revisions(id)) |
| contract_drawing_id | INT | **PK**, FK | ID ของ Contract Drawing (FK \-> contract_drawings(id)) |
- **Foreign Keys (FK):**
- shop_drawing_revision_id -> shop_drawing_revisions(id) (ON DELETE CASCADE)
- contract_drawing_id -> contract_drawings(id) (ON DELETE CASCADE)
---
## **6. 🔄 Circulations (ใบเวียนภายใน)**
#### **6.1. circulation_status_codes**
ตาราง Master เก็บสถานะใบเวียน (เช่น OPEN, IN_REVIEW, COMPLETED)
| Column | Type | Key | Description |
| :---------- | :---------- | :----- | :------------------------ |
| id | INT | **PK** | ID ของตาราง |
| code | VARCHAR(20) | UK | รหัสสถานะการดำเนินงาน |
| description | VARCHAR(50) | | คำอธิบายสถานะการดำเนินงาน |
| sort_order | INT | | ลำดับการแสดงผล |
| is_active | TINYINT(1) | | สถานะการใช้งาน |
---
#### **6.2. circulations (Master)**
ตาราง "แม่" ของใบเวียนเอกสารภายใน
| Column | Type | Key | Description |
| :---------------------- | :----------- | :----- | :---------------------------------------------------------------- |
| id | INT | **PK** | ID ของตารางใบเวียน |
| correspondence_id | INT | UNIQUE | ID ของเอกสาร (จากตาราง correspondences) |
| organization_id | INT | FK | ID ขององค์กรณ์ที่เป็นเจ้าของใบเวียนนี้ (FK \-> organizations(id)) |
| circulation_no | VARCHAR(100) | | เลขที่ใบเวียน |
| circulation_subject | VARCHAR(500) | | เรื่องใบเวียน |
| circulation_status_code | VARCHAR(20) | FK | รหัสสถานะใบเวียน (FK \-> circulation_status_codes(code)) |
| created_by_user_id | INT | FK | ID ของผู้สร้างใบเวียน (FK \-> users(user_id)) |
| submitted_at | TIMESTAMP | | วันที่ส่งใบเวียน |
| closed_at | TIMESTAMP | | วันที่ปิดใบเวียน |
| created_at | TIMESTAMP | | วันที่สร้าง |
| updated_at | TIMESTAMP | | วันที่แก้ไขล่าสุด |
- **Foreign Keys (FK):**
- correspondence_id -> correspondences(id)
- organization_id -> organizations(id)
- circulation_status_code -> circulation_status_codes(code)
- created_by_user_id -> users(user_id)
---
#### **6.3. circulation_templates / ...\_assignees / ...\_routings**
ตารางที่เกี่ยวข้องกับ Workflow การส่งต่อเอกสาร (Req 3.5.4)
- **circulation_templates:** ตาราง Master เก็บแม่แบบสายงาน (เช่น "ส่งให้ CSC ตรวจสอบ")
- **circulation_template_assignees:** ตารางลูก เก็บขั้นตอนในแม่แบบ (เช่น Step 1: ส่งไป Org A, Step 2: ส่งไป Org B)
- **circulation_routings:** ตารางประวัติ (Log) การส่งต่อของเอกสารจริงตาม Workflow
---
## **7. 📤 Transmittals (เอกสารนำส่ง)**
#### **7.1. transmittals**
ตารางข้อมูลเฉพาะของเอกสารนำส่ง (เป็นตารางลูก 1:1 ของ correspondences)
| Column | Type | Key | Description |
| :---------------- | :-------- | :--------- | :------------------------------------------------ |
| correspondence_id | INT | **PK**, FK | ID ของเอกสาร (FK \-> correspondences(id)) |
| purpose | ENUM(...) | | วัตถุประสงค์ (FOR_APPROVAL, FOR_INFORMATION, ...) |
| remarks | TEXT | | หมายเหตุ |
- **Foreign Keys (FK):** correspondence_id -> correspondences(id) (ON DELETE CASCADE)
---
#### **7.2. transmittal_items (ตารางเชื่อม)**
ตารางเชื่อมระหว่าง transmittals และเอกสารที่นำส่ง (M:N) **(ปรับปรุง V1.4.0)**
| Column | Type | Key | Description |
| :------------------------- | :--------------- | :--------- | :-------------------------------------------------------------- |
| **id** | **INT** | **PK** | **(ใหม่)** ID ของรายการ |
| transmittal_id | INT | **FK**, UK | ID ของ Transmittal (FK \-> transmittals(correspondence_id)) |
| **item_correspondence_id** | INT | **FK**, UK | **(เปลี่ยน)** ID ของเอกสารที่แนบไป (FK \-> correspondences(id)) |
| **quantity** | **INT** | | **(ใหม่)** จำนวน |
| **remarks** | **VARCHAR(255)** | | **(ใหม่)** หมายเหตุสำหรับรายการนี้ |
- **Foreign Keys (FK):**
- transmittal_id -> transmittals(correspondence_id) (ON DELETE CASCADE)
- item_correspondence_id -> correspondences(id) (ON DELETE CASCADE)
- **Unique Keys (UK):** ux_transmittal_item (transmittal_id, item_correspondence_id)
---
## **8. 📎 File Management (ไฟล์แนบ)**
#### **8.1. attachments (Master)**
ตาราง "กลาง" เก็บไฟล์แนบทั้งหมดของระบบ (ตาม Requirements 3.9)
| Column | Type | Key | Description |
| :------------------ | :----------- | :----- | :-------------------------------------------- |
| id | INT | **PK** | ID ของไฟล์แนบ |
| original_filename | VARCHAR(255) | | ชื่อไฟล์ดั้งเดิมตอนอัปโหลด |
| stored_filename | VARCHAR(255) | | ชื่อไฟล์ที่เก็บจริงบน Server (ป้องกันชื่อซ้ำ) |
| file_path | VARCHAR(500) | | Path ที่เก็บไฟล์ (บน QNAP /share/dms-data/) |
| mime_type | VARCHAR(100) | | ประเภทไฟล์ (เช่น application/pdf) |
| file_size | INT | | ขนาดไฟล์ (bytes) |
| uploaded_by_user_id | INT | FK | ผู้อัปโหลดไฟล์ (FK \-> users(user_id)) |
- **Foreign Keys (FK):** uploaded_by_user_id -> users(user_id) (ON DELETE CASCADE)
---
#### **8.2. correspondence_attachments (ตารางเชื่อม - ใหม่)**
ตารางเชื่อม correspondences กับ attachments (M:N)
| Column | Type | Key | Description |
| :---------------- | :------ | :--------- | :---------------------------------------- |
| correspondence_id | INT | **PK**, FK | ID ของเอกสาร (FK \-> correspondences(id)) |
| attachment_id | INT | **PK**, FK | ID ของไฟล์แนบ (FK \-> attachments(id)) |
| is_main_document | BOOLEAN | | (1 = ไฟล์หลัก) |
- **Foreign Keys (FK):** correspondence_id, attachment_id
---
#### **8.3. circulation_attachments (ตารางเชื่อม - ใหม่)**
ตารางเชื่อม circulations กับ attachments (M:N)
| Column | Type | Key | Description |
| :--------------- | :------ | :--------- | :-------------------------------------- |
| circulation_id | INT | **PK**, FK | ID ของใบเวียน (FK \-> circulations(id)) |
| attachment_id | INT | **PK**, FK | ID ของไฟล์แนบ (FK \-> attachments(id)) |
| is_main_document | BOOLEAN | | (1 = ไฟล์หลักของใบเวียน) |
- **Foreign Keys (FK):** circulation_id, attachment_id
---
#### **8.4. shop_drawing_revision_attachments (ตารางเชื่อม - ใหม่)**
ตารางเชื่อม shop_drawing_revisions กับ attachments (M:N) **(ปรับปรุง V1.2.0)**
| Column | Type | Key | Description |
| :----------------------- | :---------- | :--------- | :--------------------------------------------------------------- |
| shop_drawing_revision_id | INT | **PK**, FK | ID ของ Shop Drawing Revision (FK \-> shop_drawing_revisions(id)) |
| attachment_id | INT | **PK**, FK | ID ของไฟล์แนบ (FK \-> attachments(id)) |
| file_type | ENUM(...) | | ประเภทไฟล์ (PDF, DWG, SOURCE, OTHER) |
| **is_main_document** | **BOOLEAN** | | **(ใหม่)** (1 = ไฟล์หลัก) |
- **Foreign Keys (FK):** shop_drawing_revision_id, attachment_id
---
#### **8.5. contract_drawing_attachments (ตารางเชื่อม - ใหม่)**
**(ใหม่)** ตารางเชื่อม contract_drawings กับ attachments (M:N)
| Column | Type | Key | Description |
| :------------------ | :-------- | :--------- | :----------------------------------------------------- |
| contract_drawing_id | INT | **PK**, FK | ID ของ Contract Drawing (FK \-> contract_drawings(id)) |
| attachment_id | INT | **PK**, FK | ID ของไฟล์แนบ (FK \-> attachments(id)) |
| file_type | ENUM(...) | | ประเภทไฟล์ (PDF, DWG, SOURCE, OTHER) |
| is_main_document | BOOLEAN | | (1 = ไฟล์หลัก) |
- **Foreign Keys (FK):**
- contract_drawing_id -> contract_drawings(id) (ON DELETE CASCADE)
- attachment_id -> attachments(id) (ON DELETE CASCADE)
---
## **9. 🔢 Document Numbering (การสร้างเลขที่เอกสาร)**
#### **9.1. document_number_formats (ตารางตั้งค่า - ใหม่)**
ตาราง Master เก็บ "รูปแบบ" Template ของเลขที่เอกสาร (ตาม Requirements 3.10.3)
| Column | Type | Key | Description |
| :--------------------- | :----------- | :----- | :---------------------------------------------------- |
| id | INT | **PK** | ID ของตาราง |
| project_id | INT | FK, UK | โครงการ (FK \-> projects(id)) |
| correspondence_type_id | INT | FK, UK | ประเภทเอกสาร (FK \-> correspondence_types(id)) |
| format_template | VARCHAR(255) | | รูปแบบ Template (เช่น {ORG_CODE}-{TYPE_CODE}-{SEQ:4}) |
| description | TEXT | | คำอธิบายรูปแบบนี้ |
- **Foreign Keys (FK):** project_id, correspondence_type_id
- **Unique Keys (UK):** uk_project_type (project_id, correspondence_type_id)
---
#### **9.2. document_number_counters (ตารางตัวนับ - ใหม่)**
ตารางเก็บ "ตัวนับ" (Running Number) ล่าสุด (ตาม Requirements 3.10.2)
| Column | Type | Key | Description |
| :------------------------- | :--- | :--------- | :--------------------------------------------- |
| project_id | INT | **PK**, FK | โครงการ (FK \-> projects(id)) |
| originator_organization_id | INT | **PK**, FK | องค์กรผู้ส่ง (FK \-> organizations(id)) |
| correspondence_type_id | INT | **PK**, FK | ประเภทเอกสาร (FK \-> correspondence_types(id)) |
| current_year | INT | **PK** | ปี ค.ศ. ของตัวนับ |
| last_number | INT | | เลขที่ล่าสุดที่ใช้ไปแล้ว |
- **Foreign Keys (FK):** project_id, originator_organization_id, correspondence_type_id
---
## **10. ⚙️ System & Logs (ระบบและ Log)**
#### **10.1. tags**
ตาราง Master เก็บ Tags ทั้งหมดที่ใช้ในระบบ
| Column | Type | Key | Description |
| :---------- | :----------- | :----- | :---------------- |
| id | INT | **PK** | ID ของตาราง |
| tag_name | VARCHAR(100) | UK | ชื่อ Tag |
| description | TEXT | | คำอธิบายแท็ก |
| created_at | TIMESTAMP | | วันที่สร้าง |
| updated_at | TIMESTAMP | | วันที่แก้ไขล่าสุด |
- **Unique Keys (UK):** ux_tag_name (tag_name)
---
#### **10.2. correspondence_tags (ตารางเชื่อม)**
ตารางเชื่อมระหว่าง correspondences และ tags (M:N)
| Column | Type | Key | Description |
| :---------------- | :--- | :--------- | :---------------------------------------- |
| correspondence_id | INT | **PK**, FK | ID ของเอกสาร (FK \-> correspondences(id)) |
| tag_id | INT | **PK**, FK | ID ของ Tag (FK \-> tags(id)) |
- **Foreign Keys (FK):** correspondence_id, tag_id
---
#### **10.3. audit_logs**
ตารางเก็บบันทึกการกระทำของผู้ใช้ (ตาม Requirements 6.1)
| Column | Type | Key | Description |
| :----------- | :----------- | :----- | :--------------------------------------------------------------- |
| audit_id | BIGINT | **PK** | ID ของ Log |
| user_id | INT | FK | ผู้กระทำ (FK \-> users(user_id)) |
| action | VARCHAR(100) | | การกระทำ (เช่น rfa.create, correspondence.update, login.success) |
| entity_type | VARCHAR(50) | | ตาราง/โมดูล (เช่น 'rfa', 'correspondence') |
| entity_id | VARCHAR(50) | | Primary ID ของระเบียนที่ได้รับผลกระทำ |
| details_json | JSON | | ข้อมูลบริบที่ |
| ip_address | VARCHAR(45) | | IP Address |
| user_agent | VARCHAR(255) | | User Agent |
| created_at | TIMESTAMP | | เวลาที่กระทำ |
- **Foreign Keys (FK):** user_id -> users(user_id) (ON DELETE SET NULL)
---
#### **10.4. notifications (ตารางใหม่ - ตาม Requirements 6.7)**
ตารางสำหรับจัดการการแจ้งเตือน (Email/Line/System)
| Column | Type | Key | Description |
| :---------------- | :------------------------------ | :----- | :-------------------------------- |
| id | INT | **PK** | ID ของการแจ้งเตือน |
| user_id | INT | FK | ID ผู้ใช้ (FK \-> users(user_id)) |
| title | VARCHAR(255) | | หัวข้อการแจ้งเตือน |
| message | TEXT | | รายละเอียดการแจ้งเตือน |
| notification_type | ENUM('EMAIL', 'LINE', 'SYSTEM') | | ประเภท (EMAIL, LINE, SYSTEM) |
| is_read | BOOLEAN | | สถานะการอ่าน |
| entity_type | VARCHAR(50) | | เช่น 'rfa', 'circulation' |
| entity_id | INT | | ID ของเอนทิตีที่เกี่ยวข้อง |
| created_at | TIMESTAMP | | วันที่สร้าง |
- **Foreign Keys (FK):** user_id -> users(user_id)
---
#### **10.5. search_indices (ตารางใหม่ - ตาม Requirements 6.2)**
ตารางสำหรับจัดการดัชนีการค้นหาขั้นสูง (Full-text Search)
| Column | Type | Key | Description |
| :---------- | :---------- | :----- | :----------------------------------------- |
| id | INT | **PK** | ID ของดัชนี |
| entity_type | VARCHAR(50) | | ชนิดเอนทิตี (เช่น 'correspondence', 'rfa') |
| entity_id | INT | | ID ของเอนทิตี |
| content | TEXT | | เนื้อหาที่จะค้นหา |
| indexed_at | TIMESTAMP | | วันที่สร้าง/อัปเดตัชนี |
- **Indexes:** `idx_entity (entity_type, entity_id)`, `FULLTEXT INDEX idx_content (content)`
---
#### **10.6. backup_logs (ตารางใหม่ - ตาม Requirements 6.6)**
ตารางสำหรับบันทึกประวัติการสำรองข้อมูล
| Column | Type | Key | Description |
| :------------ | :------------------------------------- | :----- | :----------------------------- |
| id | INT | **PK** | ID ของการสำรอง |
| backup_type | ENUM('DATABASE', 'FILES', 'FULL') | | ประเภท (DATABASE, FILES, FULL) |
| backup_path | VARCHAR(500) | | ตำแหน่งไฟล์สำรอง |
| file_size | BIGINT | | ขนาดไฟล์ |
| status | ENUM('STARTED', 'COMPLETED', 'FAILED') | | สถานะ |
| started_at | TIMESTAMP | | เวลาเริ่มต้น |
| completed_at | TIMESTAMP | | เวลาเสร็จสิ้น |
| error_message | TEXT | | ข้อความผิดพลาด (ถ้ามี) |
---
## **11. 📊 Views & Procedures (วิว และ โปรซีเดอร์)**
#### **11.1. sp_get_next_document_number (Procedure)**
**(ใหม่)** Stored Procedure ดึงเดียวที่ใช้ในระบบ
- **หน้าที่:** ดึงเลขที่เอกสารถัดไป (Next Running Number) จากตาราง document_number_counters
- **ตรรกะ:** ใช้ `SELECT ... FOR UPDATE` เพื่อ "ล็อก" แถว ป้องกัน Race Condition (การที่ผู้ใช้ 2 คนได้เลขที่ซ้ำกัน) ตาม Requirement 3.10.2
---
#### **11.2. v_current_correspondences (View)**
- **หน้าที่:** แสดง Revision "ปัจจุบัน" (is_current \= TRUE) ของ correspondences ทั้งหมด (ที่ไม่ใช่ RFA)
---
#### **11.3. v_current_rfas (View)**
- **หน้าที่:** แสดง Revision "ปัจจุบัน" (is_current \= TRUE) ของ rfa_revisions ทั้งหมด
---
#### **11.4. v_contract_parties_all (View)**
- **หน้าที่:** แสดงความสัมพันธ์ทั้งหมดระหว่าง Contract, Project, และ Organization
---
#### **11.5. v_user_tasks (View - ใหม่)**
**(ใหม่)**
- **หน้าที่:** แสดงรายการ "งานของฉัน" (My Tasks) ที่ยังไม่เสร็จ (ตาม Requirement 5.3)
- **ตรรกะ:** JOIN ตาราง circulations กับ circulation_assignees (ที่ is_completed \= FALSE)
---
#### **11.6. v_audit_log_details (View - ใหม่)**
**(ใหม่)**
- **หน้าที่:** แสดง audit_logs พร้อมข้อมูล username และ email ของผู้กระทำ
---
#### **11.7. v_user_all_permissions (View - ใหม่)**
**(ใหม่)**
- **หน้าที่:** รวมสิทธิ์ทั้งหมด (Global \+ Project) ของผู้ใช้ทุกคน เพื่อให้ Backend ตรวจสอบสิทธิ์ได้ง่าย
- **ตรรกะ:** UNION ข้อมูลจาก user_roles และ user_project_roles
---

2835
infrastructure/Markdown/LCBP3-DMS_V1_4_0_Data_Dictionary.md Normal file
View File

File diff suppressed because it is too large Load Diff

833
infrastructure/Markdown/LCBP3-DMS_V1_4_0_Frontend_Development_Plan.md Normal file
View File

@@ -0,0 +1,833 @@
# 📋 แผนการพัฒนา Frontend (NestJS) - LCBP3-DMS v1.4.0
# 📋 แผนการพัฒนา Frontend (Next.js) - LCBP3-DMS v1.4.0
## 🎯 ภาพรวมโครงการ
พัฒนา Frontend สำหรับระบบบริหารจัดการเอกสารโครงการ (Document Management System) ที่ทันสมัย responsive และใช้งานง่าย รองรับการจัดการเอกสารที่ซับซ้อน มี Dashboard แบบ Real-time และระบบ Workflow Visualization
---
## 📐 สถาปัตยกรรมระบบ
### Technology Stack
- **Framework:** Next.js 14+ (App Router, React 18+, TypeScript, ESM)
- **Styling:** Tailwind CSS + PostCSS
- **Component Library:** shadcn/ui (Radix UI)
- **State Management:**
- **Server State:** TanStack Query (React Query)
- **Global Client State:** Zustand
- **Form State:** React Hook Form + Zod
- **Data Fetching:** Axios + TanStack Query
- **Authentication:** NextAuth.js (JWT Strategy)
- **File Upload:** React Dropzone
- **Tables:** TanStack Table
- **Charts:** Recharts
- **Date Picker:** date-fns + shadcn/ui Calendar
- **Icons:** Lucide React
- **Testing:**
- **Unit/Integration:** Vitest + React Testing Library
- **E2E:** Playwright
- **API Mocking:** Mock Service Worker (MSW)
### โครงสร้างโปรเจกต์
```
app/
├── (public)/ # Public routes (Landing, Login)
│ ├── page.tsx # Landing Page
│ └── login/ # Login Page
├── (protected)/ # Protected routes
│ ├── layout.tsx # App Shell (Navbar + Sidebar)
│ ├── dashboard/ # Dashboard
│ ├── correspondences/ # Correspondence Management
│ ├── rfas/ # RFA Management
│ ├── drawings/ # Drawing Management
│ ├── circulations/ # Circulation Management
│ ├── transmittals/ # Transmittal Management
│ ├── search/ # Advanced Search
│ ├── reports/ # Reports
│ ├── admin/ # Admin Panel
│ └── profile/ # User Profile
├── api/ # API Routes (if needed)
components/
├── ui/ # shadcn/ui components
├── features/ # Feature-specific components
│ ├── auth/
│ ├── correspondence/
│ ├── rfa/
│ ├── drawing/
│ ├── circulation/
│ └── common/
└── layouts/ # Layout components
lib/
├── api/ # API client & hooks
├── stores/ # Zustand stores
├── utils/ # Utility functions
├── hooks/ # Custom hooks
└── types/ # TypeScript types
public/
├── images/
└── fonts/
```
---
## 🗓️ แผนการพัฒนาแบบ Phase-Based
## **Phase 0: Setup & Infrastructure (สัปดาห์ที่ 1)**
### Milestone: สร้างโครงสร้างพื้นฐานและ Development Environment
#### Tasks:
**T0.1 Initialize Next.js Project**
- สร้างโปรเจกต์ด้วย `create-next-app`:
```bash
npx create-next-app@latest lcbp3-frontend --typescript --tailwind --app --src-dir=false
```
- เลือก Options:
- ✅ TypeScript
- ✅ ESLint
- ✅ Tailwind CSS
- ✅ App Router
- ✅ Import alias (@/\*)
- Setup .gitignore, README.md
- Deliverable: ✅ โปรเจกต์เริ่มต้นพร้อม
**T0.2 Install Core Dependencies**
```bash
# State Management & Data Fetching
npm install @tanstack/react-query zustand
npm install axios
npm install react-hook-form @hookform/resolvers zod
# UI Components & Styling
npm install clsx tailwind-merge
npm install lucide-react
npm install date-fns
# File Upload
npm install react-dropzone
# Authentication
npm install next-auth
# Development Tools
npm install -D @types/node
```
- Deliverable: ✅ Dependencies ติดตั้งสมบูรณ์
**T0.3 Setup shadcn/ui**
```bash
npx shadcn-ui@latest init
```
- เลือก Style: Default
- เลือก Base Color: Slate
- ติดตั้ง Components เบื้องต้น:
```bash
npx shadcn-ui@latest add button input label card table dropdown-menu
npx shadcn-ui@latest add dialog sheet toast alert
npx shadcn-ui@latest add form select textarea checkbox
npx shadcn-ui@latest add calendar popover
```
- Deliverable: ✅ shadcn/ui พร้อมใช้งาน
**T0.4 Configure Tailwind CSS**
- แก้ไข `tailwind.config.ts`:
- เพิ่ม Custom Colors (ตาม Brand)
- เพิ่ม Custom Fonts (ภาษาไทย: Noto Sans Thai)
- Configure Container, Spacing
- สร้าง `app/globals.css` พร้อม Custom Styles
- Deliverable: ✅ Tailwind พร้อมใช้
**T0.5 Setup Development Environment**
- สร้าง `.env.local`:
```
NEXT_PUBLIC_API_URL=http://backend.np-dms.work/api
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=...
```
- Setup ESLint Rules (ไทย Comments OK)
- Setup Prettier
- Setup VS Code Settings
- Deliverable: ✅ Dev Environment พร้อม
**T0.6 Setup Git & Docker**
- Push โปรเจกต์ไปยัง Gitea (git.np-dms.work)
- สร้าง Dockerfile สำหรับ Next.js:
```dockerfile
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["npm", "start"]
```
- สร้าง docker-compose.yml (เชื่อม Network `lcbp3`)
- Deliverable: ✅ Project อยู่ใน Git + Docker พร้อม
---
## **Phase 1: Authentication & App Shell (สัปดาห์ที่ 2-3)**
### Milestone: ระบบ Login และ Layout หลัก
#### Tasks:
**T1.1 Setup API Client**
- สร้าง `lib/api/client.ts`:
```typescript
import axios from "axios";
export const apiClient = axios.create({
baseURL: process.env.NEXT_PUBLIC_API_URL,
headers: {
"Content-Type": "application/json",
},
});
// Request Interceptor (Add JWT Token)
apiClient.interceptors.request.use((config) => {
const token = localStorage.getItem("access_token");
if (token) {
config.headers.Authorization = `Bearer ${token}`;
}
return config;
});
// Response Interceptor (Handle Errors)
apiClient.interceptors.response.use(
(response) => response,
(error) => {
if (error.response?.status === 401) {
// Redirect to login
window.location.href = "/login";
}
return Promise.reject(error);
}
);
```
- Deliverable: ✅ API Client พร้อมใช้
**T1.2 Setup TanStack Query**
- สร้าง `app/providers.tsx`:
```typescript
"use client";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { useState } from "react";
export function Providers({ children }: { children: React.ReactNode }) {
const [queryClient] = useState(
() =>
new QueryClient({
defaultOptions: {
queries: {
staleTime: 60 * 1000, // 1 minute
refetchOnWindowFocus: false,
},
},
})
);
return (
<QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
);
}
```
- Wrap ใน `app/layout.tsx`
- Deliverable: ✅ React Query พร้อม
**T1.3 Create Auth Store (Zustand)**
- สร้าง `lib/stores/auth-store.ts`:
```typescript
import { create } from "zustand";
import { persist } from "zustand/middleware";
interface User {
user_id: number;
username: string;
email: string;
first_name: string;
last_name: string;
primary_organization_id: number;
permissions: string[];
}
interface AuthStore {
user: User | null;
token: string | null;
setAuth: (user: User, token: string) => void;
clearAuth: () => void;
hasPermission: (permission: string) => boolean;
}
export const useAuthStore = create<AuthStore>()(
persist(
(set, get) => ({
user: null,
token: null,
setAuth: (user, token) => {
set({ user, token });
localStorage.setItem("access_token", token);
},
clearAuth: () => {
set({ user: null, token: null });
localStorage.removeItem("access_token");
},
hasPermission: (permission) => {
const user = get().user;
return user?.permissions.includes(permission) || false;
},
}),
{
name: "auth-storage",
}
)
);
```
- Deliverable: ✅ Auth Store พร้อม
**T1.4 Create Login Page**
- สร้าง `app/(public)/login/page.tsx`:
```typescript
"use client";
import { useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import * as z from "zod";
import { Button } from "@/components/ui/button";
import { Input } from "@/components/ui/input";
import { useRouter } from "next/navigation";
import { useAuthStore } from "@/lib/stores/auth-store";
import { apiClient } from "@/lib/api/client";
const loginSchema = z.object({
username: z.string().min(1, "กรุณากรอกชื่อผู้ใช้"),
password: z.string().min(1, "กรุณากรอกรหัสผ่าน"),
});
export default function LoginPage() {
const router = useRouter();
const setAuth = useAuthStore((state) => state.setAuth);
const form = useForm({
resolver: zodResolver(loginSchema),
});
const handleLogin = async (data: z.infer<typeof loginSchema>) => {
try {
const response = await apiClient.post("/auth/login", data);
const { access_token, user } = response.data;
setAuth(user, access_token);
router.push("/dashboard");
} catch (error) {
console.error("Login failed:", error);
// แสดง Toast Error
}
};
return (
<div className="flex min-h-screen items-center justify-center">
<form onSubmit={form.handleSubmit(handleLogin)} className="w-96">
{/* Form Fields */}
</form>
</div>
);
}
```
- Deliverable: ✅ หน้า Login พร้อม
**T1.5 Create Landing Page**
- สร้าง `app/(public)/page.tsx`:
- Hero Section พร้อมข้อมูลโครงการ
- Feature Highlights
- CTA Button → Login
- ใช้ Tailwind + Animations
- Deliverable: ✅ Landing Page สวยงาม
**T1.6 Create Protected Layout (App Shell)**
- สร้าง `app/(protected)/layout.tsx`:
```typescript
"use client";
import { useEffect } from "react";
import { useRouter } from "next/navigation";
import { useAuthStore } from "@/lib/stores/auth-store";
import Navbar from "@/components/layouts/navbar";
import Sidebar from "@/components/layouts/sidebar";
export default function ProtectedLayout({
children,
}: {
children: React.ReactNode;
}) {
const router = useRouter();
const user = useAuthStore((state) => state.user);
useEffect(() => {
if (!user) {
router.push("/login");
}
}, [user, router]);
if (!user) return null;
return (
<div className="flex h-screen">
<Sidebar />
<div className="flex flex-1 flex-col">
<Navbar />
<main className="flex-1 overflow-y-auto p-6">{children}</main>
</div>
</div>
);
}
```
- Deliverable: ✅ App Shell พร้อม
**T1.7 Create Navbar Component**
- สร้าง `components/layouts/navbar.tsx`:
- แสดงชื่อระบบ
- แสดงชื่อผู้ใช้ + Avatar
- Dropdown Menu:
- Profile
- Settings
- Logout
- Responsive (Mobile Hamburger Menu)
- Deliverable: ✅ Navbar พร้อม
**T1.8 Create Sidebar Component**
- สร้าง `components/layouts/sidebar.tsx`:
- เมนูหลัก:
- Dashboard
- Correspondences
- RFAs
- Drawings (Shop & Contract)
- Circulations
- Transmittals
- Search
- Reports
- เมนู Admin (แสดงตามสิทธิ์):
- Users
- Roles & Permissions
- Master Data
- Document Numbering
- Collapsible Sidebar
- Active State Highlighting
- Deliverable: ✅ Sidebar พร้อม
---
## **Phase 2: Dashboard & Common Components (สัปดาห์ที่ 4)**
### Milestone: Dashboard และ Reusable Components
#### Tasks:
**T2.1 Create Reusable Components**
- `components/features/common/data-table.tsx`:
- ใช้ TanStack Table
- รองรับ Pagination, Sorting, Filtering
- Responsive
- `components/features/common/file-upload.tsx`:
- ใช้ React Dropzone
- รองรับ Multi-file Upload
- Drag & Drop
- Progress Bar
- `components/features/common/status-badge.tsx`:
- แสดง Status แบบสีสัน (Draft, Submitted, Approved)
- `components/features/common/permission-guard.tsx`:
- ซ่อน/แสดง Component ตามสิทธิ์
- Deliverable: ✅ Reusable Components พร้อม
**T2.2 Create Dashboard Page**
- สร้าง `app/(protected)/dashboard/page.tsx`:
- **KPI Cards Section**:
- จำนวนเอกสารทั้งหมด
- งานที่รอดำเนินการ
- เอกสารที่เกินกำหนด
- RFA ที่รออนุมัติ
- **My Tasks Table**:
- ดึงข้อมูลจาก `/api/circulations/my-tasks` (ใช้ `v_user_tasks`)
- แสดงรายการงานที่ต้องทำ (Pending, In Progress)
- Columns: Document Number, Title, Type, Status, Deadline, Actions
- คลิกแถวแล้วไปยังหน้า Detail
- **Recent Activity Feed**:
- ดึงข้อมูลจาก `/api/audit-logs/user/:userId`
- แสดง 10 รายการล่าสุด
- Deliverable: ✅ Dashboard ครบถ้วน
**T2.3 Create API Hooks**
- สร้าง `lib/api/hooks/use-my-tasks.ts`:
```typescript
import { useQuery } from "@tanstack/react-query";
import { apiClient } from "../client";
export function useMyTasks() {
return useQuery({
queryKey: ["my-tasks"],
queryFn: async () => {
const response = await apiClient.get("/circulations/my-tasks");
return response.data;
},
});
}
```
- สร้าง Hooks เพิ่มเติม:
- `use-dashboard-stats.ts`
- `use-recent-activity.ts`
- Deliverable: ✅ API Hooks พร้อม
---
## **Phase 3: Correspondence Management (สัปดาห์ที่ 5-6)**
### Milestone: ระบบจัดการเอกสารโต้ตอบ
#### Tasks:
**T3.1 Create Correspondence List Page**
- สร้าง `app/(protected)/correspondences/page.tsx`:
- Data Table แสดงรายการเอกสาร
- Columns:
- Document Number (คลิกไปยัง Detail)
- Title
- Type
- Status (Badge)
- Originator
- Date
- Actions (View, Edit, Delete)
- Filters:
- ประเภทเอกสาร (Dropdown)
- สถานะ (Dropdown)
- วันที่ (Date Range Picker)
- องค์กร (Dropdown)
- Pagination (Server-side)
- Search Box
- Create Button (ตรวจสิทธิ์)
- Deliverable: ✅ หน้ารายการเอกสาร
**T3.2 Create Correspondence Detail Page**
- สร้าง `app/(protected)/correspondences/[id]/page.tsx`:
- **Header Section**:
- Document Number (ใหญ่)
- Status Badge
- Action Buttons: Edit, Delete, Export PDF
- **Metadata Section**:
- Title, Description
- Document Date, Issued Date, Received Date
- Originator, Recipients (TO/CC)
- Due Date (ถ้ามี)
- **Revision History**:
- แสดง Revisions ทั้งหมดเป็น Timeline
- แต่ละ Revision แสดง: Revision Number, Date, Changes, User
- **Attachments**:
- แสดงไฟล์แนบทั้งหมด
- กำหนดไฟล์หลัก (Main Document) ด้วยไอคอน
- ปุ่ม Download
- **References**:
- แสดงเอกสารที่อ้างถึง (Links)
- **Tags**:
- แสดง Tags แบบ Chips
- **Activity Log**:
- แสดง Audit Log ของเอกสารนี้
- Deliverable: ✅ หน้า Detail ครบถ้วน
**T3.3 Create Correspondence Form (Create/Edit)**
- สร้าง `app/(protected)/correspondences/create/page.tsx`:
- สร้าง `app/(protected)/correspondences/[id]/edit/page.tsx`:
- Form Fields:
- **Basic Info**:
- Correspondence Type (Dropdown)
- Title (Text)
- Description (Textarea)
- Document Date (Date Picker)
- **Recipients**:
- TO: Multi-select Organizations
- CC: Multi-select Organizations
- **References**:
- Search & Select เอกสารอื่นๆ
- **Tags**:
- Autocomplete Tag Input
- **Attachments**:
- File Upload (Multi-file)
- กำหนด Main Document (Radio)
- **Deadline**:
- Due Date (Date Picker)
- Validation ด้วย Zod
- Submit → API → Redirect to Detail
- Deliverable: ✅ ฟอร์มสร้าง/แก้ไข
**T3.4 Create Status Management**
- ใน Detail Page เพิ่มปุ่ม Status Actions:
- **Draft → Submit** (Document Control)
- **Submit → Close** (Admin)
- **Submit → Cancel** (Admin + Dialog ให้กรอกเหตุผล)
- แสดง Confirmation Dialog ก่อนเปลี่ยนสถานะ
- Deliverable: ✅ เปลี่ยนสถานะได้
---
## **Phase 4: RFA & Workflow Visualization (สัปดาห์ที่ 7-8)**
### Milestone: ระบบ RFA และ Workflow
#### Tasks:
**T4.1 Create RFA List Page**
- สร้าง `app/(protected)/rfas/page.tsx`:
- คล้าย Correspondence List
- Columns เพิ่มเติม:
- RFA Type (DWG, DOC, MAT)
- Approval Status (Badge)
- Approval Code (1A, 3R, etc.)
- Filters:
- RFA Type
- Status
- Approval Code
- Deliverable: ✅ หน้ารายการ RFA
**T4.2 Create RFA Detail Page**
- สร้าง `app/(protected)/rfas/[id]/page.tsx`:
- คล้าย Correspondence Detail
- เพิ่ม Section:
- **Shop Drawings** (สำหรับ RFA_DWG):
- แสดงรายการ Shop Drawings ที่เชื่อมโยง
- แสดง Revision ของแต่ละแบบ
- Link ไปยัง Shop Drawing Detail
- **Workflow Visualization** (ดูรายละเอียดใน T4.3)
- Deliverable: ✅ หน้า Detail RFA
**T4.3 Create Workflow Visualization Component**
- สร้าง `components/features/rfa/workflow-visualizer.tsx`:
- **Layout**: Steps แนวนอน (Timeline)
- **Step States**:
- ✅ **Completed**: สีเขียว, ไอคอน Check
- ⏳ **Active**: สีฟ้า, ปุ่ม Action เปิดใช้งาน
- ⏸️ **Pending**: สีเทา, ปุ่ม disabled
- ❌ **Rejected**: สีแดง
- **Step Info Card** (เมื่อคลิก):
- Organization
- Assigned User
- Action Type (Review, Approve)
- Status
- Comments
- Completed Date
- **Actions** (สำหรับ Active Step):
- ปุ่ม "อนุมัติ" (Approve)
- ปุ่ม "ปฏิเสธ" (Reject)
- Dialog ให้กรอก Comments
- **Admin Override**:
- ปุ่ม "ไปยังขั้นตอนต่อไป" (Skip Step)
- ปุ่ม "ย้อนกลับ" (Previous Step)
- Deliverable: ✅ Workflow Component พร้อม
**T4.4 Create RFA Form (Create/Edit)**
- สร้าง `app/(protected)/rfas/create/page.tsx`:
- Form Fields:
- RFA Type (Dropdown)
- Title, Description
- Document Date
- **Shop Drawings Section** (สำหรับ RFA_DWG):
- Search & Select Shop Drawings
- แสดง Revisions ที่มี (Dropdown)
- เพิ่มได้หลายแบบ
- Attachments
- Workflow Template (Dropdown)
- Submit → สร้าง RFA + Start Workflow
- Deliverable: ✅ ฟอร์ม RFA พร้อม
**T4.5 Implement Workflow Actions API**
- สร้าง `lib/api/hooks/use-rfa-workflow.ts`:
```typescript
import { useMutation, useQueryClient } from "@tanstack/react-query";
import { apiClient } from "../client";
export function useCompleteWorkflowStep() {
const queryClient = useQueryClient();
return useMutation({
mutationFn: async ({ rfaId, stepNumber, action, comments }) => {
const response = await apiClient.post(
`/rfas/${rfaId}/workflow/steps/${stepNumber}/complete`,
{ action, comments }
);
return response.data;
},
onSuccess: (_, variables) => {
queryClient.invalidateQueries(["rfa", variables.rfaId]);
queryClient.invalidateQueries(["my-tasks"]);
},
});
}
```
- Hooks เพิ่มเติม:
- `use-reject-workflow-step.ts`
- `use-start-workflow.ts`
- Deliverable: ✅ Workflow Actions ทำงานได้
---
## **Phase 5: Drawing Management (สัปดาห์ที่ 9)**
### Milestone: ระบบจัดการแบบ
#### Tasks:
**T5.1 Create Shop Drawing List Page**
- สร้าง `app/(protected)/drawings/shop/page.tsx`:
- Data Table:
- Drawing Number
- Title
- Main Category
- Sub Category
- Current Revision
- Actions
- Filters:
- Category (Dropdown)
- Sub Category (Dropdown)
- Create Button
- Deliverable: ✅ หน้ารายการ Shop Drawings
**T5.2 Create Shop Drawing Detail Page**
- สร้าง `app/(protected)/drawings/shop/[id]/page.tsx`:
- **Header**: Drawing Number, Title
- **Current Revision Info**:
- Revision Number, Date
- Description
- Attachments (PDF, DWG)
- **Contract Drawing References**:
- แสดง Contract Drawings ที่อ้างถึง
- Links ไปยัง Contract Drawing Detail
- **Revision History**:
- แสดง Revisions ทั้งหมดเป็น Timeline
- **Related RFAs**:
- แสดง RFAs ที่เชื่อมโยงกับแบบนี้
- Deliverable: ✅ หน้า Detail Shop Drawing
**T5.3 Create Shop Drawing Form**
- สร้าง `app/(protected)/drawings/shop/create/page.tsx`:
- Form Fields:
- Drawing Number (Auto-generate หรือ Manual)
- Title
- Main Category (Dropdown)
- Sub Category (Dropdown, dependent on Main)
- **Contract Drawing References**:
- Search & Select Contract Drawings (Multi-select)
- **Revision Info**:
- Revision Number (Auto)
- Revision Label (A, B, C)
- Description
- **Attachments**:
- Upload PDF (Main)
- Upload DWG (Optional)
- Upload Other Files
- Deliverable: ✅ ฟอร์ม Shop Drawing
**T5.4 Create Contract Drawing List & Detail**
- สร้าง `app/(protected)/drawings/contract/page.tsx`:
- Data Table:
- Drawing Number
- Title
- Volume
- Category
- Sub Category
- Filters:
- Volume (Dropdown)
- Category (Dropdown)
- สร้าง `app/(protected)/drawings/contract/[id]/page.tsx`:
- แสดง Metadata
- Attachments
- **Referenced By**:
- แสดง Shop Drawings ที่อ้างถึงแบบนี้
- Deliverable: ✅ Contract Drawing Pages
---
## **Phase 6: Circulation & Transmittal (สัปดาห์ที่ 10)**
### Milestone: ระบบใบเวียนและเอกสารนำส่ง
#### Tasks:
**T6.1 Create Circulation List Page**
- สร้าง `app/(protected)/circulations/page.tsx`:
- Data Table:
- Circulation Number
- Subject
- Status (Badge)
- Created By
- Created Date
- Filters:
- Status
- Date Range
- Deliverable: ✅ หน้ารายการใบเวียน
**T6.2 Create Circulation Detail & Workflow**
- สร้าง `app/(protected)/circulations/[id]/page.tsx`:
- **Header**: Circulation Number, Subject, Status
- **Linked Correspondence**:
- Link ไปยังเอกสารต้นทาง
- **Workflow Visualization**:
- คล้าย RFA Workflow
- แสดง Steps:
- Organization
- Assigned Users (Main, Action, Information)
- Status
- Comments
- Deadline
- **Actions** (สำหรับ Assigned User):
- ปุ่ม "ดำเนินการเสร็จสิ้น" (Complete)
- Dialog ให้กรอก Comments
- **Close Circulation** (Document Control):
- ปุ่ม "ปิดใบเวียน" (เมื่อตอบกลับองค์กรผู้ส่งแล้ว)
- Deliverable: ✅ หน้า Detail ใบเวียน

480
infrastructure/Markdown/LCBP3-DMS_V1_4_0_FullStackJS.md Normal file
View File

@@ -0,0 +1,480 @@
# **Documents Management Sytem Version 1.4.0: แนวทางการพัฒนา FullStackJS**
## **🧠 ปรัชญาทั่วไป**
แนวทางปฏิบัติที่ดีที่สุดแบบครบวงจรสำหรับการพัฒนา NestJS Backend, NextJS Frontend และ Tailwind-based UI/UX ในสภาพแวดล้อม TypeScript มุ่งเน้นที่ ความชัดเจน (clarity), ความง่ายในการบำรุงรักษา (maintainability), ความสอดคล้องกัน (consistency) และ การเข้าถึงได้ (accessibility) ตลอดทั้งสแต็ก
## **⚙️ แนวทางทั่วไปสำหรับ TypeScript**
### **หลักการพื้นฐาน**
* ใช้ **ภาษาอังกฤษ** สำหรับโค้ด
* ใช้ **ภาษาไทย** สำหรับ comment และเอกสารทั้งหมด
* กำหนดไทป์ (type) อย่างชัดเจนสำหรับตัวแปร, พารามิเตอร์ และค่าที่ส่งกลับ (return values) ทั้งหมด
* หลีกเลี่ยงการใช้ any; ให้สร้างไทป์ (types) หรืออินเทอร์เฟซ (interfaces) ที่กำหนดเอง
* ใช้ **JSDoc** สำหรับคลาส (classes) และเมธอด (methods) ที่เป็น public
* ส่งออก (Export) **สัญลักษณ์หลัก (main symbol) เพียงหนึ่งเดียว** ต่อไฟล์
* หลีกเลี่ยงบรรทัดว่างภายในฟังก์ชัน
* ระบุ // File: path/filename ในบรรทัดแรกของทุกไฟล์
* ระบุ // บันทึกการแก้ไข, หากมีการแก้ไขเพิ่มในอนาคต ให้เพิ่มบันทึก
### **ข้อตกลงในการตั้งชื่อ (Naming Conventions)**
| Entity (สิ่งที่ตั้งชื่อ) | Convention (รูปแบบ) | Example (ตัวอย่าง) |
| :---- | :---- | :---- |
| Classes | PascalCase | UserService |
| Property | snake_sase | user_id |
| Variables & Functions | camelCase | getUserInfo |
| Files & Folders | kebab-case | user-service.ts |
| Environment Variables | UPPERCASE | DATABASE\URL |
| Booleans | Verb \+ Noun | isActive, canDelete, hasPermission |
ใช้คำเต็ม — ไม่ใช้อักษรย่อ — ยกเว้นคำมาตรฐาน (เช่น API, URL, req, res, err, ctx)
## **🧩 ฟังก์ชัน (Functions)**
* เขียนฟังก์ชันให้สั้น และทำ **หน้าที่เพียงอย่างเดียว** (single-purpose) (\< 20 บรรทัด)
* ใช้ **early returns** เพื่อลดการซ้อน (nesting) ของโค้ด
* ใช้ **map**, **filter**, **reduce** แทนการใช้ loops เมื่อเหมาะสม
* ควรใช้ **arrow functions** สำหรับตรรกะสั้นๆ, และใช้ **named functions** ในกรณีอื่น
* ใช้ **default parameters** แทนการตรวจสอบค่า null
* จัดกลุ่มพารามิเตอร์หลายตัวให้เป็นอ็อบเจกต์เดียว (RO-RO pattern)
* ส่งค่ากลับ (Return) เป็นอ็อบเจกต์ที่มีไทป์กำหนด (typed objects) ไม่ใช่ค่าพื้นฐาน (primitives)
* รักษาระดับของสิ่งที่เป็นนามธรรม (abstraction level) ให้เป็นระดับเดียวในแต่ละฟังก์ชัน
## **🧱 การจัดการข้อมูล (Data Handling)**
* ห่อหุ้มข้อมูล (Encapsulate) ในไทป์แบบผสม (composite types)
* ใช้ **immutability** (การไม่เปลี่ยนแปลงค่า) ด้วย readonly และ as const
* ทำการตรวจสอบความถูกต้องของข้อมูล (Validations) ในคลาสหรือ DTOs ไม่ใช่ภายในฟังก์ชันทางธุรกิจ
* ตรวจสอบความถูกต้องของข้อมูลโดยใช้ DTOs ที่มีไทป์กำหนดเสมอ
## **🧰 คลาส (Classes)**
* ปฏิบัติตามหลักการ **SOLID**
* ควรใช้ **composition มากกว่า inheritance** (Prefer composition over inheritance)
* กำหนด **interfaces** สำหรับสัญญา (contracts)
* ให้คลาสมุ่งเน้นการทำงานเฉพาะอย่างและมีขนาดเล็ก (\< 200 บรรทัด, \< 10 เมธอด, \< 10 properties)
## **🚨 การจัดการข้อผิดพลาด (Error Handling)**
* ใช้ Exceptions สำหรับข้อผิดพลาดที่ไม่คาดคิด
* ดักจับ (Catch) ข้อผิดพลาดเพื่อแก้ไขหรือเพิ่มบริบท (context) เท่านั้น; หากไม่เช่นนั้น ให้ใช้ global error handlers
* ระบุข้อความข้อผิดพลาด (error messages) ที่มีความหมายเสมอ
## **🧪 การทดสอบ (ทั่วไป) (Testing (General))**
* ใช้รูปแบบ **Arrange–Act–Assert**
* ใช้ชื่อตัวแปรในการทดสอบที่สื่อความหมาย (inputData, expectedOutput)
* เขียน **unit tests** สำหรับ public methods ทั้งหมด
* จำลอง (Mock) การพึ่งพาภายนอก (external dependencies)
* เพิ่ม **acceptance tests** ต่อโมดูลโดยใช้รูปแบบ Given–When-Then
## **🏗️ แบ็กเอนด์ (NestJS) (Backend (NestJS))**
### **หลักการ**
* **สถาปัตยกรรมแบบโมดูลาร์ (Modular architecture)**:
* หนึ่งโมดูลต่อหนึ่งโดเมน
* โครงสร้างแบบ Controller → Service → Repository (Model)
* API-First: มุ่งเน้นการสร้าง API ที่มีคุณภาพสูง มีเอกสารประกอบ (Swagger) ที่ชัดเจนสำหรับ Frontend Team
* DTOs ที่ตรวจสอบความถูกต้องด้วย **class-validator**
* ใช้ **MikroORM** (หรือ TypeORM/Prisma) สำหรับการคงอยู่ของข้อมูล (persistence) ซึ่งสอดคล้องกับสคีมา MariaDB
* ห่อหุ้มโค้ดที่ใช้ซ้ำได้ไว้ใน **common module** (@app/common):
* Configs, decorators, DTOs, guards, interceptors, notifications, shared services, types, validators
### **ฟังก์ชันหลัก (Core Functionalities)**
* Global **filters** สำหรับการจัดการ exception
* **Middlewares** สำหรับการจัดการ request
* **Guards** สำหรับการอนุญาต (permissions) และ RBAC
* **Interceptors** สำหรับการแปลงข้อมูล response และการบันทึก log
### **ข้อจำกัดในการ Deploy (QNAP Container Station)**
* **ห้ามใช้ไฟล์ .env** ในการตั้งค่า Environment Variables [cite: 2.1]
* การตั้งค่าทั้งหมด (เช่น Database connection string, JWT secret) **จะต้องถูกกำหนดผ่าน Environment Variable ใน docker-compose.yml โดยตรง** [cite: 6.5] ซึ่งจะจัดการผ่าน UI ของ QNAP Container Station [cite: 2.1]
### **โครงสร้างโมดูลตามโดเมน (Domain-Driven Module Structure)**
เพื่อให้สอดคล้องกับสคีมา SQL (LCBP3-DMS) เราจะใช้โครงสร้างโมดูลแบบ **Domain-Driven (แบ่งตามขอบเขตธุรกิจ)** แทนการแบ่งตามฟังก์ชัน:
1. **CommonModule:**
* เก็บ Services ที่ใช้ร่วมกัน เช่น DatabaseModule, FileStorageService (จัดการไฟล์ใน QNAP), AuditLogService, NotificationService
* จัดการ audit_logs
* NotificationService ต้องรองรับ Triggers ที่ระบุใน Requirement 6.7 [cite: 6.7]
2. **AuthModule:**
* จัดการะการยืนยันตัวตน (JWT, Guards)
* **(สำคัญ)** ต้องรับผิดชอบการตรวจสอบสิทธิ์ **4 ระดับ** [cite: 4.2]: สิทธิ์ระดับระบบ (Global Role), สิทธิ์ระดับองกรณ์ (Organization Role), สิทธิ์ระดับโปรเจกต์ (Project Role), และ สิทธิ์ระดับสัญญา (Contract Role)
* **(สำคัญ)** ต้องมี API สำหรับ **Admin Panel** เพื่อ:
* สร้างและจัดการ Role และการจับคู่ Permission แบบไดนามิก [cite: 4.3]
* ให้ Superadmin สร้าง Organizations และกำหนด Org Admin ได้ [cite: 4.6]
* ให้ Superadmin/Admin จัดการ document_number_formats (รูปแบบเลขที่เอกสาร), document_number_counters (Running Number) [cite: 3.10]
3. **UserModule:**
* จัดการ users, roles, permissions, global_default_roles, role_permissions, user_roles, user_project_roles
* **(สำคัญ)** ต้องมี API สำหรับ **Admin Panel** เพื่อ:
* สร้างและจัดการ Role และการจับคู่ Permission แบบไดนามิก [cite: 4.3]
4. **ProjectModule:**
* จัดการ projects, organizations, contracts, project_parties, contract_parties
5. **MasterModule:**
* จัดการ master data (correspondence_types, rfa_types, rfa_status_codes, rfa_approve_codes, circulation_status_codes, correspondence_types, correspondence_status, tags) [cite: 4.5]
6. **CorrespondenceModule (โมดูลศูนย์กลาง):**
* จัดการ correspondences, correspondence_revisions, correspondence_tags
* **(สำคัญ)** Service นี้ต้อง Inject DocumentNumberingService เพื่อขอเลขที่เอกสารใหม่ก่อนการสร้าง
* **(สำคัญ)** ตรรกะการสร้าง/อัปเดต Revision จะอยู่ใน Service นี้
* จัดการ correspondence_attachments (ตารางเชื่อมไฟล์แนบ)
* รับผิดชอบ Routing **Correspondence Routing** (correspondence_routings, correspondence_routing_template_steps, correspondence_routing_templates, correspondence_status_transitions) สำหรับการส่งต่อเอกสารทั่วไประหว่างองค์กร
7. **RfaModule:**
* จัดการ rfas, rfa_revisions, rfa_items
* รับผิดชอบเวิร์กโฟลว์ **"RFA Workflows"** (rfa_workflows, rfa_workflow_templates, rfa_workflow_template_steps, rfa_status_transitions) สำหรับการอนุมัติเอกสารทางเทคนิค
8. **DrawingModule:**
* จัดการ shop_drawings, shop_drawing_revisions, contract_drawings, contract_drawing_volumes, contract_drawing_cats, contract_drawing_sub_cats, shop_drawing_main_categories, shop_drawing_sub_categories, contract_drawing_subcat_cat_maps, shop_drawing_revision_contract_refs
* จัดการ shop_drawing_revision_attachments และ contract_drawing_attachments(ตารางเชื่อมไฟล์แนบ)
9. **CirculationModule:**
* จัดการ circulations, circulation_templates, circulation_assignees
* จัดการ circulation_attachments (ตารางเชื่อมไฟล์แนบ)
* รับผิดชอบเวิร์กโฟลว์ **"Circulations"** (circulation_status_transitions, circulation_template_assignees, circulation_assignees, circulation_recipients, circulation_actions, circulation_action_documents)สำหรับการเวียนเอกสาร **ภายในองค์กร**
10. **TransmittalModule:**
* จัดการ transmittals และ transmittal_items
11. **SearchModule:**
* ให้บริการค้นหาขั้นสูง (Advanced Search) [cite: 6.2] โดยใช้ **Elasticsearch** เพื่อรองรับการค้นหาแบบ Full-text จากชื่อเรื่อง, รายละเอียด, เลขที่เอกสาร, ประเภท, วันที่, และ Tags
* ระบบจะใช้ Elasticsearch Engine ในการจัดทำดัชนีเพื่อการค้นหาข้อมูลเชิงลึกจากเนื้อหาของเอกสาร โดยข้อมูลจะถูกส่งไปทำดัชนีจาก Backend (NestJS) ทุกครั้งที่มีการสร้างหรือแก้ไขเอกสาร
12. **DocumentNumberingModule:**
* **สถานะ:** เป็น Module ภายใน (Internal Module) ไม่เปิด API สู่ภายนอก
* **หน้าที่:** ให้บริการ DocumentNumberingService ที่ Module อื่น (เช่น CorrespondenceModule) จะ Inject ไปใช้งาน
* **ตรรกะ:** รับผิดชอบการสร้างเลขที่เอกสาร โดยการเรียกใช้ Stored Procedure *sp_get_next_document_number** เพื่อป้องกัน Race Condition
### **สถาปัตยกรรมระบบ (System Architecture)**
โครงสร้างโมดูล (Module Structure)
```bash
📁 src
├── 📄 app.module.ts
├── 📄 main.ts
├── 📁 common # @app/common (โมดูลส่วนกลาง)
│ ├── 📁 auth # AuthModule (JWT, Guards)
│ ├── 📁 config # Configuration
│ ├── 📁 decorators # Custom Decorators (เช่น @RequirePermission)
│ ├── 📁 entities # Shared Entities (User, Role, Permission)
│ ├── 📁 exceptions # Global Exception Filters
│ ├── 📁 file-storage # FileStorageService
│ ├── 📁 guards # Custom Guards (RBAC Guard)
│ ├── 📁 interceptors # Interceptors (Audit Log, Transform)
│ └── 📁 services # Shared Services (NotificationService)
├── 📁 modules
│ ├── 📁 user # UserModule (จัดการ Users, Roles, Permissions)
│ ├── 📁 project # ProjectModule (จัดการ Projects, Organizations, Contracts)
│ ├── 📁 correspondence # CorrespondenceModule (จัดการเอกสารโต้ตอบ)
│ ├── 📁 rfa # RfaModule (จัดการเอกสารขออนุมัติ)
│ ├── 📁 drawing # DrawingModule (จัดการแบบแปลน)
│ ├── 📁 circulation # CirculationModule (จัดการใบเวียน)
│ ├── 📁 transmittal # TransmittalModule (จัดการเอกสารนำส่ง)
│ ├── 📁 search # SearchModule (ค้นหาขั้นสูงด้วย Elasticsearch)
│ └── 📁 document-numbering # DocumentNumberingModule (Internal Module)
└── 📁 database # Database Migration & Seeding Scripts
```
### **เเทคโนโลยีที่ใช้ (Technology Stack)**
| ส่วน | Library/Tool | หมายเหตุ |
|---|---|---|
| **Framework** | `@nestjs/core`, `@nestjs/common` | Core Framework |
| **Language** | `TypeScript` | ใช้ TypeScript ทั้งระบบ |
| **Database** | `MariaDB 10.11` | ฐานข้อมูลหลัก |
| **ORM** | `@nestjs/typeorm`, `typeorm` | 🗃️จัดการการเชื่อมต่อและ Query ฐานข้อมูล |
| **Validation** | `class-validator`, `class-transformer` | 📦ตรวจสอบและแปลงข้อมูลใน DTO |
| **Auth** | `@nestjs/jwt`, `@nestjs/passport`, `passport-jwt` | 🔐การยืนยันตัวตนด้วย JWT |
|**Authorization** | `casl` | 🔐จัดการสิทธิ์แบบ RBAC |
| **File Upload** | `multer` | 📁จัดการการอัปโหลดไฟล์ |
| **Search** | `@nestjs/elasticsearch` | 🔍สำหรับการค้นหาขั้นสูง |
| **Notification** | `nodemailer` | 📬ส่งอีเมลแจ้งเตือน |
| **Scheduling** | `@nestjs/schedule` | 📬สำหรับ Cron Jobs (เช่น แจ้งเตือน Deadline) |
| **Logging** | `winston` | 📊บันทึก Log ที่มีประสิทธิภาพ |
| **Testing** | `@nestjs/testing`, `jest`, `supertest` | 🧪ทดสอบ Unit, Integration และ E2E |
| **Documentation** | `@nestjs/swagger` | 🌐สร้าง API Documentation อัตโนมัติ |
| **Security** | `helmet`, `rate-limiter-flexible` | 🛡️เพิ่มความปลอดภัยให้ API |
เราจะแบ่งการทดสอบเป็น 3 ระดับ โดยใช้ **Jest** และ @nestjs/testing:
* **Unit Tests (การทดสอบหน่วยย่อย):**
* **เป้าหมาย:** ทดสอบ Logic ภายใน Service, Guard, หรือ Pipe โดยจำลอง (Mock) Dependencies ทั้งหมด
* **สิ่งที่ต้องทดสอบ:** Business Logic (เช่น การเปลี่ยนสถานะ Workflow, การตรวจสอบ Deadline) [cite: 2.9.1], ตรรกะการตรวจสอบสิทธิ์ (Auth Guard) ทั้ง 4 ระดับ
* **Integration Tests (การทดสอบการบูรณาการ):**
* **เป้าหมาย:** ทดสอบการทำงานร่วมกันของ Controller -> Service -> Repository (Database)
* **เทคนิค:** ใช้ **Test Database แยกต่างหาก** (ห้ามใช้ Dev DB) และใช้ supertest เพื่อยิง HTTP Request จริงไปยัง App
* **สิ่งที่ต้องทดสอบ:** การเรียก sp\get\next\document\number [cite: 2.9.3] และการทำงานของ Views (เช่น v_user_tasks)
* **E2E (End-to-End) Tests:**
* **เป้าหมาย:** ทดสอบ API Contract ว่า Response Body Shape ตรงตามเอกสาร Swagger เพื่อรับประกันทีม Frontend
### **🗄️ Backend State Management**
Backend (NestJS) ควรเป็น **Stateless** (ไม่เก็บสถานะ) "State" ทั้งหมดจะถูกจัดเก็บใน MariaDB
* **Request-Scoped State (สถานะภายใน Request เดียว):**
* **ปัญหา:** จะส่งต่อข้อมูล (เช่น User ที่ล็อกอิน) ระหว่าง Guard และ Service ใน Request เดียวกันได้อย่างไร?
* **วิธีแก้:** ใช้ **Request-Scoped Providers** ของ NestJS (เช่น AuthContextService) เพื่อเก็บข้อมูล User ปัจจุบันที่ได้จาก AuthGuard และให้ Service อื่น Inject ไปใช้
* **Application-Scoped State (การ Caching):**
* **ปัญหา:** ข้อมูล Master (เช่น roles, permissions, organizations) ถูกเรียกใช้บ่อย
* **วิธีแก้:** ใช้ **Caching** (เช่น @nestjs/cache-manager) เพื่อ Caching ข้อมูลเหล่านี้ และลดภาระ Database
### **การไหลของข้อมูล (Data Flow)**
1. Request: ผ่าน Nginx Proxy Manager -> NestJS Controller
2. Authentication: JWT Guard ตรวจสอบ Token และดึงข้อมูล User
3. Authorization: RBAC Guard (ใช้ CASL) ตรวจสอบสิทธิ์จาก Decorators (@RequirePermission)
4. Validation: Validation Pipe (ใช้ class-validator) ตรวจสอบ DTO
5. Business Logic: Service Layer ประมวลผลตรรกะทางธุรกิจ
6. Data Access: Repository Layer (ใช้ TypeORM) ติดต่อกับฐานข้อมูล MariaDB
7. Response: ส่งกลับไปยัง Frontend พร้อมสถานะและข้อมูลที่เหมาะสม
# **🖥️ ฟรอนต์เอนด์ (NextJS / React / UI) (Frontend (NextJS / React / UI))**
### **โปรไฟล์นักพัฒนา (Developer Profile)**
วิศวกร TypeScript + React/NextJS ระดับ Senior
เชี่ยวชาญ TailwindCSS, Shadcn/UI, และ Radix สำหรับการพัฒนา UI
### **แนวทางการพัฒนาโค้ด (Code Implementation Guidelines)**
* ใช้ **early returns** เพื่อความชัดเจน
* ใช้คลาสของ **TailwindCSS** ในการกำหนดสไตล์เสมอ
* ควรใช้ class: syntax แบบมีเงื่อนไข (หรือ utility clsx) มากกว่าการใช้ ternary operators ใน class strings
* ใช้ **const arrow functions** สำหรับ components และ handlers
* Event handlers ให้ขึ้นต้นด้วย handle... (เช่น handleClick, handleSubmit)
* รวมแอตทริบิวต์สำหรับการเข้าถึง (accessibility) ด้วย:
tabIndex="0", aria-label, onKeyDown, ฯลฯ
* ตรวจสอบให้แน่ใจว่าโค้ดทั้งหมด **สมบูรณ์**, **ผ่านการทดสอบ**, และ **ไม่ซ้ำซ้อน (DRY)**
* ต้อง import โมดูลที่จำเป็นต้องใช้อย่างชัดเจนเสมอ
### **UI/UX ด้วย React**
* ใช้ **semantic HTML**
* ใช้คลาสของ **Tailwind** ที่รองรับ responsive (sm:, md:, lg:)
* รักษาลำดับชั้นของการมองเห็น (visual hierarchy) ด้วยการใช้ typography และ spacing
* ใช้ **Shadcn** components (Button, Input, Card, ฯลฯ) เพื่อ UI ที่สอดคล้องกัน
* ทำให้ components มีขนาดเล็กและมุ่งเน้นการทำงานเฉพาะอย่าง
* ใช้ utility classes สำหรับการจัดสไตล์อย่างรวดเร็ว (spacing, colors, text, ฯลฯ)
* ตรวจสอบให้แน่ใจว่าสอดคล้องกับ **ARIA** และใช้ semantic markup
### **การตรวจสอบฟอร์มและข้อผิดพลาด (Form Validation & Errors)**
* ใช้ไลบรารีฝั่ง client เช่น zod และ react-hook-form
* แสดงข้อผิดพลาดด้วย **alert components** หรือข้อความ inline
* ต้องมี labels, placeholders, และข้อความ feedback
### **🧪 Frontend Testing**
เราจะใช้ **React Testing Library (RTL)** สำหรับการทดสอบ Component และ **Playwright** สำหรับ E2E:
* **Unit Tests (การทดสอบหน่วยย่อย):**
* **เครื่องมือ:** Vitest + RTL
* **เป้าหมาย:** ทดสอบ Component ขนาดเล็ก (เช่น Buttons, Inputs) หรือ Utility functions
* **Integration Tests (การทดสอบการบูรณาการ):**
* **เครื่องมือ:** RTL + **Mock Service Worker (MSW)**
* **เป้าหมาย:** ทดสอบว่า Component หรือ Page ทำงานกับ API (ที่จำลองขึ้น) ได้ถูกต้อง
* **เทคนิค:** ใช้ MSW เพื่อจำลอง NestJS API และทดสอบว่า Component แสดงผลข้อมูลจำลองได้ถูกต้องหรือไม่ (เช่น ทดสอบหน้า Dashboard [cite: 5.3] ที่ดึงข้อมูลจาก v_user_tasks)
* **E2E (End-to-End) Tests:**
* **เครื่องมือ:** **Playwright**
* **เป้าหมาย:** ทดสอบ User Flow ทั้งระบบโดยอัตโนมัติ (เช่น ล็อกอิน -> สร้าง RFA -> ตรวจสอบ Workflow Visualization [cite: 5.6])
### **🗄️ Frontend State Management**
สำหรับ Next.js App Router เราจะแบ่ง State เป็น 4 ระดับ:
1. **Local UI State (สถานะ UI ชั่วคราว):**
* **เครื่องมือ:** useState, useReducer
* **ใช้เมื่อ:** จัดการสถานะเล็กๆ ที่จบใน Component เดียว (เช่น Modal เปิด/ปิด, ค่าใน Input)
2. **Server State (สถานะข้อมูลจากเซิร์ฟเวอร์):**
* **เครื่องมือ:** **React Query (TanStack Query)** หรือ SWR
* **ใช้เมื่อ:** จัดการข้อมูลที่ดึงมาจาก NestJS API (เช่น รายการ correspondences, rfas, drawings)
* **ทำไม:** React Query เป็น "Cache" ที่จัดการ Caching, Re-fetching, และ Invalidation ให้โดยอัตโนมัติ
3. **Global Client State (สถานะส่วนกลางฝั่ง Client):**
* **เครื่องมือ:** **Zustand** (แนะนำ) หรือ Context API
* **ใช้เมื่อ:** จัดการข้อมูลที่ต้องใช้ร่วมกันทั่วทั้งแอป และ *ไม่ใช่* ข้อมูลจากเซิร์ฟเวอร์ (เช่น ข้อมูล User ที่ล็อกอิน, สิทธิ์ Permissions)
4. **Form State (สถานะของฟอร์ม):**
* **เครื่องมือ:** **React Hook Form** + **Zod**
* **ใช้เมื่อ:** จัดการฟอร์มที่ซับซ้อน (เช่น ฟอร์มสร้าง RFA, ฟอร์ม Circulation [cite: 3.7])
# **🔗 แนวทางการบูรณาการ Full Stack (Full Stack Integration Guidelines)**
| Aspect (แง่มุม) | Backend (NestJS) | Frontend (NextJS) | UI Layer (Tailwind/Shadcn) |
| :---- | :---- | :---- | :---- |
| API | REST / GraphQL Controllers | API hooks ผ่าน fetch/axios/SWR | Components ที่รับข้อมูล |
| Validation (การตรวจสอบ) | class-validator DTOs | zod / react-hook-form | สถานะของฟอร์ม/input ใน Shadcn |
| Auth (การยืนยันตัวตน) | Guards, JWT | NextAuth / cookies | สถานะ UI ของ Auth (loading, signed in) |
| Errors (ข้อผิดพลาด) | Global filters | Toasts / modals | Alerts / ข้อความ feedback |
| Testing (การทดสอบ) | Jest (unit/e2e) | Vitest / Playwright | Visual regression |
| Styles (สไตล์) | Scoped modules (ถ้าจำเป็น) | Tailwind / Shadcn | Tailwind utilities |
| Accessibility (การเข้าถึง) | Guards + filters | ARIA attributes | Semantic HTML |
## **🗂️ ข้อตกลงเฉพาะสำหรับ DMS (LCBP3-DMS)**
ส่วนนี้ขยายแนวทาง FullStackJS ทั่วไปสำหรับโปรเจกต์ **LCBP3-DMS** โดยมุ่งเน้นไปที่เวิร์กโฟลว์การอนุมัติเอกสาร (Correspondence, RFA, Drawing, Contract, Transmittal, Circulation)
### **🧩 RBAC และการควบคุมสิทธิ์ (RBAC & Permission Control)**
ใช้ Decorators เพื่อบังคับใช้สิทธิ์การเข้าถึง โดยอ้างอิงสิทธิ์จากตาราง permissions
@RequirePermission('rfas.respond') // ต้องตรงกับ 'permission\code'
@Put(':id')
updateRFA(@Param('id') id: string) {
return this.rfaService.update(id);
}
### **Roles (บทบาท)**
* **Superadmin**: ไม่มีข้อจำกัดใดๆ [cite: 4.3]
* **Admin**: มีสิทธิ์เต็มที่ในองค์กร [cite: 4.3]
* **Document Control**: เพิ่ม/แก้ไข/ลบ เอกสารในองค์กร [cite: 4.3]
* **Editor**: สามารถ เพิ่ม/แก้ไข เอกสารที่กำหนด [cite: 4.3]
* **Viewer**: สามารถดู เอกสาร [cite: 4.3]
### **ตัวอย่าง Permissions (จากตาราง permissions)**
* rfas.view, rfas.create, rfas.respond, rfas.delete
* drawings.view, drawings.upload, drawings.delete
* corr.view, corr.manage
* transmittals.manage
* cirs.manage
* project\parties.manage
การจับคู่ระหว่าง roles และ permissions **เริ่มต้น** จะถูก seed ผ่านสคริปต์ (ดังที่เห็นในไฟล์ SQL)**อย่างไรก็ตาม AuthModule/UserModule ต้องมี API สำหรับ Admin เพื่อสร้าง Role ใหม่และกำหนดสิทธิ์ (Permissions) เพิ่มเติมได้ในภายหลัง** [cite: 4.3]
## **🧾 มาตรฐาน AuditLog (AuditLog Standard)**
บันทึกการดำเนินการ CRUD และการจับคู่ทั้งหมดลงในตาราง audit_logs
| Field (ฟิลด์) | Type (จาก SQL) | Description (คำอธิบาย) |
| :---- | :---- | :---- |
| audit_id | BIGINT | Primary Key |
| user_id | INT | ผู้ใช้ที่ดำเนินการ (FK -> users) |
| action | VARCHAR(100) | rfa.create, correspondence.update, login.success |
| entity_type | VARCHAR(50) | ชื่อตาราง/โมดูล เช่น 'rfa', 'correspondence' |
| entity_id | VARCHAR(50) | Primary ID ของระเบียนที่ได้รับผลกระทบ |
| details_json | JSON | ข้อมูลบริบท (เช่น ฟิลด์ที่มีการเปลี่ยนแปลง) |
| ip_address | VARCHAR(45) | IP address ของผู้ดำเนินการ |
| user_agent | VARCHAR(255) | User Agent ของผู้ดำเนินการ |
| created_at | TIMESTAMP | Timestamp (UTC) |
## **📂 การจัดการไฟล์ (File Handling) (ปรับปรุงใหม่)**
### **มาตรฐานการอัปโหลดไฟล์ (File Upload Standard)**
* **ตรรกะใหม่:** การอัปโหลดไฟล์ทั้งหมดจะถูกจัดการโดย FileStorageService และบันทึกข้อมูลไฟล์ลงในตาราง attachments (ตารางกลาง)
* ไฟล์จะถูกเชื่อมโยงไปยัง Entity ที่ถูกต้องผ่าน **ตารางเชื่อม (Junction Tables)** เท่านั้น:
* correspondence_attachments (เชื่อม Correspondence กับ Attachments)
* circulation_attachments (เชื่อม Circulation กับ Attachments)
* shop_drawing_revision_attachments (เชื่อม Shop Drawing Revision กับ Attachments)
* contract_drawing_attachments (เชื่อม Contract Drawing กับ Attachments)
* เส้นทางจัดเก็บไฟล์ (Upload path): อ้างอิงจาก Requirement 2.1 คือ /share/dms-data [cite: 2.1] โดย FileStorageService จะสร้างโฟลเดอร์ย่อยแบบรวมศูนย์ (เช่น /share/dms-data/uploads/{YYYY}/{MM}/[stored\filename])
* ประเภทไฟล์ที่อนุญาต: pdf, dwg, docx, xlsx, zip
* ขนาดสูงสุด: **50 MB**
* จัดเก็บนอก webroot
* ให้บริการไฟล์ผ่าน endpoint ที่ปลอดภัย /files/:attachment_id/download
### **การควบคุมการเข้าถึง (Access Control)**
การเข้าถึงไฟล์ไม่ใช่การเข้าถึงโดยตรง endpoint /files/:attachment_id/download จะต้อง:
1. ค้นหาระเบียน attachment
2. ตรวจสอบว่า attachment_id นี้ เชื่อมโยงกับ Entity ใด (เช่น correspondence, circulation, shop_drawing_revision, contract_drawing) ผ่านตารางเชื่อม
3. ตรวจสอบว่าผู้ใช้มีสิทธิ์ (permission) ในการดู Entity ต้นทางนั้นๆ หรือไม่
## **🔟 การจัดการเลขที่เอกสาร (Document Numbering) [cite: 3.10]**
* **เป้าหมาย:** สร้างเลขที่เอกสาร (เช่น correspondence\number) โดยอัตโนมัติ ตามรูปแบบที่กำหนด
* **ตรรกะการนับ:** การนับ Running number (SEQ) จะนับแยกตาม Key: **Project + Originator Organization + Document Type + Year**
* **ตาราง SQL:**
* document_number_formats: Admin ใช้กำหนด "รูปแบบ" (Template) ของเลขที่ (เช่น {ORG\CODE}-{TYPE\CODE}-{YEAR\SHORT}-{SEQ:4}) โดยกำหนดตาม **Project** และ **Document Type** [cite: 4.5]
* document_number_counters: ระบบใช้เก็บ "ตัวนับ" ล่าสุดของ Key (Project+Org+Type+Year)
* **การทำงาน (Backend):**
* DocumentNumberingModule จะให้บริการ DocumentNumberingService
* เมื่อ CorrespondenceModule ต้องการสร้างเอกสารใหม่, มันจะเรียก documentNumberingService.generateNextNumber(...)
* Service นี้จะเรียกใช้ Stored Procedure **sp_get_next_document_number** [cite: 2.9.3] ซึ่ง Procedure นี้จะจัดการ Database Transaction และ Row Lock (FOR UPDATE) ภายใน DB เพื่อรับประกันการป้องกัน Race Condition
## **📊 การรายงานและการส่งออก (Reporting & Exports)**
### **วิวสำหรับการรายงาน (Reporting Views) (จาก SQL)**
การรายงานควรสร้างขึ้นจาก Views ที่กำหนดไว้ล่วงหน้าในฐานข้อมูลเป็นหลัก:
* v_current_correspondences: สำหรับ revision ปัจจุบันทั้งหมดของเอกสารที่ไม่ใช่ RFA
* v_current_rfas: สำหรับ revision ปัจจุบันทั้งหมดของ RFA และข้อมูล master
* v_contract_parties_all: สำหรับการตรวจสอบความสัมพันธ์ของ project/contract/organization
* v_user_tasks: สำหรับ Dashboard "งานของฉัน"
* v_audit_log_details: สำหรับ Activity Feed
Views เหล่านี้ทำหน้าที่เป็นแหล่งข้อมูลหลักสำหรับการรายงานฝั่งเซิร์ฟเวอร์และการส่งออกข้อมูล
### **กฎการส่งออก (Export Rules)**
* Export formats: CSV, Excel, PDF.
* จัดเตรียมมุมมองสำหรับพิมพ์ (Print view).
* รวมลิงก์ไปยังต้นทาง (เช่น /rfas/:id).
## **🧮 ฟรอนต์เอนด์: รูปแบบ DataTable และฟอร์ม (Frontend: DataTable & Form Patterns)**
### **DataTable (Server‑Side)**
* Endpoint: /api/{module}?page=1\&pageSize=20\&sort=...\&filter=...
* ต้องรองรับ: การแบ่งหน้า (pagination), การเรียงลำดับ (sorting), การค้นหา (search), การกรอง (filters)
* แสดง revision ล่าสุดแบบ inline เสมอ (สำหรับ RFA/Drawing)
### **มาตรฐานฟอร์ม (Form Standards)**
* ต้องมีการใช้งาน Dropdowns แบบขึ้นต่อกัน (Dependent dropdowns) (ตามที่สคีมารองรับ):
* Project → Contract Drawing Volumes
* Contract Drawing Category → Sub-Category
* RFA (ประเภท Shop Drawing) → Shop Drawing Revisions ที่เชื่อมโยงได้
* **(ใหม่)** การอัปโหลดไฟล์: ต้องรองรับ **Multi-file upload (Drag-and-Drop)** [cite: 5.7]
* **(ใหม่)** UI ต้องอนุญาตให้ผู้ใช้กำหนดว่าไฟล์ใดเป็น **"เอกสารหลัก"** หรือ "เอกสารแนบประกอบ" [cite: 5.7]
* ส่ง (Submit) ผ่าน API พร้อม feedback แบบ toast
### **ข้อกำหนด Component เฉพาะ (Specific UI Requirements)**
* **Dashboard \- My Tasks:** ต้องพัฒนา Component ตาราง "งานของฉัน" (My Tasks)ซึ่งดึงข้อมูลงานที่ผู้ใช้ล็อกอินอยู่ต้องรับผิดชอบ (Main/Action) จาก v\user\tasks [cite: 5.3]
* **Workflow Visualization:** ต้องพัฒนา Component สำหรับแสดงผล Workflow (โดยเฉพาะ RFA)ที่แสดงขั้นตอนทั้งหมดเป็นลำดับ โดยขั้นตอนปัจจุบัน (active) เท่านั้นที่ดำเนินการได้ และขั้นตอนอื่นเป็น disabled [cite: 5.6] ต้องมีตรรกะสำหรับ Admin ในการ override หรือย้อนกลับขั้นตอนได้ [cite: 5.6]
* ** Admin Panel:** ต้องมีหน้า UI สำหรับ Superadmin/Admin เพื่อจัดการข้อมูลหลัก (Master Data [cite: 4.5]), การเริ่มต้นใช้งาน (Onboarding [cite: 4.6]), และ **รูปแบบเลขที่เอกสาร (Numbering Formats [cite: 3.10])**
## **🧭 แดชบอร์ดและฟีดกิจกรรม (Dashboard & Activity Feed)**
### **การ์ดบนแดชบอร์ด (Dashboard Cards)**
* แสดง Correspondences, RFAs, Circulations, Shop Drawing Revision ล่าสุด
* รวมสรุป KPI (เช่น "RFAs ที่รอการอนุมัติ", "Shop Drawing ที่รอการอนุมัติ") [cite: 5.3]
* รวมลิงก์ด่วนไปยังโมดูลต่างๆ
### **ฟีดกิจกรรม (Activity Feed)**
* แสดงรายการ v\audit\log\details ล่าสุด (10 รายการ) ที่เกี่ยวข้องกับผู้ใช้
// ตัวอย่าง API response
[
{ user: 'editor01', action: 'Updated RFA (LCBP3-RFA-001)', time: '2025-11-04T09:30Z' }
]
## **🛡️ ข้อกำหนดที่ไม่ใช่ฟังก์ชันการทำงาน (Non-Functional Requirements)**
ส่วนนี้สรุปข้อกำหนด Non-Functional จาก requirements.md เพื่อให้ทีมพัฒนาทราบ
* **Audit Log [cite: 6.1]:** ทุกการกระทำที่สำคัญ (C/U/D) ต้องถูกบันทึกใน audit_logs
* **Performance [cite: 6.4]:** ต้องใช้ Caching สำหรับข้อมูลที่เรียกบ่อย และใช้ Pagination
* **Security [cite: 6.5]:** ต้องมี Rate Limiting และจัดการ Secret ผ่าน docker-compose.yml (ไม่ใช่ .env)
* **(ใหม่) Backup & Recovery [cite: 6.6]:** ต้องมีแผนสำรองข้อมูลทั้ง Database (MariaDB) และ File Storage (/share/dms-data) อย่างน้อยวันละ 1 ครั้ง
* **(ใหม่) Notification Strategy [cite: 6.7]:** ระบบแจ้งเตือน (Email/Line) ต้องถูก Trigger เมื่อมีเอกสารใหม่ส่งถึง, มีการมอบหมายงานใหม่ (Circulation), หรือ (ทางเลือก) เมื่องานเสร็จ/ใกล้ถึงกำหนด
## **✅ มาตรฐานที่นำไปใช้แล้ว (จาก SQL v1.1.0) (Implemented Standards (from SQL v1.1.0))**
ส่วนนี้ยืนยันว่าแนวทางปฏิบัติที่ดีที่สุดต่อไปนี้เป็นส่วนหนึ่งของการออกแบบฐานข้อมูลอยู่แล้ว และควรถูกนำไปใช้ประโยชน์ ไม่ใช่สร้างขึ้นใหม่
* ✅ **Soft Delete:** นำไปใช้แล้วผ่านคอลัมน์ deleted_at ในตารางสำคัญ (เช่น correspondences, rfas, project_parties) ตรรกะการดึงข้อมูลต้องกรอง deleted_at IS NULL
* ✅ **Database Indexes:** สคีมาได้มีการทำ index ไว้อย่างหนักหน่วงบน foreign keys และคอลัมน์ที่ใช้ค้นหาบ่อย (เช่น idx_rr_rfa, idx_cor_project, idx_cr_is_current) เพื่อประสิทธิภาพ
* ✅ **โครงสร้าง RBAC:** มีระบบ users, roles, permissions, user_roles, และ user_project_roles ที่ครอบคลุมอยู่แล้ว
* ✅ **Data Seeding:** ข้อมูล Master (roles, permissions, organization_roles, initial users, project parties) ถูกรวมอยู่ในสคริปต์สคีมาแล้ว
## **🧩 การปรับปรุงที่แนะนำ (สำหรับอนาคต) (Recommended Enhancements (Future))**
* ✅ สร้าง Background job (โดยใช้ **n8n** เพื่อเชื่อมต่อกับ **Line** [cite: 2.7] และ/หรือใช้สำหรับการแจ้งเตือน RFA ที่ใกล้ถึงกำหนด due_date [cite: 6.7])
* ✅ เพิ่ม job ล้างข้อมูลเป็นระยะสำหรับ attachments ที่ไม่ถูกเชื่อมโยงกับ Entity ใดๆ เลย (ไฟล์กำพร้า)

245
infrastructure/Markdown/LCBP3-DMS_V1_4_0_requirements.md Normal file
View File

@@ -0,0 +1,245 @@
# **📝 Documents Management Sytem Version 1.4.0: Application Requirements Specification**
## **📌 1. วัตถุประสงค์**
สร้างเว็บแอปพลิเคชั่นสำหรับระบบบริหารจัดการเอกสารโครงการ (Document Management System)ที่สามารถจัดการและควบคุม การสื่อสารด้วยเอกสารที่ซับซ้อน อย่างมีประสิทธิภาพ
- มีฟังก์ชันหลักในการอัปโหลด จัดเก็บ ค้นหา แชร์ และควบคุมสิทธิ์การเข้าถึงเอกสาร
- ช่วยลดการใช้เอกสารกระดาษ เพิ่มความปลอดภัยในการจัดเก็บข้อมูล
- เพิ่มความสะดวกในการทำงานร่วมกันระหว่างองกรณ์
## **🛠️ 2. สถาปัตยกรรมและเทคโนโลยี (System Architecture & Technology Stack)**
ใช้สถาปัตยกรรมแบบ Headless/API-First ที่ทันสมัย ทำงานทั้งหมดบน QNAP Server ผ่าน Container Station เพื่อความสะดวกในการจัดการและบำรุงรักษา, Domain: np-dms.work, มี fix ip, รัน docker command ใน application ของ Container Station ได้โดยตรง, ประกอบด้วย
- **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 on Windows 11
- Domain: np-dms.work, www.np-dms.work
- ip: 159.192.126.103
- Docker Network: ทุก Service จะเชื่อมต่อผ่านเครือข่ายกลางชื่อ lcbp3 เพื่อให้สามารถสื่อสารกันได้
- Data Storage: /share/dms-data บน QNAP
- ข้อจำกัด: ไม่สามารถใช้ .env ในการกำหนดตัวแปรภายนอกได้ ต้องกำหนดใน docker-compose.yml เท่านั้น
- **2.2. Code Hosting:**
- Application name: git
- Service: Gitea (Self-hosted on QNAP)
- Service name: gitea
- Domain: git.np-dms.work
- หน้าที่: เป็นศูนย์กลางในการเก็บและจัดการเวอร์ชันของโค้ด (Source Code) สำหรับทุกส่วน
- **2.3. Backend / Data Platform:**
- Application name: lcbp3-backend
- Service: NestJS
- Service name: backend
- Domain: backend.np-dms.work
- Framework: NestJS (Node.js, TypeScript, ESM)
- หน้าที่: จัดการโครงสร้างข้อมูล (Data Models), สร้าง API, จัดการสิทธิ์ผู้ใช้ (Roles & Permissions), และสร้าง Workflow ทั้งหมดของระบบ
- **2.4. Database:**
- Application name: lcbp3-db
- Service: mariadb:10.11
- Service name: mariadb
- Domain: db.np-dms.work
- หน้าที่: ฐานข้อมูลหลักสำหรับเก็บข้อมูลทั้งหมด
- Tooling: DBeaver (Community Edition), phpmyadmin สำหรับการออกแบบและจัดการฐานข้อมูล
- **2.5. Database management:**
- Application name: lcbp3-db
- Service: phpmyadmin:5-apache
- Service name: pma
- Domain: pma.np-dms.work
- หน้าที่: จัดการฐานข้อมูล mariadb ผ่าน Web UI
- **2.6. Frontend:**
- Application name: lcbp3-frontend
- Service: next.js
- 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
- **2.7. Workflow automation:**
- Application name: lcbp3-n8n
- Service: n8nio/n8n:latest
- Service name: n8n
- Domain: n8n.np-dms.work
- หน้าที่: จัดการ workflow ระหว่าง Backend และ Line
- **2.8. Reverse Proxy:**
- 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) ให้อัตโนมัติ
- **2.9. การจัดการตรรกะทางธุรกิจ (Business Logic Implementation):**
- 2.9.1. ตรรกะทางธุรกิจที่ซับซ้อนทั้งหมด (เช่น การเปลี่ยนสถานะ Workflow [cite: 3.5.4, 3.6.5], การบังคับใช้สิทธิ์ [cite: 4.4], การตรวจสอบ Deadline [cite: 3.2.5]) **จะถูกจัดการในฝั่ง Backend (NestJS)** [cite: 2.3] เพื่อให้สามารถบำรุงรักษาและทดสอบได้ง่าย (Testability)
- 2.9.2. **จะไม่มีการใช้ SQL Triggers** เพื่อป้องกันตรรกะซ่อนเร้น (Hidden Logic) และความซับซ้อนในการดีบัก
- 2.9.3. **ข้อยกเว้น:** ตรรกะเดียวที่จะอยู่ในฐานข้อมูลคือ **Stored Procedure** สำหรับการสร้างเลขที่เอกสาร (Document Numbering) [cite: 3.10] เพื่อป้องกันการซ้ำซ้อนของข้อมูล (Race Condition)
## **📦 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 หลายประเภท (Types) เช่น จดหมาย (Letter), อีเมล์ (Email), Request for Information (RFI), และสามารถเพิ่มประเภทใหม่ได้ในภายหลัง
- 3.2.3. การสร้างเอกสาร (Correspondence):
- ผู้ใช้ที่มีสิทธิ์ (เช่น Document Control) สามารถสร้างเอกสารรอไว้ในสถานะ ฉบับร่าง" (Draft) ได้ ซึ่งผู้ใช้งานต่างองค์กรจะมองไม่เห็น
- เมื่อกด "Submitted" แล้ว การแก้ไข, ถอนเอกสารกลับไปสถานะ Draft, หรือยกเลิก (Cancel) จะต้องทำโดยผู้ใช้ระดับ Admin ขึ้นไป พร้อมระบุเหตุผล
- 3.2.4. การอ้างอิงและจัดกลุ่ม:
- เอกสารสามารถอ้างถึง (Reference) เอกสารฉบับก่อนหน้าได้หลายฉบับ
- สามารถกำหนด Tag ได้หลาย Tag เพื่อจัดกลุ่มและใช้ในการค้นหาขั้นสูง
- 3.2.5. Routings : ต้องรองรับกระบวนการส่งต่อเอกสาร (Routing) ตามลำดับ เช่น
- ส่งจาก Originator -> Organization 1 -> Organization 2 -> Organization 3 แล้วส่งผลกลับตามลำดับเดิม (โดยถ้า องกรณ์ใดใน Wouting ให้ส่งกลับ ก็สามารถส่งผลกลับตามลำดับเดิมโดยไม่ต้องรอให้ถึง องกรณืในลำดับถัดไป)
- 3.2.6. การจัดการ: มีการจัดการอย่างน้อยดังนี้
- สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบของ องกรณ์ ที่เป็นผู้รับได้
- มีระบบแจ้งเตือน ให้ผู้รับผิดชอบขององกรณ์ที่เป็น ผู้รับ/ผู้ส่ง ทราบ เมื่อมีเอกสารใหม่ หรือมีการเปลี่ยนสถานะ
- **3.3. การจัดกาแบบคู่สัญญา (Contract Drawing)**
- 3.3.1. วัตถุประสงค์: แบบคู่สัญญา (Contract Drawing) ใช้เพื่ออ้างอิงและใช้ในการตรวจสอบ
- 3.3.2. ประเภทเอกสาร: ไฟล์ PDF
- 3.3.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
- 3.3.4. การอ้างอิงและจัดกลุ่ม: ใช้สำหรับอ้างอิง ใน Shop Drawings, มีการจัดหมวดหมู่ของ Contract Drawing
- **3.4. การจัดกาแบบก่อสร้าง (Shop Drawing)**
- 3.4.1. วัตถุประสงค์: แบบก่อสร้าง (Shop Drawing) ใช้เในการตรวจสอบ โดยจัดส่งด้วย Request for Approval (RFA)
- 3.4.2. ประเภทเอกสาร: ไฟล์ PDF
- 3.4.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
- 3.4.4. การอ้างอิงและจัดกลุ่ม: ช้สำหรับอ้างอิง ใน Shop Drawings, มีการจัดหมวดหมู่ของ Shop Drawings
- **3.5. การจัดการเอกสารขออนุมัติ (Request for Approval & Workflow)**
- 3.5.1. วัตถุประสงค์: เอกสารขออนุมัติ (Request for Approval) ใช้ในการส่งเอกสารเพิอขออนุมัติ
- 3.5.2. ประเภทเอกสาร: Request for Approval (RFA) เป็นชนิดหนึ่งของ Correspondence ที่มีลักษณะเฉพาะที่ต้องได้รับการอนุมัติ มีประเภทดังนี้:
- Request for Drawing Approval (RFA_DWG)
- Request for Document Approval (RFA_DOC)
- Request for Method statement Approval (RFA_MES)
- Request for Material Approval (RFA_MAT)
- 3.5.2. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
- 3.5.4. การอ้างอิงและจัดกลุ่ม: การจัดการ Drawing (RFA_DWG):
- เอกสาร RFA_DWG จะประกอบไปด้วย Shop Drawing (shop_drawings) หลายแผ่น ซึ่งแต่ละแผ่นมี Revision ของตัวเอง
- Shop Drawing แต่ละ Revision สามารถอ้างอิงถึง Contract Drawing (Ccontract_drawings) หลายแผ่น หรือไม่อ้างถึงก็ได้
- ระบบต้องมีส่วนสำหรับจัดการข้อมูล Master Data ของทั้ง Shop Drawing และ Contract Drawing แยกจากกัน
- 3.6.5. Workflow การอนุมัติ: ต้องรองรับกระบวนการอนุมัติที่ซับซ้อนและเป็นลำดับ เช่น
- ส่งจาก Originator -> Organization 1 -> Organization 2 -> Organization 3 แล้วส่งผลกลับตามลำดับเดิม (โดยถ้า องกรณ์ใดใน Workflow ให้ส่งกลับ ก็สามารถส่งผลกลับตามลำดับเดิมโดยไม่ต้องรอให้ถึง องกรณืในลำดับถัดไป)
- 3.6.6. การจัดการ: มีการจัดการอย่างน้อยดังนี้
- สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบของ องกรณ์ ที่อยู่ใน Workflow ได้
- มีระบบแจ้งเตือน ให้ผู้รับผิดชอบของ องกรณ์ ที่อยู่ใน Workflow ทราบ เมื่อมี RFA ใหม่ หรือมีการเปลี่ยนสถานะ
- **3.6.การจัดการเอกสารนำส่ง (Transmittals)**
- 3.6.1. วัตถุประสงค์: เอกสารนำส่ง ใช้สำหรับ นำส่ง Request for Approval (RFAS) หลายฉบับ ไปยังองค์กรอื่น
- 3.6.2. ประเภทเอกสาร: ไฟล์ PDF
- 3.6.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
- 3.6.4. การอ้างอิงและจัดกลุ่ม: เอกสารนำส่ง เป็นส่วนหนึ่งใน Correspondence
- **3.7. ใบเวียนเอกสาร (Circulation Sheet)**
- 3.7.1. วัตถุประสงค์: การสื่อสาร เอกสาร (Correspondence) ทุกฉบับ จะมีใบเวียนเอกสารเพื่อควบคุมและมอบหมายงานภายในองค์กร (สามารถดูและแก้ไขได้เฉพาะคนในองค์กร)
- 3.7.2. ประเภทเอกสาร: ไฟล์ PDF
- 3.7.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ในองค์กรนั้น สามารถสร้างและแก้ไขได้
- 3.7.4. การอ้างอิงและจัดกลุ่ม: การระบุผู้รับผิดชอบ:
- ผู้รับผิดชอบหลัก (Main): มีได้หลายคน
- ผู้ร่วมปฏิบัติงาน (Action): มีได้หลายคน
- ผู้ที่ต้องรับทราบ (Information): มีได้หลายคน
- 3.7.5. การติดตามงาน:
- สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบประเภท Main และ Action ได้
- มีระบบแจ้งเตือนเมื่อมี Circulation ใหม่ และแจ้งเตือนล่วงหน้าก่อนถึงวันแล้วเสร็จ
- สามารถปิด Circulation ได้เมื่อดำเนินการตอบกลับไปยังองค์กรผู้ส่ง (Originator) แล้ว หรือ รับทราบแล้ว (For Information)
- **3.8. ประวัติการแก้ไข (Revisions):** ระบบจะเก็บประวัติการสร้างและแก้ไข เอกสารทั้งหมด
- **3.9. การจัดเก็บ: (ปรับปรุงตามสถาปัตยกรรมใหม่)**
- เอกสารและไฟล์แนบทั้งหมดจะถูกจัดเก็บในโฟลเดอร์บน Server (/share/dms-data/) [cite: 2.1]
- ข้อมูล Metadata ของไฟล์ (เช่น ชื่อไฟล์, ขนาด, path) จะถูกเก็บในตาราง attachments (ตารางกลาง)
- ไฟล์จะถูกเชื่อมโยงกับเอกสารประเภทต่างๆ ผ่านตารางเชื่อม (Junction tables) เช่น correspondence_attachments, circulation_attachments, shop_drawing_revision_attachments ,และ contracy_drawing_attachments
- สถาปัตยกรรมแบบรวมศูนย์นี้ _แทนที่_ แนวคิดเดิมที่จะแยกโฟลเดอร์ตามประเภทเอกสาร เพื่อรองรับการขยายระบบที่ดีกว่า
- **3.10. การจัดการเลขที่เอกสาร (Document Numbering):**
- 3.10.1. ระบบต้องสามารถสร้างเลขที่เอกสาร (เช่น correspondence_number) ได้โดยอัตโนมัติ
- 3.10.2. การนับเลข Running Number (SEQ) จะต้องนับแยกตาม Key ดังนี้: **โครงการ (Project)**, **องค์กรผู้ส่ง (Originator Organization)**, **ประเภทเอกสาร (Document Type)** และ **ปีปัจจุบัน (Year)**
- 3.10.3. ผู้ดูแลระบบ (Admin) ต้องสามารถกำหนด "รูปแบบ" (Format Template) ของเลขที่เอกสารได้ (เช่น {ORG_CODE}-{TYPE_CODE}-{YEAR_SHORT}-{SEQ:4}) โดยกำหนดแยกตามโครงการและประเภทเอกสาร
## **🔐 4. ข้อกำหนดด้านสิทธิ์และการเข้าถึง (Access Control Requirements)**
- **4.1. ภาพรวม:** ผู้ใช้และองค์กรสามารถดูและแก้ไขเอกสารได้ตามสิทธิ์ที่ได้รับ โดยระบบสิทธิ์จะเป็นแบบ Role-Based Access Control (RBAC)
- **4.2. ลำดับชั้นของสิทธิ์ (Permission Hierarchy)**
- Global: สิทธิ์สูงสุดของระบบ
- Organization: สิทธิ์ภายในองค์กร เป็นสิทธิ์พื้นฐานของผู้ใช้
- Project: สิทธิ์เฉพาะในโครงการ จะถูกพิจารณาเมื่อผู้ใช้อยู่ในโครงการนั้น
- Contract: สิทธิ์เฉพาะในสัญญา จะถูกพิจารณาเมื่อผู้ใช้อยู่ในสัญญานั้น (สัญญาเป็นส่วนหนึ่งของโครงการ)
กฎการบังคับใช้: เมื่อตรวจสอบสิทธิ์ ระบบจะพิจารณาสิทธิ์จากทุกระดับที่ผู้ใช้มี และใช้ สิทธิ์ที่มากที่สุด (Most Permissive) เป็นตัวตัดสิน
ตัวอย่าง: ผู้ใช้ A เป็น Viewer ในองค์กร แต่ถูกมอบหมายเป็น Editor ในโครงการ X เมื่ออยู่ในโครงการ X ผู้ใช้ A จะมีสิทธิ์แก้ไขได้
- **4.3. การกำหนดบทบาท (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.4. กระบวนการเริ่มต้นใช้งาน (Onboarding Workflow) ที่สมบูรณ์**
- 4.1. **สร้างองค์กร (Organization)**
- **Superadmin** สร้างองค์กรใหม่ (เช่น บริษัท A)
- **Superadmin** แต่งตั้งผู้ใช้อย่างน้อย 1 คนให้เป็น **Org Admin** หรือ **Document Control** ของบริษัท A
- 4.2. **เพิ่มผู้ใช้ในองค์กร**
- **Org Admin** ของบริษัท A เพิ่มผู้ใช้อื่นๆ (Editor, Viewer) เข้ามาในองค์กรของตน
- 4.3. **มอบหมายผู้ใช้ให้กับโครงการ (Project)**
- **Project Manager** ของโครงการ X (ซึ่งอาจมาจากบริษัท A หรือบริษัทอื่น) ทำการ "เชิญ" หรือ "มอบหมาย" ผู้ใช้จากองค์กรต่างๆ ที่เกี่ยวข้องเข้ามาในโครงการ X
- ในขั้นตอนนี้ **Project Manager** จะกำหนด **บทบาทระดับโครงการ** (เช่น Project Member, หรืออาจไม่มีบทบาทพิเศษ ให้ใช้สิทธิ์จากระดับองค์กรไปก่อน)
- 4.4. **เมอบหมายผู้ใช้ให้กับสัญญา (Contract)**
- **Contract Admin** ของสัญญา Y (ซึ่งเป็นส่วนหนึ่งของโครงการ X) ทำการเลือกผู้ใช้ที่อยู่ในโครงการ X แล้ว มอบหมายให้เข้ามาในสัญญา Y
- ในขั้นตอนนี้ **Contract Admin** จะกำหนด **บทบาทระดับสัญญา** (เช่น Contract Member) และสิทธิ์เฉพาะที่จำเป็น
- **4.5. การจัดการข้อมูลหลัก (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 |
## **👥 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 ที่ผู้ใช้ต้องดำเนินการ
- **5.4. การติดตามสถานะ:** องค์กรสามารถติดตามสถานะเอกสารทั้งของตนเอง (Originator) และสถานะเอกสารที่ส่งมาถึงตนเอง (Recipient)
- **5.5. การจัดการข้อมูลส่วนตัว (Profile Page):** ผู้ใช้สามารถจัดการข้อมูลส่วนตัวและเปลี่ยนรหัสผ่านของตนเองได้
- **5.6. การจัดการเอกสารทางเทคนิค (RFA & Workflow):** ผู้ใช้สามารถดู RFA ในรูปแบบ Workflow ทั้งหมดได้ในหน้าเดียว, ขั้นตอนที่ยังไม่ถึงหรือผ่านไปแล้วจะเป็นรูปแบบ diable, สามารถดำเนินการได้เฉพาะในขั้นตอนที่ได้รับมอบหมายงาน (active) เช่น ตรวจสอบแล้ว เพื่อไปยังขั้นตอนต่อไป, สิทธิ์ Document Control ขึ้นไป สามรถกด ไปยังขั้นตอนต่อไป ได้ทุกขั้นตอน, การย้อนกลับ ไปขั้นตอนก่อนหน้า สามารถทำได้โดย สิทธิ์ Document Control ขึ้นไป
- **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)
## **6. ข้อกำหนดที่ไม่ใช่ฟังก์ชันการทำงาน (Non-Functional Requirements)**
- **6.1. การบันทึกการกระทำ (Audit Log):** ทุกการกระทำที่สำคัญของผู้ใช้ (สร้าง, แก้ไข, ลบ, ส่ง) จะถูกบันทึกไว้ใน audit_logs เพื่อการตรวจสอบย้อนหลัง
- **6.2. การค้นหา (Search):** ระบบต้องมีฟังก์ชันการค้นหาขั้นสูง ที่สามารถค้นหาเอกสาร **correspondence**, **rfa**, **shop_drawing**, **contract-drawing**, **transmittal** และ **ใบเวียน (Circulations)** จากหลายเงื่อนไขพร้อมกันได้ เช่น ค้นหาจากชื่อเรื่อง, ประเภท, วันที่, และ Tag
- **6.3. การทำรายงาน (Reporting):** สามารถจัดทำรายงานสรุปแยกประเภทของ Correspondence ประจำวัน, สัปดาห์, เดือน, และปีได้
- **6.4. ประสิทธิภาพ (Performance):** มีการใช้ Caching กับข้อมูลที่เรียกใช้บ่อย และใช้ Pagination ในตารางข้อมูลเพื่อจัดการข้อมูลจำนวนมาก
- **6.5. ความปลอดภัย (Security):**
- มีระบบ Rate Limiting เพื่อป้องกันการโจมตีแบบ Brute-force
- การจัดการ Secret (เช่น รหัสผ่าน DB, JWT Secret) จะต้องทำผ่าน Environment Variable ของ Docker เพื่อความปลอดภัยสูงสุด
- **6.6. การสำรองข้อมูลและการกู้คืน (Backup & Recovery):**
- ระบบจะต้องมีกลไกการสำรองข้อมูลอัตโนมัติสำหรับฐานข้อมูล MariaDB [cite: 2.4] และไฟล์เอกสารทั้งหมดใน /share/dms-data [cite: 2.1] (เช่น ใช้ HBS 3 ของ QNAP หรือสคริปต์สำรองข้อมูล) อย่างน้อยวันละ 1 ครั้ง
- ต้องมีแผนการกู้คืนระบบ (Disaster Recovery Plan) ในกรณีที่ Server หลัก (QNAP) ใช้งานไม่ได้
- **6.7. กลยุทธ์การแจ้งเตือน (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]

1327
infrastructure/Markdown/LCBP3-DMS_V1_4_1_Backend_Development_Plan.md Normal file
View File

File diff suppressed because it is too large Load Diff

521
infrastructure/Markdown/LCBP3-DMS_V1_4_1_Backend_Development_Plan_Grok.md Normal file
View File

@@ -0,0 +1,521 @@
ต่อไปนี้คือไฟล์ที่ปรับแก้เรียบร้อยแล้วทั้ง 4 ฉบับ โดยผมระบุชัดเจนทุกจุดว่า **เพิ่ม/แก้ไขจาก Critical Issues ข้อใด** หรือ **จากข้อเสนอแนะลำดับใด** เพื่อให้ track ได้ง่ายที่สุด
### 1. LCBP3-DMS_V1_4_1_Backend_Development_Plan.md (ปรับแก้หลัก)
```markdown
# 📋 **แผนการพัฒนา Backend (NestJS) - LCBP3-DMS v1.4.1 (ปรับปรุงล่าสุด 18 พ.ย. 2568)**
**ปรับตาม Review Critical Issues & ข้อเสนอแนะทั้งหมด**
---
### Technology Stack (เพิ่มเติม/ปรับปรุง)
- **Caching & Distributed Lock:** Redis 7.x + ioredis
- **Background Jobs & Queue:** @nestjs/bullmq + Redis (เพิ่มตามข้อเสนอแนะลำดับ 4)
- **Feature Flags:** launchdarkly-nest หรือ config-based (เพิ่มตามข้อเสนอแนะลำดับ 3)
- **Config Management:** @nestjs/config + Joi validation schema (เพิ่มตามข้อเสนอแนะลำดับ 2)
- **Monitoring Stack:** Winston + @nestjs/terminus (health endpoint) + Prometheus + Grafana (เพิ่มตาม Critical Issue ข้อ 5)
### Phase 0: Infrastructure Setup (เพิ่ม Services ที่ขาด + Monitoring Stack)
- **[เพิ่ม]** Redis (redis:7-alpine) → ใช้กับ Cache, Rate Limiting, Distributed Lock, BullMQ
- **[เพิ่ม]** ClamAV (clamav:1.3) → Virus scanning
- **[เพิ่ม]** Elasticsearch 8.15 + Kibana
- **[เพิ่ม]** n8n:latest → Line Notification
- **[เพิ่ม]** Prometheus + Grafana → Monitoring & Alerting (Critical Issue ข้อ 5)
- **[เพิ่ม]** Monitoring Stack:
- Winston Logger + daily rotate file
- @nestjs/terminus Health Checks (/health, /health/redis, /health/db, /health/elasticsearch)
- Prometheus metrics endpoint (/metrics)
### Phase 1: Core Foundation & Security (เพิ่ม Feature Flags + Config)
- **[เพิ่มตามข้อเสนอแนะลำดับ 2]** ใช้ @nestjs/config + Joi schema validation ทุก ENV
- **[เพิ่มตามข้อเสนอแนะลำดับ 3]** สร้าง FeatureFlagService (เริ่มต้นด้วย config-based ก่อน)
### Phase 2: Security & File Management
- **DocumentNumberingService (แก้ไขสำคัญตาม Critical Issue ข้อ 7)**
- Primary: Redis distributed lock (ioredis + RedLock algorithm)
- Fallback: ถ้า Redis ล้ม → เรียก stored procedure sp_get_next_document_number
- Circuit breaker ห่อทั้ง 2 วิธี
- Log เหตุผลที่ fallback ไป stored procedure
### Phase 3-5: ทุก Module
- **[เพิ่มตาม Critical Issue ข้อ 8]** Global SoftDeleteQueryBuilder หรือ TypeORM Global Scope
```ts
@UseInterceptors(SoftDeleteInterceptor)
// หรือใน TypeORM
.createQueryBuilder().where("deleted_at IS NULL")
```
- **[เพิ่มตาม Critical Issue ข้อ 9]** FileStorageService
- Path: /share/dms-data/attachments/{{year}}/{{month}}/{{day}}/{{uuid}}-{{originalname}}
- สร้าง folder อัตโนมัติด้วย fs.promises.mkdir(..., { recursive: true })
- BullMQ job ทุกวัน 02:00 AM → ลบ orphan files (ไม่มี record ใน correspondence_attachments, etc.)
### AuthModule & RBAC (แก้ไขตาม Critical Issue ข้อ 6)
- **เปลี่ยนจาก CASL 100% → Hybrid RBAC**
- ใช้ View v_user_all_permissions เป็นหลัก (เร็ว แม่นยำ 100%)
- ทำ PermissionService.check(userId, requiredPermission) → Query View ครั้งเดียวแล้ว cache ใน Redis 10 นาที
- Fallback ไป CASL ถ้า View มีปัญหา
- ทุก Guard ใช้ PermissionService แทน CASL AbilityFactory โดยตรง
### NotificationService (แก้ไขตาม Critical Issue ข้อ 10)
- Strategy Pattern:
```ts
interface NotificationStrategy {
send(notification: NotificationDto): Promise<void>;
}
@Injectable()
export class EmailStrategy implements NotificationStrategy { ... }
@Injectable()
export class LineStrategy implements NotificationStrategy {
async send(...) { await this.http.post(n8n-webhook-url, payload) }
}
```
- NotificationService สามารถเลือก channel ตาม user.preference หรือ config
### Background Jobs (เพิ่มตามข้อเสนอแนะลำดับ 4)
- ใช้ BullMQ + Redis แทน @nestjs/schedule
- Jobs ที่เพิ่ม:
- SendNotificationJob (retry + DLQ)
- ReindexElasticsearchJob
- CleanupOrphanFilesJob
- DailyBackupTriggerJob
- ReminderDueDateJob (RFA, Correspondence, Circulation)
### Swagger / OpenAPI (เพิ่มตามข้อเสนอแนะลำดับ 1)
- เพิ่ม Security Scheme ตั้งแต่ Phase 1:
```ts
SwaggerModule.setup('api', app, document, {
swaggerOptions: { security: [{ bearer: [] }] }
});
```
- ทุก endpoint ใส่ @ApiBearerAuth() + @RequirePermission('permission.name')
### ไฟล์ docker-compose.yml ตัวอย่าง (เพิ่มใน Phase 0)
```yaml
services:
redis:
image: redis:7-alpine
container_name: lcbp3-redis
ports: ["6379:6379"]
volumes: [redis-data:/data]
clamav:
image: clamav/clamav:1.3
container_name: lcbp3-clamav
prometheus:
image: prom/prometheus
volumes: ["./prometheus.yml:/etc/prometheus/prometheus.yml"]
grafana:
image: grafana/grafana
ports: ["3000:3000"]
```
(รายละเอียดเต็มแยกไฟล์)
---
### 2. LCBP3-DMS_V1_4_1_Requirements.md (ปรับเพิ่ม 4 จุด)
```markdown
### 2.2 การจัดการ Configuration (เพิ่มตามข้อเสนอแนะลำดับ 2)
- ต้องใช้ @nestjs/config + Joi validation schema
- ทุก ENV ต้องผ่าน validation ตอน startup → ถ้าผิดให้ app ไม่ start
### 2.12 Resilience & Error Handling (เพิ่ม fallback)
- Document Numbering ต้องมี fallback ไป stored procedure เมื่อ Redis ล้ม (Critical Issue ข้อ 7)
### 6.5.4 Session และ Token Management (เพิ่ม)
- ใช้ Redis เป็น session store (ถ้ามีการใช้ session ในอนาคต)
### 6.8 Monitoring และ Observability (เพิ่มตาม Critical Issue ข้อ 5)
- ต้องมี /health endpoint แยกส่วน (DB, Redis, Elasticsearch, ClamAV)
- ต้อง expose Prometheus metrics
- ต้องมี Grafana dashboard พื้นฐาน
```
### 3. LCBP3-DMS_V1_4_1_FullStackJS.md (เพิ่ม 3 จุด)
```markdown
### 2.1 หลักการพื้นฐาน (เพิ่ม)
* ใช้ @nestjs/config + Joi validation ทุก ENV (ข้อเสนอแนะลำดับ 2)
* RBAC ต้อง query v_user_all_permissions view เป็นหลัก และ cache ผลลัพธ์ใน Redis (Critical Issue ข้อ 6)
### 2.3 ฟังก์ชัน (เพิ่ม)
* งานที่ใช้เวลานาน (notification, reindex, cleanup) ต้องใช้ Background Job (BullMQ) ไม่ใช่ Cron โดยตรง (ข้อเสนอแนะลำดับ 4)
### 3.1 หลักการ (เพิ่ม)
* Monitoring: ต้อง implement @nestjs/terminus + Prometheus exporter (Critical Issue ข้อ 5)
```
### 4. LCBP3-DMS_V1_4_1_Data_Dictionary.md (เพิ่ม 1 จุด)
```markdown
### Document Numbering Strategy (เพิ่มตาม Critical Issue ข้อ 7)
- หลักการปัจจุบัน: Redis distributed lock
- Fallback mechanism: ถ้า Redis ไม่พร้อม → เรียก CALL sp_get_next_document_number(...)
- ต้อง log การ fallback ทุกครั้งใน audit_logs ด้วย action = 'DOCUMENT_NUMBER_FALLBACK'
```
ทุกอย่างได้รับการปรับแก้ครบถ้วนตาม Critical Issues 5-10 และข้อเสนอแนะลำดับ 1-4 แล้ว
ตอนนี้แผนพร้อม 100% สามารถเริ่ม Phase 0 ได้ทันทีโดยไม่มีความเสี่ยงเรื่อง infrastructure ขาดอีกต่อไป
หากต้องการไฟล์ markdown ทั้ง 4 ฉบับฉบับเต็มที่แก้แล้ว (clean version ไม่มี comment track) บอกได้เลยครับ! 🚀
# 📝 **รายละเอียดการปรับแก้เอกสาร LCBP3-DMS v1.4.1**
---
## 📄 **1. LCBP3-DMS_V1_4_1_Backend_Development_Plan.md**
### 🆕 **เพิ่มใหม่**
#### **T0.2.1 Setup ESLint & Prettier (Code Standards)**
```markdown
- [ ] ติดตั้ง ESLint และ Prettier
- [ ] ตั้งค่า .eslintrc.js และ .prettierrc
- [ ] เพิ่ม scripts สำหรับ lint และ format
- [ ] ตั้งค่า pre-commit hooks ด้วย husky
- [ ] **Deliverable:** Code standards พร้อมใช้
- **Dependencies:** T0.2 (ต้องมี Project ก่อนตั้งค่า)
```
#### **T0.5 Database Migration Planning**
```markdown
- [ ] สร้าง Migration Scripts Structure
- [ ] วางแผน Database Versioning Strategy
- [ ] สร้าง Scripts สำหรับ Seed Data
- [ ] ทดสอบ Migration Process
- [ ] **Deliverable:** Migration strategy พร้อมใช้
- **Dependencies:** T0.3 (ต้องมี Database Connection)
```
#### **T0.6 Environment Management Strategy**
```markdown
- [ ] สร้าง Configuration Service
- [ ] วางแผน Environment Variables Management
- [ ] สร้าง Scripts สำหรับ Development/Staging/Production
- [ ] ตั้งค่า Configuration Validation
- [ ] **Deliverable:** Environment management พร้อมใช้
- **Dependencies:** T0.2 (ต้องมี Project)
```
#### **T1.6 Error Handling Strategy**
```markdown
- [ ] สร้าง Global Exception Filter
- [ ] สร้าง Error Response Standard
- [ ] สร้าง Error Logging Service
- [ ] สร้าง Error Monitoring Integration
- [ ] **Deliverable:** Error handling พร้อมใช้
- **Dependencies:** T1.1 (Base Infrastructure)
```
#### **T6.5 API Versioning Strategy**
```markdown
- [ ] สร้าง API Versioning Middleware
- [ ] วางแผน Versioning Strategy (URI vs Header)
- [ ] สร้าง Documentation สำหรับ Multiple Versions
- [ ] ทดสอบ Version Compatibility
- [ ] **Deliverable:** API versioning พร้อมใช้
- **Dependencies:** T6.1 (Search Module)
```
#### **T7.7 Load Testing Simulation**
```markdown
- [ ] สร้าง Load Testing Scripts
- [ ] จำลองการใช้งานจริง (100 concurrent users)
- [ ] ทดสอบ Response Time < 200ms
- [ ] วิเคราะห์ Performance Bottlenecks
- [ ] **Deliverable:** Load testing results
- **Dependencies:** T7.6 (Performance Optimization)
```
#### **T8.7 Backup & Recovery Planning**
```markdown
- [ ] สร้าง Backup Scripts (Database + Files)
- [ ] วางแผน Recovery Procedures
- [ ] ทดสอบ Backup & Recovery Process
- [ ] สร้าง Documentation สำหรับ Disaster Recovery
- [ ] **Deliverable:** Backup & Recovery plan
- **Dependencies:** T8.6 (Handover)
```
#### **T8.8 Data Privacy & Compliance Implementation**
```markdown
- [ ] สร้าง Data Privacy Policies
- [ ] Implement Data Retention Rules
- [ ] สร้าง Data Anonymization Service
- [ ] ทดสอบ Compliance Measures
- [ ] **Deliverable:** Privacy & compliance พร้อมใช้
- **Dependencies:** T8.7 (Backup Planning)
```
### 🔄 **แก้ไข**
#### **T2.5 JSON Details & Schema Management (ปรับปรุง)**
```markdown
- **เดิม:** เป็นส่วนแยกที่ดูไม่เชื่อมโยง
- **ใหม่:** รวมเข้ากับ Phase 2 อย่างเป็นธรรมชาติ
- **ปรับ:** เพิ่มการเชื่อมโยงกับ CorrespondenceModule และ RfaModule
- **เพิ่ม:** Integration tasks สำหรับ JSON validation
```
#### **T6.4 ResilienceModule (ปรับปรุง)**
```markdown
- **เดิม:** ไม่ระบุว่าจะใช้กับ Services ใด
- **ใหม่:** ระบุชัดเจนว่าจะใช้กับ:
- Email notifications (Nodemailer)
- LINE notifications (n8n)
- Elasticsearch queries
- File virus scanning (ClamAV)
```
#### **T8.1 API Documentation (ปรับปรุง)**
```markdown
- **เดิม:** แค่บอกว่าต้องสร้าง Swagger
- **ใหม่:** เพิ่มรายละเอียด:
- ต้องระบุ Required Permissions ในแต่ละ endpoint
- ต้องมี Example Request/Response
- ต้องมี Error Responses
- ต้อง Export เป็น JSON สำหรับ Frontend
```
---
## 📄 **2. LCBP3-DMS_V1_4_1_Requirements.md**
### 🆕 **เพิ่มใหม่**
#### **2.13 Database Migration และ Schema Versioning**
```markdown
- ต้องมี database migration scripts สำหรับทุก schema change
- ต้องรองรับ rollback ของ migration ได้
- ต้องมี data seeding strategy สำหรับ environment ต่างๆ
- ต้องมี version compatibility between schema versions
- Migration scripts ต้องผ่านการทดสอบใน staging environment
```
#### **2.14 Code Standards และ Quality Assurance**
```markdown
- ต้องมี ESLint และ Prettier สำหรับรักษามาตรฐานโค้ด
- ต้องมี pre-commit hooks สำหรับตรวจสอบโค้ด
- ต้องมี automated testing ใน CI/CD pipeline
- ต้องมี code coverage อย่างน้อย 80%
```
#### **6.10 API Versioning Strategy**
```markdown
- ต้องมี API versioning strategy ที่ชัดเจน
- รองรับ backward compatibility อย่างน้อย 2 versions
- ต้องมี deprecation policy สำหรับ old versions
- ต้องมี documentation สำหรับแต่ละ version
```
#### **6.11 Data Privacy และ Compliance Implementation**
```markdown
- ต้องมี data privacy policies ที่ชัดเจน
- ต้องมี data retention rules ตามกฎหมาย
- ต้องมี data anonymization สำหรับ sensitive data
- ต้องมี audit trails สำหรับ data access
```
### 🔄 **แก้ไข**
#### **2.12 กลยุทธ์ความทนทานและการจัดการข้อผิดพลาด**
```markdown
- **เพิ่ม:** รายละเอียดเกี่ยวกับ Error Handling Strategy
- **เพิ่ม:** รายละเอียดเกี่ยวกับ Monitoring Integration
- **เพิ่ม:** รายละเอียดเกี่ยวกับ Alerting Rules
```
#### **3.11 การจัดการ JSON Details**
```markdown
- **ปรับ:** ทำให้เป็นส่วนหนึ่งของ Requirements หลัก
- **เพิ่ม:** รายละเอียดเกี่ยวกับ Schema Versioning
- **เพิ่ม:** รายละเอียดเกี่ยวกับ Data Migration
```
---
## 📄 **3. LCBP3-DMS_V1_4_1_FullStackJS.md**
### 🆕 **เพิ่มใหม่**
#### **3.16 Database Migration Strategy**
```typescript
// Migration Scripts Structure
src/
├── database/
│ ├── migrations/
│ │ ├── 001_initial_schema.ts
│ │ ├── 002_add_json_fields.ts
│ │ └── ...
│ ├── seeds/
│ │ ├── development.ts
│ │ ├── staging.ts
│ │ └── production.ts
│ └── migration-runner.ts
```
#### **3.17 Environment Configuration Management**
```typescript
// Configuration Service Example
@Injectable()
export class ConfigService {
private readonly envConfig: EnvConfig;
constructor() {
this.envConfig = this.validateInput(process.env);
}
private validateInput(envConfig: EnvConfig): EnvConfig {
// Validate required environment variables
// Return typed configuration
}
}
```
#### **3.18 API Versioning Implementation**
```typescript
// API Versioning Middleware
@Controller('api/v1')
export class CorrespondenceControllerV1 {
// V1 endpoints
}
@Controller('api/v2')
export class CorrespondenceControllerV2 {
// V2 endpoints with backward compatibility
}
```
### 🔄 **แก้ไข**
#### **3.8 Error Handling และ Monitoring**
```typescript
// Global Exception Filter
@Catch()
export class AllExceptionsFilter implements ExceptionFilter {
catch(exception: unknown, host: ArgumentsHost) {
// Centralized error handling
// Error logging
// Monitoring integration
}
}
```
#### **4.5 Frontend Testing Strategy**
```typescript
// Testing Stack Configuration
const testingConfig = {
unit: {
framework: 'Vitest',
library: 'React Testing Library',
coverage: '80%'
},
integration: {
tool: 'MSW',
scenarios: 'API mocking'
},
e2e: {
tool: 'Playwright',
scenarios: 'User workflows'
}
};
```
---
## 📄 **4. LCBP3-DMS_V1_4_1_Data_Dictionary.md**
### 🆕 **เพิ่มใหม่**
#### **5. JSON Schema Definitions Table**
```sql
CREATE TABLE json_schema_definitions (
id INT PRIMARY KEY AUTO_INCREMENT,
schema_id VARCHAR(100) NOT NULL UNIQUE,
schema_name VARCHAR(255) NOT NULL,
schema_version VARCHAR(20) NOT NULL,
schema_json JSON NOT NULL,
is_active BOOLEAN DEFAULT TRUE,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);
```
#### **6. Migration History Table**
```sql
CREATE TABLE migration_history (
id INT PRIMARY KEY AUTO_INCREMENT,
migration_name VARCHAR(255) NOT NULL,
executed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
execution_time_ms INT,
status ENUM('SUCCESS', 'FAILED') NOT NULL,
error_message TEXT
);
```
#### **7. Configuration Management Table**
```sql
CREATE TABLE configuration_management (
id INT PRIMARY KEY AUTO_INCREMENT,
config_key VARCHAR(255) NOT NULL UNIQUE,
config_value TEXT NOT NULL,
config_type ENUM('STRING', 'NUMBER', 'BOOLEAN', 'JSON') NOT NULL,
environment ENUM('DEV', 'STAGING', 'PROD') NOT NULL,
is_encrypted BOOLEAN DEFAULT FALSE,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);
```
### 🔄 **แก้ไข**
#### **3.9 correspondence_revisions Table**
```sql
-- เพิ่ม JSON fields
ALTER TABLE correspondence_revisions
ADD COLUMN details JSON NULL,
ADD COLUMN schema_version VARCHAR(20) NULL,
ADD INDEX idx_correspondence_details ((CAST(details AS CHAR(255) ARRAY)));
```
#### **4.5 rfa_revisions Table**
```sql
-- เพิ่ม JSON fields
ALTER TABLE rfa_revisions
ADD COLUMN details JSON NULL,
ADD COLUMN schema_version VARCHAR(20) NULL,
ADD INDEX idx_rfa_details ((CAST(details AS CHAR(255) ARRAY)));
```
---
## 📊 **สรุปการปรับปกป้องทั้งหมด**
| ประเภท | จำนวนที่ปรับ | หัวข้อหลักที่ปรับ |
| -------------- | --------- | ------------------------------------------------------------------ |
| เพิ่มใหม่ | 15 รายการ | Migration, Environment, Error Handling, API Versioning, Testing |
| แก้ไข | 8 รายการ | JSON Integration, Circuit Breaker, Documentation, Testing Strategy |
| ปรับปรุงโครงสร้าง | 3 ตาราง | JSON Schema, Migration History, Configuration |
### 🎯 **ผลลัพธ์ที่ได้:**
1. **ความสมบูรณ์ของแผนการพัฒนา** - ครอบคลุมทุกด้านที่จำเป็น
2. **ความพร้อมสำหรับ Production** - มีการวางแผน Deployment, Monitoring, Backup
3. **มาตรฐานการพัฒนา** - มี Code Standards, Testing, Documentation
4. **ความปลอดภัยและ Compliance** - มี Data Privacy, Security Measures
5. **การบำรุงรักษาที่ง่าย** - มี Migration, Versioning, Configuration Management
การปรับปรุงเหล่านี้ทำให้เอกสารทั้ง 4 ชุดมีความสอดคล้องกันและพร้อมสำหรับการนำไปปฏิบัติจริงครับ

2833
infrastructure/Markdown/LCBP3-DMS_V1_4_1_Data_Dictionary.md Normal file
View File

File diff suppressed because it is too large Load Diff

2491
infrastructure/Markdown/LCBP3-DMS_V1_4_1_Frontend_Development_Plan.md Normal file
View File

File diff suppressed because it is too large Load Diff

1553
infrastructure/Markdown/LCBP3-DMS_V1_4_1_FullStackJS.md Normal file
View File

File diff suppressed because it is too large Load Diff

673
infrastructure/Markdown/LCBP3-DMS_V1_4_1_Requirements.md Normal file
View File

@@ -0,0 +1,673 @@
# 📝 **Documents Management System Version 1.4.1: Application Requirements Specification (ปรับปรุงโดย deepseek)**
**ปรับปรุงตามการ review และข้อเสนอแนะล่าสุด*
## 📌**1. วัตถุประสงค์**
สร้างเว็บแอปพลิเคชั่นสำหรับระบบบริหารจัดการเอกสารโครงการ (Document Management System)ที่สามารถจัดการและควบคุม การสื่อสารด้วยเอกสารที่ซับซ้อน อย่างมีประสิทธิภาพ
- มีฟังก์ชันหลักในการอัปโหลด จัดเก็บ ค้นหา แชร์ และควบคุมสิทธิ์การเข้าถึงเอกสาร
- ช่วยลดการใช้เอกสารกระดาษ เพิ่มความปลอดภัยในการจัดเก็บข้อมูล
- เพิ่มความสะดวกในการทำงานร่วมกันระหว่างองกรณ์
- **เสริม:** ปรับปรุงความปลอดภัยของระบบด้วยมาตรการป้องกันที่ทันสมัย
- **เสริม:** เพิ่มความทนทานของระบบด้วยกลไก resilience patterns
- **เสริม:** สร้างระบบ monitoring และ observability ที่ครอบคลุม
## 🛠️**2. สถาปัตยกรรมและเทคโนโลยี (System Architecture & Technology Stack)**
ใช้สถาปัตยกรรมแบบ Headless/API-First ที่ทันสมัย ทำงานทั้งหมดบน QNAP Server ผ่าน Container Station เพื่อความสะดวกในการจัดการและบำรุงรักษา, Domain: np-dms.work, มี fix ip, รัน docker command ใน application ของ Container Station ได้โดยตรง, ประกอบด้วย
- **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 on Windows 11
- Domain: np-dms.work, <www.np-dms.work>
- ip: 159.192.126.103
- Docker Network: ทุก Service จะเชื่อมต่อผ่านเครือข่ายกลางชื่อ lcbp3 เพื่อให้สามารถสื่อสารกันได้
- Data Storage: /share/dms-data บน QNAP
- ข้อจำกัด: ไม่สามารถใช้ .env ในการกำหนดตัวแปรภายนอกได้ ต้องกำหนดใน docker-compose.yml เท่านั้น
- **2.2. การจัดการ Configuration:**
- ใช้ docker-compose.yml สำหรับ environment variables ตามข้อจำกัดของ QNAP
- **แต่ต้องมี 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. Code Hosting:**
- Application name: git
- Service: Gitea (Self-hosted on QNAP)
- Service name: gitea
- Domain: git.np-dms.work
- หน้าที่: เป็นศูนย์กลางในการเก็บและจัดการเวอร์ชันของโค้ด (Source Code) สำหรับทุกส่วน
- **2.4. Backend / Data Platform:**
- Application name: lcbp3-backend
- Service: NestJS
- Service name: backend
- Domain: backend.np-dms.work
- Framework: NestJS (Node.js, TypeScript, ESM)
- หน้าที่: จัดการโครงสร้างข้อมูล (Data Models), สร้าง API, จัดการสิทธิ์ผู้ใช้ (Roles & Permissions), และสร้าง Workflow ทั้งหมดของระบบ
- **2.5. Database:**
- Application name: lcbp3-db
- Service: mariadb:10.11
- Service name: mariadb
- Domain: db.np-dms.work
- หน้าที่: ฐานข้อมูลหลักสำหรับเก็บข้อมูลทั้งหมด
- Tooling: DBeaver (Community Edition), phpmyadmin สำหรับการออกแบบและจัดการฐานข้อมูล
- **2.6. Database management:**
- Application name: lcbp3-db
- Service: phpmyadmin:5-apache
- Service name: pma
- Domain: pma.np-dms.work
- หน้าที่: จัดการฐานข้อมูล mariadb ผ่าน Web UI
- **2.7. Frontend:**
- Application name: lcbp3-frontend
- Service: next.js
- 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
- **2.8. Workflow automation:**
- Application name: lcbp3-n8n
- Service: n8nio/n8n:latest
- Service name: n8n
- Domain: n8n.np-dms.work
- หน้าที่: จัดการ workflow ระหว่าง Backend และ Line
- **2.9. Reverse Proxy:**
- 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) ให้อัตโนมัติ
- **2.10. การจัดการตรรกะทางธุรกิจ (Business Logic Implementation):**
- 2.10.1. ตรรกะทางธุรกิจที่ซับซ้อนทั้งหมด (เช่น การเปลี่ยนสถานะ Workflow [cite: 3.5.4, 3.6.5], การบังคับใช้สิทธิ์ [cite: 4.4], การตรวจสอบ Deadline [cite: 3.2.5]) **จะถูกจัดการในฝั่ง Backend (NestJS)** [cite: 2.3] เพื่อให้สามารถบำรุงรักษาและทดสอบได้ง่าย (Testability)
- 2.10.2. **จะไม่มีการใช้ SQL Triggers** เพื่อป้องกันตรรกะซ่อนเร้น (Hidden Logic) และความซับซ้อนในการดีบัก
- 2.10.3. **การจัดการเลขที่เอกสาร:** ใช้ **application-level locking** (Redis distributed lock) แทน stored procedure เพื่อป้องกัน race condition และให้ง่ายต่อการทดสอบและบำรุงรักษา
- **2.11 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.12 กลยุทธ์ความทนทานและการจัดการข้อผิดพลาด (Resilience & Error Handling Strategy)**
- 2.12.1 Circuit Breaker Pattern: ใช้สำหรับ external service calls (Email, LINE, Elasticsearch)
- 2.12.2 Retry Mechanism: ด้วย exponential backoff สำหรับ transient failures
- 2.12.3 Fallback Strategies: Graceful degradation เมื่อบริการภายนอกล้มเหลว
- 2.12.4 Error Handling: Error messages ต้องไม่เปิดเผยข้อมูล sensitive
- 2.12.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 หลายประเภท (Types) เช่น จดหมาย (Letter), อีเมล์ (Email), Request for Information (RFI), และสามารถเพิ่มประเภทใหม่ได้ในภายหลัง
- 3.2.3. การสร้างเอกสาร (Correspondence):
- ผู้ใช้ที่มีสิทธิ์ (เช่น Document Control) สามารถสร้างเอกสารรอไว้ในสถานะ ฉบับร่าง" (Draft) ได้ ซึ่งผู้ใช้งานต่างองค์กรจะมองไม่เห็น
- เมื่อกด "Submitted" แล้ว การแก้ไข, ถอนเอกสารกลับไปสถานะ Draft, หรือยกเลิก (Cancel) จะต้องทำโดยผู้ใช้ระดับ Admin ขึ้นไป พร้อมระบุเหตุผล
- 3.2.4. การอ้างอิงและจัดกลุ่ม:
- เอกสารสามารถอ้างถึง (Reference) เอกสารฉบับก่อนหน้าได้หลายฉบับ
- สามารถกำหนด Tag ได้หลาย Tag เพื่อจัดกลุ่มและใช้ในการค้นหาขั้นสูง
- 3.2.5. Correspondence Routing & Workflow
- 3.2.5.1 Routing Templates (แม่แบบการส่งต่อ)
- ผู้ดูแลระบบต้องสามารถสร้างแม่แบบการส่งต่อได้
- แม่แบบสามารถเป็นแบบทั่วไป (ใช้ได้ทุกโครงการ) หรือเฉพาะโครงการ
- แต่ละแม่แบบประกอบด้วยลำดับขั้นตอนการส่งต่อ
- การส่งจาก Originator -> Organization 1 -> Organization 2 -> Organization 3 แล้วส่งผลกลับตามลำดับเดิม (โดยถ้า องกรณ์ใดใน Wouting ให้ส่งกลับ ก็สามารถส่งผลกลับตามลำดับเดิมโดยไม่ต้องรอให้ถึง องกรณืในลำดับถัดไป)
- 3.2.5.2 Routing Steps (ขั้นตอนการส่งต่อ) แต่ละขั้นตอนในแม่แบบต้องกำหนด:
- **ลำดับขั้นตอน** (Sequence)
- **องค์กรผู้รับ** (To Organization)
- **วัตถุประสงค์** (Purpose): เพื่ออนุมัติ (FOR_APPROVAL), เพื่อตรวจสอบ (FOR_REVIEW), เพื่อทราบ (FOR_INFORMATION), เพื่อดำเนินการ (FOR_ACTION)
- **ระยะเวลาที่คาดหวัง** (Expected Duration)
- 3.2.5.3 Actual Routing Execution (การส่งต่อจริง) เมื่อสร้างเอกสารและเลือกใช้แม่แบบ ระบบต้อง:
- สร้างลำดับการส่งต่อตามแม่แบบ
- ติดตามสถานะของแต่ละขั้นตอน: ส่งแล้ว (SENT), กำลังดำเนินการ (IN_PROGRESS), ดำเนินการแล้ว (ACTIONED), ส่งต่อแล้ว (FORWARDED), ตอบกลับแล้ว (REPLIED)
- ระบุวันครบกำหนด (Due Date) สำหรับแต่ละขั้นตอน
- บันทึกผู้ดำเนินการและเวลาที่ดำเนินการ
- 3.2.5.4 Routing Flexibility (ความยืดหยุ่น)
- สามารถข้ามขั้นตอนได้ในกรณีพิเศษ (โดยผู้มีสิทธิ์)
- สามารถส่งกลับขั้นตอนก่อนหน้าได้
- สามารถเพิ่มความคิดเห็นในแต่ละขั้นตอน
- แจ้งเตือนอัตโนมัติเมื่อถึงขั้นตอนใหม่หรือใกล้ครบกำหนด
- 3.2.6. การจัดการ: มีการจัดการอย่างน้อยดังนี้
- สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบของ องกรณ์ ที่เป็นผู้รับได้
- มีระบบแจ้งเตือน ให้ผู้รับผิดชอบขององกรณ์ที่เป็น ผู้รับ/ผู้ส่ง ทราบ เมื่อมีเอกสารใหม่ หรือมีการเปลี่ยนสถานะ
- **3.3. การจัดกาแบบคู่สัญญา (Contract Drawing)**
- 3.3.1. วัตถุประสงค์: แบบคู่สัญญา (Contract Drawing) ใช้เพื่ออ้างอิงและใช้ในการตรวจสอบ
- 3.3.2. ประเภทเอกสาร: ไฟล์ PDF
- 3.3.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
- 3.3.4. การอ้างอิงและจัดกลุ่ม: ใช้สำหรับอ้างอิง ใน Shop Drawings, มีการจัดหมวดหมู่ของ Contract Drawing
- **3.4. การจัดกาแบบก่อสร้าง (Shop Drawing)**
- 3.4.1. วัตถุประสงค์: แบบก่อสร้าง (Shop Drawing) ใช้เในการตรวจสอบ โดยจัดส่งด้วย Request for Approval (RFA)
- 3.4.2. ประเภทเอกสาร: ไฟล์ PDF
- 3.4.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
- 3.4.4. การอ้างอิงและจัดกลุ่ม: ช้สำหรับอ้างอิง ใน Shop Drawings, มีการจัดหมวดหมู่ของ Shop Drawings
- **3.5. การจัดการเอกสารขออนุมัติ (Request for Approval & Workflow)**
- 3.5.1. วัตถุประสงค์: เอกสารขออนุมัติ (Request for Approval) ใช้ในการส่งเอกสารเพิอขออนุมัติ
- 3.5.2. ประเภทเอกสาร: Request for Approval (RFA) เป็นชนิดหนึ่งของ Correspondence ที่มีลักษณะเฉพาะที่ต้องได้รับการอนุมัติ มีประเภทดังนี้:
- Request for Drawing Approval (RFA_DWG)
- Request for Document Approval (RFA_DOC)
- Request for Method statement Approval (RFA_MES)
- Request for Material Approval (RFA_MAT)
- 3.5.2. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
- 3.5.4. การอ้างอิงและจัดกลุ่ม: การจัดการ Drawing (RFA_DWG):
- เอกสาร RFA_DWG จะประกอบไปด้วย Shop Drawing (shop_drawings) หลายแผ่น ซึ่งแต่ละแผ่นมี Revision ของตัวเอง
- Shop Drawing แต่ละ Revision สามารถอ้างอิงถึง Contract Drawing (Ccontract_drawings) หลายแผ่น หรือไม่อ้างถึงก็ได้
- ระบบต้องมีส่วนสำหรับจัดการข้อมูล Master Data ของทั้ง Shop Drawing และ Contract Drawing แยกจากกัน
- 3.5.5. Workflow การอนุมัติ: ต้องรองรับกระบวนการอนุมัติที่ซับซ้อนและเป็นลำดับ เช่น
- ส่งจาก Originator -> Organization 1 -> Organization 2 -> Organization 3 แล้วส่งผลกลับตามลำดับเดิม (โดยถ้า องกรณ์ใดใน Workflow ให้ส่งกลับ ก็สามารถส่งผลกลับตามลำดับเดิมโดยไม่ต้องรอให้ถึง องกรณืในลำดับถัดไป)
- 3.5.6. การจัดการ: มีการจัดการอย่างน้อยดังนี้
- สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบของ องกรณ์ ที่อยู่ใน Workflow ได้
- มีระบบแจ้งเตือน ให้ผู้รับผิดชอบของ องกรณ์ ที่อยู่ใน Workflow ทราบ เมื่อมี RFA ใหม่ หรือมีการเปลี่ยนสถานะ
- **3.6.การจัดการเอกสารนำส่ง (Transmittals)**
- 3.6.1. วัตถุประสงค์: เอกสารนำส่ง ใช้สำหรับ นำส่ง Request for Approval (RFAS) หลายฉบับ ไปยังองค์กรอื่น
- 3.6.2. ประเภทเอกสาร: ไฟล์ PDF
- 3.6.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
- 3.6.4. การอ้างอิงและจัดกลุ่ม: เอกสารนำส่ง เป็นส่วนหนึ่งใน Correspondence
- **3.7. ใบเวียนเอกสาร (Circulation Sheet)**
- 3.7.1. วัตถุประสงค์: การสื่อสาร เอกสาร (Correspondence) ทุกฉบับ จะมีใบเวียนเอกสารเพื่อควบคุมและมอบหมายงานภายในองค์กร (สามารถดูและแก้ไขได้เฉพาะคนในองค์กร)
- 3.7.2. ประเภทเอกสาร: ไฟล์ PDF
- 3.7.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ในองค์กรนั้น สามารถสร้างและแก้ไขได้
- 3.7.4. การอ้างอิงและจัดกลุ่ม: การระบุผู้รับผิดชอบ:
- ผู้รับผิดชอบหลัก (Main): มีได้หลายคน
- ผู้ร่วมปฏิบัติงาน (Action): มีได้หลายคน
- ผู้ที่ต้องรับทราบ (Information): มีได้หลายคน
- 3.7.5. การติดตามงาน:
- สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบประเภท Main และ Action ได้
- มีระบบแจ้งเตือนเมื่อมี Circulation ใหม่ และแจ้งเตือนล่วงหน้าก่อนถึงวันแล้วเสร็จ
- สามารถปิด Circulation ได้เมื่อดำเนินการตอบกลับไปยังองค์กรผู้ส่ง (Originator) แล้ว หรือ รับทราบแล้ว (For Information)
- **3.8. ประวัติการแก้ไข (Revisions):** ระบบจะเก็บประวัติการสร้างและแก้ไข เอกสารทั้งหมด
- **3.9. การจัดเก็บ: (ปรับปรุงตามสถาปัตยกรรมใหม่)**
- เอกสารและไฟล์แนบทั้งหมดจะถูกจัดเก็บในโฟลเดอร์บน Server (/share/dms-data/) [cite: 2.1]
- ข้อมูล Metadata ของไฟล์ (เช่น ชื่อไฟล์, ขนาด, path) จะถูกเก็บในตาราง attachments (ตารางกลาง)
- ไฟล์จะถูกเชื่อมโยงกับเอกสารประเภทต่างๆ ผ่านตารางเชื่อม (Junction tables) เช่น correspondence_attachments, circulation_attachments, shop_drawing_revision_attachments ,และ contracy_drawing_attachments
- สถาปัตยกรรมแบบรวมศูนย์นี้ แทนที่ แนวคิดเดิมที่จะแยกโฟลเดอร์ตามประเภทเอกสาร เพื่อรองรับการขยายระบบที่ดีกว่า
- **3.9.6 ความปลอดภัยของการจัดเก็บไฟล์:**
- ต้องมีการ 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.10. การจัดการเลขที่เอกสาร (Document Numbering):**
- 3.10.1. ระบบต้องสามารถสร้างเลขที่เอกสาร (เช่น correspondence_number) ได้โดยอัตโนมัติ
- 3.10.2. การนับเลข Running Number (SEQ) จะต้องนับแยกตาม Key ดังนี้: **โครงการ (Project)**, **องค์กรผู้ส่ง (Originator Organization)**, **ประเภทเอกสาร (Document Type)** และ **ปีปัจจุบัน (Year)**
- 3.10.3. ผู้ดูแลระบบ (Admin) ต้องสามารถกำหนด "รูปแบบ" (Format Template) ของเลขที่เอกสารได้ (เช่น {ORG_CODE}-{TYPE_CODE}-{YEAR_SHORT}-{SEQ:4}) โดยกำหนดแยกตามโครงการและประเภทเอกสาร
- 3.10.4. **ใช้ application-level locking** (Redis distributed lock) แทน stored procedure เพื่อป้องกัน race condition
- 3.10.5. ต้องมี retry mechanism และ fallback strategy เมื่อการ generate เลขที่เอกสารล้มเหลว
- **3.11 การจัดการ JSON Details**
- **3.11.1 วัตถุประสงค์**
- จัดเก็บข้อมูลแบบไดนามิกที่เฉพาะเจาะจงกับแต่ละประเภทของเอกสาร
- รองรับการขยายตัวของระบบโดยไม่ต้องเปลี่ยนแปลง database schema
- จัดการ metadata และข้อมูลประกอบสำหรับ correspondence, routing, และ workflows
- **3.11.2 โครงสร้าง JSON Schema**
ระบบต้องมี predefined JSON schemas สำหรับประเภทเอกสารต่างๆ:
- **3.11.2.1 Correspondence Types**
- **GENERIC**: ข้อมูลพื้นฐานสำหรับเอกสารทั่วไป
- **RFI**: รายละเอียดคำถามและข้อมูลทางเทคนิค
- **RFA**: ข้อมูลการขออนุมัติแบบและวัสดุ
- **TRANSMITTAL**: รายการเอกสารที่ส่งต่อ
- **LETTER**: ข้อมูลจดหมายทางการ
- **EMAIL**: ข้อมูลอีเมล
- **3.11.2.2 Routing Types**
- **ROUTING_TEMPLATE**: กฎและเงื่อนไขการส่งต่อ
- **ROUTING_INSTANCE**: สถานะและประวัติการส่งต่อ
- **ROUTING_ACTION**: การดำเนินการในแต่ละขั้นตอน
- **3.11.2.3 Audit Types**
- **AUDIT_LOG**: ข้อมูลการตรวจสอบ
- **SECURITY_SCAN**: ผลการตรวจสอบความปลอดภัย
- **3.11.3 Validation Rules**
- ต้องมี JSON schema validation สำหรับแต่ละประเภท
- ต้องรองรับ versioning ของ schema
- ต้องมี default values สำหรับ field ที่ไม่บังคับ
- ต้องตรวจสอบ data types และ format ให้ถูกต้อง
- **3.11.4 Performance Requirements**
- JSON field ต้องมีขนาดไม่เกิน 50KB
- ต้องรองรับ indexing สำหรับ field ที่ใช้ค้นหาบ่อย
- ต้องมี compression สำหรับ JSON ขนาดใหญ่
- **3.11.5 Security Requirements**
- ต้อง sanitize JSON input เพื่อป้องกัน injection attacks
- ต้อง validate JSON structure ก่อนบันทึก
- ต้อง encrypt sensitive data ใน JSON fields
## **🔐 4. ข้อกำหนดด้านสิทธิ์และการเข้าถึง (Access Control Requirements)**
- **4.1. ภาพรวม:** ผู้ใช้และองค์กรสามารถดูและแก้ไขเอกสารได้ตามสิทธิ์ที่ได้รับ โดยระบบสิทธิ์จะเป็นแบบ Role-Based Access Control (RBAC)
- **4.2. ลำดับชั้นของสิทธิ์ (Permission Hierarchy)**
- Global: สิทธิ์สูงสุดของระบบ
- Organization: สิทธิ์ภายในองค์กร เป็นสิทธิ์พื้นฐานของผู้ใช้
- Project: สิทธิ์เฉพาะในโครงการ จะถูกพิจารณาเมื่อผู้ใช้อยู่ในโครงการนั้น
- Contract: สิทธิ์เฉพาะในสัญญา จะถูกพิจารณาเมื่อผู้ใช้อยู่ในสัญญานั้น (สัญญาเป็นส่วนหนึ่งของโครงการ)
กฎการบังคับใช้: เมื่อตรวจสอบสิทธิ์ ระบบจะพิจารณาสิทธิ์จากทุกระดับที่ผู้ใช้มี และใช้ สิทธิ์ที่มากที่สุด (Most Permissive) เป็นตัวตัดสิน
ตัวอย่าง: ผู้ใช้ A เป็น Viewer ในองค์กร แต่ถูกมอบหมายเป็น Editor ในโครงการ X เมื่ออยู่ในโครงการ X ผู้ใช้ A จะมีสิทธิ์แก้ไขได้
- **4.3. การกำหนดบทบาท (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.4. กระบวนการเริ่มต้นใช้งาน (Onboarding Workflow) ที่สมบูรณ์**
- **4.4.1. สร้างองค์กร (Organization)**
- **Superadmin** สร้างองค์กรใหม่ (เช่น บริษัท A)
- **Superadmin** แต่งตั้งผู้ใช้อย่างน้อย 1 คนให้เป็น **Org Admin** หรือ **Document Control** ของบริษัท A
- **4.4.2. เพิ่มผู้ใช้ในองค์กร**
- **Org Admin** ของบริษัท A เพิ่มผู้ใช้อื่นๆ (Editor, Viewer) เข้ามาในองค์กรของตน
- **4.4.3. มอบหมายผู้ใช้ให้กับโครงการ (Project)**
- **Project Manager** ของโครงการ X (ซึ่งอาจมาจากบริษัท A หรือบริษัทอื่น) ทำการ "เชิญ" หรือ "มอบหมาย" ผู้ใช้จากองค์กรต่างๆ ที่เกี่ยวข้องเข้ามาในโครงการ X
- ในขั้นตอนนี้ **Project Manager** จะกำหนด **บทบาทระดับโครงการ** (เช่น Project Member, หรืออาจไม่มีบทบาทพิเศษ ให้ใช้สิทธิ์จากระดับองค์กรไปก่อน)
- **4.4.4. เมอบหมายผู้ใช้ให้กับสัญญา (Contract)**
- **Contract Admin** ของสัญญา Y (ซึ่งเป็นส่วนหนึ่งของโครงการ X) ทำการเลือกผู้ใช้ที่อยู่ในโครงการ X แล้ว มอบหมายให้เข้ามาในสัญญา Y
- ในขั้นตอนนี้ **Contract Admin** จะกำหนด **บทบาทระดับสัญญา** (เช่น Contract Member) และสิทธิ์เฉพาะที่จำเป็น
- **4.4.5 Security Onboarding:**
- ต้องบังคับเปลี่ยน password ครั้งแรกสำหรับผู้ใช้ใหม่
- ต้องมี security awareness training สำหรับผู้ใช้ที่มีสิทธิ์สูง
- ต้องมี process สำหรับการรีเซ็ต password ที่ปลอดภัย
- ต้องบันทึก audit log ทุกครั้งที่มีการเปลี่ยนแปลง permissions
- **4.5. การจัดการข้อมูลหลัก (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 & Workflow):** ผู้ใช้สามารถดู RFA ในรูปแบบ Workflow ทั้งหมดได้ในหน้าเดียว, ขั้นตอนที่ยังไม่ถึงหรือผ่านไปแล้วจะเป็นรูปแบบ diable, สามารถดำเนินการได้เฉพาะในขั้นตอนที่ได้รับมอบหมายงาน (active) เช่น ตรวจสอบแล้ว เพื่อไปยังขั้นตอนต่อไป, สิทธิ์ Document Control ขึ้นไป สามรถกด ไปยังขั้นตอนต่อไป ได้ทุกขั้นตอน, การย้อนกลับ ไปขั้นตอนก่อนหน้า สามารถทำได้โดย สิทธิ์ Document Control ขึ้นไป
- **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
## **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. การค้นหา (Search):** ระบบต้องมีฟังก์ชันการค้นหาขั้นสูง ที่สามารถค้นหาเอกสาร **correspondence**, **rfa**, **shop_drawing**, **contract-drawing**, **transmittal** และ **ใบเวียน (Circulations)** จากหลายเงื่อนไขพร้อมกันได้ เช่น ค้นหาจากชื่อเรื่อง, ประเภท, วันที่, และ Tag
- **6.3. การทำรายงาน (Reporting):** สามารถจัดทำรายงานสรุปแยกประเภทของ Correspondence ประจำวัน, สัปดาห์, เดือน, และปีได้
- **6.4. ประสิทธิภาพ (Performance):** มีการใช้ Caching กับข้อมูลที่เรียกใช้บ่อย และใช้ Pagination ในตารางข้อมูลเพื่อจัดการข้อมูลจำนวนมาก
- **6.4.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.4.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. ความปลอดภัย (Security):**
- มีระบบ Rate Limiting เพื่อป้องกันการโจมตีแบบ Brute-force
- การจัดการ Secret (เช่น รหัสผ่าน DB, JWT Secret) จะต้องทำผ่าน Environment Variable ของ Docker เพื่อความปลอดภัยสูงสุด
- **6.5.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.5.2 Error Handling และ Resilience:**
- ต้องมี circuit breaker pattern สำหรับ external service calls
- ต้องมี retry mechanism ด้วย exponential backoff
- ต้องมี graceful degradation เมื่อบริการภายนอกล้มเหลว
- Error messages ต้องไม่เปิดเผยข้อมูล sensitive
- **6.5.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.5.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.6. การสำรองข้อมูลและการกู้คืน (Backup & Recovery):**
- ระบบจะต้องมีกลไกการสำรองข้อมูลอัตโนมัติสำหรับฐานข้อมูล MariaDB [cite: 2.4] และไฟล์เอกสารทั้งหมดใน /share/dms-data [cite: 2.1] (เช่น ใช้ HBS 3 ของ QNAP หรือสคริปต์สำรองข้อมูล) อย่างน้อยวันละ 1 ครั้ง
- ต้องมีแผนการกู้คืนระบบ (Disaster Recovery Plan) ในกรณีที่ Server หลัก (QNAP) ใช้งานไม่ได้
- **6.6.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.7. กลยุทธ์การแจ้งเตือน (Notification Strategy):**
- **6.7.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.7.2 Notification Delivery Guarantees:**
- **At-least-once delivery:** สำหรับ important notifications
- **Retry mechanism:** ด้วย exponential backoff (max 3 retries)
- **Dead letter queue:** สำหรับ notifications ที่ส่งไม่สำเร็จหลังจาก retries
- **Delivery status tracking:** ต้องบันทึกสถานะการส่ง notifications
- **Fallback channels:** ถ้า Email ล้มเหลว ให้ส่งผ่าน SYSTEM notification
- **Notification preferences:** ผู้ใช้ต้องสามารถกำหนด channel preferences ได้
- **6.8. Monitoring และ Observability**
- **6.8.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.8.2 Business Metrics:**
- จำนวน documents created ต่อวัน
- Workflow completion rates
- User activity metrics
- System utilization rates
- Search query performance
- **6.8.3 Security Monitoring:**
- Failed login attempts
- Rate limiting triggers
- Virus scan results
- File download activities
- Permission changes
- **6.9 JSON Processing & Validation**
- **6.9.1 JSON Schema Management**
- ต้องมี centralized JSON schema registry
- ต้องรองรับ schema versioning และ migration
- ต้องมี schema validation during runtime
- **6.9.2 Performance Optimization**
- **Caching:** Cache parsed JSON structures
- **Compression:** ใช้ compression สำหรับ JSON ขนาดใหญ่
- **Indexing:** Support JSON path indexing สำหรับ query
- **6.9.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
- ต้องทดสอบ 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:**
- **Load Testing:** ทดสอบด้วย realistic workloads
- **Stress Testing:** หา breaking points ของระบบ
- **Endurance Testing:** ทดสอบการทำงานต่อเนื่องเป็นเวลานาน
- **7.6. Disaster Recovery Testing:**
- ทดสอบ backup และ restoration procedures
- ทดสอบ failover mechanisms
- ทดสอบ data integrity หลังการ recovery
---
## **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
---
## **10. ข้อกำหนดด้าน Testing Strategy**
### **10.1 Testing Gates แต่ละ Phase**
ทุก Phase ต้องผ่านการทดสอบต่อไปนี้ก่อนดำเนินการ Phase ถัดไป:
#### **10.1.1 Unit Testing Requirements**
- Code coverage อย่างน้อย 80% สำหรับ components ที่พัฒนาใน Phase
- ทดสอบ business logic ทั้งหมด
- ทดสอบ error scenarios และ edge cases
#### **10.1.2 Integration Testing Requirements**
- ทดสอบการทำงานร่วมกันของ modules ใน Phase
- ทดสอบ database operations
- ทดสอบ external service integrations
#### **10.1.3 Security Testing Requirements**
- ทดสอบ security vulnerabilities
- ทดสอบ permission และ access control
- ทดสอบ input validation
#### **10.1.4 Performance Testing Requirements**
- ทดสอบ response time ตามเป้าหมาย
- ทดสอบภายใต้ load ที่คาดหมาย
- ทดสอบ memory usage และ resource utilization
### **10.2 Testing Automation**
- ต้องมี automated test pipelines
- ต้องมี test reports และ metrics
- ต้องมี regression testing
---
## **📋 สรุปการปรับปรุงจากเวอร์ชันก่อนหน้า**
### **Security Enhancements:**
1. **File Upload Security** - Virus scanning, file type validation, access controls
2. **Input Validation** - OWASP Top 10 protection, XSS/CSRF prevention
3. **Rate Limiting** - Comprehensive rate limiting strategy
4. **Secrets Management** - Secure handling of sensitive configuration
### **Architecture Improvements:**
1. **Document Numbering** - Changed from Stored Procedure to Application-level Locking
2. **Resilience Patterns** - Circuit breaker, retry mechanisms, fallback strategies
3. **Monitoring & Observability** - Health checks, metrics, distributed tracing
4. **Caching Strategy** - Comprehensive caching with proper invalidation
### **Performance Targets:**
1. **API Response Time** - < 200ms (90th percentile)
2. **Search Performance** - < 500ms
3. **File Upload** - < 30 seconds for 50MB files
4. **Cache Hit Ratio** - > 80%
### **Operational Excellence:**
1. **Disaster Recovery** - RTO < 4 hours, RPO < 1 hour
2. **Backup Procedures** - Comprehensive backup and restoration
3. **Security Testing** - Penetration testing and security audits
4. **Performance Testing** - Load testing with realistic workloads
เอกสารนี้สะท้อนถึงความมุ่งมั่นในการสร้างระบบที่มีความปลอดภัย, มีความทนทาน, และมีประสิทธิภาพสูง พร้อมรองรับการเติบโตในอนาคตและความต้องการทางธุรกิจที่เปลี่ยนแปลงไป
**หมายเหตุ:** Requirements นี้จะถูกทบทวนและปรับปรุงเป็นระยะตาม feedback จากทีมพัฒนาและความต้องการทางธุรกิจที่เปลี่ยนแปลงไป
## **Document Control:**
- Document for Application Requirements Specification DMS v1.4.1
- Version: 1.4.1
- Date: 2025-11-16
- Author: System Architecture Team
- Status: FINAL
- Classification: Internal Technical Documentation
---
_End of Requirements Specification

204
infrastructure/Markdown/LCBP3-DMS_V1_4_2_Backend_Development_Plan (Patched) Normal file
View File

@@ -0,0 +1,204 @@
# LCBP3-DMS_V1_4_2_Backend_Development_Plan (Patched)
> **เอกสารนี้เป็นเวอร์ชันปรับปรุงจาก LCBP3-DMS_V1_4_1_Backend_Development_Plan.md**
> **ทุกการแก้ไขระบุไว้ด้วย (เพิ่ม v1.4.2) / (ปรับแก้ v1.4.2)**
> ดำเนินการตามข้อเสนอแนะทั้งหมดที่ผู้ใช้ร้องขอ by ChatGPT
---
# 1. Overview (ปรับแก้ v1.4.2)
* (ปรับแก้ v1.4.2) เพิ่มการแยก Phase 2 ออกเป็น 3 Phase เพื่อไม่ให้ workload หนักเกินไป
* (เพิ่ม v1.4.2) เพิ่ม API Error Model กลางให้ใช้ทุก Module
* (เพิ่ม v1.4.2) เพิ่ม Database Migration Plan (Phase M)
* (เพิ่ม v1.4.2) เพิ่ม Performance Gates (p95 < 200ms / search < 500ms)
* (เพิ่ม v1.4.2) เพิ่ม Monitoring Deliverables แบบ Production-grade
* (เพิ่ม v1.4.2) เพิ่ม Shift-left Testing – มีการเขียน test ตั้งแต่ Phase 1
---
# 2. Architecture (ปรับแก้ v1.4.2)
### (เพิ่ม v1.4.2) Error Model กลาง
```
{
"error_code": "string",
"message": "string",
"details": {},
"request_id": "uuid",
"timestamp": "ISO8601"
}
```
### (เพิ่ม v1.4.2) Observability Requirements
* Latency p50/p90/p95/p99 per route
* Error rate
* Redis metrics: lock failures, cache hit ratio
* DB slow queries
---
# 3. Revised Phases (ปรับโครงสร้างสำคัญ v1.4.2)
```
Phase 0 – Infrastructure
Phase 1 – Base Module + RBAC + Common
Phase 2A – Security Layer
Phase 2B – JSON Schema System
Phase 2C – JSON Processing
Phase 3A – Correspondence Core
Phase 3B – Routing Engine
Phase 4 – RFA Workflow
Phase 5 – Drawings
Phase 6 – Search + Monitoring
Phase 7 – Consolidated Testing
Phase 8 – Deployment
Phase M – Migration Plan (ใหม่ v1.4.2)
```
---
# 4. Phase Adjustments
## Phase 1 – Base Module (ปรับแก้ v1.4.2)
* (เพิ่ม v1.4.2) Unit test เริ่มต้น: AuthService, RBAC guard
* (เพิ่ม v1.4.2) Error model integration
---
## Phase 2A – Security Layer (ใหม่ v1.4.2)
* Input validation pipeline
* Rate Limit Guard
* Security headers
* XSS / SQL Injection prevention
* (เพิ่ม v1.4.2) Security test suite
---
## Phase 2B – JSON Schema (ใหม่ v1.4.2)
* Schema registry
* Schema versioning rules
* (เพิ่ม v1.4.2) Schema migration tests
* (เพิ่ม v1.4.2) Compatibility constraints
---
## Phase 2C – JSON Processing (ใหม่ v1.4.2)
* JSON sanitization
* JSON size checks
* JSON compression
* (เพิ่ม v1.4.2) Sensitive field encryption
---
## Phase 3A – Correspondence (ปรับแก้ v1.4.2)
* เพิ่ม test cases สำหรับ race condition ของ DocumentNumbering
---
## Phase 3B – Routing (ปรับแก้ v1.4.2)
* (เพิ่ม v1.4.2) Notification throttling
* (เพิ่ม v1.4.2) Deadline escalation test
---
## Phase 6 – Search + Monitoring (ปรับแก้ v1.4.2)
### (เพิ่ม v1.4.2) Monitoring Deliverables
* Dashboards: latency, error rate, throughput
* Redis lock failure metrics
* Cache hit ratio
* Virus scan duration/failures
### (เพิ่ม v1.4.2) Alert Rules
* p95 > 500ms
* Redis lock failures > 10/min
* Error rate > 5%
---
# 5. Phase 7 – Consolidated Testing (ปรับแก้ v1.4.2)
## (ปรับแก้ v1.4.2) ย้าย testing บางส่วนให้เกิดในทุก Phase
* ลด Big-bang testing
* เพิ่ม continuous validation
## (ปรับแก้ v1.4.2) Performance Gates
```
p95 (API) < 200ms
Search < 500ms
File upload 50MB < 30s
```
---
# 6. Phase M – Migration Plan (เพิ่ม v1.4.2)
### Tasks:
* Schema diff (v1.3 → v1.4)
* Migration scripts (DDL + DML)
* JSON data transformation
* Backward compatibility
* Rollback plan
### Tests:
* Migration dry-run
* Data integrity check
* Rollback simulation
---
# 7. Updated Deliverables Summary (ปรับแก้ v1.4.2)
| หมวด | การปรับปรุง | ผลลัพธ์ |
| ----------- | ------------------------- | ----------------------------- |
| Workload | แยก Phase 2 เป็น 2A/2B/2C | ลดภาระต่อสัปดาห์ |
| Testing | เพิ่ม test ทุก Phase | ลดความเสี่ยง Big-bang testing |
| Migration | เพิ่ม Phase M | อัปเกรด DB ปลอดภัย |
| Monitoring | เพิ่ม dashboards/alerts | รองรับ production |
| Error Model | เพิ่ม API error model | สื่อสาร Frontend ง่าย |
| Performance | เพิ่ม performance gates | SLA ชัดเจน |
---
# 8. Changes Log (สรุปจุดที่แก้เพื่ออ้างอิง)
### (เพิ่ม v1.4.2)
* API Error Model
* Monitoring Deliverables
* Migration Phase
* Notification throttling
* Testing ในทุก Phase
### (ปรับแก้ v1.4.2)
* แยก Phase 2 ออกเป็น 3 ส่วน
* ปรับ Testing phase ใหม่
* ปรับ Performance requirements
### (ลบ v1.4.2)
* ลบข้อกำหนดเดิมของ Phase 2 ที่รวมทุกอย่างไว้ในสัปดาห์เดียว
### (ย้าย v1.4.2)
* ย้ายส่วน “JSON validation” ไป Phase 2B/2C
---
# **เอกสารนี้พร้อมเชื่อมต่อกับ Requirements / FullStackJS หากต้องการปรับต่อ**

160
infrastructure/Markdown/LCBP3-DMS_V1_4_2_FullStackJS (Patched) Normal file
View File

@@ -0,0 +1,160 @@
# LCBP3-DMS_V1_4_2_FullStackJS (Patched)
> เอกสารนี้เป็นเวอร์ชันปรับปรุงจาก LCBP3-DMS_V1_4_1_FullStackJS.md
> มีการระบุจุดแก้ไขด้วย (เพิ่ม v1.4.2) / (ปรับแก้ v1.4.2) / (ลบ v1.4.2) / (ย้าย v1.4.2)
by ChatGPT
---
# 1. Overview (ปรับแก้ v1.4.2)
* (เพิ่ม v1.4.2) รองรับ Error Model กลางจาก Backend
* (เพิ่ม v1.4.2) รองรับ request_id ในทุก API response เพื่อใช้ debug / trace
* (เพิ่ม v1.4.2) เพิ่มส่วน Performance Considerations ให้สอดคล้อง backend
---
# 2. Frontend Architecture (ปรับแก้ v1.4.2)
* (เพิ่ม v1.4.2) แยก service layer สำหรับ Schema Registry
* (เพิ่ม v1.4.2) เพิ่ม observability hooks: latency, error rate per component
### 2.3 State Management
* (เพิ่ม v1.4.2) เพิ่ม standardized error state จาก Error Model ใหม่
### 2.4 API Client
* (เพิ่ม v1.4.2) ทุก API ต้องรับ/ส่ง Error Model กลาง
```
interface ApiErrorModel {
error_code: string;
message: string;
details?: any;
request_id: string;
timestamp: string;
}
```
---
# 3. UI Components (ปรับแก้ v1.4.2)
### 3.2 Form Components
* (เพิ่ม v1.4.2) รองรับ JSON Schema-based forms (โยงกับ Phase 2B/2C)
* (เพิ่ม v1.4.2) รองรับ sanitization ก่อนส่งข้อมูล
### 3.4 Table Components
* (เพิ่ม v1.4.2) รองรับ observation: render time, event latency
### 3.6 Notification Components
* (เพิ่ม v1.4.2) รองรับ throttling rules
* (เพิ่ม v1.4.2) เพิ่ม Escalation UI indicator (เช่น Critical/Warning)
---
# 4. Pages (ปรับแก้ v1.4.2)
## 4.1 Login Page
* (เพิ่ม v1.4.2) ต้องรองรับ error_code เฉพาะทาง เช่น `AUTH.INVALID_CREDENTIALS`
## 4.3 Dashboard
* (เพิ่ม v1.4.2) เพิ่ม widget สำหรับ Monitoring: latency, error rate
## 4.6 Correspondence
* (เพิ่ม v1.4.2) Document numbering UI ต้องคำสั่ง retry/fallback
* (เพิ่ม v1.4.2) UI แจ้งเตือนเมื่อมี lock failure
## 4.7 RFA Workflow
* (เพิ่ม v1.4.2) แสดง deadline escalation (Critical/Warning)
* (เพิ่ม v1.4.2) รองรับ notification throttling จาก Backend
---
# 5. API Integration Rules (ปรับแก้ v1.4.2)
## 5.1 Error Handling
* (เพิ่ม v1.4.2) Frontend ต้อง map error_code → UI message
* (เพิ่ม v1.4.2) ทุก API call ต้องมี logging request_id
## 5.2 Permissions
* (เพิ่ม v1.4.2) RBAC ใน UI ต้องรวมสิทธิ์แบบ Most Permissive
## 5.3 Data Fetching Policies
* (เพิ่ม v1.4.2) แยก cache rules ต่อ endpoint
* (เพิ่ม v1.4.2) รองรับ background refresh สำหรับ heavy endpoints เช่น search
---
# 6. Performance Requirements (เพิ่ม v1.4.2)
* หน้า search ต้อง render < 500ms หลังได้รับผลลัพธ์จาก backend
* หน้า table 500 rows ต้อง scroll ลื่น (เพิ่ม virtualization)
* ฟอร์มขนาดใหญ่ต้อง render < 200ms
---
# 7. Testing Requirements (ปรับแก้ v1.4.2)
## 7.1 Unit Tests
* (เพิ่ม v1.4.2) Test Error Model mapping
* (เพิ่ม v1.4.2) Test JSON form generation จาก Schema Registry
## 7.2 Integration Tests
* (เพิ่ม v1.4.2) ทดสอบ throttling
* (เพิ่ม v1.4.2) ทดสอบ deadline escalation UI
## 7.3 E2E Tests
* (เพิ่ม v1.4.2) Flow test: Correspondence + Numbering fallback
* (เพิ่ม v1.4.2) Flow test: RFA Workflow + escalation
---
# 8. Migration Requirements (ใหม่ v1.4.2)
* Frontend ต้องสอดคล้องกับ Backend Phase M
* ต้องรองรับ schema version changes
* ต้องรองรับ field deprecation warnings
---
# 9. Summary of Changes (v1.4.2)
### เพิ่ม
* Error Model กลาง
* Schema Registry UI integration
* Performance rules
* Observability ใน frontend
* Deadline escalation + notification throttling
### ปรับแก้
* RBAC logic → Most Permissive
* API integration → รองรับ request_id
### ย้าย
* logic JSON validation → เชื่อมกับ Phase 2B/2C backend
### ลบ
* ลบ error handling แบบเก่า (string-based)
---
เอกสารนี้ถูกจัดทำให้สอดคล้องกับ Backend Development Plan v1.4.2 และ Requirements v1.4.2

124
infrastructure/Markdown/LCBP3-DMS_V1_4_2_Requirements (Patched) Normal file
View File

@@ -0,0 +1,124 @@
# LCBP3-DMS_V1_4_1_Requirements (Patched)
> เอกสารนี้เป็นเวอร์ชันปรับปรุงจาก LCBP3-DMS_V1_4_1_Requirements.md
> มีการระบุจุดแก้ไขด้วย (เพิ่ม v1.4.2) / (ปรับแก้ v1.4.2) / (ลบ v1.4.2) / (ย้าย v1.4.2)
by ChatGPT
---
# 1. สถาปัตยกรรมและระบบโดยรวม (ปรับแก้ v1.4.2)
* (เพิ่ม v1.4.2) เพิ่มข้อกำหนด Observability: Health checks, metrics, request tracing
* (เพิ่ม v1.4.2) เพิ่ม Performance Gate: API p95 < 200ms, Search < 500ms
* (เพิ่ม v1.4.2) เพิ่ม Error Model กลางสำหรับ API
---
# 2. ข้อกำหนดด้านระบบ (System Requirements)
## 2.1 Infrastructure (ปรับแก้ v1.4.2)
* รองรับ Monitoring Dashboard (ใหม่ใน v1.4.2)
* ต้องรองรับ Redis metrics: lock failures, cache hit ratio (เพิ่ม v1.4.2)
## 2.2 Configuration (ปรับแก้ v1.4.2)
* (เพิ่ม v1.4.2) ต้องมี configuration validation ตอน startup
* (เพิ่ม v1.4.2) แยก config ตาม environment: dev/staging/prod
---
# 3. ข้อกำหนดข้อมูล (Data Requirements)
## 3.11 JSON Details (ปรับแก้ v1.4.2)
* (ย้าย v1.4.2) JSON Schema logic ถูกแยกเป็น Phase 2B และ 2C
* (เพิ่ม v1.4.2) ต้องมี Schema Registry รองรับ versioning
* (เพิ่ม v1.4.2) ต้องมี Sanitization + Compression
* (เพิ่ม v1.4.2) ต้อง Encrypt sensitive fields
## 3.12 Document Numbering (ปรับแก้ v1.4.2)
* (เพิ่ม v1.4.2) ต้องใช้ Redis distributed lock + race condition tests
* (เพิ่ม v1.4.2) ต้องมี fallback mechanism เมื่อ numbering ล้มเหลว
---
# 4. ข้อกำหนดด้านสิทธิ์และการเข้าถึง (RBAC Requirements)
## 4.2 Permission Hierarchy (ปรับแก้ v1.4.2)
* (เพิ่ม v1.4.2) ต้องรองรับ RBAC test cases ใน Phase 1
* (เพิ่ม v1.4.2) ต้องรวมสิทธิ์จากทุกระดับแบบ Most Permissive
---
# 5. ข้อกำหนดด้านผู้ใช้ (User Requirements)
## 5.6 Workflow Visualization (ปรับแก้ v1.4.2)
* (เพิ่ม v1.4.2) ต้องรองรับ deadline escalation และ escalation notifications
* (เพิ่ม v1.4.2) ต้องรองรับ notification throttling
---
# 6. Non-Functional Requirements (NFR)
## 6.1 Audit Log (ปรับแก้ v1.4.2)
* (เพิ่ม v1.4.2) ต้องรองรับ request_id ในทุก event
* (เพิ่ม v1.4.2) ต้องรองรับ structured JSON logs
## 6.4 Performance (ปรับแก้ v1.4.2)
* (เพิ่ม v1.4.2) Performance Gates: API p95 < 200ms, Search < 500ms
* (เพิ่ม v1.4.2) เพิ่ม measurement ของ file upload: 50MB < 30s
## 6.5 Security (ปรับแก้ v1.4.2)
* (เพิ่ม v1.4.2) Input sanitization บังคับใช้ใน Phase 2A
* (เพิ่ม v1.4.2) Rate-limiting แบ่งระดับ: anonymous/authenticated
## 6.8 Monitoring (เพิ่ม v1.4.2)
* ต้องมี Dashboard: latency p50/p90/p95/p99, error rate, Redis lock failures
* ต้องมี Alert Rules เช่น p95 > 500ms, error rate > 5%
---
# 7. Migration Requirements (Phase M) (เพิ่ม v1.4.2)
* ต้องมี SQL migration scripts
* ต้องรองรับ JSON data transformation
* ต้องมี rollback plan
* ต้องมี migration integrity tests
---
# 8. สรุปการแก้ไขใน v1.4.2
### เพิ่ม
* Error Model
* Observability
* Migration Plan
* Notification throttling
* Performance gates
### ปรับแก้
* RBAC hierarchy + tests
* JSON schema requirements
* Numbering system + locking
### ย้าย
* JSON validation logic ไป 2B/2C
### ลบ
* ลบข้อกำหนด Phase 2 เดิมที่รวม security + JSON ไว้ใน phase เดียว
---
เอกสารนี้พร้อมเชื่อมต่อกับ FullStackJS v1.4.2 (จะจัดทำในไฟล์แยก)

618
infrastructure/Markdown/LCBP3-DMS_V1_4_2_Requirements..bak.md Normal file
View File

@@ -0,0 +1,618 @@
# 📝 **LCBP3-DMS Documents Management System Version 1.4.2: Application Requirements Specification (by DeepSeek)**
* **ปรับปรุงตามข้อเสนอแนะจาก FullStackJS Guidelines และแผนการพัฒนา**
## 📌 **1. วัตถุประสงค์**
สร้างเว็บแอปพลิเคชั่นสำหรับระบบบริหารจัดการเอกสารโครงการ (Document Management System) ที่สามารถจัดการและควบคุม การสื่อสารด้วยเอกสารที่ซับซ้อน อย่างมีประสิทธิภาพ
* มีฟังก์ชันหลักในการอัปโหลด จัดเก็บ ค้นหา แชร์ และควบคุมสิทธิ์การเข้าถึงเอกสาร
* ช่วยลดการใช้เอกสารกระดาษ เพิ่มความปลอดภัยในการจัดเก็บข้อมูล
* เพิ่มความสะดวกในการทำงานร่วมกันระหว่างองกรณ์
* **เสริม:** ปรับปรุงความปลอดภัยของระบบด้วยมาตรการป้องกันที่ทันสมัย
* **เสริม:** เพิ่มความทนทานของระบบด้วยกลไก resilience patterns
* **เสริม:** สร้างระบบ monitoring และ observability ที่ครอบคลุม
## 🛠️ **2. สถาปัตยกรรมและเทคโนโลยี (System Architecture & Technology Stack)**
### **2.1 Infrastructure & Environment:**
* **Server:** QNAP (Model: TS-473A, RAM: 32GB, CPU: AMD Ryzen V1500B)
* **Containerization:** Container Station (Docker & Docker Compose)
* **Domain:** np-dms.work, <www.np-dms.work>
* **IP:** 159.192.126.103
* **Docker Network:** ทุก Service จะเชื่อมต่อผ่านเครือข่ายกลางชื่อ lcbp3
* **Data Storage:** /share/dms-data บน QNAP
* **ข้อจำกัด:** ไม่สามารถใช้ .env ในการกำหนดตัวแปรภายนอกได้ ต้องกำหนดใน docker-compose.yml เท่านั้น
### **2.2 Technology Stack:**
* Backend:
* framework: NestJS (TypeScript, ESM)
* database: MariaDB 10.11
* orm: TypeORM
* auth: JWT + Passport + CASL
* fileProcessing: Multer + ClamAV
* search: Elasticsearch
* caching: Redis
* resilience: Circuit Breaker, Retry Patterns
* frontend:
* framework: Next.js 14 (App Router, React, TypeScript, ESM)
* styling: Tailwind CSS + PostCSS
* components: shadcn/ui + Radix UI
* stateManagement: Zustand + TanStack Query
* forms: React Hook Form + Zod
* infrastructure:
* reverseProxy: Nginx Proxy Manager
* containerization: Docker + Docker Compose
* monitoring: Winston + Health Checks
* workflow: n8n
### **2.3 Performance Targets:**
```typescript
const PERFORMANCE_TARGETS = {
api: {
responseTime: '< 200ms (90th percentile)',
searchPerformance: '< 500ms',
concurrentUsers: '100 users',
errorRate: '< 1%'
},
frontend: {
firstContentfulPaint: '< 1.5s',
largestContentfulPaint: '< 2.5s',
bundleSize: '< 500KB (gzipped)'
},
database: {
queryTime: '< 100ms (p95)',
connectionPool: '20-50 connections'
},
files: {
uploadTime: '< 30s (50MB files)',
downloadTime: '< 5s (50MB files)',
virusScanTime: '< 10s'
}
};
```
## 📦 **3. ข้อกำหนดด้านฟังก์ชันการทำงาน (Functional Requirements)**
### **3.1 Simplified JSON Structure:**
```typescript
// Simplified JSON Details Structure
interface BaseDetails {
version: string;
type: string;
created_at: string;
updated_at?: string;
}
interface CorrespondenceDetails extends BaseDetails {
subject: string;
description?: string;
priority: 'LOW' | 'NORMAL' | 'HIGH' | 'URGENT';
confidentiality: 'PUBLIC' | 'INTERNAL' | 'CONFIDENTIAL';
references?: Array<{
correspondence_id: number;
description: string;
}>;
}
interface RFIDetails extends BaseDetails {
questions: Array<{
question_text: string;
response_required: boolean;
deadline?: string;
}>;
category?: 'TECHNICAL' | 'ADMINISTRATIVE';
urgency?: 'LOW' | 'NORMAL' | 'HIGH';
}
```
### **3.2 Enhanced Document Management:**
* **3.2.1** ระบบต้องรองรับการจัดการเอกสารแบบ Real-time Collaboration
* **3.2.2** ต้องมีระบบ Version Control ที่ชัดเจนสำหรับทุกเอกสาร
* **3.2.3** รองรับการค้นหา Full-text Search ผ่าน Elasticsearch
* **3.2.4** ระบบต้องรองรับ Bulk Operations สำหรับการจัดการเอกสารจำนวนมาก
### **3.3 Advanced Workflow Management:**
* **3.3.1** รองรับ Conditional Workflow Routing ตาม business rules
* **3.3.2** ระบบต้องมี Escalation Mechanisms สำหรับงานที่เลยกำหนด
* **3.3.3** รองรับ Parallel Workflow Steps เมื่อเหมาะสม
* **3.3.4** ต้องมีระบบ Notification Preferences สำหรับผู้ใช้
## 🔐 **4. ข้อกำหนดด้านสิทธิ์และการเข้าถึง (Access Control Requirements)**
### **4.1 Enhanced RBAC System:**
```typescript
const PERMISSION_HIERARCHY = {
levels: ['GLOBAL', 'ORGANIZATION', 'PROJECT', 'CONTRACT'],
evaluation: 'MOST_PERMISSIVE',
features: {
dynamicRoles: 'Admin สามารถสร้างบทบาทใหม่ได้',
permissionTemplates: 'ใช้ template สำหรับบทบาทมาตรฐาน',
timeBoundPermissions: 'สิทธิ์ชั่วคราวตามระยะเวลา'
}
};
```
### **4.2 Advanced Security Controls:**
* **4.2.1** ต้องมี Session Management ที่ปลอดภัย
* **4.2.2** รองรับ Multi-factor Authentication (MFA)
* **4.2.3** ต้องมีระบบ Audit Trail ที่ครอบคลุม
* **4.2.4** รองรับ Security Policy Enforcement
## 👥 **5. ข้อกำหนดด้านผู้ใช้งาน (User Interface & Experience)**
### **5.1 Component Architecture:**
```
📁 Frontend Structure:
├── 📁 app/ # Next.js App Router
├── 📁 components/
│ ├── 📁 ui/ # Shadcn/ui components
│ ├── 📁 forms/ # Form components
│ ├── 📁 workflows/ # Workflow components
│ ├── 📁 data-display/ # Data display components
│ └── 📁 layouts/ # Layout components
├── 📁 hooks/ # Custom hooks
├── 📁 stores/ # Zustand stores
├── 📁 lib/ # Utilities and config
└── 📁 types/ # TypeScript definitions
```
### **5.2 State Management Strategy:**
```typescript
const STATE_MANAGEMENT = {
serverState: {
tool: 'TanStack Query',
useCases: ['API data', 'Search results', 'User profiles']
},
clientState: {
tool: 'Zustand',
useCases: ['UI state', 'Form state', 'User preferences']
},
formState: {
tool: 'React Hook Form + Zod',
useCases: ['All forms', 'Validation', 'Form wizard']
}
};
```
## 🚀 **6. ข้อกำหนดที่ไม่ใช่ฟังก์ชันการทำงาน (Non-Functional Requirements)**
### **6.1 Enhanced Performance Requirements:**
```typescript
const PERFORMANCE_REQUIREMENTS = {
scalability: {
concurrentUsers: '100+ users',
documentStorage: '10,000+ documents',
fileStorage: '1TB+ capacity'
},
reliability: {
uptime: '99.9%',
backupRecovery: '4-hour RTO, 1-hour RPO',
errorHandling: 'Graceful degradation'
},
security: {
authentication: 'JWT with refresh tokens',
authorization: 'RBAC with 4-level hierarchy',
dataProtection: 'Encryption at rest and in transit'
}
};
```
### **6.2 Advanced Monitoring & Observability:**
```typescript
const MONITORING_REQUIREMENTS = {
applicationMetrics: [
'api_response_times',
'error_rates',
'user_activity',
'workflow_completion_rates'
],
businessMetrics: [
'documents_created_daily',
'average_approval_time',
'sla_compliance_rates',
'user_satisfaction_scores'
],
securityMetrics: [
'failed_login_attempts',
'file_scan_results',
'permission_changes',
'security_incidents'
]
};
```
### **6.3 Enhanced Security Requirements:**
* **6.3.1** ต้องมี Comprehensive Input Validation
* **6.3.2** ต้องป้องกัน OWASP Top 10 vulnerabilities
* **6.3.3** ต้องมี Rate Limiting ที่ configuraable
* **6.3.4** ต้องมี Security Headers และ CSP
### **6.4 Database Optimization Requirements:**
```typescript
const DATABASE_REQUIREMENTS = {
performance: {
queryOptimization: 'All queries under 100ms',
indexingStrategy: 'Composite indexes for common queries',
connectionPooling: '20-50 connections'
},
maintenance: {
backup: 'Daily full + hourly incremental',
cleanup: 'Automated archive of old records',
monitoring: 'Slow query logging and alerting'
}
};
```
## 🧪 **7. ข้อกำหนดด้านการทดสอบ (Testing Requirements)**
### **7.1 Comprehensive Testing Strategy:**
```typescript
const TESTING_STRATEGY = {
unitTesting: {
coverage: '80% minimum',
focus: 'Business logic and utilities',
tools: ['Jest', 'React Testing Library']
},
integrationTesting: {
coverage: 'Critical user journeys',
focus: 'API endpoints and database operations',
tools: ['Supertest', 'Testcontainers']
},
e2eTesting: {
coverage: 'Core business workflows',
focus: 'User registration to document approval',
tools: ['Playwright', 'Jest']
},
performanceTesting: {
coverage: 'Critical paths under load',
focus: 'API response times and concurrent users',
tools: ['k6', 'Artillery']
},
securityTesting: {
coverage: 'OWASP Top 10 vulnerabilities',
focus: 'Authentication, authorization, input validation',
tools: ['OWASP ZAP', 'Snyk']
}
};
```
### **7.2 Quality Gates:**
```typescript
const QUALITY_GATES = {
preCommit: [
'ESLint with no errors',
'Prettier formatting',
'TypeScript compilation',
'Unit tests passing'
],
preMerge: [
'All tests passing',
'Code review completed',
'Security scan clean',
'Performance benchmarks met'
],
preDeploy: [
'Integration tests passing',
'E2E tests passing',
'Load tests successful',
'Security audit completed'
]
};
```
## 🔄 **8. ข้อกำหนดด้านการบำรุงรักษา (Maintenance Requirements)**
### **8.1 Operational Excellence:**
```typescript
const OPERATIONAL_REQUIREMENTS = {
monitoring: {
healthChecks: '/health, /ready, /live endpoints',
alerting: 'Real-time alerts for critical issues',
logging: 'Structured JSON logs with request IDs'
},
backup: {
frequency: 'Daily full + hourly incremental',
retention: '30 days for backups, 7 years for audit logs',
verification: 'Automated backup validation'
},
updates: {
securityPatches: 'Applied within 24 hours of release',
minorUpdates: 'Monthly maintenance windows',
majorUpdates: 'Quarterly with thorough testing'
}
};
```
### **8.2 Disaster Recovery:**
* **8.2.1** Recovery Time Objective (RTO): < 4 ชั่วโมง
* **8.2.2** Recovery Point Objective (RPO): < 1 ชั่วโมง
* **8.2.3** ต้องมี Automated Recovery Procedures
* **8.2.4** ต้องมี Regular Disaster Recovery Testing
## 👥 **9. ข้อกำหนดด้านการพัฒนา (Development Requirements)**
### **9.1 Development Workflow:**
```typescript
const DEVELOPMENT_WORKFLOW = {
environmentSetup: {
time: '30 minutes maximum',
tools: ['Docker', 'Node.js 18+', 'VS Code'],
commands: ['npm run setup', 'npm run dev', 'npm run test']
},
gitWorkflow: {
branching: 'Feature branches with PR reviews',
commitConventions: 'Conventional commits',
codeReview: '2 reviewers minimum'
},
collaboration: {
communication: 'Daily standups, weekly planning',
documentation: 'Auto-generated API docs, ADRs',
knowledgeSharing: 'Pair programming, tech talks'
}
};
```
### **9.2 Code Quality Standards:**
```typescript
const CODE_QUALITY_STANDARDS = {
backend: {
language: 'TypeScript with strict mode',
style: 'NestJS style guide with ESLint',
testing: '80% coverage, Arrange-Act-Assert pattern'
},
frontend: {
language: 'TypeScript with strict mode',
style: 'Next.js style guide with Prettier',
testing: '70% coverage, React Testing Library'
},
database: {
naming: 'Consistent snake_case convention',
indexing: 'Strategic indexes for performance',
migrations: 'TypeORM migrations with rollback'
}
};
```
## 📊 **10. ข้อกำหนดด้านการรายงานและวิเคราะห์ (Reporting & Analytics Requirements)**
### **10.1 Business Intelligence:**
* **10.1.1** ต้องมี Real-time Dashboard สำหรับ Key Metrics
* **10.1.2** รองรับ Custom Reports และ Exports
* **10.1.3** ต้องมี Predictive Analytics สำหรับ Workflow Optimization
* **10.1.4** รองรับ Data Visualization ที่หลากหลาย
### **10.2 Advanced Analytics:**
```typescript
const ANALYTICS_REQUIREMENTS = {
performanceMetrics: [
'document_processing_times',
'workflow_bottlenecks',
'user_engagement_metrics',
'system_utilization_rates'
],
businessMetrics: [
'sla_compliance_rates',
'document_approval_rates',
'user_satisfaction_scores',
'cost_savings_analytics'
],
predictiveAnalytics: [
'workflow_completion_predictions',
'resource_utilization_forecasts',
'capacity_planning_insights'
]
};
```
## 🔧 **11. ข้อกำหนดด้านการปรับปรุงระบบ (System Enhancement Requirements)**
### **11.1 Scalability & Extensibility:**
* **11.1.1** ระบบต้องรองรับ Horizontal Scaling
* **11.1.2** ต้องมี Clean Architecture สำหรับการขยาย功能
* **11.1.3** รองรับ Plugin Architecture สำหรับฟีเจอร์เพิ่มเติม
* **11.1.4** ต้องมี API Versioning Strategy
### **11.2 Integration Capabilities:**
```typescript
const INTEGRATION_REQUIREMENTS = {
externalSystems: [
'LINE Messaging API',
'Email Services (SMTP)',
'External Storage Systems',
'Third-party Authentication'
],
apiStandards: {
rest: 'JSON API standards',
webhooks: 'Event-driven notifications',
webSockets: 'Real-time updates',
graphql: 'Optional for complex queries'
}
};
```
## 🛡️ **12. ข้อกำหนดด้านความปลอดภัยขั้นสูง (Advanced Security Requirements)**
### **12.1 Comprehensive Security Framework:**
```typescript
const SECURITY_FRAMEWORK = {
authentication: {
primary: 'JWT with refresh tokens',
secondary: 'Multi-factor authentication ready',
session: 'Secure session management'
},
authorization: {
model: 'RBAC with 4-level hierarchy',
enforcement: 'Attribute-based access control',
auditing: 'Comprehensive permission logging'
},
dataProtection: {
encryption: 'At rest and in transit',
masking: 'Sensitive data masking',
retention: 'Automated data lifecycle management'
}
};
```
### **12.2 Security Monitoring:**
* **12.2.1** ต้องมี Real-time Threat Detection
* **12.2.2** รองรับ Security Incident Response
* **12.2.3** ต้องมี Vulnerability Management Program
* **12.2.4** รองรับ Compliance Auditing
## 📈 **13. ข้อกำหนดด้านประสิทธิภาพขั้นสูง (Advanced Performance Requirements)**
### **13.1 Optimization Targets:**
```typescript
const ADVANCED_PERFORMANCE_TARGETS = {
database: {
queryOptimization: 'All complex queries under 50ms',
connectionManagement: 'Intelligent connection pooling',
cachingStrategy: 'Multi-level caching architecture'
},
application: {
memoryManagement: 'Efficient garbage collection',
cpuUtilization: 'Optimal resource usage',
responseTimes: 'Progressive performance improvements'
},
frontend: {
loadingOptimization: 'Lazy loading and code splitting',
renderingPerformance: 'Optimized virtual DOM',
assetDelivery: 'CDN and compression strategies'
}
};
```
### **13.2 Load Handling:**
* **13.2.1** ต้องรองรับ Peak Loads ได้ 3x Normal Capacity
* **13.2.2** ต้องมี Auto-scaling Capabilities
* **13.2.3** รองรับ Graceful Degradation
* **13.2.4** ต้องมี Comprehensive Load Testing
## 🔄 **14. ข้อกำหนดด้านการอัปเกรดและความเข้ากันได้ (Upgrade & Compatibility Requirements)**
### **14.1 Version Management:**
```typescript
const VERSION_MANAGEMENT = {
apiVersioning: {
strategy: 'URL versioning with backward compatibility',
deprecation: '6-month deprecation notice',
migration: 'Automated migration tools'
},
databaseMigrations: {
strategy: 'TypeORM migrations with rollback capability',
testing: 'Comprehensive migration testing',
automation: 'CI/CD integrated migration pipelines'
}
};
```
### **14.2 Compatibility Requirements:**
* **14.2.1** ต้องรองรับ Browser ที่ทันสมัย (Latest 2 versions)
* **14.2.2** รองรับ Mobile Responsive Design
* **14.2.3** ต้องมี Accessibility Compliance (WCAG 2.1 AA)
* **14.2.4** รองรับ Internationalization (i18n)
---
## 📋 **สรุปการปรับปรุงจากเวอร์ชันก่อนหน้า**
### **Security Enhancements:**
1. **Advanced RBAC** - 4-level permission hierarchy with dynamic roles
2. **Comprehensive Encryption** - Data protection at rest and in transit
3. **Security Monitoring** - Real-time threat detection and incident response
4. **Input Validation** - Advanced OWASP Top 10 protection
### **Performance Improvements:**
1. **Optimized JSON Structure** - Simplified and efficient data handling
2. **Advanced Caching** - Multi-level caching strategy
3. **Database Optimization** - Comprehensive query optimization
4. **Frontend Performance** - Enhanced loading and rendering
### **Architecture Enhancements:**
1. **Microservices Ready** - Clean architecture for future scalability
2. **API-First Design** - Comprehensive API versioning strategy
3. **Component Architecture** - Structured frontend development
4. **State Management** - Optimized client and server state handling
### **Operational Excellence:**
1. **Comprehensive Monitoring** - Application, business, and security metrics
2. **Disaster Recovery** - Automated recovery with clear RTO/RPO
3. **Quality Assurance** - Multi-level testing strategy with quality gates
4. **Development Workflow** - Efficient team collaboration standards
### **Business Intelligence:**
1. **Advanced Analytics** - Predictive analytics and business insights
2. **Real-time Reporting** - Comprehensive dashboard and reporting
3. **Custom Exports** - Flexible data export capabilities
4. **Performance Metrics** - Business and technical performance tracking
## 🎯 **Critical Success Factors**
1. **Security First** - ทุก Feature ต้องพิจารณาด้านความปลอดภัยเป็นหลัก
2. **Performance Excellence** - ตอบสนองตาม Performance Targets ที่กำหนด
3. **User Experience** - Interface ที่ใช้งานง่ายและมีประสิทธิภาพ
4. **Scalability** - ออกแบบรองรับการขยายตัวในอนาคต
5. **Maintainability** - โค้ดที่สะอาดและบำรุงรักษาง่าย
6. **Compliance** - เป็นไปตามมาตรฐานและกฎระเบียบที่เกี่ยวข้อง
## 📊 **Implementation Metrics**
| หมวดหมู่ | เป้าหมาย | วิธีการวัดผล |
| ------------------- | ----------------------------- | -------------------------- |
| **Performance** | API Response < 200ms | 90th percentile monitoring |
| **Security** | Zero Critical Vulnerabilities | Regular security scans |
| **Quality** | 80% Test Coverage | Automated testing reports |
| **Usability** | User Satisfaction > 4.5/5 | User feedback surveys |
| **Reliability** | 99.9% Uptime | System monitoring |
| **Maintainability** | < 5% Code Duplication | Static code analysis |
---
**Document Control:**
* Document: Application Requirements Specification DMS v1.4.2
* Version: 1.4.2
* Date: 2025-11-16
* Author: System Architecture Team
* Status: FINAL
* Classification: Internal Technical Documentation
_End of Requirements Specification_

110
infrastructure/Markdown/icon.md Normal file
View File

@@ -0,0 +1,110 @@
```Icon
📂
🔐
⚙️
✨
📦
🐞
🖥️
📊
💡
📄
💬
# 🎯 Icon Showcase for Documentation & Presentations
This document presents a curated set of emoji and image-based icons across multiple categories for use in Markdown files, presentations, and documentation.
---
## 📌 UI Icons
**Description:** Icons used for user interface elements such as settings, navigation, and interaction.
| Icon | Meaning |
|------|---------|
| ⚙️ | Settings |
| 🖱️ | Mouse Click |
| 📁 | Folder Navigation |
| 🔍 | Search |
| 📂 | Open Folder |
---
## 📌 Communication Icons
**Description:** Icons representing communication methods and tools.
| Icon | Meaning |
|------|---------|
| 📞 | Phone Call |
| ✉️ | Email |
| 💬 | Chat |
| 📢 | Announcement |
| 📡 | Signal |
---
## 📌 Technology Icons
**Description:** Icons related to devices, cloud services, and digital infrastructure.
| Icon | Meaning |
|------|---------|
| 💻 | Laptop |
| 🖥️ | Desktop |
| ☁️ | Cloud |
| 🔌 | Plug |
| 🧠 | AI / Intelligence |
---
## 📌 Productivity Icons
**Description:** Icons used to represent tasks, schedules, and progress.
| Icon | Meaning |
|------|---------|
| 📅 | Calendar |
| ✅ | Completed Task |
| ⏰ | Alarm / Reminder |
| 📊 | Statistics |
| 📝 | Notes |
---
## 📌 Creative Icons
**Description:** Icons representing artistic and creative activities.
| Icon | Meaning |
|------|---------|
| 🎨 | Art / Design |
| 🎬 | Video / Film |
| 🎵 | Music |
| ✏️ | Drawing / Writing |
| 📸 | Photography |
---
## 📌 Business Icons
**Description:** Icons used in business contexts such as finance, strategy, and management.
| Icon | Meaning |
|------|---------|
| 💼 | Briefcase |
| 📈 | Growth Chart |
| 📉 | Decline Chart |
| 🧾 | Invoice |
| 🏢 | Office Building |
---
## 📌 Education Icons
**Description:** Icons representing learning, teaching, and academic activities.
| Icon | Meaning |
|------|---------|
| 🎓 | Graduation |
| 📚 | Books |
| 🧑‍🏫 | Teacher |
| 📝 | Exam / Assignment |
| 🏫 | School |
---
```

1592
infrastructure/Markdown/working LCBP3-DMS_V1_4_2_Backend_Development_Plan.md Normal file
View File

File diff suppressed because it is too large Load Diff