Adopt shared step-by-step inline homework reader

[alexeygrigorev]

Adopt shared step-by-step inline homework reader

Status: groomed
Tags: courses, frontend, accessibility, enhancement, P1
Depends on: DataTalksClub/community-base#292 and a tagged community-base release containing homework_steps
Related: AI-Shipping-Labs/website#1778; #415

Normative sources

• DTC course and assessment policy: _docs/specs/04-courses-and-cohorts.md, especially Preserved learner behavior and cohort ownership.
• Canonical route: _docs/specs/02-url-link-seo-compatibility.md and _docs/specs/open-decisions.md §5.
• Page/navigation design: _docs/design/specs/unit-page.md and _docs/design/specs/learning-flow-ux.md.
• Shared stepper contract: DataTalksClub/community-base docs/plan/phase-5.md §C5.2i and community-base#292.
• Current DTC submission contract: courses/views/homework.py, homework_post_preview.py, homework_submission.py, homework_submission_fields.py, and courses/templates/homework/.

Scope

DTC adapter and learner page

• Add a DTC site adapter for the shared community_base.homework_steps app over the homework models and submission path currently serving DTC: courses.models.homework.Homework, Question, Submission, Answer and courses.views.homework_submission. community_base.coursework is installed for migration preparation but does not currently serve this learner route. Do not wait for D5.2 Freeze weekend: DTC courses cutover and self-paced mode #415. When D5.2 Freeze weekend: DTC courses cutover and self-paced mode #415 later moves DTC to package coursework, preserve this reader's adapter contract and learner behavior.
• Use the existing canonical /courses/<family>/<identifier>/homework/<homework-slug> page and DTC's submission-page shell, breadcrumbs, module rail, instructions link, deadline/status notices and course navigation. The homework remains one cohort-owned assignment; Introduction, the ordered question steps, and Review & submit are page sections/steps, not new Course, Module, Unit, Homework, or Question rows. Preserve legacy route aliases and existing external links.
• For a homework with question rows and state=OPEN, show Introduction → one step per question → Review & submit. Use the authored number of questions, not a fixed six. Introduction gives the existing homework description, available instructions and instructions link. Each question step presents its Question.text, answer options and its bound control. Do not infer a question/answer binding or correctness from Markdown headings. Review shows the latest saved answers, clearly marks blanks, and hosts all currently enabled DTC submission fields. The final action is labelled Submit homework or Update submission as appropriate. The only final-submit control is on Review.
• Keep step URLs bookmarkable on the canonical page with ?homework_step=intro, ?homework_step=<stable-question-id>, and ?homework_step=review; use source_question_id where present and a stable q-<question.pk> fallback for site-managed questions. A bare URL starts at Introduction for a first visit and can offer the next unfinished step for a returning learner. An invalid/stale step safely returns to a valid step with an explanation. Preserve the cohort route and browser Back/Forward behavior.
• Answer types are existing DTC MC, CB, FF, and FL; preserve numeric/free-form validation and the existing choice values. Map source-managed source_option_ids to the current option indices only at the existing final-submit boundary; DB-managed options use a stable question-local index. Reordering questions must not attach a draft answer to another question. Do not expose encrypted or plain correct-answer data before existing reveal policy permits it.

Draft and submit behavior

• An authenticated learner can save one answer at a time, including clearing it, as a server draft scoped to that learner and the exact cohort-owned homework. Auto-save after input settles; Save & continue waits for a successful save. Show saving, saved, retryable failure and stale-tab conflict states without claiming an unsaved answer was saved. Refresh, navigation away/back, or a second signed-in device restores the draft. Full form POST navigation works without JavaScript.
• A draft write validates the server-resolved homework, learner, question and option membership, value shape/size, CSRF token, eligibility and draft revision. A forged assignment or a question from another homework never reads or changes a draft. A stale tab cannot overwrite a newer answer. Draft reads/writes are private and must not create an Enrollment, Submission or Answer; change submitted_at or scores; or call email, notification, event, scoring, or submit callbacks.
• When an existing submission has no draft, prefill all steps and enabled final fields from its saved answers/metadata, then seed editing without changing that submission. The final action rechecks current permissions and Homework.state and reads the latest complete draft; it calls DTC's current final submission path once, including its validation and full answer set. Only success clears the draft. A validation error, closed state, conflict, or server failure retains the learner's work and displays a usable explanation.
• DTC accepts a late final submission while Homework.state=OPEN; the displayed due date is not an independent rejection gate. CLOSED and SCORED keep the current no-submit behavior. Preserve DTC question scoring and answer reveal timing, statistics, partial/blank answer rules, submit/update semantics, one submission per learner, any enrollment created at final submit, and the existing confirmation email and callbacks.
• Preserve every currently enabled final field and its validation: required homework URL when enabled, learning-in-public links/cap/duplicate checks, time spent on lectures/homework, cohort problems/comments, and FAQ contribution URL. Save these in the draft/review as host-defined final fields; do not silently reset unchanged values during a one-question edit or resubmission.

Compatibility and limits

