260222:1053 20260222 refactor specs/ #1 03-Data-and-Storage

specs/01-requirements/modules/01-03.1-project-management.md

@@ -0,0 +1,24 @@
+# 3.1 Project Management (การจัดการโครงสร้างโครงการและองค์กร)
+
+---
+
+title: "Functional Requirements: Project Management"
+version: 1.5.0
+status: first-draft
+owner: Nattanin Peancharoen
+last_updated: 2025-11-30
+related:
+
+- specs/01-requirements/01-objectives.md
+- specs/01-requirements/02-architecture.md
+- specs/01-requirements/03-functional-requirements.md
+
+---
+
+## Details (รายละเอียด)
+
+- 3.1.1. โครงการ (Projects): ระบบต้องสามารถจัดการเอกสารภายในหลายโครงการได้ (ปัจจุบันมี 4 โครงการ และจะเพิ่มขึ้นในอนาคต)
+- 3.1.2. สัญญา (Contracts): ระบบต้องสามารถจัดการเอกสารภายในแต่ละสัญญาได้ ในแต่ละโครงการ มีได้หลายสัญญา หรืออย่างน้อย 1 สัญญา
+- 3.1.3. องค์กร (Organizations):
+  - มีหลายองค์กรในโครงการ องค์กรณ์ที่เป็น Owner, Designer และ Consultant สามารถอยู่ในหลายโครงการและหลายสัญญาได้
+  - Contractor จะถือ 1 สัญญา และอยู่ใน 1 โครงการเท่านั้น

specs/01-requirements/modules/01-03.12-json-details.md

