Files
speaking-practice/docs/superpowers/specs/2026-06-02-speaking-lab-home-dashboard-design.md
T
2026-06-03 00:34:42 +08:00

6.8 KiB

Speaking Lab Home Dashboard v1 Design

Goal

Upgrade the existing home page from a simple material grid into a learning dashboard that feels useful as a shareable product prototype.

The dashboard should help a learner answer three questions quickly:

  • What can I study?
  • What have I already studied?
  • Which saved or difficult materials should I return to?

Current Context

Speaking Lab currently has:

  • index.html: home page with search, tag chips, material cards, and admin link.
  • home.js: loads /api/videos, renders generated covers, and reads local user progress.
  • study.html and app.js: learning workspace with subtitles, progress, favorites, watch-later, and difficult-line tracking.
  • admin.html and admin.js: local admin page for adding, editing, replacing, and deleting materials.
  • Local user state in localStorage under speaking-lab-state-v1.
  • Material metadata from FastAPI and SQLite through GET /api/videos.

No README changes are part of this upgrade.

Scope

Home Dashboard v1 includes:

  • Add a left overview panel on the home page.
  • Show dashboard metrics:
    • total materials
    • studied materials
    • unstudied materials
    • favorite materials
    • materials with difficult lines
  • Add status filters:
    • all
    • studied
    • unstudied
    • favorites
    • difficult
  • Keep existing search and tag/category filters.
  • Combine status, search, and tag filters.
  • Upgrade material cards with:
    • favorite toggle
    • sentence count
    • practiced percentage
    • difficult-line count
    • subtitle language summary
    • latest progress hint
  • Keep card click behavior opening study.html?video=<id>.
  • Keep admin link visible only to local admin users.

Home Dashboard v1 excludes:

  • README updates.
  • Real backend accounts.
  • Server-side learning progress.
  • Uploading custom thumbnails.
  • Extracting thumbnails from video files.
  • Backend search or filter endpoints.
  • Calendar/check-in features.
  • Separate pages for favorites or difficult sentences.

Layout

The home page becomes a two-column dashboard on desktop:

  • Left column:
    • product name and compact learning overview
    • metric buttons for total, studied, unstudied, favorites, and difficult
  • Right column:
    • heading and primary material grid
    • search and category controls
    • status text
    • material cards

On smaller screens, the overview panel stacks above the grid.

The design should stay practical and work-focused. It should look like a learning tool, not a marketing landing page.

Filters

Dashboard status filters are represented by metric buttons in the overview panel.

Filter rules:

  • all: every material.
  • studied: material has practiced lines or playback progress.
  • unstudied: material has no practiced lines and no playback progress.
  • favorites: material ID is in the current user's favorites.
  • difficult: material progress has at least one difficult line.

If the visitor is not logged in:

  • studied, favorites, and difficult counts are zero.
  • Clicking those filters shows an empty state that asks the learner to log in before tracking personal learning data.
  • all and unstudied still work from the material list.

Search and tag filters combine with the active status filter.

Dashboard Metrics

Metrics are calculated in the browser from loaded videos and local user state.

Definitions:

  • total materials: number of videos loaded from /api/videos.
  • studied materials: materials with currentTime > 1, activeLineIndex > 0, or at least one practiced line.
  • unstudied materials: total minus studied materials for the current user.
  • favorite materials: current user's favorites list intersected with loaded videos.
  • difficult materials: materials whose progress has at least one difficult line.

Metrics should update immediately after:

  • login or logout
  • clicking a favorite button on a card
  • changing filters
  • reloading materials

Study-page progress changes are already stored in localStorage. The home page reads that state when it loads.

Material Cards

Each card displays:

  • generated preview cover
  • title
  • speaker/source
  • tags
  • subtitle language summary
  • sentence count
  • practiced percentage
  • difficult-line count
  • progress hint, such as 已练 3/12 · 25% or 看到 02:04
  • favorite button

Favorite behavior:

  • Clicking the favorite button toggles the current video in the user's favorites.
  • The click does not open the study page.
  • If no user is logged in, show a short alert asking the learner to log in first.

Card navigation:

  • Clicking the non-button area opens study.html?video=<id>.

Empty States

Empty states should explain the current filter result.

Examples:

  • No materials at all:
    • admin user: 还没有素材,去后台添加第一个素材。
    • normal visitor: 暂无素材。
  • Search or category has no matches:
    • 没有匹配的素材。
  • Personal filter without login:
    • 登录后可以查看你的学习记录。
  • Favorites filter with no favorites:
    • 还没有收藏素材。
  • Difficult filter with no difficult materials:
    • 还没有标记难句。

State And Data

No backend changes are required.

Home Dashboard v1 uses:

  • GET /api/videos
  • localStorage key speaking-lab-state-v1
  • existing user shape:
    • favorites
    • watchLater
    • progress

Helper logic in home.js should stay local to the home page. Shared backend schema is unchanged.

Error Handling

If /api/videos fails:

  • show the API error or a clear fallback message
  • clear the grid
  • avoid crashing metric rendering

If localStorage is malformed:

  • fall back to an empty user state
  • continue rendering materials

If a progress entry refers to a deleted material:

  • ignore it in dashboard metrics

Testing

Automated checks:

node --check home.js
node --check app.js
node --check admin.js
python -m py_compile backend\main.py backend\db.py
node tests\progress-helpers.test.mjs
node tests\admin-file-input.test.mjs

Manual browser checks:

  1. Open http://127.0.0.1:8000/.
  2. Confirm the dashboard overview appears.
  3. Confirm materials render as cards.
  4. Search by title, speaker, and tag.
  5. Click a category chip and confirm it combines with search.
  6. Log in as a normal user.
  7. Favorite a card from the home page and confirm the favorite count updates.
  8. Click the favorite filter and confirm only favorites show.
  9. Open a material, mark one line practiced and one line difficult, then return home.
  10. Confirm studied and difficult counts update after reload.
  11. Confirm clicking a card opens study.html?video=<id>.
  12. Confirm an admin user still sees the admin link.

Future Extensions

Good follow-up features after this:

  • Upload custom cover images in the admin page.
  • Add a dedicated difficult-sentence review page.
  • Add a daily learning/check-in calendar.
  • Move user progress to SQLite when preparing for shared accounts.
  • Add real authentication before deploying publicly.