alla-tms/plans/add-year-filter-training-history-page.md

You are a Senior Full Stack Engineer working on this Next.js 16 Training System project.

Task: In the Admin/HRD Training History page, add a Year filter.

Before editing code, inspect and follow:

1. AGENTS.md
2. docs/AI_DEVELOPMENT_GUIDE.md
3. docs/PROJECT_ARCHITECTURE.md

Scope: Only modify the Admin/HRD Training History page and related query/filter logic if necessary.

Requirements:

1. Find the Admin/HRD Training History page.
2. Add a Year filter to the existing filter area.
3. The Year filter should allow HRD/Admin to filter training records by training year.
4. Default selected year should be the current year.
5. Year should be based on the training date, not created_at.
6. Preserve existing filters, table layout, pagination, sorting, and UI style.
7. Use existing project components such as Select, Button, DataTable, filter hooks, nuqs, TanStack Query, or existing patterns if already used.
8. Do not introduce a new UI pattern if an existing filter pattern exists.
9. Ensure the year filter works with server-side fetching if the current page uses server-side query params.
10. Ensure the filter persists in the URL if the page already uses URL search params.
11. Include an “All years” option if the existing filter design supports all/empty values.
12. Do not change employee-facing pages unless shared logic requires it.
13. Do not use any.
14. Ensure TypeScript and ESLint pass.

Implementation expectations:

• Add year filter state/search param.
• Pass year to the API/query options.
• Update API/service/database query to filter by YEAR(training_date) or the equivalent date range.
• Prefer date range filtering for performance: training_date >= startOfYear training_date < startOfNextYear
• Keep existing role permissions unchanged.

After implementation: Create /docs/ai/report.md with:

• Summary
• Files changed
• Root cause / reason for change
• Changes made
• Testing checklist
• Risks
• Rollback plan

Testing checklist must include:

• Default current year shows records correctly
• Selecting another year updates table data
• All years shows all records if supported
• Existing filters still work together with year
• Pagination still works
• Sorting still works
• HRD/Admin permissions unchanged
• TypeScript passes
• ESLint passes

Return a concise summary after completing the changes.