Prepare to version 1.5 use spec-kit

infrastructure/Markdown/LCBP3-DMS Requirements Specification.bak

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