@@ -0,0 +1,100 @@
+# 3.12 JSON Details Management (การจัดการ JSON Details)
+
+---
+
+title: 'Functional Requirements: JSON Details Management'
+version: 1.5.0
+status: first-draft
+owner: Nattanin Peancharoen
+last_updated: 2025-11-30
+related:
+
+- specs/01-requirements/01-objectives.md
+- specs/01-requirements/02-architecture.md
+- specs/01-requirements/03-functional-requirements.md
+
+---
+
+## 3.12.1 วัตถุประสงค์
+
+- จัดเก็บข้อมูลแบบไดนามิกที่เฉพาะเจาะจงกับแต่ละประเภทของเอกสาร
+- รองรับการขยายตัวของระบบโดยไม่ต้องเปลี่ยนแปลง database schema
+- จัดการ metadata และข้อมูลประกอบสำหรับ correspondence, routing, และ workflows
+
+## 3.12.2 โครงสร้าง JSON Schema
+
+- ระบบต้องมี predefined JSON schemas สำหรับประเภทเอกสารต่างๆ:
+
+  - 3.12.2.1 Correspondence Types
+    - GENERIC: ข้อมูลพื้นฐานสำหรับเอกสารทั่วไป
+    - RFI: รายละเอียดคำถามและข้อมูลทางเทคนิค
+    - RFA: ข้อมูลการขออนุมัติแบบและวัสดุ
+    - TRANSMITTAL: รายการเอกสารที่ส่งต่อ
+    - LETTER: ข้อมูลจดหมายทางการ
+    - EMAIL: ข้อมูลอีเมล
+  - 3.12.2.2 Rworkflow Types
+    - workflow_definitions: กฎและเงื่อนไขการส่งต่อ
+    - workflow_histories: สถานะและประวัติการส่งต่อ
+    - workflow_instances: การดำเนินการในแต่ละขั้นตอน
+  - 3.12.2.3 Audit Types
+    - AUDIT_LOG: ข้อมูลการตรวจสอบ
+    - SECURITY_SCAN: ผลการตรวจสอบความปลอดภัย
+
+## 3.12.3 Virtual Columns (ปรับปรุง)
+
+- สำหรับ Field ใน JSON ที่ต้องใช้ในการค้นหา (Search) หรือจัดเรียง (Sort) บ่อยๆ ต้องสร้าง Generated Column (Virtual Column) ใน Database และทำ Index ไว้ เพื่อประสิทธิภาพสูงสุด
+- Schema Consistency: Field ที่ถูกกำหนดเป็น Virtual Column ห้าม เปลี่ยนแปลง Key Name หรือ Data Type ใน JSON Schema Version ถัดไป หากจำเป็นต้องเปลี่ยน ต้องมีแผนการ Re-index หรือ Migration ข้อมูลเดิมที่ชัดเจน
+
+## 3.12.4 Validation Rules
+
+- ต้องมี JSON schema validation สำหรับแต่ละประเภท
+- ต้องรองรับ versioning ของ schema
+- ต้องมี default values สำหรับ field ที่ไม่บังคับ
+- ต้องตรวจสอบ data types และ format ให้ถูกต้อง
+
+## 3.12.5 Performance Requirements
+
+- JSON field ต้องมีขนาดไม่เกิน 50KB
+- ต้องรองรับ indexing สำหรับ field ที่ใช้ค้นหาบ่อย
+- ต้องมี compression สำหรับ JSON ขนาดใหญ่
+
+## 3.12.6 Security Requirements
+
+- ต้อง sanitize JSON input เพื่อป้องกัน injection attacks
+- ต้อง validate JSON structure ก่อนบันทึก
+- ต้อง encrypt sensitive data ใน JSON fields
+
+## 3.12.7 JSON Schema Migration Strategy (เพิ่มเติม)
+
+- สำหรับ Schema Breaking Changes:
+
+  - Phase 1 - Add New Column
+    ALTER TABLE correspondence_revisions
+    ADD COLUMN ref_project_id_v2 INT GENERATED ALWAYS AS
+    (JSON_UNQUOTE(JSON_EXTRACT(details, '$.newProjectIdPath'))) VIRTUAL;
+
+  - Phase 2 - Backfill Old Records
+    - ใช้ background job แปลง JSON format เก่าเป็นใหม่
+    - Update `details` JSON ทีละ batch (1000 records)
+  - Phase 3 - Switch Application Code
+    - Deploy code ที่ใช้ path ใหม่
+  - Phase 4 - Remove Old Column
+
+    - หลังจาก verify แล้วว่าไม่มี error
+    - Drop old virtual column
+
+  - สำหรับ Non-Breaking Changes
+    - เพิ่ม optional field ใน schema
+    - Old records ที่ไม่มี field = ใช้ default value
+
+## 3.13. ข้อกำหนดพิเศษ
+
+- ผู้ใช้งานที่มีสิทธิ์ระดับสูง (Global) หรือผู้ได้รับอนุญาตเป็นกรณีพิเศษ
+  - สามารถเลือก สร้างในนามองค์กร (Create on behalf of) ได้ เพื่อให้สามารถออกเลขที่เอกสาร (Running Number) ขององค์กรอื่นได้โดยไม่ต้องล็อกอินใหม่
+  - สามารถทำงานแทนผู้ใช้งานอื่นได้ Routing & Workflow ของ Correspondence, RFA, Circulation Sheet
+
+## 3.14. การจัดการข้อมูลหลักขั้นสูง (Admin Panel for Master Data)
+
+- 3.14.1. Disciplines Management: Admin ต้องสามารถ เพิ่ม/ลบ/แก้ไข สาขางาน (Disciplines) แยกตามสัญญา (Contract) ได้
+- 3.14.2. Sub-Type Mapping: Admin ต้องสามารถกำหนด Correspondence Sub-types และ Mapping รหัสตัวเลข (เช่น MAT = 11) ได้
+- 3.14.3. Numbering Format Configuration: Admin ต้องมี UI สำหรับตั้งค่า Format Template ของแต่ละ Project/Type ได้โดยไม่ต้องแก้โค้ด

specs/01-requirements/modules/01-03.2-correspondence.md

