93 lines
6.6 KiB
Markdown
93 lines
6.6 KiB
Markdown
# V2 versus V1 and the rebuild brief
|
|
|
|
Source review on 2026-11-11, comparing `main` V1 at 7bd0a9a with local V2.
|
|
This distinguishes implementation from verification. Passing mocked AI tests does not
|
|
establish real-provider compatibility, and sampled desktop/mobile QA is not exhaustive.
|
|
|
|
## Original requirements
|
|
|
|
| Area | Current state |
|
|
| --- | --- |
|
|
| New architecture and UI | Rebuilt: React/Vite, Hono, built-in SQLite; distinct responsive light/dark design |
|
|
| Single administrator and public visitors | Implemented: secure local login, revocable links, isolated visitor progress |
|
|
| Classes and organization | Classes/folders, edit/move/search/delete, quiz/deck duplication; manual ordering and duplication are not equally exposed for every content type |
|
|
| Quizzes | MC/SATA, per-option explanations, question rationale, partial credit, practice/exam, shuffle, resume, missed review and history implemented |
|
|
| Flashcards | Decks, browse/self-assessment, persistent FSRS, reviews, undo and class/deck scoping implemented |
|
|
| Imports/templates/export | Preview/validation/editing, JSON/text bulk input, reusable templates and exports implemented |
|
|
| Documents | Required common formats, extraction/chunks/FTS search, optional provider OCR, private storage and AI generation implemented |
|
|
| AI providers and models | Five adapters, encrypted keys, discovery/manual models, routing/settings/usage; live provider verification remains |
|
|
| Integrated AI actions | Search/read content, weak-area generation, editable drafts, confirmed modifications implemented |
|
|
| ChatGPT account | No configured account OAuth. Hosted-client eligibility/approval remains unresolved; conventional API access is available |
|
|
| Docker/persistence/backups | Single-container image now builds and passes disposable runtime checks; Unraid proxy/volume validation remains |
|
|
| Accessibility and polish | Keyboard shortcuts, focus styles, reduced-motion rules, responsive layouts and state components exist; full keyboard/screen-reader audit remains |
|
|
|
|
The nursing-specific AI features are prompt-based tools using the same single/multi-choice
|
|
question engine. Dedicated interactive case-study/NGN question types and an adaptive NCLEX
|
|
exam engine are not implemented; the brief listed additional types as optional.
|
|
|
|
## V1 features that are not equivalent in V2
|
|
|
|
- **Named spaced-repetition sets:** V1 could collect selected decks into named sets with
|
|
independent schedules and new-card limits. V2 schedules each card once, with a global
|
|
daily new-card limit and deck/class/all review scopes. A practical simplification, but
|
|
it cannot reproduce separate course/exam review sets or independent per-set schedules.
|
|
- **Manual material order:** V1 supported drag/drop ordering of decks within material groups.
|
|
V2 class lists sort by recent update or title; the visible drag/drop is for file upload.
|
|
Some reorder APIs exist without matching UI. Quiz questions do have move-up/down controls.
|
|
- **Migration fidelity:** V2 imports source content, completed attempts and one selected
|
|
schedule per card. V1 interrupted StudyProgress sessions, named sets and their independent
|
|
schedules are not recreated. Historical reviewSnapshotJson is not consumed: imported
|
|
attempts reconstruct questions from current source content rather than preserving every
|
|
historical question version. Existing V1 share links are deliberately not reused.
|
|
|
|
These are not all mandatory requirements in the rebuild brief, but they matter when replacing
|
|
a V1 workflow. Extra visual effects should not obscure these functional tradeoffs.
|
|
|
|
## Issues found and addressed in this pass
|
|
|
|
- Card entrance utility overrode swipe-away CSS. Entrance and exit classes are now mutually
|
|
exclusive, restoring the intended grading transition.
|
|
- Added horizontal touch-to-grade after revealing a flashcard, while retaining vertical
|
|
scrolling. Browse uses learning/known; FSRS uses Again/Good. Desktop buttons/keys remain.
|
|
- Shuffle now rearranges only remaining cards, retaining completed cards and assessments.
|
|
Browser check confirmed the session stays at card 2/4 and 25% after shuffling.
|
|
- Review now remounts when its query scope changes, avoiding a stale deck queue when selecting
|
|
global Review from a scoped review screen.
|
|
- Note saves are serialized; navigation/read-mode waits for a successful save, and unsaved
|
|
changes trigger the browser's unload protection. Verified editing then immediately
|
|
navigating away and reopening retains the latest text.
|
|
|
|
## Rationale check requested by the owner
|
|
|
|
Created an isolated three-question quiz with a separate explanation on every option plus
|
|
each question's overall rationale. Through the actual internal browser, verified a correct
|
|
single-choice answer, an incorrect single-choice answer and partially correct SATA answer.
|
|
|
|
Practice reveals each option's explanation **under that option**, including unselected
|
|
distractors and missed correct options. The overall rationale follows that question's choices.
|
|
Results retain the same per-option/per-question grouping. Exam mode intentionally delays
|
|
feedback until submission. The stored option explanation field is `why`; a legacy import
|
|
with only a question-level rationale cannot invent separate option explanations.
|
|
|
|
Screenshot: ignored local `.test-data/rationale-check/correct-inline.png`.
|
|
|
|
## Remaining usability/feature priorities
|
|
|
|
1. Restore selected-deck named review collections if replacing that V1 workflow is important.
|
|
2. Expose consistent ordering and duplication controls across content types.
|
|
3. Make timed exams use an explicit wall-clock deadline. The current runner is an active-study
|
|
clock: it pauses when hidden, and server completion does not enforce a deadline.
|
|
4. Preserve shared quiz question snapshots if scores must remain stable across owner edits;
|
|
public saved sessions currently rebuild against the latest published quiz content.
|
|
5. Add better import reporting/preservation for V1 history and interrupted sessions.
|
|
6. Improve large scanned-document OCR: currently sent as one native vision/PDF request with
|
|
a 30 MB scanned-PDF limit and an output cap, rather than paginated OCR. Lexical retrieval
|
|
and sampled long-document generation are implemented; comprehensive textbook coverage
|
|
and semantic matching are not guaranteed.
|
|
7. Full offline private studying, rich-text WYSIWYG authoring, study-plan generation and
|
|
additional case/question types remain optional future enhancements.
|
|
|
|
No obvious missing basic flip/streak/quiz-answer feedback remains by source review. Visual
|
|
polish still needs targeted long-content/mobile/empty/error-state passes beyond the sampled
|
|
screens already checked. Prioritize those user-visible improvements over expanding a test
|
|
count for its own sake.
|