FAC-113 feat: scoped program filters for analytics attention endpoint

[ayacoders]

Summary

The frontend dean dashboard now includes a Faculty Requiring Attention section powered by:

• GET /api/v1/analytics/attention

We also want the dashboard to support filtering by:

• semester
• program

At the moment, overview already supports programCode, but attention does not, so the dashboard cannot be filtered consistently by program.

Role scope rules

Expected access model:

Dean

• scoped to their department(s) for the selected semester
• can view all programs inside those departments

Example:

• specific campus
• specific department
• all programs under that department (BSCS, BSIT, etc.)

Chairperson

• still within the parent department context
• but limited to one or more assigned programs only

Example:

• same department as dean scope
• only assigned programs such as BSCS
• or multiple programs if assigned

Requested backend changes

1. Add scoped analytics programs endpoint

Proposed route:

• GET /api/v1/analytics/programs

Query params:

• semesterId required

Auth:

• DEAN
• CHAIRPERSON
• SUPER_ADMIN

Response:

Array<{
  id: string;
  code: string;
  name: string | null;
}>

Expected behavior:

• DEAN: return all programs inside the dean's scoped department(s) for the selected semester
• CHAIRPERSON: return only assigned/in-scope programs for the selected semester
• SUPER_ADMIN: unrestricted list is acceptable

2. Extend attention endpoint to support program filter

Existing route:

• GET /api/v1/analytics/attention

Add optional query param:

• programCode?: string

Expected behavior:

• when programCode is provided, return only attention items for that program
• still enforce caller scope
• if the requested program is outside caller scope, either return empty results or reject with 403

Either is acceptable as long as behavior is intentional and documented.

Why this is needed

Frontend wants a consistent dean/chairperson dashboard filter model:

• Semester
• Program

Current state:

• GET /analytics/overview supports semesterId + programCode
• GET /analytics/attention supports only semesterId

Because of that mismatch, the dashboard cannot safely expose a real program filter yet without creating inconsistent sections.

Frontend dependency

Frontend is waiting on:

1. scoped program options endpoint
2. programCode support on GET /analytics/attention

Once available, frontend will wire the dashboard filter so both:

• overview metrics/chart
• faculty requiring attention

follow the same selected semester and program.

Notes

This should be reusable for both:

• dean dashboard
• future chairperson dashboard

[y4nder]

Implementation Summary — PR #269

Addressed all requested backend changes:

1. Scoped program options

Reused the existing GET /curriculum/programs endpoint instead of creating a new GET /analytics/programs. Fixed chairperson scoping — chairpersons now see only their assigned programs (was returning all programs in the department). Deans and super admins are unaffected.

2. programCode support on attention endpoint

Added optional programCode query param to GET /analytics/attention. All 3 attention sub-queries (declining trends, quant-qual gap, low coverage) are filtered. For declining trends, a join-back to mv_faculty_semester_stats is used since mv_faculty_trends lacks a program column.

3. Scope validation

Added programCode scope validation on both GET /analytics/overview and GET /analytics/attention. Out-of-scope program codes return empty results (silent filter, consistent with existing overview behavior).

Other

• Added ResolveProgramCodes() to ScopeResolverService (extracted shared resolveChairpersonPrograms() helper)
• Hardened DTO validation: @IsNotEmpty(), @MaxLength(20), @Transform(trim)
• 103 unit tests passing (13 new)