19 KiB
Speaking Lab Home Dashboard v1 Implementation Plan
For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (
- [ ]) syntax for tracking.
Goal: Upgrade the home page into a learning dashboard with overview metrics, status filters, richer material cards, and home-page favorite toggles.
Architecture: Keep the feature entirely in the existing frontend home page. index.html owns the dashboard markup, home.js owns browser-side metric/filter/card behavior using /api/videos plus existing localStorage state, and styles.css owns the responsive layout and card styling. No backend, README, or deployment changes are required.
Tech Stack: Vanilla HTML, CSS, JavaScript, FastAPI /api/videos, browser localStorage.
File Structure
- Modify
F:\ooo\speaking-practice-local\index.html: add dashboard overview panel and metric button containers. - Modify
F:\ooo\speaking-practice-local\home.js: add active status filter, dashboard metrics, personal filter empty states, favorite toggles, and richer card metadata. - Modify
F:\ooo\speaking-practice-local\styles.css: style the two-column dashboard, metric buttons, upgraded cards, and mobile stacking. - Do not modify
F:\ooo\speaking-practice-local\README.md. - Do not modify backend files unless verification exposes an unrelated syntax issue.
Task 1: Add Home Dashboard Markup
Files:
-
Modify:
F:\ooo\speaking-practice-local\index.html -
Step 1: Replace the home main layout
Replace the current <main class="home-shell">...</main> block with this structure:
<main class="home-shell">
<aside class="home-dashboard" aria-label="学习概览">
<div class="home-dashboard-title">
<span>学习概览</span>
<strong id="homeDashboardUser">本地学习</strong>
</div>
<div id="homeMetricFilters" class="home-metrics"></div>
</aside>
<section class="home-library">
<div class="home-heading">
<div>
<h2>素材库</h2>
<p>搜索素材,按分类和学习状态继续练习。</p>
</div>
<a class="primary-link" href="./study.html">进入学习页</a>
</div>
<div id="homeCategoryFilters" class="home-categories"></div>
<div id="homeStatus" class="home-status"></div>
<div id="homeGrid" class="home-grid"></div>
</section>
</main>
- Step 2: Verify the markup has all IDs needed by JavaScript
Run:
rg -n "homeDashboardUser|homeMetricFilters|homeCategoryFilters|homeStatus|homeGrid" index.html
Expected: each ID appears exactly once.
Task 2: Implement Dashboard Metrics And Filters
Files:
-
Modify:
F:\ooo\speaking-practice-local\home.js -
Step 1: Add new DOM references and status state
Extend the els object with:
dashboardUser: document.querySelector("#homeDashboardUser"),
metricFilters: document.querySelector("#homeMetricFilters"),
Add this state next to activeTag:
let activeStatus = "all";
- Step 2: Update render flow
In renderHome(), call renderDashboard() before categories are rendered:
function renderHome() {
renderDashboard();
renderCategories();
const filtered = getFilteredVideos();
const emptyMessage = getEmptyMessage(filtered);
els.status.textContent = filtered.length ? `${filtered.length} 个素材` : emptyMessage;
els.grid.innerHTML = "";
if (!filtered.length) return;
const fragment = document.createDocumentFragment();
filtered.forEach((video) => {
fragment.appendChild(createVideoCard(video));
});
els.grid.appendChild(fragment);
}
- Step 3: Add dashboard rendering helpers
Add these functions below renderCategories():
function renderDashboard() {
const user = getCurrentUser();
const metrics = calculateDashboardMetrics(user);
els.dashboardUser.textContent = user ? user.email : "登录后记录进度";
els.metricFilters.innerHTML = "";
getMetricItems(metrics).forEach((item) => {
const button = document.createElement("button");
button.type = "button";
button.className = `home-metric${activeStatus === item.key ? " active" : ""}`;
button.dataset.status = item.key;
button.innerHTML = `
<span>${item.label}</span>
<strong>${item.value}</strong>
<small>${item.hint}</small>
`;
button.addEventListener("click", () => {
activeStatus = item.key;
renderHome();
});
els.metricFilters.appendChild(button);
});
}
function getMetricItems(metrics) {
return [
{ key: "all", label: "当前素材", value: metrics.total, hint: "可学习内容" },
{ key: "studied", label: "已学", value: metrics.studied, hint: "有学习记录" },
{ key: "unstudied", label: "未学", value: metrics.unstudied, hint: "还未开始" },
{ key: "favorites", label: "已收藏", value: metrics.favorites, hint: "收藏的视频" },
{ key: "difficult", label: "难句素材", value: metrics.difficult, hint: "含难句标记" },
];
}
function calculateDashboardMetrics(user) {
const loadedIds = new Set(videos.map((video) => String(video.id)));
const studied = videos.filter((video) => hasStudyProgress(user, video.id)).length;
const favoriteIds = new Set((user?.favorites || []).map(String));
const favorites = [...favoriteIds].filter((id) => loadedIds.has(id)).length;
const difficult = videos.filter((video) => getVideoProgress(user, video.id).difficultLineIndexes.length > 0).length;
return {
total: videos.length,
studied,
unstudied: Math.max(0, videos.length - studied),
favorites,
difficult,
};
}
function hasStudyProgress(user, videoId) {
if (!user) return false;
const progress = getVideoProgress(user, videoId);
return progress.currentTime > 1
|| progress.activeLineIndex > 0
|| progress.practicedLineIndexes.length > 0;
}
- Step 4: Extend filtering
Replace getFilteredVideos() with:
function getFilteredVideos() {
const query = els.searchInput.value.trim().toLowerCase();
const user = getCurrentUser();
return videos.filter((video) => {
const tags = normalizeTags(video.tags);
const matchesTag = activeTag === "全部" || tags.includes(activeTag);
const matchesStatus = matchesStatusFilter(video, user);
const haystack = [video.title, video.speaker, video.description, tags.join(" ")]
.join(" ")
.toLowerCase();
return matchesTag && matchesStatus && (!query || haystack.includes(query));
});
}
function matchesStatusFilter(video, user) {
if (activeStatus === "all") return true;
if (activeStatus === "studied") return hasStudyProgress(user, video.id);
if (activeStatus === "unstudied") return !hasStudyProgress(user, video.id);
if (activeStatus === "favorites") return Boolean(user?.favorites.map(String).includes(String(video.id)));
if (activeStatus === "difficult") return getVideoProgress(user, video.id).difficultLineIndexes.length > 0;
return true;
}
- Step 5: Add empty-state messaging
Add this function below the filtering helpers:
function getEmptyMessage(filtered) {
const user = getCurrentUser();
const query = els.searchInput.value.trim();
if (!videos.length) {
return isAdmin(user) ? "还没有素材,去后台添加第一个素材。" : "暂无素材。";
}
if (!user && ["studied", "favorites", "difficult"].includes(activeStatus)) {
return "登录后可以查看你的学习记录。";
}
if (activeStatus === "favorites") return "还没有收藏素材。";
if (activeStatus === "difficult") return "还没有标记难句。";
if (query || activeTag !== "全部") return "没有匹配的素材。";
return filtered.length ? "" : "没有匹配的素材。";
}
- Step 6: Syntax check
Run:
node --check home.js
Expected: no output and exit code 0.
Task 3: Upgrade Material Cards
Files:
-
Modify:
F:\ooo\speaking-practice-local\home.js -
Modify:
F:\ooo\speaking-practice-local\styles.css -
Step 1: Replace
createVideoCard(video)
Replace the current function with:
function createVideoCard(video) {
const card = document.createElement("article");
const user = getCurrentUser();
const tags = normalizeTags(video.tags);
const subtitleLabel = getSubtitleLabel(video);
const totalLines = getDefaultCueCount(video);
const progress = getVideoProgress(user, video.id);
const summary = calculatePracticeSummary(progress, totalLines);
const progressLabel = formatProgressSummary(progress, totalLines);
const difficultCount = progress.difficultLineIndexes.filter((index) => index < totalLines || totalLines === 0).length;
const coverTone = getCoverTone(video.id);
const isFavorite = Boolean(user?.favorites.map(String).includes(String(video.id)));
card.className = "home-card";
card.innerHTML = `
<div class="home-cover tone-${coverTone}">
<span class="home-cover-badge"></span>
<button class="home-favorite" type="button" aria-label="收藏素材"></button>
<strong></strong>
</div>
<a class="home-card-link" href="./study.html?video=${encodeURIComponent(video.id)}">
<div class="home-card-body">
<h3></h3>
<p class="home-card-meta"></p>
<div class="home-card-tags"></div>
<dl class="home-card-stats">
<div>
<dt>句子</dt>
<dd></dd>
</div>
<div>
<dt>进度</dt>
<dd></dd>
</div>
<div>
<dt>难句</dt>
<dd></dd>
</div>
</dl>
<p class="home-card-subtitles"></p>
<p class="home-progress" hidden></p>
</div>
</a>
`;
card.querySelector(".home-cover-badge").textContent = tags[0] || "素材";
card.querySelector(".home-cover strong").textContent = getCoverText(video.title);
card.querySelector("h3").textContent = video.title || "Untitled";
card.querySelector(".home-card-meta").textContent = video.speaker || "Unknown";
card.querySelector(".home-card-tags").append(...tags.map(createTagPill));
card.querySelector(".home-card-subtitles").textContent = subtitleLabel;
const statValues = card.querySelectorAll(".home-card-stats dd");
statValues[0].textContent = totalLines ? `${totalLines}` : "-";
statValues[1].textContent = totalLines ? `${summary.percent}%` : "未开始";
statValues[2].textContent = `${difficultCount}`;
const favorite = card.querySelector(".home-favorite");
favorite.textContent = isFavorite ? "已收藏" : "收藏";
favorite.classList.toggle("active", isFavorite);
favorite.addEventListener("click", (event) => {
event.preventDefault();
event.stopPropagation();
toggleFavorite(video.id);
});
const progressNode = card.querySelector(".home-progress");
progressNode.textContent = progressLabel || "还未开始";
progressNode.hidden = false;
return card;
}
- Step 2: Add favorite toggle helper
Add this function below loginOrRegister():
function toggleFavorite(videoId) {
const user = getCurrentUser();
if (!user) {
alert("请先登录。第一版会自动注册新邮箱。");
return;
}
const key = String(videoId);
const favorites = new Set((user.favorites || []).map(String));
if (favorites.has(key)) {
favorites.delete(key);
} else {
favorites.add(key);
}
user.favorites = [...favorites];
saveState();
renderHome();
}
- Step 3: Syntax check
Run:
node --check home.js
Expected: no output and exit code 0.
Task 4: Style Dashboard And Upgraded Cards
Files:
-
Modify:
F:\ooo\speaking-practice-local\styles.css -
Step 1: Replace home layout styles
Replace the existing .home-shell, .home-library, .home-heading, .home-grid, .home-card, .home-card-link, .home-cover, .home-card-body, .home-card-meta, .home-card-subtitles, .home-progress, .home-card-tags, and related home card blocks with the updated home section styles below:
.home-shell {
display: grid;
grid-template-columns: 260px minmax(0, 1fr);
gap: 18px;
max-width: 1240px;
margin: 0 auto;
padding: 20px 24px 40px;
}
.home-dashboard,
.home-library {
min-width: 0;
}
.home-dashboard {
align-self: start;
position: sticky;
top: 82px;
display: grid;
gap: 12px;
}
.home-dashboard-title {
padding: 14px;
border: 1px solid var(--line);
border-radius: 8px;
background: var(--panel);
box-shadow: var(--shadow);
}
.home-dashboard-title span,
.home-dashboard-title strong {
display: block;
}
.home-dashboard-title span {
color: var(--muted);
font-size: 12px;
}
.home-dashboard-title strong {
margin-top: 4px;
overflow: hidden;
text-overflow: ellipsis;
white-space: nowrap;
font-size: 15px;
}
.home-metrics {
display: grid;
gap: 9px;
}
.home-metric {
min-height: 72px;
display: grid;
grid-template-columns: minmax(0, 1fr) auto;
align-items: center;
gap: 4px 10px;
padding: 11px 12px;
text-align: left;
border-radius: 8px;
background: var(--panel);
box-shadow: var(--shadow);
}
.home-metric span,
.home-metric small {
min-width: 0;
}
.home-metric span {
font-weight: 700;
}
.home-metric strong {
font-size: 24px;
line-height: 1;
font-variant-numeric: tabular-nums;
}
.home-metric small {
grid-column: 1 / -1;
color: var(--muted);
font-size: 12px;
}
.home-metric.active {
color: #fff;
border-color: var(--accent);
background: var(--accent);
}
.home-metric.active small {
color: rgba(255, 255, 255, 0.72);
}
.home-heading {
display: flex;
justify-content: space-between;
align-items: flex-start;
gap: 16px;
margin-bottom: 16px;
}
.home-heading h2 {
margin: 0;
font-size: 24px;
}
.home-heading p {
margin: 6px 0 0;
color: var(--muted);
font-size: 13px;
}
.home-categories {
display: flex;
gap: 8px;
overflow-x: auto;
padding: 2px 0 12px;
}
.home-status {
min-height: 22px;
color: var(--muted);
font-size: 13px;
margin-bottom: 12px;
}
.home-grid {
display: grid;
grid-template-columns: repeat(auto-fill, minmax(250px, 1fr));
gap: 14px;
}
.home-card {
min-width: 0;
overflow: hidden;
border: 1px solid var(--line);
border-radius: 8px;
background: var(--panel);
box-shadow: var(--shadow);
}
.home-card-link {
display: block;
color: inherit;
text-decoration: none;
}
.home-card:hover .home-cover {
filter: saturate(1.08);
}
.home-cover {
position: relative;
min-height: 138px;
display: grid;
align-content: space-between;
padding: 14px;
color: #fff;
background: #0f766e;
}
.home-favorite {
position: absolute;
top: 10px;
right: 10px;
min-height: 28px;
border-color: rgba(255, 255, 255, 0.38);
color: #fff;
background: rgba(17, 24, 39, 0.3);
font-size: 12px;
}
.home-favorite:hover,
.home-favorite.active {
color: #111827;
background: #fff;
border-color: #fff;
}
.home-cover.tone-1 {
background: linear-gradient(135deg, #0f766e, #164e63);
}
.home-cover.tone-2 {
background: linear-gradient(135deg, #7c3aed, #0f766e);
}
.home-cover.tone-3 {
background: linear-gradient(135deg, #1d4ed8, #4338ca);
}
.home-cover.tone-4 {
background: linear-gradient(135deg, #b45309, #be123c);
}
.home-cover.tone-5 {
background: linear-gradient(135deg, #334155, #0f766e);
}
.home-cover-badge {
width: fit-content;
max-width: calc(100% - 86px);
overflow: hidden;
text-overflow: ellipsis;
white-space: nowrap;
border: 1px solid rgba(255, 255, 255, 0.34);
border-radius: 999px;
padding: 4px 8px;
background: rgba(255, 255, 255, 0.14);
font-size: 12px;
}
.home-cover strong {
font-size: 34px;
line-height: 1;
}
.home-card-body {
padding: 12px;
}
.home-card-body h3 {
margin: 0;
font-size: 16px;
line-height: 1.35;
}
.home-card-meta,
.home-card-subtitles,
.home-progress {
margin: 6px 0 0;
color: var(--muted);
font-size: 12px;
line-height: 1.4;
}
.home-card-tags {
display: flex;
flex-wrap: wrap;
gap: 6px;
margin-top: 10px;
}
.home-card-tags span {
border-radius: 999px;
padding: 3px 7px;
color: #334155;
background: #eef2f7;
font-size: 12px;
}
.home-card-stats {
display: grid;
grid-template-columns: repeat(3, minmax(0, 1fr));
gap: 6px;
margin: 12px 0 0;
}
.home-card-stats div {
min-width: 0;
padding: 8px;
border-radius: 7px;
background: var(--panel-soft);
}
.home-card-stats dt,
.home-card-stats dd {
margin: 0;
}
.home-card-stats dt {
color: var(--muted);
font-size: 11px;
}
.home-card-stats dd {
margin-top: 3px;
font-weight: 800;
font-size: 13px;
}
.home-progress {
color: var(--brand);
font-weight: 700;
}
- Step 2: Update mobile styles
In the @media (max-width: 720px) block, use:
@media (max-width: 720px) {
.home-shell {
grid-template-columns: 1fr;
padding: 14px 12px 28px;
}
.home-dashboard {
position: static;
}
.home-metrics {
grid-template-columns: repeat(2, minmax(0, 1fr));
}
.home-heading {
align-items: stretch;
flex-direction: column;
}
.home-search {
max-width: none;
}
.home-grid {
grid-template-columns: 1fr;
}
}
- Step 3: Check for duplicate home style blocks
Run:
rg -n "\.home-shell|\.home-dashboard|\.home-card-stats|\.home-favorite" styles.css
Expected: selectors exist, and old conflicting .home-shell single-column rules are not duplicated outside media queries.
Task 5: Full Verification
Files:
-
Verify:
F:\ooo\speaking-practice-local\home.js -
Verify:
F:\ooo\speaking-practice-local\app.js -
Verify:
F:\ooo\speaking-practice-local\admin.js -
Verify:
F:\ooo\speaking-practice-local\backend\main.py -
Verify:
F:\ooo\speaking-practice-local\backend\db.py -
Step 1: Run automated checks
Run:
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
Expected: all commands finish with exit code 0.
- Step 2: Start or reuse the local server
If no server is running, run:
python -m uvicorn backend.main:app --reload --host 127.0.0.1 --port 8000
Expected: server listens on http://127.0.0.1:8000/.
- Step 3: Browser verification
Open:
http://127.0.0.1:8000/
Confirm:
-
the left learning overview appears
-
metric buttons update the grid
-
search and category chips still work
-
material cards show sentence, progress, difficult, subtitle, and favorite information
-
favorite button toggles without opening the study page
-
clicking the card body opens
study.html?video=<id> -
admin link remains visible only for admin users
-
Step 4: Confirm README was not modified
Run:
git diff -- README.md
Expected if inside a git repo: no diff. If not inside a git repo, this command may report that the directory is not a repository; in that case, manually confirm README.md was not edited.