docs(web): 任务说明、DSH 约束与交付文档

2026-09-14 19:00:55 +08:00
parent 5a8b77b0a4
commit b9215d4190
16 changed files with 1461 additions and 0 deletions
@@ -0,0 +1,53 @@
+# T-WEB-008 歌曲管理界面
+
+- **状态**：done
+- **依赖**：T-WEB-003
+
+## 目标
+
+React 管理端的歌曲管理页面：列表、检索、新建/编辑、音频上传与试听、删除。
+
+## load
+
+```
+DSH.md
+contracts/rest-api.yaml          # 锚点：#/paths/~1api~1songs、#/components/schemas/Song
+contracts/data-models.md         # 锚点：§2 Song
+web-server/admin/src/**
+web-server/admin/package.json
+```
+
+## 交付物
+
+`web-server/admin/`（React 18 + Vite + TypeScript）：
+
+| 路径 | 说明 |
+|---|---|
+| `src/pages/SongsPage.tsx` | 歌曲列表 + 分页 + 检索（`q` / `status` / `artist`） |
+| `src/components/SongForm*` | 新建/编辑表单，含来源五元组 |
+| `src/api/client.ts` | fetch 封装；非 2xx 抛 `ApiError`，兼容 Nest 的 `message: string[]` |
+| `src/api/types.ts` | 与契约对齐的 TypeScript 类型 |
+| `src/styles.css` | 无 UI 框架，纯 CSS |
+
+## 页面能力
+
+- 分页表格 + 关键词/状态/歌手过滤
+- 新建与编辑：曲名、歌手、专辑、语言、时长（秒输入 → 毫秒提交）、BPM、
+  难度 1–5、标签（逗号分隔）、状态、**来源五元组**
+- 音频上传（`POST /api/songs/:id/audio`，字段名 `file`）与 `<audio controls>` 试听
+- 删除需二次确认（软删除）
+- 客户端校验：曲名/歌手与来源五项必填，`sourceUrl` 必须以 `http` 开头
+- 加载中 / 空列表 / 请求失败三态均有明确反馈，绝不出现白屏
+
+## 验收
+
+```bash
+cd web-server/admin
+npm run build     # tsc -b && vite build 必须成功
+```
+
+## 构建与运行
+
+- 开发：`npm run dev`（5173，`/api` 与 `/health` 代理到 `localhost:3000`）
+- 生产：多阶段 Dockerfile 构建后由 nginx 托管，`/api` 反代到 `api:3000`
+- `VITE_API_BASE` 可覆盖 API 基地址；留空表示同源