Files
speaking-practice/docs/superpowers/specs/2026-06-01-speaking-lab-admin-page-design.md
T
2026-06-03 00:34:42 +08:00

5.6 KiB

Speaking Lab Admin Page Design

Goal

Move content management out of the study page and into a dedicated local admin page. The first admin page supports only adding and deleting materials, keeping the study page focused on learning.

Scope

In scope:

  • Add a dedicated admin.html page.
  • Add a small admin entry button beside the left material rail title on index.html.
  • Show the admin entry button only when the current local user is an admin.
  • Remove the bottom 后台管理 dock from the study page.
  • Support adding materials from the new admin page through the existing POST /api/videos endpoint.
  • Support deleting materials from the new admin page through a new DELETE /api/videos/{video_id} endpoint.
  • Delete local uploaded video and subtitle files when deleting a material.
  • Keep external video/HLS URLs untouched when deleting a material.

Out of scope:

  • Editing video title, speaker, description, tags, or URL.
  • Replacing subtitles after creation.
  • Real backend authentication or sessions.
  • User roles stored in SQLite.
  • Batch delete, undo, recycle bin, or soft delete.
  • Server deployment.

Admin Visibility

This phase keeps the current local prototype auth rule:

  • A user is an admin when their email contains admin.
  • Login state remains in browser localStorage.
  • The study page shows the admin entry button only for admin users.
  • The admin page checks the same local login state. If the visitor is not an admin, it shows a simple message telling them to return to the study page and log in with an admin email.

This is not secure server-side authorization. It is acceptable for the local prototype phase and should be replaced when real multi-user deployment starts.

Study Page Changes

The study page should become learning-focused.

Changes:

  • Remove the bottom 后台管理 dock from index.html.
  • Keep login/register in the top bar.
  • In the left material rail header, show:
    • 素材
    • current video count
    • a small admin button when the current user is admin
  • Clicking the admin button navigates to admin.html.

The existing study page continues to load videos through GET /api/videos, use demo videos as empty-library fallback, and preserve existing study behaviors.

Admin Page

Add admin.html and admin.js.

The admin page has:

  • Header with product name and a return-to-study button.
  • Admin status area showing the current local admin email.
  • Add material form:
    • title
    • speaker
    • description
    • comma-separated tags
    • local video file
    • video/HLS URL
    • English .srt / .vtt subtitle
    • Chinese .srt / .vtt subtitle
  • Material list:
    • title
    • speaker
    • tags
    • source type
    • subtitle availability
    • delete button

First-version behavior:

  • Add uses existing POST /api/videos.
  • On successful add, the form resets and the list reloads.
  • Delete asks for confirmation with 确定删除这个素材吗?此操作不可恢复。
  • Confirmed delete calls DELETE /api/videos/{video_id}.
  • Successful delete removes the item from the list.

Backend Delete Design

Add DELETE /api/videos/{video_id}.

Behavior:

  • If the video does not exist, return 404 with 视频不存在.
  • Before deleting database rows, collect local file paths:
    • videos.video_url if it starts with /uploads/
    • every related subtitles.file_path if it starts with /uploads/
  • Delete the video row from SQLite. Existing foreign key cascade deletes related subtitle rows.
  • After the database delete succeeds, attempt to remove collected local files from disk.
  • Ignore missing files.
  • If a file cannot be deleted, keep the database delete successful and return a response that includes a warning list.

Suggested response:

{
  "ok": true,
  "deletedVideoId": 1,
  "warnings": []
}

If file deletion has warnings:

{
  "ok": true,
  "deletedVideoId": 1,
  "warnings": ["无法删除文件: uploads/videos/example.mp4"]
}

Data And File Safety

Delete only files under the project uploads/ directory. Never delete arbitrary paths from database content.

Implementation rule:

  • Convert /uploads/... URLs to filesystem paths under the project upload directory.
  • Resolve the path.
  • Delete it only if the resolved path is inside UPLOADS_DIR.

This prevents a bad database value from deleting unrelated local files.

Testing

Manual verification:

  1. Start the app:

    cd F:\ooo\speaking-practice-local
    python -m uvicorn backend.main:app --reload --host 127.0.0.1 --port 8000
    
  2. Open http://127.0.0.1:8000.

  3. Log in with a normal email. Confirm the material rail does not show the admin button.

  4. Log out, then log in with an email containing admin. Confirm the admin button appears beside 素材.

  5. Click the admin button. Confirm admin.html opens.

  6. Add a URL-based material with subtitles from the admin page.

  7. Return to the study page and confirm the new material appears.

  8. Return to the admin page and delete the material.

  9. Return to the study page and confirm the deleted material no longer appears.

  10. Add a local video-file material with subtitles, then delete it. Confirm uploaded files are removed from uploads/videos/ and uploads/subtitles/.

  11. Open http://127.0.0.1:8000/docs and confirm DELETE /api/videos/{video_id} appears.

Automated or command-line checks:

python -m py_compile backend\main.py backend\db.py
node --check app.js
node --check admin.js

Future Work

Likely follow-up phases:

  • Edit video metadata.
  • Replace subtitles.
  • Add backend-backed accounts and real admin authorization.
  • Add import/export backup.
  • Add server deployment flow.