109 lines
7 KiB
Markdown
109 lines
7 KiB
Markdown
# Study Desk V2 — progress and resume notes
|
||
|
||
Updated 2026-11-11. Branch: **v2**. Original V1: **main**, preserved at `7bd0a9a`.
|
||
The owner authorized publishing progress and `v2` now tracks Forgejo `origin/v2`.
|
||
No production deployment has been performed.
|
||
|
||
## Product and architecture
|
||
|
||
This is a rebuilt app using React + Vite + TypeScript, Hono/Node HTTP server, built-in
|
||
`node:sqlite`, SQLite FTS5, local document storage and a persistent document queue. One process,
|
||
one data volume, one administrator. Anonymous visitors get public read-only shares and
|
||
browser-local study progress. Administrator progress stays server-side.
|
||
|
||
The previous agent implemented the core product and committed it through `c549c34`:
|
||
classes/folders, CRUD/duplicate/move/search, quiz sessions/results/history, FSRS flashcards,
|
||
imports/exports/templates, documents/extraction/retrieval/OCR, provider adapters, editable
|
||
AI drafts, tool-based assistant actions, sharing, analytics and the responsive themed UI.
|
||
User feedback fixes are already included: larger clickable flashcards, arrow keys, streak
|
||
effects, persistent review sidebar, live quiz score, shared quiz timers, SATA credit details,
|
||
type-grouped materials, copyable import instructions and assistant library links.
|
||
|
||
## Current continuation
|
||
|
||
- Confirmed original 162 tests pass; sandbox networking initially blocked the mock provider.
|
||
- Added encryption-key corruption/missing-key refusal, static-path boundary validation,
|
||
private embedded-media authorization and share-revocation checks.
|
||
- Full backups include the generated encryption key and fail on unreadable files.
|
||
- Added backup restore, media authorization, key durability, static-path traversal, V1 import and failed-migration
|
||
rollback tests. The new V1 test checks source bytes are unchanged and state is preserved.
|
||
- Added Dockerfile, Compose, .dockerignore, README and deployment/migration/AI documentation.
|
||
- Updated obsolete ChatGPT subscription wording after checking official documentation:
|
||
account integration exists for eligible clients, but hosted app approval for this private
|
||
Unraid web deployment has not been established. API integration remains the working path.
|
||
- Terra completed isolated UI/workflow and visual QA; see results below.
|
||
- Guarded quiz exit/submission when the latest save failed, and prevented repeated automatic
|
||
timer submissions after a failed request.
|
||
- Preserved the V1 card elapsed-days scheduling field during import.
|
||
|
||
## Verification status
|
||
|
||
Baseline: 162 tests passed, TypeScript passed and production web/server builds passed.
|
||
Added six regression tests. Full `npm run check` passes: **168 tests**, TypeScript and both
|
||
production builds. Tests were run with loopback access for the mock provider.
|
||
|
||
The earlier agent manually exercised quiz completion/results, flashcards, streak effects,
|
||
mock AI generation through the assistant, editable drafts, and a 375px home page without
|
||
horizontal overflow. Treat these as historical evidence; record Terra's fresh results below.
|
||
|
||
Docker Desktop is now installed. Image build and a disposable non-root container passed
|
||
login, document/card persistence across restart, full-backup ZIP, anonymous sharing and
|
||
private API denial. Still unverified: Unraid filesystem permissions/proxy, paid-provider
|
||
inference and real ChatGPT OAuth/eligibility. The installable app caches its shell, not private study data;
|
||
full offline administrator study is not implemented.
|
||
|
||
## Remaining work
|
||
|
||
1. On Unraid later: execute the deployment/restore checklist in docs/DEPLOYMENT.md.
|
||
2. With owner-supplied provider connections: verify live discovery, streamed chat, generation,
|
||
OCR and task routing. No real-provider calls should be inferred from mock test results.
|
||
3. Future optional work: approved ChatGPT account OAuth, more robust offline studying and
|
||
semantic embeddings (current retrieval is lexical FTS5).
|
||
|
||
## Resume safely
|
||
|
||
1. `git status --short`, read this file and recent commits. Do not overwrite user changes.
|
||
2. The ignored `.env` currently selects `.data/`, containing dev/demo content that the user
|
||
has tried. Never print its secrets or reset/seed it casually. Use a new `.test-data/...`
|
||
directory and a separate port for destructive QA.
|
||
3. `npm.cmd run check` (tests require localhost networking for their mock AI server).
|
||
4. `npm.cmd run dev` for Vite + API, or `npm.cmd run build` then `npm.cmd start` for the built
|
||
app. See README and .env.example. All automated test databases are disposable copies.
|
||
5. Keep focused commits on `v2`. The owner has now authorized pushing progress to this branch;
|
||
Git Credential Manager works. Never force push or publish/deploy to production implicitly.
|
||
|
||
## V1 comparison and follow-up usability work
|
||
|
||
See `docs/V2-COMPARISON.md` for the requirement matrix, V1 differences and remaining priorities.
|
||
Fixed the flashcard entrance/exit CSS conflict; restored touch grading and shuffle-remaining;
|
||
reset review queues on scope changes; serialized note autosaves, protected navigation with
|
||
unsaved edits and added an explicit retry action. Verified a note survives immediate
|
||
navigation and reload, and shuffling keeps browse progress at 2/4 rather than restarting.
|
||
|
||
The owner's rationale check passed using a synthetic three-question quiz with per-option
|
||
explanations: correct, incorrect and partial SATA feedback all show explanations inline under
|
||
their options. Results group explanations with each question. Screenshot is ignored at
|
||
`.test-data/rationale-check/correct-inline.png`. The temporary test server is stopped after QA.
|
||
|
||
## Fresh UI QA findings
|
||
|
||
Terra tested through Edge in an isolated volume on port 3731. Observed successful login,
|
||
class creation, quiz/question editing, practice start, save/exit, resume, answer check and
|
||
100% results; deck/card creation, browse flip, FSRS review, pasted question import; desktop
|
||
and emulated 400×933 mobile layouts in both themes. No obvious clipping or overlap observed
|
||
on those screens. The test server was stopped and the temporary password removed.
|
||
|
||
Visual finding: secondary labels appeared faint, particularly in dark mode. Adjusted the
|
||
shared `ink-3` colors. Computed WCAG contrast against paper/surface/sunken backgrounds:
|
||
light now **5.15 / 5.38 / 4.76** (previously 3.48 / 3.63 / 3.21); dark now
|
||
**7.42 / 6.86 / 7.71**. These ratios cover these token pairs, not a full accessibility audit.
|
||
|
||
Screenshots remain ignored under `.test-data/ui-terra/`: desktop-dark-quiz.png,
|
||
desktop-light-quiz.png, mobile-dark-quiz.png, mobile-light-quiz.png and mobile-light-session.png.
|
||
Post-fix Terra recheck: desktop light/dark screenshots show improved secondary-text legibility
|
||
(`postfix-dark-desktop.png`, `postfix-light-desktop.png`). An Edge InPrivate visitor opened
|
||
the isolated shared quiz without login, completed practice, saw its rationale and reached
|
||
100% results. Shared-deck UI, long-label layout stress tests and post-fix mobile contrast were
|
||
not revisited in this follow-up. Public deck data isolation/revocation is covered by API tests.
|
||
No known functional failures were found in the UI paths exercised. This is sampled QA, not
|
||
an exhaustive audit of every layout and browser. Terra's isolated server is stopped.
|