Volume 0 · Getting Started

เล่มนี้เขียนเป็นเล่มสุดท้ายของคู่มือฉบับนี้ — ตอนที่เขียน Volume 3 ถึง 20 เสร็จหมดแล้ว จึงเป็นการสังเคราะห์ (synthesis) จากทุกสิ่งที่เอกสารทั้งหมดค้นพบ ไม่ใช่การสำรวจโค้ดจากศูนย์ ถ้าข้อความใดในเล่มนี้ดูขัดกับ volume ต้นทาง ให้ถือ volume ต้นทางเป็นความจริง แล้วแจ้งแก้ที่นี่

Deep Redo status (2026-07-14): Per-service volumes (Vol 3–9) ถูกเขียนใหม่ให้ใกล้ความลึกของ docs-v1-archive/ แล้ว (~52k บรรทัดรวม cross-cutting). Critical security ชุดใหม่ดู Vol 12.5. ตัวเลข debt 275 ใน Vol 17 ยังเป็น baseline จาก shallow pass — ใช้ร่วมกับ 17.4 addendum จนกว่าจะ reconcile. VitePress npm run build ผ่านแล้วหลังแก้ mustache/N:M:path fences.

เล่มนี้คืออะไร สำหรับใคร

VTRC Knowledge Manual v2 เป็นคู่มืออ้างอิงภายในสำหรับแพลตฟอร์ม HR/Welfare ของสภากาชาดไทย ครอบคลุม 31 repositories ที่มีโค้ดจริง (บวก 8 repositories placeholder ที่ยังไม่มีโค้ด) กระจายอยู่ใน 7 กลุ่มแพลตฟอร์ม — ดูรายชื่อทั้งหมดที่ repo fact-sheet index

ผู้อ่านหลักคือ วิศวกรที่เข้ามาดูแลระบบต่อ ไม่ว่าจะเป็นคนใหม่ที่ไม่เคยเห็นระบบนี้มาก่อน หรือวิศวกรเดิมที่ต้องการแผนที่ข้ามบริการที่ไม่มีใครเขียนไว้มาก่อน เอกสารนี้ไม่ต้องใช้ความรู้เฉพาะทางมาก่อน แต่ถือว่าผู้อ่านเขียนโค้ดเป็นและคุ้นเคยกับ concept ทั่วไปของเว็บ/API (HTTP, database, authentication)

เอกสารนี้ ไม่ใช่ product manual สำหรับผู้ใช้ปลายทาง (พนักงาน/HR) และไม่ใช่ marketing material — น้ำเสียงคือ senior engineer ที่ทำระบบจริงเขียนให้เพื่อนร่วมทีมอ่าน

โครงสร้างคู่มือ — ทำไมถึงแบ่งเป็น 21 volume, 4 ชั้น

คู่มือแบ่งเป็น 21 volume (0 ถึง 20) จัดเป็น 4 ชั้นตามลำดับตัวเลข — การจัดลำดับนี้ไม่ใช่อำเภอใจ แต่สะท้อนลำดับที่ผู้อ่านควรซึมซับข้อมูล จากภาพกว้างไปเจาะลึก แล้ววนกลับมาที่ภาพกว้างอีกครั้งในรูปของ findings/roadmap

ชั้นที่ 1 — Foundation (Vol 0-2)
  │  ปูพื้น: คู่มือนี้คืออะไร (0) → ธุรกิจคืออะไร (1) → สถาปัตยกรรมเป็นอย่างไร (2)
  ▼
ชั้นที่ 2 — Per-service deep dive (Vol 3-10)
  │  ลงรายละเอียดทีละกลุ่มแพลตฟอร์ม 8 เล่ม ตามลำดับที่ระบบถูกแยกออกจาก legacy core:
  │  Legacy Core (3) → Frontends (4) → 2way (5) → Domain Microservices (6)
  │  → Meeting (7) → Mobile (8) → OCR/Aux (9) → Placeholder repos (10)
  ▼
ชั้นที่ 3 — Cross-cutting (Vol 11-16)
  │  สังเคราะห์ข้ามทุก repo ในแต่ละ "เลนส์": data (11), security (12), API (13),
  │  business logic (14), infrastructure (15), runbook สำหรับ on-call (16)
  ▼
