3.10 JSON Details Management (การจัดการ JSON Details)

title: 'Functional Requirements: JSON Details Management' version: 1.8.1 status: updated owner: Nattanin Peancharoen last_updated: 2026-03-24 related:

specs/01-requirements/01-01-objectives.md
specs/01-requirements/01-03-modules/01-03-00-index.md
specs/01-requirements/01-03-modules/01-03-02-correspondence.md
specs/01-requirements/01-03-modules/01-03-03-rfa.md
specs/01-requirements/01-03-modules/01-03-06-unified-workflow.md
specs/03-Data-and-Storage/03-01-data-dictionary.md
specs/06-Decision-Records/ADR-009-db-strategy.md

3.10.1. วัตถุประสงค์

ระบบใช้ JSON column สำหรับข้อมูลที่มีโครงสร้างแตกต่างกันตามประเภทเอกสาร โดยไม่ต้องเพิ่ม column ใหม่ใน Schema รองรับการขยายตัวโดยไม่กระทบ ADR-009 (No-migration policy)

3.10.2. JSON Columns ในระบบ (ครบทุกตาราง)

ตาราง	Column	วัตถุประสงค์
`correspondence_revisions`	`details`	ข้อมูลเฉพาะตามประเภทเอกสาร (Letter, RFI ฯลฯ)
`rfa_revisions`	`details`	ข้อมูลเฉพาะ RFA (เช่น drawingCount)
`workflow_definitions`	`dsl`	นิยาม Workflow ต้นฉบับ (JSON DSL)
`workflow_definitions`	`compiled`	Execution Tree ที่ Compile แล้ว
`workflow_instances`	`context`	ตัวแปร Context สำหรับตัดสินใจ Transition
`workflow_histories`	`metadata`	Snapshot ข้อมูล ณ ขณะ Transition
`audit_logs`	`details_json`	ข้อมูล Context เพิ่มเติมของ Event
`document_numbers`	`counter_key`	Counter key (8 fields) สำหรับ Document Numbering
`document_numbers`	`metadata`	Additional context ของการออกเลข
`document_number_errors`	`context_data`	Context ของ request ที่เกิด error
`json_schemas`	`schema_definition`	JSON Schema (AJV Standard)
`json_schemas`	`ui_schema`	UI Schema สำหรับ Frontend render
`json_schemas`	`virtual_columns`	Config สำหรับสร้าง Virtual Columns
`json_schemas`	`migration_script`	Script แปลงข้อมูลระหว่าง versions

3.10.3. JSON Schema Registry (json_schemas)

ระบบมีตาราง json_schemas เป็น Centralized Registry สำหรับ validate และ manage โครงสร้าง JSON:

Field	หมายเหตุ
`schema_code`	รหัส Schema เช่น `RFA_DWG`, `CORRESPONDENCE_LETTER`
`version`	Version ของ Schema (UNIQUE ร่วมกับ `schema_code`)
`table_name`	ตารางเป้าหมาย เช่น `rfa_revisions`
`schema_definition`	โครงสร้าง AJV JSON Schema สำหรับ validation
`ui_schema`	โครงสร้าง UI Schema สำหรับ Frontend render dynamic form
`virtual_columns`	Config สำหรับสร้าง Generated Columns
`migration_script`	Script แปลงข้อมูลจาก version ก่อนหน้า

3.10.4. Virtual Columns (Generated Columns)

JSON field ที่ต้องใช้ใน Query / Search สร้างเป็น Generated Virtual Column + Index:

ตาราง	Virtual Column	JSON Path	ใช้สำหรับ
`correspondence_revisions`	`v_ref_project_id`	`$.projectId`	Filter by Project
`correspondence_revisions`	`v_doc_subtype`	`$.subType`	Filter by Sub-type
`rfa_revisions`	`v_ref_drawing_count`	`$.drawingCount`	Count / Sort

กฎสำคัญ: Field ที่เป็น Virtual Column ห้ามเปลี่ยน JSON key หรือ data type ใน version ถัดไป — ต้องมีแผน Re-index / Migration ก่อน

3.10.5. Validation Rules

Backend validate ด้วย json_schemas.schema_definition (AJV Standard) ก่อน save ทุกครั้ง
แต่ละ record มี schema_version — ใช้เลือก schema ที่ถูกต้องสำหรับ validate
Field ไม่บังคับ → ใช้ default value ตามที่กำหนดใน schema
Sanitize JSON input เพื่อป้องกัน injection ก่อน validate

3.10.6. JSON Schema Migration Strategy

Breaking Changes (เปลี่ยน key / type)

Phase 1 — Add New Virtual Column ด้วย path ใหม่
Phase 2 — Backfill Old Records ด้วย background job (batch 1,000 records)
Phase 3 — Deploy Application Code ที่ใช้ path ใหม่
Phase 4 — Drop Old Column หลัง verify ไม่มี error

Non-Breaking Changes (เพิ่ม optional field)

เพิ่ม field ใน schema definition — old records ที่ไม่มี field ใช้ default value อัตโนมัติ
ไม่ต้อง backfill

หมายเหตุ: เนื้อหาเดิม §3.13 (Impersonation) และ §3.14 (Master Data Management) ได้ถูกย้ายไปยัง spec ที่เกี่ยวข้องแล้ว:

Impersonation → 01-02-01-rbac-matrix.md

Disciplines Management → 01-03-01-project-management.md (§3.1.6)

Numbering Format → Document Numbering spec

5.8 KiB Raw Blame History