# 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`)
- 生产：`npm run build` 产物由**后端服务自身**托管（`ADMIN_DIR`，含 SPA 回退），反向代理只需整体转发到后端端口(见 `deploy/proxy/README.md`)
- `VITE_API_BASE` 可覆盖 API 基地址；留空表示同源