176 lines
7.4 KiB
Markdown
176 lines
7.4 KiB
Markdown
# 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 เดิมของระบบ
|