hhhge/NeteaseUrl
Archived
1
0 Fork 0
Code Issues Actions Packages Projects Releases Wiki Activity
80 Commits 1 Branch 0 Tags
e8cc7cb34abff7ddabead5ae90771a271ca29bea
Commit Graph
48 Commits
Author SHA1 Message Date
snowy-yang 046225e38d refactor: aria2 改手写原生异步 JSON-RPC，aria2p 与同步 HTTP 栈从依赖树清零 
为什么：aria2p 内部是 requests + websocket-client 的同步实现，每个 RPC 都是一次
「同步网络 IO 藏在 to_thread 里」——线程池跑得再满也不产生真正的并发，每次轮询
还要额外付一次线程跳转。这是本项目最后一处此类残留，删掉后整个进程的网络 IO
都走同一个 aiohttp 连接池。

改动：
- music_downloader/_aria2.py 整体重写：新增 _Aria2Rpc，直接向 aria2 的
  JSON-RPC 2.0 端点发 getVersion / addUri / tellStatus / forceRemove /
  removeDownloadResult，一律走 core.http_client.request_once（不重试，与 aria2p
  口径一致）；新增 Aria2RpcError 承载 HTTP 200 + error 对象的协议错误。
- _abort 逐条复刻 aria2p.remove(force=True, files=?, clean=True) 语义：终态走
  removeDownloadResult；在途先 forceRemove 再清结果表；控制文件 .aria2 无条件
  删除（clean=True 默认）；仅当 files 且主移除成功才删数据文件。
- get_backend / _try_start 改原生异步：asyncio.Lock 单飞 + await rpc.get_version()
  探活，不再用 to_thread 包 subprocess.Popen；超时路径改 to_thread(_reap) 回收。
- 新增 Protocol _Rpc / _ProcessHandle（补 returncode 声明）——只声明本模块真正
  调用的方法，测试据此用轻量替身驱动状态机，不必依赖真实 aria2 进程。
- pyproject.toml 删 aria2p 依赖并同步更新过时注释；uv lock 连带移除 8 个传递
  依赖：requests / urllib3 / websocket-client / charset-normalizer / loguru /
  platformdirs / win32-setctime。至此全仓无任何 requests 栈。
- tests/test_aria2.py 重写为 21 项用例（_FakeRpc / _FakeProc / _LiveProc /
  _FakeHTTP 替身），新增终态体积守卫、_try_start 三分支（就绪重试 / 超时不就绪
  杀进程 / 进程提前退出）与 JSON-RPC 信封四例。
- tests/test_downloader.py 的 get_backend 替身由同步 lambda 改为协程——调用点
  已直接 await，同步替身会被 await 成 None 而报 TypeError。

验证（在 aria2p 已物理移除的环境上复核，故能真正证明无残留依赖）：
- uv run ruff check .  → All checks passed!
- uv run pyright       → 0 errors, 0 warnings, 0 informations
- uv run pytest        → 392 项，0 失败 / 0 error / 0 skipped（基线 382，净增 10）
- data/site.db sha256 前后一致（a19f5dbf…6487），无 -wal/-shm 残留
 2026-09-29 15:14:56 +08:00
snowy-yang 133beab492 chore: 删除 HTTP 线三个垫片，同步/异步桥接层彻底清零 
删 core/sync_http.py（requests 同形同步门面）、core/async_bridge.py（run_sync
同步↔异步桥）、core/http_errors.py（两垫片共用的 requests 同形异常层次），
以及 tests/test_async_bridge.py。

为什么必须一次删完：三者是**自闭环三角**——sync_http 是 async_bridge 与
http_errors 的唯一消费者，删掉任何一个其余两个立刻悬空。前序 B1 把 worker 变成
协程、B2 把 auth_system 迁到 aiosqlite、更早一轮把 music_api 改走
core.http_client 之后，这条链上的生产消费者已归零；http_errors 更是在 B2 之后
只剩 sync_http 一个使用者（此前 sync_http 的 docstring 还提到
models._RetryFromScratch 继承它的 RequestException——B1 已改为继承 Exception）。

删除前的核查（避免误删活代码）：
- run_sync / get_loop / SyncResponse / Session( 全仓零残留引用（只剩
  aiohttp.ClientSession，那是真正的客户端，不受影响）。
- 所有 HTTPError 命中都是 core.http_client.UpstreamHTTPError——与
  core.http_errors 的 HTTPError **名字像但不是一个东西**，删除时别被 grep 骗。
- requests 早已不是声明依赖、全仓零导入；删掉 http_errors 后连 requests 同形
  异常的最后残影也没了。
- core/__init__.py 只有 docstring，无需改动；web/app.py 的 async_bridge.shutdown()
  已在 B1 移除。

顺带修正两处过时措辞：tests/test_search_music.py 的错误映射注释
RequestException → UpstreamError（异常层次已换）；pyproject.toml 中 pyright
include 的理由注释 requests→sync_http → requests→aiohttp（去掉已删模块名、
保留原意）。auth_system/geo.py 的历史注释本就是过去时，保持不动。

门禁：ruff 全过 / pyright 0-0-0 / pytest 382 项全绿（0 失败 0 error 0 skipped）。
项数 384→382 是 test_async_bridge.py 两条用例**随被测对象一起删除**的预期减项，
不是跳过或漏跑。data/site.db 读写前后 sha256 一致（a19f5db…6487）。

至此「同步调异步 / 异步桥同步」两类垫片全部拆净：DB 线（B1 worker + B2
auth_system）、HTTP 线（本批）。生产代码里 to_thread 仅剩正当的阻塞卸载
（PBKDF2 / smtplib / 备份文件 IO / ZIP 组装 / rmtree），threading.Event 仅剩
取消与暂停的跨线程置位载体。
 2026-09-28 20:18:08 +08:00
snowy-yang 96af56cc27 refactor: auth_system 全面异步化（aiosqlite），拆掉 web/services 层的 to_thread 桥接 
拆掉两类垫片的最后一处：auth_system 原为同步 sqlite3 栈，web 层与 services 的
worker 只能靠 asyncio.to_thread 逐个桥接才不阻塞事件循环——每次 DB 访问都白付一次
线程池调度，且「同步调异步」的边界散落在 100+ 个调用点。B1 已把 worker 变成协程，
本批把访问层本身也迁到原生异步，两条线在此合拢。

改动（按子系统）：
- auth_system：db.py 照 core/db.py 现有范式重建为原生异步访问层（aiosqlite + WAL）
  ——读路径 _q 每次独立连接、无锁、可并发；写路径 _x / write_transaction 用
  asyncio.Lock 串行化，写者不阻塞读者。users / cards / credits / ledger / logs /
  settings / mail / geo / backup 九模块随之全部 async/await；security.py 是纯计算
  （pbkdf2/normalize）不动。__init__ 去掉 _DB_LOCK 与 get_conn 导出。
- web：app / deps / billing / tasks_registry 与 routers/{admin_site,auth,music,
  register,user} 直接 await，拆掉包裹的 to_thread。deps.secret_key 改 async，
  连带 _parse_cookie 也 async（会话解析要读密钥）。
- services：_taskcore / tasks / downloads / podcast 的账本调用与查询直接 await。
  4 处 start_task 调用点（download.py）确认已 await。

设计取舍（为什么这么做，而不是直接包一层）：
- 锁按**事件循环**隔离（_LOOP_LOCKS 以 id(loop) 为键）：asyncio.Lock 绑定创建它的
  loop，应用主 loop 与测试各自的 loop 并存，跨 loop 复用会抛 "bound to a different
  event loop"。
- WAL 切换用**独立锁** _wal_lock 而非 _write_lock：execute() 已持写锁，再在锁内
  connect→_configure 会自锁死（asyncio.Lock 非重入）。切换 + 标记在专用锁内串行并
  二次复查，否则并发首连会同时执行 PRAGMA journal_mode=WAL 争排他锁报
  database is locked（core/db.py 同款教训，实测复现）。
- force_wal 保留：journal_mode 持久化在库文件头，库文件被删重建时新文件不继承，
  必须重设。exists() 判定须在 aiosqlite.connect **之前**（connect 会创建空文件）。
- connect() 用 DB_PATH.parent 兜底建目录，优于 DATA_DIR：生产两者相同，但测试
  monkeypatch 只换 DB_PATH 时兜底仍能命中正确目录。

留在 to_thread 上的仅剩**正当的阻塞卸载**，不是同步门面：PBKDF2 的 10 万次迭代
（登录链路每次都要跑）、smtplib 发信、备份文件的 copy2 / os.replace、secret.key
的文件 IO。原有 aria2 / downloader / zip 侧的 to_thread 未动。

不变量逐条保持（迁移只改执行模型，不改语义）：
- ledger_settle 幂等：账本非 open 直接 return 0，重启后重放不重复退款；
- 终态先到先得：_mark_task_terminal 对已 done/error/canceled 的任务直接 return，
  堵住 canceled→error 的非法迁移边；
- settle 必须在任务锁**外**调用（ledger_settle 要抢 SQLite 写锁，busy 最长 15s，
  持任务锁会让全站进度/提交/取消随库停摆）；
- reserve_and_open 的预扣与开账同事务，消除原两步之间的崩溃丢账窗口。

路径真源红线：DATA_DIR / DB_PATH / BACKUP_DIR / SECRET_KEY_PATH 仍是 auth_system.db
的**模块全局**（用与 core.db 相同的表达式，但**不是**它的别名）。测试只 patch
auth_system.db.*，若改成 core.db 的别名会静默把测试写到生产库。已核 data/site.db
读写前后 sha256 完全一致。
顺带清掉 get_conn：迁移后它只剩「转调 connect()」一层空壳、全仓零消费者（测试
直接开裸连接、备份用 db.connect()），保留等于留一条「拿裸连接自己写」的口子。

测试：19 个文件同步迁移——10 个文件的 web.deps.secret_key 替身改 async；
test_db_conn.py 的多线程首连用例按异步语义拆成 2 条（单 loop gather(16) 覆盖批量
并发首连、WAL 就绪后 8 线程各自 loop 建连覆盖跨 loop）；test_billing_scope.py 去掉
多余的 @pytest.mark.anyio；被 await 且**正常返回**的 monkeypatch 替身一律改 async
（仅 raise 的同步替身仍可用）。

门禁：ruff 全过 / pyright 0-0-0（standard 模式含 tests 与顶层模块）/ pytest
384 项全绿（0 失败 0 error 0 skipped；383→384 因 test_db_conn 拆用例）。
data/site.db 读写前后 sha256 一致（a19f5db…6487），无 -wal/-shm 边车残留。

下一步 B3：删 core/sync_http.py、core/async_bridge.py、core/http_errors.py 及
 tests/test_async_bridge.py——三者在生产侧已零消费者（http_errors 仅 sync_http
 自用，requests 已非声明依赖）。
 2026-09-28 20:13:19 +08:00
snowy-yang 69a50c2c31 refactor: worker 子系统全面异步化，拆掉同步转异步的桥接层 
拆掉「同步调异步 / 异步桥同步」两类垫片的第二半（HTTP 线 B2 见前序提交）。
worker 侧此前是「起线程跑同步函数、函数体内部再用 asyncio.to_thread 把活塞给
另一条循环」——线程与协程互等，取消/暂停只能靠轮询。本轮把 worker 自身变成
协程，由 _start_task 直接挂到应用事件循环上，桥接层随之失去存在理由。

改动（按子系统）：
- music_downloader：downloader / _aria2 / _concurrency / cover / _http /
  __main__ 全链路协程化。per-file 锁改 asyncio.Lock；计数闸改
  「active 计数 + await asyncio.sleep(0.5)」的可取消等待（原阻塞式 with 会让
  已取消任务仍要等全局名额腾出，卡死并拖后腿退款）；aria2p 的同步 RPC 仍经
  to_thread，轮询改 asyncio.sleep；新增 core.http_client.iter_chunks，把**流式
  读取期**的 aiohttp.ClientError 收敛成 UpstreamNetworkError（请求建立阶段早已
  有这条路径，读取阶段此前没有，断流会绕过调用方的 UpstreamError 分类）。
  删除 get_http_session / _SESSION_LOCAL。
  models._RetryFromScratch 不再继承 requests.RequestException 而继承 Exception：
  它是「续传起点失效、残片已清、从头重下」，既不是确定性失败
  (DownloadException)，也不是残片已保留的网络失败(UpstreamError)，必须独立
  成类且在 except 链中先于二者捕获。
- music_api：podcast.py 全部函数协程化（直链解析内部改
  await NeteaseAPI.get_song_url）；compat.py 删除——16 个死掉的同步门面早已
  清空，文件只剩空壳。
- services：_taskcore / _zipcore / batch / downloads / podcast / tasks 协程化。
  threading.Thread → loop.create_task（任务句柄字段 worker_thread →
  worker_task），ThreadPoolExecutor → asyncio.gather + asyncio.Semaphore，
  终态函数与结算回调全部改 await；监控线程里「worker 已死」判定改 task.done()。
  删除 services/streaming.py（同步流垫片，唯一消费者已迁到
  core.http_client.open）。zipfile 实例仍非线程安全，故「下载」并行、
  「入包」严格串行。
- web：路由层 130+ 处 to_thread 拆除——被包住的目标自己已是协程，再包一层只是
  把协程丢进线程里跑一圈。tasks_registry.start_task 直接 create_task。
  web/app.py 关闭段去掉 async_bridge.shutdown()（不再有第二条约循环）。
  web/routers/download.py 的播客端点补上 3 处漏掉的 await
  （extract_podcast_ref / get_radio_detail）——漏掉时不报错、只静默返回协程对象，
  靠 pyright 抓出来后修正。

留在 to_thread 上的都是**正当的阻塞卸载**：同步 SQLite 落库与账本结算、
mutagen 全量重写标签、zipfile 整段拷贝、shutil.rmtree、aria2p 的同步 RPC、
PBKDF2 的 10 万次迭代。ruff 对残留的本地元数据操作（exists/stat/os.replace/
往 .part 顺序写分块）按「微秒级、卸载的调度开销大于操作本身」放行，pyproject
逐条注明理由。

取消/暂停仍由 threading.Event 承载：置位方是请求线程/监控线程，读取方是 worker
协程，只有「置位」与「轮询读取」两种操作，既不需要跨循环唤醒也不会卡住事件
循环——比 asyncio.Event 更省心（ASYNC110 同理按此豁免）。

测试：10 个文件的替身边界同步迁移——网络替身从 core.sync_http 的
get_http_session 换成 downloader/服务模块的 _http.open + **真实** iter_chunks
（顺带钉住读取期异常收敛）；`_run` 改为在独立线程里 asyncio.run(worker(...))；
aria2 的假时钟从 time.sleep 换成 _POLL_INTERVAL=0；monitor 的线程句柄替身换成
done() 可控的轻量替身（asyncio.Task 的构造需要运行中的事件循环，而监控循环跑在
常驻线程里）；podcast / 封面 / 结算包装等替身一律改 async。

门禁：ruff 全过 / pyright 0-0 / pytest 383 项全绿（0 失败）。

下一步 B2：auth_system 12 个模块改 aiosqlite 背板、web 层剩余 to_thread 收尾；
B3：删 core/sync_http.py、core/async_bridge.py、core/http_errors.py（现仅
sync_http 自用）。
 2026-09-28 19:36:56 +08:00
snowy-yang 65adfc9089 refactor: 删除 aiohttp_compat 垫片，music_api 改走原生 core.http_client 
core/aiohttp_compat 是「同步转异步」迁移期的 requests 同形异步垫片：它存在的
唯一理由是让既有 `requests.post/get + raise_for_status()` 风格的代码以最小
改动迁到异步。其两个调用方（music_api/api.py、music_api/client.py）**本就已是
async def**——垫片只剩「保留 requests 语义」这一层包装，属于迁移残留。

改动：
- api.py：23 处 requests.post/get → await core.http_client.request()。
  该文件每处都在请求后立刻 raise_for_status() 才取 .json()，从不把 4xx 当数据读，
  故「_once 对非 2xx 直接抛 UpstreamHTTPError」与旧语义等价（原 raise_for_status
  抛的 HTTPError 也一律落入 RequestException 分支）；
  except requests.RequestException → except UpstreamError。
- client.py：两个自管重试的方法改用新公开的 core.http_client.request_once()
  （单次、不重试），保留原有「5xx 退避重试一次 / 4xx 立即失败」的分流——
  把 status_code>=500 的判断换成 UpstreamHTTPError.status，行为逐条对齐
  （4xx=风控不重试，网络/5xx 重试一次）。响应体上限交由客户端 max_bytes 统一把关。
  post_request_full 返回类型改为 HTTPResult（qr.py 用到的 .text/.cookies/.headers
  三者在 HTTPResult 上齐备）。
- core/http_client：_once 更名并公开为 request_once（自管重试的调用方需要它）。
  注：这是为「删垫片」而补的唯一一个小口子，不是新增抽象。

注意一处**有意的行为变化**：api.py 原经垫片请求零重试，现在 request() 自带
「网络异常/5xx 退避重试一次、4xx 不重试」（core.http_client 既定口径）。
429/460 属 4xx 不重试，不加剧风控。

- 删除 core/aiohttp_compat.py；web/app.py 去掉其 close()；pyproject 去掉其
  per-file-ignore；core/http_errors.py 注释更正为「仅供 core.sync_http」。
- 测试：test_aiohttp_compat.py 拆解为 test_async_bridge.py（只留桥的两条契约，
  垫片自身的 4 条随垫片消亡）；test_search_music / test_playlist_detail 的替身
  边界从 api.requests.post 换成 api._http.request，异常类型换成 UpstreamNetworkError。

门禁：ruff 全过 / pyright 0-0 / pytest 383 项全绿（0 失败；383=387-6+2，账面吻合）。
 2026-09-28 19:17:03 +08:00
snowy-yang b089dadac2 refactor: geo 走原生异步 HTTP，清掉短链展开死链 
「同步转异步」的残留清理：

1) auth_system/geo.query_ip_province 原经 core.sync_http 同步门面（在后台
   事件循环桥接）查询归属地，但其唯一调用方 record_login_location 的入口
   本来就是 async 的登录链路（web/routers/auth 里还套了一层 to_thread）。
   改为直接 await core.http_client——桥接纯属多余，顺带把 record_login_location
   转 async，落库仍走同步 sqlite 但经 asyncio.to_thread 卸载，避免 sqlite busy
   等待（最长 15s）冻结事件循环。
   调用方两处（普通用户/管理员登录）去掉 to_thread 包装，直接 await。