ชั้นที่ 4 — Findings & Roadmap (Vol 17-20)
     รวมหนี้ทางเทคนิคทั้งหมด (17) → เจาะ security ต่อ (18) → แผนแก้ (19) → ดัชนีค้นหา (20)

เหตุผลของลำดับนี้ — Volume 3-10 แต่ละเล่มตอบคำถาม "repo นี้ทำงานอย่างไร" ได้ดี แต่ไม่มีเล่มไหนตอบคำถามระดับแพลตฟอร์มเช่น "ถ้า secret ตัวหนึ่งรั่ว กระทบกี่ repo" หรือ "ใครเรียกใครทั้งระบบ" — Volume 11-16 จึงเกิดขึ้นเพื่ออุดช่องว่างนั้นโดยเฉพาะ (ดู Volume 11 § ทำไมต้องมี Volume แยก เป็นตัวอย่างของการให้เหตุผลนี้ซ้ำในทุกเล่มชั้น 3) ส่วน Volume 17-20 แปลง finding ทั้งหมดที่สะสมมาจากชั้น 2-3 เป็นทะเบียนที่ตรวจสอบย้อนกลับได้และแผนงานที่ลงมือทำได้จริง

Volume 0-2 (ชั้นที่ 1) เขียนเป็นลำดับสุดท้าย เพราะต้องมีเนื้อหาของชั้น 2-4 ครบก่อนถึงจะสังเคราะห์ภาพรวมได้อย่างซื่อตรงกับหลักฐาน — นี่คือเหตุผลที่ผู้อ่านเล่มนี้จะเห็น citation ชี้ไปยัง volume อื่นเป็นส่วนใหญ่ แทนที่จะเป็น file:line ตรงเหมือนเล่มอื่น

แผนที่ 7 กลุ่มแพลตฟอร์ม (โดยย่อ)

กลุ่ม	Repository	Volume
Legacy Core	`vtrc-api`, `cu-central-api`, `centralize-api`	Vol 3
Web Frontends	`vtrc-web`, `vtrc-rc-backoffice`, `vtrc-backoffice`, `vtrc-backoffice-new`	Vol 4
2way Platform	`2way-api`, `2way-batch`, `2way-line-service`, `2way-meeting-backoffice`, `2way-vtrc-api`	Vol 5
Domain Microservices	`benefit-api`, `chat-center-api`, `job-scheduler-api`, `workflow-api`, `recruitment-api`, `ai-recruitment-api`, `pms-api`, `sso-api`, `vtrc-common`	Vol 6
Meeting Platform	`meeting-vtrc-api`, `meeting-backoffice`, `meeting-backoffice-new`	Vol 7
Mobile	`vtrc-mobile`, `new-vtrc-mobile`, `vtrc-application-front`	Vol 8
OCR & Auxiliary	`vtrc-ocr-api`, `report-log`, `recruitment-web`, `interns_playground`	Vol 9
(Placeholder — ไม่มีโค้ด)	`attendance-api`, `auth-api`, `career-api`, `hrservice-api`, `learning-api`, `notification-api`, `payroll-api`, `performing-api`	Vol 10

รายละเอียดของแต่ละกลุ่ม (stack จริง, ความสัมพันธ์ข้าม repo, ข้อคลาดเคลื่อนที่พบระหว่างตรวจสอบ) อยู่ที่ Volume 2 — เล่มนี้ให้แค่แผนที่สำหรับนำทางไปเล่มที่ถูกต้อง

วิธีนำทาง — ถามคำถามนี้ก่อนเปิดเล่มไหน

