fix(lms): Gate course completion and certificates on graded assignments

[jeromehardaway]

Problem

POST /api/lms/progress computed course completion from lesson progress alone (completedLessons / totalLessons). At 100% it marked the enrollment COMPLETED and auto-generated + emailed a verifiable certificate without ever consulting the Assignment/Submission models — a learner could earn a certificate without submitting any graded work.

Solution

• When lesson progress reaches 100%, the route now fetches all assignments for the course along with the user's GRADED submissions (one query via a filtered submissions relation select). All assignments of a course are treated as required.
• The COMPLETED enrollment transition and the certificate generation/email path only run when every assignment has a GRADED submission. Courses with zero assignments keep current behavior.
• Lesson progressPercentage (the progress bar value) is unchanged; only the completion transition gains the gate.
• Outstanding requirements are surfaced in the response as courseProgress.pendingAssignments (count + titles) so the UI can display what remains.
• Added an @swagger block for the route (it previously had only a plain JSDoc comment).

Verification

• npx vitest run __tests__/pages/api/lms/progress.test.ts — 5 new tests pass: ungraded assignment blocks completion/certificate, non-GRADED submission blocks, all-GRADED completes and issues certificate, zero-assignment course keeps current behavior, below-100% lessons never query assignments.
• npm test — 42 files / 389 tests pass.
• npm run typecheck — 7 pre-existing errors in unrelated __tests__/pages/api/j0di3/* files; identical count on clean master, zero introduced by this change.
• npm run lint — 20 pre-existing findings, identical count on clean master; both changed files are clean apart from pre-existing any annotations in untouched route code.
• npm run build — compiles; /api/lms/progress builds and the generated swagger spec picks up the new annotation (regenerated public/swagger-spec.json not committed, matching existing practice).

Follow-up

• No existing frontend component consumes the POST /api/lms/progress response (courseProgress is referenced nowhere outside the route), so no UI wiring was done; pendingAssignments is ready for whichever component adopts it.
• Grading an assignment (submissions flow) does not re-trigger this route, so a learner who finishes lessons before grading completes will flip to COMPLETED on their next progress update rather than at grading time. Worth a separate issue if certificates should issue immediately upon final grading.

Closes #1149

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
vets-who-code-app	Ready	Preview, Comment	Jun 11, 2026 4:46pm