2) MusicAPIService._extract_music_id 是死代码：ID 归一化早已迁到
   web.request_utils（注释里明说是它的迁移口径），全仓零调用。它也是
   core.utils.expand_shortlink 的唯一调用方——一并删除，core.utils 由此
   彻底不再 import core.sync_http。

门禁：ruff 全过 / pyright 0-0 / pytest 387 项全绿（0 失败）。
 2026-09-28 19:10:45 +08:00
snowy-yang 17b4a99680 test: golden 快照切换到 React 构建产物口径 
为什么：首页响应源从 Jinja2 渲染模板（去尾换行）变为
frontend/dist/index.html 原样字节，html_len/位移到 967 字节。
快照以固定产物名重建，docstring 同步更新口径说明。
 2026-09-27 18:35:07 +08:00
snowy-yang 6fb37534d3 refactor: 计费退款不变量收敛为 Billing.scope()（download.py 25 处手工退款 → 0） 
为什么：「任何失败路径必须退款」此前靠路由里每条早退/except 手工调
refund_open 维持（download.py 单文件 25 处），上一轮拆 register/login
时已经体会过这个模式的代价——改任何一条返回路径都要核对还原时序，
漏一处不会有测试报警，只剩重启对账兜底在跑。

改动：
- Billing.scope()（asynccontextmanager）：作用域退出时自动退还仍 open
  的账本行。正确性完全依赖 refund_open 的既有幂等口径（只退仍 open
  的行）——settle()/rename_to() 消费过的行天然豁免，成功路径零动作，
  无需手动「取消自动退」；未捕获异常先退款再原样穿透。
- download.py 四个端点全部改用 async with billing.scope()，删除全部
  手工退款与 _fail 收尾闭包；_sync_download_json 的内部退款一并移除
  （docstring 标明必须在 scope 内运行）。
- 语义逐路径等价：错误早退→自动退（同原手工）；register 成功后
  rename→自动退 no-op（同原手工退的 no-op）；start 失败行挂 task_id
  留给对账（同原）；CancelledError 语义不变（退款随取消中断，对账兜底）。

先写测试后动代码：tests/test_billing_scope.py 5 例（TDD 红→绿），
对真实沙箱账本断言——open 行自动退、settle 后 no-op 且余额恰 -1、
rename 后请求级行消失且任务级行保持 open、异常穿透、free 路径零动作。
既有 30 例计费/下载端到端测试作迁移回归网。
门禁：ruff 全过 · pyright 0/0 · pytest 387 passed（382→387）。
 2026-09-27 12:13:00 +08:00
snowy-yang 9a34517454 perf: get_conn 每连接固定开销 1.6ms → 0.5ms（-70%） 
为什么：同步层每次数据库操作都新建连接并执行 mkdir + PRAGMA
journal_mode=WAL。实测拆解（各 100 次中位数）：
  mkdir(exist_ok)  190us
  sqlite3.connect  435us
  PRAGMA WAL(新连接首语句)  ~1000us  ← 大头
  get_conn 合计    1641us → 501us
登录路径走同步层 4 次查询（身份解析/验证/位置/日志），每次请求
固定省 ~4.6ms；下载任务的 ledger/日志调用同样受益。

改动（对齐 core/db.py 既有模式——异步层早已做过同款优化并记录过
「并发 PRAGMA 争排他锁报 database is locked」的实测坑，同步层漏同步）：
- _WAL_READY 按路径缓存：journal_mode 持久化在库文件头，设一次即可；
  _WAL_SETUP_LOCK 串行化首连切换（读路径不持 _DB_LOCK）
- mkdir 移出 happy path：connect 失败才兜底补建（用 DB_PATH.parent，
  monkeypatch 场景下与 DATA_DIR 可能不同）
- exists() 检查在 connect 之前（connect 会创建空文件，之后恒真），
  覆盖「删库重建后新文件回退 delete 模式」的边界

新增 tests/test_db_conn.py 6 例：WAL 首连生效、后续连接零 PRAGMA
（set_trace_callback 实证）、换路径重设、目录缺失自动建、删库重建
恢复 WAL、8 线程并发首连无报错。
门禁：ruff 全过 · pyright 0/0 · pytest 382 passed（375→382）。
 2026-09-27 11:32:03 +08:00
snowy-yang be4dd0646a 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）。
 2026-09-27 11:11:56 +08:00
snowy-yang 4d3204213e refactor: resolve_episode_url 阶梯构造拆解（58 行 / 圈 19 / 嵌套 3 → 36 行 / 圈 12 / 嵌套 2） 
为什么：播客单集直链解析的唯一入口，前 20 行是降级阶梯的嵌套构造
（if 套 for 套 if），与尝试循环混在同一个函数里，改音质口径要通读全函数。

拆出：
- _falldown_order（模块级纯函数）：降级尝试序列——auto→通用阶梯原序 /
  已知音质→向下后缀 / 未知音质→该音质优先+通用阶梯，去重保序收敛为
  dict.fromkeys；_FALLDOWN_LADDER 从函数内上移模块级
- resolve_episode_url 只剩尝试循环；song_id 的 int 防御上提循环外
  （循环不变量：原实现首轮即判、失败直接 None，url_v1 从未收到过坏 sid）

