8.5 · GraphQL queries + mutations catalog

บทนี้สรุป GraphQL operations ทั้งหมดที่ vtrc-rc-backoffice ส่งไป vtrc-api — รวม 120 queries + 94 mutations — จัดเป็นกลุ่มฟีเจอร์ พร้อมทั้งระบุไฟล์ที่เก็บและวิธีใช้

ภาพรวม

ประเภท	ไฟล์	บรรทัด	จำนวน operations
Queries (main)	`src/graphql/queries.js`	4,108	120
Mutations (main)	`src/graphql/mutations.js`	2,208	94
Queries (WorkForce)	`src/graphql/WorkForce/queries.js`	~1,500	~40
Mutations (WorkForce)	`src/graphql/WorkForce/mutations.js`	~900	~30
Re-export	`src/graphql/index.js`	5	—

รูปแบบนิยาม — ตัวอย่าง

// src/graphql/queries.js (ตัวอย่าง shape)
import gql from "graphql-tag";

const FETCH_USERS = gql`
  query FetchUsers($page: Int, $limit: Int, $search: String) {
    fetchUsers(page: $page, limit: $limit, search: $search) {
      id
      username
      firstName
      lastName
      email
      role { id name }
    }
  }
`;

// ไฟล์ปิดท้ายด้วย export default { ... } ไม่ใช่ export const
export default {
  FETCH_USERS,
  // ... 120 queries
};

ข้อระวังเรื่องรูปแบบ

ใช้ export default { ... } ไม่ใช่ export const — ทำให้ grep หา ^export const ไม่เจอ
ชื่อ query ในไฟล์เป็น UPPER_SNAKE_CASE แต่ operation name ใน gql เป็น camelCase (เช่น FetchUsers)
มี snapshot หลายตัว — queries_bk.js, queries_bk-061265.js, mutations_bk.js — ห้ามใช้

วิธี import ใน component

// แบบที่ 1: import ทั้ง object (พบบ่อยในไฟล์เก่า)
import Queries from "../graphql/queries";
import Mutations from "../graphql/mutations";

// ใช้
this.props.client.query({
  query: Queries.FETCH_USERS,
  variables: { page: 1, limit: 20 },
});

// แบบที่ 2: import เฉพาะตัว (พบในไฟล์ใหม่)
import { useQuery } from "@apollo/react-hooks";
import Queries from "../graphql/queries";

const { data, loading } = useQuery(Queries.FETCH_USERS, {
  variables: { page: 1 },
});

ข้อสังเกต

ไฟล์เก่าใช้ withApollo HOC + this.props.client.query() (class component)
ไฟล์ใหม่ใช้ useQuery hook (function component) — แต่ก็ยังอิงจาก Apollo v2

Queries — จัดกลุ่มตามฟีเจอร์

1. Auth / user / role

Query	ความหมาย
`ME`	ข้อมูลผู้ใช้ปัจจุบัน
`FETCH_USERS`	รายการผู้ใช้ทั้งหมด
`FETCH_USER_BY_ID`	รายละเอียดผู้ใช้รายคน
`FETCH_ROLES`	รายการ role
`FETCH_PERMISSIONS`	รายการ permission
`CHECK_TOKEN`	ตรวจ token ที่ login

2. Organization / career / course

Query	ความหมาย
`FETCH_ORGANIZATIONS`	รายการหน่วยงาน
`FETCH_ORGANIZATION_GROUPS`	กลุ่มหน่วยงาน
`FETCH_CAREERS`	รายการเส้นทางอาชีพ
`FETCH_COURSES`	รายการหลักสูตร
`FETCH_COURSE_BY_ID`	รายละเอียดหลักสูตร

3. Document / policy

Query	ความหมาย
`FETCH_DOCUMENTS`	รายการเอกสาร
`FETCH_DOCUMENT_GROUPS`	กลุ่มเอกสาร
`FETCH_POLICIES`	รายการนโยบาย
`FETCH_POLICY_OFFICER_DOCS`	เอกสารนโยบายสำหรับเจ้าหน้าที่

