2 · Core pipeline — ตั้งตัวชี้วัด → ประเมินผล → อนุมัติ → ปรับเงินเดือน

pms-api มี flow ที่ยาวกว่า repo อื่นในกลุ่มมาก เพราะครอบคลุมทั้งวงจรการบริหารผลงานประจำปี บทนี้ประกอบภาพจากโครงสร้าง module, controller endpoint, และเอกสารที่ทีม dev เขียนไว้เอง (docs/PMS-Period-Notification-System.md) — ส่วนที่ไม่มีหลักฐาน citation ตรงจะระบุว่าเป็นการอนุมานจากชื่อ module/endpoint

ภาพรวม flow (อนุมานจากลำดับ module + endpoint ที่มี)

ต้นปีงบประมาณ — ฝ่าย HR ตั้งค่ารอบ (period)
       │
       ▼
1) PeriodModule — กำหนดช่วงเวลา settingGoalStart/End, checkDataStart, updateResultStart,
                   evaluationStart/End, feedbackEnd ต่อ tbPeriod (fiscalYear, status='confirm')
       │
       ├─ ConfigNotificationModule ผูกกับ period นี้ — ตั้งว่าจะแจ้งเตือนใครที่วันไหน (isEvaluatee/isEvaluator/isApprover/isOrgUnitAdmin)
       │      └─ cron ทุกวัน 6 โมงเช้า ตรวจว่าวันนี้ตรงกับวันแจ้งเตือนของ notification type ใดหรือไม่ → ส่ง email
       │
       ▼
2) IndicatorType / Indicator / IndicatorWeight / RatingScale / Grading / GradeLimit
       │
       └─ ฝ่าย HR ตั้งตัวชี้วัดกลาง + scale การให้คะแนน + สัดส่วนเกรด (forced distribution ต่อ gradeLimit)
       │
       ▼
3) CreateFormModule (2,701 บรรทัด) — สร้างแบบประเมินจากตัวชี้วัดที่ตั้งไว้ ผูกกับ evaluateUserAmount (รายชื่อผู้ถูกประเมินต่อรอบ)
       │
       ▼
4) EvaluateFormModule (2,996 บรรทัด — ใหญ่สุดในทั้ง repo) — พนักงาน/หัวหน้ากรอกแบบประเมินจริง
       │
       ├─ getEvaluateFormList / getEvaluateFormSalaryList — ติดตามสถานะการประเมิน + สถานะที่เกี่ยวกับเงินเดือน
       └─ exportPDFEvaluations / exportPDFEvaluationsMobile — puppeteer generate PDF ผลประเมินต่อคน
       │
       ▼
5) ApproverModule (546 บรรทัด) — จัดการสายอนุมัติ + เปลี่ยนผู้อนุมัติ (delegate) ระหว่างทาง
       │
       ▼
6) ConfirmEvaluationModule (1,240 บรรทัด) — ยืนยันผลประเมินระดับหน่วยงาน (org unit) ก่อนเข้าสู่กระบวนการปรับเงินเดือน
       │
       ├─ orgUnit/update_no_quota — ปรับกรณีหน่วยงานไม่มีโควต้าเกรด
       ├─ orgUnit/update_reject — ปฏิเสธผลรวมของหน่วยงาน ส่งกลับไปแก้
       └─ orgUnit/confirm_update_status — ยืนยันผลของหน่วยงาน
       │
       ▼
7) BudgetModule — จัดสรรงบประมาณปรับเงินเดือนต่อหน่วยงาน (มี endpoint getEmployeeSalary ที่เป็น @Public() — ดู scorecard)
       │
       ▼
8) SalaryRange → SalaryPercentage → SalaryAdjust → SalaryAdjustment (2,367 บรรทัด)
       │
       └─ คำนวณ % ปรับเงินเดือนตามเกรดผลประเมิน + budget ของหน่วยงาน แล้วบันทึกเป็น SalaryAdjustBu/SalaryAdjustHd/SalaryAdjustDt
       │
       ▼
