refactor: 拆分 4 个巨石模块为包，清理过时注释并删除作废文档

为什么：单文件 1100~1900 行的巨石模块让「改一处要通读全文」；同时注释里残留
大量已删台账的编号，以及「Flask/FastAPI 双栈迁移期」这类已失实的架构描述，
会误导后来者按不复存在的架构去改代码。

拆分（对外导入路径不变，行为零变更）：
- music_downloader.py  -> music_downloader/（models/downloader/cover/_http/_log/_concurrency）
- auth_system.py       -> auth_system/（db/security/users/credits/ledger/mail/cards/backup...）
- music_api.py         -> music_api/（api/client/crypto/qr/cookies/compat/constants/errors）
- services/runtime.py  -> services/（api_service/_shared/_taskcore/downloads/batch/podcast/
  streaming/tasks）；services/runtime.py 保留为兼容门面

兼容性做法：各包用 __init__.py 以 __all__ 原样再导出全部符号，既有调用点
（auth_system.xxx / services.xxx / from music_api import Y）零改动；路径常量改为经包属性
动态读取（auth_system.DB_PATH），否则测试的 monkeypatch 会静默失效并写到生产库。

修复 9 处代码损伤（上一轮注释清理把 `()` 当「空括号残留」删掉所致；用「与拆分前逐字
等价」校验逐一定位，静态检查只会报出其中 4 处）：
- core/config.py  ).strip() or '*'
- core/state.py   threading.Lock() x2
- qr_login.py     datetime.now() / .strip()
- music_downloader/downloader.py  .lower()
- services/podcast.py  set() / time.time() x2

清理与删除：
- 删除 部署文档.md / 功能介绍.md / README_私有包警告.txt
- 清理指向已删台账与文档的过时编号注释；把「迁移期 / 两栈 / 双框架 / 已迁移」等
  失实描述改写为现状描述（保留 `<-> Flask /path` 映射表等仍有价值的契约来源说明）
- _mkpkg.py：公开包剔除清单去掉已不存在的文档名；私有包警告改为自包含
- pyproject.toml：补 pythonpath = ["."]，使裸跑 pytest 不再 import core 失败

验证：ruff 全通过；pyright 0 errors / 0 warnings（102 文件）；pytest 144 passed；
真实 uvicorn 冒烟 6 条路由符合预期且生产 data/ 指纹未变；忽略注释的逐字等价性校验通过。

core/__init__.py

@@ -1,12 +1,12 @@
 # -*- coding: utf-8 -*-
-"""框架无关的核心层（Flask → FastAPI 迁移期两边共用）。
+"""框架无关的核心层。
 
 分层约定：
 - core.config   —— 常量、配置类、路径（无框架依赖，可被任意层导入）
 - core.state    —— 进程内运行时状态容器与锁（纯 threading/collections）
 - core.utils    —— 纯函数工具（字符串/时间/歌词/SRT、短链展开）
-- core.security —— 音频直链签名与校验（密钥由启动时注入，不依赖 Flask）
+- core.security —— 音频直链签名与校验（密钥由启动时注入，不依赖具体框架）
 
-本包**不得**导入 flask / fastapi，也不得持有路由或请求上下文相关知识，
-以便同一套状态与工具在迁移期被新老两个应用同时复用。
+本包**不得**导入 fastapi，也不得持有路由或请求上下文相关知识，
+以便同一套状态与工具被 web/ 应用层与各服务模块同时复用。
 """

core/aiohttp_compat.py

@@ -6,7 +6,7 @@
 `from core import aiohttp_compat as requests`，加 `await`、加 `async def` 即可，
 其余 `.text/.json()/.status_code/.raise_for_status()` 语义保持不变。
 
-与 requests 的语义对齐点（很关键，迁移期不能变）：
+与 requests 的语义对齐点（很关键，不得改动）：
 - 请求本身**不**因 4xx/5xx 抛异常；只有显式 `raise_for_status()` 才抛 `HTTPError`
   （上游风控 429/460 的重试/不重试判断依赖调用方读取 `status_code`，见 music_api.HTTPClient）。
 - 网络异常/超时抛 `RequestException`（含 `Timeout`）。

core/async_bridge.py

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
-"""同步 ↔ 异步桥（迁移期用）。
+"""同步 ↔ 异步桥。
 
-场景：部分调用方仍是同步代码（遗留 Flask 路由、线程池下载器），而服务层已异步。
+场景：部分调用方仍是同步代码（线程池下载器、后台任务线程），而服务层已异步。
 `run_sync(coro)` 把协程提交到**专用后台事件循环线程**执行并阻塞等待结果，
 使同步代码得以调用异步实现，无需把调用链一次性全部改异步。
 

core/config.py

@@ -1,35 +1,35 @@
 # -*- coding: utf-8 -*-
 """集中配置与常量（框架无关）。
 