4. Hospital / medical claim

Query	ความหมาย
`FETCH_HOSPITALS`	รายการโรงพยาบาล
`FETCH_HOSPITAL_HR`	โรงพยาบาลฝั่ง HR
`FETCH_HOSPITAL_PAID`	การเบิกที่จ่ายแล้ว
`FETCH_HOSPITAL_FAILED`	การเบิกที่ล้มเหลว
`FETCH_SICKNESS_NAMES`	รายการชื่อโรค

5. Leave (ระบบลา)

Query	ความหมาย
`FETCH_LEAVES`	รายการใบลา
`FETCH_LEAVE_HR`	ใบลาฝั่ง HR
`FETCH_LEAVE_STUDIES`	ใบลาศึกษา
`FETCH_LEAVE_STUDIES_PAYMENTS`	การเบิกค่าเล่าเรียน
`FETCH_LEAVE_STUDIES_SCHOLAR`	ทุนการศึกษา
`FETCH_DELEGATES`	ผู้รับมอบฉันทะ

6. Welfare / fund

Query	ความหมาย
`FETCH_OTHER_WELFARE`	สวัสดิการอื่น
`FETCH_FUNDS`	กองทุนสงเคราะห์
`FETCH_BANK_BRANCHES`	สาขาธนาคาร

7. News / notification

Query	ความหมาย
`FETCH_NEWS`	รายการข่าว
`FETCH_NEWS_BY_ID`	รายละเอียดข่าว
`FETCH_NOTIFICATIONS`	การแจ้งเตือน

8. System / dashboard

Query	ความหมาย
`FETCH_DASHBOARD_STATS`	สถิติหน้าแรก
`FETCH_SETTINGS`	การตั้งค่าระบบ
`FETCH_ABOUT_US`	เกี่ยวกับเรา

9. Recruitment

Query	ความหมาย
`FETCH_ANNOUNCEMENTS`	ประกาศรับสมัคร
`FETCH_CANDIDATES`	ผู้สมัคร
`FETCH_PREVIEW_EMAIL`	preview อีเมล

10. WorkForce module (ไฟล์ `WorkForce/queries.js`)

Query	ความหมาย
`FETCH_EMPLOYEES`	รายการพนักงาน
`FETCH_POSITIONS_MANAGE`	ตำแหน่งบริหาร
`FETCH_POSITIONS_TECHNICAL`	ตำแหน่งวิชาการ
`FETCH_PROFESSIONAL_LICENSES`	ใบประกอบวิชาชีพ (typo — `Perfessional`)
`FETCH_MANPOWER_MANAGE`	อัตรากำลัง
`FETCH_LEARNING`	หลักสูตรฝึกอบรม

Mutations — จัดกลุ่มตามฟีเจอร์

1. Auth / user / role

Mutation	ความหมาย
`LOGIN`	เข้าสู่ระบบ
`LOGIN_BACKOFFICE`	login สำหรับ backoffice (ต่างจาก vtrc-web)
`REFRESH_TOKEN`	ขอ token ใหม่
`CREATE_USER`	สร้างผู้ใช้
`UPDATE_USER`	แก้ไขผู้ใช้
`DELETE_USER`	ลบผู้ใช้
`CHANGE_PASSWORD`	เปลี่ยนรหัสผ่าน
`FORGET_PASSWORD`	ลืมรหัสผ่าน
`CONFIRM_USER_A1` / `CONFIRM_USER_A2`	ยืนยันผู้ใช้ 2 ขั้น
`SET_PASSWORD_FIRST_TIME`	ตั้งรหัสผ่านครั้งแรก

2. Organization / career / course

