# Sprint 6.12 Employee Ownership Final Migration Review

## 1. Summary

Sprint 6.12 completes the remaining runtime migration from user-owned training data to employee-owned training data in the main HRD paths.

Primary outcomes:

- Employee Directory now reads employee master data from `employees`.
- Dashboard overview aggregates training ownership from `training_records.employee_id`.
- Reports aggregate from `employees` and `training_records.employee_id`.
- Employee target resolution prefers `employee_training_targets.employee_id` and falls back to policy.
- Compatibility paths for login and legacy references remain intact.

## 2. Files Changed

Schema and migration:

- `src/db/schema.ts`
- `drizzle/0010_romantic_marauders.sql`
- `drizzle/meta/0010_snapshot.json`
- `drizzle/meta/_journal.json`

Employee identity and import:

- `src/features/employees/server/employee-identity-linking.ts`
- `src/features/employees/server/employee-data.ts`
- `src/app/api/import-employees/route.ts`
- `src/app/api/employees/route.ts`

Training records and ownership:

- `src/features/training-records/api/types.ts`
- `src/features/training-records/api/service.ts`
- `src/features/training-records/schemas/training-record.ts`
- `src/features/training-records/components/training-record-form.tsx`
- `src/features/training-records/components/training-record-view-page.tsx`
- `src/features/training-records/server/training-record-data.ts`
- `src/app/api/training-records/route.ts`
- `src/app/api/training-records/[id]/route.ts`
- `src/app/api/training-records/[id]/review/route.ts`
- `src/app/dashboard/training-records/[trainingRecordId]/page.tsx`

Employee directory:

- `src/features/employee-directory/server/employee-directory-data.ts`
- `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-action-menu.tsx`
- `src/features/employee-directory/components/employee-directory-detail-page.tsx`

Overview and reports:

- `src/features/overview/server/overview-data.ts`
- `src/features/reports/server/report-data.ts`
- `src/features/reports/api/types.ts`
- `src/features/training-matrix/server/training-matrix-data.ts`
- `src/features/training-matrix/api/types.ts`

Training target resolution:

- `src/features/training-policy/server/employee-training-target-data.ts`

## 3. Employee Directory Data Source Validation

Implemented:

- List page now fetches from `employeesQueryOptions(...)`, not `usersQueryOptions(...)`.
- Table row shape now uses `Employee` contracts from the employee module.
- Row action routes now use `employeeId`.
- Detail page already resolves primary data from `employees`.
- Training summary in detail page uses `training_records.employee_id = employees.id`.

Validated behavior:

- Imported employees without linked user accounts remain visible in Employee Directory.
- Department and position display come from employee relations.
- Employee code and display fields come from employee-owned data, not auth-owned user data.

## 4. Overview Migration

Updated `src/features/overview/server/overview-data.ts` to:

- resolve self scope from `user_employee_maps` through `getEmployeeIdsForUser(...)`
- resolve the primary self employee through `getPrimaryEmployeeIdForUser(...)`
- use `employees` as the employee source for admin dashboards
- use `training_records.employee_id` for all yearly aggregates
- use employee-owned target resolution through `getResolvedTrainingTargetForEmployee(...)`
- use employee-owned target maps through `getResolvedTrainingTargetsForEmployees(...)`

Result:

- employee cards now represent the mapped employee record
- HRD cards, charts, rankings, and pending counts now use employee ownership consistently

## 5. Reports Migration

Updated `src/features/reports/server/report-data.ts` to:

- scope employees through `employees` instead of membership/user joins
- aggregate transcript rows from `employees + training_records.employee_id`
- count department employees from `employees`
- aggregate annual summary from employee-owned training records
- calculate training matrix from `employees`, `training_matrices`, and `training_records.employee_id`
- keep PDF and Excel export behavior working on the migrated datasets

Also updated report API types so report row ids now use employee ids as numbers.

## 6. Target Resolution Changes

Current target priority:

1. `employee_training_targets.employee_id`
2. `training_policies`
3. default zero-value fallback if no policy exists

Compatibility retained:

- user-based target resolution still exists only for legacy callers and fallback compatibility
- new migrated paths call employee-first target resolvers

## 7. Remaining Legacy Dependencies

Still required now:

- `training_records.user_id`
  - retained for compatibility, notifications, and staged migration safety
- `employee_training_targets.user_id`
  - retained for compatibility with legacy target readers/import history
- `users.employee_id`
  - retained as fallback when no `user_employee_maps` row exists
- `users.employee_code`
  - retained for compatibility and historical link recovery

Can be migrated later:

- legacy user-based target resolver branches in `employee-training-target-data.ts`
- compatibility updates in `employee-identity-linking.ts` that still backfill `trainingRecords.userId` and `employeeTrainingTargets.userId`
- user-centric fields in the users feature that still surface employee identity for admin maintenance

Safe candidates for future cleanup after validation period:

- direct runtime reads that rely on `training_records.user_id` for ownership semantics
- fallback reads from `users.employee_id` once all active accounts have `user_employee_maps`
- fallback reads from `users.employee_code` once mapping stability is confirmed

## 8. Regression Checklist

Code-level verification completed:

- `npx tsc --noEmit`

Expected runtime validation checklist:

- Employee login
- Employee dashboard
- HRD dashboard
- Employee Directory list
- Employee Directory detail
- Employee imported without user appears in Employee Directory
- Employee transcript
- Department summary
- Annual summary
- Training matrix
- Training record create/edit
- HRD review
- Employee import
- Employee target import

## 9. Risks

- Existing databases require the new migration before the new ownership fields and map table are fully available.
- Some compatibility code still writes both employee-owned and user-owned references; that is intentional for this sprint, but it increases temporary complexity.
- If older rows lack employee linkage, self-scoped dashboards and reports will return empty data until mapping is backfilled.

## 10. Recommendation Before Sprint 7.2

- Run the new Drizzle migration in every active environment.
- Backfill and verify `user_employee_maps` coverage for all active employee users.
- Run UAT on dashboard, directory, reports, training record create/review, and import flows using real migrated data.
- Keep legacy user-owned columns for one more validation cycle, then schedule a dedicated cleanup sprint.

## Migration Commands

Run the pending migration:

```bash
npm run migrate
```

Optional validation:

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