# Safety Quiz Results Backend

## Purpose

`safety_quiz_results` stores weekly safety/de-escalation quiz submissions per authenticated staff
user. The backend owns tenant scope, user ownership, the user display-name snapshot, the product
role snapshot, and persistence. Each submission is an append (create) — there is no update path.

## Slice Files (by layer)

- Route: `src/routes/safety_quiz_results.ts` (thin wiring; `GET /`, `GET /me`,
  `GET /completion`, `POST /`).
- Controller: `src/api/controllers/safety_quiz_results.controller.ts` (custom — not the CRUD
  factory).
- Service (BLL): `src/services/safety_quiz_results.ts`.
- Repository (DAL): queries run through `db.safety_quiz_results` inside the service (no separate
  `db/api/safety_quiz_results.ts`).
- Model: `src/db/models/safety_quiz_results.ts`.
- Shared used: `db/with-transaction.ts` (`withTransaction`); `shared/constants/pagination.ts`
  (`resolvePagination`); `services/shared/access.ts` (`getOrganizationIdOrGlobal`, `getCampusId`,
  `assertAuthenticatedTenantUser`, `hasFeaturePermission`, `getDisplayName`);
  `shared/constants/roles.ts` (`ROLE_NAMES`); `shared/errors/validation.ts` (`ValidationError`).

## API

All routes require JWT authentication. Base path mounted at `/api/safety_quiz_results`.

- `GET /api/safety_quiz_results` -> `200` `{ rows, count }`. Optional query `week_of`, plus
  `limit` / `page` (paginated via `resolvePagination`). Returns results visible to the current user
  (see Access Rules), ordered by `completed_at` desc.
- `GET /api/safety_quiz_results/me` -> `200` `{ completed, result }`. Optional query `week_of`.
  Always reads only the authenticated user's own saved quiz result and is used for profile status
  and weekly notification state.
- `GET /api/safety_quiz_results/completion` -> `200` `{ summary, rows }`. Optional query
  `week_of`. Requires report access and returns every staff user in the current scope with
  `complete` or `pending` status based on saved `safety_quiz_results` rows.
- `POST /api/safety_quiz_results` -> `201`. Request body wrapped as `{ data: <SafetyQuizInput> }`.
  Returns the created result DTO. If the caller is a parent-scope user acting through a drilled
  child scope, the request is accepted as a no-op and returns `null`.

## Access Rules

- All operations require an authenticated tenant user (`assertAuthenticatedTenantUser`).
- `create`: a staff user creates a result for themselves; ownership fields are filled from the
  authenticated user.
- `create` persists only when the active scope is the user's own scope. Parent users drilled into a
  child school/campus/classroom can complete the quiz there, but the backend does not create
  reportable quiz rows for that child scope.
- `list`: users with `READ_SAFETY_QUIZ_REPORTS` see scope-filtered results;
  everyone else sees only their own rows (filtered by `userId`).
- `me`: ignores report access and only checks the authenticated user's own saved result rows.
- `completion`: requires `READ_SAFETY_QUIZ_REPORTS` and joins staff users in the current scope with
  saved result rows. Pending rows are derived from missing database results, not frontend state.
  Role-seeded permissions are only the baseline grants. `custom_permissions` can
  grant the report permission and
  `custom_permissions_filter` can remove it for non-global users.

## Tenant Scope

- Organization is resolved via `getOrganizationIdOrGlobal`: global access users bypass the org
  filter and see results across all organizations; regular users are bound to their organization.
- On create, `campusId` is set from `getCampusId`; `userId`, `createdById`, `updatedById` come from
  the current user.
- Drilled child scopes are not treated as the user's own scope for personal saves, even though list
  visibility can use the active scope for reports.

## Data Contract

- Mutation input (`SafetyQuizInput`): `quiz_id`, `quiz_title`, `week_of` (non-empty strings);
  `score` and `total_questions` (integers); `answers` (an array of integers). Invalid input raises
  `ValidationError`.
- On create the backend fills `user_name` from `getDisplayName(currentUser)` and `user_role` from
  the user's `app_role.name` (defaulting to `teacher`); `completed_at` is set to the current time. The frontend does not
  send name, role, or ownership fields.
- DTO fields: `id`, `quiz_id`, `quiz_title`, `week_of`, `score`, `total_questions`, `answers`,
  `user_name`, `user_role`, `completed_at`, `organizationId`, `campusId`, `userId`, `createdAt`,
  `updatedAt`.
- Model columns: `quiz_id`, `quiz_title`, `week_of`, `user_name`, `user_role` (all TEXT, not null);
  `score`, `total_questions` (INTEGER, not null); `answers` (JSONB, not null); `completed_at`
  (DATE, not null); `importHash` (unique); plus tenant/audit UUID columns (`organizationId`,
  `campusId`, `userId`, `createdById`, `updatedById`, all nullable). The model is `paranoid` (soft
  delete via `deletedAt`) and uses `freezeTableName`.
- Associations: `belongsTo` organizations (`organization`), campuses (`campus`), users (`user`,
  `createdBy`, `updatedBy`).

## Behavior / Notes

- `create` first checks whether the caller is acting in their own scope. If not, it skips
  persistence and returns `null`. Otherwise it runs inside `withTransaction`; trimmed string fields
  are persisted.
- `list` is paginated with shared defaults (`resolvePagination`).
- `completion` reports organization, school, campus, and class scope staff according to the active
  scope. Student, guardian, guest, and system roles are not completion subjects.

## Tests

- `src/services/personal_scope_results.test.ts` verifies that parent users drilled into child
  scopes do not create safety quiz result rows, that personal status reads from saved rows, and that
  completion reports include both completed and pending staff.

## Related

- Frontend: `frontend/docs/safety-quiz-integration.md`.
- Quiz content management: `backend/docs/content-catalog.md` (`safety-qbs-quiz` is organization-scoped).
- Related slices: `personality-quiz-results.md`, `walkthrough-checkins.md`, `user-progress.md`.