Mutation	ความหมาย
`CREATE_ORGANIZATION`	สร้างหน่วยงาน
`UPDATE_ORGANIZATION`	แก้ไขหน่วยงาน
`DELETE_ORGANIZATION`	ลบหน่วยงาน
`CREATE_CAREER` / `UPDATE_CAREER` / `DELETE_CAREER`	จัดการเส้นทางอาชีพ
`CREATE_COURSE` / `UPDATE_COURSE` / `DELETE_COURSE`	จัดการหลักสูตร

3. Document / policy

Mutation	ความหมาย
`CREATE_DOCUMENT`	สร้างเอกสาร
`UPDATE_DOCUMENT`	แก้ไขเอกสาร
`DELETE_DOCUMENT`	ลบเอกสาร
`CREATE_POLICY`	สร้างนโยบาย

4. Hospital / medical claim

Mutation	ความหมาย
`CREATE_HOSPITAL`	สร้างโรงพยาบาล
`UPDATE_HOSPITAL_PAID`	อัปเดตการจ่าย
`REJECT_HOSPITAL_CLAIM`	ปฏิเสธการเบิก
`IMPORT_HOSPITAL`	import หลายรายการ

5. Leave (ระบบลา)

Mutation	ความหมาย
`CREATE_LEAVE`	สร้างใบลา
`APPROVE_LEAVE`	อนุมัติใบลา
`REJECT_LEAVE`	ปฏิเสธใบลา
`CREATE_LEAVE_STUDIES_PAYMENT`	สร้างการเบิกค่าเล่าเรียน
`APPROVE_LEAVE_STUDIES_PAYMENT`	อนุมัติการเบิก
`CREATE_DELEGATE`	ตั้งผู้รับมอบฉันทะ

6. Welfare / fund

Mutation	ความหมาย
`CREATE_OTHER_WELFARE`	สร้างสวัสดิการอื่น
`APPROVE_OTHER_WELFARE`	อนุมัติสวัสดิการ
`CREATE_FUND`	สร้างกองทุน
`UPDATE_FUND`	แก้ไขกองทุน

7. News / notification

Mutation	ความหมาย
`CREATE_NEWS`	สร้างข่าว
`UPDATE_NEWS`	แก้ไขข่าว
`DELETE_NEWS`	ลบข่าว
`MARK_NOTIFICATION_READ`	ทำเครื่องหมายว่าอ่านแล้ว

8. Recruitment

Mutation	ความหมาย
`CREATE_ANNOUNCEMENT`	สร้างประกาศรับสมัคร
`UPDATE_CANDIDATE_STATUS`	อัปเดตสถานะผู้สมัคร
`SEND_EMAIL_CANDIDATE`	ส่งอีเมลให้ผู้สมัคร

9. WorkForce module (ไฟล์ `WorkForce/mutations.js`)

Mutation	ความหมาย
`CREATE_EMPLOYEE`	สร้างพนักงาน
`UPDATE_EMPLOYEE`	แก้ไขพนักงาน
`CREATE_POSITION_MANAGE`	สร้างตำแหน่งบริหาร
`ASSIGN_MANPOWER`	กำหนดอัตรากำลัง

10. Misc / utility

Mutation	ความหมาย
`UPLOAD_FILE`	อัปโหลดไฟล์
`DELETE_FILE`	ลบไฟล์
`EVENT_LOG`	บันทึก log event

รูปแบบ query ที่ต้องระวัง

Query ที่ return ฟิลด์เยอะมาก

graphql

# ตัวอย่าง — query ที่ดึงฟิลด์เกือบทั้งตาราง
query FetchLeaveStudiesPayments($id: ID!) {
  fetchLeaveStudiesPayments(id: $id) {
    id
    user { id firstName lastName lastNameEn idCard position { id name } organization { id name } }
    amount
    status
    approver { id firstName }
    attachments { id filename url }
    course { id name startDate endDate }
    scholar { id name gpa }
    paymentHistory { id amount date method }
    # ... อีก 30+ ฟิลด์
  }
}

ปัญหา: return payload ใหญ่ ทำให้ response ช้าและ server โหลดหนัก

