Files
speaking-practice/docs/superpowers/plans/2026-06-01-speaking-lab-content-library.md
T
2026-06-03 00:34:42 +08:00

22 KiB
Raw Blame History

Speaking Lab Content Library 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: Build the first real content-library slice so admins can add videos with uploaded files or URLs plus English/Chinese subtitles, and the library persists in SQLite after refresh.

Architecture: Keep the current FastAPI + SQLite backend and vanilla frontend. Add a small backend content-library module for database serialization, file validation, and multipart uploads, then switch the frontend video library from browser-only storage to /api/videos.

Tech Stack: FastAPI, Python sqlite3, vanilla JavaScript, browser FormData, local filesystem uploads.


File Structure

  • Modify F:\ooo\speaking-practice-local\backend\db.py: add helpers for video/subtitle inserts and video serialization.
  • Modify F:\ooo\speaking-practice-local\backend\main.py: mount uploads, add GET /api/videos, GET /api/videos/{video_id}, and POST /api/videos.
  • Modify F:\ooo\speaking-practice-local\app.js: load videos from the API, submit admin uploads with FormData, normalize backend subtitle content into existing cue objects, and keep localStorage only for user/session state.
  • Modify F:\ooo\speaking-practice-local\README.md: document the new content-library behavior and manual verification.

The project currently has no test runner or git repository in speaking-practice-local. Use focused manual and API verification in this plan. If the project is later initialized as a git repository, commit after each completed task using the suggested commit messages.


Task 1: Add Backend Video Persistence Helpers

Files:

  • Modify: F:\ooo\speaking-practice-local\backend\db.py

  • Step 1: Add imports and helper functions

Add these imports near the top:

import json

Add these helpers after initialize_database():

def parse_tags(tags_text: str | None) -> list[str]:
    tags = [
        tag.strip()
        for tag in (tags_text or "").replace(",", ",").split(",")
        if tag.strip()
    ]
    return tags or ["未分类"]


def row_to_video(row: sqlite3.Row, subtitle_rows: list[sqlite3.Row]) -> dict[str, object]:
    subtitles: dict[str, dict[str, str]] = {}
    for subtitle in subtitle_rows:
        subtitles[subtitle["language_code"]] = {
            "languageName": subtitle["language_name"] or subtitle["language_code"],
            "format": subtitle["format"],
            "filePath": subtitle["file_path"],
            "content": subtitle["content"] or "",
        }

    try:
        tags = json.loads(row["tags"] or "[]")
    except json.JSONDecodeError:
        tags = parse_tags(row["tags"])

    return {
        "id": row["id"],
        "title": row["title"],
        "speaker": row["speaker"] or "Unknown",
        "description": row["description"] or "",
        "tags": tags if isinstance(tags, list) and tags else ["未分类"],
        "duration": row["duration_seconds"] or 0,
        "videoUrl": row["video_url"] or "",
        "sourceType": "url" if str(row["video_url"] or "").startswith(("http://", "https://")) else "local-file",
        "subtitles": subtitles,
    }
  • Step 2: Add insert and read helpers

Add these functions after row_to_video():

def create_video(
    *,
    title: str,
    speaker: str | None,
    description: str | None,
    tags: list[str],
    video_url: str,
    subtitles: list[dict[str, str]],
) -> dict[str, object]:
    with get_connection() as connection:
        cursor = connection.execute(
            """
            INSERT INTO videos (
                title, speaker, description, tags, video_url, status
            )
            VALUES (?, ?, ?, ?, ?, 'published')
            """,
            (
                title,
                speaker or "Unknown",
                description or "",
                json.dumps(tags, ensure_ascii=False),
                video_url,
            ),
        )
        video_id = int(cursor.lastrowid)

        for subtitle in subtitles:
            connection.execute(
                """
                INSERT INTO subtitles (
                    video_id, language_code, language_name, format, file_path, content
                )
                VALUES (?, ?, ?, ?, ?, ?)
                """,
                (
                    video_id,
                    subtitle["language_code"],
                    subtitle["language_name"],
                    subtitle["format"],
                    subtitle["file_path"],
                    subtitle["content"],
                ),
            )

    video = get_video(video_id)
    if video is None:
        raise RuntimeError("Created video could not be loaded")
    return video


