# Music_Server Token Binding Pause Handoff

日期：2026-04-20

## 项目快照

- 仓库：`D:\source\musicdl-catalog-sync-worktrees\Music_Server`
- 分支：`feature/musicfree-music-server-plugin`
- remote：未配置
- 当前主跟踪文档：
  - `docs/superpowers/specs/2026-04-20-music-server-token-binding-design.md`
  - `docs/superpowers/plans/2026-04-20-music-server-token-binding-implementation.md`

## 已验证进度

### Task 1: Build Music_Server TokenService

已完成，且经过两轮 review 后通过。

已落地文件：

- `src/music_server/services/token_service.py`
- `tests/test_token_service.py`

本会话最终验证：

- `python -m pytest D:\source\musicdl-catalog-sync-worktrees\Music_Server\tests\test_token_service.py -q`
- 结果：`7 passed`

已确认处理的问题：

- 首绑竞态不会让两个客户端都 `valid=True`
- 过期判断不再做字符串比较
- `status()` 使用最终状态构造响应，避免前后不一致
- 已补“读取后、绑定前被撤销”回归测试

### Task 2: Wire FastAPI auth dependency and token status route

实现已完成到“功能可跑 + spec review 通过”的阶段，但尚未完成最终 code quality 修复闭环。

已落地文件：

- `src/music_server/services/catalog_reader.py`
- `src/music_server/routes/auth.py`
- `src/music_server/auth.py`
- `src/music_server/app.py`
- `tests/support.py`
- `tests/test_auth_routes.py`
- `tests/test_catalog_reader.py`
- `tests/test_health.py`
- `tests/test_mf_catalog_routes.py`
- `tests/test_mf_media_routes.py`
- `tests/test_mf_detail_routes.py`
- `tests/test_player_routes.py`
- `tests/test_player_history_routes.py`

已验证命令：

- `python -m pytest D:\source\musicdl-catalog-sync-worktrees\Music_Server\tests\test_auth_routes.py D:\source\musicdl-catalog-sync-worktrees\Music_Server\tests\test_catalog_reader.py D:\source\musicdl-catalog-sync-worktrees\Music_Server\tests\test_health.py -q`
- 结果：`16 passed`

- `python -m pytest D:\source\musicdl-catalog-sync-worktrees\Music_Server\tests\test_auth_routes.py D:\source\musicdl-catalog-sync-worktrees\Music_Server\tests\test_catalog_reader.py D:\source\musicdl-catalog-sync-worktrees\Music_Server\tests\test_health.py D:\source\musicdl-catalog-sync-worktrees\Music_Server\tests\test_mf_catalog_routes.py D:\source\musicdl-catalog-sync-worktrees\Music_Server\tests\test_mf_media_routes.py D:\source\musicdl-catalog-sync-worktrees\Music_Server\tests\test_mf_detail_routes.py D:\source\musicdl-catalog-sync-worktrees\Music_Server\tests\test_player_routes.py D:\source\musicdl-catalog-sync-worktrees\Music_Server\tests\test_player_history_routes.py -q`
- 结果：`39 passed, 1 warning`

spec review 结论：

- `PASS`

code quality review 结论：

- `CHANGES_REQUIRED`

未收尾的问题：

1. `src/music_server/routes/auth.py`
   - `/auth/v1/token-status` 在 active token 场景下，如果 `catalog_read.db` 缺少 `catalog_track_files` 表，当前会因为 `count_playable_tracks()` 抛 sqlite 异常而返回 500。
   - 期望修复：降级为 `playableSongCount = null`，不要把 token 状态查询耦合成目录库健康检查。

2. `src/music_server/services/catalog_reader.py`
   - `list_playlists(platform=...)` 当前对未知平台会静默回退为“全量列表”。
   - 期望修复：只要传了 platform，就按该 platform 过滤；未知平台应返回空集而不是全量。

3. `src/music_server/services/catalog_reader.py`
   - `list_playlist_tracks()` 只按 `position` 排序，没有稳定二级 key。
   - 期望修复：补二级排序，避免 position 重复时跨页抖动。

4. `tests/support.py` 及相关路由测试
   - `auth_headers()` 默认每次都新发 token，会把一次用例里的多次请求弱化成“多 token”场景。
   - 期望修复：让重复请求更容易复用同一个 token。

5. `tests/test_mf_catalog_routes.py`
   - 有一个 `total == page_size` 时断言 `isEnd == false` 的测试，容易固化当前可争议分页语义。
   - 期望修复：放宽或改写这个断言，不把潜在缺陷锁死。

## 中断说明

- 针对上面 5 个问题，已派出 implementer 继续修复。
- 该 implementer 在用户切换任务前被中途打断，状态为 `interrupted`。
- 因此“Task 2 修复版”目前没有经过本会话验证，不应视为完成。

## 当前工作树提醒

- 工作树为 dirty 状态，包含本会话 token binding 相关改动，也包含其它既有改动。
- 暂停这条线时不要回滚无关文件。

## 恢复此任务时建议顺序

1. 先打开：
   - `docs/superpowers/plans/2026-04-20-music-server-token-binding-implementation.md`
   - `docs/superpowers/handoffs/2026-04-20-token-binding-pause.md`
2. 重新检查 Task 2 当前文件状态，确认中断 implementer 没有留下未验证半成品。
3. 仅修复本 handoff 列出的 5 个 code-quality 问题。
4. 重新跑 Task 2 的 39 个相关测试。
5. 再做一次 code quality re-review。
6. Task 2 过关后，再继续 Task 3。

## 下次续做可直接用的提示词

```text
继续处理 D:\source\musicdl-catalog-sync-worktrees\Music_Server 的 token binding implementation。
先打开：
1. docs/superpowers/plans/2026-04-20-music-server-token-binding-implementation.md
2. docs/superpowers/handoffs/2026-04-20-token-binding-pause.md

当前状态：
- Task 1 已完成并验证通过
- Task 2 功能与 spec review 已通过
- Task 2 code quality review 还剩 5 个问题待修

请先核对当前文件状态，再只修复 handoff 中列出的 5 个 Task 2 问题，跑完 39 个相关测试，并完成 code quality re-review。
```