UX authoring Backend Alignment (Questions + Evaluations + Passages)

This document captures backend-supported authoring capabilities that are currently missing or under-specified in authoring UX docs, and proposes how UX should handle them.

Scope:

• Question authoring
• Evaluation authoring
• Passage authoring and linkage
• Cross-cutting authoring flows (bulk, import, taxonomy, usage, lifecycle)

0. Why this exists

UX-AUTHORING.md defines the core interaction model. Since then, backend authoring contracts expanded materially (bulk actions, usage graphs, passages, verification/review policy controls, import pipelines, etc.).

Without this alignment layer, frontend implementation will either:

• hide useful backend capability, or
• invent UI behavior that conflicts with API contracts.

1. Missing Feature Map (Backend -> UX)

Capability (Backend)	Current UX Coverage	UX Proposal	Priority
Question lifecycle includes in_review (not only draft/published/archived)	Missing	Add explicit In Review chip and list filter; treat as editable but publish-blocked unless review requirements pass.	P1
Safe delete fallback (question_in_use / evaluation_in_use) with counts and archive fallback	Missing	Replace generic delete confirm with "Delete or Archive" decision modal. If API returns in-use conflict, show impact counts and complete as archive-first with explicit confirmation result.	P1
Bulk actions (archive, restore, taxonomyReplace) with dryRun + per-item outcomes	Missing	Add Bulk Action Drawer with 2-step flow: Preview (dry run) -> Apply; show result table (ok/code/message/changed) and downloadable failures list.	P1
CSV import preview/commit for questions, passages, evaluations	Missing	Add Import Wizard: upload -> row diagnostics -> fix/retry -> commit summary. Keep row-level errors visible and localizable.	P1
Passage CRUD and passage->questionVersion linkage	Under-specified	Add "Passage Library" in authoring nav; include passage editor, linked question versions panel, and usage count chips.	P1
Evaluation version policy controls (randomizationType, fixedSeed, requiredVerificationLevel, reviewPolicy, autoApprove)	Partially implied	Add "Delivery & Defensibility" panel in Evaluation Version settings with safe defaults and progressive disclosure for advanced policy.	P1
Evaluation feedback config (feedbackTagKeys)	Missing	Add "Feedback Disclosure" section in Evaluation version settings with selectable tag keys and preview of what candidate sees.	P2
Section item types include questionVersionId, bucketId, passageId, passageBucketId	Partial	Extend builder item picker to support all four item types with explicit type badges and per-type validation hints.	P1
Per-section controls include navigation and timeLimitSeconds	Partial	Add section settings drawer with explicit "Linear/Free roam" and optional section timer controls.	P2
Usage graph dependencies are detailed (evaluations/passages for questions; assignments/programmes/content packs for evaluations)	Partial	Upgrade "Usage" tab from counts-only to dependency graph list with deep links and impact severity labels.	P1
Taxonomy assignment + hierarchy filters (terms_any, terms_all, include_descendants)	Partial	Add taxonomy filter builder (Any/All + Include descendants toggle) in library filters and saved views UI.	P1
Inventory views support personal/shared with canonical filter schema	Partial	Keep current virtual folders UX, but add explicit schema-backed builder to prevent invalid filter payloads.	P2
Advanced sharing granularity (named users/groups) is planned, not yet backend-complete	Mentioned conceptually	Keep "Advanced sharing" visible but feature-flagged; UI copy should state "Org shared today, granular ACL coming".	P2
Optimistic concurrency (ifUpdatedAt) on question metadata updates	Missing	Add stale-write conflict UX: "Someone updated this item. Review changes and retry." with refresh/merge choices.	P2
Localization projections (lang, localeProjection) on question/passage read surfaces	Missing	Add locale-aware editing shell with default locale picker, fallback indicator, and "view as locale" preview.	P2
Structured error envelopes + stable codes	Partial (global conventions docs only)	authoring forms should map code-based errors/warnings consistently, never raw backend strings.	P1

2. Proposed UX Patterns

2.1 Delete/Archive Decision Pattern (MUST)

Problem:

• Backend can refuse hard delete and provide structured in-use counts, then archive.

UX pattern:

1. Primary action in list/detail remains Delete.
2. Confirmation modal has two options:
   • Delete permanently (only when safe)
   • Archive instead (recommended default)