-自 main.py 原样迁出，语义不变：仅常量、配置类与路径定义。
-不导入 flask/fastapi，不持有任何运行时可变状态（运行时状态见 core.state）。
+仅常量、配置类与路径定义；分层重构未改变任何取值。
+不导入 fastapi，不持有任何运行时可变状态（运行时状态见 core.state）。
 """
 
 import os
 from dataclasses import dataclass
 
-# 站点统一版本号（P3-12/P3-22：/health、/api/info、前端 CHANGELOG 全部以此为准，别处不得硬编码）
+# 站点统一版本号（/health、/api/info、前端 CHANGELOG 全部以此为准，别处不得硬编码）
 APP_VERSION = '2.4.0'
 
-# 交付结果保留期（P1-3/D-1：服务端与前端「领取」入口统一 35 分钟——前端入口保留 35 分钟，
+# 交付结果保留期（/D-1：服务端与前端「领取」入口统一 35 分钟——前端入口保留 35 分钟，
 # 原 30 分钟会在最后 5 分钟让领取必 404）。终态任务记录、任务目录、下载缓存均按此回收。
 RESULT_RETENTION_SECONDS = 35 * 60
 
 
 @dataclass
 class Settings:
-    """服务配置类（原 main.APIConfig；迁移期保留 APIConfig 别名以兼容既有引用）"""
+    """服务配置类（保留 APIConfig 别名以兼容既有引用）"""
 
     host: str = '0.0.0.0'
     port: int = 5000
     debug: bool = False
     downloads_dir: str = 'downloads'
-    # 第 98 条：max_file_size/request_timeout 两个架空字段已删除——请求体上限真实
+    # max_file_size/request_timeout 两个架空字段已删除——请求体上限真实
     # 生效点是 _body_size_limit（业务 2MB/备份 200MB），上游超时在 music_api 各调用点
     log_level: str = 'INFO'
     cors_origins: str = (
         os.environ.get('CORS_ORIGINS') or '*'
-    ).strip() or '*'  # 第 100 条：可经环境变量收敛同源（空值回落默认）
+    ).strip() or '*'  # 可经环境变量收敛同源（空值回落默认）
 
 
 # 向后兼容别名：既有代码/文档沿用 APIConfig 名称
@@ -37,8 +37,8 @@ APIConfig = Settings
 
 
 # 游客个人登录使用的独立 Cookie 文件（与管理员全局 Cookie 分离）。
-# 第 100 条：这是有意的隔离——QRLoginClient 的默认值恰是全局 cookie.txt，
-# 显式传参防误写全局文件；第 91 条起本站任何路径都不再写它（仅构造参数）
+# 这是有意的隔离——QRLoginClient 的默认值恰是全局 cookie.txt，
+# 显式传参防误写全局文件；起本站任何路径都不再写它（仅构造参数）
 USER_COOKIE_FILE = 'user_cookie.txt'
 
 
@@ -47,10 +47,10 @@ PAUSE_AFTER_SECONDS = 40
 CANCEL_AFTER_SECONDS = 30 * 60
 HEARTBEAT_INTERVAL = 15
 
-# 每用户同时在途（排队/运行/暂停）任务上限与全站任务表上限（F20：资源上限）
+# 每用户同时在途（排队/运行/暂停）任务上限与全站任务表上限（资源上限）
 MAX_ACTIVE_TASKS_PER_USER = 5
 MAX_TOTAL_TASKS = 200
-# 第 97 条（P2-2）：终态任务要留表 35 分钟供领取，容量闸只数在途任务——旧口径把
+# 终态任务要留表 35 分钟供领取，容量闸只数在途任务——旧口径把
 # 终态记录计入 200 上限会把全站吞吐封顶在约 5.7 任务/分钟；终态另设更大的滞留
 # 上限保内存有界（1000 ≈ 28 任务/分钟的领取窗口，远高于在途处理能力）
 MAX_TERMINAL_TASKS = 1000
@@ -60,7 +60,7 @@ BATCH_ZIP_CONCURRENCY = 3
 
 
 # 音频直链多重防护（HMAC 签名 + 时效 + 代理流）
-AUDIO_TOKEN_TTL = RESULT_RETENTION_SECONDS + 60  # 第 93 条（P2-4）：= 36 分钟——原 30 分钟
+AUDIO_TOKEN_TTL = RESULT_RETENTION_SECONDS + 60  # = 36 分钟——原 30 分钟
 # 大于交付/解析结果 35 分钟保留期 60 秒：交付窗口末段试听不再 403（旧 30 分钟口径矛盾已修）
 AUDIO_URL_KEYS = {'url', 'audioUrl'}
 AUDIO_HOST_MARKS = ('126.net', 'music.126.net', '.netease')

core/db.py

@@ -26,7 +26,7 @@ DATA_DIR = Path(os.environ.get('SITE_DATA_DIR', 'data'))
 DB_PATH = DATA_DIR / 'site.db'
 
 # 锁按事件循环隔离：asyncio.Lock 绑定创建它的 loop，跨 loop 复用会抛
-# "bound to a different event loop"（迁移期 FastAPI loop + 同步桥 loop + 测试各自
+# "bound to a different event loop"（应用主 loop + 同步桥 loop + 测试各自
 # 的 loop 并存，必须分开持有）。
 _LOOP_LOCKS: dict[tuple[int, str], asyncio.Lock] = {}
 

core/http_client.py

@@ -25,7 +25,7 @@ import aiohttp
 DEFAULT_TIMEOUT = 30
 DEFAULT_MAX_BYTES = 8 * 1024 * 1024
 
-# 第 95 条（P2-6）/第 98 条口径：UA 与 Referer 由调用方传入（music_api.APIConstants）
+# UA 与 Referer 由调用方传入（music_api.APIConstants）
 _EMPTY: Mapping[str, str] = {}
 
 
@@ -109,7 +109,7 @@ class AsyncHTTPClient:
     async def _session_for_loop(self) -> aiohttp.ClientSession:
         """按事件循环隔离 session。
 
