101 lines
6.1 KiB
Markdown
101 lines
6.1 KiB
Markdown
# 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 ได้โดยไม่ต้องแก้โค้ด
|