260324:1349 Refactor RFA #01

2026-03-24 13:49:30 +07:00
parent a3e3206b06
commit 4cd0952482
29 changed files with 1700 additions and 306 deletions
@@ -1,97 +1,107 @@
-# 3.12 JSON Details Management (การจัดการ JSON Details)
+# 3.10 JSON Details Management (การจัดการ JSON Details)

 ---

 title: 'Functional Requirements: JSON Details Management'
-version: 1.8.0
-status: first-draft
+version: 1.8.1
+status: updated
 owner: Nattanin Peancharoen
-last_updated: 2026-02-23
+last_updated: 2026-03-24
 related:

 - specs/01-requirements/01-01-objectives.md
- specs/02-architecture/README.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.12.1 วัตถุประสงค์
+## 3.10.1. วัตถุประสงค์

- จัดเก็บข้อมูลแบบไดนามิกที่เฉพาะเจาะจงกับแต่ละประเภทของเอกสาร
- รองรับการขยายตัวของระบบโดยไม่ต้องเปลี่ยนแปลง database schema
- จัดการ metadata และข้อมูลประกอบสำหรับ correspondence, routing, และ workflows
+ระบบใช้ `JSON` column สำหรับข้อมูลที่มีโครงสร้างแตกต่างกันตามประเภทเอกสาร โดยไม่ต้องเพิ่ม column ใหม่ใน Schema รองรับการขยายตัวโดยไม่กระทบ ADR-009 (No-migration policy)

-## 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.10.2. JSON Columns ในระบบ (ครบทุกตาราง)

-## 3.12.3 Virtual 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 |

- สำหรับ 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
+## 3.10.3. JSON Schema Registry (json_schemas)

- ต้องมี JSON schema validation สำหรับแต่ละประเภท
- ต้องรองรับ versioning ของ schema
- ต้องมี default values สำหรับ field ที่ไม่บังคับ
- ต้องตรวจสอบ data types และ format ให้ถูกต้อง
+ระบบมีตาราง `json_schemas` เป็น **Centralized Registry** สำหรับ validate และ manage โครงสร้าง JSON:

-## 3.12.5 Performance Requirements
+| 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 ก่อนหน้า |

- JSON field ต้องมีขนาดไม่เกิน 50KB
- ต้องรองรับ indexing สำหรับ field ที่ใช้ค้นหาบ่อย
- ต้องมี compression สำหรับ JSON ขนาดใหญ่
+---

-## 3.12.6 Security Requirements
+## 3.10.4. Virtual Columns (Generated Columns)

- ต้อง sanitize JSON input เพื่อป้องกัน injection attacks
- ต้อง validate JSON structure ก่อนบันทึก
- ต้อง encrypt sensitive data ใน JSON fields
+JSON field ที่ต้องใช้ใน Query / Search สร้างเป็น **Generated Virtual Column** + Index:

-## 3.12.7 JSON Schema Migration Strategy (เพิ่มเติม)
+| ตาราง | 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 |

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

-  - 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.10.5. Validation Rules

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

- ผู้ใช้งานที่มีสิทธิ์ระดับสูง (Global) หรือผู้ได้รับอนุญาตเป็นกรณีพิเศษ
-  - สามารถเลือก สร้างในนามองค์กร (Create on behalf of) ได้ เพื่อให้สามารถออกเลขที่เอกสาร (Running Number) ขององค์กรอื่นได้โดยไม่ต้องล็อกอินใหม่
-  - สามารถทำงานแทนผู้ใช้งานอื่นได้ Routing & Workflow ของ Correspondence, RFA, Circulation Sheet
+---

-## 3.14. การจัดการข้อมูลหลักขั้นสูง (Master Data Management)
+## 3.10.6. JSON Schema Migration Strategy

- 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: ระบบต้องรองรับการตั้งค่า Format Template ของแต่ละ Project/Type ได้โดยไม่ต้องแก้โค้ด
+### Breaking Changes (เปลี่ยน key / type)
+
+1. **Phase 1 — Add New Virtual Column** ด้วย path ใหม่
+2. **Phase 2 — Backfill Old Records** ด้วย background job (batch 1,000 records)
+3. **Phase 3 — Deploy Application Code** ที่ใช้ path ใหม่
+4. **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