alla-tms/docs/pre-sprint-6-stabilization-review.md

Pre-Sprint 6 Stabilization Review

Summary

งาน pre-sprint รอบนี้โฟกัสที่การปิดช่องโหว่ด้าน authorization, ความสม่ำเสมอของ dashboard, การลด hardcoded policy target, การปรับข้อความภาษาไทยบนหน้าหลักของ TMS และการ harden workflow ของ Employee Import และ Master Review ก่อนเริ่ม Sprint 6

ผลลัพธ์หลัก:

• ยืนยันว่า dashboard และการคำนวณชั่วโมงหลักใช้เฉพาะรายการ APPROVED
• เอา default training target แบบ hardcoded 30 / 12 / 12 / 6 ออกจาก runtime fallback
• ปิด route/API protection ที่ยังขาดใน proxy.ts สำหรับ training policy, employee import และ master review
• ปรับข้อความ API/UI หลายจุดเป็นภาษาไทยให้สอดคล้องกับ TMS
• เพิ่ม downloadable error summary สำหรับ employee import
• ตรวจซ้ำ org scoping และ duplicate prevention ของ master review / import flow

Files Changed

• src/proxy.ts
• src/features/training-policy/constants/training-policy-defaults.ts
• src/features/training-policy/components/training-policy-page.tsx
• src/features/training-policy/components/training-policy-form.tsx
• src/features/training-policy/schemas/training-policy.ts
• src/app/api/training-policies/route.ts
• src/app/api/training-policies/[id]/route.ts
• src/app/api/training-records/route.ts
• src/app/api/training-records/[id]/route.ts
• src/app/api/training-records/[id]/review/route.ts
• src/app/api/training-records/[id]/certificates/route.ts
• src/app/api/training-records/[id]/certificates/[certificateId]/route.ts
• src/app/api/import-employees/route.ts
• src/app/api/master-review/route.ts
• src/features/import-employees/components/employee-import-page.tsx
• src/features/import-employees/components/master-review-page.tsx
• src/features/courses/components/course-tables/index.tsx
• src/features/training-matrix/components/training-compliance-card.tsx
• src/features/training-matrix/components/training-matrix-tables/columns.tsx
• src/features/training-matrix/components/training-matrix-tables/options.tsx
• src/app/dashboard/pending-review/page.tsx
• src/app/dashboard/training-policy/page.tsx
• src/app/dashboard/import-employees/page.tsx
• src/app/dashboard/master-review/page.tsx

Issues Found

1. proxy.ts ยังไม่ได้บังคับ auth กับบาง API route ที่เป็น HRD flow
2. Training policy fallback ยังมีค่าฮาร์ดโค้ด 30 / 12 / 12 / 6
3. Empty state บางจุดยังอ้างอิง target เดิมแบบฮาร์ดโค้ด
4. ข้อความ UI/API หลายจุดยังเป็นอังกฤษหรือมีอาการ encoding เพี้ยน
5. Employee import ยังไม่มีไฟล์สรุป error สำหรับดาวน์โหลด

Issues Fixed

1. เพิ่ม protected API prefixes และ matcher ใน src/proxy.ts สำหรับ:
   • /api/training-policies
   • /api/import-employees
   • /api/master-review
2. เปลี่ยน default fallback training policy เป็น 0 / 0 / 0 / 0 ใน src/features/training-policy/constants/training-policy-defaults.ts
3. ปรับ training policy page/form และ validation message เป็นภาษาไทย
4. ปรับ training records review/certificate/training-policy/import/master-review API messages เป็นภาษาไทย
5. เพิ่มปุ่มดาวน์โหลด CSV สรุป error ใน employee import page
6. ปรับ master review UI และ employee import UI ให้เป็นภาษาไทยและมี empty/result state ที่อ่านง่ายขึ้น

Authorization Review

Pages

HRD-only pages ถูกป้องกัน server-side แล้วผ่าน requireHRDDashboardAccess():

• /dashboard/pending-review
• /dashboard/training-policy
• /dashboard/import-employees
• /dashboard/master-review

ผลการตรวจ:

• direct URL access จาก role user ควรถูกบล็อกที่ page guard
• nav filtering ยังเป็นเพียง UX layer ตามสถาปัตยกรรมเดิม

APIs

ตรวจ route handlers ที่เกี่ยวข้องแล้ว:

