alla-tms/plans/change-import-employee-ksa-targets.md

You are a Senior Full Stack Engineer.

Project: Training Management System (TMS)

Current task: Enhance Employee Import to support employee-specific K/S/A training hour targets.

Requirement: When HRD imports employees, the Excel template must support importing individual training hour targets per employee.

Target fields:

• ชั่วโมงรวม
• ชั่วโมง K
• ชั่วโมง S
• ชั่วโมง A

Important constraints:

• Do NOT remove existing employee import functionality.
• Do NOT break existing employee import template.
• Do NOT change folder structure.
• Keep Thai UI.
• Keep responsive/mobile behavior.
• Minimal-impact changes only.
• Use Drizzle ORM.
• Use existing Auth.js authorization.

Business rule: Training Policy remains the default organization-wide target. Employee-specific target overrides Training Policy for that employee and year.

Priority:

1. Employee-specific target
2. Training Policy default

Example: Training Policy 2569:

• Total = 30
• K = 12
• S = 12
• A = 6

Employee AC2026 imported with:

• Total = 60
• K = 24
• S = 24
• A = 12

Dashboard and reports for AC2026 must use:

• Total = 60
• K = 24
• S = 24
• A = 12

Part 1: Database

Add new table if not existing:

employee_training_targets

Fields:

• id
• organizationId
• employeeId or userId
• year
• totalHours
• kHours
• sHours
• aHours
• createdBy
• updatedBy
• createdAt
• updatedAt

Recommended unique constraint:

• organizationId + employeeId/userId + year

Important: Use whichever identifier is currently stable in the system:

• employeeId if employee table is the source of truth
• userId if users table stores employeeCode and is used by dashboard/report

Do not duplicate targets for the same employee/year. If importing again:

• update existing target

Part 2: Excel Template

Update employee import template headers.

Existing headers:

• รหัสพนักงาน
• ชื่อพนักงาน
• อีเมล
• บริษัท
• แผนก
• ตำแหน่ง
• สถานะ

Add:

• ชั่วโมงรวม
• ชั่วโมง K
• ชั่วโมง S
• ชั่วโมง A

Final headers:

• รหัสพนักงาน
• ชื่อพนักงาน
• อีเมล
• บริษัท
• แผนก
• ตำแหน่ง
• สถานะ
• ชั่วโมงรวม
• ชั่วโมง K
• ชั่วโมง S
• ชั่วโมง A

Part 3: Import Validation

Validation rules:

1. Existing employee fields remain unchanged.

2. K/S/A target fields are optional.

3. If all target fields are empty:

• import employee normally
• do not create employee-specific target
• dashboard/report fallback to Training Policy

4. If any target field is filled:

• all 4 fields are required:
  • ชั่วโมงรวม
  • ชั่วโมง K
  • ชั่วโมง S
  • ชั่วโมง A

5. Values must be numeric.

6. Values must be >= 0.

7. ชั่วโมงรวม must be > 0.

8. ชั่วโมง K + ชั่วโมง S + ชั่วโมง A must equal ชั่วโมงรวม.

9. Year:

• use current selected/import year if import UI has year filter
• otherwise use current year
• for Thai year 2569 store as Gregorian 2026 if existing app uses Gregorian year

Thai error messages:

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

Part 4: Import Behavior

For each valid row:

1. Upsert employee/user as existing behavior.

2. If K/S/A target fields are provided:

• upsert employee_training_targets by employee/year
• update target values if already exists

3. Import result summary must include:

• จำนวนพนักงานที่นำเข้า
• จำนวนเป้าหมาย K/S/A ที่นำเข้า
• จำนวนรายการที่ใช้ค่า Training Policy เริ่มต้น
• จำนวนรายการผิดพลาด

Part 5: Employee Import Page UI

Update right-side supported template card to show:

• รหัสพนักงาน
• ชื่อพนักงาน
• อีเมล
• บริษัท
• แผนก
• ตำแหน่ง
• สถานะ
• ชั่วโมงรวม
• ชั่วโมง K
• ชั่วโมง S
• ชั่วโมง A

Add helper text:

• หากไม่ระบุชั่วโมง K/S/A ระบบจะใช้ค่าเริ่มต้นจาก Training Policy

Part 6: Dashboard Impact

Update dashboard target resolution:

For employee dashboard:

1. Check employee_training_targets for employee/year.
2. If found, use employee-specific target.
3. If not found, use Training Policy.

For HRD dashboard:

• Passed / Not Passed calculation should use each employee's individual target when available.
• Otherwise fallback to Training Policy.

Part 7: Reports Impact

Update reports if target is shown or used:

• Training Matrix
• Employee Transcript
• Department Summary if it uses target pass/fail
• Annual Summary if it uses target pass/fail

Rule: Use employee-specific target first, fallback to policy.

Part 8: Permissions

Only HRD/Admin can import targets.

Employee:

• cannot modify target
• can only see calculated progress based on assigned target

Part 9: Audit Log

Add audit event when target is created/updated during import.

Events:

• EMPLOYEE_TARGET_CREATE
• EMPLOYEE_TARGET_UPDATE

Include:

• employeeCode
• year
• old target
• new target

Part 10: Output Review File

Create:

docs/management-change-import-employee-ksa-targets-review.md

Include:

1. Summary
2. Files Changed
3. Database Changes
4. Excel Template Changes
5. Validation Rules
6. Import Behavior
7. Dashboard Impact
8. Reports Impact
9. Audit Events
10. Permission Rules
11. Manual Test Checklist
12. Known Limitations

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.

Return:

• Complete code changes with file paths.
• Migration command if required.
• Content of docs/management-change-import-employee-ksa-targets-review.md.