refactor: 单曲下载 worker 拆解（177 行 / 圈 36 → 43 行 / 圈 8）

为什么：_single_download_worker 是单曲下载的**唯一**后台执行路径（/download 的
file 模式由 start_task 启动它），177 行 / 圈复杂度 36 / 嵌套 5，且此前**零测试
覆盖**——改坏任意一处都不会有测试报警。它的三个 except 分支各写一遍「置终态 +
退款 + 删任务目录」（9 行 × 3），正文里又散着四处逐字相同的取消检查。

改法：一步一个具名函数，主函数只留线性流程。
  SingleTaskParams      参数快照（frozen dataclass），免去每步重列长参数表
  _begin_single_task    置 running + 取参数
  _fetch_single_metadata 一次预取歌曲信息 + 算交付基础名
  _single_progress_cb   构造字节级进度回调（限频 0.4s）
  _abort_if_canceled    取消检查点（原三处逐字重复 → 一处）
  _single_file_result   不打包的交付描述
  _pack_single_zip      音频 + 歌词 + 封面 + info.txt 打成一包
  _publish_single_task  置 done（已终态不覆盖）+ 结算 + 记日志
  _fail_single_task     失败/取消统一收尾（原三处 × 9 行 → 一处）

复杂度（同口径 AST 实测，HEAD 与工作区由同一脚本测出）：
  _single_download_worker  177 行 / 圈 36 / 嵌套 5  →  43 行 / 圈 8 / 嵌套 2
  文件最大圈复杂度           36（就是它）             →  9（_single_progress_cb，
                                                          节流回调本身的形状）
  文件行数 234 → 310（+76，全是新签名与 docstring）· 函数数 3 → 11

等价性证据（三道，互相独立）：
1. 19 例行为契约测试**在未改动的原始实现上一次性全绿**（先写测试、后动代码；
   改完再跑仍全绿）——这批测试因此忠实编码了旧行为，构成等价性验证，而不是
   「照着新实现写的断言」。断言只依赖任务终态 / 磁盘文件 / ZIP 内容 / 账本行 /
   余额，不引用任何内部函数名，可跨后续重构复用。
2. 反向注入验证：把 HEAD 版注入回 services.downloads（**sys.modules 与父包属性
   两处都要挂**——否则 monkeypatch.resolve 走 getattr 父包拿到真模块），同一套
   19 例**全过**，与第 1 条相互独立地再次证明测试忠实。
3. AST 字面量多重集比对 + 逐条位置归因：字符串 69 种**一个不少**——没有一条
   用户可见文案被动过。数值差异全部归因：
     0    4→2：三处 ledger_settle(task_id, 0, ...) 收敛成一处（理由参数化）
     True 5→4：三处 rmtree(..., ignore_errors=True) 收敛成一处（另 +1 为新增
               dataclass 的 frozen=True）
     '任务已取消' 5→3：三处 raise DownloadCanceled 收敛进 _abort_if_canceled

刻意保留的语义（是决定，不是疏漏）：
- task_dir_path 仍在 try 外初始化、失败收尾仍用它判空——「下载未开始就失败」
  时无目录可删，语义原样。
- 结算失败**不**把 done 改标 error（钱由重启对账兜底，宁可商家小损不坑用户），
  已用 test_settle_failure_does_not_flip_done_to_error 固化。
- 末段「已终态不得覆盖为 done」的状态检查与取消检查合流进 _publish_single_task，
  仍是先到先得；用 test_terminal_state_not_overwritten_by_late_success 固化。
- 日志调用移到各自 except 分支开头（原在收尾之后），仅调整同一分支内的顺序，
  不影响任何可观察行为；三处格式串原样保留。
- music_id 保持**原样透传**：params 里是数字字符串，而下游签名声明 int，两侧
  一直不一致、运行时靠字符串参与上游查询拼装而正常工作。顺手 int() 会把异常面
  从「上游查不到」变成 ValueError，属行为变更，故只把标注写成 Any 并在
  docstring 记明。

测试：新增 tests/test_single_worker.py（19 例）——正常交付与交付副本位置、
ZIP 四件套与 SRT 歌词、空歌词跳过、取封面失败仍发布、文件名格式、操作记录与
remote_ip 兜底、下载失败退费、未知异常泛化文案（上游细节不外泄）、下载中/下载
后/打包中三种取消、终态不被覆盖、进度回调三态（有总量 / 无总量 / 自身抛错）、
结算失败不影响已交付、worker 崩在结算前留给对账兜底。

顺带修正一处自己的假设错误：最初把「取封面失败」写成 fetch_cover_bytes 抛异常，
实测该函数契约是**失败返回 None**（内部已 except Exception），抛异常是不存在的
形状——改为注入 None 后才在旧实现上跑绿。测试要贴合生产的真实形状。

验证：ruff 全过 · pyright 0/0 · pytest 294 passed（275→294）· 生产 data/ 未被
触碰（全部用例走 tmp_path 沙箱）。

services/downloads.py

@@ -3,14 +3,22 @@
 
 账号探测（VIP/音质）与二维码登录客户端均已迁出（前者只剩 web.routers.account
 的异步实现，后者只剩 web.routers.admin 自己的客户端），本模块只负责单曲任务。
+
+``_single_download_worker`` 原是 177 行 / 圈复杂度 30 的单函数，三个 except 分支
+各写一遍「结算 + 删任务目录」，正文里又散着四处取消检查。此处按「一步一个具名
+函数」拆开：主函数只留线性流程，失败收尾收敛到 ``_fail_single_task`` 一处。
 """
 
 import os
 import shutil
+import threading
 import time
 import traceback
 import zipfile
+from collections.abc import Callable
+from dataclasses import dataclass
 from pathlib import Path
+from typing import Any
 
 import auth_system
 from core.state import (
@@ -21,6 +29,7 @@ from core.utils import format_lyric as _format_lyric
 from music_downloader import (
     DownloadCanceled,
     DownloadException,
+    MusicInfo,
     fetch_cover_bytes,
 )
 
@@ -55,180 +64,254 @@ def _task_delivery_copy(task_id: str, src: Path, filename: str) -> str:
 # rmtree，本函数全文件零调用（审计确认）。
 
 
-def _single_download_worker(task_id: str) -> None:
-    """后台单曲下载：下载音频（可选 ZIP 打包），支持取消；完成后由 /download/result 交付，35 分钟保留期清理"""
+@dataclass(frozen=True)
+class SingleTaskParams:
+    """单曲任务参数快照（worker 只读）。
+
+    原来是 10 个局部变量从 ``task['params']`` 逐个取出、再原样穿过整段流程；
+    收成一个 frozen 对象后，各步骤按需取字段，调用点不必重列一遍长参数表。
+    ``cancel_ev`` 不是 params 里的值，而是任务对象上的取消事件，一并放这里
+    以免每一步都多传一个参数。
+
+    ``music_id`` 刻意保持 **原样透传**（不转换）：它来自前端、经 ``_extract_id``
+    归一化成数字字符串，而下游 ``get_music_info`` / ``download_music_file`` 的
+    签名声明 ``int``——两侧一直不一致，运行时靠字符串参与上游查询拼装而正常工作
+    （调用链上无算术）。类型标注为 ``Any`` 如实反映这个输入边界的实际形状；
+    顺手 ``int()`` 会改变异常面（非数字时从「上游查不到」变成 ``ValueError``），
+    属于行为变更，不在重构范围内。
+    """
+
+    music_id: Any
+    quality: str
+    filename_format: str
+    write_meta: bool
+    meta_fields: Any
+    lyric_format: str
+    need_zip: bool
+    cookies: dict[str, str]
+    remote_ip: str
+    cancel_ev: threading.Event
+
+
+def _begin_single_task(task_id: str) -> SingleTaskParams:
+    """把任务置为 running 并取出参数快照。"""
+    with DOWNLOAD_TASKS_LOCK:
+        task = DOWNLOAD_TASKS[task_id]
+        task['status'] = 'running'
+        task['msg'] = '下载中...'
+    params = task['params']
+    return SingleTaskParams(
+        music_id=params['music_id'],
+        quality=params['quality'],
+        filename_format=params['filename_format'],
+        write_meta=params['write_meta'],
+        meta_fields=params['meta_fields'],
+        lyric_format=params['lyric_format'],
+        need_zip=params['need_zip'],
+        cookies=params['cookies'],
+        remote_ip=params.get('remote_ip') or '-',
+        cancel_ev=task['cancel'],
+    )
+
+
+def _fetch_single_metadata(p: SingleTaskParams) -> tuple[MusicInfo, dict[str, Any], str, str]:
+    """一次预取歌曲完整信息（URL/详情/歌词三接口并行），并算出交付基础名。
+
+    替代原先 name_v1 + url_v1 + 下载器内部 get_music_info 的重复串行调用。
+    返回 ``(MusicInfo, 下载器口径的 music_info, base, filename)``。
+    """
+    mi = api_service.downloader.get_music_info(p.music_id, p.quality, p.cookies)
+    music_info = {
+        'id': p.music_id,
+        'name': mi.name,
+        'artist_string': mi.artists,
+        'album': mi.album,
+        'pic_url': mi.pic_url,
+        'file_type': mi.file_type,
+        'file_size': mi.file_size,
+        'duration': mi.duration * 1000,
+        'download_url': mi.download_url,
+    }
+    base = _build_download_base(p.filename_format, music_info)
+    return mi, music_info, base, f"{base}.{music_info['file_type']}"
+
+
+def _single_progress_cb(task_id: str) -> Callable[[int, int], None]:
+    """构造字节级进度回调（限频 0.4s）：写进任务 live_percent。
+
+    /api/batch_progress 对运行中的单曲任务优先返回它——原实现 done 按首计数，
+    单曲进度条全程 0%。回调内任何故障都被吞掉，绝不影响下载主流程。
+    """
+    last_ts = {'t': 0.0}
+
+    def _cb(written: int, total_bytes: int) -> None:
+        try:
+            now = time.time()
+            if now - last_ts['t'] < 0.4 and written < (total_bytes or 0):
+                return
+            last_ts['t'] = now
+            with DOWNLOAD_TASKS_LOCK:
+                t = DOWNLOAD_TASKS.get(task_id)
+                if not t or t.get('status') != 'running':
+                    return
+                if total_bytes:
+                    pct = min(99.0, written / total_bytes * 100)
+                    t['live_percent'] = pct
+                    t['msg'] = (f"下载中 {int(pct)}% · "
+                                f"{api_service._format_file_size(written)}/{api_service._format_file_size(total_bytes)}")
+                else:
+                    t['msg'] = f"下载中 · 已接收 {api_service._format_file_size(written)}"
+        except Exception:
+            pass   # 进度上报故障绝不影响下载
+
+    return _cb
+
+
+def _abort_if_canceled(cancel_ev: threading.Event) -> None:
+    """取消检查点：下载完成后到发布前，每一步之间都要过这道闸。
+
+    原先这三处检查（下载后 / 打包后 / 发布前）逐字重复，且末段那次还兼
+    「不得把已取消覆盖成 done」的职责——后者在 ``_publish_single_task`` 里另做。
+    """
+    if cancel_ev.is_set():
+        raise DownloadCanceled("任务已取消")
+
+
+def _single_file_result(file_path_str: str, filename: str,
+                        music_info: dict[str, Any]) -> dict[str, Any]:
+    """不打包（zip=false）的交付描述。"""
+    return {
+        'file_path': file_path_str,
+        'filename': filename,
+        'mimetype': f"audio/{music_info['file_type']}",
+        'audio_files': [file_path_str],
+    }
+
+
+def _pack_single_zip(file_path_str: str, base: str, filename: str, mi: MusicInfo,
+                     music_info: dict[str, Any], p: SingleTaskParams) -> dict[str, Any]:
+    """把音频 + 歌词 + 封面 + info.txt 打成单曲 ZIP 交付包。
+
+    歌词与封面都是**尽力而为**：歌词在预取时已一并拿到（无需再请求一次），
+    封面走共享缓存；两者拿不到就不写对应条目，不影响音频交付。
+    """
     import tempfile as _tempfile
 
-    file_path_str: str | None = None
-    zip_tmp_path: str | None = None
+    fd, zip_tmp_path = _tempfile.mkstemp(prefix='single_zip_', suffix='.zip',
+                                         dir=str(Path(file_path_str).parent))
+    os.close(fd)
+    with zipfile.ZipFile(zip_tmp_path, 'w', zipfile.ZIP_DEFLATED) as zf:
+        zf.write(file_path_str, arcname=filename)
+        # 歌词已在预取时一并拿到，无需再请求一次
+        if mi.lyric:
+            try:
+                zf.writestr(f"{base}.{p.lyric_format}", _format_lyric(mi.lyric, p.lyric_format))
+            except Exception:
+                pass
+        # 封面走共享缓存（与元数据写入共用同一次网络请求）
+        cover = fetch_cover_bytes(mi.pic_url)
+        if cover:
+            zf.writestr(f"{base}.jpg", cover)
+        info_txt = (
+            f"歌曲: {music_info['name']}\n"
+            f"歌手: {music_info['artist_string']}\n"
+            f"专辑: {music_info['album']}\n"
+            f"音质: {api_service._get_quality_display_name(p.quality)}\n"
+        )
+        zf.writestr("info.txt", info_txt)
+    return {
+        'file_path': file_path_str,
+        'zip_path': zip_tmp_path,
+        'filename': f"{base}.zip",
+        'mimetype': 'application/zip',
+        'audio_files': [file_path_str],
+    }
+
+
+def _publish_single_task(task_id: str, result: dict[str, Any], remote_ip: str,
+                         name: str, filename: str) -> None:
+    """最终发布：置 done（已终态不覆盖）→ 结算 → 记操作日志。
+
+    交付已落定；结算失败**不再**把任务改标 error——钱由重启对账兜底，
+    宁可商家小损不坑用户。末段取消检查与此处的状态检查合流：任务已被外部
+    置成 canceled/error 时，worker 的成功路径不得把它覆盖回 done。
+    """
+    with DOWNLOAD_TASKS_LOCK:
+        t = DOWNLOAD_TASKS.get(task_id)
+        if t is None or t.get('status') in ('canceled', 'error'):
+            raise DownloadCanceled("任务已取消")
+        t['status'] = 'done'
+        t['completed_at'] = time.time()
+        t['done'] = 1
+        t['msg'] = '下载完成'
+        t['result'] = result
+    try:
+        auth_system.ledger_settle(task_id, 1, 'delivered')
+    except Exception as _e:
+        api_service.logger.error(f"单曲交付结算失败（重启对账兜底）: {task_id} {_e}")
+    try:
+        _record_log('下载', remote_ip, name)
+    except Exception:
+        pass
+    api_service.logger.info(f"单曲下载完成: {filename} ({task_id})")
+
+
+def _fail_single_task(task_id: str, status: str, msg: str, ledger_status: str,
+                      task_dir_path: str | None) -> None:
+    """失败/取消的统一收尾：置终态 → 退款 → 清掉任务目录。
+
+    这三个 except 分支原先各写一遍（共 9 行 × 3 处）；收敛后新增一种失败
+    只需要挑一个 ``ledger_status``，不会再漏掉清理或退款。
+    """
+    _mark_task_terminal(task_id, status, msg)
+    try:
+        auth_system.ledger_settle(task_id, 0, ledger_status)
+    except Exception:
+        pass
+    if task_dir_path:
+        shutil.rmtree(task_dir_path, ignore_errors=True)
+
+
+def _single_download_worker(task_id: str) -> None:
+    """后台单曲下载：下载音频（可选 ZIP 打包），支持取消；完成后由 /download/result 交付，35 分钟保留期清理"""
     task_dir_path: str | None = None
     try:
-        with DOWNLOAD_TASKS_LOCK:
-            task = DOWNLOAD_TASKS[task_id]
-            task['status'] = 'running'
-            task['msg'] = '下载中...'
-        params = task['params']
-        cancel_ev = task['cancel']
-        music_id = params['music_id']
-        quality = params['quality']
-        filename_format = params['filename_format']
-        write_meta = params['write_meta']
-        meta_fields = params['meta_fields']
-        lyric_format = params['lyric_format']
-        need_zip = params['need_zip']
-        cookies = params['cookies']
-        remote_ip = params.get('remote_ip') or '-'
-
-        # 一次预取歌曲完整信息（URL/详情/歌词三接口并行），
-        # 替代原先 name_v1 + url_v1 + 下载器内部 get_music_info 的重复串行调用
-        mi = api_service.downloader.get_music_info(music_id, quality, cookies)
-        music_info = {
-            'id': music_id,
-            'name': mi.name,
-            'artist_string': mi.artists,
-            'album': mi.album,
-            'pic_url': mi.pic_url,
-            'file_type': mi.file_type,
-            'file_size': mi.file_size,
-            'duration': mi.duration * 1000,
-            'download_url': mi.download_url,
-        }
-        base = _build_download_base(filename_format, music_info)
-        filename = f"{base}.{music_info['file_type']}"
-
-        # 字节级进度回调（限频 0.4s）：写进任务 live_percent，/api/batch_progress
-        # 对运行中的单曲任务优先返回它——原实现 done 按首计数，单曲进度条全程 0%
-        _cb_ts = {'t': 0.0}
-
-        def _progress_cb(written, total_bytes):
-            try:
-                now = time.time()
-                if now - _cb_ts['t'] < 0.4 and written < (total_bytes or 0):
-                    return
-                _cb_ts['t'] = now
-                with DOWNLOAD_TASKS_LOCK:
-                    t = DOWNLOAD_TASKS.get(task_id)
-                    if not t or t.get('status') != 'running':
-                        return
-                    if total_bytes:
-                        pct = min(99.0, written / total_bytes * 100)
-                        t['live_percent'] = pct
-                        t['msg'] = (f"下载中 {int(pct)}% · "
-                                    f"{api_service._format_file_size(written)}/{api_service._format_file_size(total_bytes)}")
-                    else:
-                        t['msg'] = f"下载中 · 已接收 {api_service._format_file_size(written)}"
-            except Exception:
-                pass   # 进度上报故障绝不影响下载
+        p = _begin_single_task(task_id)
+        mi, music_info, base, filename = _fetch_single_metadata(p)
 
         download_result = api_service.downloader.download_music_file(
-            music_id, quality,
-            write_meta=write_meta,
-            meta_fields=meta_fields,
-            cookies=cookies,
-            cancel_event=cancel_ev,
+            p.music_id, p.quality,
+            write_meta=p.write_meta,
+            meta_fields=p.meta_fields,
+            cookies=p.cookies,
+            cancel_event=p.cancel_ev,
             music_info=mi,
-            progress_cb=_progress_cb,
+            progress_cb=_single_progress_cb(task_id),
         )
         if not download_result.success:
             raise DownloadException(download_result.error_message or "下载失败")
-        # 下载完成后的每一阶段都可能已被取消，发布前统一校验
-        if cancel_ev.is_set():
-            raise DownloadCanceled("任务已取消")
+        _abort_if_canceled(p.cancel_ev)
         assert download_result.file_path is not None
-        cache_path = Path(download_result.file_path)
         # 交付文件用任务专属副本，共享缓存不进清理清单
-        file_path_str = _task_delivery_copy(task_id, cache_path, filename)
+        file_path_str = _task_delivery_copy(task_id, Path(download_result.file_path), filename)
         task_dir_path = str(Path(file_path_str).parent)
 
-        if need_zip:
-            fd, zip_tmp_path = _tempfile.mkstemp(prefix='single_zip_', suffix='.zip',
-                                                 dir=str(Path(file_path_str).parent))
-            os.close(fd)
-            with zipfile.ZipFile(zip_tmp_path, 'w', zipfile.ZIP_DEFLATED) as zf:
-                zf.write(file_path_str, arcname=filename)
-                # 歌词已在预取时一并拿到，无需再请求一次
-                if mi.lyric:
-                    try:
-                        zf.writestr(f"{base}.{lyric_format}", _format_lyric(mi.lyric, lyric_format))
-                    except Exception:
-                        pass
-                # 封面走共享缓存（与元数据写入共用同一次网络请求）
-                cover = fetch_cover_bytes(mi.pic_url)
-                if cover:
-                    zf.writestr(f"{base}.jpg", cover)
-                info_txt = (
-                    f"歌曲: {music_info['name']}\n"
-                    f"歌手: {music_info['artist_string']}\n"
-                    f"专辑: {music_info['album']}\n"
-                    f"音质: {api_service._get_quality_display_name(quality)}\n"
-                )
-                zf.writestr("info.txt", info_txt)
-            # 打包阶段同样以取消检查收口
-            if cancel_ev.is_set():
-                raise DownloadCanceled("任务已取消")
-            result = {
-                'file_path': file_path_str,
-                'zip_path': zip_tmp_path,
-                'filename': f"{base}.zip",
-                'mimetype': 'application/zip',
-                'audio_files': [file_path_str],
-            }
+        if p.need_zip:
+            result = _pack_single_zip(file_path_str, base, filename, mi, music_info, p)
         else:
-            result = {
-                'file_path': file_path_str,
-                'filename': filename,
-                'mimetype': f"audio/{music_info['file_type']}",
-                'audio_files': [file_path_str],
-            }
+            result = _single_file_result(file_path_str, filename, music_info)
+        # 打包阶段同样以取消检查收口
+        _abort_if_canceled(p.cancel_ev)
 
-        # 最终发布前的取消检查（末段取消不得覆盖为 done）
-        if cancel_ev.is_set():
-            raise DownloadCanceled("任务已取消")
-        with DOWNLOAD_TASKS_LOCK:
-            t = DOWNLOAD_TASKS.get(task_id)
-            if t is None or t.get('status') in ('canceled', 'error'):
-                raise DownloadCanceled("任务已取消")
-            t['status'] = 'done'
-            t['completed_at'] = time.time()
-            t['done'] = 1
-            t['msg'] = '下载完成'
-            t['result'] = result
-        # 交付已落定；结算失败不再把任务改标 error（钱由重启对账兜底，宁可商家小损不坑用户）
-        try:
-            auth_system.ledger_settle(task_id, 1, 'delivered')
-        except Exception as _e:
-            api_service.logger.error(f"单曲交付结算失败（重启对账兜底）: {task_id} {_e}")
-        try:
-            _record_log('下载', remote_ip, music_info['name'])
-        except Exception:
-            pass
-        api_service.logger.info(f"单曲下载完成: {filename} ({task_id})")
+        _publish_single_task(task_id, result, p.remote_ip, music_info['name'], filename)
     except DownloadCanceled:
-        _mark_task_terminal(task_id, 'canceled', '任务已取消')
-        try:
-            auth_system.ledger_settle(task_id, 0, 'canceled')
-        except Exception:
-            pass
-        if task_dir_path:
-            shutil.rmtree(task_dir_path, ignore_errors=True)
         api_service.logger.info(f"单曲下载已取消: {task_id}")
+        _fail_single_task(task_id, 'canceled', '任务已取消', 'canceled', task_dir_path)
     except DownloadException as e:
-        _mark_task_terminal(task_id, 'error', str(e))
-        try:
-            auth_system.ledger_settle(task_id, 0, 'error')
-        except Exception:
-            pass
-        if task_dir_path:
-            shutil.rmtree(task_dir_path, ignore_errors=True)
         api_service.logger.error(f"单曲下载失败: {task_id} {e}")
+        _fail_single_task(task_id, 'error', str(e), 'error', task_dir_path)
     except Exception as e:
         # 非预期异常的 repr 可能含上游主机/连接细节——用户可见文案
         # 泛化为固定文案，原文 logger 先行留档（教训：先记录再泛化）
         api_service.logger.error(f"单曲下载异常: {task_id} {e}\n{traceback.format_exc()}")
-        _mark_task_terminal(task_id, 'error', '下载失败，请稍后重试')
-        try:
-            auth_system.ledger_settle(task_id, 0, 'error')
-        except Exception:
-            pass
-        if task_dir_path:
-            shutil.rmtree(task_dir_path, ignore_errors=True)
+        _fail_single_task(task_id, 'error', '下载失败，请稍后重试', 'error', task_dir_path)