先写测试后动代码：新增 tests/test_resolve_episode_url.py 11 例，在未改动
实现上一次跑绿，钉住核心口径——「只向下不向上」（standard 绝不回退到
exhigh，历史坑）、未知音质前置、垃圾 song_id 零请求、APIException 降级、
data[0] 无 url 降级、结果映射缺省值。
门禁：ruff 全过 · pyright 0/0 · pytest 370 passed（359→370）。
 2026-09-27 11:00:50 +08:00
snowy-yang d2e6856899 refactor: get_playlist_detail 批次拉取拆解（94 行 / 圈 24 / 嵌套 3 → 60 行 / 圈 9 / 嵌套 1） 
为什么：歌单解析的唯一上游通道，94 行单函数把「歌单头解析 / trackIds
分批拉明细 / 失败批次记账 / incomplete 标记 / 错误映射」五件事揉在
一个 try 里；曲目字段映射与搜索歌曲路逐字段重复。

拆出（模块级，与 search_music 拆解同风格）：
- _song_base_fields：歌曲条目公共字段（搜索/歌单共用同一容错口径），
  _map_song_item 改为其加 type 键的包装
- _playlist_track_ids：trackIds → 字符串 ID 列表
- _collect_playlist_tracks：批次循环整体（失败批次计数、脏 ID 跳批、
  明细缺 id 跳过、incomplete 判定输入），嵌套 3 是批次语义固有，
  集中在单一职责函数内

保留语义：脏 ID（'①'.isdigit() 为真但 int() 抛 ValueError）跳过整批
且不计 failed_batches；批次阶段网络错误仍映射「获取歌单详情请求失败」。

先写测试后动代码：新增 tests/test_playlist_detail.py 11 例，在未改动
实现上跑绿（修正 1 例测试自身的替身消费顺序），覆盖此前零测试路径——
playlist:null 防枚举、业务 code 错误、非 dict 响应、批次失败记账、
脏 ID 跳批、100/批分批、错误映射。
门禁：ruff 全过 · pyright 0/0 · pytest 359 passed（348→359）。
 2026-09-27 10:53:48 +08:00
snowy-yang f0de0b65b1 refactor: login 端点拆解（90 行 / 圈 26 / 嵌套 2 → 39 行 / 圈 10 / 嵌套 1） 
为什么：登录是全部拒绝路径最密的端点（超长密码/锁定/密码错/封禁/
禁用/管理员无邮箱/异地封禁七道闸），90 行单函数把「身份解析、锁定
计数、状态闸、2FA 转票据、会话建立」五件事揉在一个 try 里，改任何
一道闸都要在嵌套分支里核对上下文。

拆出五个成员（顺序 = 原执行顺序，逐条语义对应）：
- _resolve_login_identity：邮箱→账号解析 + 锁定键（保留两处判定
  差异：锁定键用真值判断，verify_name 用 is not None——历史口径，
  契约测试分别钉住）
- _allow_login_attempt：锁定闸 + 一次性审计日志（锁定周期内不重复落）
- _check_account_status：封禁（原因落日志）/禁用，通过返回 None
- _admin_two_factor_response：2FA 转票据，未绑定邮箱 fail-closed
- _user_session_response：login_seq 顶号 + 异地多省封禁闸（封禁时
  再递增一次顶掉在途会话）+ Cookie 签发

先写测试后动代码：新增 tests/test_login_flow.py 9 例，在未改动实现上
一次跑绿，覆盖此前零测试的路径——超长密码不碰 PBKDF2（monkeypatch
verify_login 断言不被调用）、邮箱登录按归一化地址锁定、锁定日志幂等、
封禁/禁用文案、管理员 fail-closed、异地封禁双递增、非预期异常 500。

门禁：ruff 全过 · pyright 0/0 · pytest 348 passed（339→348）。
 2026-09-27 10:13:36 +08:00
snowy-yang 5ad2152acc refactor: register 端点拆解（84 行 / 圈 34 → 58 行 / 圈 20 / 嵌套 1） 
为什么：注册是站点唯一的建号入口，84 行里五条「建号前失败」路径各自
手写一遍 restore_verify_code（有的还带失败日志），防刷双闸与三种建号
异常的口径全埋在分支里，改任何一条都要通读全函数核对还原时序。

拆出（顺序 = 原执行顺序，逐条语义对应）：
- _validate_registration_input：入参四道闸（协议/用户名/密码/邮箱），
  按序返回第一条错误文案
- _reject_registration：统一拒绝出口——还原已消费验证码（可选失败
  日志）；五处 restore 收敛为一处，docstring 写明「为何必须还原」
- _register_credits：赠送闸（同设备重复注册归零；顺带删除
  credits<0 死分支——_safe_register_credits 已保证非负）
- _issue_registration_session：成功收尾（login_seq 递增 + 日志 + Cookie）

先写测试后动代码：新增 tests/test_register_flow.py 9 例，在未改动
实现上一次跑绿。验证码由 check_verify_code DELETE 原子消费，测试用
「失败路径后 email_codes 行仍在」做 restore 实证断言（不 mock 还原）；
其中用户名重名路径用端到端方式验证——同一验证码不重发即可二次注册。
覆盖此前零测试的路径：IP 闸、设备赠送闸、IntegrityError/ValueError/
读回 None 三种建号异常映射、非预期异常 500 泛化文案。

门禁：ruff 全过 · pyright 0/0 · pytest 339 passed（330→339）。
 2026-09-27 10:05:20 +08:00
snowy-yang e00ac14460 refactor: search_music 四路映射拆解（101 行 / 圈 32 / 嵌套 6 → 42 行 / 圈 7 / 嵌套 1） 
为什么：站内搜索的唯一上游通道，101 行里 if/elif 四路条目映射占了
2/3，错误映射与字段容错口径（歌曲 artists 空缺兜底未知歌手、专辑
不兜底、alias 缺省 '' 等）全埋在分支里，改一路要通读全函数。

拆出（模块级，与既有 _ensure_dict 同风格）：
- _map_song_item / _map_album_item / _map_artist_item / _map_playlist_item
  ——四路口径原样，docstring 标注各路容错差异
- _SEARCH_RESULT_KEYS + _SEARCH_ITEM_MAPPERS 派发表（未知类型不在表内
  → 空结果，原 if/elif 无 else 行为一致）
- _collect_search_items 统一「取键 → 无 id 跳过 → 映射」

先写测试后动代码：新增 tests/test_search_music.py 12 例，在未改动
实现上跑绿（修正 1 例替身形状：网络异常必须抛垫片自己的
RequestException，aiohttp.ClientError 由 aiohttp_compat 内部翻译，
直接抛底层是不存在的形状）。契约测试不为违反 offset: int 签名的
None 入参背书（防御性 int(offset or 0) 保留，不测）。
门禁：ruff 全过 · pyright 0/0 · pytest 330 passed（319→330）。
 2026-09-27 09:42:07 +08:00
snowy-yang 37f8d77405 refactor: init_db 四段拆解（142 行 / 圈 15 / 嵌套 4 → 14 行 / 圈 2 / 嵌套 1） 
为什么：init_db 是站点库全部结构演进的唯一入口，但 142 行单函数把
「建表 / 列迁移 / 邮箱唯一索引 / 邮箱归一化 / 管理员引导」五件事
揉在一个 with-try 里，任何一段改动都要在 140 行上下文里核对边界。

拆出五个成员（全部接收 conn，调用顺序 = 原执行顺序，单连接单 commit 不变）：
- _SCHEMA_SQL 常量 + _create_schema（建表 + 种子行，纯数据上移）
- _apply_column_migrations（ALTER 循环；非 duplicate column 的
  OperationalError 仍然抛出，禁止静默带病初始化）
- _ensure_email_unique_index（重复邮箱仅告警不阻断，原文案保留）
- _migrate_user_emails（撞唯一索引行保留原值，原文案保留）
- _ensure_initial_admin（按 role 判断而非用户名，防改名后误重建）

先写测试后动代码：新增 tests/test_auth_init_db.py 7 例，覆盖此前
零测试的路径——旧库列迁移、二次初始化幂等、改名管理员不重建、
存量重复邮箱告警不阻断、+tag 邮箱归一化迁移、归一化撞行保留原值。
7 例在未改动实现上一次跑绿，重构后即等价性验证。
门禁：ruff 全过 · pyright 0/0 · pytest 319 passed（312→319）。
 2026-09-27 09:36:31 +08:00
snowy-yang 1c6b17f718 refactor: 播客单集 worker 拆解（140 行 / 圈 35 → 40 行 / 圈 6 / 嵌套 1） 
为什么：_podcast_download_worker 是播客单集下载的唯一后台执行路径，
此前零直接测试覆盖；三条 except 分支各写一遍「结算+删任务目录」，
正文散着三处取消检查，改坏任意一处不会有测试报警。

拆出（与单曲 worker 9cbd341 同风格）：
- _PodcastTaskSpec（frozen dataclass，program_id 标注 Any——params 历史
  存数字字符串，worker 只透传，int() 是行为变更）
- _PodcastTarget（磁盘名/交付名/任务目录的命名组装）
- _begin_podcast_task / _prepare_podcast_target / _write_podcast_zip /
  _podcast_file_result / _podcast_zip_result / _publish_podcast_task /
  _fail_podcast_task（三处 ×9 行收尾收敛）
- 取消检查复用 downloads._abort_if_canceled（无循环依赖）；tempfile
  局部 import 上移模块顶

先写测试后动代码：新增 tests/test_podcast_worker.py 18 例，在**未改动**
实现上一次跑绿 = 忠实编码旧行为，重构后同一套测试即等价性验证。
唯一语义顺序变化：except 分支的日志从「收尾后」挪到「收尾前」（与
单曲 worker 对齐，日志内容不变，无行为影响）。
门禁：ruff 全过 · pyright 0/0 · pytest 312 passed（294→312）。
 2026-09-27 09:30:52 +08:00
snowy-yang d08ae85cd4 feat: 前端美化层 v11——品牌氛围 + Tab 药丸化 
为什么：页面经 v4-v10 十层打磨后整体已精致，但截图复看仍有四处寡淡——
纯文字下划线 Tab 缺乏点击感、背景氛围是中性灰与品牌无关、卡片顶边
平、账号区与音质区无分隔。

改动（全部为 CSS 叠加覆盖，不动类名/结构/JS 契约）：
- Tab 药丸化：hover 软底 + active 主色片 + 按压回弹，::after 下划线隐藏；
  用 .tabs .tab 权重压过基础层与 v10 超小屏规则
- 背景氛围替换为品牌红 + 主题蓝双色辉光（明暗两套参数）
- 卡片顶部内高光，浅色主题更挺括
- 账号栏补下分隔线，与音质栏边框上下呼应
- 主按钮补顶部高光渐变（对齐 success/danger 既有处理）
- 页脚字距微调；空状态浮动动画 v4 已有，不重复

golden：index 快照按 docstring 约定同步刷新（sha256/len），
仅 2 行值变更。门禁：ruff/pyright 0-0，pytest 294 全绿；
浏览器实测明暗两主题 + Tab 切换正常。
 2026-09-27 09:19:23 +08:00
snowy-yang 9cbd341e2e 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 沙箱）。
 2026-09-27 09:03:05 +08:00
snowy-yang 9910e4dbec refactor: _fetch_via_http 拆解（94 行 / 圈 21 → 46 行 / 圈 5） 
为什么：_fetch_via_http 是全仓内置下载通道的落盘实现，也是本文件此前最大的
圈复杂度所在。94 行的单体里叠着三段互不相关的职责——Range 起点校验、流式写盘
与体积上限、HTTP 错误分类——还共享一个 try/except/finally。上一轮拆
download_music_file 时它是唯一没动的重函数。

改法：拆成 7 个具名成员，主函数只留四步编排（构造 Range 头 → 发请求 →
定追加/重写并校验分片起点 → 流式落盘）。
  _range_headers                  续传时请求「起点之后的全部字节」
  _resolve_write_mode             续传且服务器确实给 206 才追加，否则从头重写
  _verify_content_range           校验 206 分片起点；无法确认就清残片从头下
  _stream_body                    逐块写盘 + 取消检查 + 体积硬上限（500MB）
  _safe_progress                  上报进度，回调异常吞掉（原两处 try/except 收敛）
  _http_status                    从 HTTPError 取状态码
  _is_deterministic_client_error  4xx 判定（408 例外，唯一保留可重试的 4xx）

