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.htmlandapp.js: learning workspace with subtitles, progress, favorites, watch-later, and difficult-line tracking.admin.htmlandadmin.js: local admin page for adding, editing, replacing, and deleting materials.- Local user state in
localStorageunderspeaking-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, anddifficultcounts are zero.- Clicking those filters shows an empty state that asks the learner to log in before tracking personal learning data.
allandunstudiedstill 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
favoriteslist 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:
暂无素材。
- admin user:
- 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/videoslocalStoragekeyspeaking-lab-state-v1- existing user shape:
favoriteswatchLaterprogress
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:
- Open
http://127.0.0.1:8000/. - Confirm the dashboard overview appears.
- Confirm materials render as cards.
- Search by title, speaker, and tag.
- Click a category chip and confirm it combines with search.
- Log in as a normal user.
- Favorite a card from the home page and confirm the favorite count updates.
- Click the favorite filter and confirm only favorites show.
- Open a material, mark one line practiced and one line difficult, then return home.
- Confirm studied and difficult counts update after reload.
- Confirm clicking a card opens
study.html?video=<id>. - 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.