def list_videos() -> list[dict[str, object]]:
    with get_connection() as connection:
        video_rows = connection.execute(
            """
            SELECT *
            FROM videos
            WHERE status = 'published'
            ORDER BY created_at DESC, id DESC
            """
        ).fetchall()
        subtitle_rows = connection.execute(
            """
            SELECT *
            FROM subtitles
            ORDER BY id ASC
            """
        ).fetchall()

    subtitles_by_video: dict[int, list[sqlite3.Row]] = {}
    for subtitle in subtitle_rows:
        subtitles_by_video.setdefault(int(subtitle["video_id"]), []).append(subtitle)

    return [
        row_to_video(row, subtitles_by_video.get(int(row["id"]), []))
        for row in video_rows
    ]


def get_video(video_id: int) -> dict[str, object] | None:
    with get_connection() as connection:
        row = connection.execute(
            """
            SELECT *
            FROM videos
            WHERE id = ? AND status = 'published'
            """,
            (video_id,),
        ).fetchone()
        if row is None:
            return None

        subtitle_rows = connection.execute(
            """
            SELECT *
            FROM subtitles
            WHERE video_id = ?
            ORDER BY id ASC
            """,
            (video_id,),
        ).fetchall()

    return row_to_video(row, subtitle_rows)
  • Step 3: Run a syntax check

Run:

python -m py_compile backend\db.py

Expected: command exits with no output.

Suggested commit if this directory is later made a git repo:

git add backend/db.py
git commit -m "backend: add video persistence helpers"

Task 2: Add Video Library API Endpoints

Files:

  • Modify: F:\ooo\speaking-practice-local\backend\main.py

  • Step 1: Add FastAPI imports

Replace the current FastAPI import block with:

from pathlib import Path
from uuid import uuid4

from fastapi import FastAPI, File, Form, HTTPException, UploadFile
from fastapi.responses import FileResponse
from fastapi.staticfiles import StaticFiles

from .db import (
    DATABASE_PATH,
    create_video,
    initialize_database,
    list_videos,
    parse_tags,
    table_names,
    get_video,
)
  • Step 2: Add upload validation constants and helpers

Add this after UPLOADS_DIR = PROJECT_DIR / "uploads":

VIDEO_EXTENSIONS = {".mp4", ".webm", ".mov", ".m4v"}
SUBTITLE_EXTENSIONS = {".srt", ".vtt"}


def extension_for_upload(upload: UploadFile) -> str:
    return Path(upload.filename or "").suffix.lower()


def safe_upload_name(upload: UploadFile) -> str:
    extension = extension_for_upload(upload)
    return f"{uuid4().hex}{extension}"


async def save_upload(upload: UploadFile, target_dir: Path) -> tuple[str, str]:
    target_dir.mkdir(parents=True, exist_ok=True)
    filename = safe_upload_name(upload)
    target_path = target_dir / filename
    content = await upload.read()
    try:
        target_path.write_bytes(content)
    except OSError as exc:
        raise HTTPException(status_code=500, detail="保存文件失败,请重试") from exc
    return filename, content.decode("utf-8-sig", errors="replace")


async def save_binary_upload(upload: UploadFile, target_dir: Path) -> str:
    target_dir.mkdir(parents=True, exist_ok=True)
    filename = safe_upload_name(upload)
    target_path = target_dir / filename
    content = await upload.read()
    try:
        target_path.write_bytes(content)
    except OSError as exc:
        raise HTTPException(status_code=500, detail="保存文件失败,请重试") from exc
    return filename
  • Step 3: Mount uploaded files

Add this after the on_startup() function:

app.mount("/uploads", StaticFiles(directory=UPLOADS_DIR), name="uploads")

Leave the existing final app.mount("/", StaticFiles(directory=PROJECT_DIR), name="static") at the bottom so /uploads/... is matched before the root static mount.

  • Step 4: Add list and detail endpoints

Add this after health_check():