• training-policies ใช้ requireOrganizationAccess() และเช็ก role ระดับ reviewer/admin
• import-employees ใช้ requireOrganizationAccess() และเช็กสิทธิ์ HRD/admin
• master-review ใช้ requireOrganizationAccess() และเช็กสิทธิ์ HRD/admin
• training-records review/certificate/update/delete มีการบังคับสิทธิ์และ owner/org scoping ฝั่ง server

Fix Applied

เดิม proxy.ts ยังไม่ครอบ /api/training-policies, /api/import-employees, /api/master-review จึงเพิ่ม matcher เพื่อไม่ให้ route เหล่านี้หลุดออกจาก middleware auth layer

Localization Review

จุดที่ปรับแล้ว:

• Training Policy page/form
• Employee Import page
• Master Review page
• Pending Review page header
• Training matrix table labels / compliance card
• Course empty state
• Training record review/certificate/import/master-review/training-policy API response messages

หลักการที่คงไว้:

• UI label/message ใช้ภาษาไทย
• internal enum/db values เช่น approved, pending, department, position ยังคงเป็นภาษาอังกฤษตาม schema/runtime contract เดิม

Dashboard Review

Approved Records Only

ตรวจแล้วว่าการคำนวณหลักใช้เฉพาะรายการอนุมัติ:

• src/features/overview/server/overview-data.ts
• src/features/training-matrix/server/training-matrix-data.ts
• src/features/reports/server/report-data.ts

ผลลัพธ์:

• Total training hours ใช้ approved records
• Dashboard summary K/S/A ใช้ approved records
• Employee dashboard progress ผูกกับ policy + approved records
• Training matrix compliance ใช้ approved records

Hardcoded Target Review

พบ hardcoded training target เดิมใน runtime flow ที่เกี่ยวกับ policy:

• src/features/training-policy/constants/training-policy-defaults.ts
• src/features/training-policy/components/training-policy-page.tsx

การแก้ไข:

• เอา fallback 30 / 12 / 12 / 6 ออก
• ให้ระบบอ่านค่าจาก Training Policy จริงเป็นหลัก
• ถ้ายังไม่มี policy สำหรับ organization จะ fallback เป็น 0

หมายเหตุ:

• ตัวเลข 30 / 60 / 90 / 180 ใน reports ใช้สำหรับ filter วันหมดอายุใบรับรอง ไม่ใช่ training target
• ตัวเลข 6 บางจุดใน overview เป็นจำนวนเดือนย้อนหลัง ไม่ใช่ policy target

Import Review

Current Validation / Hardening

ตรวจ flow import แล้วพบว่ารองรับ:

• duplicate employee code / email ด้วยการ update user เดิมตามเงื่อนไขของระบบ
• invalid status handling
• invalid template / missing required columns
• clear Thai error messages ใน API response
• downloadable CSV error summary จากหน้า UI

Pending Master Data

import flow สร้าง pending master data เฉพาะกรณีจำเป็น และสรุปจำนวน:

• pending companies
• pending departments
• pending positions

Master Review

Review Actions

ตรวจแล้วว่า approve / reject ทำงานผ่าน server-side route เดิมโดยไม่เปลี่ยนโครงสร้างระบบ

Duplicate Prevention

duplicate department/position ถูกกันด้วยการตรวจข้อมูลเดิมก่อน insert ใน import flow และใช้รายการ pending/master data ที่แยกจากกัน

Organization Scope

review action และผลกระทบที่ตามมาอ้างอิง active organization ของ session ปัจจุบัน ไม่เปิดช่องให้อนุมัติ/ปฏิเสธข้าม organization

Remaining Technical Debt

1. ยังมีหน้า legacy/non-TMS บางส่วนที่ใช้ภาษาอังกฤษ ซึ่งอยู่นอกขอบเขต pre-sprint นี้
2. npm run lint ผ่านในระดับใช้งานได้ แต่ยังมี warning เดิมในไฟล์ที่ไม่เกี่ยวกับ sprint นี้:
   • src/components/ui/slider.tsx
   • src/components/ui/calendar.tsx
   • src/features/products/components/product-form.tsx
   • src/components/kbar/render-result.tsx
   • src/constants/mock-api-users.ts
   • src/constants/mock-api.ts
3. ยังควรมี regression test เชิง integration สำหรับ HRD-only routes และ import/master review workflow ใน Sprint 6

Recommended Sprint 6 Scope

1. เพิ่ม automated regression coverage สำหรับ auth + import + review flow
2. เก็บ Thai localization ให้ครบทุก TMS surface ที่ยังเหลือ
3. ทำ audit ของ notification flow และ dashboard aggregates เพิ่มเติม
4. พิจารณาเพิ่ม observability/logging สำหรับ import job และ review action