22 KiB
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, addGET /api/videos,GET /api/videos/{video_id}, andPOST /api/videos. - Modify
F:\ooo\speaking-practice-local\app.js: load videos from the API, submit admin uploads withFormData, 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/healthreturnsok: True. -
/api/videosreturns 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/videosis visible.GET /api/videos/{video_id}is visible.POST /api/videosis 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, andfilePath. - Frontend normalizes subtitle
contentinto existingcues. - Video ids may become numbers from SQLite; comparisons that need robustness use string conversion in the admin insert path.