# 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.

## Related

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