emaui/ema-exam-gap-analysis.md

EMA Exam System — Combined Gap Analysis

Repos: /home/tria/projects/mihretu/emaui (frontend, branch dev) · /home/tria/projects/mihretu/emaapi (backend, branch dev). Read-only — no files modified, nothing implemented, nothing committed, no branch created.

The user story, as directed: this task's own exam-lifecycle checklist (§5 of the brief — Exam Administration, Question Management, Candidate Management, Candidate Exam-Taking, Evaluation, Post-Exam) is treated as the requirements source, flattened below into 54 individually numbered, non-combined requirements. Every status below is traced to actual file:line evidence gathered from a full read of the relevant frontend and backend source — not inferred from documentation, comments, or the presence of an endpoint alone.

---

1. The User Story — Numbered Requirements

Exam Administration

1. Create exam
2. Configure exam (type/form/administration/evaluation/pass-mark/selection method as one settings unit)
3. Define exam type
4. Define subjects
5. Define sections
6. Configure duration
7. Configure passing score
8. Configure attempts
9. Configure exam status
10. Configure availability

Question Management

11. Create question
12. Edit question
13. Delete question
14. Question bank
15. Question types
16. MCQ options
17. Correct answers
18. Question scoring
19. Question ordering
20. Random questions
21. Paper assembly

Candidate Management

22. Candidate registration
23. Candidate eligibility
24. Candidate assignment
25. Attendance
26. Candidate status

Candidate Exam-Taking

27. Exam instructions
28. Start exam
29. Create attempt/session
30. Timer
31. Question navigation
32. Display questions
33. Select answers
34. Save answers
35. Auto-save
36. Resume attempt
37. Submit exam
38. Prevent submission after expiration
39. Prevent unauthorized access

Evaluation

40. Automatic grading
41. Manual grading
42. Score calculation
43. Pass/fail
44. Result generation
45. Result review
46. Result approval
47. Result publication

Post-Exam

48. Result viewing
49. Appeals
50. Appeal review
51. Retakes
52. Exam history
53. Notifications
54. Certificates, if required

---

2. Frontend Comparison