ถ้าอยากรู้...	ไปที่
เข้าใจ repo หนึ่งตัวโดยเฉพาะ (เช่น `benefit-api` ทำงานอย่างไร)	Volume ของกลุ่มนั้น (ดูตารางด้านบน) → subfolder ของ repo นั้น
"ใครเรียกใคร" ข้ามทั้งแพลตฟอร์ม	Volume 13 · API Reference § 13.3 Inter-service map — 34 ความสัมพันธ์ caller→callee ที่ยืนยันจากโค้ด
service ไหนต่อ database ของ service อื่นตรง (ไม่ผ่าน API)	Volume 11 · Data Model § 11.2 Cross-service coupling
ระบบตอนนี้พังตรงไหน / เสี่ยงอะไร	Volume 17 · Technical Debt Register (ภาพรวมทุก category) หรือ Volume 18 · Security Review Findings (เฉพาะ security)
กำลังจะวางแผนแก้ไข ควรเริ่มตรงไหนก่อน	Volume 19 · Modernization Roadmap — จัดตามขอบฟ้า 90 วัน / 6 เดือน / 12 เดือน จาก deep ROI
กำลัง debug incident ที่เกิดขึ้นจริง ไม่รู้ต้องดูโค้ดตรงไหน	Volume 16 · Operational Runbooks
อยากรู้ว่า secret ตัวหนึ่งรั่วแล้วกระทบใครบ้าง	Volume 11 · Data Model § 11.4 Shared secrets & credentials
อยากเข้าใจ business process (การลา, การเบิกสวัสดิการ, การสรรหา) ก่อนเปิดโค้ด	Volume 1 · Business Context หรือ Volume 14 · Business Logic & Workflows
ไม่รู้จะเริ่มตรงไหนเลย	อ่านเล่มนี้ต่อจนจบ แล้วดู "ถ้าจะอ่านแค่ 5 อย่าง" ด้านล่าง

ถ้าจะอ่านแค่ 5 อย่างในคู่มือทั้งเล่ม

ถ้าเวลาน้อยมาก นี่คือ 5 หน้าที่ให้ผลตอบแทนสูงสุดต่อเวลาที่ใช้อ่าน:

Canonical Truths — ข้อเท็จจริงยืนยันจากโค้ดที่ผิดพลาดบ่อยที่สุดถ้าอ่านแบบผิวเผิน (พอร์ต, ชื่อ service ที่คล้ายกัน, branch canonical) อ่านก่อนเชื่อ claim ใดๆ ในคู่มือ
Volume 13 § 13.3 Inter-service map — แผนที่ "ใครเรียกใคร" ทั้งแพลตฟอร์ม เห็นภาพเดียวว่า vtrc-api/cu-central-api คือ hub ที่ถ้าล่มกระทบทุกอย่าง
Volume 12 § 12.3 + 12.5 Deep Redo addendum — Critical security ชุด baseline + ชุดใหม่หลัง deep scorecards (backdoors, secrets-in-git, SQLi)
Volume 11 § 11.2 Cross-service coupling — เหตุผลว่าทำไม VTRC ไม่ใช่ microservices ตามตำรา แต่เป็น "distributed monolith" ที่ schema เปลี่ยนจุดเดียวกระทบหลาย repo
Volume 2 · Architecture & Topology — ภาพรวมสถาปัตยกรรมระดับ platform-group พร้อม topology diagram สรุปจากทั้ง 4 ข้อข้างต้น

Citation convention — วิธีอ่านการอ้างอิงในคู่มือนี้

ทุก claim ในคู่มือ (ยกเว้นเนื้อหาสังเคราะห์ในเล่มนี้กับ Vol 1-2 ที่ชี้กลับไปยัง volume ต้นทางเป็นหลัก) ต้องมี citation แบบ file:line ตัวอย่าง:

cu-central-api ใช้ LDAP สำหรับ authentication (cu-central-api/main-api/src/config.js:20)

Branch annotation — repo จำนวนมากมี default branch (main/master) ที่ว่างหรือมีโค้ดน้อยกว่า branch ที่ deploy จริง เมื่อ citation อ้างถึง repo เหล่านี้ ต้องระบุ branch ด้วยเสมอ:

benefit-api/src/main.ts (branch: prod):42

ดูตาราง branch canonical ของทุก repo ที่ไม่ตรงกับ default branch ที่ Canonical Truths § Branch topology

ถ้าพบข้อความที่ไม่มี citation หรือดูน่าสงสัย ให้เปิดไฟล์ที่อ้างถึงเพื่อยืนยันก่อนเชื่อเสมอ — คู่มือเขียนจากโค้ดที่ commit ไว้ ณ วันที่ตรวจสอบ (2026-07-13) ไม่ใช่จากการสังเกต production จริง

Debt ID scheme — สัญกรณ์ที่ใช้ทั่วทั้งคู่มือ

ทุก finding ที่นับเป็นหนี้ทางเทคนิคจะได้ debt ID รูปแบบ {PREFIX}-{REPO}-{NUMBER} เช่น SEC-BENEFIT-02, CORR-WORKFLOW-01