复杂度（同口径 AST 实测，HEAD 与工作区用同一脚本）：
  _fetch_via_http     94 行 / 圈 21 / 嵌套 7  →  46 行 / 圈 5 / 嵌套 3
  文件内最大圈复杂度    21（当时就是它）        →  16（余下最大是 download_music_file）
  文件行数 710 → 753（+43，全是新签名与 docstring）· 函数数 19 → 26
  口径说明：上一轮口头报的「圈 35」用的是另一脚本（另计入布尔运算与比较），
  本轮 HEAD 同口径实测为 21。以本轮为准——HEAD 与重构后由同一脚本测出，可比。

等价性证据（两道，互相独立）：
1. 反向注入验证：把 HEAD 版 downloader 注入成 music_downloader.downloader，用同一套
   tests/test_downloader.py 跑 → 30 例**全过**。证明这批测试忠实编码了旧行为，
   因而对新实现构成等价性验证（含本次新增的 5xx 用例，它在旧实现上同样通过）。
2. AST 字面量多重集比对 + 逐条位置定位：数值/布尔 26 种、字符串 80 种，
   差异全部归因，且**没有一条用户可见文案或阈值被改动**：
     206  2→1：旧的两段独立 if（`!= 206` 归零 mode、`== 206` 校验起点）合并进
               _resolve_write_mode 的一个判断
     0   26→24：两处 progress 的 `or 0` 收敛成 expected_size（-1）；
               两处 206 判断各含一个 `> 0` 合并成一个 `<= 0`（-1）
     'wb' 2→1：初始赋值与条件改写两处合并成一个 return
   500MB 阈值、各条错误文案原样保留。

重写条件表达式必须补分支穷举（字面量审计不管这一层），已逐路核对：
  resume_from <= 0                     → 'wb'（旧：不进任何 if，保持初始 'wb'）
  resume_from > 0 且 status != 206     → 'wb'（旧：第一个 if 命中）
  resume_from > 0 且 status == 206     → 校验起点 + 'ab'（旧：第二个 if 命中）
三路与旧实现一致。

刻意保留的语义（是决定，不是疏漏）：
- 超限清理仍**延后到 with 退出后**——Windows 无法删除仍被打开的文件，原实现在
  打开中 unlink 被静默吞掉，残片会留在磁盘上。
- 进度回调异常一律吞掉，绝不影响下载主流程。
- 4xx 里 408 是唯一例外（保留可重试）；416 与「206 头被剥离解析不出起点」同口径
  清残片从头下（盲追加拼出的是坏文件）。
- 非 416/4xx 的错误走**裸 raise**（不用 `raise e`），保持原 traceback 不被改动。

测试：新增 1 例 test_5xx_is_retried_and_keeps_part —— 5xx 是服务端瞬时故障而非
确定性失败，须可重试且保留 .part 供续传。这条路径此前无覆盖，且它正是
_is_deterministic_client_error 与 4xx 的分界所在。

顺带记录一个验证工具自身的坑（第一次跑反向注入时 30 例全红，看似「测试不忠实」，
实为注入没生效、测试静默走了真实网络，报错为 Cannot connect to host cdn.test）：
只覆盖 sys.modules['music_downloader.downloader'] 不够——pytest 的 monkeypatch
解析目标字符串走 _pytest.monkeypatch.resolve()，是「逐级 getattr 父包」而非纯
sys.modules 查找，包的 downloader 属性仍指向真模块。必须同时 setattr 父包属性。
教训：等价性验证的**工具本身**也要能证伪，否则结论会 180 度反转。

验证：ruff 全过 · pyright 0/0 · pytest 275 passed（274→275）· 行尾 i/lf w/lf
与仓库一致 · 生产 data/ 未被触碰（全部用例走 tmp_path 沙箱）。
 2026-09-27 08:05:44 +08:00
snowy-yang 8716617d5d refactor: download_music_file 拆解（205 行 / 圈 47 → 125 行 / 圈 20） 
为什么：download_music_file 是**唯一**的音频落盘路径（单曲 worker、音乐批量 ZIP
都经它），205 行 / 圈复杂度 47 / 嵌套 7 的单体里叠着缓存校验、断点续传、内容嗅探、
体积上限、取消语义、重试退避、元数据限流七件事，却**零直接测试覆盖**
（test_zip_workers 里只有一个 stub）。任何一处被改坏都不会有测试报警。

改法：拆成 8 个具名方法，主函数只留「5 步管线 + 重试策略」：
  _cached_result          锁内复查缓存（命中即返回，坏缓存删除重下）
  _promote_complete_part  已下完未改名的 .part 直接转正，不发起网络请求
  _resume_offset          断点续传起点，并清理没有续传价值的残片
  _transfer               占全局名额 + 选通道（aria2c / 内置 aiohttp）
  _size_mismatch_error    完整性判定（已知期望精确相等 / 未知期望至少非空）
  _publish                嗅探 → 原子转正 → 写元数据
  _write_metadata_locked  标签信号量内的元数据写入（原三处重复的 with 收敛）
  _backoff_wait           退避秒数（原五处重复的 0.5*(attempt+1) 收敛）

复杂度（同口径 AST 实测）：
  download_music_file  205 行 / 圈 47 / 嵌套 7  →  125 行 / 圈 20 / 嵌套 4
                       （125 行里 26 行是 docstring，正文 87 行）
  文件内嵌套 >=5 层     2 → 1（余下的是本次未动的 _fetch_via_http）
  文件内最大圈复杂度     47 → 35（同样落在未动的 _fetch_via_http 上）
  文件行数             614 → 710（+96，全是新签名与 docstring）

等价性证据（两道，互相独立）：
1. 29 例行为契约测试**在未改动的原始实现上一次性全绿**（先写测试、后动代码；改完
   再跑仍全绿）——这批测试因此忠实编码了旧行为，构成等价性验证，而不是「照着新
   实现写的新行为测试」。断言只依赖返回值 / 磁盘上的文件 / 发往网络的请求，不引用
   任何内部函数名，故可跨后续重构复用。
2. AST 字面量多重集比对 + **逐条位置定位**：数值/布尔 27 种、字符串 80 种。差异
   全部归因，且**没有一条用户可见文案或阈值被改动**——
     0   +2：_resume_offset 的三个 return 0 取代原 resume_from = 0
     0.0 +1、0.5 −3、1 −3：四处重复的 0.5*(attempt+1) 收敛进 _backoff_wait
     None +16：新增方法的 6 处类型标注 + 4 处 return None + 2 处 is not None
     ''  +1：_size_mismatch_error 的内部哨兵（非用户可见）
   续传起点逻辑另做逐例核对：promote 命中 / existing<=0 / 超尺寸 / 部分 四路等价。

刻意保留的语义（是决定，不是疏漏）：
- 退避睡眠仍在文件锁外执行——同名并发任务不陪睡。
- 缓存命中时若 write_meta 仍按本次请求重跑一次标签写入（幂等）；write_meta=False
  则不写。
- 已转正（os.replace 之后）才发现取消时**不回滚文件**，只跳过元数据——原行为如此，
  已用 test_cancel_after_promote_keeps_file_but_skips_metadata 固化。
- 未知期望尺寸（file_size=0）走「非空即通过」+ 内容嗅探兜底；已知期望尺寸要求
  **精确相等**（放宽到容差会交付截断的坏文件还照扣次数）。
- 缓存有效性用 st_size != file_size（而非 >=）：跨账号音质降级 / 上游变更都会让
  同 ID 同音质的实际文件不同，命中即返回会把旧文件当本次结果交付。

测试：新增 tests/test_downloader.py（29 例）——正常落盘与 .part 转正、空分块跳过、
进度回调（起点 / 每块 / 异常吞掉）、缓存命中不发请求、坏缓存重下、0 字节缓存拒绝、
续传发 Range 并追加、服务器忽略 Range 时重写、完整残片免网络转正、超尺寸残片丢弃、
206 起点错位 / 206 缺 Content-Range / 416 三路从头重下、CDN 4xx 不重试、408 可重试、
不完整保留 .part、下轮续传、未知尺寸非音频拒绝、体积上限、五种取消路径、元数据开关。

验证：ruff 全过 · pyright 0/0 · pytest 274 passed（245→274）· 生产 data/ 未被触碰
（全部用例走 tmp_path 沙箱）。
 2026-09-27 07:56:01 +08:00
snowy-yang a05af4a880 refactor: 播客流式下载拆解（嵌套 10 层 → 1，三段职责各就其位） 
为什么：_podcast_stream_download 是播客单集下载的**唯一落盘路径**（单集 worker
与整台打包的首集都走它），却零测试覆盖；而且它把三段互不相关的职责——全局名额
排队、流式写盘与进度上报、完整性校验与坏文件清理——叠在 try/with/with/for 加四层
if 里，最大嵌套 10 层，是全仓最深的一个。

改法：拆成四个具名函数，主函数只留编排。
  _stream_to_part    ：拿响应 → 写 .part → 按 0.5s 节流上报进度，返回 (已写, 期望)
  _report_progress   ：把一次进度写进任务表（含单集任务的 live_percent）
  _verify_downloaded ：完整性判定 + 清掉坏文件（精确相等 / 非空两条口径）
  _remove_quietly    ：删文件并吞掉 OSError（Windows 句柄未释放时 remove 会抛）

复杂度（同口径 AST 实测）：
  _podcast_stream_download  63 行 / 圈 19 / 嵌套 10  →  21 行 / 圈 3 / 嵌套 1
  新增 _stream_to_part 25 行/圈 8/嵌套 4 · _report_progress 22/6/3 · _verify_downloaded 14/3/1
  文件内嵌套 ≥5 层 2 → 1（余下那个是本次未动的 _podcast_download_worker）

刻意保留的语义（是决定，不是疏漏）：
- 取消时 **.part 留存不删**（改名不发生，下次同名下载直接覆盖）——已用测试固化。
  不「顺手」改成删除，那是行为变更。
- 进度 msg 的计算与「是否真有可取的任务」无关：task_id 为空时仍会格式化字符串再
  return。这是既有的无害浪费，一并保留。
- 完整性口径原样：已知期望大小要求**精确相等**（放宽到 95% 容差会交付截断的坏文件
  还照扣次数），期望未知则退化为非空校验。

等价性证据（两道）：
1. 反向注入验证：把 HEAD 的旧实现换回去，用同一套 tests/test_podcast_stream.py 跑
   → 12 例**全过**，证明这批测试忠实编码旧行为、对新实现构成等价性验证。
2. 新增 12 例行为契约（该函数此前零覆盖）：正常落盘与改名、空分块跳过、
   Content-Length 兜底、字节数不符清坏文件、空下载报错、已知大小不容忍部分交付、
   上游 4xx、开始前取消、中途取消留 .part、running 任务写 msg/live_percent、
   终态任务不被覆盖、无 task_id 不报错。

顺带记录一个测试自身的坑：替身响应最初用 list(chunks) 归一化，导致传入生成器的
副作用（中途置取消位）在**构造时刻**就执行，测出来变成「开始前取消」——两条本不
相同的路径被混成一条。已改为保留原 iterable 并写明原因。

验证：ruff 全过 · pyright 0/0 · pytest 245 passed（233→245）· 生产 data/ 未被触碰。
 2026-09-27 07:45:49 +08:00
snowy-yang f27bd7dd74 refactor: /song 端点拆解（99 行 / 圈 18 → 主函数 27 行 / 圈 8） 
为什么：song 是端点层最重的函数——参数校验（4 条）、账号 Cookie 选择、四种 type
分发、json 分支的三源合并与降级全塞在一处；而四种 type 的返回体形状与降级口径
**没有任何测试记录**（golden 里的 /song 只有一条参数校验用例 song_badid）。