@@ -0,0 +1,39 @@
+# 3.2 การจัดการเอกสารโต้ตอบ (Correspondence Management)
+
+---
+
+title: 'Functional Requirements: Correspondence Management'
+version: 1.5.0
+status: first-draft
+owner: Nattanin Peancharoen
+last_updated: 2025-11-30
+related:
+
+- specs/01-requirements/01-objectives.md
+- specs/01-requirements/02-architecture.md
+- specs/01-requirements/03-functional-requirements.md
+
+---
+
+## 3.2.1. วัตถุประสงค์:
+
+- เอกสารโต้ตอบ (Correspondences) ระหว่างองค์กรณ์-องค์กรณ์ ภายใน โครงการ (Projects) และระหว่าง องค์กรณ์-องค์กรณ์ ภายนอก โครงการ (Projects), รองรับ To (ผู้รับหลัก) และ CC (ผู้รับสำเนา) หลายองค์กรณ์
+
+## 3.2.2. ประเภทเอกสาร:
+
+- ระบบต้องรองรับเอกสารรูปแบบ ไฟล์ PDF, ZIP
+- เอกสารโต้ตอบ (Correspondence) สามารถมีได้หลายประเภท (Types) เช่น จดหมาย (Letter), อีเมล์ (Email), Request for Information (RFI), รวมถึง เอกสารขออนุมัติ (RFA) แต่ละ revision และสามารถเพิ่มประเภทใหม่ได้ในภายหลัง
+
+## 3.2.3. การสร้างเอกสาร (Correspondence):
+
+- ผู้ใช้ที่มีสิทธิ์ (เช่น Document Control) สามารถสร้างเอกสารรอไว้ในสถานะ ฉบับร่าง" (Draft) ได้ ซึ่งผู้ใช้งานต่างองค์กรจะมองไม่เห็น
+- เมื่อกด "Submitted" แล้ว การแก้ไข, ถอนเอกสารกลับไปสถานะ Draft, หรือยกเลิก (Cancel) จะต้องทำโดยผู้ใช้ระดับ Admin ขึ้นไป พร้อมระบุเหตุผล
+
+## 3.2.4. การอ้างอิงและจัดกลุ่ม:
+
+- เอกสารสามารถอ้างถึง (Reference) เอกสารฉบับก่อนหน้าได้หลายฉบับ
+- สามารถกำหนด Tag ได้หลาย Tag เพื่อจัดกลุ่มและใช้ในการค้นหาขั้นสูง
+
+## 3.2.5. Workflow (Unified Workflow):
+
+- ระบบต้องรองรับ Workflow ที่เป็นแบบ Unified Workflow

specs/01-requirements/modules/01-03.3-rfa.md

@@ -0,0 +1,39 @@
+# 3.3 RFA Management (การจัดการเอกสาขออนุมัติ)
+
+---
+
+title: 'Functional Requirements: RFA Management'
+version: 1.5.0
+status: first-draft
+owner: Nattanin Peancharoen
+last_updated: 2025-11-30
+related:
+
+- specs/01-requirements/01-objectives.md
+- specs/01-requirements/02-architecture.md
+- specs/01-requirements/03-functional-requirements.md
+
+---
+
+## 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

specs/01-requirements/modules/01-03.4-contract-drawing.md

@@ -0,0 +1,32 @@
+# 3.4 Contract Drawing Management (การจัดการแบบคู่สัญญา)
+
+---
+
+title: 'Functional Requirements: Contract Drawing Management'
+version: 1.5.0
+status: first-draft
+owner: Nattanin Peancharoen
+last_updated: 2025-11-30
+related:
+
+- specs/01-requirements/01-objectives.md
+- specs/01-requirements/02-architecture.md
+- specs/01-requirements/03-functional-requirements.md
+
+---
+
+## 3.4.1. วัตถุประสงค์:
+
+- แบบคู่สัญญา (Contract Drawing) ใช้เพื่ออ้างอิงและใช้ในการตรวจสอบ
+
+## 3.4.2. ประเภทเอกสาร:
+
+- ไฟล์ PDF
+
+## 3.4.3. การสร้างเอกสาร:
+
+- ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
+
+## 3.4.4. การอ้างอิงและจัดกลุ่ม:
+
+- ใช้สำหรับอ้างอิง ใน Shop Drawings, มีการจัดหมวดหมู่ของ Contract Drawing

