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

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:

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.