改法：
- _parse_song_query：提取 + 校验，返回 _SongQuery 或**错误消息字符串**。返回
  字符串而非响应对象，是为了让它不依赖响应层、可单独断言（校验段 4 条错误都是
  默认 400，无需状态码）。
- _SongQuery：frozen dataclass。music_id 保持 extract_id 的**字符串原值**——它
  原样进响应体 id 字段、golden 按字符串比对；上游要的 int 走 .mid property。
- _song_url_response / _song_json_response：两个实体分支各自成函数。
- song 主函数只剩「校验 → 选 Cookie → 四路分发」。

刻意保留的语义（是决定，不是疏漏）：
- 解析日志**只在 json 分支**记录，url/name/lyric 三路不记——历史实现如此。
  已写进 _song_json_response 的 docstring：不要为了「统一」把它上提到主函数，
  那会新增三路的可观察副作用。
- 校验顺序（缺参 → ID 非数字 → 音质 → 类型）原样保留，并用测试钉住「同时传错
  时报哪条」。顺序是用户可见行为。
- 三条 404 降级（上游 data 为空 / data=[null] / songs 为空）逐条保留。

复杂度（同口径 AST 实测，重构前后）：
  song                 99 行 / 圈 18 / 嵌套 4  →  27 行 / 圈 8 / 嵌套 2
  _song_json_response   新增                  →  49 行 / 圈 6 / 嵌套 1
  _parse_song_query     新增                  →  21 行 / 圈 5 / 嵌套 1
  文件内 >80 行函数 1 → 0；最大圈 18 → 11（余下最大的是本次未动的 mask_server_nickname）
  注：上一轮口头报的「圈 44」与本轮口径不同，此处以本轮统一口径为准，重测为准绳。

等价性证据（三道，互相独立）：
1. AST 字面量审计：字符串字面量 **227 处完全一致**；数值唯一差异是新增的
   dataclass frozen=True。即没有一条用户可见文案或阈值被改动。
2. 反向注入验证：把 HEAD 的旧 song 换回去，用同一套 tests/test_song_types.py 跑
   → 19 例**全过**，证明这批测试忠实编码了旧行为、对新实现构成等价性验证。
3. 新增 19 例行为契约测试：四种 type 正路、json 的三源合并与三种降级（歌词失败
   不阻断 / 直链失败置空 / 详情失败 404）、校验优先级、分享链接解析、
   account=user 无 Cookie 401、全局 Cookie 冒用拦截。

顺带修掉一个测试自身缺陷：新用例里「个人 Cookie 与全局账号一致」一条**单跑通过、
全套失败**——根因是它依赖 GLOBAL_MUSIC_U_CACHE（5 分钟粘性的模块级缓存），别的
文件先跑会把值填上，于是拿到缓存值而非本处 patch 的 Cookie。已改为 fixture 里
用 monkeypatch.setitem 显式重置该缓存，让用例自足。

验证：ruff 全过 · pyright 0/0 · pytest 233 passed（214→233）· 生产 data/ 未被
触碰（全部用例走 tmp_path 沙箱）。
 2026-09-27 07:41:16 +08:00
snowy-yang 1973d6a0e8 fix: 启用会话过期（服务端校验签发时间，堵住旧 Cookie 永不过期） 
为什么：签发侧 Cookie 的 max_age 是 7 天，但那只是**浏览器**行为——被保存、
复制或从日志里捞出来的旧 Cookie 仍带着有效签名，而解析侧 loads 从不校验签发
时间（max_age=None），等于「登录态永不过期」。登出/顶号靠递增 login_seq 兜底，
但拿不到库的一方（如泄露的 Cookie）无从失效。

改法：
- core/session.py 新增 COOKIE_NAME / SESSION_MAX_AGE，作为会话名与有效期的
  唯一来源。此前 'session' 在 web/deps、web/routers/auth、web/routers/register
  各写一遍，7 天在两处各写一遍——三处同名常量各改各的，正是漂移温床。
- web/deps._parse_cookie 传入 max_age=SESSION_MAX_AGE，过期判定落在服务端。
- 两个签发侧改引用共享常量（保留模块级别名，对外名字不变）。
- loads() 的签名与语义**不变**（max_age=None 仍不校验）：它是通用工具，策略
  属于调用点，这样 test_session 里「None 接受旧时间戳」的语义继续成立。

行为变更（本轮唯一一处）：签发时间超过 7 天的会话 Cookie 现在按未登录处理。
正常浏览器用户无感——浏览器本来就按 max_age 丢弃它；受影响的是手工保存、
跨 7 天复用的旧 Cookie，正是要堵的那类。

验证：
- 新增 tests/test_deps.py::test_expired_cookie_rejected：用 monkeypatch.context()
  把时钟拨回 SESSION_MAX_AGE 之前签发（itsdangerous 时间戳取自 dumps 时刻），
  再以当前时间解析 → 必须拒绝；同时断言有效期内不受影响。用 context 而非
  undo()，后者会连带撤销 site fixture 的设置。
- 变异验证：把 max_age 参数摘掉后**恰好**该用例变红、其余 10 例全绿——证明测试
  精确盯着这一处，不是碰巧通过。
- ruff 全过 · pyright 0/0 · pytest 214 passed（213→214）。golden 快照与
  test_download_billing（真实登录拿 Cookie 打 API）均通过，端到端链路未受影响。
 2026-09-27 07:32:05 +08:00
snowy-yang 5c8f941d19 refactor: 两个 ZIP 打包 worker 合并为一个参数化引擎（604 行重复骨架 → 一份） 
为什么：_batch_zip_worker（327 行 / 圈 78 / 嵌套 9）与 _podcast_zip_worker
（277 行 / 圈 84 / 嵌套 9）是两份平行实现——任务状态机、断线暂停、全局批量
名额、「逐条失败不计整批」、取消与异常的四路终态收敛、账本结算全部各写一遍，
连注释都逐字重复。上一轮修的 zip_valid 未绑定缺陷正是同型出现在这两处，
重复代码在持续制造同类 bug。

改法：新增 services/_zipcore.py 只保留共用骨架，差异收敛到 ZipJob 钩子：
prepare / download_one / write_entry / zip_filename 必实现，prefetch /
fail_label / done_msg / log_label / all_failed_msg / partial_msg / supplement /
on_delivered / cleanup 按需覆写。batch.py 与 podcast.py 只剩薄包装 + flavor 类。

线程模型（改动中最容易踩坏的一条，已写进模块 docstring）：
ZipFile 不是线程安全的，且包内名去重是「读改写 used_arcnames」。因此把下载与
落包拆成两个钩子——只有 download_one 进线程池，zf.write 与去重一律在调用线程
串行。旧的音乐批量之所以安全，只是因为它的 zf.write 恰好写在主线程的
as_completed 循环里；照搬成「整个下载单元进池」会引入静默的 ZIP 损坏。

复杂度（同口径 AST 实测）：
  两个 worker 合计   604 行 / 圈 162 / 嵌套 9,9
  → run_zip_job      167 行 / 圈  37 / 嵌套 4
    + _fill_zip       64 行 / 圈  13 / 嵌套 5
  全仓最大圈复杂度 84 → 37；>80 行函数 3 → 2（余下两个之一是本次未改动的
  _podcast_download_worker）。两文件改为三文件后总行数 930 → 1071，多出的
  主要是引擎 docstring——注释比代码贵，但它把「为什么这么拆」留给了下一个人。

逐条对齐的分叉（合并必须做的决定，此处全部列明）：
1. 账本终态：播客全失败走自己的 except DownloadException → 落 'settled'，音乐
   同语义事件落 'error'。统一为 'error'。全仓仅读取 'open'（对账/清理/计数），
   其余取值只作排障留痕 → 这是本次**唯一可观察的语义变更**，由新增用例固化。
2. 通用异常路径的「部分交付」：音乐侧会发布已打包的 ZIP 并挂 result，播客侧
   直接丢弃（却已按 delivered 结算 = 用户扣了费拿不到货）。统一采用音乐侧口径。
   该路径实际不可达（ZIP 写完后到发布前只有取消检查会抛错，已被取消分支接管）。
3. 全失败判定：音乐用 `ok == 0 and failed`、播客用早抛 DownloadException。
   统一为显式 `ok == 0`——好处是不再发布空 ZIP、不再把空批次标 done。
4. 早抛业务失败（无可下载条目 / 补扣失败）：播客走 DownloadException 分支，
   音乐无此分支（落通用异常，用户看到的是「打包失败，请稍后重试」）。统一保留
   该分支，音乐侧同类失败从此也给出具体原因。
5. 错误终态写法：播客在手写任务字典（重复一遍「已终态不覆盖」，且漏掉 /F-E 的
   「worker 线程已死则按账本补结算」兜底），统一走 _mark_task_terminal。
6. 暂停检查点：统一采用音乐侧更严的一处——拿到 BATCH_ZIP_SEM 后再查一次
   pause/cancel。播客此前会多下完一集才停。
7. total 字段：音乐由提交侧设置、播客由 worker 设置，统一为 worker 设
   len(items)（对音乐是同一个值）。
8. 日志文案统一（tag / 名词提成类属性）：'批量打包异常' 与 '批量ZIP任务异常'
   两种前缀收敛为一种；完成日志统一带上 task_id 与退回次数。

删除的不可达分支（可证明）：
  两个 worker 在 zip_valid = True 之后各留了一段 `if not zip_valid:` 失败收敛
  （音乐 16 行 / 播客 18 行，含「ZIP 打包失败（可能磁盘空间不足）…」文案）。
  赋值紧跟其后、中间无任何语句可改写 zip_valid，故恒不可达——是原注释所称
  「复审 修正」留下的护栏。zip_valid 在异常路径仍有意义（决定 delivered 是否为 0）。

等价性证据（三道，互相独立）：
1. AST 字面量多重集比对 + 逐条位置定位：数值 16 种一个不少。少掉的 8 处 `0`
   全部来自上面删的不可达分支与重复字面量合并（`delivered = … else 0` 5 处→3 处）。
2. 反向注入验证：把 git HEAD 的旧 worker 注入成 services.batch / services.podcast，
   用同一套 tests/test_zip_workers.py 去跑 → 第 1 批 9 例行为契约**全过**，证明
   这套测试忠实编码了旧行为、因而对新实现构成等价性验证；新增 4 例中只有账本
   终态那 1 例失败（'settled' == 'error'），恰好把上面第 1 条对齐实证出来。该用例
   里「全部单集下载失败: …（已退回 2 次下载次数）」的文案断言在旧实现上也通过
   → 用户可见文案逐字保留。
3. 新增 4 例固化测试：同名歌声的音频/歌词/封面三条目共享序号后缀（F-C）、
   两边的全失败文案与账本终态、单集失败后任务目录不留中间文件与 .part 残片。

顺带修掉一个自己引入的缺陷：引擎化后播客侧的单条失败文案本会退化成整个条目
字典，字面量审计里 '(' ')' 各少 1 处把它逼了出来 → 补 ZipJob.fail_label 覆盖。

验证：ruff 全过 · pyright 0/0 · pytest 213 passed（209→213）· 生产 data/ 未被
触碰（全部用例走 tmp_path 沙箱）。
 2026-09-26 19:25:06 +08:00
snowy-yang 65a81af94a refactor: 拆分任务监控循环的 7 组周期作业（170 行 / 圈 58 → 17 行 / 圈 3） 
为什么：_task_monitor_loop 是一个 170 行 / 圈复杂度 58 / 嵌套 8 层的单函数，把
7 组互不相关的周期性作业塞在一起——终态回收、超时取消、缓存清扫、限流桶清理、
账本对账、孤儿目录补扫、心跳离线——整轮共用一个 try/except。任何一处改动都要
通读全部 7 组逻辑；上一轮恢复它的启动点时，也正是这个体量让判读很吃力。

改法：一组作业一个具名函数，另抽 _run_monitor_tick 只负责编排顺序（循环本身
只剩「sleep + try + 限频记录」三件事）。