@app.get("/api/videos")
def api_list_videos() -> list[dict[str, object]]:
    return list_videos()


@app.get("/api/videos/{video_id}")
def api_get_video(video_id: int) -> dict[str, object]:
    video = get_video(video_id)
    if video is None:
        raise HTTPException(status_code=404, detail="视频不存在")
    return video
  • Step 5: Add create endpoint

Add this after api_get_video():

@app.post("/api/videos")
async def api_create_video(
    title: str = Form(...),
    speaker: str = Form(""),
    description: str = Form(""),
    tags: str = Form(""),
    video_url: str = Form(""),
    video_file: UploadFile | None = File(None),
    subtitle_en: UploadFile | None = File(None),
    subtitle_zh: UploadFile | None = File(None),
) -> dict[str, object]:
    clean_title = title.strip()
    if not clean_title:
        raise HTTPException(status_code=400, detail="标题不能为空")

    clean_video_url = video_url.strip()
    if video_file is None and not clean_video_url:
        raise HTTPException(status_code=400, detail="请上传视频文件或填写视频地址")

    final_video_url = clean_video_url
    if video_file is not None:
        if extension_for_upload(video_file) not in VIDEO_EXTENSIONS:
            raise HTTPException(status_code=400, detail="视频文件格式不支持")
        video_filename = await save_binary_upload(video_file, UPLOADS_DIR / "videos")
        final_video_url = f"/uploads/videos/{video_filename}"

    subtitles: list[dict[str, str]] = []
    for upload, language_code, language_name in (
        (subtitle_en, "en", "English"),
        (subtitle_zh, "zh", "中文"),
    ):
        if upload is None:
            continue
        extension = extension_for_upload(upload)
        if extension not in SUBTITLE_EXTENSIONS:
            raise HTTPException(status_code=400, detail="字幕只支持 .srt 或 .vtt")
        subtitle_filename, subtitle_text = await save_upload(upload, UPLOADS_DIR / "subtitles")
        subtitles.append(
            {
                "language_code": language_code,
                "language_name": language_name,
                "format": extension.removeprefix("."),
                "file_path": f"/uploads/subtitles/{subtitle_filename}",
                "content": subtitle_text,
            }
        )

    return create_video(
        title=clean_title,
        speaker=speaker.strip(),
        description=description.strip(),
        tags=parse_tags(tags),
        video_url=final_video_url,
        subtitles=subtitles,
    )
  • Step 6: Run a syntax check

Run:

python -m py_compile backend\main.py backend\db.py

Expected: command exits with no output.

  • Step 7: Verify the API imports

Run:

python -c "from backend.main import app; print(app.title)"

Expected output:

Speaking Lab API

Suggested commit if this directory is later made a git repo:

git add backend/main.py backend/db.py
git commit -m "backend: add content library api"

Task 3: Switch Frontend Library Loading to the API

Files:

  • Modify: F:\ooo\speaking-practice-local\app.js

  • Step 1: Add API helper functions

Add this after the let hlsInstance = null; line:

async function apiRequest(path, options = {}) {
  const response = await fetch(path, options);
  if (!response.ok) {
    let message = "请求失败,请重试。";
    try {
      const payload = await response.json();
      message = payload.detail || message;
    } catch {
      message = response.statusText || message;
    }
    throw new Error(message);
  }
  return response.json();
}

function normalizeVideoFromApi(video) {
  const subtitles = {};
  Object.entries(video.subtitles || {}).forEach(([code, subtitle]) => {
    subtitles[code] = {
      languageName: subtitle.languageName || code,
      format: subtitle.format || "",
      filePath: subtitle.filePath || "",
      content: subtitle.content || "",
      cues: parseSubtitle(subtitle.content || ""),
    };
  });

  return {
    id: video.id,
    title: video.title || "Untitled",
    speaker: video.speaker || "Unknown",
    description: video.description || "",
    tags: Array.isArray(video.tags) && video.tags.length ? video.tags : ["未分类"],
    duration: video.duration || 0,
    videoUrl: video.videoUrl || "",
    sourceType: video.sourceType || "url",
    subtitles,
  };
}
  • Step 2: Replace startup calls