specs/01-requirements/modules/01-03.5-shop-drawing.md

@@ -0,0 +1,32 @@
+# 3.5 Shop Drawing Management (การจัดการแบบก่อสร้าง)
+
+---
+
+title: 'Functional Requirements: Shop Drawing Management'
+version: 1.5.0
+status: first-draft
+owner: Nattanin Peancharoen
+last_updated: 2025-11-30
+related:
+
+- specs/01-requirements/01-objectives.md
+- specs/01-requirements/02-architecture.md
+- specs/01-requirements/03-functional-requirements.md
+
+---
+
+## 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 ฉบับ

specs/01-requirements/modules/01-03.6-unified-workflow.md

@@ -0,0 +1,43 @@
+# 3.6 Unified Workflow Management (การจัดการ Workflow)
+
+---
+
+title: 'Functional Requirements: Unified Workflow Management'
+version: 1.5.0
+status: first-draft
+owner: Nattanin Peancharoen
+last_updated: 2025-11-30
+related:
+
+- specs/01-requirements/01-objectives.md
+- specs/01-requirements/02-architecture.md
+- specs/01-requirements/03-functional-requirements.md
+
+---
+
+## 3.6.1 Workflow Definition:
+
+- Admin ต้องสามารถสร้าง/แก้ไข Workflow Rule ได้ผ่านหน้าจอ UI (DSL Editor)
+- รองรับการกำหนด State, Transition, Required Role, Condition (JS Expression)
+
+## 3.6.2 Workflow Execution:
+
+- ระบบต้องรองรับการสร้าง Instance ของ Workflow ผูกกับเอกสาร (Polymorphic)
+- รองรับการเปลี่ยนสถานะ (Action) เช่น Approve, Reject, Comment, Return
+- Auto-Action: รองรับการเปลี่ยนสถานะอัตโนมัติเมื่อครบเงื่อนไข (เช่น Review ครบทุกคน)
+
+## 3.6.3 Flexibility:
+
+- รองรับ Parallel Review (ส่งให้หลายคนตรวจพร้อมกัน)
+- รองรับ Conditional Flow (เช่น ถ้ายอดเงิน > X ให้เพิ่มผู้อนุมัติ)
+
+## 3.6.4 Workflow การอนุมัติ:
+
+- รองรับกระบวนการอนุมัติที่ซับซ้อนและเป็นลำดับ เช่น ส่งจาก Originator -> Organization 1 -> Organization 2 -> Organization 3 แล้วส่งผลกลับตามลำดับเดิม (โดยถ้า องกรณ์ใดใน Workflow ให้ส่งกลับ ก็สามารถส่งผลกลับตามลำดับเดิมโดยไม่ต้องรอให้ถึง องกรณืในลำดับถัดไป)
+
+## 3.6.5 การจัดการ:
+
+- สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบของ องกรณ์ ที่อยู่ใน Workflow ได้
+- มีระบบแจ้งเตือน ให้ผู้รับผิดชอบของ องกรณ์ ที่อยู่ใน Workflow ทราบ เมื่อมี RFA ใหม่ หรือมีการเปลี่ยนสถานะ
+- สามารถข้ามขั้นตอนได้ในกรณีพิเศษ (โดยผู้มีสิทธิ์)
+- สามารถส่งกลับขั้นตอนก่อนหน้าได้

specs/01-requirements/modules/01-03.7-transmittals.md