คำแนะนำ: ดึงเฉพาะฟิลด์ที่ใช้ — แต่ทำได้ยากเพราะใช้ร่วมกันหลาย component

Query ที่มี `$search` ที่เป็น string ยาว

graphql

query FetchUsers($search: String) {
  fetchUsers(search: $search) { ... }
}

ถ้าผู้ใช้ค้นหาด้วยคำยาว — backend อาจต้อง LIKE '%search%' ทำให้ query DB ช้า (ดู Volume 9 บท 8.4 เรื่อง index)

Mutation ที่รับ input ขนาดใหญ่

graphql

mutation CreateOtherWelfare($input: OtherWelfareInput!) {
  createOtherWelfare(input: $input) { id }
}

OtherWelfareInput มีฟิลด์ 50+ ทำให้ validation ฝั่ง server หนัก และถ้า field validation ผิด 1 ตัว — request ทั้งหมดล้มเหลว

N+1 pattern — ที่พบบ่อย

// ในหน้า list ที่มี relation
const { data } = useQuery(Queries.FETCH_LEAVES);
// แล้วใน render:
data.fetchLeaves.map((leave) => (
  <LeaveCard
    key={leave.id}
    leave={leave}
    approver={/* ดึงแยก */}
  />
));

// ใน LeaveCard:
const { data: approverData } = useQuery(Queries.FETCH_USER_BY_ID, {
  variables: { id: leave.approverId },
});

ปัญหา: ถ้ามี 20 รายการใน list จะเกิด 20 request FETCH_USER_BY_ID แยก — เป็น N+1 problem

คำแนะนำ: ให้ query หลัก (FETCH_LEAVES) return relation (approver) มาด้วย — ลดจำนวน request

ข้อระวังเมื่อแก้ไข query

1. อย่าลบฟิลด์โดยไม่ตรวจ

ถ้าลบฟิลด์จาก query (เช่น ลบ email ออกจาก FETCH_USERS) — component อื่นที่อ่าน data.fetchUsers[i].email จะได้ undefined และอาจพัง

วิธีที่ปลอดภัย:

grep ชื่อ query ในไฟล์ทั้งหมด เพื่อหาผู้ใช้
ตรวจว่าทุก component ที่ใช้ query นั้น ยังใช้ฟิลด์ที่จะลบหรือไม่
ถ้าไม่มีผู้ใช้ — ลบได้

2. ระวังการเปลี่ยนชื่อ operation

ถ้าเปลี่ยน FetchUsers → GetUsers — ต้องเปลี่ยนทุกที่ที่ import และเรียกใช้

3. อย่าเพิ่ม fragment ในไฟล์เก่า

ไฟล์ queries.js ไม่ได้ใช้ fragment — ทุก query เขียนฟิลด์ตรงๆ ถ้าจะเพิ่ม fragment ต้องทำทั้งไฟล์ ไม่งั้นจะผสม style

เปรียบเทียบกับ vtrc-web

ด้าน	vtrc-rc-backoffice	vtrc-web
Query count	120	~80
Mutation count	94	~50
รูปแบบ export	`export default { ... }`	เหมือนกัน
Fragment	ไม่ใช้	ไม่ใช้
ไฟล์ WorkForce	มี (แยก)	ไม่มี
`withApollo`	ใช้ (module เก่า)	ใช้
`useQuery`	ใช้ (module ใหม่)	ใช้บ้าง

เคล็ดลปตอนค้นหา query

หาว่า query ทำอะไร

grep ชื่อ query ใน src/graphql/queries.js
ดู operation name + argument + return type
ถ้าไม่ชัด — ดูใน Volume 3 บท 3.2 สำหรับ resolver

หาว่าใครใช้ query นี้

bash

# ใน IDE — ใช้ Grep tool
pattern: "FETCH_USERS"
path: src/pages

จะเจอไฟล์ทุกตัวที่ import + เรียก query นี้

