VTRC Knowledge Manual
คู่มืออ้างอิงภายในสำหรับระบบ HR/Welfare ของสภากาชาดไทย
จัดทำโดยทีมที่ดูแลระบบ สำหรับวิศวกรและบุคลากรที่เข้ามาดูแลระบบต่อ
ระบบ VTRC คืออะไร
VTRC เป็นชุดเว็บแอปพลิเคชันและ API ที่พนักงานสภากาชาดไทยใช้ในงานด้าน HR ประจำวัน เช่น ดูสลิปเงินเดือน ขอลา เบิกสวัสดิการ และงานอื่น ๆ ที่เกี่ยวข้อง รวมถึงส่วนสำหรับฝ่าย HR ใช้พิจารณาและอนุมัติคำขอต่าง ๆ
ระบบนี้แบ่งการพัฒนาออกเป็น 6 repositories แยกกัน ภายใต้โฟลเดอร์ /Users/tnd/Documents/I3/vtrc/ — ไม่ใช่ monorepo ที่มี root package.json ร่วมกัน แต่ละ repository มี package.json, .git, และกระบวนการ deploy ของตนเอง: vtrc-api, vtrc-web, vtrc-rc-backoffice, cu-central-api, centralize-api, และ benefit-api
ระบบเริ่มเปิดใช้งานครั้งแรกราวปี 2019 และปัจจุบันยังทำงานบนเทคโนโลยีเดิม (Node.js 12, React 16, Apollo v2) สำหรับส่วนแกนกลาง ส่วน NestJS service (centralize-api, benefit-api) เป็นชั้นที่เพิ่มเข้ามาภายหลัง
วัตถุประสงค์ของคู่มือเล่มนี้
ก่อนหน้านี้มีเอกสารวิเคราะห์ระบบจำนวน 5 ไฟล์ (อยู่ใน /audit/) ซึ่งเขียนขึ้นอย่างละเอียดและมีคุณภาพ แต่เน้นไปที่การ ตรวจสอบหาข้อบกพร่อง และตั้งสมมติฐานว่าผู้อ่านเข้าใจ codebase อยู่แล้ว
คู่มือเล่มนี้จัดทำขึ้นเพื่อ สานต่องาน — เริ่มต้นจากผู้อ่านที่ยังไม่เคยพบเห็นระบบนี้มาก่อน และดำเนินเนื้อหาไปถึงจุดที่สามารถแก้ไขปัญหาหรือ deploy ระบบได้จริง
ข้อความทุกข้อในคู่มือมีการอ้างอิงเป็น file:line — หากพบข้อมูลที่ดูไม่ถูกต้อง ให้เปิดไฟล์ที่อ้างถึงเพื่อตรวจสอบก่อนเสมอ มิใช่การยึดถือคู่มือเป็นที่สุด
โครงสร้างคู่มือ
คู่มือแบ่งเนื้อหาออกเป็น 18 volumes เนื่องจากเนื้อหามีขอบเขตกว้างเกินกว่าจะจัดไว้ในไฟล์เดียว และผู้อ่านแต่ละกลุ่มสนใจเนื้อหาที่แตกต่างกัน
| Volume | ชื่อ | กลุ่มผู้อ่านที่เหมาะสม |
|---|---|---|
| 0 | Getting Started | ทุกคน — ควรอ่านก่อนเล่มอื่น |
| 1 | Business & Operations | HR, Operations, Product — ฟีเจอร์และกระบวนการทางธุรกิจ |
| 2 | Architecture & Topology | วิศวกรใหม่ — ภาพรวมทางเทคนิค |
| 3 | vtrc-api Deep Dive | วิศวกร — แกนกลางของระบบ |
| 4 | cu-central-api Deep Dive | วิศวกร — ระบบ identity และข้อมูล HR เดิม |
| 5 | centralize-api Deep Dive | วิศวกร — แนวทางการปรับปรุงระบบสมัยใหม่ |
| 6 | benefit-api Deep Dive | วิศวกร — service สวัสดิการ/การเบิกจ่าย |
| 7 | vtrc-web Deep Dive | วิศวกร — frontend ฝั่งพนักงาน |
| 8 | vtrc-rc-backoffice Deep Dive | วิศวกร — frontend ฝั่ง HR |
| 9 | Data Model & Persistence | วิศวกร — โครงสร้างตารางและ relation ทั้งหมด |
| 10 | Security & Authentication | วิศวกรและผู้ตรวจสอบ |
| 11 | API Reference | วิศวกร — endpoint ทั้งหมดของ GraphQL และ REST |
| 12 | Business Logic & Workflows | วิศวกร — state machine, กระบวนการอนุมัติ |
| 13 | Infrastructure & Deployment | DevOps, Site Reliability Engineer |
| 14 | Operational Runbooks | ผู้ดูแลระบบ — ขั้นตอนเมื่อเกิดเหตุ |
| 15 | Technical Debt Register | สถาปนิกซอฟต์แวร์, หัวหน้าทีมเทคนิค |
| 16 | Modernization Roadmap | สถาปนิกซอฟต์แวร์, หัวหน้าทีมเทคนิค |
| 17 | Appendices | สำหรับค้นหา — glossary, ดัชนีไฟล์, environment variables |
แนะนำลำดับการอ่าน
ลำดับการอ่านขึ้นอยู่กับวัตถุประสงค์ของผู้อ่าน
- ยังไม่เคยพบเห็นระบบนี้มาก่อน — เริ่มที่ Volume 0 ประมาณ 1 ชั่วโมง จากนั้นเลือกเล่มถัดไปตามบทบาท
- เป็น HR หรือ Operations ที่ต้องเข้าใจฟีเจอร์ — อ่าน Volume 0 แล้วไปต่อที่ Volume 1
- เป็นวิศวกรที่เข้ามาดูแลระบบ — อ่าน Volume 0, 2, 3, 9, 10, 11 ตามลำดับ
- ดูแลการ deploy หรือ infrastructure — อ่าน Volume 13 และ Volume 14
- ประเมินความเสี่ยง — อ่าน Volume 10, 15 และ
/audit/ - วางแผนการปรับปรุงระบบ — อ่าน Volume 5, 6, 15, 16
ข้อตกลงเรื่องภาษา
คู่มือเขียนเป็นภาษาไทย แต่ใช้คำทับศัพท์ภาษาอังกฤษในทุกกรณีที่นักพัฒนาไทยใช้งานจริง เช่น login, fetch, deploy, cache miss, query, mutation, token, session, resolve
เหตุผลคือ โค้ดทั้งหมดเป็นภาษาอังกฤษ หากแปลเป็นไทยล้วน คู่มือจะไม่สอดคล้องกับโค้ด — ผู้อ่านจะไม่ทราบว่าควรเปิดดูในไฟล์ใด เช่น resolvers/slip.js ตรงส่วนใด
หากพบคำศัพท์ที่ไม่แน่ใจ สามารถดูคำอธิบายได้ใน Volume 17 และคำศัพท์สั้น 50 คำใน บท 0.6
ข้อควรทราบตอนอ่าน
คู่มือเล่มนี้เขียนจาก codebase ที่ commit แล้วใน workspace ณ เวลาที่จัดทำ หากมีการแก้ไขโค้ดครั้งใหญ่ เนื้อหาบางส่วนอาจล้าสมัย — ก่อนดำเนินการใด ๆ ตามคู่มือ ควรเปิดไฟล์ที่อ้างถึงเพื่อตรวจสอบก่อนเสมอ
หากพบเนื้อหาที่ไม่ถูกต้องหรือค้างเคาะ สามารถแก้ไขได้ทันที — คู่มือเล่มนี้อยู่ในโฟลเดอร์ docs/ และ build ด้วย VitePress สามารถรัน npm run dev ในโฟลเดอร์ docs/ แล้วดูผลลัพธ์ที่ http://localhost:5173/