9) SalaryAdjustToHRMIModule (554 บรรทัด) — export ผลการปรับเงินเดือนเป็นไฟล์ Excel (`exceljs`) สำหรับนำเข้าระบบ HRMI
       │      (ต่างจาก recruitment-api ที่ export ไป HRMI ผ่าน HTTP + email — ที่นี่ export เป็นไฟล์ Excel ให้ทีม HR นำเข้าด้วยมือ)
       │
       ▼
10) ReportModule — สรุปผลประเมิน/การปรับเงินเดือนระดับองค์กร

หลักฐาน — โครงสร้าง module: pms-api/src/app.module.ts (branch: uat):83-113, notification cron: pms-api/docs/PMS-Period-Notification-System.md (branch: uat):1-142 + pms-api/src/modules/configNotification/configNotification.controller.ts (branch: uat):27-41, evaluateForm endpoint: pms-api/src/modules/evaluateForm/evaluateForm.controller.ts (branch: uat):28-60, confirmEvaluation endpoint: pms-api/src/modules/confirmEvaluation/confirmEvaluation.controller.ts (branch: uat):24-50, salaryAdjustment endpoint: pms-api/src/modules/salaryAdjustment/salaryAdjustment.controller.ts (branch: uat):25-50, salaryAdjustToHRMI export: pms-api/src/modules/salaryAdjustToHRMI/salaryAdjustToHRMI.service.ts (branch: uat):1-18 (import exceljs)

หมายเหตุความเชื่อมั่นของ flow นี้ — ลำดับ 1-10 ข้างต้นอนุมานจากชื่อ module, endpoint, และความสัมพันธ์ entity เป็นหลัก ไม่ได้ trace โค้ดทีละบรรทัดแบบที่ทำกับ benefit-api/recruitment-api เนื่องจากขนาด service ที่ใหญ่กว่ามาก (service ใหญ่สุดของ repo นี้ยาวเป็น 2 เท่าของ repo อื่น) — ควรถือเป็น โครงกระดูก (skeleton) ที่ยืนยันได้ระดับ module ไม่ใช่ trace เต็มรูปแบบระดับ field-by-field เหมือนบทเดียวกันของ benefit-api

จุดที่ควรรู้

workforce sync ที่ทำงานคู่ขนานกับ flow หลัก

UsagePermissionService.handleCron (@Cron('*/1 * * * *')) ดึงข้อมูล employee trigger queue จาก workforce connection ทุก 1 นาที เพื่ออัปเดตข้อมูลองค์กร/ตำแหน่งให้ตรงกับระบบ workforce กลาง (pms-api/src/modules/usagePermission/usagePermission.service.ts (branch: uat):1698-1937) — ข้อมูลที่ evaluateForm/confirmEvaluation/salaryAdjustment ใช้ (org unit, position, salary range) ขึ้นอยู่กับความสด (freshness) ของ sync job นี้เป็นสำคัญ ถ้า cron หยุดทำงานเงียบ ๆ ข้อมูลองค์กรใน pms-api จะ drift จาก workforce โดยไม่มี alert ใดแจ้ง (ไม่พบ health-check/alert สำหรับ cron นี้)

Budget public endpoint คั่นกลาง flow

GET /budget/getEmployeeSalary เป็น @Public() (pms-api/src/modules/budget/budget.controller.ts (branch: uat):49-53) อยู่ตรงกลางของ flow ปรับเงินเดือน (step 7) — คืนเงินเดือนพนักงานตามหน่วยงานโดยไม่ต้อง login ดูรายละเอียดที่ 06 Scorecard (SEC-PMS-01)

เคล็ดลับตอนทำงานจริง

• ก่อนแก้ logic ในกลุ่ม salary (5 module) ให้ไล่ดู entity salaryAdjustBu/salaryAdjustHd/salaryAdjustDt ก่อนเสมอเพื่อแยกว่าข้อมูลอยู่ระดับหน่วยงาน (Bu) หรือระดับเอกสาร (Hd/Dt)
• ถ้า sync จาก workforce ดูเหมือนขาดข้อมูล ให้ตรวจ usagePermission cron ก่อนอันดับแรก เพราะเป็นจุดเดียวที่ sync ข้อมูลองค์กรเข้า pms-api แบบอัตโนมัติ

ไป บท 3 Persistence →