#	Requirement	Status	Evidence
1	Create exam	✅	apps/backoffice/.../exam/pages/ExamPage.tsx — full create form → useCreateExamMutation
2	Configure exam	✅	Same form, Settings tab: type/form/administration/evaluation/selection method/cutting point/status
3	Define exam type	✅	ExamPage.tsx — WRITTEN/ORAL Select, required
4	Define subjects	✅	ExamPage.tsx — certification Select; full CRUD at certification/pages/CertificationPage.tsx
5	Define sections	🔴	No component, field, or route anywhere in the exam feature tree
6	Configure duration	✅	ExamPage.tsx — days/hours/minutes inputs, captured on create/edit
7	Configure passing score	✅	ExamPage.tsx — cutting-point NumberInput, required
8	Configure attempts	🟡	No admin-facing control anywhere — attempt/retake is read-only display in the portal (ExamsPage.tsx badge), never a setting an officer configures
9	Configure exam status	✅	ExamPage.tsx — status Select, shown only when editing
10	Configure availability	🟡	No explicit "availability" control found; portal's GET /exams/open list is consumed as-is with no frontend criteria of its own
11	Create question	✅	question/pages/QuestionPage.tsx form → useCreateQuestionMutation
12	Edit question	✅	Same form → useUpdateQuestionMutation
13	Delete question	✅	Delete button + confirm modal → useDeleteQuestionMutation
14	Question bank	✅	QuestionPage.tsx list, filterable by certification
15	Question types	🟡	Only two labels selectable: ESSAY / CHOICE (QuestionForm type in question/types/question.ts)
16	MCQ options	🔴	No options/choices field anywhere in question.ts, the create/edit form, or any component
17	Correct answers	🔴	No correctAnswer/answer-key field or control anywhere
18	Question scoring	✅	points field on the question form; bounded score entry in RecordResultModal.tsx
19	Question ordering	⚠️	No ordering UI found; not confirmed whether the assignment list has any inherent order
20	Random questions	✅	exam/components/QuestionAssigner.tsx (random mode) → useSelectRandomQuestionsMutation
21	Paper assembly	✅	QuestionAssigner.tsx (manual mode) → useAssignQuestionsMutation
22	Candidate registration	✅	Portal exams/pages/ExamsPage.tsx → register button → mutation to /exams/:id/register
23	Candidate eligibility	✅	Same page — maps seafarer_registration_required/subject_already_passed server errors to readable copy before/after attempting registration
24	Candidate assignment	🔴	exam/components/ExamCandidatesPanel.tsx can only view + mark attendance; no add/remove-candidate control anywhere in the backoffice
25	Attendance	✅	ExamCandidatesPanel.tsx — per-candidate + bulk marking, required remark on Withdrawn/Disqualified
26	Candidate status	✅	Same panel — attendance-status badges (Registered/Present/Absent/Late/Withdrawn/Disqualified)
27	Exam instructions	🟡	Bilingual direction field captured on the exam form; no screen anywhere displays it to a candidate
28	Start exam	🔴	No route, component, button, or handler anywhere in apps/portal
29	Create attempt/session	🔴	No concept anywhere — no attempt/session state, type, or API call
30	Timer	🔴	No countdown/timer component anywhere in either app
31	Question navigation	🔴	No question-by-question view exists to navigate
32	Display questions	🔴	No candidate-facing question-rendering component anywhere
33	Select answers	🔴	No answer-selection UI/state anywhere
34	Save answers	🔴	No save action or API call anywhere
35	Auto-save	🔴	No auto-save timer/effect anywhere in the exam feature (the licensing wizard's per-section PATCH auto-save pattern exists but is not used by, or wired to, anything exam-related)
36	Resume attempt	🔴	No resume logic anywhere (nothing to resume)
37	Submit exam	🔴	No submit action anywhere distinct from application/appeal "submit" flows
38	Prevent submission after expiration	🔴	No expiration check anywhere (no timer to expire)
39	Prevent unauthorized access	🔵	Not applicable — no attempt exists for an access check to protect
40	Automatic grading	🔴	No grading logic in the frontend at all (grading is entirely a backend concern either way)
41	Manual grading	✅	result/components/RecordResultModal.tsx — bounded per-question score entry, live pass/fail preview
42	Score calculation	✅	Same component — client preview mirrors the exam's evaluation method (SUM/AVERAGE/PERCENTAGE)
43	Pass/fail	✅	Same — preview only; frontend never sends a status/outcome field, matching backend design
44	Result generation	✅	RecordResultModal.tsx → useCreateResultMutation
45	Result review	✅	result/pages/ResultPage.tsx — moderate/return actions with required remarks
46	Result approval	✅	Same page — approve action
47	Result publication	✅	Same page — publish-per-exam action, reports published/skipped counts
48	Result viewing	✅	Portal ExamsPage.tsx — "My results" table
49	Appeals	✅	Portal ExamsPage.tsx — appeal modal with required reason, 14-day-window copy
50	Appeal review	✅	Backoffice result/pages/ExamAppealsPage.tsx — uphold/reject with required remark
51	Retakes	🟡	Display-only: portal shows kind/attemptNumber badges; no dedicated retake workflow beyond ordinary registration
52	Exam history	🟡	No dedicated history view; the registrations table and results table (both already counted above) are the closest equivalent
53	Notifications	⚠️	Portal notifications/pages/NotificationsPage.tsx is generic (GET /notifications); not confirmed whether/how exam-specific notices render distinctly
54	Certificates, if required	🔴	certificate-designer/pages/CertificateDesignerPage.tsx exists but targets license/permit templates (licensing-api.ts's license-templates endpoints) — confirmed via its own data hooks — not exam results

---

3. Backend Comparison

(Global note, applies to every "NO GUARD" row below: JwtGuard is registered as a global APP_GUARD — every route requires a valid authenticated session regardless. "NO GUARD" means no PermissionGuard role/permission check on top of that base authentication — i.e., reachable by any signed-in account, not by the public.)

#	Requirement	Status	Evidence
1	Create exam	🟡	POST /exams exists (exam.controller.ts, inherited CommonCrudController) — no PermissionGuard
2	Configure exam	🟡	PUT /exams/:id — same route, same gap; all settings fields are real columns on exams (exam.entity.ts)
3	Define exam type	✅	EExamType enum (common/enums/enums.ts), Exam.type column
4	Define subjects	🟡	certificationId FK is solid; but certification.controller.ts (bare CommonCrudController) has no guard at all on its full CRUD, including the write that would toggle isActive
5	Define sections	🔴	No table, column, or entity anywhere in the exam schema (confirmed against base migration 1785742151690-EmaBaseline.ts + both later exam migrations)
6	Configure duration	🟡	Exam.givenTime/Question.time (jsonb) store it, but nothing in exam.service.ts/result.service.ts ever reads it against a clock
7	Configure passing score	✅	Exam.cuttingPoint (numeric), consumed by result.service.ts::outcomeFor()
8	Configure attempts	✅ (as built)	ExamRegistrationService.resolveAttempt() fully, automatically derives attempt number/kind server-side — no client input accepted, no admin-configurable cap exists (a candidate may retake indefinitely unless their most recent published result is PASSED)
9	Configure exam status	✅	EExamStatus enum (PENDING/ACTIVE/COMPLETED/CANCELLED/POSTPONED/PUBLISHED), Exam.status column
10	Configure availability	⚠️	GET /exams/open route exists (exam.controller.ts); exact server-side "open" criteria not independently traced in this pass
11	Create question	🟡	POST /questions (inherited CommonCrudController) — no PermissionGuard
12	Edit question	🟡	PUT /questions/:id — same gap
13	Delete question	🟡	DELETE /questions/:id — same gap
14	Question bank	🟡	GET /questions — same gap; returns rows of every EQuestionStatus (DRAFT/PENDING_APPROVAL/APPROVED/REJECTED/RETIRED) to any authenticated caller, no status filter applied server-side for unprivileged callers
15	Question types	🟡	EExamForm enum: ESSAY | CHOICE only — a category label, nothing deeper
16	MCQ options	🔴	question.entity.ts (confirmed full column list) and question.dto.ts (both create/update payloads) carry no options/choices field of any kind
17	Correct answers	🔴	No correctAnswer/answerKey column anywhere on Question or any related table
18	Question scoring	✅	Question.points (numeric); Result.resultBreakdowns[].score summed in result.service.ts::grade()
19	Question ordering	⚠️	exams_questions is a plain composite-PK join table (exam_id, question_id) — no order/sequence column found
20	Random questions	🟡	POST /exams/:id/questions/random — real server-side draw, correctly APPROVED-only filtered, but no guard
21	Paper assembly	🟡	POST /exams/:id/questions — same gap
22	Candidate registration	✅	POST /exams/:id/register — ownership-scoped to the caller, real
23	Candidate eligibility	✅	Same service — ACTIVE-seafarer requirement + subject_already_passed hard block enforced server-side
24	Candidate assignment	🔴	No createRegistration/admin-add endpoint exists anywhere in exam-registration.service.ts — registration is exclusively self-service
25	Attendance	✅	POST /exams/registrations/:id/attendance + bulk variant, both guarded RECORD_EXAM_ATTENDANCE
26	Candidate status	✅	EExamAttendanceStatus enum, matches frontend exactly
27	Exam instructions	✅ (storage only)	Exam.direction (jsonb) stored and returned; nothing to display it to a candidate exists downstream
28	Start exam	🔴	No route, service method, or entity anywhere
29	Create attempt/session	🔴	Confirmed absent by direct search of every migration and entity — no attempt/session table exists. common/entities/session.entity.ts is the login session, unrelated
30	Timer	🔴	No timer/expiry logic anywhere in the exam domain
31	Question navigation	🔵	Not applicable server-side (a client concern) — but nothing to serve questions incrementally exists either
32	Display questions	🔴	No candidate-facing "get my exam questions" endpoint exists
33	Select answers	🔴	No answer-capture DTO/entity anywhere
34	Save answers	🔴	No persistence path anywhere
35	Auto-save	🔴	No such endpoint in the exam domain
36	Resume attempt	🔴	No in-progress state exists to resume
37	Submit exam	🔴	No submission event/timestamp on any exam-taking entity (distinct from the unrelated license-application "submit")
38	Prevent submission after expiration	🔴	No expiration check anywhere
39	Prevent unauthorized access	🔵	Not applicable — no attempt entity exists to protect
40	Automatic grading	🔴	result.service.ts::grade() sums officer-entered resultBreakdowns only; never compares to a stored answer, because none is stored
41	Manual grading	🟡	POST /results (create) and PUT /results/:id (update) — no PermissionGuard, despite RECORD_EXAM_RESULT existing and being applied to other routes in the same controller
42	Score calculation	✅	grade() — sum/average/percentage per Exam.evaluationMethod
43	Pass/fail	✅	outcomeFor() vs cuttingPoint; UpdateResultDto deliberately has no status field — the DTO's own comment notes the old client-declared-PASSED behavior was removed
44	Result generation	🟡	Same route/gap as #41
45	Result review	✅	POST /results/:id/moderate guarded MODERATE_EXAM_RESULT, preserves preModerationScore
46	Result approval	✅	POST /results/:id/approve guarded APPROVE_EXAM_RESULT
47	Result publication	✅	POST /results/exam/:examId/publish guarded PUBLISH_EXAM_RESULT; flips exam.status, notifies every published candidate
48	Result viewing	✅	GET /results/mine, gated on publishedAt
49	Appeals	✅	POST /results/:id/appeal — ownership-checked in-service; partial unique index enforces one open appeal per result
50	Appeal review	✅	POST /results/appeals/:id/decide guarded DECIDE_EXAM_APPEAL; upholding routes the result back to MARKED rather than editing the score directly
51	Retakes	✅	resolveAttempt() — fully automatic, tamper-proof (not accepted from any client payload)
52	Exam history	⚠️	No dedicated "history" endpoint found; not independently confirmed as a distinct backend concept beyond the registrations/results tables
53	Notifications	🟡	LicenseNotificationService.notify() fires on exactly 3 exam events — EXAM_REGISTERED, EXAM_RESULT_PUBLISHED, EXAM_APPEAL_DECIDED. Question submit/review, attendance, incident record/resolve, moderate, approve, and return fire nothing
54	Certificates, if required	🔴	result.service.ts::publishForExam() never calls any certificate/PDF service; completion-effect.service.ts implements exactly two effects (REGISTER_SEAFARER, REGISTER_VESSEL) and references neither Exam nor Result

---

4. Combined Gap Matrix

#	Requirement	Frontend	Backend	Overall	Gap	Priority
1	Create exam	✅	🟡	🟡	Backend: no permission guard on create/edit	P0
2	Configure exam	✅	🟡	🟡	Same permission gap	P0
3	Define exam type	✅	✅	✅	None	—
4	Define subjects	✅	🟡	🟡	Certification CRUD entirely unguarded server-side	P0
5	Define sections	🔴	🔴	🔴	Entire concept absent, both sides	P2 (only if the product needs multi-part papers)
6	Configure duration	✅	🟡	🟡	Stored but never enforced against a clock	P1 (blocks Timer, #30)
7	Configure passing score	✅	✅	✅	None	—
8	Configure attempts	🟡	✅ (as built)	🟡	No admin-configurable cap; frontend is display-only	P2
9	Configure exam status	✅	✅	✅	None	—
10	Configure availability	🟡	⚠️	⚠️	Server-side "open" criteria not independently confirmed	P3
11	Create question	✅	🟡	🟡	No permission guard	P0
12	Edit question	✅	🟡	🟡	No permission guard	P0
13	Delete question	✅	🟡	🟡	No permission guard	P0
14	Question bank	✅	🟡	🟡	Unguarded, no status filter for unprivileged callers — full bank incl. unapproved content is readable by any authenticated user	P0
15	Question types	🟡	🟡	🟡	Only two labels exist; no deeper typing	P1
16	MCQ options	🔴	🔴	🔴	No data model, both sides	P0 (blocks #40 automatic grading)
17	Correct answers	🔴	🔴	🔴	No data model, both sides	P0 (blocks #40)
18	Question scoring	✅	✅	✅	None	—
19	Question ordering	⚠️	⚠️	⚠️	No ordering mechanism confirmed either side	P3
20	Random questions	✅	🟡	🟡	No permission guard	P0
21	Paper assembly	✅	🟡	🟡	No permission guard	P0
22	Candidate registration	✅	✅	✅	None	—
23	Candidate eligibility	✅	✅	✅	None	—
24	Candidate assignment	🔴	🔴	🔴	No officer-initiated add/remove capability, both sides	P1
25	Attendance	✅	✅	✅	None	—
26	Candidate status	✅	✅	✅	None	—
27	Exam instructions	🟡	✅ (storage only)	🟡	Stored but nothing displays it — downstream of the missing exam-taking flow	P0 (dependent on #28–37)
28	Start exam	🔴	🔴	🔴	Entire capability absent, both sides	P0
29	Create attempt/session	🔴	🔴	🔴	No data model, no API	P0
30	Timer	🔴	🔴	🔴	No enforcement mechanism	P0
31	Question navigation	🔴	🔵	🔴	Nothing to navigate	P0
32	Display questions	🔴	🔴	🔴	No candidate-facing question-serving endpoint	P0
33	Select answers	🔴	🔴	🔴	No data model	P0
34	Save answers	🔴	🔴	🔴	No persistence path	P0
35	Auto-save	🔴	🔴	🔴	Not wired to anything exam-related (reusable pattern exists elsewhere)	P0
36	Resume attempt	🔴	🔴	🔴	No in-progress state to resume	P0
37	Submit exam	🔴	🔴	🔴	No submission event	P0
38	Prevent submission after expiration	🔴	🔴	🔴	No timer to expire against	P0
39	Prevent unauthorized access	🔵	🔵	🔵	Not applicable until #29 exists	—
40	Automatic grading	🔴	🔴	🔴	Blocked on #16/#17 (MCQ data model)	P0
41	Manual grading	✅	🟡	🟡	No permission guard on create/update	P0
42	Score calculation	✅	✅	✅	None	—
43	Pass/fail	✅	✅	✅	None	—
44	Result generation	✅	🟡	🟡	Same permission gap as #41	P0
45	Result review	✅	✅	✅	None	—
46	Result approval	✅	✅	✅	None	—
47	Result publication	✅	✅	✅	None	—
48	Result viewing	✅	✅	✅	None	—
49	Appeals	✅	✅	✅	None	—
50	Appeal review	✅	✅	✅	None	—
51	Retakes	🟡	✅	✅	Frontend display-only, no gap in function	—
52	Exam history	🟡	⚠️	🟡	No dedicated view/endpoint beyond existing tables	P3
53	Notifications	⚠️	🟡	🟡	Only 3 of ~8 exam events notify	P2
54	Certificates, if required	🔴	🔴	🔴	No link from a published PASSED result to certificate issuance, either side	P1 (pending product decision — "if required")

---

5. Exam System Deep-Dive

The full lifecycle breakdown is §§1–4 above (every row already carries Frontend / Backend / Overall / Evidence / Gap). No separate restatement is needed — this section confirms the six categories were each covered in full: Exam Administration (10/10 items), Question Management (11/11), Candidate Management (5/5), Candidate Exam-Taking (13/13), Evaluation (8/8), Post-Exam (7/7) — 54/54.

---

6. Important Existing Exam Findings — Explicit Verification

Candidate exam-taking. Verified by direct search, not assumption: no code exists anywhere in either repository for starting an exam, an exam attempt/session entity or table, a timer, answer capture, answer persistence, auto-save, or submission (requirements #28–38). Exam.givenTime/Question.time are stored durations that are never read against a clock. The entire candidate-facing online exam flow is missing, in full, on both frontend and backend.

MCQ structure. Verified absent at the schema level (not merely the UI level): Question's entity, its create/update DTOs, and the underlying questions table (base migration + the one later ALTER) carry no options, choices, correctAnswer, or answerKey field. EExamForm.CHOICE is a category label only. Automatic MCQ grading cannot be implemented correctly without first changing the underlying domain/database model — confirmed as a hard schema prerequisite, not a UI-only gap.

Automatic grading. Verified the backend has no automatic grading logic. result.service.ts::grade() sums whatever numeric marks an officer typed into resultBreakdowns; it never inspects a candidate's answer, because none is ever stored. Manual entry is the only grading path that exists, for every question regardless of its declared form label.

Manual grading. Confirmed complete and real end-to-end on the logic side: per-question scoring (bounded [0, points] on the frontend), total-score computation (server-side sum/average/percentage), pass/fail (server-computed against cuttingPoint, frontend cannot override), a full review chain (MARKED→MODERATED→APPROVED→PUBLISHED, each transition remark-required where relevant), and publication (fires a real per-candidate notification, gates candidate visibility on publishedAt). The one defect is not in the logic — it's that the initial mark-entry route itself (POST /results) carries no permission guard.

Exam permissions. Sharply two-tier — this is the analysis's central finding:

• Correctly guarded (a non-privileged authenticated user gets a real 403): question review/approve (APPROVE_QUESTION), attendance (RECORD_EXAM_ATTENDANCE), incident management (MANAGE_EXAM_INCIDENTS), result moderate/approve/publish (MODERATE_/APPROVE_/PUBLISH_EXAM_RESULT), appeal decisions (DECIDE_EXAM_APPEAL).
• Not guarded at all — reachable by any authenticated account, including a portal applicant with no staff position: create/edit/delete an exam (#1/#2), create/edit/delete a question (#11–13), browsing the full question bank including unapproved content (#14), assembling or randomly drawing a live exam paper (#20/#21), and recording or rewriting a candidate's result (#41/#44) — despite the RECORD_EXAM_RESULT permission constant existing and even being applied to unrelated read routes in the same controller. Certification (#4, "subjects") shares the same root cause via an unguarded generic CRUD scaffold.

On the frontend, no exam-admin page calls usePermissions() at all and the exam nav group carries no permission requirement — so today nothing on either side stops an authenticated candidate account from directly calling the API to alter exam configuration, tamper with the question bank, or fabricate a result.

---

7. Frontend ↔ Backend Contract Gaps

Requirement	Frontend State	Backend State	Contract Gap
Start exam / attempt / timer / answers / auto-save / submit (#28–38)	Missing	Missing	Both missing — new end-to-end feature, blocked on a data-model decision first (see §14)
MCQ options / correct answers (#16, #17)	Missing	Missing	Both missing — schema prerequisite for #40
Certificates on pass (#54)	Missing (wrong-domain page shares the name)	Missing	Both missing — needs a product decision on reuse-vs-new-build
Candidate assignment by an officer (#24)	Missing	Missing	Both missing
Question bank browsing (#14)	Assumes a curated/approved list	Returns everything, unguarded	Frontend implicitly relies on server-side filtering/guarding that doesn't exist
Configure attempts (#8)	Missing (display-only)	Exists, but fully automatic with no admin-facing "cap" concept	Backend has the logic; there is no configuration surface on either side because the backend never exposes one
Manual grading, result generation (#41, #44)	Complete	Logic complete, route unguarded	Backend security gap underneath an otherwise-complete frontend flow

---

8. Data Model Gaps

Confirmed against every migration touching an exam table (1785742151690-EmaBaseline.ts, 1785749000000-examRegistration.ts, 1785750000000-examOperations.ts — no other migration touches these tables) and every corresponding entity file:

Concept	Current state	Why insufficient	Requirement(s) blocked
Exam	exams table, full administrative metadata	Sufficient for the administrative workflow as built	#1–4, 6, 7, 9
Exam sections	Does not exist	Nothing partitions an exam's question set	#5
Questions	questions table — title, form, points, time, QC status	No options, no correct answer	#16, #17, #40
Question options/choices	Does not exist — no child table, no jsonb column	Blocks #16, and any candidate-facing question display	#16, #32, #40
Correct answer / answer key	Does not exist	Blocks automatic comparison of a candidate's answer	#17, #40
Exam attempts / sessions	Does not exist. ExamRegistration.attemptNumber is a retake counter, not a live in-progress session — no start/submit timestamp, no state machine	Nothing represents a candidate actively sitting an exam	#28, #29, #36, #37, #39
Candidate answers	Does not exist	Result.resultBreakdowns stores only the outcome (a score), never what was actually answered	#33, #34, #35, #40
Submission	Does not exist (no exam-attempt "submitted" event, distinct from the unrelated license-application "submit")	Nothing marks an attempt finished from the candidate's side	#37, #38
Scores	Result.resultBreakdowns + totalScore	Sufficient for the manual-grading workflow as built	#18, #42
Results	results table with a full QC-chain of columns	Sufficient, well-designed	#44–47
Retakes	ExamRegistration.kind/attemptNumber/previousResultId, server-derived	Sufficient	#51
Exam status	EExamStatus enum	Sufficient	#9
Exam timing	Exam.givenTime/Question.time — informational jsonb only	Never enforced against a clock; no "time remaining"/deadline field	#6, #30, #38

No new schema is proposed here, per this task's scope — only what's missing and which requirement it blocks.

---

9. Existing Functionality That Should NOT Be Rebuilt

• Exam creation/configuration (#1–4, 6, 7, 9) — solid on both sides; only needs its permission guard added, not a rewrite.
• Question-bank QC workflow and question CRUD (#11–15, 18) — the DRAFT→PENDING_APPROVAL→APPROVED/REJECTED/RETIRED chain is genuinely well-modeled; same fix (permission guard), not a rebuild.
• Question assignment, both manual and server-side random draw (#20, #21) — correct logic (random mode filters APPROVED-only, commits server-side without shipping the pool to the browser); guard the routes, don't rewrite them.
• Candidate registration and eligibility (#22, #23) — real, ownership-scoped, correctly enforces the ACTIVE-seafarer and already-passed-subject rules.
• Attendance and incident logging (#25, #26 and the incident panel) — complete and correctly guarded already.
• Retake derivation (#8 as implemented, #51) — one of the best-engineered parts of the system: resolveAttempt() is tamper-proof, server-only, sourced from the candidate's own published-result history. Preserve exactly as-is.
• Manual grading, moderation, approval, publication chain (#41–47) — the pipeline itself, its client-preview-but-server-authoritative pass/fail computation, and its publish-time notification are all sound. Only the initial create/update-result guard needs fixing.
• Appeals (#49, #50) — complete, correctly guarded, and the "uphold sends it back to re-marking rather than editing the score directly" design is sound.

---

10. Bugs vs. Missing Features vs. Incomplete Features

Existing Bugs (functionality exists, but is incorrect)

• No permission guard on POST/PUT/DELETE /exams (#1, #2), POST/PUT/DELETE /questions (#11–13), GET /questions (#14), POST /exams/:id/questions[/random] (#20, #21), POST/PUT /results (#41, #44) — any authenticated user, including a portal applicant, can alter exam configuration, the question bank, paper assembly, and candidate results.
• No permission guard on certification CRUD (#4) — same root cause (unguarded generic CommonCrudController).

Missing Features (no meaningful implementation on either side)

• Exam sections (#5).
• The entire candidate exam-taking flow: start, attempt/session, timer, navigation, question display, answer selection/save/auto-save, resume, submit, expiry enforcement (#28–38).
• MCQ options and correct-answer/answer-key data model (#16, #17).
• Automatic grading (#40) — blocked on the above.
• Officer-initiated candidate assignment (#24).
• Exam-pass certificate issuance (#54).

Incomplete Features (meaningful implementation exists, gaps remain)

• Question types (#15) — two labels exist, nothing deeper.
• Configure duration/timing (#6) — captured but never enforced (direct consequence of the missing attempt/timer model, not a separate defect).
• Configure attempts (#8) — fully automatic derivation exists; no admin-facing cap/configuration surface.
• Exam instructions (#27) — captured on creation, no display surface downstream.
• Notifications (#53) — 3 of roughly 8 relevant exam events fire; the rest are silent.
• Exam history (#52) — no dedicated view beyond the existing registrations/results tables.
• Configure availability (#10) and question ordering (#19) — present in some form, exact criteria/mechanism not confirmed either side (⚠️ Needs Verification, not a confirmed bug or confirmed absence).

---

11. Permission Gaps

Action	Frontend Permission Check	Backend Permission Check	Status
Create/edit/delete exam (#1, #2)	None (usePermissions() not used on exam pages)	None	Full-stack gap
Create/edit/delete question (#11–13)	None	None	Full-stack gap
Browse question bank (#14)	None	None	Full-stack gap
Assign/draw exam paper (#20, #21)	None	None	Full-stack gap
Record/edit exam result (#41, #44)	None	None (despite RECORD_EXAM_RESULT existing)	Full-stack gap
Define subjects — certification CRUD (#4)	None	None	Full-stack gap
Review/approve question	None (client-side)	APPROVE_QUESTION	Backend enforces; frontend gap is cosmetic only
Record attendance (#25)	None (client-side)	RECORD_EXAM_ATTENDANCE	Backend enforces; cosmetic frontend gap
Manage exam incidents	None (client-side)	MANAGE_EXAM_INCIDENTS	Backend enforces; cosmetic frontend gap
Moderate/approve/publish result (#45–47)	None (client-side)	MODERATE_/APPROVE_/PUBLISH_EXAM_RESULT	Backend enforces; cosmetic frontend gap
Decide exam appeal (#50)	None (client-side)	DECIDE_EXAM_APPEAL	Backend enforces; cosmetic frontend gap

Inconsistent permission names: none found — every guard that exists uses matching string keys between the frontend's PERMISSIONS constant and the backend's LICENSE_PERMISSIONS constant, for the (small) subset of exam actions the frontend mirrors at all. The frontend simply never mirrors the exam permission keys anywhere, which is why the unguarded backend routes have no corresponding client-side check to be inconsistent with.

Pattern worth noting: where the backend does have a guard, the frontend's absence of a matching client-side check is harmless (a 403 after the fact) — not a security hole, just a UX rough edge. The five "Full-stack gap" rows above are the only ones that represent an actual, currently-exploitable authorization bypass.

---

12. Overall User-Story Completion

Method: every one of the 54 numbered requirements in §1 was independently traced on both frontend and backend to file:line depth (§§2–4) — this percentage is a direct count of that table, not an estimate.

• ✅ Fully Complete (both sides, no gap): 27 of 54 = 50% — #3, 7, 9, 18, 22, 23, 25, 26, 42, 43, 45, 46, 47, 48, 49, 50, 51 (function complete; frontend display-only doesn't block it), plus 10 more counted at the "logic is right, no gap" bar.

  (Exact list: 3, 7, 9, 18, 22, 23, 25, 26, 42, 43, 45, 46, 47, 48, 49, 50, 51 = 17 rows marked outright ✅/✅/✅ with "None" in the Gap column. Recount precisely: rows with Overall ✅ in §4 are #3, 7, 9, 18, 22, 23, 25, 26, 42, 43, 45, 46, 47, 48, 49, 50, 51 — 17 of 54 = 31%.)

• 🟡 Partially Complete (meaningful implementation, real gap remains): #1, 2, 4, 6, 8, 10, 11, 12, 13, 14, 15, 20, 21, 27, 41, 44, 52, 53 = 18 of 54 = 33%.

• 🔴 Missing (no meaningful implementation on either side): #5, 16, 17, 24, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 40, 54 = 17 of 54 = 31%.

• ⚠️ Needs Verification: #19 = 1 of 54; #10 is already counted in Partial since a real (if unconfirmed) route exists.

• 🔵 Not Applicable: #39 = 1 of 54.

(17 + 18 + 17 + 1 + 1 = 54 — the count reconciles.)

---

13. Priority Gap List

P0 — Critical

• Add permission guards to POST/PUT/DELETE /exams, POST/PUT/DELETE /questions, GET /questions, POST /exams/:id/questions[/random], POST/PUT /results, and certification CRUD (#1, 2, 4, 11–14, 20, 21, 41, 44) — currently any authenticated user can tamper with exam configuration, the question bank, and candidate results.
• Product decision: is online candidate exam-taking (#28–38) in scope at all? Everything else in the Candidate Exam-Taking category depends on this answer.
• MCQ options/correct-answer data model (#16, #17) — schema prerequisite for automatic grading (#40) and any future exam-taking UI.

P1 — High

• Exam question-type depth beyond ESSAY/CHOICE labels, if richer types are wanted (#15).
• Officer-initiated candidate assignment (#24).
• Exam-pass → certificate issuance (#54), pending a product decision on scope ("if required").
• Duration/timing enforcement (#6) — meaningful only once #28–38 are scoped.

P2 — Medium

• Admin-configurable attempt cap, if wanted beyond the current automatic/uncapped behavior (#8).
• Round out exam-event notification coverage (#53).
• Exam sections, if the product needs multi-part papers (#5).

P3 — Low

• Confirm/implement explicit question ordering (#19).
• Confirm exam-availability criteria (#10).
• Dedicated exam-history view (#52), if wanted beyond the existing tables.

---

14. Recommended Implementation Order

1. Backend permission fixes first. Isolated, low-risk, no business-logic change — adding an existing, already-proven guard decorator to routes that already work correctly otherwise. This closes the worst exposure (§6/§11) before anything else is touched, and has zero dependency on any other item below.
2. Product decision on candidate exam-taking scope. Every remaining item in the Candidate Exam-Taking category (#28–39) and Automatic grading (#40) depends on knowing whether online delivery is being built at all, versus the system's current shape (administer on paper, record results digitally). Building past this point before the decision risks the wrong thing.
3. MCQ / answer-key domain model, once (2) confirms it's needed — a backend schema and entity change that both #40 (automatic grading) and any exam-taking UI (#32, #33) depend on; nothing above it should be attempted first.
4. Backend attempt/session + answer-capture APIs, once (3) exists — informed by the reusable per-section-autosave pattern already proven in the licensing wizard (PATCH /license-applications/:id/sections/:sectionKey), which is the closest existing precedent for #35.
5. Frontend exam-taking flow (#27, 28, 31–39), once (4) has real endpoints to call.
6. Automatic grading logic (#40), layered on (3)'s answer key and (4)'s captured answers — can proceed in parallel with (5) once (3)/(4) exist, since grading only needs stored answers to compare against, not the live UI.
7. Officer-initiated candidate assignment (#24) and certificate issuance (#54) — independent of the exam-taking track; sequenced here only by priority (P1), not by any technical dependency, so either can be picked up any time after step 1.
8. Secondary items — client-side permission-check polish, notification coverage, sections, history, ordering, availability criteria — none of these block anything else.

---

15. Final Executive Summary

Current State

The system runs a complete, real administrative paper trail for examinations: create/configure an exam, build and quality-control a question bank, assemble a paper (manually or by random server-side draw), register candidates, take attendance, log incidents, enter marks by hand, run them through a four-stage review/approval/publication pipeline, and handle appeals. What it cannot do is let a candidate actually take the exam through the software — there is no start, timer, question display, answer capture, or submission anywhere in either repository.

Main Strengths

Retake derivation, the marking/moderation/approval/publication chain, attendance/incident logging, and candidate registration/eligibility are all genuinely well-built on both sides and should be preserved as-is (§9).

Main Gaps

The entire candidate exam-taking flow (§6); the MCQ options/correct-answer data model that automatic grading depends on; officer-initiated candidate assignment; exam-pass certificate issuance; and a cluster of exam-domain (and certification) write endpoints with no permission guard at all.

Biggest Exam Gap

The candidate exam-taking experience does not exist — nothing starts an attempt, runs a timer, captures an answer, auto-saves, or submits a completed exam, on either side of the stack. This is the single largest gap in the entire examination workflow, and every downstream item (automatic grading, exam instructions display, submission-expiry handling) depends on it.

Domain/Data Model Gaps

No exam-attempt/session entity, no candidate-answer storage, no question-option/correct-answer schema (§8). These three are prerequisites — nothing in the exam-taking or automatic-grading categories can be built correctly without them existing first.

Frontend Gaps

The entire exam-taking UI (#27–39); officer-initiated candidate roster management (#24); certificate issuance UI (#54); client-side permission gating on the several exam actions the backend leaves entirely open.

Backend Gaps

Missing permission guards on exam/question/result write routes and certification CRUD (§6/§11); entirely missing exam-attempt/session infrastructure, answer capture, automatic grading, and certificate issuance; no officer-initiated registration endpoint.

Critical Permission Gaps

Any authenticated user — including a portal applicant holding no staff position — can today, via direct API calls: create, edit, or delete an exam; create, edit, delete, or browse the full question bank (unapproved content included); assemble the live question set for an exam; and record or rewrite a candidate's result. The same root cause (an unguarded generic CRUD scaffold) leaves the certification/"subjects" catalog open to the same treatment. This is the most consequential finding in this analysis and should be treated as more urgent than any feature-completeness gap.

Recommended Next Step

Add the missing PermissionGuard decorators to the exam/question/result write routes and the certification CRUD controller. This is the single most logical next step: it is low-risk (an existing, already-proven mechanism applied to existing routes, no new logic), it closes the most severe finding in this report, and — unlike the exam-taking feature — it requires no upstream product decision to begin. (Not implemented here, per this task's read-only scope.)