refactor: 两个根级游离模块并入 music_api 包，消除分层倒置

为什么：podcast_api.py(560 行) 与 qr_login.py(397 行) 既不属于任何包、也不是
入口脚本，却同时被 services 层与 web 层引用——`services/downloads.py` 直接
`from qr_login import ...`、`services/podcast.py` 直接 `import podcast_api`，
业务层反向依赖顶层游离模块，是本次架构体检里唯一的无争议分层倒置。
两者本就依赖 music_api（前者取 url_v1/APIConstants/APIException，后者取
QRLoginManager），与 music_api 下已有的 qr.py / compat.py 是同一层的同类物。

迁移（git 保留重命名历史）：
- podcast_api.py -> music_api/podcast.py
- qr_login.py    -> music_api/qr_client.py

**命名避让**：不叫 music_api/qr_login.py——music_api/__init__ 已经从 .compat
导出了一个**同名函数** qr_login，同名子模块会与之互相遮蔽。改叫 qr_client
（其核心导出即 QRLoginClient），并在验证里专门确认 music_api.qr_login 仍是
可调用函数、music_api.podcast 是模块，两者不冲突。

内部导入顺带改为精确子模块，不再绕道包门面：
- podcast.py：from music_api import APIConstants/APIException/url_v1
  → from .compat import url_v1 / from .constants import ... / from .errors import ...
- qr_client.py：删掉那层 try/except ImportError 包装（它给的是「请确保
  music_api.py 文件存在」这类顶层脚本时代的提示，作为包内模块已无意义），
  改 from .cookies/.errors/.qr 相对导入
- CLI 用法文本 python qr_login.py → python -m music_api.qr_client
  （相对导入后直接跑脚本会失败，必须走 -m；全仓确认无脚本/文档引用旧入口）
- 路径安全性已核对：qr_client 用的是 CWD 相对的 cookie.txt，不是 __file__ 相对，
  迁移不改其解析结果

引用点全部更新（AST 扫描确认覆盖全集，替换后残留 0）：
- podcast：services/podcast.py(1 + 5 处调用) · web/routers/podcast.py(1 + 6)
  · web/routers/download.py(2 处函数内 + 3)，导入名统一为 `podcast`
- qr_login：services/downloads.py · web/routers/admin.py · web/routers/user.py(×2)
- services/__init__.py 依赖自检列表去掉这两个名字（已并入 music_api）
- pyproject include 去掉两个顶层文件名（music_api 目录已覆盖）

验证：
- 11 + 3 个符号在新位置全部 hasattr 通过；podcast_api / qr_login 已
  ModuleNotFoundError；6 个调用方模块均可 import；services 依赖自检仍生效
- 门禁：ruff 0 · pyright 0 errors/0 warnings · pytest 184 passed
- 真实 uvicorn 冒烟 10/10，含 /podcast/parse 与 /podcast/hot 返回 401
  （模块导入失败会是 500，路由缺失会是 404，401 证明两者都正常）
- 生产 data/ 指纹 before == after

.dockerignore

@@ -18,7 +18,7 @@ _test_podcast_api.py
 # 真实凭据、用户数据库、密钥、日志、交接文档、运维脚本与审查工作目录
 cookie.txt
 user_cookie.txt
-# Cookie 备份（qr_login._backup_cookie 产生，含真实 MUSIC_U）：
+# Cookie 备份（music_api.qr_client._backup_cookie 产生，含真实 MUSIC_U）：
 # 原模式 *.cookie.backup.* 与实际文件名 cookie.backup.*.txt 不匹配，排除形同虚设
 cookie.*.txt
 user_cookie.*.txt

_mkpkg.py

@@ -24,7 +24,7 @@ ignore = shutil.ignore_patterns(
     '_audit_work*',
     # .zcode 为 AI 工具工作目录（内部规划/会话文件），不得进任何分发包
     '.zcode*',
-    # Cookie 备份文件（qr_login._backup_cookie 产生，含真实 MUSIC_U）：
+    # Cookie 备份文件（music_api.qr_client._backup_cookie 产生，含真实 MUSIC_U）：
     # 'cookie.*.txt' 匹配 cookie.prewrite/backup/logout.*.txt 但不匹配 cookie.txt 本身
     'cookie.*.txt', 'user_cookie.*.txt')
 

