docs(readme): 新增初次部署清单与常见问题;统一 root 执行写法;清除 markdown 粗体标记与残留真实库名

This commit is contained in:
2026-09-15 21:27:29 +08:00
parent 9c8379e5eb
commit ebd871018f
19 changed files with 345 additions and 296 deletions
+6 -6
View File
@@ -5,14 +5,14 @@
## 目标
曲目的增删改查与分页检索,字段语义符合 `contracts/data-models.md` §2。
曲目的增删改查与分页检索,字段语义符合 `contracts/data-models.md` 2。
## load
```
DSH.md
contracts/rest-api.yaml # 锚点:#/paths/~1api~1songs
contracts/data-models.md # 锚点:§1 通用约定、§2 Song
contracts/data-models.md # 锚点:1 通用约定、2 Song
web-server/src/songs/*
web-server/src/common/source.dto.ts
web-server/src/common/pagination.ts
@@ -21,7 +21,7 @@ web-server/src/common/pagination.ts
## 端点
| 方法 | 路径 | 说明 |
|---|---|---|
|--|--|--|
| GET | `/api/songs` | 分页 + `q`/`artist`/`status` 过滤 |
| POST | `/api/songs` | 新建(来源五元组必填) |
| GET | `/api/songs/:id` | 详情 |
@@ -33,9 +33,9 @@ web-server/src/common/pagination.ts
## 关键实现
- `likePattern()` 转义 `%` `_` `\`,用户输入不会被当作 LIKE 模式。
- `assertSourceTupleComplete()` 实现「全有或全无」:PATCH 只给部分来源字段 → 400。
- PATCH 直接改 `status` 时校验状态机;非法流转 → 409 并提示改用 `/api/reviews`。
- `toDtos()` 批量解析 asset → URL,避免 N+1。
- `assertSourceTupleComplete()` 实现「全有或全无」:PATCH 只给部分来源字段 -> 400。
- PATCH 直接改 `status` 时校验状态机;非法流转 -> 409 并提示改用 `/api/reviews`。
- `toDtos()` 批量解析 asset -> URL,避免 N+1。
## 验收