5.5 KiB
Speaking Lab Home Page v1 Design
Goal
Add a dedicated home page for browsing learning materials, so http://127.0.0.1:8000/ feels like a shareable product entry instead of opening directly inside the study workspace.
Current Context
Speaking Lab currently has:
index.html: the study page.app.js: study-page logic for loading videos, search, tags, subtitles, recording, favorites, watch-later, and learning progress.admin.htmlandadmin.js: admin material management./api/videos: returns material metadata, tags, video URLs, subtitles, and source type.- Local user state in
localStorage.
The current left-side material rail is useful inside the study page, but it is too narrow to work as the product home page.
Scope
Home Page v1 includes:
- Make
/open the new home page. - Move the current study experience to
study.html. - Add
home.htmlandhome.js. - Home page supports searching materials.
- Home page supports category filtering from material tags.
- Home page shows material cards in a responsive grid.
- Cards show an automatic preview cover when no real thumbnail exists.
- Cards show title, speaker/source, tags, subtitle languages, and learning progress.
- Clicking a card opens
study.html?video=<id>. - The study page reads
?video=<id>and opens that material first. - Admin entry remains available for admin users.
Home Page v1 excludes:
- Uploading custom thumbnails.
- Automatically extracting thumbnails from video files.
- Pagination.
- Advanced sorting.
- Multi-level category management.
- Backend search endpoints.
- Server-side user authentication.
Page Routing
Routes after this feature:
/
Shows the new home page.
/study.html
Shows the current learning workspace.
/study.html?video=<id>
Opens the learning workspace and selects the requested material.
/admin.html
Shows the existing admin page.
Home Page Layout
The home page uses a product-library layout:
- Top bar:
Speaking Lab- Search input
- Login/register or current user
- Admin link shown only for admin users
- Category row:
全部- One chip per tag from loaded materials
- Main content:
- Responsive grid of material cards
- Empty state when no materials match
The home page should be practical and product-like, not a marketing landing page. It should prioritize finding and opening materials.
Material Card
Each card displays:
- Preview cover area.
- Title.
- Speaker/source.
- Tags.
- Subtitle language summary, for example
英文 / 中文. - Learning progress summary, for example
已练 2/15 · 13%or看到 02:04.
Clicking anywhere on a card opens:
study.html?video=<id>
Preview Cover Strategy
Home Page v1 uses generated CSS preview covers instead of real video thumbnails.
Reason:
- Local and remote videos may not be safe or easy to screenshot in the browser.
- Cross-origin video URLs may block frame extraction.
- A generated cover is reliable and fast for the prototype.
Generated cover contents:
- Large short title or initials.
- First tag as a category badge.
- Subtle color variant based on material ID.
Future extension:
- Add a backend
thumbnail_urlfield. - Allow admin upload of cover images.
- Show real thumbnail when available, generated cover as fallback.
Search And Category Behavior
Search matches:
- Title.
- Speaker/source.
- Description.
- Tags.
Category filtering:
全部shows all materials.- Clicking a tag chip filters cards whose tags include that tag.
- Search and category filters combine.
Study Page Behavior
The current study page becomes study.html.
Changes:
- It keeps existing playback, subtitles, recording, progress, favorites, and admin entry behavior.
- On load, it checks
URLSearchParamsforvideo. - If the requested video exists, it selects that video.
- If the requested video does not exist, it falls back to existing active-video behavior.
The study page may keep the left material rail for quick switching during learning.
State And Data
Home page uses:
GET /api/videosfor materials.- The same
speaking-lab-state-v1localStorage key for users and progress.
No new database table is required.
No backend API change is required for Home Page v1.
Error Handling
If /api/videos fails:
- Show a clear local error state.
- Home page may show demo/sample materials only if the study page already uses those as fallback.
If no materials exist:
- Show an empty state that points admin users to
admin.html. - Non-admin users see a simple “暂无素材” state.
If study.html?video=<id> references a missing material:
- Select the first available material.
- Do not crash.
Testing
Automated checks:
node --check home.jsnode --check app.js- Existing helper tests still pass.
Manual/browser verification:
- Open
http://127.0.0.1:8000/. - Confirm the home page appears, not the study workspace.
- Confirm materials render as cards.
- Confirm search filters by title/source/tag.
- Confirm category chips filter cards.
- Confirm each card has a generated preview cover.
- Click a card.
- Confirm
study.html?video=<id>opens and selects that material. - Confirm
admin.htmlstill works. - Confirm logged-in admin users can see an admin entry on the home page.
Future Extensions
Good follow-up features:
- Upload custom thumbnail in admin page.
- Add
我的学习section on the home page. - Add sorting by recently studied, newest, or most practiced.
- Add collections or curated playlists.
- Move search/filter to backend when the library becomes large.