40227-vm/backend/docs/assessments.md

Assessments Backend

Purpose

assessments is the per-organization catalog of student assessments (quizzes, homework, exams, etc.) attached to a class subject. It is a generic-CRUD slice assembled from the shared factories; the backend is the source of truth for these records.

Slice Files (by layer)

• Route: src/routes/assessments.ts — createCrudRouter(controller, { permission: 'assessments' }).
• Controller: src/api/controllers/assessments.controller.ts — createCrudController(service, { csvFields }).
• Service (BLL): src/services/assessments.ts — createCrudService(DbApi, { notFoundCode: 'assessmentsNotFound' }).
• Repository (DAL): src/db/api/assessments.ts (AssessmentsDBApi) — entity-specific create/bulkImport/update/findBy/findAll; remove/deleteByIds/findAllAutocomplete delegate to db/api/shared/repository.ts.
• Model: src/db/models/assessments.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/api/file.ts (replaceRelationFiles for the attachments relation).

API

The standard generic-CRUD surface (all under /api/assessments, JWT + ${METHOD}_ASSESSMENTS permission, all 200) — see backend-architecture.md for the shared 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 name.
• GET /:id — returns the record with eager associations (see Data Contract).

csvFields: id, name, instructions, max_score, assigned_at, due_at.

Access Rules

• JWT required; the whole router is guarded by checkCrudPermissions('assessments'), deriving READ_ASSESSMENTS / CREATE_ASSESSMENTS / UPDATE_ASSESSMENTS / DELETE_ASSESSMENTS 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), name, instructions (TEXT, nullable).
• assessment_type — ENUM quiz | homework | project | midterm | final | other.
• status — ENUM draft | published | closed.
• assigned_at, due_at — DATE, nullable.
• max_score — DECIMAL (nullable).
• importHash (unique), organizationId, class_subjectId, createdById, updatedById, timestamps.

Associations: belongsTo organization, class_subject (class_subjects), createdBy/updatedBy (users); hasMany assessment_results_assessment (assessment_results); hasMany file as attachments (scoped relation). findBy/GET /:id eager-load assessment_results_assessment, organization, class_subject, and attachments in a single Promise.all.

List filters (AssessmentsFilter): id, name, instructions, calendarStart+calendarEnd (matches rows whose assigned_at or due_at falls between the two), assigned_atRange, due_atRange, max_scoreRange, active, assessment_type, status, class_subject (id or status text, |-separated, applied as an include where-clause), organization (|-separated ids), createdAtRange, plus field/sort ordering and limit/page pagination.

Behavior / Notes

• create/bulkImport/update manage the attachments file relation via FileDBApi.replaceRelationFiles.
• 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: AssessmentsFilter accepts an active flag the model has no column for; it is currently inert (kept for source accuracy).
• Note: the class_subject filter matches against the related class_subjects' status field for the text branch (kept for source accuracy).

Tests

None yet.

Related

• Generic-CRUD contract: backend-architecture.md; related slices: assessment_results, class_subjects, organizations, file.md, permissions.md.