• Homework with no questions, existing scored/closed result pages, public correct-answer display, statistics/submissions pages, and the current non-step form continue to work. Keep the all-in-one form reachable at the same homework route with ?homework_view=classic; its existing POST remains accepted. After a successful classic POST, clear or refresh any older step draft so returning to the stepper cannot silently replace newer submitted answers. Existing submissions require no destructive migration. Keep the fallback page usable if an assignment cannot safely build stable step bindings.
• This issue changes DTC site integration and page presentation. The package owns generic draft persistence, revision protection, step navigation and accessibility in Build the offline Docs source parser and fail-closed parity census #292. No AISL content, DTC content import schema, Studio workflow, scoring policy, or D5.2 Freeze weekend: DTC courses cutover and self-paced mode #415 data cutover is in scope.

Acceptance criteria

• A signed-in learner reaches the stepper from the existing cohort homework link and sees Introduction, exactly one step for each stored question in order, then Review & submit, inside the DTC page shell and module navigation at desktop and mobile widths.
• Each supported question type displays the right prompt, options/control, and current answer; stable question identities survive question reorder or re-import, and source option IDs survive source option reorder without misbinding saved values.
• A learner saves Q1, leaves, refreshes or uses another signed-in session, then resumes the exact answer; editing/clearing Q1 does not alter Q2. Save failures and stale-tab conflicts retain the typed input and offer recovery.
• A draft read/write denies anonymous, cross-learner, forged-homework, forged-question, invalid-option and stale-revision requests. The draft response never reveals answer keys or scores.
• Draft activity creates no enrollment, submission, answer row, score, submission event, confirmation email or notification. Review shows all current answers and blanks, then final submit alone calls the current DTC submission path once.
• Review contains every enabled DTC final field, restores saved values on edit, validates them with current rules, and preserves them on a one-question update. A successful submit/update has the same stored answers, metadata and email/callback behavior as the existing form.
• DTC's OPEN gate controls submission even when the due date has passed; a stale Review page is rejected after the state changes to CLOSED/SCORED, with its draft retained. Scored answer reveal and public statistics stay governed by current DTC policy.
• An existing submission opens prefilled, remains unchanged during drafting, and updates only after explicit final submit. Current canonical/legacy homework links, no-question pages, closed/scored pages, ?homework_view=classic, old non-step POST and historical submissions remain usable; a classic submit invalidates any stale step draft.
• The tagged package pin and lockfile are updated; focused DTC Django and Playwright user-flow checks pass. Community-base and AISL consumer results are reported separately as required by the shared package change, without representing a package test as a DTC result.

Browser scenarios

Learner completes a six-question assignment

Given an accessible OPEN cohort homework with six stored questions and no draft, when a signed-in learner opens its existing course link, traverses Introduction and Q1–Q6, and reaches Review, then each step has only its own answer control, navigation works by keyboard/Back/Forward, the DTC breadcrumb/module context remains, and no submission exists before final click.

Learner resumes and corrects work

Given Q1 and Q2 are drafted, when the learner leaves, returns, changes Q1 and clears Q2, then Review shows the new Q1 value and Q2 as blank, the server draft survives refresh, and no score or confirmation email exists.

Learner recovers from failure and a second tab

Given one tab has a newer saved answer, when another tab saves an older revision or a save request fails, then the typed answer remains visible with a conflict/retry path and Save & continue stays on that step until a successful save.

Learner submits with DTC metadata

Given an OPEN homework with every optional field enabled and a prior submission, when the learner changes one question, reviews the complete answer set/metadata and submits, then the existing submission is updated once, unchanged answers/fields survive, validation errors remain editable, and the usual confirmation callback runs only on success.

Late, closed and scored homework

Given a draft after the displayed due date, when state remains OPEN, then final submit follows DTC's late-submission policy. If state becomes CLOSED before final click, the submit is rejected and the draft stays. When SCORED, the current result and answer-reveal view remains available under its existing access rules.

Visitor and legacy homework

Given an anonymous visitor, a homework with no questions and an older submission/form client, when each opens or posts the existing homework URL, then the visitor gets the existing sign-in/preview treatment without draft access, the no-question page remains usable, and the old final POST still follows its current validation and confirmation behavior.

[alexeygrigorev]

Grooming Complete

Ready for engineering after community-base #292 ships a tagged homework_steps release. DTC will use a site adapter over its currently serving courses.* homework models and submission path, so #415 is related future cutover work rather than a blocker. The issue covers step navigation, resumable drafts, existing DTC metadata/scoring/reveal/late-submit/email rules, classic-form compatibility, and browser/security scenarios. No code or tests were changed during grooming.

[alexeygrigorev]

Development deployment status for the merged homework release: exact-source CI passed for 34c75cc8, but the development deploy stopped at the schema migration (exit 21) before either service changed. The release is not deployed to development or production.

The blocker is the historical site-to-package events database cutover tracked in #412. A synthetic PostgreSQL rehearsal from the last green dev schema reproduces a table collision at events.0001_provisional_initial. Do not retry the deploy or run rebuild_events_tables --apply until #412's prerequisite and row-preserving cutover gates are complete. The exact live traceback needs the scoped CloudWatch read grant in aws-infra #59.