หาว่า query ตรงกับ resolver ไหนฝั่ง server

ดู vtrc-api/api/src/typeDefs/*.js และ vtrc-api/api/src/resolvers/*.js (ดู Volume 3)

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

ไป บท 7.6 Component + Recoil + MUI architecture →

8.5 · GraphQL queries + mutations catalog ​

ภาพรวม ​

รูปแบบนิยาม — ตัวอย่าง ​

ข้อระวังเรื่องรูปแบบ ​

วิธี import ใน component ​

ข้อสังเกต ​

Queries — จัดกลุ่มตามฟีเจอร์ ​

1. Auth / user / role ​

2. Organization / career / course ​

3. Document / policy ​

4. Hospital / medical claim ​

5. Leave (ระบบลา) ​

6. Welfare / fund ​

7. News / notification ​

8. System / dashboard ​

9. Recruitment ​

10. WorkForce module (ไฟล์ WorkForce/queries.js) ​

Mutations — จัดกลุ่มตามฟีเจอร์ ​

1. Auth / user / role ​

2. Organization / career / course ​

3. Document / policy ​

4. Hospital / medical claim ​

5. Leave (ระบบลา) ​

6. Welfare / fund ​

7. News / notification ​

8. Recruitment ​

9. WorkForce module (ไฟล์ WorkForce/mutations.js) ​

10. Misc / utility ​

รูปแบบ query ที่ต้องระวัง ​

Query ที่ return ฟิลด์เยอะมาก ​

Query ที่มี $search ที่เป็น string ยาว ​

Mutation ที่รับ input ขนาดใหญ่ ​

N+1 pattern — ที่พบบ่อย ​

ข้อระวังเมื่อแก้ไข query ​

1. อย่าลบฟิลด์โดยไม่ตรวจ ​

2. ระวังการเปลี่ยนชื่อ operation ​

3. อย่าเพิ่ม fragment ในไฟล์เก่า ​

เปรียบเทียบกับ vtrc-web ​

เคล็ดลปตอนค้นหา query ​

หาว่า query ทำอะไร ​

หาว่าใครใช้ query นี้ ​

หาว่า query ตรงกับ resolver ไหนฝั่ง server ​

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

8.5 · GraphQL queries + mutations catalog

ภาพรวม

รูปแบบนิยาม — ตัวอย่าง

ข้อระวังเรื่องรูปแบบ

วิธี import ใน component

ข้อสังเกต

Queries — จัดกลุ่มตามฟีเจอร์

1. Auth / user / role

2. Organization / career / course

3. Document / policy

4. Hospital / medical claim

5. Leave (ระบบลา)

6. Welfare / fund

7. News / notification

8. System / dashboard

9. Recruitment

10. WorkForce module (ไฟล์ `WorkForce/queries.js`)

Mutations — จัดกลุ่มตามฟีเจอร์

1. Auth / user / role

2. Organization / career / course

3. Document / policy

4. Hospital / medical claim

5. Leave (ระบบลา)

6. Welfare / fund

7. News / notification

8. Recruitment

9. WorkForce module (ไฟล์ `WorkForce/mutations.js`)

10. Misc / utility

รูปแบบ query ที่ต้องระวัง

Query ที่ return ฟิลด์เยอะมาก

Query ที่มี `$search` ที่เป็น string ยาว

Mutation ที่รับ input ขนาดใหญ่

N+1 pattern — ที่พบบ่อย

ข้อระวังเมื่อแก้ไข query

1. อย่าลบฟิลด์โดยไม่ตรวจ

2. ระวังการเปลี่ยนชื่อ operation

3. อย่าเพิ่ม fragment ในไฟล์เก่า

เปรียบเทียบกับ vtrc-web

เคล็ดลปตอนค้นหา query

หาว่า query ทำอะไร

หาว่าใครใช้ query นี้

หาว่า query ตรงกับ resolver ไหนฝั่ง server

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