Attendance Sessions Backend

Purpose

attendance_sessions records an attendance-taking occasion (a homeroom, subject, exam, or event sitting) against a class. It is a generic-CRUD slice assembled from the shared factories; each session is the parent of the individual attendance_records entered for it.

Slice Files (by layer)

Route: src/routes/attendance_sessions.ts — createCrudRouter(controller, { permission: 'attendance_sessions' }).
Controller: src/api/controllers/attendance_sessions.controller.ts — createCrudController(service, { csvFields }).
Service (BLL): src/services/attendance_sessions.ts — createCrudService(DbApi, { notFoundCode: 'attendance_sessionsNotFound' }).
Repository (DAL): src/db/api/attendance_sessions.ts (Attendance_sessionsDBApi) — entity-specific create/bulkImport/update/findBy/findAll; remove/deleteByIds/findAllAutocomplete delegate to db/api/shared/repository.ts.
Model: src/db/models/attendance_sessions.ts.
Shared used: CRUD factories (services/shared/crud-service.ts, api/controllers/shared/crud-controller.ts, api/http/crud-router.ts), repository helpers (db/api/shared/repository.ts), shared/constants/pagination.ts (resolvePagination), db/utils.ts (Utils.uuid/Utils.ilike), shared/constants/database.ts (BULK_IMPORT_TIMESTAMP_STEP_MS).

API

The standard generic-CRUD surface (all under /api/attendance_sessions, JWT + ${METHOD}_ATTENDANCE_SESSIONS permission, all 200) — see backend-architecture.md for the shared 9-endpoint contract:

POST / — body { data }, returns true.
POST /bulk-import — multipart CSV file, returns true.
PUT /:id — body { data, id } (the service reads the id from the body), returns true.
DELETE /:id — returns true.
POST /deleteByIds — body { data: string[] }, returns true.
GET / — query filters, returns { rows, count }; ?filetype=csv streams a CSV of csvFields.
GET /count — returns { rows: [], count }.
GET /autocomplete — ?query&limit&offset, returns [{ id, label }] where label is session_type.
GET /:id — returns the record with eager associations (see Data Contract).

csvFields: id, notes, session_date.

Access Rules

JWT required; the whole router is guarded by checkCrudPermissions('attendance_sessions'), deriving READ_ATTENDANCE_SESSIONS / CREATE_ATTENDANCE_SESSIONS / UPDATE_ATTENDANCE_SESSIONS / DELETE_ATTENDANCE_SESSIONS per HTTP method.
Access is granted by role permission or per-user custom_permissions (see permissions.md).

Tenant Scope

findAll scopes where.organizationId to currentUser.organizationId; a globalAccess role clears the org filter (sees all tenants).
create assigns the organization from currentUser.organizationId; update only reassigns organization for globalAccess users (otherwise it stays the caller's org).

Data Contract

Model columns (paranoid, soft-delete via deletedAt):

id (UUID PK).
session_date — DATE.
session_type — ENUM homeroom | subject | exam | event.
notes — TEXT.
importHash (STRING(255), unique), organizationId, campusId, classId, class_subjectId, taken_byId, createdById, updatedById, timestamps (all UUID FKs nullable).

Associations: belongsTo organization, campus, class (classes, as class), class_subject (class_subjects), taken_by (staff), createdBy/updatedBy (users); hasMany attendance_records as attendance_records_attendance_session. findBy/GET /:id eager-load attendance_records_attendance_session, organization, campus, class, class_subject, and taken_by in a single Promise.all.

List filters (AttendanceSessionsFilter): id, notes (iLike), session_dateRange, session_type, campus (id or name, |-separated), class (id or name), class_subject (id or status), taken_by (id or employee_number), organization, createdAtRange, plus field/sort ordering and limit/page pagination.

Behavior / Notes

create/bulkImport/update set associations via the Sequelize set* mixins (no file relations on this entity).
bulkImport offsets createdAt per row by BULK_IMPORT_TIMESTAMP_STEP_MS to preserve order.
List pagination uses the shared resolvePagination defaults (page size 10, capped at 100).
Note: AttendanceSessionsFilter accepts an active flag the model has no column for; it is applied to where.active but, with no such column, is currently inert (kept for source accuracy).

Tests

None yet.

Generic-CRUD contract: backend-architecture.md; related slices: attendance_records, classes, class_subjects, campuses, staff, permissions.md.

4.7 KiB Raw Blame History