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

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.