# Personality Quiz Results Backend

## Purpose

`personality_quiz_results` stores each authenticated tenant user's current personality quiz
result (one row per user per organization) and exposes an aggregate distribution of personality
types for leadership reporting. The backend owns tenant scope, user ownership, the saved
personality type, and the answer snapshot. It does not write to user employment fields.

## Slice Files (by layer)

- Route: `src/routes/personality_quiz_results.ts` (thin wiring; `GET /me`, `PUT /me`,
  `GET /distribution`).
- Controller: `src/api/controllers/personality_quiz_results.controller.ts` (custom — not the CRUD
  factory).
- Service (BLL): `src/services/personality_quiz_results.ts`.
- Repository (DAL): queries run through `db.personality_quiz_results` inside the service (no
  separate `db/api/personality_quiz_results.ts`).
- Model: `src/db/models/personality_quiz_results.ts`.
- Shared used: `db/with-transaction.ts` (`withTransaction`); `services/shared/access.ts`
  (`getOrganizationIdOrGlobal`, `getCampusId`, `assertAuthenticatedTenantUser`, `hasFeaturePermission`);
  `shared/errors/*`
  (`ForbiddenError`, `ValidationError`).

## API

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

- `GET /api/personality_quiz_results/me` -> `200`. Returns the current user's saved result DTO
  (most recently updated), or `null` if none exists.
- `PUT /api/personality_quiz_results/me` -> `200`. Request body wrapped as
  `{ data: { personality_type, quiz_answers } }`. Creates or updates the current user's result and
  returns the saved 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 the caller's currently saved result (or `null`).
- `GET /api/personality_quiz_results/distribution` -> `200`. Optional query `campusId`. Returns
  `{ rows: [{ type, count }], count }` (number of distinct personality types). Restricted to report
  roles.

## Access Rules

- `getCurrentUserResult` / `upsertCurrentUserResult`: any authenticated tenant user
  (`assertAuthenticatedTenantUser`); each user reads and writes only their own result (filtered by
  `userId`).
- `upsertCurrentUserResult` persists only when the active scope is the user's own scope. Parent
  users drilled into a child school/campus/classroom can complete the UI flow there, but the backend
  does not create or update reportable quiz rows for that child scope.
- `distribution`: restricted to `READ_PERSONALITY_REPORTS`; otherwise
  `ForbiddenError`. Role-seeded permissions are only the baseline grants. The distribution response contains
  only `type` and `count` per group — no individual names or answers.
  `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 can see their results across organizations; regular users are bound to their org.
- On upsert, `campusId` is set from `getCampusId` (the current user's direct campus, else the
  user's `campusId`, else `null`); `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 reads
  and reports use the active scope for visibility.
- `distribution` filters by organization via `getOrganizationIdOrGlobal` (global users see all
  orgs) and, when a `campusId` query value is provided, additionally by that campus.

## Data Contract

- Mutation input (`PUT /me`): `personality_type` (non-empty string) and `quiz_answers` (a non-array
  object whose values are all non-empty strings). Invalid input raises `ValidationError`.
- On save, `personality_type` is trimmed and upper-cased; `completed_at` is set to the current
  time.
- DTO fields: `id`, `personality_type`, `quiz_answers`, `completed_at`, `organizationId`,
  `campusId`, `userId`, `createdById`, `updatedById`, `createdAt`, `updatedAt`.
- Model columns: `personality_type` (TEXT, not null), `quiz_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

- `upsertCurrentUserResult` first checks whether the caller is acting in their own scope. If not,
  it skips persistence and returns the current saved result. Otherwise it runs inside
  `withTransaction`: it looks up the existing row by
  `organizationId` + `userId` and updates it, otherwise creates a new one.
- `getCurrentUserResult` orders by `updatedAt` desc and returns the first match.
- `distribution` groups by `personality_type` with a `COUNT(id)` aggregate, ordered by count desc;
  `count` in the response is the number of distinct types returned.

## Tests

- `src/services/personal_scope_results.test.ts` verifies that parent users drilled into child
  scopes do not create or update personality quiz rows.

## Related

- Frontend: `frontend/docs/personality-integration.md`, `frontend/docs/personality-catalog.md`.
- Related slices: `safety-quiz-results.md`, `walkthrough-checkins.md`, `user-progress.md` (similar
  per-user tenant-scoped result/progress pattern).
