musicdl-catalog-sync-suite/Music_Server/docs/superpowers/handoffs/2026-04-20-token-binding-pause.md

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。

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

继续处理 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。