-        迁移期同一进程内可能有两个 loop（FastAPI 主 loop + 遗留 Flask 的同步桥 loop）。
+        同一进程内可能有两个 loop（应用主 loop + 同步桥的后台 loop）。
         aiohttp 的 ClientSession 不能跨 loop 复用，故按 loop 分别持有。
         """
         key = id(asyncio.get_running_loop())

core/media.py

@@ -2,7 +2,7 @@
 """媒体相关的纯函数（文件大小/音质显示名/Cookie 串解析）——框架无关。
 
 与 main.MusicAPIService 上的同名方法保持逐字一致的实现，
-供 FastAPI 栈直接复用，避免两栈各写一份而漂移。
+供 web/ 应用层与服务模块直接复用，避免各写一份而漂移。
 """
 
 

core/net.py

@@ -2,15 +2,15 @@
 """客户端 IP 解析工具（框架无关）。
 
 从 auth_system 抽出：可信反代判定与 XFF/X-Real-IP 解析规则。
-Flask 侧原本经 request.headers 取头；FastAPI 侧由 web.ratelimit 传入 header 值调用，
+调用方（web.ratelimit / web.deps）从请求头取值后传入，
 故此处只保留纯函数（不依赖任何 Web 框架）。
 """
 
 
 def is_loopback_ip(ip: str) -> bool:
-    """可信反代判定（第 91 条 P2-4：从"所有内网源"收窄为仅回环地址）。
+    """可信反代判定（从"所有内网源"收窄为仅回环地址）。
     服务绑 0.0.0.0 时内网任意主机都可直连伪造 XFF/X-Real-IP 轮换绕过限流与
-    登录锁定（实测实锤）；同机 Caddy 反代（127.0.0.1 → Flask）不受影响。"""
+    登录锁定（实测实锤）；同机 Caddy 反代（127.0.0.1 → 本服务）不受影响。"""
     try:
         import ipaddress
         addr = ipaddress.ip_address(ip)
@@ -22,7 +22,7 @@ def is_loopback_ip(ip: str) -> bool:
 
 
 def trusted_proxy_ip(header_value: str) -> str:
-    """第 97 条（P2-1）：从可信反代转发的 X-Forwarded-For 中取最右一个可解析 IP。
+    """从可信反代转发的 X-Forwarded-For 中取最右一个可解析 IP。
     最右段是可信反代（Caddy）追加的直连方地址；最左段与 X-Real-IP 均可被客户端
     伪造（Caddy 默认不改写客户端自带的 X-Real-IP），采信它们等于给限流/锁定/省份
     记录开了伪造口。无有效值返回空串，调用方回落 remote_addr。"""