@@ -0,0 +1,32 @@
+# 3.7 Transmittals Management (การจัดการเอกสารนำส่ง)
+
+---
+
+title: 'Functional Requirements: Transmittals Management'
+version: 1.5.0
+status: first-draft
+owner: Nattanin Peancharoen
+last_updated: 2025-11-30
+related:
+
+- specs/01-requirements/01-objectives.md
+- specs/01-requirements/02-architecture.md
+- specs/01-requirements/03-functional-requirements.md
+
+---
+
+## 3.7.1. วัตถุประสงค์:
+
+- เอกสารนำส่ง ใช้สำหรับ นำส่ง Request for Approval (RFAS) หลายฉบับ ไปยังองค์กรอื่น
+
+## 3.7.2. ประเภทเอกสาร:
+
+- ไฟล์ PDF
+
+## 3.7.3. การสร้างเอกสาร:
+
+- ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
+
+## 3.7.4. การอ้างอิงและจัดกลุ่ม:
+
+- เอกสารนำส่ง เป็นส่วนหนึ่งใน Correspondence

specs/01-requirements/modules/01-03.8-circulation-sheet.md

@@ -0,0 +1,41 @@
+# 3.8 Circulation Sheet Management (การจัดการใบเวียนเอกสาร)
+
+---
+
+title: 'Functional Requirements: Circulation Sheet Management'
+version: 1.5.0
+status: first-draft
+owner: Nattanin Peancharoen
+last_updated: 2025-11-30
+related:
+
+- specs/01-requirements/01-objectives.md
+- specs/01-requirements/02-architecture.md
+- specs/01-requirements/03-functional-requirements.md
+
+---
+
+## 3.8.1. วัตถุประสงค์:
+
+- การสื่อสาร เอกสาร (Correspondence) ทุกฉบับ จะมีใบเวียนเอกสารเพื่อควบคุมและมอบหมายงานภายในองค์กร (สามารถดูและแก้ไขได้เฉพาะคนในองค์กร)
+
+## 3.8.2. ประเภทเอกสาร:
+
+- ไฟล์ PDF
+
+## 3.8.3. การสร้างเอกสาร:
+
+- ผู้ใช้ที่มีสิทธิ์ในองค์กรนั้น สามารถสร้างและแก้ไขได้
+
+## 3.8.4. การอ้างอิงและจัดกลุ่ม:
+
+- การระบุผู้รับผิดชอบ:
+  - ผู้รับผิดชอบหลัก (Main): มีได้หลายคน
+  - ผู้ร่วมปฏิบัติงาน (Action): มีได้หลายคน
+  - ผู้ที่ต้องรับทราบ (Information): มีได้หลายคน
+
+## 3.8.5. การติดตามงาน:
+
+- สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบประเภท Main และ Action ได้
+- มีระบบแจ้งเตือนเมื่อมี Circulation ใหม่ และแจ้งเตือนล่วงหน้าก่อนถึงวันแล้วเสร็จ
+- สามารถปิด Circulation ได้เมื่อดำเนินการตอบกลับไปยังองค์กรผู้ส่ง (Originator) แล้ว หรือ รับทราบแล้ว (For Information)

specs/01-requirements/modules/01-03.9-logs.md

@@ -0,0 +1,21 @@
+# 3.9 Logs Management (ประวัติการแก้ไข)
+
+---
+
+title: 'Functional Requirements: Logs Management'
+version: 1.5.0
+status: first-draft
+owner: Nattanin Peancharoen
+last_updated: 2025-11-30
+related:
+
+- specs/01-requirements/01-objectives.md
+- specs/01-requirements/02-architecture.md
+- specs/01-requirements/03-functional-requirements.md
+
+---
+
+## 3.9.1. วัตถุประสงค์:
+
+- เพื่อ บันทึกการกระทำ CRUD ของเอกสารทั้งหมด รวมถึงการ เข้าใช้งาน ของ users
+- admin สามารถดูประวัติการแก้ไขของเอกสารทั้งหมด พร้อม จัดทำรายงายตามข้อกำหนดที่ ต้องการได้