# Management Change Import Employee KSA Targets Review

## 1. Summary

เพิ่มการนำเข้าชั่วโมงเป้าหมายรายบุคคล K/S/A ผ่านหน้า Import Employees โดยยังคงพฤติกรรมเดิมของการนำเข้าพนักงานไว้ครบถ้วน และเพิ่ม fallback จาก `Training Policy` เมื่อแถวใดไม่ระบุเป้าหมายรายบุคคล

ลำดับการ resolve เป้าหมายที่ระบบใช้หลังการเปลี่ยนแปลง:

1. `employee_training_targets`
2. `training_policies`
3. ค่าเริ่มต้น 0 ชั่วโมง

## 2. Files Changed

- `src/db/schema.ts`
- `src/constants/thai-labels.ts`
- `src/features/training-policy/server/employee-training-target-data.ts`
- `src/features/import-employees/api/types.ts`
- `src/app/api/import-employees/route.ts`
- `src/app/api/import-employees/template/route.ts`
- `src/features/import-employees/components/employee-import-page.tsx`
- `src/features/audit-logs/server/audit-service.ts`
- `src/features/audit-logs/server/audit-log-data.ts`
- `src/features/overview/server/overview-data.ts`
- `src/features/reports/api/types.ts`
- `src/features/reports/server/report-data.ts`
- `src/features/reports/components/reports-page-content.tsx`

## 3. Database Changes

เพิ่มตาราง `employee_training_targets`

- `id`
- `organization_id`
- `user_id`
- `year`
- `total_hours`
- `k_hours`
- `s_hours`
- `a_hours`
- `created_by`
- `updated_by`
- `created_at`
- `updated_at`

Unique constraint:

- `organization_id + user_id + year`

เหตุผลที่ใช้ `user_id`:

- ระบบ runtime ปัจจุบันใช้ `users` เป็น source of truth
- dashboard, reports, training records อ้างอิง `training_records.user_id`

## 4. Excel Template Changes

เพิ่มคอลัมน์ท้าย template:

- `ชั่วโมงรวม`
- `ชั่วโมง K`
- `ชั่วโมง S`
- `ชั่วโมง A`

Template download ตัวอย่างแถวข้อมูลถูกอัปเดตให้มีคอลัมน์ใหม่ครบ

## 5. Validation Rules

กติกา validation ที่เพิ่ม:

- ถ้าไม่กรอกคอลัมน์ target ทั้ง 4 ช่อง จะ import พนักงานตามปกติ
- ถ้ากรอก target อย่างน้อย 1 ช่อง ต้องกรอกให้ครบทั้ง 4 ช่อง
- ต้องเป็นตัวเลข
- ต้องมากกว่าหรือเท่ากับ 0
- `ชั่วโมงรวม` ต้องมากกว่า 0
- `K + S + A` ต้องเท่ากับ `ชั่วโมงรวม`
- ปีที่ใช้บันทึก target จะใช้ปีปัจจุบัน หรือปีที่ส่งมาจาก form ถ้ามี
- ถ้าส่งปีแบบ พ.ศ. ระบบจะแปลงเป็น ค.ศ. ก่อนจัดเก็บ

ข้อความ error หลักที่รองรับ:

- `กรุณาระบุชั่วโมงรวม`
- `กรุณาระบุชั่วโมง K`
- `กรุณาระบุชั่วโมง S`
- `กรุณาระบุชั่วโมง A`
- `ชั่วโมงต้องเป็นตัวเลข`
- `ชั่วโมงต้องเป็นตัวเลขที่มากกว่าหรือเท่ากับ 0`
- `ชั่วโมงรวมต้องมากกว่า 0`
- `ผลรวมของชั่วโมง K/S/A ต้องเท่ากับชั่วโมงรวม`

## 6. Import Behavior

ต่อ 1 แถวที่ผ่าน validation:

1. upsert `users` และ `memberships` ตาม behavior เดิม
2. ถ้ามี target รายบุคคล จะ upsert `employee_training_targets`
3. ถ้าไม่มี target รายบุคคล ระบบจะถือว่าแถวนั้นใช้ fallback จาก `Training Policy`

Import summary ที่เพิ่ม:

- จำนวนเป้าหมาย K/S/A ที่นำเข้า
- จำนวนรายการที่ใช้ `Training Policy`

## 7. Dashboard Impact

Employee dashboard:

- ใช้ target รายบุคคลก่อน
- ถ้าไม่พบ target รายบุคคล จะ fallback ไป `Training Policy`
- K/S/A progress และ completion cards จะอิง target ที่ resolve แล้ว

HRD dashboard:

- การคำนวณ `ผ่านเป้าหมาย` และ `ยังไม่ผ่านเป้าหมาย` เปลี่ยนเป็นใช้ target รายคน
- ถ้าไม่พบ target รายคน จะ fallback ไป `Training Policy`

## 8. Reports Impact

Training Matrix:

- เพิ่มข้อมูล `approvedHours`
- เพิ่มข้อมูล `targetHours`
- เพิ่ม `targetSource`
- เพิ่ม `targetStatus`

รายงานหน้า UI จะแสดง:

- ชั่วโมงอนุมัติ
- เป้าหมายชั่วโมง
- แหล่งที่มาของเป้าหมาย
- สถานะผ่าน/ยังไม่ผ่านเป้าหมาย

## 9. Audit Events

เพิ่ม audit actions:

- `EMPLOYEE_TARGET_CREATE`
- `EMPLOYEE_TARGET_UPDATE`

ข้อมูลที่บันทึก:

- `employeeCode`
- `year`
- ค่า target เดิม
- ค่า target ใหม่

## 10. Permission Rules

- ใช้ `requireHRD()` เหมือนเดิม
- เฉพาะ HRD/Admin ที่เข้าถึง import route ได้
- พนักงานไม่มี route สำหรับแก้ target รายบุคคลโดยตรง

## 11. Manual Test Checklist

- [ ] Download template includes K/S/A target columns.
- [ ] Import employee without K/S/A target works.
- [ ] Import employee with valid target works.
- [ ] Import creates employee-specific target.
- [ ] Re-import updates existing employee target.
- [ ] Import blocks missing partial target fields.
- [ ] Import blocks non-numeric target fields.
- [ ] Import blocks K+S+A not equal total.
- [ ] Import summary shows target counts.
- [ ] Employee dashboard uses employee target.
- [ ] Employee dashboard falls back to Training Policy when no target exists.
- [ ] HRD dashboard pass/fail uses employee target.
- [ ] Training Matrix uses employee target.
- [ ] Audit log records target create/update.
- [ ] Employee cannot edit target directly.
- [ ] Mobile import page remains responsive.

## 12. Known Limitations

- Import UI ปัจจุบันยังไม่มี year picker แยก จึงใช้ปีปัจจุบันเป็นค่า default
- Export header ของรายงานยังควรทดสอบกับข้อมูลจริงอีกครั้งหลัง migrate/seed
- การ import ต่อแถวไม่ได้ห่อ transaction แยกทั้งแถว จึงเป็น partial success ได้ตาม behavior เดิมของระบบ