commit

docs/sprint-4-training-policy-course-master-review.md

@@ -0,0 +1,147 @@
+# Sprint 4 Review: Training Policy and Course Master
+
+## 1. Summary of changes
+
+- Implemented the HRD-only Training Policy module at `/dashboard/training-policy`.
+- Added yearly training policy create/update flow with Zod validation.
+- Enforced `kHours + sHours + aHours === totalHours`.
+- Added active policy handling so the active record drives dashboard targets.
+- Updated dashboard summary cards to use Training Policy values.
+- Enhanced Course Master to support:
+  - `courseCode`
+  - `courseName` via existing `name`
+  - `description`
+  - `defaultCategory` via existing `category`
+  - `defaultHours` via existing `standardHours`
+  - `provider` via existing `organizer`
+  - `status` via existing `isActive`
+  - `mandatory` via existing `isRequired`
+  - `certificateRequired`
+  - `validityMonths` via existing `certificateValidityMonths`
+  - `trainingCost`
+- Added loading, empty, success, and error states for Sprint 4 pages.
+
+## 2. Files changed
+
+### Training Policy
+
+- `src/app/api/training-policies/route.ts`
+- `src/app/api/training-policies/[id]/route.ts`
+- `src/app/dashboard/training-policy/page.tsx`
+- `src/app/dashboard/training-policy/loading.tsx`
+- `src/app/dashboard/training-policy/error.tsx`
+- `src/features/training-policy/api/types.ts`
+- `src/features/training-policy/api/service.ts`
+- `src/features/training-policy/api/queries.ts`
+- `src/features/training-policy/api/mutations.ts`
+- `src/features/training-policy/components/training-policy-page.tsx`
+- `src/features/training-policy/components/training-policy-form.tsx`
+- `src/features/training-policy/constants/training-policy-defaults.ts`
+- `src/features/training-policy/schemas/training-policy.ts`
+- `src/features/training-policy/server/training-policy-data.ts`
+
+### Course Master
+
+- `src/app/api/courses/route.ts`
+- `src/app/api/courses/[id]/route.ts`
+- `src/app/dashboard/courses/loading.tsx`
+- `src/app/dashboard/courses/error.tsx`
+- `src/app/dashboard/courses/[courseId]/loading.tsx`
+- `src/app/dashboard/courses/[courseId]/error.tsx`
+- `src/features/courses/api/types.ts`
+- `src/features/courses/components/course-form.tsx`
+- `src/features/courses/components/course-tables/columns.tsx`
+- `src/features/courses/components/course-tables/index.tsx`
+- `src/features/courses/components/course-tables/options.tsx`
+- `src/features/courses/constants/course-options.ts`
+- `src/features/courses/schemas/course.ts`
+- `src/features/courses/server/course-data.ts`
+
+### Dashboard usage
+
+- `src/features/overview/server/overview-data.ts`
+
+## 3. Database changes
+
+- No new schema changes were required.
+- Sprint 4 reused the existing `training_policies` table.
+- Sprint 4 reused existing `courses` columns:
+  - `course_code`
+  - `category`
+  - `standard_hours`
+  - `organizer`
+  - `is_required`
+  - `certificate_required`
+  - `certificate_validity_months`
+  - `training_cost`
+
+## 4. Migration commands
+
+- No new migration is required for this sprint.
+- If your database has not yet applied the current schema in the repository, run:
+
+```bash
+npm run migrate
+```
+
+## 5. New routes
+
+- `GET /api/training-policies`
+- `POST /api/training-policies`
+- `PATCH /api/training-policies/[id]`
+- `/dashboard/training-policy`
+
+## 6. Validation rules
+
+### Training Policy
+
+- `year` is required
+- `totalHours` is required and must be greater than `0`
+- `kHours` is required and must be `>= 0`
+- `sHours` is required and must be `>= 0`
+- `aHours` is required and must be `>= 0`
+- `kHours + sHours + aHours` must equal `totalHours`
+- `year` must be unique per organization
+
+### Course Master
+
+- `courseName` maps to `name` and must be at least 2 characters
+- `defaultCategory` maps to `category` and is required
+- `defaultHours` maps to `standardHours` and must be `>= 0`
+- `validityMonths` maps to `certificateValidityMonths` and must be an integer `>= 0`
+- `trainingCost` must be `>= 0` when provided
+- `courseCode` is optional and limited to 50 characters
+
+## 7. Permission rules
+
+- Training Policy page and APIs require HRD access through existing Auth.js session helpers.
+- Employee users cannot access `/dashboard/training-policy`.
+- Course Master remains HRD-only through the existing route and API guards.
+- Dashboard policy usage respects the user's existing organization/session scope.
+
+## 8. Manual test checklist
+
+- [ ] HRD can open Training Policy page.
+- [ ] Employee cannot open Training Policy page.
+- [ ] HRD can create policy.
+- [ ] HRD can edit policy.
+- [ ] System blocks invalid K/S/A sum.
+- [ ] Dashboard uses policy values.
+- [ ] HRD can create course.
+- [ ] HRD can edit course.
+- [ ] Course Master supports `certificateRequired`.
+- [ ] Course Master supports `trainingCost`.
+
+## 9. Known limitations
+
+- Course category input is now aligned to `K/S/A`, but legacy category values are still preserved for existing rows.
+- Training Policy currently supports create and update only; delete/archive flow is not part of Sprint 4.
+- Dashboard summary cards use the active policy, or the shared default example if no policy row exists yet.
+
+## 10. Next recommended sprint
+
+- Add audit logging for Training Policy changes.
+- Add a dedicated policy history detail or archive flow.
+- Expand dashboard policy reporting to show K/S/A completion progress, not only total-hour target progress.
+- Add course import/export support if HRD master-data volume is expected to grow.
+