# 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:

```bash
npx tsc --noEmit
```

## Migration Commands

No new database migration is required for this UI enhancement.