alla-tms/docs/sprint-6-12-employee-directory-ui-review.md

Sprint 6.12 Employee Directory UI Review

1. Summary

Employee Directory was redesigned into a dedicated HR Employee Master screen backed by employees as the primary source.

This update separates Employee Directory from user management and adds:

• HR-oriented page header actions
• richer employee table with training-hour summary columns
• search and filter controls for employee master data
• employee create/edit flows under Employee Directory routes
• employee-specific K/S/A target management
• improved employee detail presentation

2. Files Changed

Employee Directory pages and UI:

• src/app/dashboard/employee-directory/page.tsx
• src/app/dashboard/employee-directory/[id]/page.tsx
• src/app/dashboard/employee-directory/create/page.tsx
• src/app/dashboard/employee-directory/[id]/edit/page.tsx
• src/app/dashboard/employee-directory/[id]/targets/page.tsx
• src/features/employee-directory/components/employee-directory-listing.tsx
• src/features/employee-directory/components/employee-directory-table.tsx
• src/features/employee-directory/components/employee-directory-columns.tsx
• src/features/employee-directory/components/employee-directory-toolbar.tsx
• src/features/employee-directory/components/employee-directory-action-menu.tsx
• src/features/employee-directory/components/employee-directory-detail-page.tsx
• src/features/employee-directory/components/employee-target-form.tsx

Employee Directory API/data layer:

• src/app/api/employee-directory/route.ts
• src/app/api/employee-directory/[id]/target/route.ts
• src/features/employee-directory/api/types.ts
• src/features/employee-directory/api/service.ts
• src/features/employee-directory/api/queries.ts
• src/features/employee-directory/api/mutations.ts
• src/features/employee-directory/server/employee-directory-data.ts

Employee CRUD support reused by directory:

• src/app/api/employees/route.ts
• src/app/api/employees/[id]/route.ts
• src/features/employees/server/employee-data.ts
• src/features/employees/components/employee-form.tsx

Shared search params:

• src/lib/searchparams.ts

3. UI Improvements

• Added page-level primary action: สร้างรายชื่อพนักงาน
• Added page-level secondary action: Import รายชื่อพนักงาน
• Reworked table columns into an HR-focused layout:
  • รหัสพนักงาน
  • ชื่อพนักงาน
  • ฝ่าย
  • ตำแหน่ง
  • grouped training-hour columns
  • action menu
• Added responsive search + filter toolbar
• Expanded action menu:
  • ดูข้อมูลพนักงาน
  • แก้ไขข้อมูลพนักงาน
  • กำหนดเป้าหมาย K/S/A
• Improved detail page with:
  • employee identity summary
  • hour summary cards
  • progress bar
  • K/S/A summary cards
  • training history table

4. Data Source Validation

Primary source for Employee Directory list/detail:

• employees

Related sources:

• training_records
• employee_training_targets
• departments
• positions
• organizations

Validation notes:

• list data does not depend on users
• employees without login accounts are still returned
• detail data resolves directly from employee master records

5. Training Hour Calculation

Training-hour summary is calculated from:

• training_records.employee_id

Current logic:

• Approved Hours:
  • approval_status = approved
  • uses approved_hours, fallback to submitted hours when applicable
• Pending Hours:
  • approval_status in (pending, needs_revision)
• Rejected Hours:
  • approval_status = rejected
• Total Hours:
  • approved + pending + rejected

Employee target screen writes to:

• employee_training_targets.employee_id

6. Responsive Changes

• page header actions stack vertically on mobile and align horizontally on larger screens
• toolbar wraps cleanly on tablet
• table stays inside a horizontal scroll container
• detail page cards stack on smaller viewports
• edit/target actions on detail page wrap instead of overflowing

7. Permission Rules

Allowed:

• HRD/Admin can view employee directory
• HRD/Admin can create employee records
• HRD/Admin can edit employee records
• HRD/Admin can manage employee K/S/A targets

Blocked:

• Employee role cannot access Employee Directory by page guard

8. Manual Test Checklist

• Employee Directory reads from employees
• Employees without user account are displayed
• Search works by employee code, name, email, department, and position
• Company / department / position / status filters work
• สร้างรายชื่อพนักงาน opens the create page
• Import รายชื่อพนักงาน opens the import page
• Training hour calculation uses training_records.employee_id
• Employee detail page loads correctly
• Edit employee flow saves successfully
• K/S/A target page saves successfully
• Mobile/tablet layout does not overflow

9. Known Limitations

• Employee Directory filters currently use employee master text fields and related department/position names; there is no separate companies table yet.
• The K/S/A target editor is implemented as a dedicated page route, not an inline modal.
• Existing legacy compatibility paths in auth/training ownership were intentionally left in place from Sprint 6.12 migration work.

Validation

TypeScript verification completed:

npx tsc --noEmit

Migration Commands

No new database migration is required for this UI enhancement.