40227-vm/backend/docs/staff-attendance.md

Staff Attendance Backend

Purpose

staff_attendance_records stores staff-level attendance entries per organization. This slice is a read-only reporting surface: it exposes a filtered record list and an aggregated summary used by the attendance snapshot and the director dashboard. It does not write, import, or generate records.

This is distinct from the student-level attendance models (attendance_sessions, attendance_records) and from campus daily aggregates (campus_attendance_summaries).

Slice Files (by layer)

• Route: src/routes/staff_attendance.ts (thin wiring; GET /records, GET /summary).
• Controller: src/api/controllers/staff_attendance.controller.ts (custom — not the CRUD factory).
• Service (BLL): src/services/staff_attendance.ts.
• Repository (DAL): queries run through db.staff_attendance_records and db.staff inside the service (no separate db/api/staff_attendance.ts).
• Model: src/db/models/staff_attendance_records.ts.
• Shared used: services/shared/access.ts (assertAuthenticatedTenantUser, requireOrganizationId, requireUserId, hasRoleAccess, campusScope), services/shared/validate.ts (clampLimit, optionalIsoDate), shared/constants/staff-attendance.ts (STAFF_ATTENDANCE_STATUSES, STAFF_ATTENDANCE_REPORT_ROLE_NAMES, STAFF_ATTENDANCE_TENANT_WIDE_ROLE_NAMES, STAFF_ATTENDANCE_DEFAULT_LIMIT, STAFF_ATTENDANCE_MAX_LIMIT), shared/constants/staff.ts (STAFF_STATUSES).

API

The slice is mounted at /api/staff_attendance; all routes require JWT authentication (the mount in src/index.ts applies the jwt passport guard).

• GET /api/staff_attendance/records -> 200 { rows, count }. Query parameters (all optional): startDate and endDate (ISO YYYY-MM-DD, validated via optionalIsoDate), and limit (positive integer, defaulting to STAFF_ATTENDANCE_DEFAULT_LIMIT = 90 and capped at STAFF_ATTENDANCE_MAX_LIMIT = 366 via clampLimit). Each row is the record DTO below. Rows are ordered by attendance_date descending, then user_name ascending.
• GET /api/staff_attendance/summary -> 200 { staffCount, recordsCount, present, late, absent }. Accepts the same startDate, endDate, and limit query parameters; limit is read from the filter type but the summary counts are computed with SQL COUNT aggregates, not by limiting rows.

Invalid startDate/endDate (non-ISO) or a non-positive / non-integer limit raises ValidationError.

Access Rules

Enforced by visibilityScope in the service:

• A user who does NOT hold a report role (STAFF_ATTENDANCE_REPORT_ROLE_NAMES) sees only their own records, scoped by userId (requireUserId).
• A user who holds a report role sees campus-scoped records via campusScope: tenant-wide roles (STAFF_ATTENDANCE_TENANT_WIDE_ROLE_NAMES) or users with globalAccess see all organization records; other report-role users are restricted to their own campus (campusId from their staff profile, else unrestricted if no campus resolves).
• STAFF_ATTENDANCE_REPORT_ROLE_NAMES = the generated roles Super Administrator, Administrator, Platform Owner, Tenant Director, Campus Manager.
• STAFF_ATTENDANCE_TENANT_WIDE_ROLE_NAMES = Super Administrator, Administrator, Platform Owner.
• globalAccess on the user's app role grants access in any role check (hasRoleAccess).

Both endpoints call assertAuthenticatedTenantUser first; a request without an authenticated user or resolvable organization raises ForbiddenError.

Tenant Scope

• Every query is bound to the current user's organization (requireOrganizationId).
• Within the organization, visibility is narrowed to the user, their campus, or the whole tenant per the access rules above. The summary's staffCount query applies the same campusScope over the staff table (active staff only).

Data Contract

Record DTO returned by GET /records (toRecordDto): id, date (from attendance_date), status, note, user_name, user_role, organizationId, campusId, userId, createdAt, updatedAt.

Summary DTO returned by GET /summary: staffCount (active staff in scope, from the staff table filtered by STAFF_STATUSES.ACTIVE), recordsCount (= present + late + absent), present, late, absent.

Model staff_attendance_records fields: id (UUID PK), attendance_date (DATEONLY, not null), status (ENUM of STAFF_ATTENDANCE_STATUSES — present, late, absent; not null), note (TEXT, nullable), user_name (TEXT, not null), user_role (TEXT, nullable), importHash (unique, nullable), organizationId (UUID, not null), campusId (UUID, nullable), userId (UUID, not null), createdById (UUID, not null), updatedById (UUID, nullable), plus createdAt/updatedAt/deletedAt. The model is paranoid (soft delete) with freezeTableName. Associations (belongsTo): organization, campus, user, createdBy, updatedBy.

Behavior / Notes

• The summary aggregates each status with separate SQL COUNT queries (run concurrently with the active-staff count via Promise.all) rather than fetching and counting rows in JS, so totals are not truncated by limit.
• dateFilter builds an attendance_date range using Op.gte / Op.lte only for the provided bound(s); with neither bound it adds no date condition.
• The list limit defaults and caps come from the staff-attendance constants, not the shared pagination helper.

Tests

None yet (no staff_attendance unit/e2e test in src/).

Related

• Frontend: frontend/docs/staff-attendance-integration.md.
• Related slices: campus-attendance (campus daily aggregates), the student-level attendance_sessions / attendance_records slices, and staff (active staff count, campus resolution).