core/repo.py

@@ -1,11 +1,11 @@
 # -*- coding: utf-8 -*-
-"""站点数据异步读写仓储（FastAPI 栈用）。
+"""站点数据异步读写仓储。
 
 直接读写 auth_system 建立的同一份 SQLite（同一 DB_PATH / 同一 schema），
 但走 core.db 的 aiosqlite 异步层——读并发、写串行、WAL 读写同时进行。
 
 设计约束：本模块**不改动** auth_system 既有 schema，只做读写；字段口径与
-auth_system 保持一致（键名、默认值）。迁移期两条栈共存、共库。
+auth_system 保持一致（键名、默认值），读写同一份库文件。
 """
 from typing import Any
 

core/security.py

@@ -1,9 +1,9 @@
 # -*- coding: utf-8 -*-
 """音频直链多重防护（HMAC 签名 + 时效 + 代理流）——框架无关。
 
-自 main.py 原样迁出，唯一改动是把密钥来源从 Flask 的 `app.secret_key`
-改为**启动时注入**（`init_secret_key`），从而解除对本模块对 Flask app 的依赖；
-签名/校验算法与口径保持逐字一致，迁移期新旧应用共用同一密钥即可互认 token。
+密钥来源为**启动时注入**（`init_secret_key`），不依赖任何 Web 框架；
+签名与校验算法逐字保持与历史实现一致，
+故存量客户端已持有的直链 token 仍然有效。
 """
 
 import base64

core/session.py

@@ -1,12 +1,12 @@
 # -*- coding: utf-8 -*-
-"""Flask 会话 Cookie 与 Starlette/FastAPI 的互操作。
+"""Flask 兼容的会话 Cookie 编解码（itsdangerous 签名格式）。
 
 Flask 默认会话即 itsdangerous 签名 Cookie（`session` cookie，格式 `payload.timestamp.hmac`，
-payload 为 compact JSON、值类型化 `{"site_uid":{" b":i"4":".."}}`）。迁移期要让
-「Flask 签发的会话在 FastAPI 侧可读、FastAPI 刷新后可被 Flask 读回」，
-本模块给出同一套编解码，避免两栈各签一份、互相看不懂。
+payload 为会话字典的 compact JSON；bytes/datetime/tuple 等类型会被 Flask 打上
+单字符标签再包一层）。本站早期由 Flask 签发会话，为让**存量 Cookie 无需重新登录即可继续使用**，
+本模块复刻同一套编解码（同格式、同密钥、同摘要算法）。
 
-密钥同源：都取自 auth_system.get_secret_key()（data/secret.key）。
+密钥同源：取自 auth_system.get_secret_key()（data/secret.key）。
 """
 import base64
 import hashlib