3. If API returns *_in_use, modal transitions to impact mode:
   • show counts (submissions, activeSessions, etc.)
   • show note: "Historical records exist; archive preserves defensibility."
4. Success toast should reflect actual outcome (Archived instead of deleted).

2.2 Bulk Action Drawer (MUST)

Flow:

1. Select rows in library table.
2. Open Bulk Action Drawer.
3. Action select: Archive / Restore / Replace taxonomy.
4. Preview changes calls dry-run.
5. Result table shows:
   • changed/not changed
   • error code
   • message
6. Apply runs mutating call with same payload.
7. Final summary with succeeded/failed/changed counts.

Guardrails:

• Block apply when taxonomyReplace has no terms selected.
• Keep partial success visible; do not collapse to a binary success state.

2.3 Import Wizard (MUST)

Flow:

1. Upload CSV (or paste).
2. Preview parse and validation.
3. Row diagnostics with filter chips (valid, errors).
4. Commit accepted rows.
5. Post-commit summary:
   • created count
   • created asset IDs
   • link to filtered inventory view of imported assets.

Notes:

• This should be implemented for questions, passages, and evaluations with shared components.

2.4 Evaluation Policy Panel (MUST)

New panel in Evaluation Version settings:

• Randomization mode: dynamic/fixed
• Fixed seed (required only for fixed mode)
• Required verification level (L1-L4)
• Review policy: self-approve / four-eyes
• Auto-approve: allowed only when compatible with review policy

Behavior:

• Show policy compatibility checks inline before publish.
• Persist as part of version settings, not runtime session controls.

2.5 Passage authoring Surface (MUST)

Add Passages as a first-class authoring library:

• list/detail/edit passages
• tags + locale-aware content
• linked question versions list
• quick action: replace linked question versions

Why:

• Backend already treats passages as reusable assets; UX should not force hidden or indirect editing.

2.6 Usage Graph View (MUST)

Question usage:

• evaluations referencing the question
• passages linking the question version

Evaluation usage:

• assignments
• programme requirements
• content packs

UI behavior:

• show dependency type chips
• allow filtering by dependency type
• deep-link to dependent asset
• surface risk labels (active sessions, historical submissions present, etc.)

2.7 Locale-Aware authoring Shell (SHOULD)

For questions and passages:

• explicit default locale selector
• locale tabs/list
• "view as candidate locale" preview
• fallback indicator when requested locale is unavailable.

2.8 Conflict Resolution UX (SHOULD)

When optimistic concurrency fails:

• show non-destructive conflict panel
• options:
  • reload latest
  • copy draft edits to clipboard buffer
  • retry after refresh.

3. KOE Coverage Notes

These proposals keep KOE-aligned authoring practical:

• K: question/evaluation lifecycle, versioning, scoring, randomization
• O: evaluation review policy and verification controls that govern assessor workflows
• E: passage/evidence-linked authoring contexts and dependency visibility

No separate K/O/E UI split is required in authoring; the split should remain policy/structure-driven.

4. Suggested Delivery Order

Phase A (highest leverage):

1. Delete/archive decision UX
2. Bulk action drawer
3. Import wizard
4. Usage graph expansion
5. Evaluation policy panel

Phase B:

1. Passage library surface
2. Taxonomy filter builder with descendants semantics
3. Structured error/warning normalization in all authoring forms

Phase C:

1. Concurrency conflict UX
2. Locale-aware authoring shell
3. Advanced sharing (when backend ACL model is available)

5. Source references

• openapi/paths/questions/questions.yaml
• openapi/paths/questions/question-by-id.yaml
• openapi/paths/questions/question-usage.yaml
• openapi/paths/questions/passages.yaml
• openapi/paths/questions/passage-by-id.yaml
• openapi/paths/questions/passage-questions.yaml
• openapi/paths/evaluations/evaluations.yaml
• openapi/paths/evaluations/evaluation-by-id.yaml
• openapi/paths/evaluations/evaluation-versions.yaml
• openapi/paths/evaluations/evaluation-feedback.yaml
• openapi/paths/evaluations/evaluation-sections.yaml
• openapi/paths/evaluations/evaluation-section-items.yaml
• openapi/paths/evaluations/evaluation-usage.yaml
• openapi/components/schemas/common.yaml
• openapi/components/schemas/questions.yaml
• openapi/components/schemas/evaluations.yaml
• docs/product/content-library-approach.md
• docs/product/implementation-status-feature-matrix.md