复杂度（同口径 AST 实测，重构前后）：
  _task_monitor_loop   170 行 / 圈 58 / 嵌套 8  →  17 行 / 圈 3 / 嵌套 2
  文件内最大函数        170 行                  →  66 行（_reap_finished_tasks）
  文件内 >80 行函数      1 → 0  ·  嵌套 ≥5 层   1 → 0
  代价：总行数 231 → 291（+60，全部是新的函数签名与 docstring）

等价性证据（重构的分内之事，不是附赠）：
  1. AST **数值字面量多重集**比对：旧 16 种 / 新 16 种，计数零差异——确认搬运
     中没有改任何阈值（4h 硬超时 / 8 次重试 / 60s / 24h / 5h / 90 天 / 600s …）。
  2. 剔除 docstring 后的**字符串字面量**比对：旧版有的一处不少——确认用户可见
     状态文案与日志格式没被抄错。
  3. 新增 20 例行为契约测试（tests/test_monitor_jobs.py），按「调用后世界里发生
     了什么」断言，不引用实现细节，故可跨后续重构复用。

刻意保留的语义（是决定，不是疏漏）：
  - 单个 tick 仍共用一个 try/except：前段作业抛异常会跳过本轮剩余作业。改为
    逐作业隔离属于**行为变更**，本提交不夹带；已用 test_tick_exception_skips_
    rest_of_tick 如实钉住现状，让那次变更有据可依、不会悄悄发生。
  - _run_periodic_ledger_jobs / _sweep_orphan_task_dirs 的局部 try/except 原样
    保留（原注释即写明「下轮重试」意图），其兜底粒度各有独立用例。
  - 代结算的前提仍是「worker_thread 字段存在且线程已死」：没有线程句柄的任务
    不退款——拿不到句柄就无法判断 worker 是否已在别处结算过，贸然退会双退。
    该约束由新增用例固化（原实现如此，此前无测试记录）。

验证：ruff 全过 · pyright 0/0 · pytest 209 passed（189→209）·
生产 data/ 未被触碰（全部用例走 tmp_path 沙箱）。
 2026-09-26 19:04:36 +08:00
snowy-yang 2b4704183c refactor: session 改用 itsdangerous，去掉手写密码学原语 
为什么：core/session.py 原本手写 HMAC + 自定义 base64 签名，等于自己复刻
itsdangerous 的核心功能——密码学原语自己实现是风险点，且难与上游的安全
修复同步。

关键约束（换库的坑）：两者字节级格式并不一致——手写实现用标准 base64 且
保留 '=' 填充，itsdangerous 用 urlsafe 且去填充。若不钉住旧格式，部署瞬间
线上全部登录态会失效。

改法：
- 用 URLSafeTimedSerializer，按 secret 做 lru_cache(maxsize=8)，避免每请求
  重建序列化器
- loads() 增加 max_age 参数（默认 None，保持既有「不叠加服务端过期」行为）
- get_uid() 顺带加固：cookie 里塞非整数不再抛 ValueError 变 500，改为返回 None
- 删除 _derive_key / _int_to_bytes 及手写 HMAC/b64

验证：新增 2 例回归测试，其中 legacy cookie 样本由替换前的旧实现在固定时间戳
1700000000 下采集，钉住的是格式而非实现；另一例验证 max_age=None 接受旧
时间戳、max_age=60 拒绝。
 2026-09-26 18:53:47 +08:00
snowy-yang 0b25f215a2 fix: 恢复任务监控线程的启动点（迁移中丢失，超时取消与账本对账静默失效） 
为什么：d209af8 基线在 main.py:4594 用 threading.Thread(...).start() 启动
_task_monitor_loop；8446166「移除 Flask」把实现搬进 services/runtime.py 时
只搬了函数定义、丢了启动点，6288a98 拆包后落到 services/tasks.py，HEAD 仍
无任何调用方——函数体完好，但一次都没跑过。

后果（自该次迁移起持续失效）：
- 心跳超时不再暂停离线设备的批量任务，排队名额无法释放
- 离线 >30 分钟 / 运行 >4 小时的任务不再自动取消
- 终态任务记录、tasks/ 孤儿目录、downloads 缓存不再回收
- ledger_recover_orphans 停摆，预扣未退款的账永久悬挂在 open 状态

改法：新增 start_task_monitor()，加锁保证幂等（重复调用返回 False），
在 create_app 的 lifespan 里用 asyncio.to_thread 启动；新增 start_monitor
开关供测试显式关闭。裸 TestClient(app) 不进上下文管理器、不触发 lifespan，
故既有测试不受影响。

验证：pytest 新增 3 例（幂等 / lifespan 启动 / 可跳过）；端到端 uvicorn 冒烟
日志出现「任务监控线程已启动」。
 2026-09-26 18:53:40 +08:00
snowy-yang 095171e0b7 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
 2026-09-26 15:03:47 +08:00
snowy-yang 1d86ec87ec refactor: 抽两个 zip worker 的重复实现，并补齐暂停/恢复路径的测试 
为什么先测后改：_batch_zip_worker(347 行) 与 _podcast_zip_worker(295 行) 近乎
复制——连 _wait_if_paused 那 16 行都逐字相同（注释只差一行）。重复的代价是实打实
的：上一次修的 zip_valid「变量可能未绑定」缺陷就是**同型出现在这两处**。
但暂停/恢复是一条并发状态机，此前**零测试覆盖**，直接改不符合先测量后改动。

所以本 commit 分两步落地。

第一步（新增 tests/test_zip_workers.py，9 个用例）——行为级契约
断言只用「调用 worker 后世界里发生了什么」：任务终态、ZIP 内条目、账本守恒
（delivered / refunded）、暂停/恢复/取消后的余额。不引用任何内部函数名，
这样第二步重构时测试不必跟着改，才具备等价性验证能力。
- batch：正常完成 / 暂停→恢复 / 暂停→取消 / 全失败退费 /
  循环中途取消 / 发布前一刻取消
- podcast：正常完成 / 暂停→恢复 / 全失败退费
- 脚手架一律用 reserve_and_open 真预扣（ledger_open 只记账不扣款，
  会让「退款」凭空给余额加次数，守恒断言就失去意义）

写测试过程中暴露两处代码与注释不符，如实钉住而非粉饰：
1. **循环内取消并不会「交付已打包部分」**。zip_valid = True 位于 with zipfile
   块**之后**，而 while 循环内的任何取消都以异常**穿过**该块
   （zipfile.__exit__ 仍写出中央目录，但那行赋值不执行）→ zip_valid 恒为 False
   → delivered = ok_count if zip_valid else 0 恒为 0。源码注释所称的
   「部分成功后取消照常交付（成果守恒）」只在发布前最后一个检查点可达，
   已分别用两个用例把两条路径都钉住。
2. podcast 的 _wait_if_paused 与 batch 版本除 docstring 外完全一致。

第二步——抽取（只抽逐字相同、零语义差异的部分）
- _taskcore._wait_if_paused(task, pause_ev, cancel_ev, done)：done 写成参数
  而非捕获闭包，使函数脱离两个 worker 各自的局部状态
- _taskcore._task_work_dir(task_id)：任务专属目录约定（ZIP 与中间文件都落
  tasks/<task_id>/，对根目录的缓存清扫免疫）
- 两个 worker 各自的 16 行副本与 2 行 mkdir 删除，调用点改为显式传参

复杂度实测量（同口径，git HEAD 对比）：
  两个 worker 合计  行数 642 → 604（-38）  决策点 152 → 140（-12）
  新增共享实现      _wait_if_paused 27 行/7 决策点 · _task_work_dir 11 行/1
**净行数基本持平（总量 -38 +38）**——重复代码抽取的收益从来不是行数变少，
而是**唯一真源**：以后改暂停语义只需改一处，不会再出现「同型缺陷出现在两地」。

验证：pytest 184 passed（175 → 184，+9）· ruff 0 · pyright 0 errors/0 warnings
 2026-09-26 14:57:28 +08:00
snowy-yang 70ca21974b refactor: 拆掉 auth_system 包内循环依赖，路径常量收敛到 db 单一来源 
为什么：auth_system 的 11 个子模块此前构成一个强连通分量——db.py 与 backup.py
为了「动态读取路径常量」而在模块级 `import auth_system`（包自身），而包 __init__
又再导出这两个子模块的全部符号，互相指成环。

这个环当前并不崩（实测 8/8 种导入姿势全通过），它的代价是**双绑定**：
`auth_system.DB_PATH is auth_system.db.DB_PATH` 初始为 True，但只 patch 其一
另一处不跟随。于是测试不得不把 4 个路径常量**两处都 patch**
（setattr(auth,...) + setattr(db,...)）——而漏 patch 的后果是静默写生产库，
commit fc7fc21 修的那次「黄金测试写进生产库」正是这么来的。

改法：让路径常量回归**模块属性单一来源**。
- db.py：删掉 `import auth_system`，内部改用本模块常量（DATA_DIR / DB_PATH /
  SECRET_KEY_PATH）。这些常量本就定义在本模块，绕道包属性纯属多余。
- backup.py：改用 `import auth_system.db as db` 做模块限定访问，路径走
  db.BACKUP_DIR / db.DB_PATH——保留动态读取能力，来源从「包属性」换成
  「db 模块」，与唯一来源一致。
  注意**不能**写成 `from . import db`：该形式在静态图里同时指向包本身与子模块，
  会把这个环重新连上（实测确实如此，SCC 从 11 降到 2 就卡住了）。
- admin_site.py：5 处 `auth.DB_PATH` / `auth.BACKUP_DIR`（auth 是包别名）同样
  改为经 db 模块访问。**这处不修就会出事**——它读的是包属性快照，而测试已改为
  patch db 模块，于是备份上传会静默落到生产 data/backups/（本次实测真的发生了，
  2 个 upload_*.db 已清理，副本留在临时目录）。
- 测试：7 个文件的 patch 目标从包属性迁到 auth_system.db.*。
- __init__.py：补注释说明这些常量在此只是 import 快照，禁止经包属性重定向。

验证：
- Tarjan 重算：非平凡强连通分量 11 → **0**（import 图已是 DAG）
- AST 全仓扫描：经包属性访问路径常量的点 **0 处残留**
- 行为：子进程内 patch auth_system.db.* 后，get_conn 连的库 / create_backup
  落盘目录 / get_secret_key 目标路径**三者全部跟随**
- 导入姿势回归 8/8 通过
- 门禁：ruff 0 · pyright 0 errors 0 warnings · pytest 175 passed
 2026-09-26 14:37:58 +08:00
snowy-yang ad8c30d932 refactor: 下载/标签/格式探测改用成熟库（aria2 + mutagen + filetype） 
为什么：原先三处都在手写轮子——ffmpeg CLI 拼参数写标签、aiohttp 单连接手搓
下载、自己比对魔数判格式。手写部分既难测又易错；改走成熟库后测试从 144 涨到
175，并且彻底去掉了 ffmpeg 这个外部二进制依赖。

下载 → aria2c 常驻 JSON-RPC（aria2p 客户端），新增 _aria2.py
- 单例后端：首次调用时拉起 aria2c，只监听 127.0.0.1 且强制随机 secret
  （无鉴权的 aria2 RPC 允许本机任意进程操纵队列、读写任意文件）
- split=5 / max-connection-per-server=5 多连接 + 原生断点续传
- 异常语义与内置通道逐一对齐：取消/超限清残片抛 DownloadCanceled /
  DownloadException，任务失败/超时保留残片抛 RequestException 供续传
- 取不到 aria2c 时 get_backend() 返回 None，自动降级到内置 aiohttp 通道
  （本机无 aria2c 的降级路径已实测）

标签 → mutagen 纯 Python 写入，新增 tagging.py
- 取代 _write_metadata_with_ffmpeg + _build_format_args（226 行 shell 参数拼接）
- MP3(ID3v2.3)/FLAC/M4A/OGG/Opus 分容器实现，无子进程、不重编码
- 就地改帧：TXXX 等未触及的标签原样保留（ffmpeg 整帧重写会丢）
- 临时文件 + os.replace 原子替换，写坏不会留下半个文件
- 为什么不是 ffmpeg-python（原方案）：实测它用 **kwargs 建模选项，无法表达
  重复键（-metadata ×N），list 值还会被字符串化成 "['0', '1:v']"；-map 尚有
  内置的 stream 位置参数入口，但 -metadata 无解，且 overwrite_output=True
  生成的 -y 被排到输出文件之后、可能失效

