Files
speaking-practice/docs/superpowers/specs/2026-06-02-speaking-lab-material-edit-design.md
T
2026-06-03 00:34:42 +08:00

2.3 KiB

Speaking Lab Material Edit v1 Design

Goal

Allow an admin to update already uploaded materials without deleting and recreating them.

Scope

Material Edit v1 includes:

  • Add an 编辑 action to each material in the admin list.
  • Load the selected material into the existing admin form.
  • Allow editing title, speaker/source, description, tags, and video URL.
  • Allow replacing the video file.
  • Allow replacing English and Chinese subtitle files independently.
  • Preserve existing files when no replacement file is selected.
  • Save changes through PATCH /api/videos/{video_id}.
  • Clean up old local uploaded files when they are replaced.
  • Add 取消编辑 to return the form to add mode.

Material Edit v1 excludes:

  • Rich subtitle editing in the browser.
  • Removing a single subtitle without replacing it.
  • Server-side authentication or permissions.
  • Version history or undo.

Backend Behavior

PATCH /api/videos/{video_id} accepts multipart form data:

  • title
  • speaker
  • description
  • tags
  • video_url
  • optional video_file
  • optional subtitle_en
  • optional subtitle_zh

Rules:

  • Title is required.
  • If a new video file is uploaded, it replaces the old video source.
  • If no new video file is uploaded, video_url is used as the video source.
  • If video_url is left empty during edit and no video file is uploaded, the existing video source is preserved.
  • Replaced local files under /uploads/... are deleted safely.
  • Remote http:// / https:// URLs are never deleted as files.

Frontend Behavior

Admin page form has two modes:

  • Add mode: submit creates a new material.
  • Edit mode: submit updates the selected material.

When entering edit mode:

  • Form heading changes to 编辑素材.
  • Submit button changes to 保存修改.
  • Existing text fields are filled.
  • File buttons show that existing files are retained unless replaced.
  • Material being edited is visually highlighted in the list.

When update succeeds:

  • Form resets to add mode.
  • Material list refreshes.
  • Success message says 素材已更新。

Verification

  • Static checks pass.
  • Create a temporary material through API.
  • Patch its title/tags.
  • Patch its subtitle or video file when a local test file is available.
  • Confirm GET /api/videos/{id} returns updated data.
  • Delete the temporary material.