53 lines
1.6 KiB
Markdown
53 lines
1.6 KiB
Markdown
# T-WEB-003 /api/songs CRUD
|
||
|
||
- **状态**：done
|
||
- **依赖**：T-WEB-002
|
||
|
||
## 目标
|
||
|
||
曲目的增删改查与分页检索，字段语义符合 `contracts/data-models.md` 2。
|
||
|
||
## load
|
||
|
||
```
|
||
DSH.md
|
||
contracts/rest-api.yaml # 锚点：#/paths/~1api~1songs
|
||
contracts/data-models.md # 锚点：1 通用约定、2 Song
|
||
web-server/src/songs/*
|
||
web-server/src/common/source.dto.ts
|
||
web-server/src/common/pagination.ts
|
||
```
|
||
|
||
## 端点
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|--|--|--|
|
||
| GET | `/api/songs` | 分页 + `q`/`artist`/`status` 过滤 |
|
||
| POST | `/api/songs` | 新建（来源五元组必填） |
|
||
| GET | `/api/songs/:id` | 详情 |
|
||
| PATCH | `/api/songs/:id` | 更新（来源需五元组同时提交） |
|
||
| DELETE | `/api/songs/:id` | **软删除** |
|
||
| POST | `/api/songs/:id/audio` | 上传音频（multipart，字段名 `file`） |
|
||
| POST | `/api/songs/:id/cover` | 上传封面 |
|
||
|
||
## 关键实现
|
||
|
||
- `likePattern()` 转义 `%` `_` `\`，用户输入不会被当作 LIKE 模式。
|
||
- `assertSourceTupleComplete()` 实现「全有或全无」：PATCH 只给部分来源字段 -> 400。
|
||
- PATCH 直接改 `status` 时校验状态机；非法流转 -> 409 并提示改用 `/api/reviews`。
|
||
- `toDtos()` 批量解析 asset -> URL，避免 N+1。
|
||
|
||
## 验收
|
||
|
||
```bash
|
||
npm run test:smoke
|
||
```
|
||
|
||
冒烟脚本 [1] 段落覆盖：创建 201、id 为 number、来源回显、tags 往返、bpm 为 number、
|
||
分页结构、模糊查询命中、音频上传后 `audioUrl` 以 `/static/` 开头、PATCH 生效、
|
||
部分来源字段 400、软删除后不再出现在列表。
|
||
|
||
## 结果
|
||
|
||
全部通过（见 `web-server/test/smoke.mjs`）。
|