Prepare to version 1.5 use spec-kit

infrastructure/Markdown/LCBP3-DMS_V1_2_1_FullStackJS.md

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