music_api/podcast.py

@@ -22,7 +22,10 @@ import time
 from typing import Any
 
 from core import sync_http as requests  # 同步门面（底层 aiohttp）
-from music_api import APIConstants, APIException, url_v1
+
+from .compat import url_v1
+from .constants import APIConstants
+from .errors import APIException
 
 
 class PodcastConstants:

music_api/qr_client.py

@@ -16,13 +16,9 @@ import sys
 import time
 from pathlib import Path
 
-try:
+from .cookies import load_cookies
-    from music_api import APIException, QRLoginManager, load_cookies
+from .errors import APIException
-except ImportError as e:
+from .qr import QRLoginManager
-    print(f"导入模块失败: {e}")
-    print("请确保 music_api.py 文件存在且可用")
-    sys.exit(1)
-
 
 # 判断 cookie 是否"有效"：包含任一关键字段即可
 IMPORTANT_COOKIE_KEYS = ("MUSIC_U", "__csrf", "NMTID")
@@ -342,7 +338,7 @@ def main():
 
         elif command in ('help', '-h', '--help'):
             print("网易云音乐二维码登录工具")
-            print("\n用法: python qr_login.py [命令]")
+            print("\n用法: python -m music_api.qr_client [命令]")
             print("\n命令:")
             print("  login   - 执行二维码登录")
             print("  status  - 显示登录状态")
@@ -353,7 +349,7 @@ def main():
 
         else:
             print(f"未知命令: {command}")
-            print("使用 'python qr_login.py help' 查看帮助")
+            print("使用 'python -m music_api.qr_client help' 查看帮助")
             sys.exit(1)
 
     # 交互模式

pyproject.toml

@@ -57,7 +57,7 @@ ignore = [
     "RUF012",  # 常量类可变默认值：APIConstants/PodcastConstants 是常量表，非实例状态
     "S305",    # AES-ECB：网易云 weapi 协议**要求**的加密模式，非可自由选择
     "S311",    # randrange：生成上游 requestId（协议随机数），非安全用途
-    "ASYNC250",  # input()：qr_login 交互式 CLI 的人类输入，异步化无意义
+    "ASYNC250",  # input()：music_api.qr_client 交互式 CLI 的人类输入，异步化无意义
     "S310",    # urllib：仅用于音频 Range 代理的 URL 校验路径
 ]
 
@@ -88,8 +88,6 @@ include = [
     "music_api",
     "auth_system",
     "music_downloader",
-    "podcast_api.py",
-    "qr_login.py",
     "_mkpkg.py",
 ]
 exclude = [".venv", ".zcode", "data", "downloads", "templates", "static"]

services/__init__.py

@@ -21,7 +21,7 @@
 import importlib
 import sys
 
-for _dep in ('auth_system', 'podcast_api', 'music_api', 'music_downloader', 'qr_login'):
+for _dep in ('auth_system', 'music_api', 'music_downloader'):
     try:
         importlib.import_module(_dep)
     except ImportError as _exc:

services/downloads.py

@@ -24,12 +24,12 @@ from music_api import (
     account_info,
     detect_vip_by_probe,
 )
+from music_api.qr_client import QRLoginClient
 from music_downloader import (
     DownloadCanceled,
     DownloadException,
     fetch_cover_bytes,
 )
