refactor: /download 同步分支拆解（120 行 / 圈 19 → 78 行 / 圈 14）

为什么：单曲下载提交入口的 format=json 同步分支内嵌了完整事务
（取信息 → 下载 → 组响应 → 结算/退款，40 行），与参数校验、后台任务
登记混在一个函数里；可选参数解析 5 行两模式共用却内联两处。

拆出：
- _parse_download_options：两模式共用的可选参数解析（lyric_format
  非法静默回退 lrc 的历史口径保留）
- _sync_download_json：同步下载事务整体——任一步失败退预扣（账本
  守恒），只有成功才 settle(1, 'delivered')，docstring 写明语义

先写测试后动代码：新增 tests/test_download_sync.py 5 例，在未改动
实现上跑绿（修正 1 例预期：默认 filename_format=artist_song 产出
「歌手 - 歌名.mp3」），覆盖此前零测试的 json 同步分支——成功结算
余额恰 -1、取信息失败 404 退款、下载失败/异常退款、空 ID 专属文案。
门禁：ruff 全过 · pyright 0/0 · pytest 375 passed（370→375）。

web/routers/download.py

@@ -46,6 +46,75 @@ def _parse_meta_fields(raw: Any):
     return parse_meta_fields(raw)
 
 
+def _parse_download_options(data: dict[str, Any]) -> tuple:
+    """file/json 两模式共用的可选参数解析。
+
+    返回 (filename_format, write_meta, meta_fields, lyric_format, need_zip)；
+    lyric_format 非法时静默回退 lrc（历史口径）。
+    """
+    filename_format = data.get('filename_format', 'artist_song')
+    write_meta = str(data.get('write_meta', 'true')).lower() in ('1', 'true', 'yes')
+    meta_fields = _parse_meta_fields(data.get('meta_fields'))
+    lyric_format = data.get('lyric_format', 'lrc')
+    if lyric_format not in ('lrc', 'srt'):
+        lyric_format = 'lrc'
+    need_zip = str(data.get('zip', 'false')).lower() in ('1', 'true', 'yes')
+    return filename_format, write_meta, meta_fields, lyric_format, need_zip
+
+
+async def _sync_download_json(downloader, music_id: str, quality: str, cookies: dict,
+                              filename_format: str, write_meta: bool, meta_fields,
+                              billing, ip: str):
+    """format=json 的同步下载分支：取信息 → 下载 → 组响应 → 结算。
+
+    语义：任一步失败退回预扣（账本守恒），只有成功才 settle(1, 'delivered')。
+    """
+    try:
+        info = await asyncio.to_thread(
+            downloader.get_music_info, int(music_id), quality, cookies)
+    except Exception as e:
+        logger.error('获取音乐信息失败: %s', e)
+        await billing.refund_open('rejected')
+        return error('获取失败：歌曲不存在或暂无版权', 404)
+    from services._shared import _build_download_base
+    base = await asyncio.to_thread(
+        _build_download_base, filename_format,
+        {'name': info.name, 'artist_string': info.artists})
+    filename = f'{base}.{info.file_type}'
+    try:
+        dl = await asyncio.to_thread(
+            downloader.download_music_file, int(music_id), quality,
+            write_meta=write_meta, meta_fields=meta_fields,
+            cookies=cookies, music_info=info)
+        if not dl.success:
+            logger.error('下载失败: %s', dl.error_message)
+            await billing.refund_open('rejected')
+            return error('下载失败，请稍后重试或更换音质', 500)
+    except Exception as e:
+        logger.error('下载异常: %s', e)
+        await billing.refund_open('rejected')
+        return error('服务暂时不可用，请稍后再试', 500)
+    try:
+        _record_log('下载', ip, info.name)
+    except Exception:
+        pass
+    response_data = {
+        'music_id': music_id,
+        'name': info.name,
+        'artist': info.artists.replace('/', ', '),
+        'album': info.album,
+        'quality': quality,
+        'quality_name': media.quality_display_name(quality),
+        'file_type': info.file_type,
+        'file_size': info.file_size,
+        'file_size_formatted': media.format_file_size(info.file_size),
+        'filename': filename,
+        'duration': info.duration * 1000,
+    }
+    await billing.settle(1, 'delivered')
+    return success(response_data, '下载完成')
+
+
 
 
 def _dedup_ids(raw_ids: Any) -> list[str]:
@@ -72,7 +141,11 @@ async def _resolve_personal(data: dict[str, Any], user: SiteUser | None, request
 
 @router.post('/download')
 async def download(user: Annotated[SiteUser | None, Depends(current_user)], request: Request):
-    """下载单曲（file=后台任务 / json=同步返回）。"""
+    """下载单曲（file=后台任务 / json=同步返回）。
+
+    顺序：限流 → 预扣计费 → 四道参数闸（失败即退款）→ 账号 Cookie →
+    可选参数 → json 同步分支 / file 后台任务分支。
+    """
     await ratelimit.guard(request, bucket='dl', limit=20, window=60)
     data = await _request_data(request)
     music_id = data.get('id')
@@ -107,66 +180,20 @@ async def download(user: Annotated[SiteUser | None, Depends(current_user)], requ
         else:
             cookies = _cookies()
 
-        filename_format = data.get('filename_format', 'artist_song')
-        write_meta = str(data.get('write_meta', 'true')).lower() in ('1', 'true', 'yes')
-        meta_fields = _parse_meta_fields(data.get('meta_fields'))
-        lyric_format = data.get('lyric_format', 'lrc')
-        if lyric_format not in ('lrc', 'srt'):
-            lyric_format = 'lrc'
-        need_zip = str(data.get('zip', 'false')).lower() in ('1', 'true', 'yes')
+        (filename_format, write_meta, meta_fields,
+         lyric_format, need_zip) = _parse_download_options(data)
 
-        from services import downloads as services_downloads
-        from services import tasks as services_tasks
-        from services._shared import _build_download_base
         from services.api_service import api_service
         downloader = api_service.downloader
 
         if return_format == 'json':
-            try:
-                info = await asyncio.to_thread(
-                    downloader.get_music_info, int(music_id), quality, cookies)
-            except Exception as e:
-                logger.error('获取音乐信息失败: %s', e)
-                await billing.refund_open('rejected')
-                return error('获取失败：歌曲不存在或暂无版权', 404)
-            base = await asyncio.to_thread(
-                _build_download_base, filename_format,
-                {'name': info.name, 'artist_string': info.artists})
-            filename = f'{base}.{info.file_type}'
-            try:
-                dl = await asyncio.to_thread(
-                    downloader.download_music_file, int(music_id), quality,
-                    write_meta=write_meta, meta_fields=meta_fields,
-                    cookies=cookies, music_info=info)
-                if not dl.success:
-                    logger.error('下载失败: %s', dl.error_message)
-                    await billing.refund_open('rejected')
-                    return error('下载失败，请稍后重试或更换音质', 500)
-            except Exception as e:
-                logger.error('下载异常: %s', e)
-                await billing.refund_open('rejected')
-                return error('服务暂时不可用，请稍后再试', 500)
-            try:
-                _record_log('下载', ip, info.name)
-            except Exception:
-                pass
-            response_data = {
-                'music_id': music_id,
-                'name': info.name,
-                'artist': info.artists.replace('/', ', '),
-                'album': info.album,
-                'quality': quality,
-                'quality_name': media.quality_display_name(quality),
-                'file_type': info.file_type,
-                'file_size': info.file_size,
-                'file_size_formatted': media.format_file_size(info.file_size),
-                'filename': filename,
-                'duration': info.duration * 1000,
-            }
-            await billing.settle(1, 'delivered')
-            return success(response_data, '下载完成')
+            return await _sync_download_json(
+                downloader, music_id, quality, cookies,
+                filename_format, write_meta, meta_fields, billing, ip)
 
         # file 模式：注册后台任务
+        from services import downloads as services_downloads
+        from services import tasks as services_tasks
         device_id = str(data.get('device_id') or '').strip()[:64]
         await asyncio.to_thread(services_tasks._touch_device, device_id)
         task = _single_task({