Replace:

hydrate();
bindEvents();
renderAll();
selectVideo(activeVideoId);

with:

bindEvents();
initializeApp();
  • Step 3: Replace hydrate() with API startup loading

Replace the entire hydrate() function with:

async function initializeApp() {
  try {
    const videos = await apiRequest("/api/videos");
    state.videos = videos.map(normalizeVideoFromApi);
    if (!state.videos.length) {
      state.videos = sampleVideos;
    }
  } catch (error) {
    console.error(error);
    state.videos = sampleVideos;
    els.videoList.innerHTML = `<div class="empty-state">后端视频库加载失败,当前显示示例素材。</div>`;
  }

  if (!getVideo(activeVideoId)) {
    activeVideoId = state.videos[0]?.id || null;
  }

  renderAll();
  if (activeVideoId) selectVideo(activeVideoId);
}
  • Step 4: Keep video library out of localStorage

Replace saveState() with:

function saveState() {
  const persistable = {
    users: state.users,
    currentUserId: state.currentUserId,
    activeVideoId: state.activeVideoId,
  };
  localStorage.setItem(STORAGE_KEY, JSON.stringify(persistable));
}

Replace the loadState() return object so videos is always empty on load:

function loadState() {
  try {
    const saved = JSON.parse(localStorage.getItem(STORAGE_KEY) || "{}");
    return {
      users: Array.isArray(saved.users) ? saved.users : [],
      currentUserId: saved.currentUserId || null,
      videos: [],
      activeVideoId: saved.activeVideoId || null,
    };
  } catch {
    return { users: [], currentUserId: null, videos: [], activeVideoId: null };
  }
}
  • Step 5: Run a quick static syntax check

Run:

node --check app.js

Expected output:

The expected output is empty; the command should exit with code 0.

Suggested commit if this directory is later made a git repo:

git add app.js
git commit -m "frontend: load videos from api"

Task 4: Submit Admin Video Adds to the Backend

Files:

  • Modify: F:\ooo\speaking-practice-local\app.js

  • Step 1: Replace addVideoFromAdmin()

Replace the full addVideoFromAdmin(event) function with:

async function addVideoFromAdmin(event) {
  event.preventDefault();
  if (getCurrentUser()?.role !== "admin") return;

  const title = els.adminTitle.value.trim();
  if (!title) {
    alert("标题不能为空");
    return;
  }

  const submitButton = els.adminForm.querySelector('button[type="submit"]');
  const previousText = submitButton.textContent;
  submitButton.disabled = true;
  submitButton.textContent = "正在添加...";

  const formData = new FormData();
  formData.append("title", title);
  formData.append("speaker", els.adminSpeaker.value.trim());
  formData.append("description", els.adminDescription.value.trim());
  formData.append("tags", els.adminTags.value.trim());
  formData.append("video_url", els.adminVideoUrl.value.trim());

  const videoFile = els.adminVideoFile.files?.[0];
  const enFile = els.adminSubtitleEn.files?.[0];
  const zhFile = els.adminSubtitleZh.files?.[0];
  if (videoFile) formData.append("video_file", videoFile);
  if (enFile) formData.append("subtitle_en", enFile);
  if (zhFile) formData.append("subtitle_zh", zhFile);

  try {
    const created = normalizeVideoFromApi(await apiRequest("/api/videos", {
      method: "POST",
      body: formData,
    }));
    state.videos = [created, ...state.videos.filter((video) => String(video.id) !== String(created.id))];
    els.adminForm.reset();
    renderLibrary();
    selectVideo(created.id);
  } catch (error) {
    alert(error.message || "添加视频失败,请重试。");
  } finally {
    submitButton.disabled = false;
    submitButton.textContent = previousText;
    renderAdminAccess();
  }
}
  • Step 2: Guard current-video editing for API-backed videos

Replace updateCurrentVideoInfo() with:

function updateCurrentVideoInfo() {
  alert("第一版内容库暂不支持网页编辑。请重新添加一条新视频。");
}
  • Step 3: Verify admin form controls recover after submit

After Step 1, keep the existing renderAdminAccess() function unchanged:

[...els.adminForm.elements].forEach((element) => {
  element.disabled = !isAdmin;
});

Manual check after implementation:

  • Log in with an admin email.

  • Submit the admin form with an intentionally invalid request, such as no video file and no video URL.

  • Confirm an error appears.

  • Confirm the submit button text returns to 添加到视频库.

  • Confirm the admin form inputs are enabled again.

  • Step 4: Run a quick static syntax check

Run:

node --check app.js

Expected: command exits with no output.

Suggested commit if this directory is later made a git repo:

git add app.js
git commit -m "frontend: submit admin videos to backend"

Task 5: Document and Manually Verify the Content Library

Files:

  • Modify: F:\ooo\speaking-practice-local\README.md

  • Step 1: Add content-library notes to README

Append this section to the README:

## Content Library

The admin form now saves videos and subtitles through the FastAPI backend.

Supported first-version flow:

- Log in with an email containing `admin`.
- Add a title, speaker, description, and comma-separated tags.
- Choose either a local video file or a video/HLS URL.
- Optionally upload English and Chinese `.srt` / `.vtt` subtitle files.
- Refresh the browser and confirm the added video remains in the library.

Uploaded files are stored locally:

- Videos: `uploads/videos/`
- Subtitles: `uploads/subtitles/`

Metadata is stored in SQLite:

- `backend/speaking_lab.sqlite`

This phase does not include web editing, deletion, real authentication, learning progress sync, or server deployment.
  • Step 2: Start the dev server

Run:

python -m uvicorn backend.main:app --reload --host 127.0.0.1 --port 8000

Expected output includes:

Uvicorn running on http://127.0.0.1:8000
  • Step 3: Verify health and list endpoints

In a second terminal, run:

Invoke-RestMethod http://127.0.0.1:8000/api/health
Invoke-RestMethod http://127.0.0.1:8000/api/videos

Expected:

  • /api/health returns ok: True.

  • /api/videos returns an array. It may be empty.

  • Step 4: Verify external URL creation by API

Create a small subtitle file for testing:

@"
1
00:00:00,000 --> 00:00:02,000
Hello from Speaking Lab.
"@ | Set-Content -LiteralPath .\test-en.srt -Encoding UTF8

Run:

curl.exe -X POST http://127.0.0.1:8000/api/videos `
  -F "title=API Smoke Test" `
  -F "speaker=Tester" `
  -F "description=Created from curl" `
  -F "tags=测试,API" `
  -F "video_url=https://example.com/video.mp4" `
  -F "subtitle_en=@test-en.srt"

Expected response includes:

"title":"API Smoke Test"
  • Step 5: Verify browser flow

Open:

http://127.0.0.1:8000

Manual expected behavior:

  • Log in with an email containing admin.

  • Submit a video URL with English and Chinese subtitles.

  • The new video appears at the top of the material list.

  • Refresh the browser.

  • The new video remains in the material list.

  • Selecting the video shows parsed subtitle lines.

  • Step 6: Verify API docs

Open:

http://127.0.0.1:8000/docs

Expected:

  • GET /api/videos is visible.
  • GET /api/videos/{video_id} is visible.
  • POST /api/videos is visible.

Suggested commit if this directory is later made a git repo:

git add README.md
git commit -m "docs: document content library flow"

Self-Review

Spec coverage:

  • Backend content APIs are covered by Tasks 1 and 2.
  • Uploaded video and subtitle storage are covered by Task 2.
  • SQLite video/subtitle persistence is covered by Task 1.
  • Frontend API loading and admin submit behavior are covered by Tasks 3 and 4.
  • Manual verification and docs are covered by Task 5.

Placeholder scan:

  • No placeholder markers or unspecified implementation steps.
  • The plan intentionally excludes edit/delete, real authentication, learning records, and deployment, matching the approved spec.

Type consistency:

  • Backend returns camelCase properties expected by the existing frontend: videoUrl, sourceType, languageName, and filePath.
  • Frontend normalizes subtitle content into existing cues.
  • Video ids may become numbers from SQLite; comparisons that need robustness use string conversion in the admin insert path.