core/state.py

@@ -1,13 +1,13 @@
 # -*- coding: utf-8 -*-
 """进程内运行时状态（框架无关）。
 
-自 main.py 原样迁出：这些容器全部**原地修改**（永不重新绑定），因此
-`from core.state import DOWNLOAD_TASKS` 与 main 内的旧引用共享同一对象，
+自原单体模块迁出：这些容器全部**原地修改**（永不重新绑定），因此
+`from core.state import DOWNLOAD_TASKS` 与各模块的引用共享同一对象，
 搬移不改变任何并发行为。
 
 注意：这些状态**仅存于进程内存**，重启即丢（任务记录/限流桶/统计/缓存）；
 持久数据（账本/用户/设置）在 SQLite（auth_system）。集中在此以便
-Flask/FastAPI 迁移期共用，并为后续封装成带锁的单例（State 对象）留出唯一入口。
+web/ 与各服务模块共用，并为后续封装成带锁的单例（State 对象）留出唯一入口。
 
 依赖仅限标准库 threading/collections——任何下载器/HTTP 相关对象
 （如批量打包信号量）不放在这里，随对应服务模块搬迁。
@@ -62,8 +62,8 @@ GLOBAL_MUSIC_U_CACHE = {'v': None, 'ts': 0.0}
 
 # 服务器网易云账号昵称缓存（10 分钟）：非管理员可见响应中遮蔽真实昵称
 SERVER_NICK_CACHE = {'nick': None, 'ts': 0.0}
-SERVER_NICK_LOCK = threading.Lock()  # 第 91 条（P3-9）：刷新单飞锁，防并发重复打上游
-VIP_PROBE_LOCK = threading.Lock()  # 第 100 条：音质探测单飞锁（有界等待）
+SERVER_NICK_LOCK = threading.Lock()  # 刷新单飞锁，防并发重复打上游
+VIP_PROBE_LOCK = threading.Lock()  # 音质探测单飞锁（有界等待）
 
 # 全局账号 VIP 探测缓存（5 分钟）：probe 一次要打 8 次网易云接口，
 # 公网下账号栏高频刷新会连累服务器账号触发风控。

core/utils.py

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
-"""纯函数工具（框架无关，无 Flask/FastAPI 依赖）。
+"""纯函数工具（框架无关，无 Web 框架依赖）。
 
-自 main.py 原样迁出：安全整数解析、控制台输出兜底、SRT 时间轴、
+安全整数解析、控制台输出兜底、SRT 时间轴、
 LRC→SRT 转换、字段参数解析、163cn.tv 短链展开（含私有缓存）。
 """
 
@@ -42,7 +42,7 @@ def srt_time(t: float) -> str:
 
 def format_lyric(lrc: str, lyric_format: str) -> str:
     """将 LRC 歌词转换为指定格式（lrc / srt）
-    F37：时间轴先规范化再转 SRT——支持一行多时间标签（同句多时段各自成条）、
+    时间轴先规范化再转 SRT——支持一行多时间标签（同句多时段各自成条）、
     分钟超两位（[100:00]）、乱序行（排序后区间不再倒挂）、纯文本行（无时间戳则原样保留）。"""
     if lyric_format != 'srt':
         return lrc
@@ -111,7 +111,7 @@ def expand_shortlink(url: str) -> str:
         expanded = response.headers.get('Location', url)
     except Exception:
         expanded = url
-    # 第 97 条（P3）：展开失败（Location 缺失/网络异常，expanded 原样等于 url）不写
+    # 展开失败（Location 缺失/网络异常，expanded 原样等于 url）不写
     # 缓存——旧口径一次网络抖动会让该分享链接在整个缓存存续期内必然解析失败
     if expanded != url:
         with _SHORTLINK_CACHE_LOCK: