np-dms/lcbp3
0
0
Fork 0
Code Issues Pull Requests Actions 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 c302c5f9b1
commit ce795b26e2
169 changed files with 34584 additions and 26464 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1878
docs/01_lcbp3_v1_4_0.sql
View File

File diff suppressed because it is too large Load Diff

2418
docs/01_lcbp3_v1_4_1.sql
View File

File diff suppressed because it is too large Load Diff

2432
docs/01_lcbp3_v1_4_3.sql
View File

File diff suppressed because it is too large Load Diff

667
docs/Markdown/0_Requirements_V1_4_4.md → docs/0_Requirements_V1_4_5.md
View File

@@ -1,7 +1,7 @@
# 📝 **Documents Management System Version 1.4.4: Application Requirements Specification**
# 📝 **Documents Management System Version 1.4.5: Application Requirements Specification**
**สถานะ:** FINAL-Rev.05
**วันที่:** 2025-11-26
**วันที่:** 2025-11-29
**อ้างอิงพื้นฐาน:** v1.4.4
**Classification:** Internal Technical Documentation
@@ -111,15 +111,25 @@
### **2.4 Business Logic & Consistency (ปรับปรุง):**
- **2.4.1 Unified Workflow Engine (หลัก):** ระบบการเดินเอกสารทั้งหมด (Correspondence, RFA, Circulation) ต้อง ใช้ Engine กลางเดียวกัน โดยกำหนด Logic ผ่าน Workflow DSL (JSON Configuration) แทนการเขียน Hard-coded ลงในตาราง
- **2.4.1 Unified Workflow Engine (หลัก):**
- **2.4.2 Separation of Concerns:** Module ต่างๆ (RFA, Correspondence) จะเก็บเฉพาะข้อมูลของเอกสาร (Data) ส่วนสถานะและการเปลี่ยนสถานะ (State Transition) จะถูกจัดการโดย Workflow Engine
- ระบบการเดินเอกสารทั้งหมด (Correspondence, RFA, Circulation) ต้อง ใช้ Engine กลางเดียวกัน โดยกำหนด Logic ผ่าน Workflow DSL (JSON Configuration) แทนการเขียน Hard-coded ลงในตาราง
- Workflow Versioning (เพิ่ม): ระบบต้องรองรับการกำหนด Version ของ Workflow Definition โดยเอกสารที่เริ่มกระบวนการไปแล้ว (In-progress instances) จะต้องใช้ Workflow Version เดิม จนกว่าจะสิ้นสุดกระบวนการ หรือได้รับคำสั่ง Migrate จาก Admin เพื่อป้องกันความขัดแย้งของ State
- **2.4.3 Idempotency & Locking:** ใช้กลไกเดิมในการป้องกันการทำรายการซ้ำ
- **2.4.2 Separation of Concerns:**
- **2.4.4 Optimistic Locking (ใหม่):** ใช้ Version Column ใน Database ควบคู่กับ Redis Lock สำหรับการสร้างเลขที่เอกสาร เพื่อเป็น Safety Net ชั้นสุดท้าย
- Module ต่างๆ (Correspondence, RFA, Circulation) จะเก็บเฉพาะข้อมูลของเอกสาร (Data) ส่วนสถานะและการเปลี่ยนสถานะ (State Transition) จะถูกจัดการโดย Workflow Engine
- **2.4.5** **จะไม่มีการใช้ SQL Triggers** เพื่อป้องกันตรรกะซ่อนเร้น (Hidden Logic) และความซับซ้อนในการดีบัก
- **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:**
@@ -150,117 +160,118 @@
### **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.1. วัตถุประสงค์:
- เอกสารโต้ตอบ (correspondences) ระหว่างองค์กรณ์-องค์กรณ์ ภายใน โครงการ (Projects) และระหว่าง องค์กรณ์-องค์กรณ์ ภายนอก โครงการ (Projects), รองรับ To (ผู้รับหลัก) และ CC (ผู้รับสำเนา) หลายองค์กรณ์
- 3.2.2. ประเภทเอกสาร:
- ระบบต้องรองรับเอกสารรูปแบบ ไฟล์ PDF, ZIP
- เอกสารโต้ตอบ (Correspondence) สามารถมีได้หลายประเภท (Types) เช่น จดหมาย (Letter), อีเมล์ (Email), Request for Information (RFI), รวมถึง เอกสารขออนุมัติ (RFA) แต่ละ revision และสามารถเพิ่มประเภทใหม่ได้ในภายหลัง
- 3.2.3. การสร้างเอกสาร (Correspondence):
- ผู้ใช้ที่มีสิทธิ์ (เช่น Document Control) สามารถสร้างเอกสารรอไว้ในสถานะ ฉบับร่าง" (Draft) ได้ ซึ่งผู้ใช้งานต่างองค์กรจะมองไม่เห็น
- เมื่อกด "Submitted" แล้ว การแก้ไข, ถอนเอกสารกลับไปสถานะ Draft, หรือยกเลิก (Cancel) จะต้องทำโดยผู้ใช้ระดับ Admin ขึ้นไป พร้อมระบุเหตุผล
- 3.2.4. การอ้างอิงและจัดกลุ่ม:
- เอกสารสามารถอ้างถึง (Reference) เอกสารฉบับก่อนหน้าได้หลายฉบับ
- สามารถกำหนด Tag ได้หลาย Tag เพื่อจัดกลุ่มและใช้ในการค้นหาขั้นสูง
- 3.2.5. 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.2.5. Workflow (Unified Workflow):
- ระบบต้องรองรับ Workflow ที่เป็นแบบ Unified Workflow
### **3.3. การจัดกาแบบคู่สัญญา (Contract Drawing)**
### **3.3. การจัดการเอกสาขออนุมัติ (Request for Approval / RFA)**
- 3.3.1. วัตถุประสงค์: แบบคู่สัญญา (Contract Drawing) ใช้เพื่ออ้างอิงและใช้ในการตรวจสอบ
- 3.3.2. ประเภทเอกสาร: ไฟล์ PDF
- 3.3.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
- 3.3.4. การอ้างอิงและจัดกลุ่ม: ใช้สำหรับอ้างอิง ใน Shop Drawings, มีการจัดหมวดหมู่ของ Contract Drawing
- 3.3.1. วัตถุประสงค์:
- เอกสารขออนุมัติ (RFA) ภายใน โครงการ (Projects)
- 3.3.2. ประเภทเอกสาร:
- ระบบต้องรองรับเอกสารรูปแบบ ไฟล์ PDF
- เอกสารขออนุมัติ (RFA) สามารถมีได้หลาย revision
- มีประถทของเอกสาร ได้หลายประเภท (RFA Types) และสามารถเพิ่มประเภทใหม่ได้ในภายหลัง
- 3.3.3. การสร้างเอกสาร:
- ผู้ใช้ที่มีสิทธิ์ (เช่น Document Control) สามารถสร้างเอกสารขออนุมัติ (RFA) รอไว้ในสถานะ ฉบับร่าง" (Draft) ได้ ซึ่งผู้ใช้งานต่างองค์กรจะมองไม่เห็น
- เมื่อกด "Submitted" แล้ว การแก้ไข, ถอนเอกสารกลับไปสถานะ Draft, หรือยกเลิก (Cancel) จะต้องทำโดยผู้ใช้ระดับ Admin ขึ้นไป พร้อมระบุเหตุผล
- 3.3.4. การอ้างอิงและจัดกลุ่ม:
- RFA สามารถอ้างถึง (Reference) แบบก่อสร้าง (Shop Drawing) ได้หลายฉบับ
- 3.3.5. Workflow (Unified Workflow):
- ระบบต้องรองรับ Workflow ที่เป็นแบบ Unified Workflow ซึ่งจะมีสถานะและกิจกรรมที่ไม่เหมือนกันกับเอกสารโต้ตอบ (Correspondence)
### **3.4. การจัดกาแบบก่อสร้าง (Shop Drawing)**
### **3.4. การจัดการแบบคู่สัญญา (Contract Drawing)**
- 3.4.1. วัตถุประสงค์: แบบก่อสร้าง (Shop Drawing) ใช้เในการตรวจสอบ โดยจัดส่งด้วย Request for Approval (RFA)
- 3.4.1. วัตถุประสงค์: แบบคู่สัญญา (Contract Drawing) ใช้เพื่ออ้างอิงและใช้ในการตรวจสอบ
- 3.4.2. ประเภทเอกสาร: ไฟล์ PDF
- 3.4.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
- 3.4.4. การอ้างอิงและจัดกลุ่ม: ช้สำหรับอ้างอิง ใน Shop Drawings, มีการจัดหมวดหมู่ของ Shop Drawings
- 3.4.4. การอ้างอิงและจัดกลุ่ม: ใช้สำหรับอ้างอิง ใน Shop Drawings, มีการจัดหมวดหมู่ของ Contract Drawing
### **3.5. การจัดการ Workflow (Unified Workflow)**
### **3.5. การจัดกาแบบก่อสร้าง (Shop Drawing)**
- 3.5.1 Workflow Definition:
- 3.5.1. วัตถุประสงค์: แบบก่อสร้าง (Shop Drawing) ใช้เในการตรวจสอบ โดยจัดส่งด้วย Request for Approval (RFA)
- 3.5.2. ประเภทเอกสาร: ไฟล์ PDF, DWG, ZIP
- 3.5.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้ โดยผู้ใช้ที่มีสิทธิ์ (เช่น Document Control) สามารถสร้างเอกสารรอไว้ในสถานะ ฉบับร่าง" (Draft) ได้ ซึ่งผู้ใช้งานต่างองค์กรจะมองไม่เห็น
- 3.5.4. การอ้างอิงและจัดกลุ่ม: ใช้สำหรับอ้างอิง ใน RFA, มีการจัดหมวดหมู่ของ Shop Drawings โดยทุก แบบก่อสร้าง (Shop Drawing) แต่ละ revision ต้องมี RFA ได้เพียง 1 ฉบับ
- Admin ต้องสามารถสร้าง/แก้ไข Workflow Rule ได้ผ่านหน้าจอ UI (DSL Editor) ร
- องรับการกำหนด State, Transition, Required Role, Condition (JS Expression)
### **3.6. การจัดการ Workflow (Unified Workflow)**
- 3.5.2 Workflow Execution:
- 3.6.1 Workflow Definition:
- Admin ต้องสามารถสร้าง/แก้ไข Workflow Rule ได้ผ่านหน้าจอ UI (DSL Editor)
- รองรับการกำหนด State, Transition, Required Role, Condition (JS Expression)
- 3.6.2 Workflow Execution:
- ระบบต้องรองรับการสร้าง Instance ของ Workflow ผูกกับเอกสาร (Polymorphic)
- รองรับการเปลี่ยนสถานะ (Action) เช่น Approve, Reject, Comment, Return
- Auto-Action: รองรับการเปลี่ยนสถานะอัตโนมัติเมื่อครบเงื่อนไข (เช่น Review ครบทุกคน)
- 3.5.3 Flexibility:
- 3.6.3 Flexibility:
- รองรับ Parallel Review (ส่งให้หลายคนตรวจพร้อมกัน)
- รองรับ Conditional Flow (เช่น ถ้ายอดเงิน > X ให้เพิ่มผู้อนุมัติ)
- 3.5.4 Workflow การอนุมัติ:
- ต้องรองรับกระบวนการอนุมัติที่ซับซ้อนและเป็นลำดับ เช่น ส่งจาก Originator -> Organization 1 -> Organization 2 -> Organization 3 แล้วส่งผลกลับตามลำดับเดิม (โดยถ้า องกรณ์ใดใน Workflow ให้ส่งกลับ ก็สามารถส่งผลกลับตามลำดับเดิมโดยไม่ต้องรอให้ถึง องกรณืในลำดับถัดไป)
- 3.6.4 Workflow การอนุมัติ:
- รองรับกระบวนการอนุมัติที่ซับซ้อนและเป็นลำดับ เช่น ส่งจาก Originator -> Organization 1 -> Organization 2 -> Organization 3 แล้วส่งผลกลับตามลำดับเดิม (โดยถ้า องกรณ์ใดใน Workflow ให้ส่งกลับ ก็สามารถส่งผลกลับตามลำดับเดิมโดยไม่ต้องรอให้ถึง องกรณืในลำดับถัดไป)
- 3.6.5 การจัดการ:
- 3.5.5 การจัดการ:
- สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบของ องกรณ์ ที่อยู่ใน Workflow ได้
- มีระบบแจ้งเตือน ให้ผู้รับผิดชอบของ องกรณ์ ที่อยู่ใน Workflow ทราบ เมื่อมี RFA ใหม่ หรือมีการเปลี่ยนสถานะ
- สามารถข้ามขั้นตอนได้ในกรณีพิเศษ (โดยผู้มีสิทธิ์)
- สามารถส่งกลับขั้นตอนก่อนหน้าได้
### **3.6.การจัดการเอกสารนำส่ง (Transmittals)**
### **3.7.การจัดการเอกสารนำส่ง (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.1. วัตถุประสงค์: เอกสารนำส่ง ใช้สำหรับ นำส่ง Request for Approval (RFAS) หลายฉบับ ไปยังองค์กรอื่น
- 3.7.2. ประเภทเอกสาร: ไฟล์ PDF
- 3.7.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ในองค์กรนั้น สามารถสร้างและแก้ไขได้
- 3.7.4. การอ้างอิงและจัดกลุ่ม: การระบุผู้รับผิดชอบ:
- 3.7.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
- 3.7.4. การอ้างอิงและจัดกลุ่ม: เอกสารนำส่ง เป็นส่วนหนึ่งใน Correspondence
### **3.8.ใบเวียนเอกสาร (Circulation Sheet)**
- 3.8.1. วัตถุประสงค์: การสื่อสาร เอกสาร (Correspondence) ทุกฉบับ จะมีใบเวียนเอกสารเพื่อควบคุมและมอบหมายงานภายในองค์กร (สามารถดูและแก้ไขได้เฉพาะคนในองค์กร)
- 3.8.2. ประเภทเอกสาร: ไฟล์ PDF
- 3.8.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ในองค์กรนั้น สามารถสร้างและแก้ไขได้
- 3.8.4. การอ้างอิงและจัดกลุ่ม: การระบุผู้รับผิดชอบ:
- ผู้รับผิดชอบหลัก (Main): มีได้หลายคน
- ผู้ร่วมปฏิบัติงาน (Action): มีได้หลายคน
- ผู้ที่ต้องรับทราบ (Information): มีได้หลายคน
- 3.7.5. การติดตามงาน:
- 3.8.5. การติดตามงาน:
- สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบประเภท Main และ Action ได้
- มีระบบแจ้งเตือนเมื่อมี Circulation ใหม่ และแจ้งเตือนล่วงหน้าก่อนถึงวันแล้วเสร็จ
- สามารถปิด Circulation ได้เมื่อดำเนินการตอบกลับไปยังองค์กรผู้ส่ง (Originator) แล้ว หรือ รับทราบแล้ว (For Information)
### **3.8. ประวัติการแก้ไข (Revisions):** ระบบจะเก็บประวัติการสร้างและแก้ไข เอกสารทั้งหมด
### **3.9. ประวัติการแก้ไข (Revisions):** ระบบจะเก็บประวัติการสร้างและแก้ไข เอกสารทั้งหมด
### **3.9. การจัดเก็บไฟล์ (File Handling - ปรับปรุงใหญ่)**
### **3.10. การจัดเก็บไฟล์ (File Handling - ปรับปรุงใหญ่)**
- **3.9.1 Two-Phase Storage Strategy:**
- **3.10.1 Two-Phase Storage Strategy:**
1. **Phase 1 (Upload):** ไฟล์ถูกอัปโหลดเข้าโฟลเดอร์ `temp/` และได้รับ `temp_id`
2. **Phase 2 (Commit):** เมื่อ User กด Submit ฟอร์มสำเร็จ ระบบจะย้ายไฟล์จาก `temp/` ไปยัง `permanent/{YYYY}/{MM}/` และบันทึกลง Database ภายใน Transaction เดียวกัน
3. **Cleanup:** มี Cron Job ลบไฟล์ใน `temp/` ที่ค้างเกิน 24 ชม. (Orphan Files)
- **3.9.2 Security:**
- **3.10.2 Security:**
- Virus Scan (ClamAV) ก่อนย้ายเข้า Permanent
- Whitelist File Types: PDF, DWG, DOCX, XLSX, ZIP
- Max Size: 50MB
- Access Control: ตรวจสอบสิทธิ์ผ่าน Junction Table ก่อนให้ Download Link
- **3.9.3 ความปลอดภัยของการจัดเก็บไฟล์:**
- **3.10.3 ความปลอดภัยของการจัดเก็บไฟล์:**
- ต้องมีการ scan virus สำหรับไฟล์ที่อัปโหลดทั้งหมด โดยใช้ ClamAV หรือบริการ third-party
- จำกัดประเภทไฟล์ที่อนุญาต: PDF, DWG, DOCX, XLSX, ZIP (ต้องระบุรายการที่ชัดเจน)
- ขนาดไฟล์สูงสุด: 50MB ต่อไฟล์
@@ -269,92 +280,139 @@
- Download links ต้องมี expiration time (default: 24 ชั่วโมง)
- ต้องบันทึก audit log ทุกครั้งที่มีการดาวน์โหลดไฟล์สำคัญ
### **3.10. การจัดการเลขที่เอกสาร (Document Numbering - ปรับปรุง)**
### **3.11. การจัดการเลขที่เอกสาร (Document Numbering - ปรับปรุง)**
- 3.10.1. ระบบต้องสามารถสร้างเลขที่เอกสาร (Running Number) ได้โดยอัตโนมัติและยืดหยุ่นสูง
- 3.10.2. **Logic การนับเลข (Counter Logic):** การนับเลขจะต้องรองรับการแยกตาม Key ที่ซับซ้อนขึ้น:
- 3.11.1. ระบบต้องสามารถสร้างเลขที่เอกสาร (Running Number) ได้โดยอัตโนมัติและยืดหยุ่นสูง
- 3.11.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`
- 3.11.3. Format Template:
- รองรับการกำหนดรูปแบบด้วย Token Replacement เช่น:
- `{ORG}-{TYPE}-{DISCIPLINE}-{SEQ:4}-{REV}` -> `TEAM-RFA-STR-0001-A`
- รองรับ Token: `{PROJECT}`, `{ORG}`, `{TYPE}`, `{DISCIPLINE}`, `{SUBTYPE}`, `{SUBTYPE_NUM}`, `{YEAR}`, `{YEAR_SHORT}`, `{SEQ:n}`
- 3.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.4. Transmittal Logic: รองรับเงื่อนไขพิเศษสำหรับ Transmittal ที่เลขอาจเปลี่ยนตามผู้รับ (To Owner vs To Contractor)
- 3.11.5. กลไกความปลอดภัย: ยังคงใช้ Redis Distributed Lock และ Optimistic Locking เพื่อป้องกันเลขซ้ำหรือข้าม
- 3.11.6. ต้องมี retry mechanism และ fallback strategy เมื่อการ generate เลขที่เอกสารล้มเหลว
- 3.11.7 Fallback Logic (เพิ่ม):
- กรณีที่เอกสารประเภทนั้นไม่มี discipline_id หรือ sub_type_id (เป็นค่า NULL หรือไม่ระบุ) ให้ระบบใช้ค่า Default (เช่น 0) ในการจัดกลุ่ม Counter เพื่อป้องกัน Error และรับประกันความถูกต้องของ Running Number (Uniqueness Guarantee)
- Scenario 1: Redis Unavailable
- Fallback เป็น database-only locking (pessimistic lock)
- Log warning และแจ้ง ops team
- ระบบยังใช้งานได้แต่ performance ลดลง
- Scenario 2: Lock Acquisition Timeout
- Retry 5 ครั้งด้วย exponential backoff (1s, 2s, 4s, 8s, 16s)
- หลัง 5 ครั้ง: Return error 503 "Service Temporarily Unavailable"
- Frontend แสดง user-friendly message: "ระบบกำลังยุ่ง กรุณาลองใหม่ภายหลัง"
- Scenario 3: Version Conflict After Lock
- Retry transaction อีก 2 ครั้ง
- หากยังล้มเหลว: Log error พร้อม context และ return 409 Conflict
- Frontend แสดง user-friendly message: "เลขที่เอกสารถูกเปลี่ยน กรุณาลองใหม่"
- Monitoring:
- Alert ถ้า lock acquisition failures > 5% ใน 5 นาที
- Dashboard แสดง lock wait time percentiles
### **3.11 การจัดการ JSON Details (JSON & Performance - ปรับปรุง)**
### **3.12. การจัดการ JSON Details (JSON & Performance - ปรับปรุง)**
- **3.11.1 วัตถุประสงค์**
- **3.12.1 วัตถุประสงค์**
- จัดเก็บข้อมูลแบบไดนามิกที่เฉพาะเจาะจงกับแต่ละประเภทของเอกสาร
- รองรับการขยายตัวของระบบโดยไม่ต้องเปลี่ยนแปลง database schema
- จัดการ metadata และข้อมูลประกอบสำหรับ correspondence, routing, และ workflows
- **3.11.2 โครงสร้าง JSON Schema**
- **3.12.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.12.2.1 Correspondence Types
- GENERIC: ข้อมูลพื้นฐานสำหรับเอกสารทั่วไป
- RFI: รายละเอียดคำถามและข้อมูลทางเทคนิค
- RFA: ข้อมูลการขออนุมัติแบบและวัสดุ
- TRANSMITTAL: รายการเอกสารที่ส่งต่อ
- LETTER: ข้อมูลจดหมายทางการ
- EMAIL: ข้อมูลอีเมล
- 3.12.2.2 Rworkflow Types
- workflow_definitions: กฎและเงื่อนไขการส่งต่อ
- workflow_histories: สถานะและประวัติการส่งต่อ
- workflow_instances: การดำเนินการในแต่ละขั้นตอน
- 3.12.2.3 Audit Types
- AUDIT_LOG: ข้อมูลการตรวจสอบ
- SECURITY_SCAN: ผลการตรวจสอบความปลอดภัย
- **3.11.3 Virtual Columns (ใหม่):** สำหรับ Field ใน JSON ที่ต้องใช้ในการค้นหา (Search) หรือจัดเรียง (Sort) บ่อยๆ **ต้องสร้าง Generated Column (Virtual Column)** ใน Database และทำ Index ไว้ เพื่อประสิทธิภาพสูงสุด
- **3.12.3 Virtual Columns (ปรับปรุง):**
- **3.11.4 Validation Rules**
- สำหรับ Field ใน JSON ที่ต้องใช้ในการค้นหา (Search) หรือจัดเรียง (Sort) บ่อยๆ ต้องสร้าง Generated Column (Virtual Column) ใน Database และทำ Index ไว้ เพื่อประสิทธิภาพสูงสุด
- Schema Consistency: Field ที่ถูกกำหนดเป็น Virtual Column ห้าม เปลี่ยนแปลง Key Name หรือ Data Type ใน JSON Schema Version ถัดไป หากจำเป็นต้องเปลี่ยน ต้องมีแผนการ Re-index หรือ Migration ข้อมูลเดิมที่ชัดเจน
- **3.12.4 Validation Rules**
- ต้องมี JSON schema validation สำหรับแต่ละประเภท
- ต้องรองรับ versioning ของ schema
- ต้องมี default values สำหรับ field ที่ไม่บังคับ
- ต้องตรวจสอบ data types และ format ให้ถูกต้อง
- **3.11.5 Performance Requirements**
- **3.12.5 Performance Requirements**
- JSON field ต้องมีขนาดไม่เกิน 50KB
- ต้องรองรับ indexing สำหรับ field ที่ใช้ค้นหาบ่อย
- ต้องมี compression สำหรับ JSON ขนาดใหญ่
- **3.11.6 Security Requirements**
- **3.12.6 Security Requirements**
- ต้อง sanitize JSON input เพื่อป้องกัน injection attacks
- ต้อง validate JSON structure ก่อนบันทึก
- ต้อง encrypt sensitive data ใน JSON fields
### **3.12 ข้อกำหนดพิเศษ**
- 3.12.7 JSON Schema Migration Strategy (เพิ่มเติม)
สำหรับ Schema Breaking Changes:
- **ผู้ใช้งานที่มีสิทธิ์ระดับสูง (Global) หรือผู้ได้รับอนุญาตเป็นกรณีพิเศษ**
- สามารถเลือก **สร้างในนามองค์กร (Create on behalf of)** ได้ เพื่อให้สามารถออกเลขที่เอกสาร (Running Number) ขององค์กรอื่นได้โดยไม่ต้องล็อกอินใหม่
- Phase 1 - Add New Column
ALTER TABLE correspondence_revisions
ADD COLUMN ref_project_id_v2 INT GENERATED ALWAYS AS
(JSON_UNQUOTE(JSON_EXTRACT(details, '$.newProjectIdPath'))) VIRTUAL;
- Phase 2 - Backfill Old Records
- ใช้ background job แปลง JSON format เก่าเป็นใหม่
- Update `details` JSON ทีละ batch (1000 records)
- Phase 3 - Switch Application Code
- Deploy code ที่ใช้ path ใหม่
- Phase 4 - Remove Old Column
- หลังจาก verify แล้วว่าไม่มี error
- Drop old virtual column
- สำหรับ Non-Breaking Changes
- เพิ่ม optional field ใน schema
- Old records ที่ไม่มี field = ใช้ default value
### **3.13. ข้อกำหนดพิเศษ**
- ผู้ใช้งานที่มีสิทธิ์ระดับสูง (Global) หรือผู้ได้รับอนุญาตเป็นกรณีพิเศษ
- สามารถเลือก สร้างในนามองค์กร (Create on behalf of) ได้ เพื่อให้สามารถออกเลขที่เอกสาร (Running Number) ขององค์กรอื่นได้โดยไม่ต้องล็อกอินใหม่
- สามารถทำงานแทนผู้ใช้งานอื่นได้ Routing & Workflow ของ Correspondence, RFA, Circulation Sheet
### 3.13. การจัดการข้อมูลหลักขั้นสูง (Admin Panel for Master Data)
### **3.14. การจัดการข้อมูลหลักขั้นสูง (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 ได้โดยไม่ต้องแก้โค้ด
- 3.14.1. Disciplines Management: Admin ต้องสามารถ เพิ่ม/ลบ/แก้ไข สาขางาน (Disciplines) แยกตามสัญญา (Contract) ได้
- 3.14.2. Sub-Type Mapping: Admin ต้องสามารถกำหนด Correspondence Sub-types และ Mapping รหัสตัวเลข (เช่น MAT = 11) ได้
- 3.14.3. Numbering Format Configuration: Admin ต้องมี UI สำหรับตั้งค่า Format Template ของแต่ละ Project/Type ได้โดยไม่ต้องแก้โค้ด
## **🔐 4. ข้อกำหนดด้านสิทธิ์และการเข้าถึง (Access Control Requirements)**
### **4.1. ภาพรวม:** ผู้ใช้และองค์กรสามารถดูและแก้ไขเอกสารได้ตามสิทธิ์ที่ได้รับ โดยระบบสิทธิ์จะเป็นแบบ Role-Based Access Control (RBAC)
### **4.1. ภาพรวม:**
### **4.2. ลำดับชั้นของสิทธิ์ (Permission Hierarchy)**
- ผู้ใช้และองค์กรสามารถดูและแก้ไขเอกสารได้ตามสิทธิ์ที่ได้รับ โดยระบบสิทธิ์จะเป็นแบบ Role-Based Access Control (RBAC)
### **4.2. ลำดับชั้นของสิทธิ์ (Permission Hierarchy):**
- Global: สิทธิ์สูงสุดของระบบ
- Organization: สิทธิ์ภายในองค์กร เป็นสิทธิ์พื้นฐานของผู้ใช้
- Project: สิทธิ์เฉพาะในโครงการ จะถูกพิจารณาเมื่อผู้ใช้อยู่ในโครงการนั้น
- Contract: สิทธิ์เฉพาะในสัญญา จะถูกพิจารณาเมื่อผู้ใช้อยู่ในสัญญานั้น (สัญญาเป็นส่วนหนึ่งของโครงการ)
กฎการบังคับใช้: เมื่อตรวจสอบสิทธิ์ ระบบจะพิจารณาสิทธิ์จากทุกระดับที่ผู้ใช้มี และใช้ สิทธิ์ที่มากที่สุด (Most Permissive) เป็นตัวตัดสิน
### **4.3. กฎการบังคับใช้:**
ตัวอย่าง: ผู้ใช้ A เป็น Viewer ในองค์กร แต่ถูกมอบหมายเป็น Editor ในโครงการ X เมื่ออยู่ในโครงการ X ผู้ใช้ A จะมีสิทธิ์แก้ไขได้
- เมื่อตรวจสอบสิทธิ์ ระบบจะพิจารณาสิทธิ์จากทุกระดับที่ผู้ใช้มี และใช้ สิทธิ์ที่มากที่สุด (Most Permissive) เป็นตัวตัดสิน
- ตัวอย่าง: ผู้ใช้ A เป็น Viewer ในองค์กร แต่ถูกมอบหมายเป็น Editor ในโครงการ X เมื่ออยู่ในโครงการ X ผู้ใช้ A จะมีสิทธิ์แก้ไขได้
### **4.3. การกำหนดบทบาท (Roles) และขอบเขต (Scope)**
### **4.4. การกำหนดบทบาท (Roles) และขอบเขต (Scope):**
| บทบาท (Role) | ขอบเขต (Scope) | คำอธิบาย | สิทธิ์หลัก (Key Permissions) |
| :------------------- | :------------- | :---------------------- | :------------------------------------------------------------------------------------- |
@@ -366,31 +424,31 @@
| **Project Manager** | Project | ผู้จัดการโครงการ | จัดการสมาชิกในโครงการ (เพิ่ม/ลบ/มอบบทบาท), สร้าง/จัดการสัญญาในโครงการ, ดูรายงานโครงการ |
| **Contract Admin** | Contract | ผู้ดูแลสัญญา | จัดการสมาชิกในสัญญา, สร้าง/จัดการข้อมูลหลักเฉพาะสัญญา (ถ้ามี), อนุมัติเอกสารในสัญญา |
### **4.4. Token Management (ปรับปรุง)**
### **4.5 . Token Management (ปรับปรุง)**
- **Payload Optimization:** ใน JWT Access Token ให้เก็บเฉพาะ `userId` และ `scope` ปัจจุบันเท่านั้น
- **Permission Caching:** สิทธิ์ละเอียด (Permissions List) ให้เก็บใน **Redis** และดึงมาตรวจสอบเมื่อ Request เข้ามา เพื่อลดขนาด Token และเพิ่มความเร็ว
### **4.5. กระบวนการเริ่มต้นใช้งาน (Onboarding Workflow) ที่สมบูรณ์**
### **4.6. กระบวนการเริ่มต้นใช้งาน (Onboarding Workflow) ที่สมบูรณ์**
- **4.5.1. สร้างองค์กร (Organization)**
- 4.6.1. สร้างองค์กร (Organization)
- **Superadmin** สร้างองค์กรใหม่ (เช่น บริษัท A)
- **Superadmin** แต่งตั้งผู้ใช้อย่างน้อย 1 คนให้เป็น **Org Admin** หรือ **Document Control** ของบริษัท A
- **4.5.2. เพิ่มผู้ใช้ในองค์กร**
- 4.6.2. เพิ่มผู้ใช้ในองค์กร
- **Org Admin** ของบริษัท A เพิ่มผู้ใช้อื่นๆ (Editor, Viewer) เข้ามาในองค์กรของตน
- **4.5.3. มอบหมายผู้ใช้ให้กับโครงการ (Project)**
- 4.6.3. มอบหมายผู้ใช้ให้กับโครงการ (Project)
- **Project Manager** ของโครงการ X (ซึ่งอาจมาจากบริษัท A หรือบริษัทอื่น) ทำการ "เชิญ" หรือ "มอบหมาย" ผู้ใช้จากองค์กรต่างๆ ที่เกี่ยวข้องเข้ามาในโครงการ X
- ในขั้นตอนนี้ **Project Manager** จะกำหนด **บทบาทระดับโครงการ** (เช่น Project Member, หรืออาจไม่มีบทบาทพิเศษ ให้ใช้สิทธิ์จากระดับองค์กรไปก่อน)
- **4.5.4. เมอบหมายผู้ใช้ให้กับสัญญา (Contract)**
- 4.6.4. เมอบหมายผู้ใช้ให้กับสัญญา (Contract)
- **Contract Admin** ของสัญญา Y (ซึ่งเป็นส่วนหนึ่งของโครงการ X) ทำการเลือกผู้ใช้ที่อยู่ในโครงการ X แล้ว มอบหมายให้เข้ามาในสัญญา Y
- ในขั้นตอนนี้ **Contract Admin** จะกำหนด **บทบาทระดับสัญญา** (เช่น Contract Member) และสิทธิ์เฉพาะที่จำเป็น
- **4.5.5 Security Onboarding:**
- 4.6.5 Security Onboarding:
- ต้องบังคับเปลี่ยน password ครั้งแรกสำหรับผู้ใช้ใหม่
- ต้องมี security awareness training สำหรับผู้ใช้ที่มีสิทธิ์สูง
- ต้องมี process สำหรับการรีเซ็ต password ที่ปลอดภัย
- ต้องบันทึก audit log ทุกครั้งที่มีการเปลี่ยนแปลง permissions
### **4.6. การจัดการข้อมูลหลัก (Master Data Management) ที่แบ่งตามระดับ**
### **4.7. การจัดการข้อมูลหลัก (Master Data Management) ที่แบ่งตามระดับ**
| ข้อมูลหลัก | ผู้มีสิทธิ์จัดการ | ระดับ |
| :---------------------------------- | :------------------------------ | :--------------------------------- |
@@ -403,173 +461,199 @@
## **👥 5. ข้อกำหนดด้านผู้ใช้งาน (User Interface & Experience)**
### **5.1. Layout หลัก:** หน้าเว็บใช้รูปแบบ App Shell ที่ประกอบด้วย
### 5.1. Layout หลัก
- Navbar (ส่วนบน): แสดงชื่อระบบ, เมนูผู้ใช้ (Profile), เมนูสำหรับ Document Control/เมนูสำหรับ Admin/Superadmin (จัดการผู้ใช้, จัดการสิทธิ์), และปุ่ม Login/Logout
- Sidebar (ด้านข้าง): เป็นเมนูหลักสำหรับเข้าถึงส่วนที่เกี่ยวข้องกับเอกสารทั้งหมด เช่น Dashboard, Correspondences, RFA, Drawings
- Main Content Area: พื้นที่สำหรับแสดงเนื้อหาหลักของหน้าที่เลือก
- หน้าเว็บใช้รูปแบบ App Shell ที่ประกอบด้วย
- Navbar (ส่วนบน): แสดงชื่อระบบ, เมนูผู้ใช้ (Profile), เมนูสำหรับ Document Control/เมนูสำหรับ Admin/Superadmin (จัดการผู้ใช้, จัดการสิทธิ์, และอื่นๆ), และปุ่ม Login/Logout
- Sidebar (ด้านข้าง): เป็นเมนูหลักสำหรับเข้าถึงส่วนที่เกี่ยวข้องกับเอกสารทั้งหมด เช่น Dashboard, Correspondences, RFA, Drawings
- Main Content Area: พื้นที่สำหรับแสดงเนื้อหาหลักของหน้าที่เลือก
### **5.2. หน้า Landing Page:** เป็นหน้าแรกที่แสดงข้อมูลบางส่วนของโครงการสำหรับผู้ใช้ที่ยังไม่ได้ล็อกอิน
### 5.2. หน้า Landing Page
### **5.3. หน้า Dashboard:** เป็นหน้าแรกหลังจากล็อกอิน ประกอบด้วย
- เป็นหน้าแรกที่แสดงข้อมูลบางส่วนของโครงการสำหรับผู้ใช้ที่ยังไม่ได้ล็อกอิน
- การ์ดสรุปภาพรวม (KPI Cards): แสดงข้อมูลสรุปที่สำคัญขององค์กร เช่น จำนวนเอกสาร, งานที่เกินกำหนด
- ตาราง "งานของฉัน" (My Tasks Table): แสดงรายการงานทั้งหมดจาก Circulation ที่ผู้ใช้ต้องดำเนินการ
- Security Metrics: แสดงจำนวน files scanned, security incidents, failed login attempts
### 5.3. หน้า Dashboard
### **5.4. การติดตามสถานะ:** องค์กรสามารถติดตามสถานะเอกสารทั้งของตนเอง (Originator) และสถานะเอกสารที่ส่งมาถึงตนเอง (Recipient)
- เป็นหน้าแรกหลังจากล็อกอิน ประกอบด้วย
- การ์ดสรุปภาพรวม (KPI Cards): แสดงข้อมูลสรุปที่สำคัญขององค์กร เช่น จำนวนเอกสาร, งานที่เกินกำหนด
- ตาราง "งานของฉัน" (My Tasks Table): แสดงรายการงานทั้งหมดจาก Circulation ที่ผู้ใช้ต้องดำเนินการ
- Security Metrics: แสดงจำนวน files scanned, security incidents, failed login attempts
### **5.5. การจัดการข้อมูลส่วนตัว (Profile Page):** ผู้ใช้สามารถจัดการข้อมูลส่วนตัวและเปลี่ยนรหัสผ่านของตนเองได้
### 5.4. การติดตามสถานะ
### **5.6. การจัดการเอกสารทางเทคนิค (RFA & Workflow):** ผู้ใช้สามารถดู RFA ในรูปแบบ Workflow ทั้งหมดได้ในหน้าเดียว, ขั้นตอนที่ยังไม่ถึงหรือผ่านไปแล้วจะเป็นรูปแบบ diable, สามารถดำเนินการได้เฉพาะในขั้นตอนที่ได้รับมอบหมายงาน (active) เช่น ตรวจสอบแล้ว เพื่อไปยังขั้นตอนต่อไป, สิทธิ์ Document Control ขึ้นไป สามรถกด ไปยังขั้นตอนต่อไป ได้ทุกขั้นตอน, การย้อนกลับ ไปขั้นตอนก่อนหน้า สามารถทำได้โดย สิทธิ์ Document Control ขึ้นไป
- องค์กรสามารถติดตามสถานะเอกสารทั้งของตนเอง (Originator) และสถานะเอกสารที่ส่งมาถึงตนเอง (Recipient)
### **5.7. การจัดการใบเวียนเอกสาร (Circulation):** ผู้ใช้สามารถดู Circulation ในรูปแบบ Workflow ทั้งหมดได้ในหน้าเดียว,ขั้นตอนที่ยังไม่ถึงหรือผ่านไปแล้วจะเป็นรูปแบบ diable, สามารถดำเนินการได้เฉพาะในขั้นตอนที่ได้รับมอบหมายงาน (active) เช่น ตรวจสอบแล้ว เพื่อไปยังขั้นตอนต่อไป, สิทธิ์ Document Control ขึ้นไป สามรถกด ไปยังขั้นตอนต่อไป ได้ทุกขั้นตอน, การย้อนกลับ ไปขั้นตอนก่อนหน้า สามารถทำได้โดย สิทธิ์ Document Control ขึ้นไป
### 5.5. การจัดการข้อมูลส่วนตัว (Profile Page)
### **5.8. การจัดการเอกสารนำส่ง (Transmittals):** ผู้ใช้สามารถดู Transmittals ในรูปแบบรายการทั้งหมดได้ในหน้าเดียว
- ผู้ใช้สามารถจัดการข้อมูลส่วนตัวและเปลี่ยนรหัสผ่านของตนเองได้
### **5.9. ข้อกำหนด UI/UX การแนบไฟล์ (File Attachment UX):**
### 5.6. การจัดการเอกสารทางเทคนิค (RFA)
- ผู้ใช้สามารถดู RFA ในรูปแบบ Workflow Diagram ทั้งหมดได้ในหน้าเดียว
- Interactive History (เพิ่ม): ในแผนภาพ Workflow ผู้ใช้ต้องสามารถ คลิกที่ Node หรือ Step เก่าที่ผ่านมาแล้ว เพื่อดู Audit Log ย่อยของ Step นั้นได้ทันที (เช่น ใครเป็นคนกด Approve, เวลาไหน, มี Comment อะไร) โดยไม่ต้องสลับไปดูใน Tab History แยกต่างหาก
- ขั้นตอนที่ยังไม่ถึงหรือผ่านไปแล้วจะเป็นรูปแบบ disabled
- สามารถดำเนินการได้เฉพาะในขั้นตอนที่ได้รับมอบหมายงาน (active)
- สิทธิ์ Document Control ขึ้นไป สามารถกด "Force Proceed" ไปยังขั้นตอนต่อไปได้ทุกขั้นตอน หรือ "Revert" กลับขั้นตอนก่อนหน้าได้
### 5.7. การจัดการใบเวียนเอกสาร (Circulation)
- ผู้ใช้สามารถดู Circulation ในรูปแบบ Workflow ทั้งหมดได้ในหน้าเดียว,ขั้นตอนที่ยังไม่ถึงหรือผ่านไปแล้วจะเป็นรูปแบบ diable, สามารถดำเนินการได้เฉพาะในขั้นตอนที่ได้รับมอบหมายงาน (active) เช่น ตรวจสอบแล้ว เพื่อไปยังขั้นตอนต่อไป, สิทธิ์ Document Control ขึ้นไป สามรถกด ไปยังขั้นตอนต่อไป ได้ทุกขั้นตอน, การย้อนกลับ ไปขั้นตอนก่อนหน้า สามารถทำได้โดย สิทธิ์ Document Control ขึ้นไป
### 5.8. การจัดการเอกสารนำส่ง (Transmittals)
- ผู้ใช้สามารถดู Transmittals ในรูปแบบรายการทั้งหมดได้ในหน้าเดียว
### 5.9. ข้อกำหนด UI/UX การแนบไฟล์ (File Attachment UX)
- ระบบต้องรองรับการอัปโหลดไฟล์หลายไฟล์พร้อมกัน (Multi-file upload) เช่น การลากและวาง (Drag-and-Drop)
- ในหน้าอัปโหลด (เช่น สร้าง RFA หรือ Correspondence) ผู้ใช้ต้องสามารถกำหนดได้ว่าไฟล์ใดเป็น "เอกสารหลัก" (Main Document เช่น PDF) และไฟล์ใดเป็น "เอกสารแนบประกอบ" (Supporting Attachments เช่น .dwg, .docx, .zip)
- **Security Feedback:** แสดง security warnings สำหรับ file types ที่เสี่ยงหรือ files ที่ fail virus scan
- **File Type Indicators:** แสดง file type icons และ security status
### **5.10 Form & Interaction (ใหม่)**
### 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 (ใหม่)**
### 5.11 Mobile Responsiveness
- **Table Visualization:** บนหน้าจอมือถือ ตารางข้อมูลที่มีหลาย Column (เช่น Correspondence List) ต้องเปลี่ยนการแสดงผลเป็นแบบ **Card View** อัตโนมัติ
- **Navigation:** Sidebar ต้องเป็นแบบ Collapsible Drawer
### **5.12 Resilience & Offline Support (ใหม่)**
### 5.12 Resilience & Offline Support
- **Auto-Save Draft:** ระบบต้องบันทึกข้อมูลฟอร์มที่กำลังกรอกลง **LocalStorage** อัตโนมัติ เพื่อป้องกันข้อมูลหายกรณีเน็ตหลุดหรือปิด Browser โดยไม่ได้ตั้งใจ
- **State Management:** ใช้ State Management ที่เหมาะสมและไม่ซับซ้อนเกินไป โดยเน้นการใช้ React Query สำหรับ Server State และ React Hook Form สำหรับ Form State
- **Graceful Degradation:** หาก Service รอง (เช่น Search, Notification) ล่ม ระบบหลัก (CRUD) ต้องยังทำงานต่อได้
### 5.13. Secure In-App PDF Viewer (ใหม่)
- 5.13.1 Viewer Capabilities: ระบบต้องมี PDF Viewer ภายในแอปพลิเคชันที่สามารถเปิดดูไฟล์เอกสารหลัก (PDF) ได้ทันทีโดยไม่ต้องดาวน์โหลดลงเครื่อง เพื่อความสะดวกในการตรวจทาน (Review/Approve)
- 5.13.2 Security: การแสดงผลไฟล์ต้อง ห้าม (Disable) การทำ Browser Cache สำหรับไฟล์ Sensitive เพื่อป้องกันการกู้คืนไฟล์จากเครื่อง Client ภายหลัง
- 5.13.3 Performance: ต้องรองรับการส่งข้อมูลแบบ Streaming (Range Requests) เพื่อให้เปิดดูไฟล์ขนาดใหญ่ (เช่น แบบแปลน 50MB+) ได้รวดเร็วโดยไม่ต้องรอโหลดเสร็จทั้งไฟล์
## **🛡️ 6. ข้อกำหนดที่ไม่ใช่ฟังก์ชันการทำงาน (Non-Functional Requirements)**
### **6.1. การบันทึกการกระทำ (Audit Log):** ทุกการกระทำที่สำคัญของผู้ใช้ (สร้าง, แก้ไข, ลบ, ส่ง) จะถูกบันทึกไว้ใน audit_logs เพื่อการตรวจสอบย้อนหลัง
### 6.1. การบันทึกการกระทำ (Audit Log)
- **6.1.1 ขอบเขตการบันทึก Audit Log:**
- ทุกการกระทำที่สำคัญของผู้ใช้ (สร้าง, แก้ไข, ลบ, ส่ง) จะถูกบันทึกไว้ใน audit_logs เพื่อการตรวจสอบย้อนหลัง
- ทุกการสร้าง/แก้ไข/ลบ ข้อมูลสำคัญ (correspondences, RFAs, drawings, users, permissions)
- ทุกการเข้าถึงข้อมูล sensitive (user data, financial information)
- ทุกการเปลี่ยนสถานะ workflow (status transitions)
- ทุกการดาวน์โหลดไฟล์สำคัญ (contract documents, financial reports)
- ทุกการเปลี่ยนแปลง permission และ role assignment
- ทุกการล็อกอินที่สำเร็จและล้มเหลว
- ทุกการส่งคำขอ API ที่สำคัญ
- 6.1.1 ขอบเขตการบันทึก Audit Log:
- **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
- ทุกการสร้าง/แก้ไข/ลบ ข้อมูลสำคัญ (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.3. การค้นหา (Search):**
### **6.4. การทำรายงาน (Reporting):** สามารถจัดทำรายงานสรุปแยกประเภทของ Correspondence ประจำวัน, สัปดาห์, เดือน, และปีได้
- ระบบต้องมีฟังก์ชันการค้นหาขั้นสูง ที่สามารถค้นหาเอกสาร **correspondence**, **rfa**, **shop_drawing**, **contract-drawing**, **transmittal** และ **ใบเวียน (Circulations)** จากหลายเงื่อนไขพร้อมกันได้ เช่น ค้นหาจากชื่อเรื่อง, ประเภท, วันที่, และ Tag
### **6.5. ประสิทธิภาพ (Performance):** มีการใช้ Caching กับข้อมูลที่เรียกใช้บ่อย และใช้ Pagination ในตารางข้อมูลเพื่อจัดการข้อมูลจำนวนมาก
### **6.4. การทำรายงาน (Reporting):**
- **6.5.1 ตัวชี้วัดประสิทธิภาพ:**
- สามารถจัดทำรายงานสรุปแยกประเภทของ Correspondence ประจำวัน, สัปดาห์, เดือน, และปีได้
- **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. ประสิทธิภาพ (Performance):**
- **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)
- มีการใช้ Caching กับข้อมูลที่เรียกใช้บ่อย และใช้ Pagination ในตารางข้อมูลเพื่อจัดการข้อมูลจำนวนมาก
- 6.5.1 ตัวชี้วัดประสิทธิภาพ:
- **API Response Time:** < 200ms (90th percentile) สำหรับ operation ทั่วไป
- **Search Query Performance:** < 500ms สำหรับการค้นหาขั้นสูง
- **File Upload Performance:** < 30 seconds สำหรับไฟล์ขนาด 50MB
- **Concurrent Users:** รองรับผู้ใช้พร้อมกันอย่างน้อย 100 คน
- **Database Connection Pool:** ขนาดเหมาะสมกับ workload (default: min 5, max 20 connections)
- **Cache Hit Ratio:** > 80% สำหรับ cached data
- **Application Startup Time:** < 30 seconds
- 6.5.2 Caching Strategy:
- **Master Data Cache:** Roles, Permissions, Organizations, Project metadata (TTL: 1 hour)
- **User Session Cache:** User permissions และ profile data (TTL: 30 minutes)
- **Search Result Cache:** Frequently searched queries (TTL: 15 minutes)
- **File Metadata Cache:** Attachment metadata (TTL: 1 hour)
- **Document Cache:** Frequently accessed document metadata (TTL: 30 minutes)
- **ต้องมี cache invalidation strategy ที่ชัดเจน:**
- Invalidate on update/delete operations
- Time-based expiration
- Manual cache clearance สำหรับ admin operations
- ใช้ Redis เป็น distributed cache backend
- ต้องมี cache monitoring (hit/miss ratios)
- 6.5.3 Frontend Performance:
- **Bundle Size Optimization:** ต้องควบคุมขนาด Bundle โดยรวมไม่เกิน 2MB
- **State Management Efficiency:** ใช้ State Management Libraries อย่างเหมาะสม ไม่เกิน 2 ตัวหลัก
- **Memory Management:** ต้องป้องกัน Memory Leak จาก State ที่ไม่จำเป็น
### **6.6. ความปลอดภัย (Security):**
- มีระบบ Rate Limiting เพื่อป้องกันการโจมตีแบบ Brute-force
- การจัดการ Secret (เช่น รหัสผ่าน DB, JWT Secret) จะต้องทำผ่าน Environment Variable ของ Docker เพื่อความปลอดภัยสูงสุด
- 6.6.1 Rate Limiting Strategy:
- **Anonymous Endpoints:** 100 requests/hour ต่อ IP address
- **Authenticated Endpoints:**
- Viewer: 500 requests/hour
- Editor: 1000 requests/hour
- Document Control: 2000 requests/hour
- Admin/Superadmin: 5000 requests/hour
- **File Upload Endpoints:** 50 requests/hour ต่อ user
- **Search Endpoints:** 500 requests/hour ต่อ user
- **Authentication Endpoints:** 10 requests/minute ต่อ IP address
- **ต้องมี mechanism สำหรับยกเว้น rate limiting สำหรับ trusted services**
- ต้องบันทึก log เมื่อมีการ trigger rate limiting
- 6.6.2 Error Handling และ Resilience:
- ต้องมี circuit breaker pattern สำหรับ external service calls
- ต้องมี retry mechanism ด้วย exponential backoff
- ต้องมี graceful degradation เมื่อบริการภายนอกล้มเหลว
- Error messages ต้องไม่เปิดเผยข้อมูล sensitive
- 6.6.3 Input Validation:
- ต้องมี input validation ทั้งฝั่ง client และ server (defense in depth)
- ต้องป้องกัน OWASP Top 10 vulnerabilities:
- SQL Injection (ใช้ parameterized queries ผ่าน ORM)
- XSS (input sanitization และ output encoding)
- CSRF (CSRF tokens สำหรับ state-changing operations)
- ต้อง validate file uploads:
- File type (white-list approach)
- File size
- File content (magic number verification)
- ต้อง sanitize user inputs ก่อนแสดงผลใน UI
- ต้องใช้ content security policy (CSP) headers
- ต้องมี request size limits เพื่อป้องกัน DoS attacks
- 6.6.4 Session และ Token Management:
- **JWT token expiration:** 8 hours สำหรับ access token
- **Refresh token expiration:** 7 days
- **Refresh token mechanism:** ต้องรองรับ token rotation และ revocation
- **Token revocation on logout:** ต้องบันทึก revoked tokens จนกว่าจะ expire
- **Concurrent session management:**
- จำกัดจำนวน session พร้อมกันได้ (default: 5 devices)
- ต้องแจ้งเตือนเมื่อมี login จาก device/location ใหม่
- **Device fingerprinting:** สำหรับ security และ audit purposes
- **Password policy:**
- ความยาวขั้นต่ำ: 8 characters
- ต้องมี uppercase, lowercase, number, special character
- ต้องเปลี่ยน password ทุก 90 วัน
- ต้องป้องกันการใช้ password ที่เคยใช้มาแล้ว 5 ครั้งล่าสุด
- **6.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):**
### 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 ขั้นตอนการกู้คืน:**
- 6.7.1 ขั้นตอนการกู้คืน:
- **Database Restoration Procedure:**
- สร้างจาก full backup ล่าสุด
- Apply transaction logs ถึง point-in-time ที่ต้องการ
@@ -586,18 +670,16 @@
- **Recovery Time Objective (RTO):** < 4 ชั่วโมง
- **Recovery Point Objective (RPO):** < 1 ชั่วโมง
### **6.8. กลยุทธ์การแจ้งเตือน (Notification Strategy - ปรับปรุง):**
- **6.8.1 ระบบจะส่งการแจ้งเตือน (ผ่าน Email หรือ Line [cite: 2.7]) เมื่อมีการกระทำที่สำคัญ** ดังนี้:
### 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:**
- 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
@@ -613,19 +695,19 @@
### **6.10. Monitoring และ Observability**
- **6.10.1 Application Monitoring:**
- 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:**
- 6.10.2 Business Metrics
- จำนวน documents created ต่อวัน
- Workflow completion rates
- User activity metrics
- System utilization rates
- Search query performance
- **6.10.3 Security Monitoring:**
- 6.10.3 Security Monitoring
- Failed login attempts
- Rate limiting triggers
- Virus scan results
@@ -634,63 +716,70 @@
### **6.11 JSON Processing & Validation**
- **6.11.1 JSON Schema Management**
- 6.11.1 JSON Schema Management
- ต้องมี centralized JSON schema registry
- ต้องรองรับ schema versioning และ migration
- ต้องมี schema validation during runtime
- **6.11.2 Performance Optimization**
- 6.11.2 Performance Optimization
- **Caching:** Cache parsed JSON structures
- **Compression:** ใช้ compression สำหรับ JSON ขนาดใหญ่
- **Indexing:** Support JSON path indexing สำหรับ query
- **6.11.3 Error Handling**
- 6.11.3 Error Handling
- ต้องมี graceful degradation เมื่อ JSON validation ล้มเหลว
- ต้องมี default fallback values
- ต้องบันทึก error logs สำหรับ validation failures
## **🧪 7. ข้อกำหนดด้านการทดสอบ (Testing Requirements)**
### **7.1. Unit Testing:**
### 7.1 Unit Testing
- ต้องมี unit tests สำหรับ business logic ทั้งหมด
- Code coverage อย่างน้อย 70% สำหรับ backend services
- Business Logic: 80%+
- Controllers: 70%+
- Utilities: 90%+
- ต้องทดสอบ RBAC permission logic ทุกระดับ
### **7.2. Integration Testing:**
### 7.2 Integration Testing
- ทดสอบการทำงานร่วมกันของ modules
- ทดสอบ database migrations และ data integrity
- ทดสอบ API endpoints ด้วย realistic data
### **7.3. End-to-End Testing:**
### 7.3 End-to-End Testing
- ทดสอบ complete user workflows
- ทดสอบ document lifecycle จาก creation ถึง archival
- ทดสอบ cross-module integrations
### **7.4. Security Testing:**
### 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
- 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:**
### 7.5. Performance Testing
- **Load Testing:** ทดสอบด้วย realistic workloads
- **Stress Testing:** หา breaking points ของระบบ
- **Endurance Testing:** ทดสอบการทำงานต่อเนื่องเป็นเวลานาน
- Penetration Testing: ทดสอบ OWASP Top 10 vulnerabilities
- Security Audit: Review code สำหรับ security flaws
- Virus Scanning Test: ทดสอบ file upload security
- **Rate Limiting Test:** ทดสอบ rate limiting functionality
- **Load Testing:** ทดสอบด้วย realistic workloads
- **Stress Testing:** หา breaking points ของระบบ
- **Endurance Testing:** ทดสอบการทำงานต่อเนื่องเป็นเวลานาน
### **7.6. Disaster Recovery Testing:**
### 7.6. Disaster Recovery Testing
- ทดสอบ backup และ restoration procedures
- ทดสอบ failover mechanisms
- ทดสอบ data integrity หลังการ recovery
### **7.7 Specific Scenario Testing (เพิ่ม)**
### 7.7 Specific Scenario Testing (เพิ่ม)
- **Race Condition Test:** ทดสอบยิง Request ขอเลขที่เอกสารพร้อมกัน 100 Request
- **Transaction Test:** ทดสอบปิดเน็ตระหว่าง Upload ไฟล์ (ตรวจสอบว่าไม่มี Orphan File หรือ Broken Link)
- **Permission Test:** ทดสอบ CASL Integration ทั้งฝั่ง Backend และ Frontend ให้ตรงกัน
- **Transaction Test:** ทดสอบปิดเน็ตระหว่าง Upload ไฟล์ (ตรวจสอบว่าไม่มี Orphan File หรือ Broken Link)
- **Permission Test:** ทดสอบ CASL Integration ทั้งฝั่ง Backend และ Frontend ให้ตรงกัน
## **8. ข้อกำหนดด้านการบำรุงรักษา (Maintenance Requirements)**
@@ -738,66 +827,16 @@
- ต้องมี 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
- **Document:** Application Requirements Specification v1.4.5
- **Version:** 1.4
- **Date:** 2025-11-26
- **Date:** 2025-11-29
- **Author:** NAP LCBP3-DMS & Gemini
- **Status:** FINAL-Rev.04
- **Status:** FINAL-Rev.05
- **Classification:** Internal Technical Documentation
- **Approved By:** Nattanin
---
`End of Requirements Specification v1.4.4`
`End of Requirements Specification v1.4.5`

377
docs/1.bak
View File

@@ -1,377 +0,0 @@
ผมได้ตรวจสอบไฟล์ `FullStackJS_Guidelines01.md` และ `01_lcbp3_v1_1_0.sql` ของคุณแล้ว และได้อัปเดตไฟล์ Guidelines (Markdown) ให้สอดคล้องกับโครงสร้างฐานข้อมูล (SQL) ที่คุณกำหนดไว้อย่างสมบูรณ์ครับ
การเปลี่ยนแปลงที่สำคัญคือ:
1. **การจัดการ UI (UI Conflict):** แก้ไขความขัดแย้งในไฟล์เดิมที่ระบุทั้ง **Tailwind/Shadcn** และ **Bootstrap** ผมได้รวมศูนย์การพัฒนา UI ไปที่ **Tailwind/Shadcn** ตามที่ระบุไว้ในโปรไฟล์นักพัฒนา (Frontend Developer Profile) และลบส่วนของ Bootstrap ที่ซ้ำซ้อนออกไป
2. **DMS-Specific Conventions:** อัปเดตส่วนนี้ทั้งหมดเพื่อให้ตรงกับสคีม SQL ของคุณ
* เปลี่ยนชื่อโปรเจกต์อ้างอิงเป็น **LCBP3-DMS**
* ปรับปรุงแผนผัง **Domain Modules** ให้สะท้อนโครงสร้างจริง (เช่น `correspondences` เป็นศูนย์กลาง, เพิ่ม `circulations`)
* อัปเดตตาราง **AuditLog** ให้ตรงกับฟิลด์ใน SQL (เช่น เพิ่ม `entity_type`, `details_json`, `ip_address`)
* อัปเดตตัวอย่าง **RBAC Permissions** ให้ตรงกับสิทธิ์ที่มีในตาราง `permissions` ของคุณ
* ชี้แจง
เรื่อง **File Handling** ว่าตาราง `attachments` จะเชื่อมโยงผ่าน `correspondence_id`
* อัปเดตส่วน **Reporting** เพื่ออ้างอิงถึง `VIEWS` (เช่น `v_current_rfas`) ที่คุณได้สร้างไว้ใน SQL
* ย้ายส่วน **"Recommended Enhancements"** (เช่น soft delete, indexes) ที่มีอยู่แล้วใน SQL ไปยังส่วนใหม่ชื่อ **"Implemented Standards"** เพื่อสะท้อนว่างานส่วนนี้เสร็จแล้ว
นี่คือไฟล์ `FullStackJS_Guidelines01.md` ฉบับที่อัปเดตแล้วครับ:
-----
# FullStackJS Development Guidelines
## 🧠 General Philosophy
Unified best practices for **NestJS Backend**, **NextJS Frontend**, and **Tailwind-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 → Repository (Model) structure.
- DTOs validated with **class-validator**.
- Use **MikroORM** (or TypeORM/Prisma) for persistence, aligning with the MariaDB schema.
- 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 / UI)
### 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 (or `clsx` utility) over ternary operators in class strings.
- 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 (`sm:`, `md:`, `lg:`).
- Maintain visual hierarchy with typography and spacing.
- Use **Shadcn** components (Button, Input, Card, etc.) for consistent UI.
- Keep components small and focused.
- Use utility classes for quick styling (spacing, colors, text, etc.).
- Ensure **ARIA compliance** and semantic markup.
### Form Validation & Errors
- Use client-side libraries like `zod` and `react-hook-form`.
- Show errors with **alert components** or inline messages.
- Include labels, placeholders, and feedback messages.
-----
# 🔗 Full Stack Integration Guidelines
| Aspect | Backend (NestJS) | Frontend (NextJS) | UI Layer (Tailwind/Shadcn) |
|:--|:--|:--|:--|
| API | REST / GraphQL Controllers | API hooks via fetch/axios/SWR | Components consuming data |
| Validation | `class-validator` DTOs | `zod` / `react-hook-form` | Shadcn form/input states |
| Auth | Guards, JWT | NextAuth / cookies | Auth UI states (loading, signed in) |
| Errors | Global filters | Toasts / modals | Alerts / feedback text |
| Testing | Jest (unit/e2e) | Vitest / Playwright | Visual regression |
| Styles | Scoped modules (if needed) | Tailwind / Shadcn | Tailwind utilities |
| Accessibility | Guards + filters | ARIA attributes | Semantic HTML |
-----
# 🗂️ DMS-Specific Conventions (LCBP3-DMS)
This section extends the general FullStackJS guidelines for the **LCBP3-DMS** project, focusing on document approval workflows (Correspondence, RFA, Drawing, Contract, Transmittal, Circulation).
## 🧱 Backend Domain Modules
Use a modular domain structure reflecting the SQL schema. `correspondences` should act as the central hub.
```
src/
├─ modules/
│ ├─ correspondences/ (Core: Master documents, Revisions, Attachments)
│ ├─ rfas/ (RFA logic, Revisions, Workflows, Items)
│ ├─ drawings/ (ShopDrawings, ContractDrawings, Categories)
│ ├─ circulations/ (Internal circulation, Templates, Assignees)
│ ├─ transmittals/ (Transmittal logic, Items)
│ ├─ projects-contracts/ (Projects, Contracts, Organizations, Parties)
│ ├─ users-auth/ (Users, Roles, Permissions, Auth)
│ ├─ audit-log/
│ └─ common/
```
### Naming Convention
| Entity | Example (from 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 & Permission Control
Use decorators to enforce access rights, referencing permissions from the `permissions` table.
```ts
@RequirePermission('rfas.respond') // Must match a 'permission_code'
@Put(':id')
updateRFA(@Param('id') id: string) {
return this.rfaService.update(id);
}
```
### Roles
- **SUPER\_ADMIN**: Full system access (from `roles` table).
- **ADMIN**: Organization-level access.
- **EDITOR**: Module-specific write access.
- **VIEWER**: Read-only access.
### Example Permissions (from `permissions` table)
- `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`
Seed mapping between roles and permissions via seeder scripts (as seen in SQL file).
-----
## 🧾 AuditLog Standard
Log all CRUD and mapping operations to the `audit_logs` table.
| Field | Type (from SQL) | Description |
|:--|:--|:--|
| `audit_id` | `BIGINT` | Primary Key |
| `user_id` | `INT` | User performing the action (FK -\> users) |
| `action` | `VARCHAR(100)` | `rfa.create`, `correspondence.update`, `login.success` |
| `entity_type`| `VARCHAR(50)` | Table/module name, e.g., 'rfa', 'correspondence' |
| `entity_id` | `VARCHAR(50)` | Primary ID of the affected record |
| `details_json`| `JSON` | Contextual data (e.g., changed fields) |
| `ip_address` | `VARCHAR(45)` | Actor's IP address |
| `user_agent` | `VARCHAR(255)`| Actor's User Agent |
| `created_at` | `TIMESTAMP` | UTC timestamp |
Example implementation:
```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
- Centralize all uploads via the `attachments` table.
- Upload path (convention): `/storage/{year}/{month}/`
- Stored filename: Use `stored_filename` (e.g., UUID or hash) to prevent conflicts. `original_filename` is for display.
- Allowed types: `pdf, dwg, docx, xlsx, zip`
- Max size: **50 MB**
- Store outside webroot.
- Serve via secure endpoint `/files/:attachment_id/download`.
### Access Control
File access is not direct. The `/files/:attachment_id/download` endpoint must:
1. Find the `attachment` record.
2. Get its `correspondence_id`.
3. Verify the user has permission to view that specific `correspondence` (or its related RFA, Transmittal, etc.).
-----
## 📊 Reporting & Exports
### Reporting Views (from SQL)
Reports should be built primarily from the pre-defined database Views:
- `v_current_correspondences`: For all current non-RFA document revisions.
- `v_current_rfas`: For all current RFA revisions and their master data.
- `v_contract_parties_all`: For auditing project/contract/organization relationships.
These views serve as the primary source for server-side reporting and data exports.
### 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&sort=...&filter=...`
- Must support: pagination, sorting, search, filters.
- Always display latest revision inline (for RFA/Drawing).
### Form Standards
- Dependent dropdowns must be implemented (as supported by schema):
- Project → Contract Drawing Volumes
- Contract Drawing Category → Sub-Category
- RFA (Shop Drawing type) → Linkable Shop Drawing Revisions
- File upload: preview + validation (via `attachments` logic).
- Submit via API with toast feedback.
-----
## 🧭 Dashboard & Activity Feed
### Dashboard Cards
- Show latest Correspondences, RFAs, Circulations.
- Include KPI summaries (e.g., "RFAs Pending Approval").
- Include quick links to modules.
### Activity Feed
- Display recent `audit_logs` actions (10 latest) relevant to the user.
<!-- end list -->
```ts
// Example API response
[
{ user: 'editor01', action: 'Updated RFA (LCBP3C1-RFA-001)', time: '2025-11-04T09:30Z' }
]
```
-----
## ✅ Implemented Standards (from SQL v1.1.0)
This section confirms that the following best practices are already part of the database design and should be leveraged, not re-implemented.
- ✅ **Soft Delete:** Implemented via `deleted_at` columns on key tables (e.g., `correspondences`, `rfas`, `project_parties`). Logic must filter for `deleted_at IS NULL`.
- ✅ **Database Indexes:** The schema is heavily indexed on foreign keys and common query columns (e.g., `idx_rr_rfa`, `idx_cor_project`, `idx_cr_is_current`) for performance.
- ✅ **RBAC Structure:** A comprehensive `users`, `roles`, `permissions`, `user_roles`, and `user_project_roles` system is in place.
- ✅ **Data Seeding:** Master data (roles, permissions, organization\_roles, initial users, project parties) is included in the schema script.
## 🧩 Recommended Enhancements (Future)
- ✅ Implement Fulltext search on fields like `correspondence_revisions.title` or `details`.
- ✅ Create a background job (using **n8n** as noted in SQL comments) for RFA deadline reminders based on `due_date`.
- ✅ Add a periodic cleanup job for `attachments` that are not linked to any `correspondence_id` (orphaned files).
-----

1112
docs/Markdown/1_FullStackJS_V1_4_4.md → docs/1_FullStackJS_V1_4_5.md
View File

File diff suppressed because it is too large Load Diff

0
docs/Markdown/2_Backend_Plan_V1_4_4.Phase6A.md → docs/2_Backend_Plan_V1_4_4.Phase6A.md
View File

0
docs/Markdown/2_Backend_Plan_V1_4_4.Phase_Addition.md → docs/2_Backend_Plan_V1_4_4.Phase_Addition.md
View File

101
docs/Markdown/2_Backend_Plan_V1_4_4.md → docs/2_Backend_Plan_V1_4_5.md
View File

@@ -1,10 +1,9 @@
# 📋 **แผนการพัฒนา Backend (NestJS) - LCBP3-DMS v1.4.4 (ฉบับปรับปรุง)**
# 📋 **แผนการพัฒนา Backend (NestJS) - LCBP3-DMS v1.4.5 (ฉบับปรับปรุง)**
**สถานะ:** FINAL GUIDELINE Rev.04
**วันที่:** 2025-11-26
**อ้างอิง:** Requirements v1.4.3 & FullStackJS Guidelines v1.4.3
**สถานะ:** FINAL GUIDELINE Rev.05
**วันที่:** 2025-11-29
**อ้างอิง:** Requirements v1.4.5 & FullStackJS Guidelines v1.4.5
**Classification:** Internal Technical Documentation
**การแก้ไข:** เพิ่ม T2.5.1-T2.5.9, T3.1.1-T3.1.8,
---
@@ -117,9 +116,7 @@
│ │ ├── maintenance-mode.guard.ts
│ │ └── rbac.guard.ts
│ ├── 📁idempotency
│ │ ├── idempotency.interceptor.ts
│ │ └── performance.interceptor.ts
│ ├── 📁interceptors
│ │ ├── 📁interceptors
│ │ ├── audit-log.interceptor.ts
│ │ ├── idempotency.interceptor.ts
│ │ ├── performance.interceptor.ts
@@ -127,14 +124,15 @@
│ ├── 📁maintenance
│ ├── 📁resilience
│ │ └── resilience.module.ts
│ └── 📁security
│ ├── 📁services
│ │ ├── crypto.service.ts
│ │ └── request-context.service.ts
│ └── common.module.ts
│ ├── 📁security
│ ├── 📁services
│ │ ├── crypto.service.ts
│ │ └── request-context.service.ts
│ └── common.module.ts
├── 📁database
│ ├── 📁migrations
│ └── 📁seeds
│ ├── run-seed.ts
│ └── workflow-definitions.seed.ts
└── 📁modules
├── 📁circulation
@@ -146,6 +144,7 @@
│ │ ├── circulation-routing.entity.ts
│ │ ├── circulation-status-code.entity.ts
│ │ └── circulation.entity.ts
│ ├── circulation-workflow.service.ts
│ ├── circulation.controller.ts
│ ├── circulation.module.ts
│ └── circulation.service.ts
@@ -153,6 +152,7 @@
│ ├── 📁dto
│ │ ├── add-reference.dto.ts
│ │ ├── create-correspondence.dto.ts
│ │ ├── create-routing-template.dto.ts
│ │ ├── search-correspondence.dto.ts
│ │ ├── submit-correspondence.dto.ts
│ │ └── workflow-action.dto.ts
@@ -166,6 +166,7 @@
│ │ ├── correspondence.entity.ts
│ │ ├── routing-template-step.entity.ts
│ │ └── routing-template.entity.ts
│ ├── correspondence-workflow.service.ts
│ ├── correspondence.controller.spec.ts
│ ├── correspondence.controller.ts
│ ├── correspondence.module.ts
@@ -206,10 +207,19 @@
├── 📁json-schema
│ ├── 📁dto
│ │ ├── create-json-schema.dto.ts
│ │ ├── migrate-data.dto.ts
│ │ ├── search-json-schema.dto.ts
│ │ └── update-json-schema.dto.ts
│ ├── 📁entities
│ │ └── json-schema.entity.ts
│ ├── 📁interfaces
│ │ ├── ui-schema.interface.ts
│ │ └── validation-result.interface.ts
│ ├── 📁services
│ │ ├── json-security.service.ts
│ │ ├── schema-migration.service.ts
│ │ ├── ui-schema.service.ts
│ │ └── virtual-column.service.ts
│ ├── json-schema.controller.spec.ts
│ ├── json-schema.controller.ts
│ ├── json-schema.module.ts
@@ -271,8 +281,11 @@
│ └── project.service.ts
├── 📁rfa
│ ├── 📁dto
│ │ ├── create-rfa-revision.dto.ts
│ │ ├── create-rfa-workflow.dto.ts
│ │ ├── create-rfa.dto.ts
│ │ ├── search-rfa.dto.ts
│ │ ├── submit-rfa.dto.ts
│ │ └── update-rfa.dto.ts
│ ├── 📁entities
│ │ ├── rfa-approve-code.entity.ts
@@ -284,6 +297,7 @@
│ │ ├── rfa-workflow-template.entity.ts
│ │ ├── rfa-workflow.entity.ts
│ │ └── rfa.entity.ts
│ ├── rfa-workflow.service.ts
│ ├── rfa.controller.ts
│ ├── rfa.module.ts
│ └── rfa.service.ts
@@ -327,16 +341,22 @@
│ ├── create-workflow-definition.dto.ts
│ ├── evaluate-workflow.dto.ts
│ ├── get-available-actions.dto.ts
│ └── update-workflow-definition.dto.ts
│ ├── update-workflow-definition.dto.ts
│ └── workflow-transition.dto.ts
├── 📁entities
│ └── workflow-definition.entity.ts
├── 📁interfaces
│ ├── workflow-definition.entity.ts
│ ├── workflow-history.entity.ts
│ └── workflow-instance.entity.ts
├── 📁interfaces
│ └── workflow.interface.ts
├── workflow-dsl.service.ts
├── workflow-engine.controller.ts
├── workflow-engine.module.ts
├── workflow-engine.service.spec.ts
└── workflow-engine.service.ts
├── workflow-engine.service.ts
└── workflow-event.service.ts
```
@@ -1766,10 +1786,10 @@ export class WorkflowEngineController {
}
```
- **[ ] T3.1.8 Integration with Existing Modules**
- [ ] Correspondence Module Integration
- [ ] RFA Module Integration
- [ ] Circulation Module Integration
- **[ ] T3.1.8 Integration (Clean Migration)**
- [ ] Correspondence: เชื่อมต่อ CorrespondenceWorkflowService
- [ ] RFA: เชื่อมต่อ RfaWorkflowService กับ Engine (ลบ Code เก่าที่ใช้ตาราง rfa_workflows)
- [ ] Circulation: เชื่อมต่อ CirculationWorkflowService กับ Engine (ลบ Code เก่าที่ใช้ตาราง circulation_routings)
- [ ] Notification Module Integration
```typescript
@@ -1809,7 +1829,12 @@ export class CorrespondenceWorkflowService {
}
```
- **[ ] T3.1.9 Testing Strategy**
- [ ] **T3.1.9 Cleanup Legacy Code:**
- [ ] ลบ Entity/Repository ของตารางเก่า (_\_routings, _\_templates) ออกจาก Codebase
- [ ] อัปเดต SQL Migration ให้ Drop ตารางเก่าทิ้ง
- [ ] **T3.1.10 Testing Strategy**
- [ ] Unit Tests สำหรับ DSL parser และ state machine
- [ ] Integration Tests สำหรับ end-to-end workflow execution
- [ ] Performance Tests สำหรับ high-concurrency scenarios
@@ -1919,16 +1944,6 @@ describe('WorkflowEngineService', () => {
- [ ] **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)**
@@ -1937,6 +1952,16 @@ describe('WorkflowEngineService', () => {
### **Phase 5: Tasks**
- **[ ] T5.1 RfaModule with Unified Workflow**
- [ ] สร้าง Entities (Rfa, RfaRevision, RfaItem)
- [ ] สร้าง 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
- **[ ] T5.2 CirculationModule - Internal Routing**
- [ ] สร้าง Entities (Circulation, Template, Routing, Attachment)
@@ -2099,22 +2124,14 @@ describe('WorkflowEngineService', () => {
## **Document Control:**
- **Document:** Backend Development Plan v1.4.4
- **Document:** Backend Development Plan v1.4.5
- **Version:** 1.4
- **Date:** 2025-11-28
- **Date:** 2025-11-29
- **Author:** NAP LCBP3-DMS & Gemini
- **Status:** FINAL-Rev.04
- **Status:** FINAL-Rev.05
- **Classification:** Internal Technical Documentation
- **Approved By:** Nattanin
---
`End of Backend Development Plan v1.4.4`
```
```
```
```
`End of Backend Development Plan v1.4.5`

16
docs/Markdown/3_Frontend_Plan_V1_4_4.md → docs/3_Frontend_Plan_V1_4_5.md
View File

@@ -1,8 +1,8 @@
# 📋 **แผนการพัฒนา Frontend (Next.js) - LCBP3-DMS v1.4.4**
# 📋 **แผนการพัฒนา Frontend (Next.js) - LCBP3-DMS v1.4.5**
**สถานะ:** FINAL GUIDELINE Rev.04
**วันที่:** 2025-11-26
**อ้างอิง:** Requirements v1.4.3 & FullStackJS Guidelines v1.4.3
**สถานะ:** FINAL GUIDELINE Rev.05
**วันที่:** 2025-11-29
**อ้างอิง:** Requirements v1.4.5 & FullStackJS Guidelines v1.4.5
**Classification:** Internal Technical Documentation
## 🎯 **ภาพรวมโครงการ**
@@ -965,14 +965,14 @@
## **Document Control:**
- **Document:** Frontend Development Plan v1.4.3
- **Document:** Frontend Development Plan v1.4.5
- **Version:** 1.4
- **Date:** 2025-11-26
- **Date:** 2025-11-29
- **Author:** NAP LCBP3-DMS & Gemini
- **Status:** FINAL-Rev.04
- **Status:** FINAL-Rev.05
- **Classification:** Internal Technical Documentation
- **Approved By:** Nattanin
---
`End of Frontend Development Plan v1.4.4 (ฉบับปรับปรุง)`
`End of Frontend Development Plan v1.4.5`

366
docs/Markdown/4_Data_Dictionary_V1_4_4.md → docs/4_Data_Dictionary_V1_4_5.md
View File

@@ -1,10 +1,10 @@
# **ตารางฐานข้อมูล (Data Dictionary) - LCBP3-DMS (V1.4.4)**
# **ตารางฐานข้อมูล (Data Dictionary) - LCBP3-DMS (V1.4.5)**
เอกสารนี้สรุปโครงสร้างตาราง, Foreign Keys (FK), และ Constraints ที่สำคัญทั้งหมดในฐานข้อมูล LCBP3-DMS (v1.4) เพื่อใช้เป็นเอกสารอ้างอิงสำหรับทีมพัฒนา Backend (NestJS) และ Frontend (Next.js) โดยอิงจาก Requirements และ SQL Script ล่าสุด [GEMINI]
**สถานะ:** FINAL GUIDELINE
**วันที่:** 2025-11-26
**อ้างอิง:** Requirements v1.4.4 & FullStackJS Guidelines v1.4.4
**วันที่:** 2025-11-29
**อ้างอิง:** Requirements v1.4.5 & FullStackJS Guidelines v1.4.5
**Classification:** Internal Technical Documentation
## 📝 สรุปรายการปรับปรุง (Summary of Changes)
@@ -638,119 +638,6 @@
- Allows tracing document relationships
- Bi-directional references should be created as separate records
### 3.9 ตาราง correspondence_routing_templates
**Purpose**: เก็บข้อมูลแม่แบบ (Template) ของสายงานการส่งต่อเอกสารเพื่อขออนุมัติ ทำให้ไม่ต้องกำหนดขั้นตอนซ้ำทุกครั้ง สามารถสร้างเป็นแม่แบบทั่วไป หรือเฉพาะสำหรับโครงการใดโครงการหนึ่งได้
| Column Name | Data Type | Constraints | Description |
| --------------- | ------------ | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| id | INT | PRIMARY KEY, AUTO_INCREMENT | ID หลัก (Primary Key) ของแม่แบบ รันค่าอัตโนมัติ |
| template_name | VARCHAR(255) | NOT NULL | ชื่อของแม่แบบ เช่น "เสนอโครงการ", "ขออนุมัติจัดซื้อ" |
| description | TEXT | NULL | คำอธิบายรายละเอียดเกี่ยวกับแม่แบบนี้ |
| project_id | INT | NULL | ID ของโครงการที่แม่แบบนี้สังกัดอยู่ (ถ้ามี) **ค่า NULL หมายถึง** เป็น "แม่แบบทั่วไป" ที่สามารถใช้กับทุกโครงการได้ |
| created_at | TIMESTAMP | NOT NULL, DEFAULT CURRENT_TIMESTAMP | วันที่และเวลาที่สร้างแม่แบบนี้ |
| updated_at | TIMESTAMP | NOT NULL,`DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP | วันที่และเวลาที่แก้ไขข้อมูลในแม่แบบนี้ล่าสุด |
| is_active | BOOLEAN | DEFAULT TRUE | สถานะใช้งาน |
| workflow_config | JSON | NULL | เก็บ State Machine Configuration หรือ Rules เพิ่มเติมที่ซับซ้อนกว่า Column ปกติ |
**Indexes**:
- ux_routing_template_name_project (template_name, project_id): ดัชนีแบบ UNIQUE ป้องกันการมีชื่อแม่แบบซ้ำกันในแต่ละโครงการ หรือในส่วนของแม่แบบทั่วไป (ที่ project_id เป็น NULL)
**ความสัมพันธ์ Foreign Key:**
- fk_crt_project: อ้างอิงไปยัง projects(id)
- ON DELETE CASCAD`: ถ้าโครงการ (projects) ถูกลบ แม่แบบที่เกี่ยวข้องกับโครงการนั้นๆ จะถูกลบไปด้วยทั้งหมด
---
### 3.10 ตาราง correspondence_routing_template_steps
**Purpose**: เก็บรายละเอียดของแต่ละขั้นตอน (Steps) ภายในแม่แบบสายงาน (correspondence_routing_templates) กำหนดว่าจะส่งไปที่องค์กรไหน ลำดับเป็นเท่าไร และเพื่อวัตถุประสงค์อะไร
| Column Name | Data Type | Constraints | Description |
| :----------------- | --------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | INT | PRIMARY KEY, AUTO_INCREMENT | ID หลักของขั้นตอน |
| template_id | INT | NOT NULL | ID ของแม่แบบที่ขั้นตอนนี้สังกัดอยู่ |
| sequence | INT | NOT NULL | ลำดับของขั้นตอน (1, 2, 3, ...) |
| to_organization_id | INT | NOT NULL | ID ขององค์กรที่เป็นผู้รับในขั้นตอนนี้ |
| step_purpose | ENUM | NOT NULL,DEFAULT FOR_REVIEW | วัตถุประสงค์ของการส่งต่อในขั้นตอนนี้ **ค่าที่เป็นไปได้:** [FOR_APPROVAL: เพื่ออนุมัติ, FOR_REVIEW: เพื่อตรวจสอบ/พิจารณา, FOR_INFORMATION: เพื่อทราบ] |
| expected_days | INT | NULL | วันที่คาดหวัง |
**Indexes**:
- ux_cor_template_sequence (template_id, sequence): ดัชนีแบบ UNIQUE ป้องกันการมีลำดับขั้นตอนซ้ำกันภายในแม่แบบเดียวกัน
**ความสัมพันธ์ Foreign Key:**
- fk_cwts_template: อ้างอิงไปยัง correspondence_routing_templates(id)
- ON DELETE CASCADE: ถ้าแม่แบบถูกลบ ขั้นตอนทั้งหมดภายในแม่แบบนั้นจะถูกลบไปด้วย
- fk_cwts_org: อ้างอิงไปยัง organizations(id)
- ON DELETE CASCADE: ถ้าองค์กรถูกลบ ขั้นตอนที่ชี้ไปยังองค์กรนั้นจะถูกลบ
---
### 3.11 ตาราง correspondence_routings
**Purpose**: เป็นตารางที่เก็บข้อมูลการส่งต่อเอกสารจริง (Instance/Run-time) ติดตามประวัติการเคลื่อนย้ายของแต่ละเอกสาร ว่าผ่านใครมาบ้าง อยู่ที่ใคร และสถานะปัจจุบันคืออะไร
| Column Name | Data Type | Constraints | Description |
| -------------------- | --------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| id | INT | PRIMARY KEY, AUTO_INCREMENT | ID หลักของรายการส่งต่อ |
| correspondence_id | INT | NOT NUL | ID ของเอกสาร (FK ไปยัง correspondence_revisions) |
| template_id | INT | NULL | ID ของแม่แบบที่ใช้สร้างสายงานนี้ (เก็บไว้เป็นข้อมูลอ้างอิง) |
| sequence | INT | NOT NULL | ลำดับของขั้นตอนการส่งต่อจริง |
| from_organization_id | INT | NOT NULL | ID ขององค์กรผู้ส่ง |
| to_organization_id | INT | NOT NULL | ID ขององค์กรผู้รับ |
| step_purpose | ENUM | NOT NULL, DEFAULT FOR_REVIEW | วัตถุประสงค์ของการส่งต่อในขั้นตอนนี้จริง **ค่าที่เป็นไปได้:** [FOR_APPROVAL: เพื่ออนุมัติ, FOR_REVIEW: เพื่อตรวจสอบ/พิจารณา, FOR_INFORMATION: เพื่อทราบ, FOR_ACTION: เพื่อดำเนินการ] |
| status | ENUM | NOT NULL, DEFAULT SENT | [ACTIONED: ดำเนินการแล้ว, FORWARDED: ส่งต่อแล้ว, REPLIE: ตอบกลับแล้ว] |
| comments | TEXT | NULL | หมายเหตุหรือความคิดเห็นในการส่งต่อ |
| due_date | DATETIME | NULL | วันที่ครบกำหนดที่ต้องดำเนินการในขั้นตอนนี้ |
| processed_by_user_id | INT | NULL | ID ของผู้ใช้ที่ดำเนินการในขั้นตอนนี้จริงๆ |
| processed_at | TIMESTAMP | NULL | เวลาที่ผู้ใช้ดำเนินการเสร็จสิ้น |
| created_at | TIMESTAMP | NOT NULL, DEFAULT CURRENT_TIMESTAMP | เวลาที่สร้างรายการส่งต่อนี้ |
| state_context | JSON | NULL | Snapshot ของตัวแปรต่างๆ ใน Workflow ณ จุดนี้ (เช่น ผู้อนุมัติ, เงื่อนไขที่ผ่าน) |
**Indexes**:
- ux_cor_routing_sequence (correspondence_id, sequence): ดัชนีแบบ UNIQUE ทำให้มั่นใจได้ว่าแต่ละเอกสารจะมีขั้นตอนการส่งต่อตามลำดับได้เพียงชุดเดียว
**ความสัมพันธ์ Foreign Key:**
- fk_crs_correspondence: อ้างอิงไปยัง correspondence_revisions(correspondence_id)
- ON DELETE CASCADE`: ถ้าเอกสาร (revision) ถูกลบ ประวัติการส่งต่อทั้งหมดจะถูกลบไปด้วย
- fk_crs_template: อ้างอิงไปยัง correspondence_routing_templates(id)
- ON DELETE SET NULL: ถ้าแม่แบบถูกลบ ค่า template_id ในตารางนี้จะถูกเปลี่ยนเป็น NULL เพื่อรักษาประวัติการส่งต่อไว้
- fk_crs_from_org: อ้างอิงไปยัง organizations(id)
- ON DELETE CASCADE: ถ้าองค์กรผู้ส่งถูกลบ รายการส่งต่อนี้จะถูกลบ
- fk_crs_to_org: อ้างอิงไปยัง organizations(id)
- ON DELETE CASCADE: ถ้าองค์กรผู้รับถูกลบ รายการส่งต่อนี้จะถูกลบ
- fk_crs_processed_by_user: อ้างอิงไปยัง users(user_id)
- ON DELETE SET NULL: ถ้าผู้ใช้ถูกลบ ค่า processed_by_user_id จะถูกเปลี่ยนเป็น NULL เพื่อรักษาประวัติการดำเนินการไว้
---
### 3.12 ตาราง correspondence_status_transitions
**Purpose**: ตารางนี้ใช้กำหนดกฎ (State Machine) ว่าสถานะใดสามารถเปลี่ยนไปเป็นสถานะใดได้บ้าง โดยขึ้นอยู่กับประเภทของหนังสือ เพื่อควบคุมการไหลของสถานะให้ถูกต้องตามข้อบังคับ
| Column Name | Data Type | Constraints | Description |
| -------------- | --------- | ----------- | ------------------------------------------------------ |
| type_id | INT | PRIMARY KEY | ID ของประเภทหนังสือ (เช่น หนังสือภายใน, หนังสือภายนอก) |
| from_status_id | INT | PRIMARY KEY | ID ของสถานะต้นทาง (เช่น ร่าง) |
| to_status_id | INT | PRIMARY KEY | ID ของสถานะปลายทาง (เช่น รออนุมัติ) |
**คีย์หลัก (Primary Key):**
- (type_id, from_status_id, to_status_id)`: คีย์หลักแบบประกอบ ทำให้แน่ใจว่าแต่ละประเภทหนังสือ การเปลี่ยนจากสถานะหนึ่งไปอีกสถานะหนึ่งจะซ้ำกันไม่ได้
**ความสัมพันธ์ Foreign Key:**
- fk_cst_type : อ้างอิงไปยัง correspondence_types(id)
- fk_cst_from : อ้างอิงไปยัง correspondence_status(id)
- fk_cst_to : อ้างอิงไปยัง correspondence_status(id)
- ไม่มีการกำหนด ON DELETE จึงเป็นค่าเริ่มต้น RESTRICT หมายความว่า จะลบประเภทหนังสือหรือสถานะไม่ได้ ถ้ายังมีการใช้งานอยู่ในตารางนี้
---
## **4. 📐 approval: RFA Tables (เอกสารขออนุมัติ, Workflows)**
@@ -974,75 +861,6 @@
---
### 4.7 rfa_workflow_templates
**Purpose**: Master table for RFA approval workflow templates
| Column Name | Data Type | Constraints | Description |
| --------------- | ------------ | ----------------------------------- | ------------------------------------------------------------------------------- |
| id | INT | PRIMARY KEY, AUTO_INCREMENT | Unique template ID |
| template_name | VARCHAR(100) | NOT NULL | Template name |
| description | TEXT | NULL | Template description |
| is_active | TINYINT(1) | DEFAULT 1 | Active status |
| created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | Record creation timestamp |
| updated_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP ON UPDATE | Last update timestamp |
| workflow_config | JSON | NULL | เก็บ State Machine Configuration หรือ Rules เพิ่มเติมที่ซับซ้อนกว่า Column ปกติ |
**Indexes**:
- PRIMARY KEY (id)
- INDEX (is_active)
- INDEX (template_name)
**Relationships**:
- Children: rfa_workflow_template_steps
**Business Rules**:
- Defines reusable approval workflows for RFAs
- Can be assigned to specific RFA types or organizations
---
### 4.8 rfa_workflow_template_steps
**Purpose**: Child table defining steps in workflow templates
| Column Name | Data Type | Constraints | Description |
| --------------- | --------- | --------------------------- | ----------------------------------------- |
| id | INT | PRIMARY KEY, AUTO_INCREMENT | Unique step ID |
| template_id | INT | NOT NULL, FK | Reference to workflow template |
| step_number | INT | NOT NULL | Step sequence order |
| organization_id | INT | NOT NULL, FK | Organization responsible for step |
| role_id | INT | NULL, FK | Required role for this step |
| action_type | ENUM | NULL | Action type: REVIEW, APPROVE, ACKNOWLEDGE |
| duration_days | INT | NULL | Expected duration in days |
| is_optional | BOOLEAN | DEFAULT FALSE | Optional step flag |
**Indexes**:
- PRIMARY KEY (id)
- FOREIGN KEY (template_id) REFERENCES rfa_workflow_templates(id) ON DELETE CASCADE
- FOREIGN KEY (organization_id) REFERENCES organizations(id)
- FOREIGN KEY (role_id) REFERENCES roles(role_id)
- INDEX (template_id, step_number)
- INDEX (organization_id)
**Relationships**:
- Parent: rfa_workflow_templates, organizations, roles
**Business Rules**:
- Steps are executed in step_number order
- Optional steps can be skipped
- Duration used for deadline calculation
---
### 4.9 rfa_workflows
**Purpose**: Transaction log table tracking actual RFA approval workflow execution
| Column Name | Data Type | Constraints | Description |
@@ -1081,7 +899,7 @@
- Multiple records per RFA revision (one per step)
- Status changes tracked via updated_at
### 4.10 disciplines
### 4.7 disciplines
**Purpose**: Master table for Project Disciplines (สาขางาน) [Added in v1.4.4 based on Req 6B]
@@ -1108,7 +926,7 @@
---
### 4.11 correspondence_sub_types
### 4.8 correspondence_sub_types
**Purpose**: Master table for Correspondence/RFA Sub-types mapping [Added in v1.4.4 based on Req 6B]
@@ -1569,114 +1387,6 @@
---
### 6.3 circulation_templates
**Purpose**: Master table for circulation workflow templates
| Column Name | Data Type | Constraints | Description |
| --------------- | ------------ | ----------------------------------- | --------------------------- |
| id | INT | PRIMARY KEY, AUTO_INCREMENT | Unique template ID |
| template_name | VARCHAR(100) | NOT NULL | Template name |
| description | TEXT | NULL | Template description |
| organization_id | INT | NOT NULL, FK | Template owner organization |
| is_active | TINYINT(1) | DEFAULT 1 | Active status |
| created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | Record creation timestamp |
| updated_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP ON UPDATE | Last update timestamp |
**Indexes**:
- PRIMARY KEY (id)
- FOREIGN KEY (organization_id) REFERENCES organizations(id)
- INDEX (organization_id)
- INDEX (is_active)
**Relationships**:
- Parent: organizations
- Children: circulation_template_assignees
**Business Rules**:
- Organization-specific templates
- Defines reusable routing workflows
---
### 6.4 circulation_template_assignees
**Purpose**: Child table defining steps in circulation templates
| Column Name | Data Type | Constraints | Description |
| --------------- | --------- | --------------------------- | --------------------------------- |
| id | INT | PRIMARY KEY, AUTO_INCREMENT | Unique step ID |
| template_id | INT | NOT NULL, FK | Reference to template |
| step_number | INT | NOT NULL | Step sequence order |
| organization_id | INT | NOT NULL, FK | Organization responsible for step |
| role_id | INT | NULL, FK | Required role for this step |
| duration_days | INT | NULL | Expected duration in days |
| is_optional | BOOLEAN | DEFAULT FALSE | Optional step flag |
**Indexes**:
- PRIMARY KEY (id)
- FOREIGN KEY (template_id) REFERENCES circulation_templates(id) ON DELETE CASCADE
- FOREIGN KEY (organization_id) REFERENCES organizations(id)
- FOREIGN KEY (role_id) REFERENCES roles(role_id)
- INDEX (template_id, step_number)
- INDEX (organization_id)
**Relationships**:
- Parent: circulation_templates, organizations, roles
**Business Rules**:
- Steps executed in step_number order
- Optional steps can be skipped
- Duration used for deadline calculation
---
### 6.5 circulation_routings
**Purpose**: Transaction log table tracking actual circulation routing execution
| Column Name | Data Type | Constraints | Description |
| --------------- | --------- | ----------------------------------- | ------------------------------------------------- |
| id | INT | PRIMARY KEY, AUTO_INCREMENT | Unique routing log ID |
| circulation_id | INT | NOT NULL, FK | Reference to circulation |
| step_number | INT | NOT NULL | Current step number |
| organization_id | INT | NOT NULL, FK | Organization responsible |
| assigned_to | INT | NULL, FK | Assigned user ID |
| status | ENUM | NULL | Status: PENDING, IN_PROGRESS, COMPLETED, REJECTED |
| comments | TEXT | NULL | Comments/remarks |
| completed_at | DATETIME | NULL | Completion timestamp |
| created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | Record creation timestamp |
| updated_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP ON UPDATE | Last update timestamp |
**Indexes**:
- PRIMARY KEY (id)
- FOREIGN KEY (circulation_id) REFERENCES circulations(id) ON DELETE CASCADE
- FOREIGN KEY (organization_id) REFERENCES organizations(id)
- FOREIGN KEY (assigned_to) REFERENCES users(user_id)
- INDEX (circulation_id, step_number)
- INDEX (assigned_to, status)
- INDEX (status)
**Relationships**:
- Parent: circulations, organizations, users
**Business Rules**:
- Records actual routing history
- Multiple records per circulation (one per step)
- Tracks who reviewed/approved and when
- Used in v_user_tasks view for pending items
---
## **7. 📤 Transmittals Tables (เอกสารนำส่ง)**
### 7.1 transmittals
@@ -2193,9 +1903,49 @@
| **ui_theme** | `VARCHAR(20)` | DEFAULT 'light' | ธีมหน้าจอ (Light/Dark) |
| **updated_at** | `TIMESTAMP` | | วันที่แก้ไขล่าสุด |
## **11. 📊 Views & Procedures (วิว และ โปรซีเดอร์)**
## **11. Workflow Engine Tables (New Core)**
### 11.1 v_current_correspondences
### **11.1 workflow_definitions**
เก็บแม่แบบ (Blueprint) ของ Workflow DSL
| Column | Type | Description |
| :------------ | :---------- | :-------------------------- |
| id | CHAR(36) | PK (UUID) |
| workflow_code | VARCHAR(50) | รหัสอ้างอิง (เช่น RFA_FLOW) |
| version | INT | เวอร์ชัน |
| dsl | JSON | โครงสร้าง Logic |
| compiled | JSON | Optimized Logic |
### **11.2 workflow_instances**
เก็บสถานะการเดินเรื่องจริง
| Column | Type | Description |
| :------------ | :---------- | :------------------------------ |
| id | CHAR(36) | PK (UUID) |
| definition_id | CHAR(36) | FK -> workflow_definitions |
| entity_type | VARCHAR(50) | ประเภทเอกสาร (rfa, circulation) |
| entity_id | VARCHAR(50) | ID เอกสาร |
| current_state | VARCHAR(50) | สถานะปัจจุบัน |
| context | JSON | ตัวแปร Runtime |
### **11.3 workflow_histories**
เก็บประวัติ (Audit Log)
| Column | Type | Description |
| :---------------- | :---------- | :----------------------- |
| id | CHAR(36) | PK (UUID) |
| instance_id | CHAR(36) | FK -> workflow_instances |
| from_state | VARCHAR(50) | ต้นทาง |
| to_state | VARCHAR(50) | ปลายทาง |
| action | VARCHAR(50) | การกระทำ |
| action_by_user_id | INT | ผู้ทำ |
## **12. 📊 Views & Procedures (วิว และ โปรซีเดอร์)**
### 12.1 v_current_correspondences
**Purpose**: View showing current revision of all non-RFA correspondences
@@ -2224,7 +1974,7 @@
---
### 11.2 v_current_rfas
### 12.2 v_current_rfas
**Purpose**: View showing current revision of all RFA documents
@@ -2254,7 +2004,7 @@
---
### 11.3 v_contract_parties_all
### 12.3 v_contract_parties_all
**Purpose**: View showing all organization relationships across contracts and projects
@@ -2274,7 +2024,7 @@
---
### 11.4 v_user_tasks
### 12.4 v_user_tasks
**Purpose**: View showing pending tasks assigned to users (action items)
@@ -2302,7 +2052,7 @@
---
### 11.5 v_audit_log_details
### 12.5 v_audit_log_details
**Purpose**: View enriching audit logs with user information
@@ -2321,7 +2071,7 @@
---
### 11.6 v_user_all_permissions
### 12.6 v_user_all_permissions
**Purpose**: View showing all effective permissions for users across all scopes
@@ -2353,7 +2103,7 @@ WHERE user_id = ?
---
### 11.7 v_documents_with_attachments
### 12.7 v_documents_with_attachments
**Purpose**: View showing all documents and their attachment counts
@@ -2373,7 +2123,7 @@ WHERE user_id = ?
---
### 11.8 v_document_statistics
### 12.8 v_document_statistics
**Purpose**: View providing aggregated document statistics by project, type, and status
@@ -2910,14 +2660,14 @@ SELECT * FROM information_schema.INNODB_LOCK_WAITS;
## **Document Control:**
- **Document:** Data Dictionary v1.4.4
- **Document:** Data Dictionary v1.4.5
- **Version:** 1.4
- **Date:** 2025-11-26
- **Date:** 2025-11-29
- **Author:** NAP LCBP3-DMS & Gemini
- **Status:** FINAL.Rev.04
- **Status:** FINAL.Rev.05
- **Classification:** Internal Technical Documentation
- **Approved By:** Nattanin
---
`End of Data Dictionary v1.4.4 (ฉบับปรับปรุง)`
`End of Data Dictionary v1.4.5 (ฉบับปรับปรุง)`

280
docs/8_lcbp3_v1_4_4.sql → docs/8_lcbp3_v1_4_5.sql
View File

@@ -1,5 +1,5 @@
-- ==========================================================
-- DMS v1.4.4 Document Management System Database
-- DMS v1.4.5 Document Management System Database
-- Deploy Script Schema
-- Server: Container Station on QNAPQNAP TS-473A
-- Database service: MariaDB 10.11
@@ -9,13 +9,8 @@
-- frontend sevice: next.js
-- reverse proxy: jc21/nginx-proxy-manager:latest
-- cron service: n8n
-- DMS v1.4.4 Improvements
-- Update: revise from v1.4.3
-- 1. add disciplines, correspondence_sub_types
-- 2. ปรับปรุงตาราง RFAs และ Correspondences (เพิ่ม Column, document_number_counters
-- 3. ปรับปรุง SEED DATA
-- 4. ปรับปรุง v_current_rfas
-- 5. แยก Seed Data ออกจาก Deploy Script Schema
-- DMS v1.4.5 Improvements
-- Update: revise from v1.4.4
-- ==========================================================
SET NAMES utf8mb4;
SET time_zone = '+07:00';
@@ -62,19 +57,7 @@ DROP TABLE IF EXISTS attachments;
-- ============================================================
-- ส่วนที่ 4: ตาราง Workflow & Routing (Process Logic)
-- ============================================================
-- Circulation Workflow
DROP TABLE IF EXISTS circulation_routings;
DROP TABLE IF EXISTS circulation_template_assignees;
DROP TABLE IF EXISTS circulation_templates;
-- RFA Workflow
DROP TABLE IF EXISTS rfa_workflows;
DROP TABLE IF EXISTS rfa_workflow_template_steps;
DROP TABLE IF EXISTS rfa_workflow_templates;
-- Correspondence Workflow
DROP TABLE IF EXISTS correspondence_routings;
DROP TABLE IF EXISTS correspondence_routing_template_steps;
DROP TABLE IF EXISTS correspondence_status_transitions;
DROP TABLE IF EXISTS correspondence_routing_templates;
-- ============================================================
-- ส่วนที่ 5: ตาราง Mapping สิทธิ์และโครงสร้าง (Access Control)
-- ============================================================
@@ -402,86 +385,6 @@ CREATE TABLE correspondence_references (
-- =====================================================
-- 4. 📐 approval: RFA (เอกสารขออนุมัติ, Workflows)
-- =====================================================
-- 3.1 routing Config for Templates
-- รองรับ: Backend Plan T3.1
-- เหตุผล: เก็บ Logic การเดินเอกสารที่ซับซ้อนกว่า Column ปกติ
CREATE TABLE correspondence_routing_templates (
id INT NOT NULL PRIMARY KEY AUTO_INCREMENT COMMENT 'ID ของแม่แบบ',
template_name VARCHAR(255) NOT NULL COMMENT 'ชื่อแม่แบบ',
description TEXT COMMENT 'คำอธิบาย',
project_id INT NULL COMMENT 'ID โครงการ (ถ้าเป็นแม่แบบเฉพาะโครงการ)',
-- NULL = แม่แบบทั่วไป
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT 'วันที่สร้าง',
updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT 'วันที่แก้ไขล่าสุด',
is_active BOOLEAN DEFAULT TRUE,
workflow_config JSON NULL COMMENT 'Routing Logic Configuration',
UNIQUE KEY ux_routing_template_name_project (template_name, project_id),
CONSTRAINT fk_crt_project FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE
) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COLLATE = utf8mb4_general_ci COMMENT = 'แม่แบบสายงานการส่งต่อเอกสารขออนุมัติ';
CREATE TABLE correspondence_status_transitions(
type_id INT NOT NULL COMMENT 'ID ของประเภทหนังสือ',
from_status_id INT NOT NULL COMMENT 'ID ของสถานะต้นทาง',
to_status_id INT NOT NULL COMMENT 'ID ของสถานะปลายทาง',
PRIMARY KEY (type_id, from_status_id, to_status_id),
CONSTRAINT fk_cst_type FOREIGN KEY (type_id) REFERENCES correspondence_types(id),
CONSTRAINT fk_cst_from FOREIGN KEY (from_status_id) REFERENCES correspondence_status(id),
CONSTRAINT fk_cst_to FOREIGN KEY (to_status_id) REFERENCES correspondence_status(id)
) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COLLATE = utf8mb4_general_ci COMMENT = 'ตารางสถานะที่อนุญาตให้เปลี่ยนแปลงได้ตามประเภทหนังสือ';
-- 1.18.1 correspondence_routing_template_steps Table
CREATE TABLE correspondence_routing_template_steps (
id INT NOT NULL AUTO_INCREMENT PRIMARY KEY COMMENT 'ID ของขั้นตอน',
template_id INT NOT NULL COMMENT 'ID ของแม่แบบ',
sequence INT NOT NULL COMMENT 'ลำดับขั้นตอน',
to_organization_id INT NOT NULL COMMENT 'ID องค์กรณ์ผู้รับในขั้นตอนนี้',
step_purpose ENUM('FOR_APPROVAL', 'FOR_REVIEW', 'FOR_INFORMATION ') NOT NULL DEFAULT 'FOR_REVIEW ' COMMENT 'วัตถุประสงค์ของขั้นตอนนี้',
expected_days INT NULL,
UNIQUE KEY ux_cor_template_sequence (template_id, sequence),
CONSTRAINT fk_cwts_template FOREIGN KEY (template_id) REFERENCES correspondence_routing_templates(id) ON DELETE CASCADE,
CONSTRAINT fk_cwts_org FOREIGN KEY (to_organization_id) REFERENCES organizations(id) ON DELETE CASCADE
) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COLLATE = utf8mb4_general_ci COMMENT = 'ขั้นตอนในแม่แบบ Workflow การส่งต่อเอกสาร';
-- 1.19.1 correspondence_routings
-- 3.2 State Context for Running Workflows
-- รองรับ: Backend Plan T3.1
-- เหตุผล: เก็บ Snapshot ข้อมูล ณ ขณะนั้นเพื่อใช้ตัดสินใจใน Step ถัดไป
CREATE TABLE correspondence_routings (
id INT NOT NULL AUTO_INCREMENT PRIMARY KEY COMMENT 'ID ของขั้นตอน',
correspondence_id INT NOT NULL COMMENT 'ID ของเอกสาร(FK->correspondence_revisions)',
template_id INT NULL COMMENT 'ID ของแม่แบบที่ใช้ (ถ้ามี)',
-- สำหรับอ้างอิงถึงแม่แบบ
sequence INT NOT NULL COMMENT 'ลำดับของขั้นตอนการส่งต่อ',
from_organization_id INT NOT NULL COMMENT 'ID ขององค์กรณ์ผู้ส่ง',
to_organization_id INT NOT NULL COMMENT 'ID ขององค์กรณ์ผู้รับ',
step_purpose ENUM(
'FOR_APPROVAL',
'FOR_REVIEW',
'FOR_INFORMATION',
'FOR_ACTION '
) NOT NULL DEFAULT 'FOR_REVIEW ' COMMENT 'วัตถุประสงค์ของขั้นตอนนี้ เช่น เพื่ออนุมัติ,
เพื่อตรวจสอบ,
หรือเพื่อรับทราบ',
status ENUM(
'SENT',
'RECEIVED',
'ACTIONED',
'FORWARDED',
'REPLIED '
) NOT NULL DEFAULT 'SENT ' COMMENT 'สถานะการดำเนินการของเอกสารในขั้นตอนนี้',
comments TEXT COMMENT 'หมายเหตุ หรือความคิดเห็นในการส่งต่อ',
due_date DATETIME NULL COMMENT 'วันที่ต้องตอบเอกสารในขั้นตอนนี้',
processed_by_user_id INT NULL COMMENT 'ID ของผู้ใช้ที่ดำเนินการในขั้นตอนนี้',
processed_at TIMESTAMP NULL COMMENT 'เวลาที่ดำเนินการ',
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT 'เวลาที่สร้างขั้นตอนนี้',
state_context JSON NULL COMMENT 'Snapshot of routing state context',
UNIQUE KEY ux_cor_routing_sequence (correspondence_id, sequence),
-- Foreign Keys
CONSTRAINT fk_crs_correspondence FOREIGN KEY (correspondence_id) REFERENCES correspondence_revisions(correspondence_id) ON DELETE CASCADE,
CONSTRAINT fk_crs_template FOREIGN KEY (template_id) REFERENCES correspondence_routing_templates(id) ON DELETE
SET NULL,
CONSTRAINT fk_crs_from_org FOREIGN KEY (from_organization_id) REFERENCES organizations(id) ON DELETE CASCADE,
CONSTRAINT fk_crs_to_org FOREIGN KEY (to_organization_id) REFERENCES organizations(id) ON DELETE CASCADE,
CONSTRAINT fk_crs_processed_by_user FOREIGN KEY (processed_by_user_id) REFERENCES users(user_id) ON DELETE
SET NULL
) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COLLATE = utf8mb4_general_ci COMMENT = 'ตารางติดตาม Workflow การส่งต่อเอกสารทั่วไป';
-- ตาราง Master สำหรับประเภท RFA
CREATE TABLE rfa_types (
id INT PRIMARY KEY NOT NULL AUTO_INCREMENT COMMENT 'ID ของตาราง',
@@ -607,59 +510,6 @@ CREATE TABLE rfa_items (
FOREIGN KEY (rfarev_correspondence_id) REFERENCES rfa_revisions(correspondence_id) ON DELETE CASCADE,
FOREIGN KEY (shop_drawing_revision_id) REFERENCES shop_drawing_revisions(id) ON DELETE CASCADE
) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COLLATE = utf8mb4_general_ci COMMENT = 'ตารางเชื่อมระหว่าง rfa_revisions (ที่เป็นประเภท DWG) กับ shop_drawing_revisions (M :N)';
-- ตาราง Master เก็บแม่แบบสายอนุมัติ
-- 3.1 Workflow Config for Templates
-- รองรับ: Backend Plan T3.1
-- เหตุผล: เก็บ Logic การเดินเอกสารที่ซับซ้อนกว่า Column ปกติ
CREATE TABLE rfa_workflow_templates (
id INT PRIMARY KEY AUTO_INCREMENT COMMENT 'ID ของตาราง',
template_name VARCHAR(100) NOT NULL COMMENT 'ชื่อแม่แบบสายอนุมัติ',
description TEXT COMMENT 'คำอธิบาย',
is_active TINYINT(1) DEFAULT 1 COMMENT 'สถานะการใช้งาน',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT 'วันที่สร้าง',
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT 'วันที่แก้ไขล่าสุด',
workflow_config JSON NULL COMMENT 'State Machine Configuration Rules '
) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COLLATE = utf8mb4_general_ci COMMENT = 'ตาราง Master เก็บแม่แบบสายอนุมัติ';
-- ตารางลูก เก็บขั้นตอนในแม่แบบ
CREATE TABLE rfa_workflow_template_steps (
id INT PRIMARY KEY AUTO_INCREMENT COMMENT 'ID ของตาราง',
template_id INT NOT NULL COMMENT 'ID ของแม่แบบ',
step_number INT NOT NULL COMMENT 'ลำดับขั้นตอน',
organization_id INT NOT NULL COMMENT 'องค์กรที่รับผิดชอบ',
role_id INT COMMENT 'บทบาทที่รับผิดชอบ',
action_type ENUM('REVIEW', 'APPROVE', 'ACKNOWLEDGE ') COMMENT 'ประเภทการกระทำ',
duration_days INT COMMENT 'ระยะเวลาที่กำหนด (วัน)',
is_optional BOOLEAN DEFAULT FALSE COMMENT 'เป็นขั้นตอนเลือกหรือไม่',
FOREIGN KEY (template_id) REFERENCES rfa_workflow_templates(id) ON DELETE CASCADE,
FOREIGN KEY (organization_id) REFERENCES organizations(id),
FOREIGN KEY (role_id) REFERENCES roles(role_id)
) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COLLATE = utf8mb4_general_ci COMMENT = 'ตารางลูก เก็บขั้นตอนในแม่แบบ';
-- ตารางประวัติ (Log) การอนุมัติของ RFA จริงตามสายงาน
-- 3.2 State Context for Running Workflows
-- รองรับ: Backend Plan T3.1
-- เหตุผล: เก็บ Snapshot ข้อมูล ณ ขณะนั้นเพื่อใช้ตัดสินใจใน Step ถัดไป
CREATE TABLE rfa_workflows (
id INT PRIMARY KEY AUTO_INCREMENT COMMENT 'ID ของตาราง',
rfa_revision_id INT NOT NULL COMMENT 'ID ของ RFA Revision',
step_number INT NOT NULL COMMENT 'ลำดับขั้นตอน',
organization_id INT NOT NULL COMMENT 'องค์กรที่รับผิดชอบ',
assigned_to INT COMMENT 'ผู้ใช้ที่ได้รับมอบหมาย',
action_type ENUM('REVIEW', 'APPROVE', 'ACKNOWLEDGE ') COMMENT 'ประเภทการกระทำ',
status ENUM(
'PENDING',
'IN_PROGRESS',
'COMPLETED',
'REJECTED '
) COMMENT 'สถานะ',
comments TEXT COMMENT 'ความคิดเห็น',
completed_at DATETIME COMMENT 'วันที่เสร็จสิ้น',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT 'วันที่สร้าง',
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT 'วันที่แก้ไขล่าสุด',
state_context JSON NULL COMMENT 'Snapshot of workflow state context',
FOREIGN KEY (rfa_revision_id) REFERENCES rfa_revisions(id) ON DELETE CASCADE,
FOREIGN KEY (organization_id) REFERENCES organizations(id),
FOREIGN KEY (assigned_to) REFERENCES users(user_id)
) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COLLATE = utf8mb4_general_ci COMMENT = 'ตารางประวัติ (Log) การอนุมัติของ RFA จริงตามสายงาน';
-- =====================================================
-- 5. 📐 Drawings (แบบ, หมวดหมู่)
-- =====================================================
@@ -823,51 +673,6 @@ CREATE TABLE circulations (
FOREIGN KEY (circulation_status_code) REFERENCES circulation_status_codes(code),
FOREIGN KEY (created_by_user_id) REFERENCES users(user_id)
) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COLLATE = utf8mb4_general_ci COMMENT = 'ตาราง "แม่" ของใบเวียนเอกสารภายใน';
-- ตาราง Master เก็บแม่แบบสายงาน
CREATE TABLE circulation_templates (
id INT PRIMARY KEY AUTO_INCREMENT COMMENT 'ID ของตาราง',
template_name VARCHAR(100) NOT NULL COMMENT 'ชื่อแม่แบบสายงาน',
description TEXT COMMENT 'คำอธิบาย',
organization_id INT NOT NULL COMMENT 'องค์กรเจ้าของแม่แบบ',
is_active TINYINT(1) DEFAULT 1 COMMENT 'สถานะการใช้งาน',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT 'วันที่สร้าง',
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT 'วันที่แก้ไขล่าสุด',
FOREIGN KEY (organization_id) REFERENCES organizations(id)
) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COLLATE = utf8mb4_general_ci COMMENT = 'ตาราง Master เก็บแม่แบบสายงาน';
-- ตารางลูก เก็บขั้นตอนในแม่แบบ
CREATE TABLE circulation_template_assignees (
id INT PRIMARY KEY AUTO_INCREMENT COMMENT 'ID ของตาราง',
template_id INT NOT NULL COMMENT 'ID ของแม่แบบ',
step_number INT NOT NULL COMMENT 'ลำดับขั้นตอน',
organization_id INT NOT NULL COMMENT 'องค์กรที่รับผิดชอบ',
role_id INT COMMENT 'บทบาทที่รับผิดชอบ',
duration_days INT COMMENT 'ระยะเวลาที่กำหนด (วัน)',
is_optional BOOLEAN DEFAULT FALSE COMMENT 'เป็นขั้นตอนเลือกหรือไม่',
FOREIGN KEY (template_id) REFERENCES circulation_templates(id) ON DELETE CASCADE,
FOREIGN KEY (organization_id) REFERENCES organizations(id),
FOREIGN KEY (role_id) REFERENCES roles(role_id)
) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COLLATE = utf8mb4_general_ci COMMENT = 'ตารางลูก เก็บขั้นตอนในแม่แบบ';
-- ตารางประวัติ (Log) การส่งต่อของเอกสารจริงตาม Workflow
CREATE TABLE circulation_routings (
id INT PRIMARY KEY AUTO_INCREMENT COMMENT 'ID ของตาราง',
circulation_id INT NOT NULL COMMENT 'ID ของใบเวียน',
step_number INT NOT NULL COMMENT 'ลำดับขั้นตอน',
organization_id INT NOT NULL COMMENT 'องค์กรที่รับผิดชอบ',
assigned_to INT COMMENT 'ผู้ใช้ที่ได้รับมอบหมาย',
status ENUM(
'PENDING',
'IN_PROGRESS',
'COMPLETED',
'REJECTED '
) COMMENT 'สถานะ',
comments TEXT COMMENT 'ความคิดเห็น',
completed_at DATETIME COMMENT 'วันที่เสร็จสิ้น',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT 'วันที่สร้าง',
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT 'วันที่แก้ไขล่าสุด',
FOREIGN KEY (circulation_id) REFERENCES circulations(id) ON DELETE CASCADE,
FOREIGN KEY (organization_id) REFERENCES organizations(id),
FOREIGN KEY (assigned_to) REFERENCES users(user_id)
) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COLLATE = utf8mb4_general_ci COMMENT = 'ตารางประวัติ (Log) การส่งต่อของเอกสารจริงตาม Workflow';
-- =====================================================
-- 7. 📤 Transmittals (เอกสารนำส่ง)
-- =====================================================
@@ -1399,37 +1204,51 @@ FROM contracts c
INNER JOIN contract_organizations co ON c.id = co.contract_id
INNER JOIN organizations o ON co.organization_id = o.id
WHERE c.is_active = TRUE;
-- View แสดงรายการ "งานของฉัน" (My Tasks) ที่ยังไม่เสร็จ
CREATE VIEW v_user_tasks AS
SELECT cr.id AS routing_id,
c.id AS circulation_id,
c.circulation_no,
c.circulation_subject,
c.correspondence_id,
corr.correspondence_number,
corr.project_id,
p.project_code,
p.project_name,
cr.assigned_to AS user_id,
u.username,
u.first_name,
u.last_name,
cr.organization_id,
org.organization_name,
cr.step_number,
cr.status AS task_status,
cr.comments,
cr.completed_at,
cr.created_at AS assigned_at,
c.created_at AS circulation_created_at
FROM circulation_routings cr
INNER JOIN circulations c ON cr.circulation_id = c.id
INNER JOIN correspondences corr ON c.correspondence_id = corr.id
INNER JOIN projects p ON corr.project_id = p.id
INNER JOIN organizations org ON cr.organization_id = org.id
INNER JOIN users u ON cr.assigned_to = u.user_id
WHERE cr.status IN ('PENDING', 'IN_PROGRESS')
AND cr.assigned_to IS NOT NULL;
-- ============================================================
-- View: v_user_tasks (Unified Workflow Engine Edition)
-- ============================================================
-- หน้าที่: รวมรายการงานที่ยังค้างอยู่ (Status = ACTIVE) จากทุกระบบ (RFA, Circulation, Correspondence)
-- เพื่อนำไปแสดงในหน้า Dashboard "My Tasks"
-- ============================================================
CREATE OR REPLACE VIEW v_user_tasks AS
SELECT -- 1. Workflow Instance Info
wi.id AS instance_id,
wd.workflow_code,
wi.current_state,
wi.status AS workflow_status,
wi.created_at AS assigned_at,
-- 2. Entity Info (Polymorphic Identity)
wi.entity_type,
wi.entity_id,
-- 3. Normalized Document Info (ดึงข้อมูลจริงจากตารางลูกตามประเภท)
-- ใช้ CASE WHEN เพื่อรวมคอลัมน์ที่ชื่อต่างกันให้เป็นชื่อกลาง (document_number, subject)
CASE
WHEN wi.entity_type = 'rfa_revision' THEN rfa_corr.correspondence_number
WHEN wi.entity_type = 'circulation' THEN circ.circulation_no
WHEN wi.entity_type = 'correspondence_revision' THEN corr_corr.correspondence_number
ELSE 'N/A'
END AS document_number,
CASE
WHEN wi.entity_type = 'rfa_revision' THEN rfa_rev.title
WHEN wi.entity_type = 'circulation' THEN circ.circulation_subject
WHEN wi.entity_type = 'correspondence_revision' THEN corr_rev.title
ELSE 'Unknown Document'
END AS subject,
-- 4. Context Info (สำหรับ Filter สิทธิ์การมองเห็นที่ Backend)
-- ดึงเป็น JSON String เพื่อให้ Backend ไป Parse หรือใช้ JSON_CONTAINS
JSON_UNQUOTE(JSON_EXTRACT(wi.context, '$.ownerId')) AS owner_id,
JSON_EXTRACT(wi.context, '$.assigneeIds') AS assignee_ids_json
FROM workflow_instances wi
JOIN workflow_definitions wd ON wi.definition_id = wd.id -- 5. Joins for RFA (ซับซ้อนหน่อยเพราะ RFA ผูกกับ Correspondence อีกที)
LEFT JOIN rfa_revisions rfa_rev ON wi.entity_type = 'rfa_revision'
AND wi.entity_id = CAST(rfa_rev.id AS CHAR)
LEFT JOIN correspondences rfa_corr ON rfa_rev.correspondence_id = rfa_corr.id -- 6. Joins for Circulation
LEFT JOIN circulations circ ON wi.entity_type = 'circulation'
AND wi.entity_id = CAST(circ.id AS CHAR) -- 7. Joins for Correspondence
LEFT JOIN correspondence_revisions corr_rev ON wi.entity_type = 'correspondence_revision'
AND wi.entity_id = CAST(corr_rev.id AS CHAR)
LEFT JOIN correspondences corr_corr ON corr_rev.correspondence_id = corr_corr.id -- 8. Filter เฉพาะงานที่ยัง Active อยู่
WHERE wi.status = 'ACTIVE';
-- View แสดง audit_logs พร้อมข้อมูล username และ email ของผู้กระทำ
CREATE VIEW v_audit_log_details AS
SELECT al.audit_id,
@@ -1652,9 +1471,6 @@ CREATE INDEX idx_corr_revisions_correspondence_current ON correspondence_revisio
-- Indexes for v_current_rfas performance
CREATE INDEX idx_rfa_revisions_current_status ON rfa_revisions(is_current, rfa_status_code_id);
CREATE INDEX idx_rfa_revisions_rfa_current ON rfa_revisions(rfa_id, is_current);
-- Indexes for v_user_tasks performance
CREATE INDEX idx_circulation_routings_status_assigned ON circulation_routings(status, assigned_to);
CREATE INDEX idx_circulation_routings_circulation_status ON circulation_routings(circulation_id, status);
-- Indexes for document statistics performance
CREATE INDEX idx_correspondences_project_type ON correspondences(project_id, correspondence_type_id);
CREATE INDEX idx_corr_revisions_status_current ON correspondence_revisions(correspondence_status_id, is_current);

4
docs/8_lcbp3_v1_4_4_seed.sql → docs/8_lcbp3_v1_4_5_seed.sql
View File

@@ -1,5 +1,5 @@
-- ==========================================================
-- DMS v1.4.4 Document Management System Database
-- DMS v1.4.5 Document Management System Database
-- Deploy Seed Data
-- ==========================================================
-- Seed organization
@@ -2124,4 +2124,4 @@ SELECT c.id,
FROM contracts c,
correspondence_types ct
WHERE c.contract_code = 'LCBP3-C4'
AND ct.type_code = 'RFA';
AND ct.type_code = 'RFA';

777
docs/DMS README.bak
View File

@@ -1,777 +0,0 @@
# 📝 0. Project Title: Document Management System (DMS) Web Application for Laem Chabang Port Development Project, Phase 3
## 0. Project
### 📌 0.1 Project Overview / Description
- ระบบ Document Management System (DMS) เป็นเว็บแอปพลิเคชันที่ออกแบบมาเพื่อจัดการเอกสารภายในโครงการอย่างมีประสิทธิภาพ
- โดยมีฟังก์ชันหลักในการอัปโหลด จัดเก็บ ค้นหา แชร์ และควบคุมสิทธิ์การเข้าถึงเอกสาร
- ระบบนี้จะช่วยลดการใช้เอกสารกระดาษ เพิ่มความปลอดภัยในการจัดเก็บข้อมูล
- เพิ่มความสะดวกในการทำงานร่วมกันระหว่างองกรณ์
### 🎯 0.2 Objectives
- พัฒนาระบบที่สามารถจัดการเอกสารได้อย่างเป็นระบบ
- ลดความซ้ำซ้อนในการจัดเก็บเอกสาร
- เพิ่มความปลอดภัยในการเข้าถึงและจัดการเอกสาร
- รองรับการทำงานร่วมกันแบบออนไลน์
### 📦 0.3 Scope of Work
ระบบจะครอบคลุมฟีเจอร์หลักดังนี้:
- การลงทะเบียนและเข้าสู่ระบบ ของผู้ใช้งาน
- การอัปโหลดและจัดเก็บเอกสารในรูปแบบต่าง ๆ (PDF, DOCX, XLSX ฯลฯ)
- การจัดหมวดหมู่และแท็กเอกสาร
- การค้นหาเอกสารด้วยคำสำคัญหรือฟิลเตอร์
- การกำหนดสิทธิ์การเข้าถึงเอกสาร (เช่น อ่านอย่างเดียว, แก้ไข, ลบ)
- การบันทึกประวัติการใช้งานเอกสาร (Audit Trail)
- การมอบหมายงานให้กับผู้เกี่ยวข้อง และแจ้งเตือนเมื่อมีการมอบหมายงาน
- การแจ้งเตือนเมื่อถึงกำหนดวันที่ต้องส่งเอกสารต่อให้ ผู้เกี่ยวข้องอื่นๆ
- การแจ้งเตือนเมื่อมีการเปลี่ยนแปลงเอกสาร
### 👥 0.4 Target Users
- พนักงานภายใน ขององค์กร
- พนักงานควบคุมเอกสาร (Document Control)/ ผู้ดูแลระบบขององค์กร (admin)
- ผู้จัดการฝ่ายเอกสาร ขององค์กร
- ผู้จัดการโครงการ ขององค์กร
- คณะกรรมการ ของโครงการ
- ผู้ดูแลระบบ IT ของโครงการ (superadmin)
### 📈 0.5 Expected Outcomes
- ลดเวลาในการค้นหาเอกสารลงอย่างน้อย 50%
- ลดเวลาในการจัดทำรายงานเอกสาร ประจำวัน, ประจำสัปดาห์, ประจำเดือน, ประจำปี และ รายงานเอกสารทั้งโครงการ
- ลดการใช้เอกสารกระดาษในองค์กร
- เพิ่มความปลอดภัยในการจัดเก็บข้อมูล
- รองรับการทำงานแบบ Remote Work
### 📘 0.6 Requirements Use Cases
#### 📘 Use Case: Upload Document
Actor: พนักงานควบคุมเอกสาร (Document Control)
Description: พนักงานควบคุมเอกสารสามารถอัปโหลดเอกสารเข้าสู่ระบบเพื่อจัดเก็บและใช้งานในภายหลัง
Preconditions: พนักงานควบคุมเอกสารต้องเข้าสู่ระบบก่อน
Main Flow:
พนักงานควบคุมเอกสารเลือกเมนู “อัปโหลดเอกสาร”
เลือกไฟล์จากเครื่องคอมพิวเตอร์
กรอกข้อมูลประกอบ เช่น ชื่อเอกสาร หมวดหมู่ แท็ก
กดปุ่ม “อัปโหลด”
ระบบบันทึกเอกสารและแสดงผลการอัปโหลดสำเร็จ
Postconditions: เอกสารถูกจัดเก็บในระบบและสามารถค้นหาได้
#### 📘 Use Case: Assign Users to Document
Actor: พนักงานควบคุมเอกสาร (Document Control)
Description: พนักงานควบคุมเอกสารสามารถ มอบหมายงานให้กับ Users
Preconditions: พนักงานควบคุมเอกสารต้องเข้าสู่ระบบก่อน, เอกสารต้องอัปโหลดเรียบร้อยแล้ว
Main Flow:
พนักงานควบคุมเอกสารเลือกเมนู “มอบหมายงาน”
เลือกเอกสารในระบบ
เลือก Users กำหนดวันสิ้นสุดงาน
กดปุ่ม “มอบหมายงาน”
ระบบบันทึกเอกสารและแสดงผลการมอบหมายงานสำเร็จ
Postconditions: งานที่มอยหมาย จัดเก็บในระบบและสามารถค้นหาได้
#### 📘 Use Case: Search Document
Actor: ผู้ใช้งานทั่วไป
Description: ผู้ใช้งานสามารถค้นหาเอกสารจากระบบด้วยคำสำคัญหรือฟิลเตอร์
Preconditions: ผู้ใช้งานต้องเข้าสู่ระบบ
Main Flow:
ผู้ใช้งานกรอกคำค้นหรือเลือกฟิลเตอร์ (หมวดหมู่, วันที่, ผู้สร้าง, ผู้ได้รับมอบหมายงาน, สถานะ, title, subject)
กดปุ่ม “ค้นหา”
ระบบแสดงรายการเอกสารที่ตรงกับเงื่อนไข
Postconditions: ผู้ใช้งานสามารถเปิดดูหรือดาวน์โหลดเอกสารที่ค้นพบได้
#### 📘 Use Case: Manage Access
Actor: ผู้ดูแลระบบโครงการ (superadmin) / ผู้ดูแลระบบขององค์กร (admin)
Description: ผู้ดูแลระบบสามารถกำหนดสิทธิ์การเข้าถึงเอกสารให้กับผู้ใช้งาน
Preconditions: ผู้ดูแลระบบต้องเข้าสู่ระบบ
Main Flow:
ผู้ดูแลระบบเลือกเอกสาร
กด “จัดการสิทธิ์”
เลือกผู้ใช้งานและกำหนดสิทธิ์ (อ่าน, แก้ไข, ลบ)
กด “บันทึก”
Postconditions: สิทธิ์การเข้าถึงเอกสารถูกปรับตามที่กำหนด
#### 📘 Use Case: View Document History
Actor: ผู้ใช้งานทั่วไป / ผู้ดูแลระบบ
Description: ผู้ใช้งานสามารถดูประวัติการใช้งานเอกสาร เช่น การแก้ไข การดาวน์โหลด
Preconditions: ผู้ใช้งานต้องมีสิทธิ์เข้าถึงเอกสาร
Main Flow:
ผู้ใช้งานเปิดเอกสาร
เลือก “ดูประวัติ”
ระบบแสดงรายการกิจกรรมที่เกี่ยวข้องกับเอกสาร
Postconditions: ผู้ใช้งานสามารถตรวจสอบการเปลี่ยนแปลงย้อนหลังได้
### 🔄 0.7 Workflow อัตโนมัติในระบบ DMS
✅ ประโยชน์ของ Workflow อัตโนมัติใน DMS
- ลดภาระงานซ้ำ ๆ ของผู้ใช้งาน
- เพิ่มความปลอดภัยและการควบคุมเอกสาร
- เพิ่มความเร็วในการดำเนินงาน
- ลดข้อผิดพลาดจากการทำงานด้วยมือ
#### 🧩 Workflow: 1. Document treat Workflow
กรณี: เมื่อมีการอัปโหลดเอกสารต้องได้รับการมอบหมายงานให้กับ พนักงานภายในองค์กรณ์
ขั้นตอนอัตโนมัติ:
1. ผู้ใช้งานอัปโหลดเอกสารและเลือก “มอบหมายงาน”
2. ระบบส่งแจ้งเตือนไปยังผู้ได้รับมอบหมายงาน
3. ผู้อนุมัติสามารถตรวจสอบและกด “ตรวจสอบแล้ว”
4. ระบบบันทึกสถานะเอกสารและ ส่งต่อ ไปยัง องกรณือื่น ตามลำดับ เมื่อได้ผลและจัดทำเอกสารตอบแล้ว จึงแจ้งผลกลับไปยังผู้ส่ง
#### 📥 Workflow: 2. Auto Tagging & Categorization
กรณี: เอกสารที่อัปโหลดมีชื่อหรือเนื้อหาที่ตรงกับหมวดหมู่ที่กำหนดไว้
ขั้นตอนอัตโนมัติ:
เมื่ออัปโหลดเอกสาร ระบบวิเคราะห์ชื่อไฟล์หรือเนื้อหา
ระบบกำหนดหมวดหมู่และแท็กให้โดยอัตโนมัติ เช่น “ใบเสนอราคา” → หมวด “การเงิน”
ผู้ใช้งานสามารถแก้ไขได้หากต้องการ
#### 🔐 Workflow: 3. Access Control Workflow
กรณี: เอกสารที่มีความลับสูงต้องจำกัดการเข้าถึง
ขั้นตอนอัตโนมัติ:
เมื่ออัปโหลดเอกสารที่มีคำว่า “ลับ” หรือ “Confidential”
ระบบกำหนดสิทธิ์เริ่มต้นให้เฉพาะผู้ใช้งานระดับผู้จัดการขึ้นไป
ระบบแจ้งเตือนผู้ดูแลระบบให้ตรวจสอบสิทธิ์เพิ่มเติม
#### 📤 Workflow: 4. Expiry & Archiving Workflow
กรณี: เอกสารที่มีอายุการใช้งาน เช่น สัญญา หรือใบอนุญาต
ขั้นตอนอัตโนมัติ:
เมื่ออัปโหลดเอกสาร ผู้ใช้งานระบุวันหมดอายุ
ระบบแจ้งเตือนก่อนหมดอายุล่วงหน้า เช่น 30 วัน
เมื่อถึงวันหมดอายุ ระบบย้ายเอกสารไปยังหมวด “Archive” โดยอัตโนมัติ
#### 📊 Workflow: 5. Audit Trail & Notification Workflow
กรณี: มีการแก้ไขหรือดาวน์โหลดเอกสารสำคัญ
ขั้นตอนอัตโนมัติ:
ทุกการกระทำกับเอกสาร (เปิด, แก้ไข, ลบ) จะถูกบันทึกใน Audit Log
หากเอกสารถูกแก้ไขโดยผู้ใช้งานที่ไม่ใช่เจ้าของ ระบบแจ้งเตือนเจ้าของเอกสารทันที
## 🛠️ 1. DMS Architecture Deep Dive (Backend + Frontend)
### 1.1 Executive Summary
- Reverse proxy (Nginx/NPM) เผยแพร่ Frontend (Next.js) และ Backend (Node.js/Express) ผ่าน HTTPS (HSTS)
- Backend เชื่อม MariaDB 10.11 (ข้อมูลหลัก DMS) และแยก n8n + Postgres 16 สำหรับ workflow
- RBAC/ABAC ถูกบังคับใช้งานใน middleware + มีชุด SQL (tables → triggers → procedures → views → seed)
- ไฟล์จริง (PDF/DWG) เก็บนอก webroot ที่ /share/dms‑data พร้อมมาตรฐานการตั้งชื่อ+โฟลเดอร์
- Dev/Prod แยกชัดเจนผ่าน Docker multi‑stage + docker‑compose + โฟลเดอร์ persist logs/config/certs
### 1.2 Runtime Topology & Trust Boundaries
```text
Internet Clients (Browser)
│ HTTPS 443 (HSTS) [QNAP mgmt = 8443]
▼
┌─────────────────────────────────────────────────────┐
│ Reverse Proxy Layer │
│ ├─ Nginx (Alpine) or Nginx Proxy Manager (NPM) │
│ ├─ TLS (LE cert; SAN multi‑subdomain) │
│ └─ Routes: │
│ • /, /_next/* → Frontend (Next.js :3000) │
│ • /api/* → Backend (Express :3001) │
│ • /pma/* → phpMyAdmin │
│ • /n8n/* → n8n (Workflows) │
└─────────────────────────────────────────────────────┘
│ │
│ └──────────┐
▼ │
Frontend (Next.js) │
│ Cookie-based Auth (HttpOnly) │
▼ ▼
Backend (Node/Express ESM) ─────────► MariaDB 10.11
│ │
└────────────────────────────────────┘
Project data (.pdf/.dwg) @ /share/dms-data
n8n (workflows) ──► Postgres 16 (separate DB for automations)
```
==Trust Boundaries==
- Public zone: Internet ↔ Reverse proxy
- App zone: Reverse proxy ↔ FE/BE containers (internal Docker network)
- # Data zone: Backend ↔ Databases (MariaDB, Postgres) + /share/dms-data
### 1.3 Frontend: Next.js (ESM) / React.js
#### 1.3.1 Stack & Key libs
- Next.js (App Router), React, ESM
- Tailwind CSS, PostCSS, shadcn/ui (components.json)
- Fetch API (credentials include) → Cookie Auth (HttpOnly)
#### 1.3.2 Directory Layout
```text
/frontend/
├─ app/
│ ├─ login/
│ ├─ dashboard/
│ ├─ users/
│ ├─ correspondences/
│ ├─ health/
│ └─ layout.tsx / page.tsx (ตาม App Router)
├─ public/
├─ Dockerfile (multi-stage: dev/prod)
├─ package.json
├─ next.config.js
└─ ...
```
#### 1.3.3 Routing & Layouts
- Public /login, /health
- Protected: /dashboard, /users, /correspondences, ... (client-side guard)
- เก็บ middleware.ts (ของเดิม) เพื่อหลีกเลี่ยง regression; ใช้ client‑guard + server action อย่างระมัดระวัง
#### 1.3.4 Auth Flow (Cookie-based)
1. ผู้ใช้ submit form /login → POST /api/auth/login (Backend)
2. Backend set HttpOnly cookie (JWT) + SameSite=Lax/Strict, Secure
3. หน้า protected เรียก GET /api/auth/me เพื่อตรวจสอบสถานะ
4. หาก 401 → redirect → /login
**CORS/Fetch**: เเปิด credentials: 'include' ทุกครั้ง, ตั้ง NEXT_PUBLIC_API_BASE เป็น origin ของ backend ผ่าน proxy (เช่น https://lcbp3.np-dms.work)
#### 1.3.5 UI/UX
- Sea‑blue palette, sidebar พับได้, card‑based KPI
- ตารางข้อมูลเตรียมรองรับ server‑side DataTables\*\*
- shadcn/ui: Button, Card, Badge, Tabs, Dropdown, Tooltip, Switch, etc.
#### 1.3.6 Config & ENV
- NEXT_PUBLIC_API_BAS (ex: https://lcbp3.np-dms.work)
- Build output แยก dev/prod; ระวัง EACCES บน QNAP → ใช้ user node + ปรับสิทธิ์โวลุ่ม .next/\*
#### 1.3.7 Error Handling & Observability (FE)
- Global error boundary (app router) + toast/alert patterns
- Network layer: แยก handler สำหรับ 401/403/500 + retry/backoff ที่จำเป็น
- Metrics (optional): web‑vitals, UX timing (เก็บฝั่ง n8n หรือ simple logging)
---
### 1.4 Backend Architecture (Node.js ESM / Express)
#### 1.4.1 Stack & Structure
- Node 20.x, ESM modules, Express\*\*
- mysql2/promise, jsonwebtoken, cookie-parser, cors, helmet, winston/morgan
```text
/backend/
├─ src/
│ ├─ index.js # bootstrap server, CORS, cookies, health
│ ├─ routes/
│ │ ├─ auth.js # /api/auth/* (login, me, logout)
│ │ ├─ users.js # /api/users/*
│ │ ├─ correspondences.js # /api/correspondences/*
│ │ ├─ drawings.js # /api/drawings/*
│ │ ├─ rfas.js # /api/rfas/*
│ │ └─ transmittals.js # /api/transmittals/*
│ ├─ middleware/
│ │ ├─ authGuard.js # verify JWT from cookie
│ │ ├─ requirePermission.js# RBAC/ABAC enforcement
│ │ ├─ errorHandler.js
│ │ └─ requestLogger.js
│ ├─ db/
│ │ ├─ pool.js # createPool, sane defaults
│ │ └─ models/ # query builders (User, Drawing, ...)
│ ├─ utils/
│ │ ├─ hash.js (bcrypt/argon2)
│ │ ├─ jwt.js
│ │ ├─ pagination.js
│ │ └─ responses.js
│ └─ config/
│ └─ index.js # env, constants
├─ Dockerfile
└─ package.json
```
#### 1.4.2 Request Lifecycle
1. helmet + cors (allow specific origin; credentials true)
2. cookie-parser, json limit (e.g., 2MB)
3. requestLogger → trace + response time
4. Route handler → authGuard (protected) → requirePermission (per‑route) → Controller
5. Error bubbles → errorHandler (JSON shape, status map)
#### 1.4.3 Auth & RBAC/ABAC
- JWT ใน HttpOnly cookie; Claims: sub (user_id), roles, exp
- authGuard: ตรวจ token → แนบ req.user
- requirePermission: เช็ค permission ตามเส้นทาง/วิธี; แผนขยาย ABAC (เช่น project scope, owner, doc state)
- Roles/Permissions ถูก seed ใน SQL; มี view เมทริกซ์ เพื่อ debug (เช่น v_role_permission_matrix)
\*\*ตัวอย่าง pseudo requirePermission(permission)
```js
export const requirePermission = (perm) => async (req, res, next) => {
if (!req.user) return res.status(401).json({ error: "Unauthenticated" });
const ok = await checkPermission(req.user.user_id, perm, req.context);
if (!ok) return res.status(403).json({ error: "Forbidden" });
return next();
};
```
#### 1.4.4 Database Access & Pooling
- createPool({ connectionLimit: 10~25, queueLimit: 0, waitForConnections: true })
- ใช้ parameterized queries เสมอ; ปรับ sql_mode ที่จำเป็นใน my.cnf
#### 1.4.5 File Storage & Secure Download
- Root: /share/dms‑data
- โครงโฟลเดอร์: {module}/{yyyy}/{mm}/{entityId}/ + ชื่อไฟล์ตามมาตรฐาน (เช่น DRW-code-REV-rev.pdf)
- Endpoint download: ตรวจสิทธิ์ (RBAC/ABAC) → res.sendFile()/stream; ป้องกัน path traversal
- MIME allowlist + size limit + virus scan (optional; ภายหลัง)
#### 1.4.6 Health & Readiness
- GET /api/health → { ok: true }
- (optional) /api/ready ตรวจ DB ping + disk space (dms‑data)
#### 1.4.7 Config & ENV (BE)
- DB_HOST, DB_PORT, DB_USER, DB_PASS, DB_NAME
- JWT_SECRET, COOKIE_NAME, COOKIE_SAMESITE, COOKIE_SECURE
- CORS_ORIGIN, LOG_LEVEL, APP_BASE_URL
- FILE_ROOT=/share/dms-data
#### 1.4.8 Logging
- Access log (morgan) + App log (winston) → /share/Container/dms/logs/backend/
- รูปแบบ JSON (timestamp, level, msg, reqId) + daily rotation (logrotate/container‑side)
### 1.5 Database (MariaDB 10.11)
#### 1.5.1 Schema Overview (ย่อ)
- RBAC core: users, roles, permissions, user_roles, role_permissions
- Domain: drawings, contracts, correspondences, rfas, transmittals, organizations, projects, ...
- Audit: audit_logs (แผนขยาย), deleted_at (soft delete, แผนงาน)
```text
[users]──<user_roles>──[roles]──<role_permissions>──[permissions]
│
└── activities/audit_logs (future expansion)
[drawings]──<mapping>──[contracts]
[rfas]──<links>──[drawings]
[correspondences] (internal/external flag)
```
#### 1.5.2 Init SQL Pipeline
1. 01\_\*\_deploy_table_rbac.sql — สร้างตารางหลักทั้งหมด + RBAC
2. 02\_\*\_triggers.sql — บังคับ data rules, auto‑audit fields
3. 03\_\*\_procedures_handlers.sql — upsert/bulk handlers (เช่น sp_bulk_import_contract_dwg)
4. 04\_\*\_views.sql — รายงาน/เมทริกซ์สิทธิ์ (v_role_permission_matrix, etc.)
5. 05\_\*\_seed_data.sql — ค่าพื้นฐาน domain (project, categories, statuses)
6. 06\_\*\_seed_users.sql — บัญชีเริ่มต้น (superadmin, editors, viewers)
7. 07\_\*\_seed_contract_dwg.sql — ข้อมูลตัวอย่างแบบสัญญา
#### 1.5.3 Indexing & Performance
- Composite indexes ตามคอลัมน์ filter/sort (เช่น (project_id, updated_at DESC))
- Full‑text index (optional) สำหรับ advanced search
- Query plan review (EXPLAIN) + เพิ่ม covering index ตามรายงาน
#### 1.5.4 MySQL/MariaDB Config (my.cnf — แนวทาง)
```conf
[mysqld]
innodb_buffer_pool_size = 4G # ปรับตาม RAM/QNAP
innodb_log_file_size = 512M
innodb_flush_log_at_trx_commit = 1
max_connections = 200
sql_mode = STRICT_TRANS_TABLES,NO_ENGINE_SUBSTITUTION
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci
```
> ปรับค่าให้เหมาะกับ workload จริง + เฝ้าดู IO/CPU ของ QNAP
#### 1.5.5 Backup/Restore
- Logical backup: mysqldump --routines --triggers --single-transaction
- Physical (snapshot QNAP) + schedule ผ่าน n8n/cron
- เก็บสำเนา off‑NAS (encrypted)
### 1.6 Reverse Proxy & TLS
#### 1.6.1 Nginx (Alpine) — ตัวอย่าง server block
> สำคัญ: บนสภาพแวดล้อมนี้ ให้ใช้คนละบรรทัด:
> listen 443 ssl;
> http2 on;
> หลีกเลี่ยง listen 443 ssl http2;
```conf
server {
listen 80;
server_name lcbp3.np-dms.work;
return 301 https://$host$request_uri;
}
server {
listen 443 ssl;
http2 on;
server_name lcbp3.np-dms.work;
ssl_certificate /etc/nginx/certs/fullchain.pem;
ssl_certificate_key /etc/nginx/certs/privkey.pem;
add_header Strict-Transport-Security "max-age=63072000; preload" always;
# Frontend
location / {
proxy_pass http://frontend:3000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
# Next.js static
location /_next/ {
proxy_pass http://frontend:3000;
}
# Backend API
location /api/ {
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_pass http://backend:3001;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
}
# phpMyAdmin (sub-path)
location /pma/ {
proxy_pass http://phpmyadmin:80/;
}
# n8n
location /n8n/ {
proxy_pass http://n8n:5678/;
}
}
```
#### 1.6.2 Nginx Proxy Manager (NPM) — Tips
- ระวังอย่าใส่ proxy_http_version ซ้ำซ้อน (duplicate directive) ใน Advanced
- ถ้าต้องแก้ไฟล์ด้านใน NPM → ระวังไฟล์ใน /data/nginx/proxy_host/\*.conf
- จัดการ certificate / SAN หลาย sub‑domain ใน UI แต่ mainten ดีเรื่อง symlink/renew
#### 1.6.3 TLS & Certificates
- Let’s Encrypt (HTTP‑01 webroot/standalone) + HSTS
- QNAP mgmt เปลี่ยนเป็น 8443 → พอร์ต 443 public ว่างสำหรับ Nginx/NPM
### 1.7 Docker Compose Topology
#### 1.7.1 Services (สรุป)
- frontend (Next.js) :3000
- backend (Express) :3001
- mariadb (10.11) :3306 (internal)
- phpmyadmin :80 (internal)
- nginx or npm :80/443 (published)
- n8n :5678 (internal)
- postgres_n8n (16-alpine)
- pgadmin4
#### 1.7.2 Volumes & Paths
```text
/share/Container/dms/
├─ mariadb/data
├─ mariadb/init/*.sql
├─ backend/ (code)
├─ frontend/ (code)
├─ phpmyadmin/{sessions,tmp,config.user.inc.php}
├─ nginx/{nginx.conf,dms.conf,certs/}
├─ n8n, n8n-postgres, n8n-cache
└─ logs/{backend,frontend,nginx,pgadmin,phpmyadmin,postgres_n8n}
/share/dms-data (pdf/dwg storage)
```
#### 1.7.3 Healthchecks (suggested)
- backend:
```sh
curl http://localhost:3001/api/health
```
- frontend: curl /health (simple JSON)
- mariadb: mysqladmin ping with credentials
- nginx: nginx -t at startup
#### 1.7.4 Security Hardening
- รัน container ด้วย user non‑root (user: node สำหรับ FE/BE)
- จำกัด capabilities; read‑only FS (ยกเว้นโวลุ่มจำเป็น)
- เฉพาะ backend เมานต์ /share/dms-data
### 1.8 Observability, Ops, and Troubleshooting
#### 1.8.1 Logs
- Frontend → /logs/frontend/\*
- Backend → /logs/backend/\* (app/access/error)
- Nginx/NPM → /logs/nginx/\*
- MariaDB → default datadir log + slow query (เปิดใน my.cnf หากต้องการ)
#### 1.8.2 Common Issues & Playbooks
- 401 Unauthenticated: ตรวจ authGuard → JWT cookie มี/หมดอายุ → เวลา server/FE sync → CORS credentials: true
- EACCES Next.js: สิทธิ์ .next/\* + run as`node, โวลุ่ม map ถูก user:group
- NPM duplicate directive: ลบซ้ำ proxy_http_version ใน Advanced / ตรวจ proxy_host/\*.conf
- LE cert path/symlink: ตรวจ /etc/letsencrypt/live/npm-\* symlink ชี้ถูก
- DB field not found: ตรวจ schema vs code (migration/init SQL) → sync ให้ตรง
#### 1.8.3 Performance Guides
- Backend: keep‑alive, gzip/deflate at proxy, pool 10–25, paginate, avoid N+1
- Frontend: prefetch critical routes, cache static, image optimization
- DB: เพิ่ม index จุด filter, analyze query (EXPLAIN), ปรับ buffer pool
### 1.9 Security & Compliance
- HTTPS only + HSTS (preload)
- CORS: allow list เฉพาะ FE origin; Access-Control-Allow-Credentials: true
- Cookie: HttpOnly, Secure, SameSite=Lax/Strict
- Input Validation: celebrate/zod (optional) + sanitize
- Rate limiting: per IP/route (optional)
- AuditLog: วางแผนเพิ่ม ครอบคลุม CRUD + mapping (actor, action, entity, before/after)
- Backups: DB + /share/dms-data + config (encrypted off‑NAS)
### 1.10 Backlog → Architecture Mapping
1. RBAC Enforcement ครบ → เติม requirePermission ทุก route + test matrix ผ่าน view
2. AuditLog ครบ CRUD/Mapping → trigger + table audit_logs + BE hook
3. Upload/Download จริงของ Drawing Revisions → BE endpoints + virus scan (optional)
4. Dashboard KPI → BE summary endpoints + FE cards/charts
5. Server‑side DataTables → paging/sort/filter + indexesรองรับ
6. รายงาน Export CSV/Excel/PDF → BE export endpoints + FE buttons
7. Soft delete (deleted_at) → BE filter default scope + restore endpoint
8. Validation เข้ม → celebrate/zod schema + consistent error shape
9. Indexing/Perf → slow query log + EXPLAIN review
10. Job/Cron Deadline Alerts → n8n schedule + SMTP
### 1.11 Port & ENV Matrix (Quick Ref)
| Component | Ports | Key ENV |
| Nginx/NPM | 80/443 (public) | SSL paths, HSTS |
| Frontend | 3000 (internal) | NEXT*PUBLIC_API_BASE |
| Backend | 3001 (internal) | DB*\*, JWT*SECRET, CORS_ORIGIN, FILE_ROOT |
| MariaDB | 3306 (internal) | MY_CNF, credentials |
| n8n | 5678 (internal) | N8N*, webhook URL under /n8n/ |
| Postgres | 5432 (internal) | n8n DB |
QNAP mgmt: 8443 (already moved)
### 1.12 Sample Snippets
#### 1.12.1 Backend CORS (credentials)
```js
app.use(
cors({
origin: ["https://lcbp3.np-dms.work"],
credentials: true,
})
);
```
#### 1.12.2 Secure Download (guarded)
```js
router.get(
"/files/:module/:id/:filename",
authGuard,
requirePermission("file.read"),
async (req, res) => {
const { module, id, filename } = req.params;
// 1) ABAC: verify user can access this module/entity
const ok = await canReadFile(req.user.user_id, module, id);
if (!ok) return res.status(403).json({ error: "Forbidden" });
const abs = path.join(FILE_ROOT, module, id, filename);
if (!abs.startsWith(FILE_ROOT))
return res.status(400).json({ error: "Bad path" });
return res.sendFile(abs);
}
);
```
#### 1.12.3 Healthcheck
```js
router.get("/health", (req, res) => res.json({ ok: true }));
```
### 13 Deployment Workflow (Suggested)
1. Git (Gitea) branch strategy feature/\* → PR → main
2. Build images (dev/prod) via Dockerfile multi‑stage; pin Node/MariaDB versions
3. docker compose up -d --build จาก /share/Container/dms
4. Validate: /health, /api/health, login roundtrip
5. Monitor logs + baseline perf; run SQL smoke tests (views/triggers/procs)
### 14 Appendix
- Naming conventions: snake_case DB, camelCase JS
- Timezones: store UTC in DB; display in app TZ (+07:00)
- Character set: UTF‑8 (utf8mb4_unicode_ci)
- Large file policy: size limit (e.g., 50–200MB), allowlist extensions
- Retention: archive strategy for old revisions (optional)
## บทบาท: คุณคือ Programmer และ Document Engineer ที่เชี่ยวชาญ
1. การพัฒนาเว็บแอป (Web Application Development)
2. Configuration of Container Station on QNAP
3. Database: mariadb:10.11
4. Database management: phpmyadmin:5-apache
5. Backend: node:.js (ESM)
6. Frontend: next.js, react
7. Workflow automation: n8n:
8. Workflow database: postgres:16-alpine
9. Workflow database management: pgadmin4
10. Reverse proxy: nginx:1.27-alpine
11. linux on QNAP
12. การจัดการฐานข้อมูล (Database Management)
13. การวิเคราะห์ฐานข้อมูล (Database Analysis)
14. การจัดการฐานข้อมูลเชิงสัมพันธ์ (Relational Databases)
15. ภาษา SQL
16. RBAC
## 2. ระบบที่ใช้
## Server
- ใช้ Container Station เป็น SERVER บน QNAP (Model: TS-473A, RAM: 32GB, CPU: AMD Ryzen V1500B 4 cores 8 threads) **เปลี่ยน port 443 ของ QNAP เป็น 8443 แล้ว**
## การพัฒนาโครงการ
- ด้วย Visual Studio Code บน Windows 11
- ใช้ ๊ UI ของ Container Station เป็นหลัก
## โครงสร้างโฟลเดอร์ (บน QNAP)
/share/Container/dms/
├─ docker-compose.yml # Create โดย UI Container Station
├─ mariadb/
│ ├─ data/ # ข้อมูลจริงของ MariaDB
│ ├─ init/ # ข้อมูลเริ่มต้นของ MariaDB
│ │ ├─ 01_dms_data_v5_1_deploy_table_rbac.sql # Create all data table & RBAC table here!
│ │ ├─ 02_dms_data_v5_1_triggers.sql # Create all triggers here!
│ │ ├─ 03_dms_data_v5_1_procedures_handlers.sql # Create all procedures here!
│ │ ├─ 04_dms_data_v5_1_views.sql # Create all views here!
│ │ ├─ 05 dms_data_v5_1_seeก_data.sql # Seed nescesary data here!
│ │ ├─ 06_dms_data_v5_1_seed_users.sql # Seed users data here!
│ │ └─ 07_dms_data_v5_1_seed_contract_dwg.sql # Seed contract drawing data here!
│ └─ my.cnf
├─ backend/
│ ├─ app/
│ ├─ src/
│ │ ├─ db/
│ │ │ └─models/
│ │ ├─ middleware/
│ │ ├─ routes/
│ │ ├─ utils/
│ │ └─ index.js
│ ├─ Dockerfile
│ ├─ package.json
│ └─ package-lock.json # ไม่มี
├─ frontend/
│ ├─ app/
│ │ ├─ correspondences/
│ │ ├─ dashboard/
│ │ ├─ health/
│ │ ├─ login/
│ │ └─ users/
│ ├─ public/
│ ├─ Dockerfile
│ ├─ package.json
│ ├─ package-lock.json # ไม่มี
│ ├─ next.config.js
│ └─ page.jsx
├─ phpmyadmin/
│ ├─ sessions/ # โฟลเดอร์เซสชันถาวรของ phpMyAdmin
│ ├─ tmp/
│ ├─ config.user.inc.php
│ └─ zzz-custom.ini
├─ nginx/
│ ├─ certs/
│ ├─ nginx.conf
│ └─ dms.conf
├─ n8n/
├─ n8n-cache/
├─ n8n-postgres/
└─ logs/
├─ backend/
├─ frontend/
├─ nginx/
├─ pgadmin/
├─ phpmyadmin/
└─ postgres_n8n/
/share/dms-data # เก็บข้อมมูล .pdf, .dwg แยกตาม correspondences, documents
# งานที่ต้องการ:
- ไม่ใช้ .env เด็ดขาด Container Station ไม่รองรับ และ docker-compose.yml ได้ทดสอบ รันบน Container station มาแล้ว
- Code ของ backend ทั้งหมด
- การทดสอบระบบ backend ทุกส่วน ให้พร้อม สำหรับ frontend
# กรณี 2: มี Git อยู่แล้ว (มี main อยู่)
2.1 อัปเดต main ให้ตรงล่าสุดก่อนแตกบร้านช์
cd /share/Container/dms
git checkout main
git pull --ff-only # ถ้าเชื่อม remote อยู่
git tag -f stable-$(date +%F) # tag จุดเสถียรปัจจุบัน
2.2 แตก branch งาน Dashboard
git checkout -b feature/dashboard-update-$(date +%y%m%d)
git checkout -b feature/dashboard-update-251004
2.3 ทำงาน/คอมมิตตามปกติ
# แก้ไฟล์ frontend/app/dashboard/\* และที่เกี่ยวข้อง
git add frontend/app/dashboard
git commit -m "feat(dashboard): เพิ่มส่วนจัดการ user"
git push -u origin feature/dashboard-update-251004

BIN
docs/Dis.xlsx Normal file
View File

Binary file not shown.

768
docs/Markdown/0_Requirements_V1_4_3.md
View File

@@ -1,768 +0,0 @@
# 📝 **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`

970
docs/Markdown/1_FullStackJS_V1_4_3.md
View File

@@ -1,970 +0,0 @@
# 📝 **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`

397
docs/Markdown/2_Backend_Plan_Phase6A_V1_4_3.md
View File

@@ -1,397 +0,0 @@
# “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
docs/Markdown/2_Backend_Plan_V1_4_3.md
View File

@@ -1,552 +0,0 @@
# 📋 **แผนการพัฒนา 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`

995
docs/Markdown/3_Frontend_Plan_V1_4_3.md
View File

@@ -1,995 +0,0 @@
# 📋 **แผนการพัฒนา 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 (ฉบับปรับปรุง)`

2840
docs/Markdown/4_Data_Dictionary_V1_4_3.md
View File

File diff suppressed because it is too large Load Diff

192
docs/Markdown/FullStackJS_Guidelines.md
View File

@@ -1,192 +0,0 @@
# 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
docs/Markdown/FullStackJS_Guidelines01.md
View File

@@ -1,364 +0,0 @@
# 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
docs/Markdown/LCBP3-DMS Backend Documentation (ฉบับสมบูรณ์)
View File

File diff suppressed because one or more lines are too long

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

File diff suppressed because one or more lines are too long

1196
docs/Markdown/LCBP3-DMS Requirements Specification (v2.0)
View File

File diff suppressed because one or more lines are too long

136
docs/Markdown/LCBP3-DMS Requirements Specification.bak
View File

@@ -1,136 +0,0 @@
# 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
docs/Markdown/LCBP3-DMS V1_1_0_application _requirements.md
View File

@@ -1,197 +0,0 @@
# 📝 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
docs/Markdown/LCBP3-DMS V1_1_1_FullStackJS.md
View File

@@ -1,456 +0,0 @@
# แนวทางการพัฒนา 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
docs/Markdown/LCBP3-DMS V1_1_1_application _requirements.md
View File

@@ -1,201 +0,0 @@
# 📝 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
docs/Markdown/LCBP3-DMS — Task Breakdown สำหรับ Phase 2A–2C (v1.4.2).md
View File

@@ -1,234 +0,0 @@
# 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
docs/Markdown/LCBP3-DMS_V1_1_0_application _database.md
View File

@@ -1,55 +0,0 @@
# 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
docs/Markdown/LCBP3-DMS_V1_2_0_Data_Dictionary.ิbak
View File

@@ -1,682 +0,0 @@
# **สรุปตารางฐานข้อมูล (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
docs/Markdown/LCBP3-DMS_V1_2_1_Data_Dictionary.md
View File

@@ -1,777 +0,0 @@
---
# **สรุปตารางฐานข้อมูล (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
docs/Markdown/LCBP3-DMS_V1_2_1_FullStackJS.md
View File

@@ -1,459 +0,0 @@
# **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
docs/Markdown/LCBP3-DMS_V1_2_1_application _requirements.md
View File

@@ -1,210 +0,0 @@
# **📝 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
docs/Markdown/LCBP3-DMS_V1_3_0_Data_Dictionary.md
View File

@@ -1,775 +0,0 @@
---
# **สรุปตารางฐานข้อมูล (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
docs/Markdown/LCBP3-DMS_V1_3_0_FullStackJS.md
View File

@@ -1,478 +0,0 @@
# **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
docs/Markdown/LCBP3-DMS_V1_3_0_Test_Plan_TH.md
View File

@@ -1,79 +0,0 @@
# **🧪 แผนการทดสอบระบบ (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
docs/Markdown/LCBP3-DMS_V1_3_0_backend_dev_plan.md
View File

@@ -1,117 +0,0 @@
# แผนการพัฒนา 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
docs/Markdown/LCBP3-DMS_V1_3_0_frontend_dev_plan.md
View File

@@ -1,169 +0,0 @@
# แผนการพัฒนา 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
docs/Markdown/LCBP3-DMS_V1_3_0_requirements.md
View File

@@ -1,210 +0,0 @@
# **📝 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
docs/Markdown/LCBP3-DMS_V1_4_0_Backend_Development_Plan.md
View File

@@ -1,655 +0,0 @@
# 📋 แผนการพัฒนา 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
docs/Markdown/LCBP3-DMS_V1_4_0_Data_Dictionary.bak.md
View File

@@ -1,900 +0,0 @@
# **สรุปตารางฐานข้อมูล (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
docs/Markdown/LCBP3-DMS_V1_4_0_Data_Dictionary.md
View File

File diff suppressed because it is too large Load Diff

833
docs/Markdown/LCBP3-DMS_V1_4_0_Frontend_Development_Plan.md
View File

@@ -1,833 +0,0 @@
# 📋 แผนการพัฒนา 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
docs/Markdown/LCBP3-DMS_V1_4_0_FullStackJS.md
View File

@@ -1,480 +0,0 @@
# **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
docs/Markdown/LCBP3-DMS_V1_4_0_requirements.md
View File

@@ -1,245 +0,0 @@
# **📝 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
docs/Markdown/LCBP3-DMS_V1_4_1_Backend_Development_Plan.md
View File

File diff suppressed because it is too large Load Diff

521
docs/Markdown/LCBP3-DMS_V1_4_1_Backend_Development_Plan_Grok.md
View File

@@ -1,521 +0,0 @@
ต่อไปนี้คือไฟล์ที่ปรับแก้เรียบร้อยแล้วทั้ง 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
docs/Markdown/LCBP3-DMS_V1_4_1_Data_Dictionary.md
View File

File diff suppressed because it is too large Load Diff

2491
docs/Markdown/LCBP3-DMS_V1_4_1_Frontend_Development_Plan.md
View File

File diff suppressed because it is too large Load Diff

1553
docs/Markdown/LCBP3-DMS_V1_4_1_FullStackJS.md
View File

File diff suppressed because it is too large Load Diff

673
docs/Markdown/LCBP3-DMS_V1_4_1_Requirements.md
View File

@@ -1,673 +0,0 @@
# 📝 **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
docs/Markdown/LCBP3-DMS_V1_4_2_Backend_Development_Plan (Patched)
View File

@@ -1,204 +0,0 @@
# 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
docs/Markdown/LCBP3-DMS_V1_4_2_FullStackJS (Patched)
View File

@@ -1,160 +0,0 @@
# 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
docs/Markdown/LCBP3-DMS_V1_4_2_Requirements (Patched)
View File

@@ -1,124 +0,0 @@
# 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
docs/Markdown/LCBP3-DMS_V1_4_2_Requirements..bak.md
View File

@@ -1,618 +0,0 @@
# 📝 **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
docs/Markdown/icon.md
View File

@@ -1,110 +0,0 @@
```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
docs/Markdown/working LCBP3-DMS_V1_4_2_Backend_Development_Plan.md
View File

File diff suppressed because it is too large Load Diff

134
docs/NestJS01.bak
View File

@@ -1,134 +0,0 @@
You are a senior TypeScript programmer with experience in the NestJS framework and a preference for clean programming and design patterns.
Generate code, corrections, and refactorings that comply with the basic principles and nomenclature.
## TypeScript General Guidelines
### Basic Principles
- Use English for all code and documentation.
- Always declare the type of each variable and function (parameters and return value).
- Avoid using any.
- Create necessary types.
- Use JSDoc to document public classes and methods.
- Don't leave blank lines within a function.
- One export per file.
### Nomenclature
- Use PascalCase for classes.
- Use camelCase for variables, functions, and methods.
- Use kebab-case for file and directory names.
- Use UPPERCASE for environment variables.
- Avoid magic numbers and define constants.
- Start each function with a verb.
- Use verbs for boolean variables. Example: isLoading, hasError, canDelete, etc.
- Use complete words instead of abbreviations and correct spelling.
- Except for standard abbreviations like API, URL, etc.
- Except for well-known abbreviations:
- i, j for loops
- err for errors
- ctx for contexts
- req, res, next for middleware function parameters
### Functions
- In this context, what is understood as a function will also apply to a method.
- Write short functions with a single purpose. Less than 20 instructions.
- Name functions with a verb and something else.
- If it returns a boolean, use isX or hasX, canX, etc.
- If it doesn't return anything, use executeX or saveX, etc.
- Avoid nesting blocks by:
- Early checks and returns.
- Extraction to utility functions.
- Use higher-order functions (map, filter, reduce, etc.) to avoid function nesting.
- Use arrow functions for simple functions (less than 3 instructions).
- Use named functions for non-simple functions.
- Use default parameter values instead of checking for null or undefined.
- Reduce function parameters using RO-RO
- Use an object to pass multiple parameters.
- Use an object to return results.
- Declare necessary types for input arguments and output.
- Use a single level of abstraction.
### Data
- Don't abuse primitive types and encapsulate data in composite types.
- Avoid data validations in functions and use classes with internal validation.
- Prefer immutability for data.
- Use readonly for data that doesn't change.
- Use as const for literals that don't change.
### Classes
- Follow SOLID principles.
- Prefer composition over inheritance.
- Declare interfaces to define contracts.
- Write small classes with a single purpose.
- Less than 200 instructions.
- Less than 10 public methods.
- Less than 10 properties.
### Exceptions
- Use exceptions to handle errors you don't expect.
- If you catch an exception, it should be to:
- Fix an expected problem.
- Add context.
- Otherwise, use a global handler.
### Testing
- Follow the Arrange-Act-Assert convention for tests.
- Name test variables clearly.
- Follow the convention: inputX, mockX, actualX, expectedX, etc.
- Write unit tests for each public function.
- Use test doubles to simulate dependencies.
- Except for third-party dependencies that are not expensive to execute.
- Write acceptance tests for each module.
- Follow the Given-When-Then convention.
## Specific to NestJS
### Basic Principles
- Use modular architecture.
- Encapsulate the API in modules.
- One module per main domain/route.
- One controller for its route.
- And other controllers for secondary routes.
- A models folder with data types.
- DTOs validated with class-validator for inputs.
- Declare simple types for outputs.
- A services module with business logic and persistence.
- Entities with MikroORM for data persistence.
- One service per entity.
- Common Module: Create a common module (e.g., @app/common) for shared, reusable code across the application.
- This module should include:
- Configs: Global configuration settings.
- Decorators: Custom decorators for reusability.
- DTOs: Common data transfer objects.
- Guards: Guards for role-based or permission-based access control.
- Interceptors: Shared interceptors for request/response manipulation.
- Notifications: Modules for handling app-wide notifications.
- Services: Services that are reusable across modules.
- Types: Common TypeScript types or interfaces.
- Utils: Helper functions and utilities.
- Validators: Custom validators for consistent input validation.
- Core module functionalities:
- Global filters for exception handling.
- Global middlewares for request management.
- Guards for permission management.
- Interceptors for request processing.
### Testing
- Use the standard Jest framework for testing.
- Write tests for each controller and service.
- Write end to end tests for each api module.
- Add a admin/test method to each controller as a smoke test.

33
docs/NextJS01.bak
View File

@@ -1,33 +0,0 @@
You are a Senior Front-End Developer and an Expert in ReactJS, NextJS, JavaScript, TypeScript, HTML, CSS and modern UI/UX frameworks (e.g., TailwindCSS, Shadcn, Radix). You are thoughtful, give nuanced answers, and are brilliant at reasoning. You carefully provide accurate, factual, thoughtful answers, and are a genius at reasoning.
- Follow the user’s requirements carefully & to the letter.
- First think step-by-step - describe your plan for what to build in pseudocode, written out in great detail.
- Confirm, then write code!
- Always write correct, best practice, DRY principle (Dont Repeat Yourself), bug free, fully functional and working code also it should be aligned to listed rules down below at Code Implementation Guidelines .
- Focus on easy and readability code, over being performant.
- Fully implement all requested functionality.
- Leave NO todo’s, placeholders or missing pieces.
- Ensure code is complete! Verify thoroughly finalised.
- Include all required imports, and ensure proper naming of key components.
- Be concise Minimize any other prose.
- If you think there might not be a correct answer, you say so.
- If you do not know the answer, say so, instead of guessing.
### Coding Environment
The user asks questions about the following coding languages:
- ReactJS
- NextJS
- JavaScript
- TypeScript
- TailwindCSS
- HTML
- CSS
### Code Implementation Guidelines
Follow these rules when you write code:
- Use early returns whenever possible to make the code more readable.
- Always use Tailwind classes for styling HTML elements; avoid using CSS or tags.
- Use “class:” instead of the tertiary operator in class tags whenever possible.
- Use descriptive variable and function/const names. Also, event functions should be named with a “handle” prefix, like “handleClick” for onClick and “handleKeyDown” for onKeyDown.
- Implement accessibility features on elements. For example, a tag should have a tabindex=“0”, aria-label, on:click, and on:keydown, and similar attributes.
- Use consts instead of functions, for example, “const toggle = () =>”. Also, define a type if possible.

1248
docs/SQL/01_dms_v1_0_0.bak.sql
View File

File diff suppressed because it is too large Load Diff

1565
docs/SQL/01_dms_v1_0_0.sql
View File

File diff suppressed because it is too large Load Diff

40
docs/SQL/01_dms_v1_0_0_patch.sql
View File

@@ -1,40 +0,0 @@
-- ==========================================================
-- DMS v1.0.1 Patch
-- Reason: Add missing relationship for Req 2.5.3
-- Update: Changed link to revision-level instead of master-level based on clarification.
-- ==========================================================
SET NAMES utf8mb4;
SET time_zone = '+07:00';
SET FOREIGN_KEY_CHECKS=1;
-- สร้างตารางเชื่อมระหว่าง shop_drawing_revisions (ตารางลูก) กับ contract_drawings (Master)
-- เพื่อรองรับ Requirement 2.5.3 ที่ระบุว่า Shop Drawing "แต่ละ revision" สามารถอ้างอิง Contract Drawing ที่แตกต่างกันได้
CREATE TABLE shop_drawing_revision_contract_refs (
shop_drawing_revision_id INT NOT NULL COMMENT 'ID ของ Shop Drawing Revision (FK -> shop_drawing_revisions.id)',
contract_drawing_id INT NOT NULL COMMENT 'ID ของ Contract Drawing ที่อ้างอิง (FK -> contract_drawings.condwg_id)',
-- PRIMARY KEY (shop_drawing_revision_id, contract_drawing_id),
-- เพิ่ม KEY เพื่อประสิทธิภาพในการค้นหา
KEY idx_sdrcr_rev (shop_drawing_revision_id),
KEY idx_sdrcr_cd (contract_drawing_id),
-- Foreign Keys
CONSTRAINT fk_sdrcr_revision
FOREIGN KEY (shop_drawing_revision_id)
REFERENCES shop_drawing_revisions(id) -- เชื่อมโยงกับตาราง Revision
ON DELETE CASCADE
ON UPDATE CASCADE,
CONSTRAINT fk_sdrcr_contract_drawing
FOREIGN KEY (contract_drawing_id)
REFERENCES contract_drawings(condwg_id)
ON DELETE CASCADE
ON UPDATE CASCADE
)
ENGINE=InnoDB
DEFAULT CHARSET=utf8mb4
COLLATE=utf8mb4_general_ci
COMMENT='ตารางเชื่อมโยง Shop Drawing Revisions กับ Contract Drawings (Req 2.5.3)';

1537
docs/SQL/01_dms_v1_0_1.sql
View File

File diff suppressed because it is too large Load Diff

1603
docs/SQL/01_lcbp3_v1_1_0.sql
View File

File diff suppressed because it is too large Load Diff

1660
docs/SQL/01_lcbp3_v1_1_1.sql
View File

File diff suppressed because it is too large Load Diff

1877
docs/SQL/01_lcbp3_v1_2_0.sql
View File

File diff suppressed because it is too large Load Diff

1870
docs/SQL/01_lcbp3_v1_3_0.sql
View File

File diff suppressed because it is too large Load Diff

1870
docs/SQL/01_lcbp3_v1_3_0.txt
View File

File diff suppressed because it is too large Load Diff

1923
docs/SQL/01_lcbp3_v1_4_0.sql
View File

File diff suppressed because it is too large Load Diff

1923
docs/SQL/01_lcbp3_v1_4_0.txt
View File

File diff suppressed because it is too large Load Diff

385
docs/SQL/Cluad.sql
View File

@@ -1,385 +0,0 @@
-- ปรับปรุงโครงสร้าง Correspondence เพื่อจัดการ Revisions ได้ดีขึ้น
-- 1. แยก Master และ Revision ชัดเจน
CREATE TABLE correspondence_master (
master_id INT AUTO_INCREMENT PRIMARY KEY,
correspondence_number VARCHAR(100) NOT NULL,
project_id INT NOT NULL,
correspondence_type_id INT NOT NULL,
-- Metadata ที่ไม่เปลี่ยนแปลงตาม Revision
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
created_by INT NULL,
deleted_at DATETIME NULL,
-- Track current/latest revision
current_revision_id INT NULL,
latest_revision_number INT NOT NULL DEFAULT 0,
CONSTRAINT uq_corr_no_per_project UNIQUE (project_id, correspondence_number),
CONSTRAINT fk_cm_project FOREIGN KEY (project_id)
REFERENCES projects(project_id) ON UPDATE CASCADE ON DELETE CASCADE,
CONSTRAINT fk_cm_type FOREIGN KEY (correspondence_type_id)
REFERENCES correspondence_types(type_id) ON UPDATE CASCADE ON DELETE RESTRICT,
CONSTRAINT fk_cm_created_by FOREIGN KEY (created_by)
REFERENCES users(user_id) ON UPDATE CASCADE ON DELETE SET NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
-- 2. Revision ที่เก็บข้อมูลที่เปลี่ยนแปลงได้
CREATE TABLE correspondence_revisions_new (
revision_id INT AUTO_INCREMENT PRIMARY KEY,
master_id INT NOT NULL,
revision_number INT NOT NULL, -- เปลี่ยนเป็น INT เพื่อง่ายต่อการเรียงลำดับ
revision_label VARCHAR(10) NULL, -- A, B, C สำหรับแสดงผล
-- สถานะเฉพาะของ Revision นี้
correspondence_status_id INT NOT NULL,
is_current BOOLEAN NOT NULL DEFAULT FALSE,
-- ข้อมูลที่เปลี่ยนแปลงตาม Revision
originator_id INT NULL,
recipient_id INT NULL,
title VARCHAR(255) NOT NULL,
keywords VARCHAR(255) NULL,
issued_date DATETIME NULL,
pdf_path VARCHAR(500) NULL,
details JSON NULL,
-- Audit
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
created_by INT NULL,
change_reason TEXT NULL,
CONSTRAINT uq_master_revision_number UNIQUE (master_id, revision_number),
CONSTRAINT uq_master_current UNIQUE (master_id, is_current), -- ใช้ partial unique index ได้ดีกว่า
CONSTRAINT fk_cr_master FOREIGN KEY (master_id)
REFERENCES correspondence_master(master_id) ON UPDATE CASCADE ON DELETE CASCADE,
CONSTRAINT fk_cr_status FOREIGN KEY (correspondence_status_id)
REFERENCES correspondence_status(status_id) ON UPDATE CASCADE ON DELETE RESTRICT,
CONSTRAINT fk_cr_originator FOREIGN KEY (originator_id)
REFERENCES organizations(org_id) ON UPDATE CASCADE ON DELETE SET NULL,
CONSTRAINT fk_cr_recipient FOREIGN KEY (recipient_id)
REFERENCES organizations(org_id) ON UPDATE CASCADE ON DELETE SET NULL,
CONSTRAINT fk_cr_created_by FOREIGN KEY (created_by)
REFERENCES users(user_id) ON UPDATE CASCADE ON DELETE SET NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
-- 3. Update current_revision_id FK
ALTER TABLE correspondence_master
ADD CONSTRAINT fk_cm_current_revision
FOREIGN KEY (current_revision_id)
REFERENCES correspondence_revisions_new(revision_id)
ON UPDATE CASCADE ON DELETE SET NULL;
-- 4. View สำหรับ Query ง่าย (รวม Master + Current Revision)
CREATE OR REPLACE VIEW v_current_correspondences AS
SELECT
cm.master_id,
cm.correspondence_number,
cm.project_id,
cm.correspondence_type_id,
cr.revision_id,
cr.revision_number,
cr.revision_label,
cr.correspondence_status_id,
cr.title,
cr.keywords,
cr.originator_id,
cr.recipient_id,
cr.issued_date,
cr.pdf_path,
cr.details,
cm.created_at AS master_created_at,
cr.created_at AS revision_created_at,
cm.latest_revision_number
FROM correspondence_master cm
INNER JOIN correspondence_revisions_new cr
ON cm.current_revision_id = cr.revision_id
WHERE cm.deleted_at IS NULL;
-- 5. Stored Procedure สำหรับสร้าง Revision ใหม่
DELIMITER $$
CREATE PROCEDURE sp_create_correspondence_revision(
IN p_master_id INT,
IN p_title VARCHAR(255),
IN p_originator_id INT,
IN p_recipient_id INT,
IN p_status_id INT,
IN p_created_by INT,
IN p_change_reason TEXT,
OUT p_revision_id INT
)
BEGIN
DECLARE v_next_revision_number INT;
DECLARE v_revision_label VARCHAR(10);
-- Get next revision number
SELECT COALESCE(MAX(revision_number), 0) + 1
INTO v_next_revision_number
FROM correspondence_revisions_new
WHERE master_id = p_master_id;
-- Generate label (0->Original, 1->A, 2->B, etc.)
IF v_next_revision_number = 0 THEN
SET v_revision_label = 'Original';
ELSE
SET v_revision_label = CHAR(64 + v_next_revision_number); -- A, B, C...
END IF;
-- Mark all previous revisions as not current
UPDATE correspondence_revisions_new
SET is_current = FALSE
WHERE master_id = p_master_id;
-- Insert new revision
INSERT INTO correspondence_revisions_new (
master_id, revision_number, revision_label,
correspondence_status_id, is_current,
title, originator_id, recipient_id,
created_by, change_reason
) VALUES (
p_master_id, v_next_revision_number, v_revision_label,
p_status_id, TRUE,
p_title, p_originator_id, p_recipient_id,
p_created_by, p_change_reason
);
SET p_revision_id = LAST_INSERT_ID();
-- Update master
UPDATE correspondence_master
SET
current_revision_id = p_revision_id,
latest_revision_number = v_next_revision_number
WHERE master_id = p_master_id;
END$$
DELIMITER ;
-- *****************************************************
-- *****************************************************
-- *****************************************************
-- *****************************************************
-- *****************************************************
-- *****************************************************
-- ปรับปรุง Technical Documents เพื่อความชัดเจนและเชื่อมโยงกับ Correspondence
-- 1. Technical Document Master
CREATE TABLE technical_document_master (
master_id INT AUTO_INCREMENT PRIMARY KEY,
document_number VARCHAR(100) NOT NULL,
document_type_id INT NOT NULL,
project_id INT NOT NULL,
title VARCHAR(255) NOT NULL,
-- Link to RFA Correspondence (optional - เพราะอาจยังไม่ได้ส่ง RFA)
rfa_correspondence_id INT NULL,
-- Tracking
current_revision_id INT NULL,
latest_revision_number INT NOT NULL DEFAULT 0,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
created_by INT NULL,
deleted_at DATETIME NULL,
CONSTRAINT uq_techdoc_no_project UNIQUE (project_id, document_number),
CONSTRAINT fk_tdm_type FOREIGN KEY (document_type_id)
REFERENCES technicaldoc_types(document_types_id),
CONSTRAINT fk_tdm_project FOREIGN KEY (project_id)
REFERENCES projects(project_id) ON DELETE CASCADE,
CONSTRAINT fk_tdm_rfa_corr FOREIGN KEY (rfa_correspondence_id)
REFERENCES correspondences(corr_id) ON DELETE SET NULL,
CONSTRAINT fk_tdm_created_by FOREIGN KEY (created_by)
REFERENCES users(user_id) ON DELETE SET NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
-- 2. Technical Document Revisions
CREATE TABLE technical_document_revisions (
revision_id INT AUTO_INCREMENT PRIMARY KEY,
master_id INT NOT NULL,
revision_number INT NOT NULL,
revision_label VARCHAR(10) NULL, -- A, B, C
status_code_id INT NOT NULL,
approve_code_id INT NULL,
is_current BOOLEAN NOT NULL DEFAULT FALSE,
-- File references
pdf_path VARCHAR(500) NULL,
dwg_path VARCHAR(500) NULL, -- สำหรับ DWG type
-- Metadata
revision_description TEXT NULL,
submitted_date DATE NULL,
approved_date DATE NULL,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
created_by INT NULL,
updated_by INT NULL,
CONSTRAINT uq_master_rev_number UNIQUE (master_id, revision_number),
CONSTRAINT fk_tdr_master FOREIGN KEY (master_id)
REFERENCES technical_document_master(master_id) ON DELETE CASCADE,
CONSTRAINT fk_tdr_status FOREIGN KEY (status_code_id)
REFERENCES technicaldoc_status_codes(status_code_id),
CONSTRAINT fk_tdr_approve FOREIGN KEY (approve_code_id)
REFERENCES technicaldoc_approve_codes(approve_code_id) ON DELETE SET NULL,
CONSTRAINT fk_tdr_created_by FOREIGN KEY (created_by)
REFERENCES users(user_id) ON DELETE SET NULL,
CONSTRAINT fk_tdr_updated_by FOREIGN KEY (updated_by)
REFERENCES users(user_id) ON DELETE SET NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
-- 3. Shop Drawing References (Many-to-Many with Revisions)
CREATE TABLE technical_document_shop_drawing_refs (
tech_doc_revision_id INT NOT NULL,
shop_drawing_rev_id INT NOT NULL,
reference_type ENUM('SUPERSEDES', 'RELATED', 'AS_PER') DEFAULT 'RELATED',
PRIMARY KEY (tech_doc_revision_id, shop_drawing_rev_id),
CONSTRAINT fk_tdsdr_tech_doc FOREIGN KEY (tech_doc_revision_id)
REFERENCES technical_document_revisions(revision_id) ON DELETE CASCADE,
CONSTRAINT fk_tdsdr_shop_dwg FOREIGN KEY (shop_drawing_rev_id)
REFERENCES shop_drawing_revisions(id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
-- 4. Contract Drawing References (Many-to-Many)
CREATE TABLE technical_document_contract_drawing_refs (
tech_doc_revision_id INT NOT NULL,
contract_drawing_id INT NOT NULL,
reference_type ENUM('AS_PER', 'RELATED') DEFAULT 'AS_PER',
sheet_numbers VARCHAR(255) NULL, -- "Sheet 1-5, 10" เก็บเป็น text
PRIMARY KEY (tech_doc_revision_id, contract_drawing_id),
CONSTRAINT fk_tdcdr_tech_doc FOREIGN KEY (tech_doc_revision_id)
REFERENCES technical_document_revisions(revision_id) ON DELETE CASCADE,
CONSTRAINT fk_tdcdr_contract_dwg FOREIGN KEY (contract_drawing_id)
REFERENCES contract_drawings(condwg_id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
-- 5. ปรับปรุง RFA Workflow ให้ชัดเจนขึ้น
CREATE TABLE rfa_workflow_instances (
workflow_id INT AUTO_INCREMENT PRIMARY KEY,
rfa_correspondence_id INT NOT NULL UNIQUE,
template_id INT NULL, -- อ้างอิงถึงแม่แบบที่ใช้
current_step_sequence INT NOT NULL DEFAULT 1,
overall_status ENUM('DRAFT', 'IN_PROGRESS', 'APPROVED', 'REJECTED', 'RETURNED', 'CANCELLED')
NOT NULL DEFAULT 'DRAFT',
started_at DATETIME NULL,
completed_at DATETIME NULL,
CONSTRAINT fk_rwi_corr FOREIGN KEY (rfa_correspondence_id)
REFERENCES correspondences(corr_id) ON DELETE CASCADE,
CONSTRAINT fk_rwi_template FOREIGN KEY (template_id)
REFERENCES technicaldoc_workflow_templates(template_id) ON DELETE SET NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
-- 6. RFA Workflow Steps (แยกจาก technicaldoc_workflows เดิม)
CREATE TABLE rfa_workflow_steps (
step_id INT AUTO_INCREMENT PRIMARY KEY,
workflow_id INT NOT NULL,
sequence INT NOT NULL,
org_id INT NOT NULL,
step_purpose ENUM('FOR_APPROVAL', 'FOR_REVIEW', 'FOR_INFORMATION')
NOT NULL DEFAULT 'FOR_APPROVAL',
status ENUM('PENDING', 'ACTIVE', 'APPROVED', 'REJECTED',
'APPROVED_WITH_COMMENTS', 'SKIPPED', 'RETURNED')
NOT NULL DEFAULT 'PENDING',
approve_code_id INT NULL, -- Link to approve codes
comments TEXT NULL,
activated_at DATETIME NULL,
processed_at DATETIME NULL,
processed_by_user_id INT NULL,
deadline_date DATE NULL,
CONSTRAINT uq_workflow_sequence UNIQUE (workflow_id, sequence),
CONSTRAINT fk_rws_workflow FOREIGN KEY (workflow_id)
REFERENCES rfa_workflow_instances(workflow_id) ON DELETE CASCADE,
CONSTRAINT fk_rws_org FOREIGN KEY (org_id)
REFERENCES organizations(org_id),
CONSTRAINT fk_rws_approve_code FOREIGN KEY (approve_code_id)
REFERENCES technicaldoc_approve_codes(approve_code_id),
CONSTRAINT fk_rws_user FOREIGN KEY (processed_by_user_id)
REFERENCES users(user_id) ON DELETE SET NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
-- 7. View: Current Technical Documents with Latest Revision
CREATE OR REPLACE VIEW v_current_technical_documents AS
SELECT
tdm.master_id,
tdm.document_number,
tdm.document_type_id,
dt.code AS document_type_code,
dt.name AS document_type_name,
tdm.project_id,
tdm.title,
tdm.rfa_correspondence_id,
tdr.revision_id,
tdr.revision_number,
tdr.revision_label,
tdr.status_code_id,
sc.code AS status_code,
sc.description AS status_description,
tdr.approve_code_id,
ac.code AS approve_code,
ac.description AS approve_description,
tdr.pdf_path,
tdr.dwg_path,
tdr.submitted_date,
tdr.approved_date,
tdm.created_at,
tdr.created_at AS revision_created_at
FROM technical_document_master tdm
INNER JOIN technical_document_revisions tdr
ON tdm.current_revision_id = tdr.revision_id
INNER JOIN technicaldoc_types dt
ON tdm.document_type_id = dt.document_types_id
LEFT JOIN technicaldoc_status_codes sc
ON tdr.status_code_id = sc.status_code_id
LEFT JOIN technicaldoc_approve_codes ac
ON tdr.approve_code_id = ac.approve_code_id
WHERE tdm.deleted_at IS NULL;
-- 8. View: RFA Workflow Status
CREATE OR REPLACE VIEW v_rfa_workflow_status AS
SELECT
rwi.workflow_id,
rwi.rfa_correspondence_id,
c.correspondence_number AS rfa_number,
rwi.overall_status,
rwi.current_step_sequence,
rws.step_id AS current_step_id,
rws.org_id AS current_org_id,
o.org_name AS current_org_name,
rws.status AS current_step_status,
rws.deadline_date,
rwi.started_at,
DATEDIFF(CURDATE(), rwi.started_at) AS days_in_progress,
(SELECT COUNT(*) FROM rfa_workflow_steps WHERE workflow_id = rwi.workflow_id) AS total_steps,
(SELECT COUNT(*) FROM rfa_workflow_steps WHERE workflow_id = rwi.workflow_id AND status IN ('APPROVED','APPROVED_WITH_COMMENTS')) AS completed_steps
FROM rfa_workflow_instances rwi
INNER JOIN correspondences c ON rwi.rfa_correspondence_id = c.corr_id
LEFT JOIN rfa_workflow_steps rws
ON rwi.workflow_id = rws.workflow_id
AND rwi.current_step_sequence = rws.sequence
LEFT JOIN organizations o ON rws.org_id = o.org_id
WHERE rwi.overall_status NOT IN ('CANCELLED', 'APPROVED');

215
docs/SQL/seed01.sql
View File

@@ -1,215 +0,0 @@
-- ==========================================================
-- DMS v0.5.0
-- Database v5.1 - Deploy Script Schema (Revised)
-- Server: Container Station on QNAP TS-473A
-- Database service: MariaDB 10.11
-- Notes:
-- - Removed 'rfas' table.
-- - Added 'contracts' and 'contract_parties' tables.
-- ==========================================================
SET NAMES utf8mb4;
SET time_zone = '+07:00';
SET FOREIGN_KEY_CHECKS=0;
-- Drop tables in reverse order of creation due to dependencies
DROP TABLE IF EXISTS audit_logs;
DROP TABLE IF EXISTS user_project_roles;
DROP TABLE IF EXISTS user_roles;
DROP TABLE IF EXISTS role_permissions;
DROP TABLE IF EXISTS permissions;
DROP TABLE IF EXISTS roles;
DROP TABLE IF EXISTS users;
DROP TABLE IF EXISTS project_parties;
DROP TABLE IF EXISTS contract_parties; -- New
DROP TABLE IF EXISTS contracts; -- New
DROP TABLE IF EXISTS projects;
DROP TABLE IF EXISTS organizations;
DROP TABLE IF EXISTS correspondence_references;
DROP TABLE IF EXISTS correspondence_cc_recipients;
DROP TABLE IF EXISTS correspondences;
DROP TABLE IF EXISTS email_details;
DROP TABLE IF EXISTS instruction_details;
DROP TABLE IF EXISTS letter_details;
DROP TABLE IF EXISTS memorandum_details;
DROP TABLE IF EXISTS minutes_of_meeting_details;
DROP TABLE IF EXISTS rfi_details;
DROP TABLE IF EXISTS rfa_items;
DROP TABLE IF EXISTS transmittal_items;
DROP TABLE IF EXISTS transmittals;
DROP TABLE IF EXISTS technicaldocs;
DROP TABLE IF EXISTS shop_drawing_revisions;
DROP TABLE IF EXISTS shop_drawings;
DROP TABLE IF EXISTS shop_drawing_sub_categories;
DROP TABLE IF EXISTS shop_drawing_main_categories;
DROP TABLE IF EXISTS contract_dwg_subcat_cat_map;
DROP TABLE IF EXISTS contract_dwg_sub_cat;
DROP TABLE IF EXISTS contract_dwg_cat;
DROP TABLE IF EXISTS contract_drawings;
DROP TABLE IF EXISTS cir_action_documents;
DROP TABLE IF EXISTS cir_actions;
DROP TABLE IF EXISTS cir_recipients;
DROP TABLE IF EXISTS circulations;
DROP TABLE IF EXISTS cir_status_codes;
DROP TABLE IF EXISTS correspondence_status_transitions;
DROP TABLE IF EXISTS correspondence_statuses;
DROP TABLE IF EXISTS correspondence_types;
DROP TABLE IF EXISTS correspondence_tags;
DROP TABLE IF EXISTS tags;
DROP TABLE IF EXISTS global_default_roles;
SET FOREIGN_KEY_CHECKS=1;
-- ==========================================================
-- Table Creation
-- ==========================================================
-- Organizations Table
CREATE TABLE organizations (
org_id INT NOT NULL AUTO_INCREMENT,
org_code VARCHAR(20) NOT NULL,
org_name VARCHAR(255) NOT NULL,
primary_role ENUM('OWNER','DESIGNER','CONSULTANT','CONTRACTOR') NULL,
is_active BOOLEAN NOT NULL DEFAULT TRUE,
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
PRIMARY KEY (org_id),
UNIQUE KEY ux_organizations_code (org_code)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
-- Projects Table
CREATE TABLE projects (
project_id INT NOT NULL AUTO_INCREMENT,
project_code VARCHAR(20) NOT NULL,
project_name VARCHAR(255) NOT NULL,
description TEXT,
is_active BOOLEAN NOT NULL DEFAULT TRUE,
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
PRIMARY KEY (project_id),
UNIQUE KEY ux_projects_code (project_code)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
-- NEW: Contracts Table
-- Stores information about each contract.
CREATE TABLE contracts (
contract_id INT NOT NULL AUTO_INCREMENT,
contract_code VARCHAR(50) NOT NULL,
contract_name VARCHAR(255) NOT NULL,
description TEXT,
start_date DATE,
end_date DATE,
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
PRIMARY KEY (contract_id),
UNIQUE KEY ux_contracts_code (contract_code)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
-- NEW: Contract Parties Table
-- Links contracts, projects, and organizations together.
CREATE TABLE contract_parties (
contract_id INT NOT NULL,
project_id INT NOT NULL,
org_id INT NOT NULL,
PRIMARY KEY (contract_id, project_id, org_id),
CONSTRAINT fk_cp_contract FOREIGN KEY (contract_id) REFERENCES contracts(contract_id) ON DELETE CASCADE ON UPDATE CASCADE,
CONSTRAINT fk_cp_project FOREIGN KEY (project_id) REFERENCES projects(project_id) ON DELETE CASCADE ON UPDATE CASCADE,
CONSTRAINT fk_cp_org FOREIGN KEY (org_id) REFERENCES organizations(org_id) ON DELETE CASCADE ON UPDATE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
-- Users Table (RBAC)
CREATE TABLE users (
user_id INT NOT NULL AUTO_INCREMENT,
username VARCHAR(50) NOT NULL,
password_hash VARCHAR(255) NOT NULL,
email VARCHAR(100) NOT NULL,
first_name VARCHAR(50),
last_name VARCHAR(50),
org_id INT,
is_active BOOLEAN NOT NULL DEFAULT TRUE,
last_login TIMESTAMP NULL,
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
PRIMARY KEY (user_id),
UNIQUE KEY ux_users_username (username),
UNIQUE KEY ux_users_email (email),
CONSTRAINT fk_users_org FOREIGN KEY (org_id) REFERENCES organizations(org_id) ON DELETE SET NULL ON UPDATE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
-- Roles Table (RBAC)
CREATE TABLE roles (
role_id INT NOT NULL AUTO_INCREMENT,
role_code VARCHAR(50) NOT NULL,
role_name VARCHAR(100) NOT NULL,
description TEXT,
is_system BOOLEAN NOT NULL DEFAULT FALSE,
PRIMARY KEY (role_id),
UNIQUE KEY ux_roles_code (role_code)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
-- Permissions Table (RBAC)
CREATE TABLE permissions (
permission_id INT NOT NULL AUTO_INCREMENT,
permission_code VARCHAR(100) NOT NULL,
description TEXT,
PRIMARY KEY (permission_id),
UNIQUE KEY ux_permissions_code (permission_code)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
-- Role Permissions Junction Table (RBAC)
CREATE TABLE role_permissions (
role_id INT NOT NULL,
permission_id INT NOT NULL,
PRIMARY KEY (role_id, permission_id),
CONSTRAINT fk_rp_role FOREIGN KEY (role_id) REFERENCES roles(role_id) ON DELETE CASCADE ON UPDATE CASCADE,
CONSTRAINT fk_rp_permission FOREIGN KEY (permission_id) REFERENCES permissions(permission_id) ON DELETE CASCADE ON UPDATE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
-- User Roles Junction Table (RBAC) - For global/system-level roles
CREATE TABLE user_roles (
user_id INT NOT NULL,
role_id INT NOT NULL,
PRIMARY KEY (user_id, role_id),
CONSTRAINT fk_ur_user FOREIGN KEY (user_id) REFERENCES users(user_id) ON DELETE CASCADE ON UPDATE CASCADE,
CONSTRAINT fk_ur_role FOREIGN KEY (role_id) REFERENCES roles(role_id) ON DELETE CASCADE ON UPDATE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
-- User Project Roles Junction Table (RBAC) - For project-specific roles
CREATE TABLE user_project_roles (
user_id INT NOT NULL,
project_id INT NOT NULL,
role_id INT NOT NULL,
PRIMARY KEY (user_id, project_id, role_id),
CONSTRAINT fk_upr_user FOREIGN KEY (user_id) REFERENCES users(user_id) ON DELETE CASCADE ON UPDATE CASCADE,
CONSTRAINT fk_upr_project FOREIGN KEY (project_id) REFERENCES projects(project_id) ON DELETE CASCADE ON UPDATE CASCADE,
CONSTRAINT fk_upr_role FOREIGN KEY (role_id) REFERENCES roles(role_id) ON DELETE CASCADE ON UPDATE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
-- Project Parties Table
CREATE TABLE project_parties (
project_id INT NOT NULL,
org_id INT NOT NULL,
role ENUM('OWNER','DESIGNER','CONSULTANT','CONTRACTOR') NOT NULL,
is_contractor TINYINT(1) GENERATED ALWAYS AS (IF(role = 'CONTRACTOR', 1, NULL)) STORED,
PRIMARY KEY (project_id, org_id),
UNIQUE KEY uq_project_parties_contractor (project_id, is_contractor),
CONSTRAINT fk_pp_project FOREIGN KEY (project_id) REFERENCES projects(project_id) ON DELETE CASCADE ON UPDATE CASCADE,
CONSTRAINT fk_pp_org FOREIGN KEY (org_id) REFERENCES organizations(org_id) ON DELETE RESTRICT ON UPDATE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
-- ... (The rest of your original script for correspondences, technical docs, etc. remains here) ...
-- Global default roles (template defaults)
CREATE TABLE global_default_roles (
id TINYINT NOT NULL DEFAULT 1,
role ENUM('OWNER','DESIGNER','CONSULTANT') NOT NULL,
position TINYINT NOT NULL,
org_id INT NOT NULL,
PRIMARY KEY (id, role, position),
UNIQUE KEY ux_gdr_unique_org_per_role (id, role, org_id),
CONSTRAINT fk_gdr_org FOREIGN KEY (org_id) REFERENCES organizations(org_id) ON UPDATE CASCADE ON DELETE RESTRICT
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
-- ... (The rest of your original script continues from here) ...

316
docs/SQL/seed02.sql
View File

@@ -1,316 +0,0 @@
-- ==========================================================
-- DMS v0.5.0
-- Database v5.1 - Deploy Script Schema (Complete & Revised)
-- Server: Container Station on QNAP TS-473A
-- Database service: MariaDB 10.11
-- Notes:
-- - This is a consolidated and updated version.
-- - Removed 'rfas' table.
-- - Added tables for Contracts, detailed Circulations,
-- Technical Document Workflow, and Correspondence Revisions.
-- ==========================================================
SET NAMES utf8mb4;
SET time_zone = '+07:00';
SET FOREIGN_KEY_CHECKS=0;
-- Drop tables in reverse order of creation due to dependencies
DROP TABLE IF EXISTS audit_logs;
DROP TABLE IF EXISTS user_project_roles;
DROP TABLE IF EXISTS user_roles;
DROP TABLE IF EXISTS role_permissions;
DROP TABLE IF EXISTS permissions;
DROP TABLE IF EXISTS roles;
DROP TABLE IF EXISTS users;
DROP TABLE IF EXISTS project_parties;
DROP TABLE IF EXISTS contract_parties;
DROP TABLE IF EXISTS contracts;
DROP TABLE IF EXISTS projects;
DROP TABLE IF EXISTS organizations;
DROP TABLE IF EXISTS correspondence_references;
DROP TABLE IF EXISTS correspondence_revisions;
DROP TABLE IF EXISTS correspondence_cc_recipients;
DROP TABLE IF EXISTS technical_doc_workflows;
DROP TABLE IF EXISTS correspondences;
DROP TABLE IF EXISTS email_details;
DROP TABLE IF EXISTS instruction_details;
DROP TABLE IF EXISTS letter_details;
DROP TABLE IF EXISTS memorandum_details;
DROP TABLE IF EXISTS minutes_of_meeting_details;
DROP TABLE IF EXISTS rfi_details;
DROP TABLE IF EXISTS rfa_items;
DROP TABLE IF EXISTS transmittal_items;
DROP TABLE IF EXISTS transmittals;
DROP TABLE IF EXISTS technicaldocs;
DROP TABLE IF EXISTS shop_drawing_revisions;
DROP TABLE IF EXISTS shop_drawings;
DROP TABLE IF EXISTS shop_drawing_sub_categories;
DROP TABLE IF EXISTS shop_drawing_main_categories;
DROP TABLE IF EXISTS contract_dwg_subcat_cat_map;
DROP TABLE IF EXISTS contract_dwg_sub_cat;
DROP TABLE IF EXISTS contract_dwg_cat;
DROP TABLE IF EXISTS contract_drawings;
DROP TABLE IF EXISTS circulation_assignees;
DROP TABLE IF EXISTS circulations;
DROP TABLE IF EXISTS cir_action_documents;
DROP TABLE IF EXISTS cir_actions;
DROP TABLE IF EXISTS cir_recipients;
DROP TABLE IF EXISTS cir_status_codes;
DROP TABLE IF EXISTS correspondence_status_transitions;
DROP TABLE IF EXISTS correspondence_statuses;
DROP TABLE IF EXISTS correspondence_types;
DROP TABLE IF EXISTS correspondence_tags;
DROP TABLE IF EXISTS tags;
DROP TABLE IF EXISTS global_default_roles;
SET FOREIGN_KEY_CHECKS=1;
-- ==========================================================
-- Table Creation
-- ==========================================================
CREATE TABLE organizations (
org_id INT NOT NULL AUTO_INCREMENT,
org_code VARCHAR(20) NOT NULL,
org_name VARCHAR(255) NOT NULL,
primary_role ENUM('OWNER','DESIGNER','CONSULTANT','CONTRACTOR') NULL,
is_active BOOLEAN NOT NULL DEFAULT TRUE,
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
PRIMARY KEY (org_id),
UNIQUE KEY ux_organizations_code (org_code)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
CREATE TABLE projects (
project_id INT NOT NULL AUTO_INCREMENT,
project_code VARCHAR(20) NOT NULL,
project_name VARCHAR(255) NOT NULL,
description TEXT,
is_active BOOLEAN NOT NULL DEFAULT TRUE,
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
PRIMARY KEY (project_id),
UNIQUE KEY ux_projects_code (project_code)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
CREATE TABLE contracts (
contract_id INT NOT NULL AUTO_INCREMENT,
contract_code VARCHAR(50) NOT NULL,
contract_name VARCHAR(255) NOT NULL,
description TEXT,
start_date DATE,
end_date DATE,
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
PRIMARY KEY (contract_id),
UNIQUE KEY ux_contracts_code (contract_code)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
CREATE TABLE contract_parties (
contract_id INT NOT NULL,
project_id INT NOT NULL,
org_id INT NOT NULL,
PRIMARY KEY (contract_id, project_id, org_id),
CONSTRAINT fk_cp_contract FOREIGN KEY (contract_id) REFERENCES contracts(contract_id) ON DELETE CASCADE ON UPDATE CASCADE,
CONSTRAINT fk_cp_project FOREIGN KEY (project_id) REFERENCES projects(project_id) ON DELETE CASCADE ON UPDATE CASCADE,
CONSTRAINT fk_cp_org FOREIGN KEY (org_id) REFERENCES organizations(org_id) ON DELETE CASCADE ON UPDATE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
CREATE TABLE users (
user_id INT NOT NULL AUTO_INCREMENT,
username VARCHAR(50) NOT NULL,
password_hash VARCHAR(255) NOT NULL,
email VARCHAR(100) NOT NULL,
first_name VARCHAR(50),
last_name VARCHAR(50),
org_id INT,
is_active BOOLEAN NOT NULL DEFAULT TRUE,
last_login TIMESTAMP NULL,
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
PRIMARY KEY (user_id),
UNIQUE KEY ux_users_username (username),
UNIQUE KEY ux_users_email (email),
CONSTRAINT fk_users_org FOREIGN KEY (org_id) REFERENCES organizations(org_id) ON DELETE SET NULL ON UPDATE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
CREATE TABLE roles (
role_id INT NOT NULL AUTO_INCREMENT,
role_code VARCHAR(50) NOT NULL,
role_name VARCHAR(100) NOT NULL,
description TEXT,
is_system BOOLEAN NOT NULL DEFAULT FALSE,
PRIMARY KEY (role_id),
UNIQUE KEY ux_roles_code (role_code)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
CREATE TABLE permissions (
permission_id INT NOT NULL AUTO_INCREMENT,
permission_code VARCHAR(100) NOT NULL,
description TEXT,
PRIMARY KEY (permission_id),
UNIQUE KEY ux_permissions_code (permission_code)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
CREATE TABLE role_permissions (
role_id INT NOT NULL,
permission_id INT NOT NULL,
PRIMARY KEY (role_id, permission_id),
CONSTRAINT fk_rp_role FOREIGN KEY (role_id) REFERENCES roles(role_id) ON DELETE CASCADE ON UPDATE CASCADE,
CONSTRAINT fk_rp_permission FOREIGN KEY (permission_id) REFERENCES permissions(permission_id) ON DELETE CASCADE ON UPDATE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
CREATE TABLE user_roles (
user_id INT NOT NULL,
role_id INT NOT NULL,
PRIMARY KEY (user_id, role_id),
CONSTRAINT fk_ur_user FOREIGN KEY (user_id) REFERENCES users(user_id) ON DELETE CASCADE ON UPDATE CASCADE,
CONSTRAINT fk_ur_role FOREIGN KEY (role_id) REFERENCES roles(role_id) ON DELETE CASCADE ON UPDATE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
CREATE TABLE user_project_roles (
user_id INT NOT NULL,
project_id INT NOT NULL,
role_id INT NOT NULL,
PRIMARY KEY (user_id, project_id, role_id),
CONSTRAINT fk_upr_user FOREIGN KEY (user_id) REFERENCES users(user_id) ON DELETE CASCADE ON UPDATE CASCADE,
CONSTRAINT fk_upr_project FOREIGN KEY (project_id) REFERENCES projects(project_id) ON DELETE CASCADE ON UPDATE CASCADE,
CONSTRAINT fk_upr_role FOREIGN KEY (role_id) REFERENCES roles(role_id) ON DELETE CASCADE ON UPDATE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
CREATE TABLE project_parties (
project_id INT NOT NULL,
org_id INT NOT NULL,
role ENUM('OWNER','DESIGNER','CONSULTANT','CONTRACTOR') NOT NULL,
is_contractor TINYINT(1) GENERATED ALWAYS AS (IF(role = 'CONTRACTOR', 1, NULL)) STORED,
PRIMARY KEY (project_id, org_id),
UNIQUE KEY uq_project_parties_contractor (project_id, is_contractor),
CONSTRAINT fk_pp_project FOREIGN KEY (project_id) REFERENCES projects(project_id) ON DELETE CASCADE ON UPDATE CASCADE,
CONSTRAINT fk_pp_org FOREIGN KEY (org_id) REFERENCES organizations(org_id) ON DELETE RESTRICT ON UPDATE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
-- Correspondence & Workflow Tables
CREATE TABLE correspondence_types (
type_id INT NOT NULL AUTO_INCREMENT,
type_code VARCHAR(20) NOT NULL,
type_name VARCHAR(100) NOT NULL,
PRIMARY KEY (type_id),
UNIQUE KEY ux_ct_code (type_code)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
CREATE TABLE correspondence_statuses (
status_id INT NOT NULL AUTO_INCREMENT,
status_code VARCHAR(20) NOT NULL,
status_name VARCHAR(100) NOT NULL,
PRIMARY KEY (status_id),
UNIQUE KEY ux_cs_code (status_code)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
CREATE TABLE correspondences (
id INT NOT NULL AUTO_INCREMENT,
project_id INT NOT NULL,
document_number VARCHAR(100) NOT NULL,
title VARCHAR(500) NOT NULL,
issue_date DATE NOT NULL,
status_id INT NOT NULL,
type_id INT NOT NULL,
originator_org_id INT NOT NULL,
created_by_user_id INT NOT NULL,
root_id INT NULL, -- for revisions
version INT NOT NULL DEFAULT 1,
submitted_at TIMESTAMP NULL,
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
PRIMARY KEY (id),
UNIQUE KEY ux_corr_doc_num (document_number),
CONSTRAINT fk_corr_project FOREIGN KEY (project_id) REFERENCES projects(project_id),
CONSTRAINT fk_corr_status FOREIGN KEY (status_id) REFERENCES correspondence_statuses(status_id),
CONSTRAINT fk_corr_type FOREIGN KEY (type_id) REFERENCES correspondence_types(type_id),
CONSTRAINT fk_corr_org FOREIGN KEY (originator_org_id) REFERENCES organizations(org_id),
CONSTRAINT fk_corr_user FOREIGN KEY (created_by_user_id) REFERENCES users(user_id),
CONSTRAINT fk_corr_root FOREIGN KEY (root_id) REFERENCES correspondences(id) ON DELETE SET NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
CREATE TABLE correspondence_revisions (
revision_id INT NOT NULL AUTO_INCREMENT,
correspondence_id INT NOT NULL,
version_number INT NOT NULL,
change_reason TEXT NOT NULL,
changed_by_user_id INT NOT NULL,
changed_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
document_data_json JSON NOT NULL,
PRIMARY KEY (revision_id),
CONSTRAINT fk_cr_correspondence FOREIGN KEY (correspondence_id) REFERENCES correspondences(id) ON DELETE CASCADE,
CONSTRAINT fk_cr_user FOREIGN KEY (changed_by_user_id) REFERENCES users(user_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
CREATE TABLE cir_status_codes (
code VARCHAR(20) NOT NULL,
description VARCHAR(255),
sort_order INT NOT NULL,
PRIMARY KEY (code)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
CREATE TABLE circulations (
cir_id INT NOT NULL AUTO_INCREMENT,
correspondence_id INT NOT NULL,
org_id INT NOT NULL,
cir_subject VARCHAR(500) NOT NULL,
cir_status_code VARCHAR(20) NOT NULL DEFAULT 'DRAFT',
created_by_user_id INT NOT NULL,
submitted_at TIMESTAMP NULL,
closed_at TIMESTAMP NULL,
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
PRIMARY KEY (cir_id),
CONSTRAINT fk_cir_correspondence FOREIGN KEY (correspondence_id) REFERENCES correspondences(id),
CONSTRAINT fk_cir_org FOREIGN KEY (org_id) REFERENCES organizations(org_id),
CONSTRAINT fk_cir_status FOREIGN KEY (cir_status_code) REFERENCES cir_status_codes(code),
CONSTRAINT fk_cir_user FOREIGN KEY (created_by_user_id) REFERENCES users(user_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
CREATE TABLE circulation_assignees (
assignee_id INT NOT NULL AUTO_INCREMENT,
cir_id INT NOT NULL,
user_id INT NOT NULL,
assignee_type ENUM('MAIN', 'ACTION', 'INFO') NOT NULL,
deadline DATE NULL,
action_taken TEXT NULL,
is_completed BOOLEAN NOT NULL DEFAULT FALSE,
completed_at TIMESTAMP NULL,
PRIMARY KEY (assignee_id),
UNIQUE KEY ux_cir_user_type (cir_id, user_id, assignee_type),
CONSTRAINT fk_ca_cir FOREIGN KEY (cir_id) REFERENCES circulations(cir_id) ON DELETE CASCADE,
CONSTRAINT fk_ca_user FOREIGN KEY (user_id) REFERENCES users(user_id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
CREATE TABLE technical_doc_workflows (
workflow_id INT NOT NULL AUTO_INCREMENT,
correspondence_id INT NOT NULL,
sequence INT NOT NULL,
org_id INT NOT NULL,
status ENUM('PENDING', 'APPROVED', 'REJECTED', 'APPROVED_WITH_COMMENTS', 'FORWARDED', 'RETURNED') NOT NULL DEFAULT 'PENDING',
comments TEXT,
processed_by_user_id INT NULL,
processed_at TIMESTAMP NULL,
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
PRIMARY KEY (workflow_id),
UNIQUE KEY ux_workflow_corr_sequence (correspondence_id, sequence),
CONSTRAINT fk_tdw_correspondence FOREIGN KEY (correspondence_id) REFERENCES correspondences(id) ON DELETE CASCADE,
CONSTRAINT fk_tdw_org FOREIGN KEY (org_id) REFERENCES organizations(org_id),
CONSTRAINT fk_tdw_user FOREIGN KEY (processed_by_user_id) REFERENCES users(user_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
CREATE TABLE correspondence_status_transitions(
type_id INT NOT NULL,
from_status_id INT NOT NULL,
to_status_id INT NOT NULL,
PRIMARY KEY (type_id, from_status_id, to_status_id),
CONSTRAINT fk_cst_type FOREIGN KEY (type_id) REFERENCES correspondence_types(type_id),
CONSTRAINT fk_cst_from FOREIGN KEY (from_status_id) REFERENCES correspondence_statuses(status_id),
CONSTRAINT fk_cst_to FOREIGN KEY (to_status_id) REFERENCES correspondence_statuses(status_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
-- (The rest of your original tables for technical docs, drawings, etc. would follow here)
-- For brevity, I've included the core structure. You can append the remaining tables from your original file.

143
docs/SQL/temp.sql
View File

@@ -1,143 +0,0 @@
SET NAMES utf8mb4;
SET time_zone = '+07:00';
SET FOREIGN_KEY_CHECKS=0;
-- ==========================================================
-- 1. ลบ Stored Procedure เก่า (ย้าย Logic ไป NestJS)
-- ==========================================================
-- ตรรกะนี้ (การสร้าง Revision) จะถูกย้ายไปจัดการใน
-- CorrespondenceService และ RfaService ของ NestJS
DROP PROCEDURE IF EXISTS sp_create_correspondence_revision;
-- ==========================================================
-- 2. สร้าง Stored Procedure ใหม่ (สำหรับ Document Numbering)
-- ==========================================================
-- ใช้ Procedure นี้เพื่อจัดการ Race Condition
-- ในการดึงเลขที่เอกสารล่าสุด
-- ----------------------------------------------------------
DELIMITER $$
CREATE PROCEDURE sp_get_next_document_number(
IN p_project_id INT,
IN p_organization_id INT,
IN p_type_id INT,
IN p_year INT,
OUT p_next_number INT
)
BEGIN
DECLARE v_last_number INT;
-- 1. พยายามดึงแถวปัจจุบันและ "ล็อก" (FOR UPDATE)
-- เพื่อป้องกันไม่ให้ Transaction อื่นอ่านค่านี้จนกว่าเราจะเสร็จ
SELECT last_number
INTO v_last_number
FROM document_number_counters
WHERE
project_id = p_project_id AND
originator_organization_id = p_organization_id AND
correspondence_type_id = p_type_id AND
current_year = p_year
FOR UPDATE;
-- 2. ตรวจสอบว่าพบบแถวหรือไม่
IF v_last_number IS NULL THEN
-- 2a. ไม่พบ (นี่คือเลขที่ "1" ของ Key นี้)
INSERT INTO document_number_counters
(project_id, originator_organization_id, correspondence_type_id, current_year, last_number)
VALUES
(p_project_id, p_organization_id, p_type_id, p_year, 1);
SET p_next_number = 1;
ELSE
-- 2b. พบ (บวกเลขที่เดิม)
SET p_next_number = v_last_number + 1;
UPDATE document_number_counters
SET last_number = p_next_number
WHERE
project_id = p_project_id AND
originator_organization_id = p_organization_id AND
correspondence_type_id = p_type_id AND
current_year = p_year;
END IF;
-- (Transaction จะ Commit อัตโนมัติเมื่อ Procedure จบ)
END$$
DELIMITER ;
-- ==========================================================
-- 3. สร้าง Views (สำหรับช่วย Backend/Frontend)
-- ==========================================================
-- ----------------------------------------------------------
-- View 1: v_user_tasks (สำหรับ Dashboard "งานของฉัน" Req 5.3)
-- ----------------------------------------------------------
CREATE OR REPLACE VIEW v_user_tasks AS
SELECT
ca.user_id,
c.id AS circulation_id,
c.organization_id,
c.circulation_no,
c.circulation_subject,
ca.assignee_type,
ca.deadline,
c.created_at,
c.correspondence_id
FROM circulations c
JOIN circulation_assignees ca ON c.id = ca.circulation_id
WHERE
ca.is_completed = FALSE
AND ca.assignee_type IN ('MAIN', 'ACTION');
-- ----------------------------------------------------------
-- View 2: v_audit_log_details (สำหรับ Activity Feed Req 6.1)
-- ----------------------------------------------------------
CREATE OR REPLACE VIEW v_audit_log_details AS
SELECT
al.audit_id,
al.user_id,
al.action,
al.entity_type,
al.entity_id,
al.details_json,
al.ip_address,
al.created_at,
u.username,
u.first_name,
u.last_name,
u.email
FROM audit_logs al
LEFT JOIN users u ON al.user_id = u.user_id;
-- ----------------------------------------------------------
-- View 3: v_user_all_permissions (สำหรับ RBAC 2 ระดับ Req 4.2)
-- ----------------------------------------------------------
-- View นี้จะรวมสิทธิ์ 2 ระดับ (Global และ Project)
-- (หมายเหตุ: ไม่รวม Contract-level เนื่องจากยังไม่มีตาราง)
-- ----------------------------------------------------------
CREATE OR REPLACE VIEW v_user_all_permissions AS
-- 1. สิทธิ์ระดับ Global (project_id IS NULL)
SELECT
ur.user_id,
NULL AS project_id,
p.permission_code
FROM user_roles ur
JOIN role_permissions rp ON ur.role_id = rp.role_id
JOIN permissions p ON rp.permission_id = p.permission_id
UNION
-- 2. สิทธิ์ระดับ Project
SELECT
upr.user_id,
upr.project_id,
p.permission_code
FROM user_project_roles upr
JOIN role_permissions rp ON upr.role_id = rp.role_id
JOIN permissions p ON rp.permission_id = p.permission_id;
SET FOREIGN_KEY_CHECKS=1;

47
docs/SQL/triggers.sql
View File

@@ -1,47 +0,0 @@
-- trigger
DROP TRIGGER IF EXISTS trg_rfa_revisions_is_current;
DROP TRIGGER IF EXISTS trg_rfa_revisions_is_current_upd;
DROP TRIGGER IF EXISTS trg_rfa_revisions_auto_reset;
-- ============================================================
-- ⚙️ TRIGGERS
-- ============================================================
-- ป้องกันไม่ให้มี revision ที่ is_current=TRUE ซ้ำใน rfa_id เดียวกัน
DELIMITER $$
CREATE TRIGGER trg_rfa_revisions_is_current
BEFORE INSERT ON rfa_revisions
FOR EACH ROW
BEGIN
IF NEW.is_current = TRUE THEN
IF (SELECT COUNT(*) FROM rfa_revisions WHERE rfa_id = NEW.rfa_id AND is_current = TRUE) > 0 THEN
SIGNAL SQLSTATE '45000'
SET MESSAGE_TEXT = 'Cannot insert more than one current revision per RFA.';
END IF;
END IF;
END$$
DELIMITER ;
DELIMITER $$
CREATE TRIGGER trg_rfa_revisions_is_current_upd
BEFORE UPDATE ON rfa_revisions
FOR EACH ROW
BEGIN
IF NEW.is_current = TRUE AND (OLD.is_current IS NULL OR OLD.is_current = FALSE) THEN
IF (SELECT COUNT(*) FROM rfa_revisions WHERE rfa_id = NEW.rfa_id AND is_current = TRUE AND correspondences_id <> OLD.correspondences_id) > 0 THEN
SIGNAL SQLSTATE '45000'
SET MESSAGE_TEXT = 'Cannot set more than one current revision per RFA.';
END IF;
END IF;
END$$
DELIMITER ;
-- ทำให้เวลาสร้าง revision ใหม่ที่ is_current=TRUE ระบบจะ set revision เดิมเป็น FALSE อัตโนมัติ
DELIMITER $$
CREATE TRIGGER trg_rfa_revisions_auto_reset
BEFORE INSERT ON rfa_revisions
FOR EACH ROW
BEGIN
IF NEW.is_current = TRUE THEN
UPDATE rfa_revisions
SET is_current = FALSE
WHERE rfa_id = NEW.rfa_id;
END IF;
END$$
DELIMITER ;

171
docs/backend_setup.bak
View File

@@ -1,171 +0,0 @@
# การติดตั้งและสร้างโปรเจกต์ (Project Initialization)
1. ข้อกำหนดเบื้องต้น (Prerequisites)
ก่อนเริ่ม, ตรวจสอบให้แน่ใจว่าคุณมีเครื่องมือเหล่านี้ติดตั้งบน Windows 11 ของคุณแล้ว:
Node.js: เวอร์ชัน 18.x หรือสูงกว่า
NPM หรือ Yarn: ตัวจัดการ Package (มักจะมาพร้อมกับ Node.js)
NestJS CLI: เครื่องมือ Command-line สำหรับ NestJS
หากยังไม่ได้ติดตั้ง NestJS CLI, ให้เปิด VS Code Terminal หรือ Command Prompt แล้วรันคำสั่ง:
bash
npm install -g @nestjs/cli
## 2.1 สร้างโปรเจกต์ NestJS ใหม่
ไปที่ Directory ที่คุณต้องการเก็บโปรเจกต์ (เช่น C:\Users\YourUser\Development\)
ใช้ NestJS CLI เพื่อสร้างโปรเจกต์ใหม่ ผมจะตั้งชื่อว่า backend-np-dms นะครับ:
Bash
nest new backend
ระบบจะถามว่าต้องการใช้ Package Manager ตัวไหน แนะนำให้เลือก npm, รอจนกว่ากระบวนการจะเสร็จสิ้น คุณจะได้โฟลเดอร์ backend ที่มีโครงสร้างพื้นฐานของ NestJS พร้อมใช้งาน
## 2.2 ติดตั้ง Dependencies ที่จำเป็น
ตอนนี้เราจะติดตั้ง Modules ทั้งหมดที่คุณวางแผนไว้ในคราวเดียว เพื่อให้โปรเจกต์พร้อมสำหรับการพัฒนา
เปิด Terminal ใน VS Code ภายในโฟลเดอร์ backend (cd backend) แล้วรันคำสั่งต่อไปนี้:
* Database & ORM (TypeORM for MariaDB/MySQL)
Bash
npm install @nestjs/typeorm typeorm mysql2
* Configuration Management (สำหรับ .env)
npm install @nestjs/config
* API Documentation
npm install @nestjs/swagger
* Validation & Transformation
npm install class-validator class-transformer
* Security
npm install helmet
* Authentication (JWT)
npm install @nestjs/passport passport passport-jwt @nestjs/jwt
npm install --save-dev @types/passport-jwt
คำอธิบาย:
@nestjs/typeorm typeorm mysql2: สำหรับเชื่อมต่อและจัดการฐานข้อมูล MariaDB
@nestjs/config: สำหรับจัดการ Environment Variables (เช่น ข้อมูลการเชื่อมต่อ DB) ผ่านไฟล์ .env
@nestjs/swagger: สำหรับสร้างหน้าเอกสาร API (Swagger/OpenAPI) โดยอัตโนมัติ
class-validator class-transformer: ใช้สำหรับตรวจสอบความถูกต้องของข้อมูลที่ส่งเข้ามาใน API (Request Body Validation)
helmet: ช่วยเพิ่มความปลอดภัยพื้นฐานโดยการตั้งค่า HTTP Headers ที่เหมาะสม
@nestjs/passport, @nestjs/jwt: เครื่องมือมาตรฐานสำหรับทำระบบ Authentication
## 2.3: ตั้งค่าพื้นฐานในโปรเจกต์ (Initial Configuration)
ตอนนี้เราจะแก้ไขไฟล์หลักๆ เพื่อเปิดใช้งาน Modules ที่ติดตั้งไป
1. สร้างไฟล์ Environment (.env)
ที่ราก (root) ของโปรเจกต์ backend-np-dms, สร้างไฟล์ใหม่ชื่อ .env และใส่ข้อมูลการเชื่อมต่อฐานข้อมูลของคุณ (ข้อมูลนี้จะไม่ถูกเก็บใน Git):
.env
Code snippet
* Database Configuration
DB_TYPE=mysql
DB_HOST=localhost
DB_PORT=3306
DB_USERNAME=your_db_user # <-- แก้ไขเป็น user ของคุณ
DB_PASSWORD=your_db_password # <-- แก้ไขเป็น password ของคุณ
DB_DATABASE=dms_db # <-- แก้ไขเป็นชื่อ database ของคุณ
* Application
API_PORT=3001
💡 Tip: หากคุณรัน MariaDB ผ่าน Docker, DB_HOST อาจจะเป็นชื่อ Service ของ Docker container (เช่น mariadb-container) หรือ IP ของ QNAP ของคุณ
2. แก้ไข app.module.ts เพื่อเชื่อมต่อ Database และ Config
เปิดไฟล์ src/app.module.ts และแก้ไขให้เป็นตามนี้เพื่อ import ConfigModule และ TypeOrmModule:
src/app.module.ts
```TypeScript
import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { TypeOrmModule } from '@nestjs/typeorm';
import { AppController } from './app.controller';
import { AppService } from './app.service';
@Module({
imports: [
// 1. Config Module - สำหรับอ่าน .env (ต้องอยู่บนสุด)
ConfigModule.forRoot({
isGlobal: true, // ทำให้ ConfigService พร้อมใช้งานทั่วทั้งแอป
envFilePath: '.env',
}),
// 2. TypeORM Module - สำหรับเชื่อมต่อ Database
TypeOrmModule.forRootAsync({
imports: [ConfigModule],
inject: [ConfigService],
useFactory: (configService: ConfigService) => ({
type: 'mysql',
host: configService.get<string>('DB_HOST'),
port: configService.get<int>('DB_PORT'),
username: configService.get<string>('DB_USERNAME'),
password: configService.get<string>('DB_PASSWORD'),
database: configService.get<string>('DB_DATABASE'),
entities: [__dirname + '/../**/*.entity{.ts,.js}'],
synchronize: true, // สำหรับ Development เท่านั้น! จะสร้างตารางให้อัตโนมัติ
logging: true,
}),
}),
],
controllers: [AppController],
providers: [AppService],
})
export class AppModule {}
```
⚠️ คำเตือน: synchronize: true สะดวกมากในช่วงพัฒนาเพราะมันจะปรับโครงสร้างตารางตาม Entity ให้อัตโนมัติ ห้ามใช้ใน Production เด็ดขาด เพราะอาจทำให้ข้อมูลหายได้ ใน Production ควรใช้ระบบ Migration แทน
3. แก้ไข main.ts เพื่อเปิดใช้งาน Swagger, Validation และ Security
เปิดไฟล์ src/main.ts และเพิ่มการตั้งค่าต่างๆ เข้าไป:
src/main.ts
TypeScript
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { ValidationPipe } from '@nestjs/common';
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
import helmet from 'helmet';
async function bootstrap() {
const app = await NestFactory.create(AppModule);
// เปิดใช้งาน CORS (Cross-Origin Resource Sharing)
app.enableCors();
// เพิ่ม Helmet เพื่อความปลอดภัย
app.use(helmet());
// ตั้งค่า Global Validation Pipe
app.useGlobalPipes(new ValidationPipe({
whitelist: true, // ตัด property ที่ไม่มีใน DTO ออก
transform: true, // แปลงข้อมูลให้เป็น type ที่ระบุใน DTO
}));
// ตั้งค่า Swagger API Documentation
const config = new DocumentBuilder()
.setTitle('LCBP3-DMS API')
.setDescription('The Document Management System API for LCBP3 Project')
.setVersion('1.0')
.addBearerAuth() // สำหรับ JWT
.build();
const document = SwaggerModule.createDocument(app, config);
SwaggerModule.setup('api-docs', app, document); // เข้าถึงได้ที่ /api-docs
// เริ่มรัน Server
const port = process.env.API_PORT || 3001;
await app.listen(port);
console.log(`Application is running on: ${await app.getUrl()}`);
}
bootstrap();
curl -i -X POST \
-H "Content-Type: application/json" \
-d '{"username": "superadmin", "password": "Center#2025"}' \
https://backend.np-dms.work/api/auth/login

17
docs/features.bak
View File

@@ -1,17 +0,0 @@
ฟีเจอร์ขั้นสูง (Advanced Features)
Error Handling: ใช้ Global Exception Filter เพื่อจัดการ Error และส่ง Response ที่เป็นมาตรฐาน
Logging: ใช้ Winston สำหรับ Structured Logging และบันทึก Error ลงไฟล์
Testing: มีโครงสร้างสำหรับ Unit Test และ E2E Test ด้วย Jest และ Supertest
Performance: ใช้ CacheModule สำหรับ Caching ข้อมูลที่เรียกใช้บ่อย
Security:
Rate Limiting: ใช้ ThrottlerModule เพื่อป้องกัน Brute-force attack
Secret Management: แนะนำให้ใช้ Environment Variable ของ Docker แทนไฟล์ .env ใน Production
API Documentation: สร้างเอกสาร API อัตโนมัติด้วย @nestjs/swagger และเข้าถึงได้ที่ /api-docs

19
docs/test.sql Normal file
View File

@@ -0,0 +1,19 @@
-- 1. สร้าง Template ชื่อ "General Approval"
INSERT INTO correspondence_routing_templates (id, template_name, description, is_active)
VALUES (
1,
'General Approval',
'Template สำหรับการอนุมัติทั่วไป',
1
);
-- 2. สร้าง Steps (ส่งไป Org ID 1 ก่อน แล้วส่งไป Org ID 2)
-- (สมมติว่า Org ID 1 = Owner, Org ID 2 = Consultant ตาม Seed Data เดิม)
INSERT INTO correspondence_routing_template_steps (
template_id,
sequence,
to_organization_id,
step_purpose,
expected_days
)
VALUES (1, 1, 22, 'FOR_REVIEW', 3),
(1, 2, 1, 'FOR_APPROVAL', 5);

192
docs/workflow.bak
View File

@@ -1,192 +0,0 @@
## Workflow ระดับ Project (correspondence_routing_steps, technical_doc_workflows): คือ "การเดินทาง" ของเอกสาร ระหว่างองค์กร (เช่น จากผู้รับเหมา -> ไปยังที่ปรึกษา -> ไปยังเจ้าของโครงการ)
## Workflow ระดับ Organization (Circulation): คือ "การแจกจ่าย" เอกสาร ภายในองค์กรของคุณเอง หลังจากที่คุณได้รับเอกสารนั้นมาแล้ว (เช่น เอกสารมาถึง Document Control แล้วต้องส่งต่อให้ใครบ้างในบริษัท)
circulation_templates: ตารางหลักสำหรับเก็บชื่อแม่แบบ
circulation_template_assignees: ตารางสำหรับเก็บ "รายชื่อผู้รับผิดชอบ" ที่ถูกกำหนดไว้ในแต่ละแม่แบบ
Workflow การทำงานใน Frontend
1. หน้า Admin Panel: จะต้องมีเมนูใหม่สำหรับให้ Admin หรือผู้มีสิทธิ์ เข้าไป สร้าง/แก้ไข/ลบ แม่แบบใบเวียน (circulation_templates) สำหรับองค์กรของตนเองได้
2. หน้าที่สร้างใบเวียน (Create Circulation Dialog):
* ที่ด้านบนสุดของฟอร์ม จะมี Dropdown ใหม่ ปรากฏขึ้นมา เขียนว่า "ใช้แม่แบบ (Use Template)"
* ใน Dropdown นี้ จะแสดงรายชื่อแม่แบบทั้งหมดที่องค์กรนั้นๆ สร้างไว้
* เมื่อผู้ใช้เลือกแม่แบบ:
** ระบบจะยิง API ไปดึงรายชื่อผู้รับผิดชอบจากตาราง circulation_template_assignees
** จากนั้น JavaScript จะทำการเติมข้อมูล (Auto-populate) ลงในช่อง "Main", "Action", และ "Information" ให้โดยอัตโนมัติ
* ผู้ใช้ยังสามารถ แก้ไข/เพิ่มเติม/ลบ รายชื่อผู้รับผิดชอบได้ตามต้องการ ก่อนที่จะกดสร้างใบเวียนจริง
การจัดการข้อมูล JSON จะเกิดขึ้นใน 3 ส่วนหลักๆ คือ Backend, Frontend, และ Database ครับ
## 1. การจัดการในฝั่ง Backend (NestJS)
นี่คือส่วนที่ทำหน้าที่หลักในการสร้างและอ่านข้อมูล JSON อย่างเป็นระบบและปลอดภัย
1.1 การแก้ไข Entity
เราจะแก้ไข Correspondence entity โดยเพิ่มคอลัมน์ details เข้าไป และลบ Entity ย่อยๆ ที่ไม่ใช้ออก
src/correspondences/entities/correspondence.entity.ts
@Entity('correspondences')
export class Correspondence {
// ... (คอลัมน์เดิมทั้งหมด: id, document_number, title, etc.)
@Column({
type: 'json', // ◀️ กำหนดประเภทข้อมูลเป็น JSON
nullable: true,
comment: 'เก็บข้อมูลเฉพาะของเอกสารแต่ละประเภทในรูปแบบ JSON'
})
details: any; // ◀️ ใช้ type 'any' หรือสร้าง Interface/Type ที่ซับซ้อนขึ้น
}
1.2 การสร้าง DTOs สำหรับแต่ละประเภทเอกสาร
เพื่อรักษาความถูกต้องของข้อมูล (Validation) เราจะสร้าง DTO แยกสำหรับเอกสารแต่ละประเภท
ตัวอย่าง src/correspondences/dto/create-letter.dto.ts:
TypeScript
import { ApiProperty } from '@nestjs/swagger';
import { IsNotEmpty, IsString } from 'class-validator';
// DTO สำหรับข้อมูลใน details ของ Letter
class LetterDetailsDto {
@ApiProperty()
@IsString()
@IsNotEmpty()
attention_to: string;
@ApiProperty()
@IsString()
@IsNotEmpty()
signatory_name: string;
}
// DTO หลักสำหรับสร้าง Letter
export class CreateLetterDto {
@ApiProperty({ description: "ข้อมูลพื้นฐานของเอกสาร" })
@ValidateNested() // ◀️ บอกให้ class-validator ตรวจสอบ object ข้างในด้วย
@Type(() => CreateCorrespondenceDto) // ◀️ ใช้ DTO พื้นฐานร่วมกัน
base_data: CreateCorrespondenceDto;
@ApiProperty({ description: "ข้อมูลเฉพาะของ Letter" })
@ValidateNested()
@Type(() => LetterDetailsDto)
details: LetterDetailsDto;
}
1.3 การสร้าง API Endpoint และ Logic ใน Service
เราจะสร้าง Endpoint แยกสำหรับสร้างเอกสารแต่ละประเภทเพื่อความชัดเจน
ใน CorrespondencesController:
TypeScript
@Post('letter')
@ApiOperation({ summary: 'Create a new Letter' })
createLetter(@Body() createLetterDto: CreateLetterDto, @Req() req: Request) {
const user = req.user as any;
return this.correspondencesService.createTypedCorrespondence(
createLetterDto.base_data,
createLetterDto.details,
user
);
}
ใน CorrespondencesService:
TypeScript
async createTypedCorrespondence(baseData: CreateCorrespondenceDto, details: any, user: User): Promise<Correspondence> {
// ... (โค้ดตรวจสอบสิทธิ์เหมือนเดิม)
const newCorrespondence = this.correspondenceRepository.create({
...baseData, // ข้อมูลพื้นฐาน (เลขที่เอกสาร, ชื่อเรื่อง, etc.)
details: details, // ◀️ นำ object ของ details มาใส่ในคอลัมน์ JSON โดยตรง
created_by_user_id: user.user_id,
originator_org_id: user.org_id,
status_id: 1, // 'Draft'
});
return this.correspondenceRepository.save(newCorrespondence);
}
## 2. การจัดการในฝั่ง Frontend (Next.js / React)
Frontend จะทำหน้าที่แสดงฟอร์มที่ถูกต้องตามประเภทเอกสาร และส่งข้อมูลในรูปแบบที่ Backend ต้องการ
2.1 การแสดงฟอร์มแบบไดนามิก (Dynamic Forms)
ในหน้า "Create Correspondence" เมื่อผู้ใช้เลือกประเภทเอกสารจาก Dropdown เราจะใช้ State เพื่อแสดงฟอร์มที่ถูกต้อง
TypeScript
const [docType, setDocType] = useState('LETTER');
// ...
const renderDetailFields = () => {
switch (docType) {
case 'LETTER':
return (
<>
{/* ฟิลด์สำหรับ Attention To, Signatory */}
</>
);
case 'RFI':
return (
<>
{/* ฟิลด์สำหรับ Question, Required By Date */}
</>
);
default:
return null;
}
}
return (
<form>
{/* ฟิลด์พื้นฐาน (Document Number, Title) */}
{/* Dropdown เลือกประเภทเอกสาร */}
{renderDetailFields()} {/* ◀️ แสดงฟิลด์เฉพาะทางที่นี่ */}
</form>
);
2.2 การส่งข้อมูล
เมื่อผู้ใช้กด Submit เราจะรวบรวมข้อมูลจากฟอร์มให้เป็นโครงสร้าง JSON ที่ Backend ต้องการ
JavaScript
const handleSubmit = () => {
// รวบรวมข้อมูลพื้นฐาน
const base_data = {
document_number: '...',
title: '...',
// ...
};
// รวบรวมข้อมูลเฉพาะทาง
const details = {
attention_to: '...',
signatory_name: '...',
};
// ส่งข้อมูลไปที่ API Endpoint ที่ถูกต้อง
fetch('/api/correspondences/letter', {
method: 'POST',
body: JSON.stringify({ base_data, details }),
});
}
## 3. การจัดการในระดับฐานข้อมูล (MariaDB)
แม้ว่าเราจะไม่ค่อยได้ Query ข้อมูล JSON โดยตรงผ่าน SQL บ่อยนัก แต่ก็สามารถทำได้เมื่อจำเป็น (เช่น สำหรับการทำรายงานที่ซับซ้อน)
ตัวอย่าง: ค้นหาเอกสาร Letter ทั้งหมดที่ส่งถึง "Mr. John Doe"
SQL
SELECT
corr_id,
document_number,
details
FROM
correspondences
WHERE
type_id = (SELECT type_id FROM correspondence_types WHERE type_code = 'LETTER') -- กรองเฉพาะ Letter
AND JSON_VALUE(details, '$.attention_to') = 'Mr. John Doe'; -- ◀️ ค้นหาค่าใน JSON
การจัดการข้อมูลด้วยวิธีนี้จะทำให้ระบบของคุณมีความ