Prefix	หมวด
`SEC-`	Security
`PERF-`	Performance
`CORR-`	Correctness / data integrity
`LEG-`	Legacy / EOL / dependency
`QUAL-`	Code quality
`OBS-`	Observability

ID เหล่านี้เกิดครั้งแรกที่ scorecard ของแต่ละ repo (บทสุดท้ายของ Vol 3-9) ไหลเข้า Volume 17 · Technical Debt Register เป็นทะเบียนกลาง (275 จาก shallow pass + Critical ใหม่ใน 17.4 ที่ยังไม่ merge ครบ) รายการ SEC- ระดับ Critical/High ถูกขยายใน Volume 18 ส่วนแผนแก้ไขอยู่ใน Volume 19 — Volume 20 § Debt ID index มีดัชนี flat สำหรับค้นหาเร็ว

v1 vs v2 — ทำไมต้องเขียนใหม่ทั้งเล่ม

v1 (เก็บไว้ที่ docs-v1-archive/) ครอบคลุมเฉพาะ 5 legacy service (vtrc-api, cu-central-api, centralize-api, vtrc-web, vtrc-rc-backoffice) ด้วยความลึกที่ค่อนข้างมาก แต่แพลตฟอร์มจริงในปี 2026 ขยายออกเป็น 31 repositories ที่มีโค้ดจริง — v1 จึงไม่มีข้อมูลของ 2way Platform, Domain Microservices, Meeting Platform, Mobile รุ่นใหม่, และ OCR/Auxiliary เลย

v2 (เล่มนี้) ขยายให้ครอบทั้ง 31 repositories ที่มีความลึกใกล้เคียงกับที่ v1 ทำกับ 5 repo เดิม (per-repo deep dive อยู่ใน Volume 3-10) ส่วนอีก 8 repositories ที่เป็น placeholder ว่างเปล่าถูกบันทึกสถานะไว้ใน Volume 10 เพื่อความสมบูรณ์ ไม่ใช่เพราะมีเนื้อหาให้เจาะลึก

สิ่งที่ v2 เพิ่มเข้ามาซึ่ง v1 ไม่มี — 10 volume ที่ไม่มีใน v1 เลย: Volume 0-2 (foundation แบบขยาย), Volume 11-16 (cross-cutting synthesis ข้าม repo ทั้งหมด — data model, security, API, business logic, infrastructure, runbook), และ Volume 17-20 (findings/roadmap แบบรวมศูนย์) — เหตุผลคือเมื่อจำนวน repo เพิ่มจาก 5 เป็น 31 คำถามที่สำคัญที่สุดไม่ใช่ "repo แต่ละตัวทำงานอย่างไร" (ตอบได้จาก deep dive) แต่คือ "ระบบทั้งก้อนเชื่อมกันอย่างไรและเสี่ยงร่วมกันตรงไหน" ซึ่งต้องมี volume สังเคราะห์แยกจึงตอบได้

ขั้นตอนถัดไป

ยังไม่คุ้นเคยกับธุรกิจของ VTRC เลย → ไป Volume 1 · Business Context
อยากเห็นภาพสถาปัตยกรรมก่อนลงรายละเอียด repo → ไป Volume 2 · Architecture & Topology
รู้ตัวเองต้องดูแล repo ไหนอยู่แล้ว → ไปที่ Volume ของกลุ่มนั้นตรง (ดูตารางด้านบน)

Volume 0 · Getting Started ​

เล่มนี้คืออะไร สำหรับใคร ​

โครงสร้างคู่มือ — ทำไมถึงแบ่งเป็น 21 volume, 4 ชั้น ​

แผนที่ 7 กลุ่มแพลตฟอร์ม (โดยย่อ) ​

วิธีนำทาง — ถามคำถามนี้ก่อนเปิดเล่มไหน ​

ถ้าจะอ่านแค่ 5 อย่างในคู่มือทั้งเล่ม ​

Citation convention — วิธีอ่านการอ้างอิงในคู่มือนี้ ​

Debt ID scheme — สัญกรณ์ที่ใช้ทั่วทั้งคู่มือ ​

v1 vs v2 — ทำไมต้องเขียนใหม่ทั้งเล่ม ​

ขั้นตอนถัดไป ​