VTRC Knowledge Manual (V2)

ธีม

Volume 9 · Data Model & Persistence ​

บทนี้เปิด Volume ที่ลงลึกที่สุดเรื่องข้อมูล — ข้อมูลอยู่ที่ไหน, ใครเป็นเจ้าของ, schema เป็นอย่างไร, และทำไมถึง maintain ยาก

ทำไมต้องมี Volume 9 แยกต่างหาก ​

Volume 3 ลงรายละเอียดว่า vtrc-api ทำงานอย่างไร ตั้งแต่ boot จนถึง cron — แต่มอง data layer แบบคร่าว ๆ ในบทเดียว (3.5 Persistence layer)

เวลา debug จริง ปัญหาส่วนใหญ่ไม่ได้อยู่ที่ logic — อยู่ที่ "ข้อมูลไม่ตรงกันระหว่าง 2 schema", "query ช้าเพราะไม่มี index", "transaction ไม่ rollback เพราะผิดตำแหน่ง", "User UUID ของ vtrc ไม่ map กลับไปหา EmpCode ของ HRMI ได้"

Volume 9 เจาะตรงนี้ — ตั้งแต่ physical topology, การลงทะเบียน model, schema definition, ERD ของแต่ละ domain, ไปจนถึง integrity risk ที่ควรรู้ตอนแตะ data layer

Volume 9 เหมาะกับใคร ​

  • dev ที่จะเขียน resolver ใหม่ — ต้องรู้ว่า model ที่จะ query มี relation อะไรบ้าง, index ตรงไหน
  • DBA / ops — ต้องเข้าใจว่าทำไม syncModelToTable() รันทุก boot, schema drift เกิดอย่างไร
  • data analyst — ต้อง join ข้อมูลระหว่าง vtrc กับ dbHRMI_Center แล้วต้องรู้ว่า identity ไม่ตรงกัน
  • dev ที่จอยทีมใหม่ — อ่านแล้วเข้าใจ "แผนที่ข้อมูล" ของทั้งระบบใน 1 ที่

โครงสร้าง Volume 9 ​

Volume 9 · Data Model & Persistence
├── 8.1  Persistence topology         4 logical DBs, owner, engine, role
├── 8.2  Model registration           auto-load + Models global
├── 8.3  Model patterns               convention ที่ใช้ทุก model
├── 8.4  Schema management            syncModelToTable vs migration
├── 8.5  ERD — Identity & Access      Users, Sessions, Roles
├── 8.6  ERD — Leave & Approvals      LeaveDocument + state machine
├── 8.7  ERD — Welfare withdrawal     WDHospital + 13-state ENUM
├── 8.8  ERD — Study/Fund/Notification
├── 8.9  Identity across databases    UUID vs EmpCode mapping
├── 8.10 Indexing, transactions, perf
├── 8.11 Data integrity risks
└── 8.12 Scorecard + modernization target

ทุก ERD ใน Volume นี้ใช้ ASCII tree + markdown table ไม่ใช้ mermaid (ตาม style guide ของ manual ฉบับนี้)

สิ่งที่ Volume 9 จะไม่พูดถึง ​

เพื่อกัน scope creep

  • business logic ของแต่ละ domain — อยู่ใน Volume 11 (Business Logic & Workflows)
  • GraphQL schema ที่ expose model — อยู่ใน Volume 10 (API Reference)
  • security ของ data (encryption at rest, PII masking) — อยู่ใน Volume 9 (Security)
  • migration / modernization roadmap เชิงกลยุทธ์ — อยู่ใน Volume 15

Volume 9 โฟกัสที่ "ข้อมูลอยู่ตรงไหน เป็นอย่างไร เจ้าของใคร" เท่านั้น

สมมติฐานที่ใช้ตลอด Volume 9 ​

  • อ่าน Volume 3.1 (Repository map) และ Volume 3.5 (Persistence layer) มาก่อน
  • เข้าใจว่า Sequelize คือ ORM ของ Node.js + MariaDB/MySQL
  • เข้าใจความแตกต่างระหว่าง logical database กับ physical database
  • รู้จัก UUID, foreign key, index, transaction ในระดับ conceptual

ถ้ายังไม่คุ้นเรื่อง Sequelize แนะนำอ่าน Sequelize Manual — Model definition ควบไปด้วย

Evidence source ​

ทุก claim มาจาก code จริงใน:

  • vtrc-api/api/src/models/ — Sequelize model definitions (95 ไฟล์)
  • vtrc-api/api/src/connector.js — DB connection config
  • vtrc-api/api/src/lib/model.js — syncModelToTable + createDatabases
  • centralize-api/src/entities/ — TypeORM entities (MSSQL side)
  • cu-central-api/main-api/src/models/ — Sequelize models ของ HRMI

cross-check กับ audit doc docs/audit/03-data-and-api.md (เอกสาร audit ดั้งเดิมที่ใช้เป็น source of truth)

ไปเริ่มที่ 8.1 Persistence topology →