alla-tms/plans/identity-employee-master-refactor.md

You are a Senior Full Stack Engineer and Solution Architect.

Project: Training Management System (TMS)

Current task: Refactor Identity/User and Employee Master architecture.

Business decision: Separate user login accounts from employee master data.

Concept:

1. "พนักงาน" menu:

   • Manage user login accounts
   • Role
   • Provider
   • Keycloak mapping
   • User access

2. "รายชื่อพนักงานทั้งหมด" menu:

   • View employee master data
   • Training hours
   • K/S/A targets
   • Training history

Important constraints:

• Do NOT break existing login.
• Do NOT remove existing users table.
• Do NOT remove existing training records.
• Use migration safely.
• Use Drizzle ORM.
• Keep Thai UI.
• Keep responsive/mobile behavior.
• Implement in small safe steps.

Architecture requirement:

1. Users table should represent login identity only.

Users should store:

• id
• organizationId
• email
• username
• employeeCode
• employeeId nullable
• provider
• providerUserId
• role
• status
• lastLoginAt
• createdAt
• updatedAt

2. Employees table should represent HR employee master.

Employees should store:

• id
• organizationId
• employeeCode
• prefix
• firstNameTh
• lastNameTh
• firstNameEn
• lastNameEn
• displayName
• email
• phone
• companyName or companyId
• departmentId
• positionId
• status
• hiredAt
• createdAt
• updatedAt

3. Auto map user with employee.

Mapping logic:

• Keycloak sends attribute: empcode
• System maps: empcode -> employees.employeeCode
• If found: users.employeeId = employees.id users.employeeCode = employees.employeeCode
• If not found: login can be blocked or user can be created without employee link based on config. For MVP, create user but mark employeeId = null and show "ยังไม่เชื่อมโยงข้อมูลพนักงาน".

4. Employee Import:

• Import employees into employees table.
• Do not create user login account automatically unless explicitly configured.
• If imported employeeCode matches existing users.employeeCode: auto-link users.employeeId.

5. Training Records:

• Prefer employeeId as owner of training record.
• Keep userId only as submittedBy if existing.
• New records should save: employeeId submittedByUserId

6. Employee-specific targets:

• Link to employeeId.

7. Reports and Dashboard:

• Use employees as master source.
• Use training_records.employeeId for aggregation.
• Use user only for authentication/session.

8. Sidebar: Under "ข้อมูลหลัก":

• พนักงาน Purpose: User Login Management
• รายชื่อพนักงานทั้งหมด Purpose: Employee Directory + Training Summary
• หลักสูตร
• นโยบาย
• ประกาศ

9. Permissions: HRD/Admin:

• can view employee directory
• can manage user accounts if allowed

Employee:

• cannot view employee directory
• can view own dashboard/training history

10. Output Review File: Create: docs/identity-employee-separation-review.md

Include:

1. Summary
2. Architecture Changes
3. Database Changes
4. Migration Strategy
5. User Login Behavior
6. Keycloak Mapping Behavior
7. Employee Import Behavior
8. Training Record Impact
9. Dashboard Impact
10. Reports Impact
11. Permission Rules
12. Manual Test Checklist
13. Rollback Plan
14. Known Limitations

Return:

• Complete code changes with file paths
• Migration commands
• Review file
• Remaining risks