-from qr_login import QRLoginClient
 
 from ._shared import (
     _build_download_base,

services/podcast.py

@@ -12,13 +12,13 @@ from pathlib import Path
 from typing import Any
 
 import auth_system
-import podcast_api
 from core.state import (
     DOWNLOAD_TASKS,
     DOWNLOAD_TASKS_LOCK,
 )
 from music_api import (
     APIException,
+    podcast,
 )
 from music_downloader import (
     DownloadCanceled,
@@ -121,7 +121,7 @@ def _podcast_resolve_audio(program: dict[str, Any], quality: str,
     song_id = program.get('main_song_id')
     if not song_id:
         raise DownloadException("该单集缺少音频信息（mainSong）")
-    url_info = podcast_api.resolve_episode_url(song_id, cookies, quality)
+    url_info = podcast.resolve_episode_url(song_id, cookies, quality)
     if not url_info or not url_info.get('url'):
         raise DownloadException("未获取到音频直链（单集可能已下架或受版权限制）")
     return url_info
@@ -151,7 +151,7 @@ def _podcast_download_worker(task_id: str) -> None:
         cookies = params['cookies']
         remote_ip = params.get('remote_ip') or '-'
 
-        program = podcast_api.get_program_detail(program_id, cookies)
+        program = podcast.get_program_detail(program_id, cookies)
         url_info = _podcast_resolve_audio(program, quality, cookies)
 
         serial = int(program.get('serial_num') or 0)
@@ -315,14 +315,14 @@ def _podcast_zip_worker(task_id: str) -> None:
 
         # 组装单集清单：整台电台（正序全量）或指定单集ID列表
         if radio_id:
-            episodes = podcast_api.list_radio_all_program_ids(radio_id, cookies, max_count=limit)
+            episodes = podcast.list_radio_all_program_ids(radio_id, cookies, max_count=limit)
             if not episodes:
                 raise DownloadException("该电台暂无可下载的单集")
         else:
             episodes = []
             for pid in (preset_ids or []):
                 try:
-                    prog = podcast_api.get_program_detail(pid, cookies)
+                    prog = podcast.get_program_detail(pid, cookies)
                     episodes.append({
                         'id': prog['id'],
                         'name': prog['name'],
@@ -394,7 +394,7 @@ def _podcast_zip_worker(task_id: str) -> None:
                         label = f"[{idx}/{len(episodes)}] {ep['name'][:24]}"
                         _update_progress(f"{label} 解析中...")
                         try:
-                            prog = ep.get('detail') or podcast_api.get_program_detail(ep['id'], cookies)
+                            prog = ep.get('detail') or podcast.get_program_detail(ep['id'], cookies)
                             url_info = _podcast_resolve_audio(prog, quality, cookies)
                             _update_progress(f"{label} 下载中...")
                             ext = (url_info.get('type') or 'mp3').lower().lstrip('.')

tests/test_zip_workers.py

@@ -383,7 +383,7 @@ def podcast_stub(monkeypatch, sandbox):
     monkeypatch.setattr(podcast_svc, '_podcast_resolve_audio', fake_resolve)
     monkeypatch.setattr(podcast_svc, '_podcast_stream_download', fake_stream)
     monkeypatch.setattr(podcast_svc, 'fetch_cover_bytes', lambda _u: None)
-    monkeypatch.setattr(podcast_svc.podcast_api, 'get_program_detail', fake_detail)
+    monkeypatch.setattr(podcast_svc.podcast, 'get_program_detail', fake_detail)
     return sandbox
 
 

web/routers/admin.py

@@ -47,7 +47,7 @@ AdminUser = Annotated[SiteUser, Depends(_require_admin)]
 
 
 def _admin_client():
-    from qr_login import QRLoginClient
+    from music_api.qr_client import QRLoginClient
     return QRLoginClient()
 
 

web/routers/download.py

@@ -316,10 +316,10 @@ async def podcast_download(user: Annotated[SiteUser | None, Depends(current_user
         if not raw:
             await billing.refund_open('rejected')
             return error("参数 'id' 不能为空", 400)
-        import podcast_api
+        from music_api import podcast
         quality = _podcast_quality(data)
         need_zip = str(data.get('zip', 'false')).lower() in ('1', 'true', 'yes')
-        ref = podcast_api.extract_podcast_ref(raw)
+        ref = podcast.extract_podcast_ref(raw)
         if ref['kind'] == 'radio':
             await billing.refund_open('rejected')
             return error('这是电台链接，请先解析电台后选择单集下载，或使用「打包整个播客」')
@@ -388,16 +388,16 @@ async def podcast_batch_zip(user: Annotated[SiteUser | None, Depends(current_use
         # 引用它（radio_id 为假则取 id_list）——先绑定，避免异常/类型检查下的未绑定名
         id_list: list[str] = []
 
-        import podcast_api
+        from music_api import podcast
         if raw_radio:
-            ref = podcast_api.extract_podcast_ref(raw_radio)
+            ref = podcast.extract_podcast_ref(raw_radio)
             if ref['kind'] == 'program':
                 await billing.refund_open('rejected')
                 return error('这是单集链接，请使用「下载单集」或直接输入电台链接/ID')
             radio_id = ref['id']
             radio_name = ''
             try:
-                radio_name = podcast_api.get_radio_detail(radio_id, cookies).get('name', '')
+                radio_name = podcast.get_radio_detail(radio_id, cookies).get('name', '')
             except APIException:
                 pass
         else:

web/routers/podcast.py

@@ -7,7 +7,7 @@
 - POST/GET /api/v1/podcast/search   ↔ Flask /podcast/search
 - POST/GET /api/v1/podcast/hot      ↔ Flask /podcast/hot
 
-说明：podcast_api 仍是同步模块（requests），此处以 asyncio.to_thread 包装，
+说明：music_api.podcast 是同步模块（底层 core.sync_http），此处以 asyncio.to_thread 包装，
 让阻塞的上游调用不占用事件循环——行为不变，且不阻塞其它请求。
 """
 import asyncio
@@ -15,9 +15,8 @@ from typing import Annotated
 
 from fastapi import APIRouter, Depends, Request
 
-import podcast_api
 from core import media
-from music_api import APIException
+from music_api import APIException, podcast
 from web import ratelimit
 from web.deps import SiteUser, require_login
 from web.request_utils import cookies as _cookies
@@ -53,7 +52,7 @@ async def podcast_parse(_user: LoginUser, request: Request):
     cookies = _cookies()
     try:
         result = await asyncio.to_thread(
-            podcast_api.parse_podcast_ref, raw, cookies, page_size=page_size)
+            podcast.parse_podcast_ref, raw, cookies, page_size=page_size)
     except APIException as e:
         return error(str(e), 404)
     except Exception:
@@ -66,7 +65,7 @@ async def podcast_parse(_user: LoginUser, request: Request):
         if song_id:
             try:
                 url_info = await asyncio.to_thread(
-                    podcast_api.resolve_episode_url, song_id, cookies, quality)
+                    podcast.resolve_episode_url, song_id, cookies, quality)
             except Exception:
                 url_info = None
         if url_info:
@@ -112,7 +111,7 @@ async def podcast_programs(_user: LoginUser, request: Request):
         return error('无效的电台 ID')
     try:
         result = await asyncio.to_thread(
-            podcast_api.get_radio_programs, radio_id, _cookies(),
+            podcast.get_radio_programs, radio_id, _cookies(),
             limit=limit, offset=offset, asc=asc)
         return success(result, '获取单集列表成功')
     except APIException as e:
@@ -136,7 +135,7 @@ async def podcast_search(_user: LoginUser, request: Request):
         search_type = 'all'
     try:
         result = await asyncio.to_thread(
-            podcast_api.search_podcast, keyword, _cookies(),
+            podcast.search_podcast, keyword, _cookies(),
             limit=limit, offset=offset, search_type=search_type)
         return success(result, '播客搜索完成')
     except APIException as e:
@@ -155,13 +154,13 @@ async def podcast_hot(_user: LoginUser, request: Request):
     cate_id = data.get('cate_id') or None
     try:
         radios = await asyncio.to_thread(
-            podcast_api.get_hot_radios, _cookies(), limit=limit, offset=offset, cate_id=cate_id)
+            podcast.get_hot_radios, _cookies(), limit=limit, offset=offset, cate_id=cate_id)
     except APIException as e:
         return error(str(e), 404)
     except Exception:
         return error('服务暂时不可用，请稍后再试', 500)
     try:
-        categories = await asyncio.to_thread(podcast_api.get_categories)
+        categories = await asyncio.to_thread(podcast.get_categories)
     except APIException:
         categories = []
     # 满页视为可能还有更多

web/routers/user.py

@@ -81,7 +81,7 @@ async def _mask(nick: str, user: SiteUser | None) -> str:
 async def user_qr_create(request: Request):
     """生成个人登录二维码（返回 SVG）。"""
     await ratelimit.guard(request, bucket='free', limit=30, window=60)
-    from qr_login import QRLoginClient
+    from music_api.qr_client import QRLoginClient
 
     try:
         client = QRLoginClient('user_cookie.txt')
@@ -116,7 +116,7 @@ async def user_qr_check(
     unikey = data.get('unikey')
     if not unikey:
         return error('缺少 unikey 参数')
-    from qr_login import QRLoginClient
+    from music_api.qr_client import QRLoginClient
 
     try:
         client = QRLoginClient('user_cookie.txt')