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

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 ได้โดยไม่ต้องแก้โค้ด