格式探测 → filetype，改 _http.py
- 删除手写的 _AUDIO_MAGIC 魔数表，改用 filetype.guess() 判 MIME
  （audio/* 放行，video/mp4 作为容器显式放行）

配套
- Dockerfile：镜像不再装 ffmpeg，改装 aria2
- pyproject：新增 filetype / aria2p / mutagen；dev 加 httpx2（消除测试里的
  StarletteDeprecationWarning，现 0 warning）
- __main__.py / __init__.py / models.py：清理 ffmpeg 相关导出与文案

测试：新增 31 个用例（test_aria2.py 13、test_tagging.py 21，含最小合法 FLAC
样本构造）；全套 175 passed / 0 warning
 2026-09-26 13:54:44 +08:00
snowy-yang fc7fc21284 test: 黄金契约测试改用站点库副本，不再写生产库 
tests/test_golden.py 的 fixture 直接指向 data/site.db 并注释为「只读」，但快照里
有 2 条 auth=user 的 POST /download（均返回 400），这条路径会 reserve_and_open
开账、失败后 settle_refund 退款——于是**每次 pytest 都往生产库插 2 行
billing_ledger**（status='rejected', reserved=1, refunded=1），并把该用户的
last_active 顶到测试时刻。

发现时生产库已累积 83 行这样的行（时间戳与历次 pytest 运行一一对应），库体积
也因此长了 2 个页（151552 → 159744）。净余额为 0（预扣 1、退款 1），不丢钱，
但污染台账与后台台账视图，而且让「跑测试不动生产数据」这个前提不再成立——
排查时无法再用「库指纹没变」来证明冒烟/测试是安全的。

改法：复制一份 data/site.db（含 -wal/-shm 边车文件）到 tmp_path，再把
auth_system.DB_PATH/DATA_DIR 与 core.db.DB_PATH/DATA_DIR 一并指向副本。
契约保真度不变（同一份真实数据、同一 schema），写入全部落在临时目录。
_session_for 也改为读 auth_system.DB_PATH，保证「造 Cookie」与「发请求」
命中的是同一个库（原先写死路径，换库后会静默读生产库拿到错误 login_seq）。

验证：改前改后各跑一次完整套件，data/site.db 的 sha1 / 体积 / mtime 三项完全
不变，billing_ledger 行数停在 83；144 passed；ruff All checks passed；
pyright 0 errors / 0 warnings。

注：生产库里既有的 83 行测试残留**未删除**（那是生产数据，需确认后再动）；
ledger 自带保留期清扫（auth_system/ledger.py 的 DELETE ... settled_at <= ?）
到期会自行回收。
 2026-09-26 13:21:26 +08:00
snowy-yang da3d013e9c chore: 清理前端与容器脚本中指向已删台账的过时编号 
模板/样式/脚本的注释里散落着「第 N 条」「F59」「P3-43」这类编号，它们指向的
修复验收台账与交接文档已在本轮删除——留着既检索不到、也对不上号，还让后来读
注释的人以为存在一份可查的编号清单。本次只动注释，正文零改动。

覆盖范围（全仓一致）：
- templates/index.html 163 处、static/site_auth.js 55 处，共 218 处编号整段摘除
  （含「第 N 条（Px）：」前缀与「（Fxx 短标签）」括号）。
- 容器/配置 16 处：docker-compose.yml、entrypoint.sh（F59 / 第 93 条 / 第 97 条）、
  Dockerfile（T7 / 第 97 条）、.dockerignore（T1 / 第 97 条 / 第 55 条 / P2-9）、
  .env.example（F59 / 第 100 条 / 「详见交接文档 F11」这条失效指引）、.gitignore（P3-41）。
- Python 4 处：core/config.py（D-1）、services/tasks.py（O-5×2）、services/_shared.py（O-5）
  ——上一轮 Python 侧清理的漏网。

为什么规则要收窄（两类误伤，实测踩到）：
1. 标签首字母不能用泛化的 [A-Z]：X5 是 QQ 浏览器内核、ES5 是 JS 版本，都不是编号。
   泛化后会把「微信 XWeb/X5、QQ 内置」改成「微信 XWeb/、QQ 内置」，把
   「Chromium <87 的老 X5 不识别 inset」改成「老 不识别」。现按本仓真实用过的
   任务族白名单收窄（A B C D F O P R S T U），X5/ES5 原样保留。
2. 括号内「编号 + 长说明」不能整段删：「（F51 只防了切歌，这里补同歌翻页）」
   整段删掉会连说明一起丢；现只摘编号、保留说明文字。

为什么同步改黄金契约快照：题头注释属于模板内容，改了注释首页字节数必然变
（466261 → 464333），tests/golden/responses.json 的 index 条目按既定流程刷新
html_len/html_sha256；并在 tests/test_golden.py 补一段说明，写清该条目记的是
「当前模板」而非 Flask 期数值、以及有意改模板后如何重算
（html_len = 文件字节数 - 1，sha256 = 文件去掉末尾换行后的哈希）。

验证（全部通过）：
- 与 HEAD 比对：剥离全部注释后的正文逐行一致（唯一差异是删掉了一处行尾空注释），
  行数不变、每行半角括号/引号数量不变 → 代码与字符串零改动；
- node --check 通过（静态 JS + index.html 内联脚本），<style> 块花括号平衡；
- 真实 uvicorn 冒烟：/health /user/status /api/topen → 200、/admin/site/backup/list → 403，
  /static/site_auth.js 响应体与本地文件 sha1 相同，/ 无「第 N 条」残留；
- ruff All checks passed；pyright 0 errors / 0 warnings；pytest 144 passed。
 2026-09-26 13:18:44 +08:00
snowy-yang 838d635bc5 fix: 修复重构遗留缺陷，补齐 pyright 检查盲区 
上一次重构（8446166）声称「pyright 0 错误」，但 pyproject 里 pyright 的 include
只覆盖 core/web/services —— 根目录 6 个应用模块与整个 tests/ 从未被检查，而
requests→sync_http 迁移的遗留恰好全部藏在那里。补齐 include 后立刻暴露
7 errors + 9 warnings，其中数处在运行时静默失效。

修复：
- services/runtime.py：删除 _podcast_billing_count/_billing_ids_count 两个
  无调用方的死函数。它们仍调用 api_service._safe_get_request_data()，而该方法
  在剥离 Flask 时已被删除，异常又被 except 吞掉 —— 一旦被调用，播客/歌单计费
  恒为 1 次且不报任何错。路由层已各自实现同口径版本，故整体删除。
- web/routers/admin_site.py：备份上传的类型判定必须用 starlette 的 UploadFile。
  fastapi.UploadFile 是它的子类，而 request.form() 返回基类实例，用错会让
  isinstance 恒为 False，把每一次真实上传都判成「请选择数据库文件」。
  已补 4 例真实 multipart 回归测试，并用变异测试确认能抓住该缺陷。
- auth_system.py：修正 create_user（实返 sqlite3.Row|None）与 list_cards
  （实返 (cards,total) 元组）与实现不符的返回注解；注解一改正，立刻暴露出被它
  掩盖的 register.py 中 int(user['id']) 未做 None 检查的 500 崩溃路径，已补守卫。
- music_downloader.py：修正注解引用的 core.sync_http.Response（正确名应为
  SyncResponse）；封面缓存淘汰不再读类型为 Optional 的 deque.maxlen，改用命名常量。
- services/runtime.py：zip worker 的 result.music_info 可能为 None，原样使用会
  炸掉整批任务，改为按单曲失败处理。
- music_api.py：三处 isinstance 三元表达式收敛为 _as_dict() 帮助函数。
- web/main.py：文档串移除已删除的 Flask 兜底描述，补充 data/ 相对 CWD 解析的提醒。

验证：ruff check 通过；pyright 0 errors / 0 warnings（filesAnalyzed=67）；
pytest 144 passed；真实 uvicorn 启动冒烟通过（/health、/、静态资源 200，
未鉴权管理端点 403）。生产库仅做只读 integrity_check，未被写入。
 2026-09-26 11:52:06 +08:00
snowy-yang 8446166120 refactor!: uv 管理环境 + 彻底删除技术债（Flask 与 requests 全部移除） 
## uv 环境管理
- pyproject.toml 声明 dependencies + [dependency-groups].dev，uv.lock 精确锁定
- 删除 requirements.txt / requirements-fastapi.txt / requirements-dev.txt
- .python-version = 3.12；Dockerfile 改用 uv sync --frozen（可复现构建）
- 新增 jinja2（首页渲染）

## 删除 Flask 技术债
- 从 main.py 用 ast 精确剥离 56 个 Flask 节点（路由/中间件/错误处理/启动），
  框架无关的服务层落为 services/runtime.py（MusicAPIService、下载/打包 worker、
  任务监控、缓存清扫），零 Flask 依赖
- 删除 main.py（4527 行）与 auth_routes.py（1050 行）
- auth_system.py 移除会话/请求上下文层（login_session/current_user/login_required/
  admin_required/_client_ip 等），保留数据与业务层
- 新增 core/net.py（IP 解析）、web/auth_state.py（登录锁定/2FA 票据/发码限流）
- FastAPI 侧改直接依赖 services.runtime，不再 import main
- web/app.py 去掉 Flask fallback；入口默认根路径模式（API_PREFIX 可选）

## 删除 requests 技术债
- 新增 core/sync_http.py：requests 风格的同步门面（底层 aiohttp 连接池，
  流式读取经有界队列背压），含 Session/headers/(connect,read) 元组超时兼容
- core/utils、auth_system、podcast_api、music_downloader、services 全部切换
- 实测真实下载 5.2MB 音频完整成功

## 质量门禁归零
- ruff：0 错误（B904 全部修复，不再忽略）
- pyright：0 错误（类型收窄修复）
- pytest：140/140（含 golden 契约回归、root 模式 66 项路径覆盖）
- 真实 uvicorn 启动：/health、/、/static、受保护端鉴权全部正确

新增 tests/golden/responses.json：删除 Flask 前捕获的 32 例响应快照，
FastAPI 逐字段复现——删除巨石后行为回归仍有硬证据。
 2026-09-26 11:10:17 +08:00
snowy-yang f5d1e3c3a9 feat: 支持纯 FastAPI 模式（根路径服务前端）+ 修任务端点路径 
- web/app.py：create_app(api_prefix=) 参数化前缀——'' 即根路径模式，
  87 条路由直接服务前端使用的路径，无需 Flask 兜底
- web/main.py：WEB_MODE=dual（默认，迁移期）/ fastapi（纯 FastAPI）切换
- 修真实路径缺陷：任务类端点漏了 /api 段（Flask 为 /api/topen 等，
  原写成 /topen），根路径模式下前端会 404。已改为 /api/topen、/api/queue、
  /api/batch_progress、/api/task/*；fe_error 同步修正
- 奇偶校验路径映射同步更新

验证：
- tests/test_root_mode.py 新增 66 项：前端调用的每条路径在纯 FastAPI 模式下
  均非 404；root 模式不再暴露 /api/v1
- 纯 FastAPI 模式真实启动（uvicorn, PORT=5002）实测：
  /health、/、/static 200，/song、/api/task/list 401（鉴权生效）
- 全套 pytest 135/135；ruff All checks passed；pyright 0 errors；奇偶 36/36
 2026-09-26 10:25:05 +08:00
snowy-yang 9df0028195 feat(routes): 迁移下载/批量打包/播客下载（账本事务）+ 修密钥绑定缺陷 
迁移端点：
- POST /api/v1/download（单曲：file 后台任务 / json 同步交付+结算）
- POST /api/v1/download/batch_zip（按去重歌曲数计费）
- POST /api/v1/podcast/download、/podcast/download/batch_zip
- 新增 web/billing.py（预扣+开账同事务 / 只退 open 行 / rename 承接）
  与 web/tasks_registry.py（任务登记/容量闸/账本撞名重试，与 main 同口径）
- worker 仍复用 main 既有实现（无 flask 依赖），账本与交付语义不变

修复我引入的真实缺陷：
- download 参数校验分支（ID/音质/格式非法）漏退款 → 预扣泄漏。改为统一 _fail() 退款
- web/routers/{auth,register}.py 在导入期绑定 deps.secret_key，导致 patch web.deps.secret_key
  无效、且测试顺序相关。改为调用期 deps.secret_key() 解析

测试：tests/test_download_billing.py 7 项沙箱用例如实断言账本守恒
（预扣必退、无 open 行残留、次数不足不建任务）；
全套 pytest 69/69（顺序无关）；ruff All checks passed；pyright 0 errors；奇偶 36/36。
 2026-09-26 10:13:16 +08:00
snowy-yang 915358405c feat(routes): 迁移注册/找回密码/卡密/验证码端点 
- web/routers/register.py：auth/send_code、auth/register、auth/trial、
  auth/redeem、auth/forgot_password
- 同步调用（SQLite 事务/SMTP/PBKDF2）走 asyncio.to_thread；发码 IP 限流复用
  auth_routes._SEND_CODE_IP（跨栈共享计数）
- 注册成功路径签发会话 Cookie；管理员找回密码仍防枚举拦截

测试：tests/test_register.py 6 项沙箱用例（播种验证码绕 SMTP）——
协议门槛、注册成功建号+赠送+会话可用、验证码错误、找回重置后可登录、
管理员找回被拦、卡密充值。
全套：pytest 62/62；ruff All checks passed；pyright 0 errors；冒烟 10/10。
 2026-09-26 10:00:39 +08:00
snowy-yang 91c032a1c3 feat(routes): 迁移认证端点（login/logout/heartbeat/ann_seen） 
- web/routers/auth.py
  · login：邮箱/用户名登录、超长密码短路、失败锁定、封禁/禁用分支、
    管理员转 2FA 票据；成功签发 core.session 会话 Cookie（与 Flask 同格式）
  · logout：递增 login_seq 顶号 + 删 Cookie
  · heartbeat：次数校验（401/expired 语义同 Flask）
  · ann_seen：记录已读公告版本
  · 失败锁定与 2FA 票据表复用 auth_routes 模块级状态（跨栈共享，防绕锁定）
  · PBKDF2 与库操作走 asyncio.to_thread，不阻塞事件循环

测试：tests/test_auth_routes.py 5 项，全部使用**沙箱库**（pytest tmp_path +
monkeypatch auth_system/core.db 路径），不触碰生产 data/site.db。
全套：pytest 56/56；ruff All checks passed；pyright 0 errors；奇偶校验 28/28。
 2026-09-26 09:54:14 +08:00
snowy-yang 0104ae55e5 feat(routes): 迁移音频流代理与结果交付端点（流式） 
- web/routers/stream.py：/api/v1/audio_stream 音频范围流代理
  · 签名校验（core.security，密钥同源两栈互认）；HEAD 直接 200 不请求上游
  · Range 原样透传上游（206 + Content-Range，拖动进度可用）
  · 编码透明：上游带 Content-Encoding 时不沿用压缩前长度（同 Flask F92）
  · StreamingResponse 16KB 分块，finally 关闭上游（下游中断亦释放）
- core/http_client.py 增 open()：返回未关闭流式响应，便于先读状态码再转发
- web/routers/delivery.py：/download/result、/download/batch_zip/result
  · 归属 403 / 进行中 202 / 暂停 200 / 取消 200 / 失败 500 / 缺失 404 分支逐一对齐
  · FileResponse 流式交付 + no-store + X-Download-Filename；清理由监控线程统一回收

验证：pytest 51/51（新增 5 项流代理：无效 token/HEAD/全量/Range 透传/上游关闭）；
ruff All checks passed；pyright 0 errors；奇偶校验 26/26；实测 5.2MB 流与
Range 206 正确。
 2026-09-26 09:49:22 +08:00
snowy-yang 6c3181341b feat(routes): 迁移账号/全局歌单端点 + 鉴权依赖测试 
迁移路由（/api/v1/*，与 Flask 同端点逐字段对齐）：
- account/vip：admin/user 双路径 + 5 分钟缓存（降级结果 30s），
  VIP 探测单飞锁与 Flask 同源跨栈共享；未登录可访问（同 Flask）
- global/playlists、global/playlist：管理员闸（require_admin，403 对齐）
- web/deps.py 新增 require_admin；_resolve_user_cookies 支持可选用户（匿名审计保底）

测试：46/46（新增 10 项鉴权依赖：有效/管理员/封禁/禁用/顶号/伪造 Cookie、
401/403 闸）；ruff All checks passed；pyright 0 errors。

契约奇偶校验：16 项全 OK（新增 account:vip、global:playlists/playlist、
非管理员 403）；uvicorn 实跑双栈 account/vip 均 200、未授权歌单 403。
 2026-09-26 01:15:22 +08:00
snowy-yang a2758aa0da feat(routes): 迁移解析端点 /song /playlist /album + 响应卫生中间件 
迁移路由（/api/v1/*，与 Flask 同端点逐字段对齐）：
- song（type: url/name/lyric/json）、playlist、album
  个人账号路径实现全局账号冒用拦截（同 Flask 口径）；json 模式 asyncio.gather 并发
  song/url/lyric（歌词失败不阻断，与 Flask 线程池语义一致）
- core/media.py：format_file_size/quality_display_name/parse_cookie_str 纯函数复用

web/middleware.py（镜像 Flask after_request）：
- 音频直链 → HMAC 签名代理地址（密钥同源，两栈 token 互认）
- 安全头 nosniff/DENY/Referrer-Policy/CSP 基线；Server 抹为 NeteaseUrl；429 带 Retry-After
- 纯 ASGI 逐段转发（不破坏流式下载）；JSON 200 延迟 start 并**重算 Content-Length**
  ——修实测 IncompleteRead（原实现转发旧长度 + 新 body）

契约奇偶校验：12 项全 OK（新增 album/playlist/song×3）；
token/CDN 主机归一化（均为易变值，非契约漂移）。

验证：pytest 36/36；ruff All checks passed；pyright 0 errors；
uvicorn 实跑 /api/v1/song 直链已代理、CSP/Server 头正确。
 2026-09-26 01:12:54 +08:00
snowy-yang 2c55b55e03 feat(routes): 迁移查询类路由到 FastAPI + 会话互通 + 统一错误/限流 
会话互通（迁移关键）：
- core/session.py：itsdangerous 兼容的签名 Cookie 编解码（同密钥/同 salt/同
  时间戳编码），Flask 与 FastAPI 双向可读——实测 F->core 与 core->F 双向解出一致，
  篡改/错密钥返回 None

FastAPI 基础设施：
- web/deps.py    会话→当前用户（封禁/顶号校验，口径同 auth_system.current_user）
- web/errors.py  AppError + 全局异常处理，404/405/400 统一为本站包体
- web/ratelimit.py 复用 core.state 同一批限流桶（跨栈共享，避免绕框架绕过限流）
- core/repo.py  补 get_user_by_id（异步）

迁移路由（/api/v1/*，与 Flask 同端点逐字段对齐）：
- toplist / artist_songs / comments / search，走 music_api 异步方法
- search 的服务器昵称遮蔽改为 FastAPI 侧异步实现（不再依赖 main）

契约奇偶校验：扩展至 7 项（含登录会话互通 + 未登录 401），全 OK；
CDN 分片主机差异归一化（上游易变值，非契约漂移）。

验证：pytest 33/33；ruff All checks passed；pyright 0 errors；
uvicorn 实跑未登录 401 包体与 Flask 一致。
 2026-09-26 01:09:01 +08:00
snowy-yang c77ef40fd5 feat(db): 同步栈读写并发（_q 去锁）+ core.db 并发/跨loop 修复 
auth_system._q：单语句读不再持 _DB_LOCK —— WAL 下每连接读一致性快照，
读写互不阻塞；旧实现把全部读也串行化且被写挡住。写事务（_x 与 24 个
with _DB_LOCK 块，经扫描均为写事务）仍全程串行，无写-写竞争。

core.db 并发修复（由测试暴露的真实缺陷）：
- WAL 切换竞态：并发连接同时执行 PRAGMA journal_mode=WAL 争排他锁
  → 专用锁内串行切换 + 二次复查（busy_timeout 前置）
- 跨事件循环锁：模块级 asyncio.Lock 绑定首个 loop，多 loop 场景报
  "bound to a different event loop" → 锁按 loop 隔离

测试：25/25 通过（新增「读不被写锁阻塞」红转绿、读+同步写者并发 WAL、
异步并发读）；
lint: ruff All checks passed；pyright 0 errors。
验收：冒烟 10/10、奇偶校验 2/2、uvicorn 真实启动 Flask 兜底+FastAPI 双通。
 2026-09-26 01:03:18 +08:00
snowy-yang 0f2e72db44 feat(db-async): 站点数据异步读写仓储 + FastAPI 生命周期 
- core/repo.py：经由 core.db(aiosqlite) 读写 auth_system 的**同一份** site.db
  （settings/announcements/users 只读/ledger 只读），字段口径对齐 auth_system；
  读并发、写串行、WAL 读写同时进行
- web/routers/site.py：/api/v1/site/announcements、/api/v1/site/stats（异步多表并发读）
- web/app.py：lifespan 关闭时释放 aiohttp 连接池（含按 loop 隔离的 session）

写路径说明：迁移期写操作仍归 auth_system 的 _DB_LOCK 事务口径，避免两套写
路径互相踩踏；本层先只做读。

验证：pytest 22/22（新增 6 项含「异步读 + 同步写者并发 WAL」）；
/api/v1/site/* 实测读到共享库（3 用户/1 管理员）；ruff/pyright 干净。
 2026-09-26 00:34:11 +08:00
snowy-yang 4962542e78 feat(core): requests 兼容异步垫片 + 同步/异步桥 
- core/aiohttp_compat.py：以 requests 同形 API（post/get + Response.json/text/
  status_code/raise_for_status + HTTPError/RequestException/Timeout）实现异步请求，
  使既有 requests 风格代码可「加 await + async def」最小改动迁移；4xx/5xx 不抛、
  仅 raise_for_status() 抛（与 requests 语义一致，保住风控判断逻辑）
- core/async_bridge.py：run_sync(coro) 经常驻后台事件循环线程执行协程并阻塞等待，
  供迁移期同步调用方（遗留 Flask 路由/线程池）复用异步实现

验证：pytest 16/16；ruff All checks passed；pyright 0 errors。
 2026-09-26 00:27:47 +08:00
snowy-yang 9f56f68b66 chore(async-infra): 异步基础层 + 工具链 + 清理 
异步基础层（core/）：
- db.py   aiosqlite + WAL：读路径无锁并发、写路径 asyncio.Lock 串行，
          busy_timeout 自旋——实现「读写同时进行」（旧实现用 RLock 全读串行）
- http_client.py  aiohttp 连接池 + 有界重试（5xx 重试 / 4xx 不重试）+
          响应体上限 + 流式接口；按事件循环隔离 session（支持迁移期双 loop）

工具链：
- pyproject.toml   ruff(E/F/W/I/B/UP/C4/ASYNC/S/RUF) + pyright(basic) + pytest(asyncio auto)
- requirements-fastapi.txt  FastAPI/aiohttp/aiosqlite/aiofiles 等目标栈
- requirements-dev.txt      开发依赖（pytest/ruff/pyright）

清理：删除无用脚本 _csscheck.py 与产物标记 _css_ok.txt/_pkg_ok.txt，同步 .gitignore

验证：pytest 10/10（含「写 200 条同时 4 读协程零异常」并发用例）；
ruff All checks passed；pyright 0 errors。
 2026-09-26 00:24:00 +08:00