hhhge/NeteaseUrl
Archived
1
0 Fork 0
Code Issues Actions Packages Projects Releases Wiki Activity
74 Commits 1 Branch 0 Tags
65adfc9089f9ff065f0d60ed30db392d16996dee
Commit Graph
74 Commits
This Branch
This Branch
All Branches
Author SHA1 Message Date
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 064a89d726 refactor: 删除旧前端单体，React 产物成为唯一首页来源 
为什么：React 迁移已验证完毕（浏览器冒烟全过、golden 刷新），
legacy 模板兜底分支指向已删除的文件只会制造幻觉路径。删除
templates/index.html（466KB）与 static/site_auth.js（80KB）及
/static 挂载；jinja2 随兜底分支失去唯一使用者，连同 markupsafe
一并移出依赖（63 包 -2）。_render_index 简化为直接读构建产物——
dist 已入库恒存在，无需分支。
 2026-09-27 18:41:30 +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 58853abd3c chore: 提交 React 前端构建产物（app.js 330KB / auth.js 38KB / app.css 56KB） 
为什么：部署不经 node 构建（dockerignore 排除了源码），服务端
直接读 dist/index.html 与 /assets，因此构建产物必须入库；
文件名经 vite 固定（无内容 hash），golden 契约才能跨构建成立。
gzip 后 app.js 97KB / auth.js 12KB / app.css 11KB。
 2026-09-27 18:35:06 +08:00
snowy-yang 8803444755 feat: 后端接线上 React 构建产物，legacy 模板降级为兜底 
为什么：前端迁移到 Vite 后，首页应直接返回 frontend/dist/index.html
字节（golden 口径随之变为构建产物原样字节），仅当 dist 未构建时
回退 Jinja2 渲染的 legacy 模板。同步挂载 /assets 静态目录、排除
frontend 的 node_modules/tsbuildinfo 入库、docker 构建只带 dist
不带源码、ruff/pyright 排除 frontend 目录（TS 侧由 tsc+vite 把关）。
 2026-09-27 18:35:04 +08:00
snowy-yang 3a089caff2 feat: 前端迁移 React 18 + Vite 5 脚手架与保真移植的控制器 
为什么：index.html 单体 4600 行 ES5 已到维护极限，迁移到 Vite 工程
获得热更新、类型检查与模块化能力。迁移策略是保真优先——业务逻辑
不重写为 React 组件（行为漂移风险），而是逐字移植为
legacy.ts/auth.ts 两个 @ts-nocheck 控制器模块；React 只接管静态
骨架与响应式显隐（tab/modal/drawer/toast），动态列表/播放器/歌词
仍走 id + innerHTML 命令式更新。

关键决策：
- boot 包装：旧脚本原在 body 末尾可直取 DOM，模块化后顶层事件
  绑定会在 import 求值时打在 null 上，全部副作用包进
  __legacyBoot()/__authBoot() 由 App useEffect 骨架落盘后调用
- 轻量 store：单一可变 AppState + notify() + useSyncExternalStore，
  沿用旧版"改 state 后手动通知"心智模型
- modalBus：弹窗栈 + useSyncExternalStore，Escape 走 closeTopmost，
  stats/cookie 弹窗经 __legacyApi 调 legacy 内部专用关闭（清定时器/
  复位视图）
- vite 固定产物文件名（无内容 hash），保证 index.html 字节级稳定，
  golden sha256 契约才跨构建成立
 2026-09-27 18:34:49 +08:00
snowy-yang 0dbbb3ed63 refactor: 移除 music_api 的 16 个死掉的同步兼容门面 
music_api/compat.py 是「同步调用异步实现」的桥接门面——每个方法都用
core.async_bridge.run_sync 把 NeteaseAPI 的协程跑起来。调用方此前已陆续
迁到原生异步（await NeteaseAPI().xxx()），这 16 个方法在仓内（web/
services/ tests/ CLI）已零调用，只剩 __init__ 的再导出，属迁移期残留。

仅 url_v1 还有唯一调用方（music_api.podcast 的同步解析路径），予以保留，
并在 docstring 标注「应删不应增」，待 worker 子系统异步化时一并清除。

门禁：ruff 全过 / pyright 0-0 / pytest 387 项，失败数与前次一致（2 项
index golden，源于未提交的前端迁移，与本次无关）。
 2026-09-27 17:51:22 +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 da83201403 refactor: run_zip_job 四路终态收尾拆解（167 行 / 圈 37 → 32 行 / 圈 5） 
为什么：run_zip_job 是全仓圈复杂度最高的函数（37），167 行里四个终态——正常交付、
全部失败、取消（含部分交付/全额退两条支路）、异常（同样两条支路）——各写一段
8~20 行的收尾内联在 try/except 里，且都伸手去读同一批局部变量。上一轮抽这个引擎时
就已指出「还可以再拆」，当时为控制单次改动面留了下来。

改法：把「一次运行」的状态收进 _ZipRun，四个终态各自成函数。
  _ZipRun             job / task_id / settle / tally / task / params /
                      cancel_ev / pause_ev / items / zip_tmp_path / zip_valid / t0
  _progress_of        构造进度回调（原先是个内嵌闭包）
  _start_zip_run      置 running + 组装清单 + 写 total + 计费补扣
  _build_zip_archive  建临时 ZIP + 逐窗口填充 + 置 zip_valid + 记耗时
  _publish_delivery   正常交付（结算 → 锁内复查 → 发布 result → on_delivered → 日志）
  _finish_all_failed  全失败（丢弃空包 + 全额退费 + 转 error）
  _finish_canceled    取消（部分交付 / 全额退两条支路）
  _finish_business_error  DownloadException（保留我们自己拼的用户可读文案）
  _finish_unexpected  通用异常（先落 traceback 再泛化文案，两条支路）

复杂度（同口径 AST 实测，HEAD 与工作区由同一脚本测出）：
  run_zip_job        167 行 / 圈 37 / 嵌套 4  →  32 行 / 圈 5 / 嵌套 2
  文件内最大圈复杂度   37（就是它）             →  13（_fill_zip，本次未动）
  文件行数 439 → 522（+83，全是新签名与 docstring）· 函数数 19 → 27

顺手消掉一个**隐患**，不是纯搬家：``zip_valid`` 原先必须手工在函数头初始化为
False（注释写明「漏了就 NameError 二次崩线程」——它正是上上轮那个 bug 的残留
护栏）。收进 dataclass 后该约束由构造函数承担，而 ``_ZipRun(...)`` 的默认值就是
假值，物理上写不出「忘记初始化」。

等价性证据（两道，互相独立）：
1. 不靠注入脚本，直接把文件还原成 HEAD 版跑同一套测试（git stash push 单文件 →
   跑 → pop）：tests/test_zip_workers.py + test_monitor_jobs.py 共 33 例**全过**。
   这批测试是上一轮用反向注入验证过「忠实编码旧行为」的，故本轮它们对新实现
   构成等价性验证。
2. AST 字面量多重集比对：字符串 56 种**一个不少**——没有任何用户可见文案或日志
   格式被动过。数值唯一差异是 `0.0: 0 → 1`，即 _ZipRun.t0 的字段默认值。

刻意保留的语义（是决定，不是疏漏）：
- _publish_delivery 里「先 settle 再抛 DownloadCanceled」的顺序原样——抛出去后
  _finish_canceled 会**再 settle 一次**（delivered 口径不同），依赖的是 ledger_settle
  幂等；原实现同样如此，未动。
- 取消与异常两条支路里「部分交付」与「全额退」的判定条件（`delivered > 0 and
  zip_tmp_path`）逐字保留。
- _finish_all_failed 不走 _apply_error：它要额外记 failed 计数，口径与 error 支路
  不同（原实现即如此）。
- record_duration 仍在 zip_valid 置位之后、全失败判定之前（保持原顺序）。

验证：ruff 全过 · pyright 0/0 · pytest 294 passed（与改动前同数）· 生产 data/ 未被
触碰（全部用例走 tmp_path 沙箱）。
 2026-09-27 09:08:52 +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 3de75f7479 refactor: 两个「数据泥团」收成 dataclass / 字典 
为什么：上一轮报告「11 个参数 > 6」的清单实测只有 7 个 ≥7 参数，其中真正
该改的是 2 个（另 5 个是 HTTP/下载原语的参数透传，合并反而降低清晰度，有意
保留）。

1) auth_system.create_user（11 参 → 6 参）
   前 5 个是账号属性（username/password/email/credits/role，同属一个概念），
   后 6 个才是泥团——它们是「注册风控上下文」（同 IP 频率闸 + 设备赠送闸）。
   收成 frozen dataclass RegistrationGuard，默认值等价于「不做任何风控」，故
   老调用点语义不变。

2) web/routers/download.py._single_task（11 参 → 2 参）
   11 个位置参数改成一个 params 字典 + device_id，字典原样透传给 worker。
   顺带删掉原本就**未被使用**的 data 参数（11 个里有 1 个是死的）。
   理由不是「参数多」而是这 11 个位置参数没有名字，调用点极易错序。

教训：create_user 签名重构时漏改 web/routers/admin_site.py:155，pytest 189 例
全绿（该端点无测试覆盖）但 pyright 报出 2 errors —— 两道门禁互补的实证，
说明类型检查不是冗余。
 2026-09-26 18:54:17 +08:00
snowy-yang 0569b50737 refactor: 清理 13 处生产死代码 
为什么：用 AST 级引用分析（而非文本 grep——同名符号会互相掩盖）确认这些
符号全项目零引用。文本 grep 查不出的原因是它们都有「活着的同名兄弟」：

services/downloads.py（共 6 个，93 行）
  _parse_cookie_str / _global_music_u / _vip_name / _detect_vip /
  _admin_client / _user_client
  —— 活的是 core.media.parse_cookie_str、web/routers/music.py、account.py 的版本
  随之失效的 import：USER_COOKIE_FILE / GLOBAL_MUSIC_U_CACHE / VIP_PROBE_LOCK /
  account_info / detect_vip_by_probe / QRLoginClient

services/api_service.py
  APIResponse 类（29 行）—— web/response.py 才是活的响应封装

services/_shared.py
  _rate_ok —— 逐字复制 web.ratelimit.rate_ok

core/utils.py
  safe_int / safe_console_print —— 活的是 web/request_utils.safe_int

core/repo.py
  all_settings / get_user_by_name —— auth_system.get_user_by_name 才是活的

core/db.py / web/auth_state.py / web/request_utils.py
  execute_many / _safe_register_credits + secrets_rand / dedup_ids

结果：生产代码死代码候选 13 → 0（余下 118 个全是 pytest 测试函数，属正常）。
 2026-09-26 18:54:11 +08:00
snowy-yang 445c16c329 refactor: web/routers/tasks.py 的 _touch_device 收敛到 services 版 
为什么：_touch_device 在 services/tasks.py 与 web/routers/tasks.py 各有一份
逐字相同的实现，且两份都活着。同一份「更新设备心跳时间」的逻辑有两处副本，
改一处忘另一处就会出现行为分叉。

改法：删掉 web 层本地副本（16 行），改为调用 services.tasks._touch_device
（两处调用点），并补 import asyncio 以包裹 to_thread。

说明：上一轮报告里提到的「6 组分叉实现」实测需逐组降级——success()/error()
分属不同层（一个是 tuple 返回、一个是 JSONResponse），iter_content 是两个垫片
的适配器，都**不该**合并；只有 _touch_device 是真·逐字重复，故只收敛这一组。
 2026-09-26 18:54:04 +08:00
snowy-yang 4356c5f817 fix: 修正心跳端点在限流豁免表与限流调用里自相矛盾 
为什么：/api/task/heartbeat 同时出现在两处——
  1. guard() 开头的 _EXEMPT_PATHS 豁免表里（命中就直接 return，不进桶）
  2. task_heartbeat 自己的 guard(bucket='hb', limit=60) 调用里
结果 guard 在进入桶之前就被豁免表放行，hb 桶的 60/分限额写了等于没写，
心跳端点实际处于无限制状态。

改法：把 /api/task/heartbeat 从 _EXEMPT_PATHS 移除，让它真正走到 hb 桶。
保留 /api/queue 与 /api/batch_progress 的豁免（它们被高频轮询且无自带桶）。

顺带修正上一轮的一处误判：原以为「手写滑动窗口在多 worker 下会放大限额」，
实测 Dockerfile / docker-compose.yml / entrypoint.sh 全是单进程
python3 web/main.py（uvicorn.run 无 --workers），进程内内存窗口是正确实现，
该顾虑不成立。
 2026-09-26 18:53:59 +08:00
snowy-yang d7d3cfce69 refactor: HTTP 垫片异常层次收敛到 core.http_errors 单一来源 
为什么：core/aiohttp_compat.py 与 core/sync_http.py 各自定义了一份
RequestException / HTTPError，是**两个不同的类**。调用方在同步段捕获
core.sync_http.HTTPError、异步段抛的却是 core.aiohttp_compat.HTTPError，
两者无继承关系——异常会穿透所有 except 分支，属于隐藏的跨层 bug。

改法：新建 core/http_errors.py 作为唯一定义处（RequestException 基类 +
HTTPError / Timeout / ConnectionError），两个垫片改为从它导入并再导出。
刻意保留 requests 的命名约定（Timeout / ConnectionError 与内置同名，
调用方需带模块前缀引用），已在 docstring 写明，避免后来者误改。

注意：sync_http 补了 __all__ 显式再导出——models._RetryFromScratch 继承它、
tests/test_aria2.py 直接导入它，符号必须保持可导入。
 2026-09-26 18:53:53 +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 7a70eef636 refactor: 删除 services.runtime 兼容门面，7 处调用点直连真实子模块 
为什么：上一次分包重构把 1900 行巨石按职责拆成 9 个子模块后，留了一个
runtime.py 作为「原样再导出」的兼容门面，好让调用点零改动。但迁移期结束后
没有一个调用点迁走——门面成了永久中间层：每次读代码都要先跳一层才知道
符号真正住在哪，pyright 也无法从门面追溯定义位置。

改法：保持「函数内延迟导入」的形式不变，只把导入目标换成真实子模块。
**刻意不提到模块顶部**——services/__init__.py 里有依赖自检
（缺 auth_system/podcast_api/music_api/music_downloader/qr_login 就 sys.exit(1)），
提到顶层会让「import web.*」这一步就触发该自检，改变启动语义，超出本次范围。

7 处调用点（AST 精确扫描确认全集）：
- web/routers/download.py ×4：download / download_batch_zip / podcast_download /
  podcast_batch_zip，分别直连 services.downloads / batch / podcast / tasks
  外加 _shared._build_download_base 与 api_service.api_service
- web/routers/tasks.py ×2：_semaphores 取 _shared.BATCH_ZIP_SEM + api_service，
  topen 取 _shared.ENDPOINT_NAMES
- web/tasks_registry.py ×1：start_task 直连 _taskcore._start_task_thread

子模块短名统一加 `services_` 前缀别名（services_tasks 等），避免与函数内
既有局部名相撞。

顺带清理：9 个子模块 docstring 里「（自 services/runtime.py 拆出……）」的
历史说明在门面删除后已成悬空引用，一并去掉；包的模块划分说明改为
「不再有兼容门面层」。

验证：
- 符号可达：11 个被引符号在真实子模块上全部 hasattr 通过；
  services.runtime 已 ModuleNotFoundError；api_service 仍是同一实例对象
- 三个调用方模块均可正常 import
- 门禁：ruff 0 · pyright 0 errors 0 warnings · pytest 175 passed
- 真实 uvicorn 冒烟 8/8（含 POST /auth/login 400），临时数据目录独立落库
  9 张表，生产 data/ 指纹三项一致
 2026-09-26 14:48:05 +08:00
snowy-yang 3ed2f36b18 fix: 启动时初始化站点库表结构，修复全新部署「有库无表」的缺陷 
为什么：全仓没有任何启动期调用 init_db()——web/app.py 的 lifespan 在 yield
之前不做事（只在关停时清连接池），create_app 也只注入音频密钥。后果是全新部署
（宿主机 data/ 是空目录，compose 用 ./data:/app/data 挂载会盖掉镜像内内容）
启动后，第一次查询只是让 sqlite3 建出一个 **0 表空库**，随后所有涉库端点报
`no such table: users`。

实测证据（SITE_DATA_DIR 指向空目录，起真实 uvicorn）：
  修复前：POST /auth/login -> 500；site.db 4096 字节 / 0 张表
  修复后：POST /auth/login -> 400（用户名或密码错误，即查询真的执行了）；
          site.db 61440 字节 / 9 张表（含 users、settings）

这个故障还极难定位：500 的响应体是「登录失败，请稍后重试」，
把 no such table 整个吞掉了，日志不翻到底看不出来。

改法：在 lifespan 的 yield 之前 `await asyncio.to_thread(auth_system.init_db)`。
init_db 全程 CREATE TABLE IF NOT EXISTS + 幂等迁移，对已有生产库重复执行无副作用
（本次 175 项测试与真实启动冒烟均未触碰 data/，指纹三项一致）；初始化失败则让
异常冲出、启动即失败，优于静默带病运行。
 2026-09-26 14:38:05 +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 d600b6a630 refactor: crypto 改用手写轮子的标准替代，去掉重复的函数内 import 
- hex_digest：`"".join([hex(d)[2:].zfill(2) for d in data])` → `data.hex()`。
  前者每字节做一次 hex()+zfill 再拼接，后者是 C 实现；两者输出相同。
- hash_hex_digest：绕道 digest() → hex_digest() 两步，直接 hexdigest()。
- _aes_encrypt / encrypt 里的函数内 import 删除：模块顶部已导入
  Cipher/algorithms/modes/padding，函数内又导一遍纯属冗余；
  base64、secrets 则提到模块顶部（原来每次调用都要走一次 import 查找）。
- PKCS7(128) 保留字面量并加注释：**不要**改写成 algorithms.AES.block_size
  ——它在类型存根里声明为 property 而非 int，pyright 会报 reportArgumentType
  （本次实测踩到，门禁拦下）。

等价性验证：encrypt_params 对固定 payload 的输出 sha1 保持
76e3738f8eab61fcfd1145164ba8e1f91d40ee4f 不变；hex_digest/hash_hex_digest
的输出逐字符相同；并做了 docstring 逐条比对确认无文本误伤。
 2026-09-26 14:16:05 +08:00
snowy-yang bd3a4ac70b fix: 统一 core/auth_system 的数据目录解析，消除脑裂隐患 
为什么：`core/db.py` 认 SITE_DATA_DIR、`auth_system/db.py` 写死 Path('data')，
而两处指向的是**同一个** data/site.db。web/main.py 的文档字符串还宣称
「数据目录可由 SITE_DATA_DIR 覆盖」——只有 core 侧做到了。

后果：只要运维真的设置 SITE_DATA_DIR，站点库（用户/账本/卡密）与
core 侧读的设置/公告就会落到两个不同文件，且**不会报错**——
表现为「设置改了不生效」「公告消失」这类极难排查的诡异现象。
全仓 grep 确认该变量当前只出现在 core/db.py 与 web/main.py 两处，
没有任何测试或部署在用，所以是纯隐性隐患。

顺带修一个实测到的坑：`os.environ.get('SITE_DATA_DIR', 'data')` 的默认值
只在变量**缺失**时生效，`SITE_DATA_DIR=`（空串，compose/K8s 里很常见）
会让 Path('') 退化成当前工作目录，数据库静默落到 CWD。改用 `or 'data'`。

验证：四种取值（未设置 / 空串 / 绝对路径 / 相对路径）下
core.DATA_DIR == auth_system.DATA_DIR 且 DB_PATH 相同，全部一致。
 2026-09-26 14:15:58 +08:00
snowy-yang 961ee87511 chore: 补齐 .gitignore 缺口，避免工具缓存被误提交 
为什么：.pytest_cache/ 与 .ruff_cache/ 此前既不在忽略列表、也未被提交——
跑一次 pytest 就会在 `git status` 里冒出来，一旦有人习惯性 `git add -A`
就会被带进版本库（.workbuddy/ 就是这样浮出来的）。同时补上 .pyright/。

另 _mkpkg.py 会在**项目根**写入打包标记 _pkg_ok.txt（内容为文件数/体积
或 public 标记），同样属于运行产物，一并忽略。
 2026-09-26 14:15:51 +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 183f5744d8 fix: 修复 7 处变量可能未绑定的真缺陷，类型检查升到 standard 
为什么：IDE 里成片的黄色波浪线并非风格噪声。ruff 与 pyright(basic) 都是
0 报错，但 basic 会整体漏报「变量可能未绑定」这类**可执行缺陷**；实测
standard 多报 7 处且全部为真——异常处理器引用了尚未赋值的局部变量，一旦走进
异常分支就会 NameError 二次崩溃，把原始异常彻底掩盖。

- core/db.py, core/http_client.py：3 处 @asynccontextmanager 的返回标注
  AsyncIterator[X] 更正为 AsyncGenerator[X, None]（前者不含 send 语义）
- core/state.py：三个模块级缓存补 TypedDict 建模。原先无标注的 dict 字面量被
  推断为「所有值类型的并集」（float | None），每个读写点都退化成联合类型；
  拆成 _VipCache（data 可为 None 表示未探测）与 _VipEntry（data 必定存在）后，
  类型检查立刻抓出 account.py 对未探测缓存的直接解包隐患
- services/batch.py：zip_valid 提到函数头。ZIP 构建前的业务错误（参数缺失/
  无歌曲）会 early raise，而异常处理器引用了该名字 → NameError 二次崩溃
- services/podcast.py：radio_name、pct 同理补初始化
- services/downloads.py：声明返回 str 却可能给出 None，改 `or ''` 满足契约
- web/routers/download.py：id_list 提前绑定
- web/auth_state.py：解包出的 c 未被使用
- pyproject.toml：typeCheckingMode 由 basic 升到 standard 作为门禁，并移除
  已被 standard 覆盖的 reportGeneralTypeIssues

门禁：ruff All checks passed · pyright(standard) 0 errors 0 warnings
 2026-09-26 13:54:23 +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 6288a98ecc 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/ 指纹未变；忽略注释的逐字等价性校验通过。
 2026-09-26 12:37:48 +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 cd0f1f78a3 refactor: 迁移收尾（管理员2FA）+ 抽取公共工具层，消除 router 间重复 
补齐最后缺口：
- POST /api/v1/auth/admin_login/email、/auth/admin_login/verify（管理员 2FA Step2/3），
  复用 auth_routes 的票据表与尝试上限（跨栈共享），签发会话 Cookie

重构（消除约 200 行重复，11 个 router 受益）：
- web/request_utils.py：request_data / safe_int / extract_id / cookies / dedup_ids
  原在各 router 各复制一份，现集中
- web/serializers.py：format_credits / user_public / record_req_log
- 各 router 改为导入别名，行为逐字不变

覆盖率：Flask 90 条业务路由全部有 FastAPI 等价端点（含 5 个向后兼容别名）。
验证：pytest 69/69；ruff All checks passed；pyright 0 errors；奇偶 36/36；冒烟 10/10。
 2026-09-26 10:20:46 +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 fb40b2132c feat(routes): 迁移管理后台全部 /admin/site/* 端点（28 个） 
- web/routers/admin_site.py：用户管理(users/delete/duration/create/
  reset_password/toggle/ban/cookie)、SMTP(get/save/test)、日志(logs/clear)、
  卡密(generate/list/disable/delete)、公告(get/save)、播放密钥(get/rotate)、
  数据库备份(create/list/download/upload/restore/delete/auto)
- 全量经 asyncio.to_thread 调用 auth_system 同步函数（SQLite/SMTP/文件），不阻塞事件循环
- 操作者名取当前管理员用户名；管理员闸 403 带 error_code='forbidden'（与 admin_required 同）

验证：11 项代表性端点与 Flask 逐字段一致（含参数校验与错误文案）；
非管理员 403 一致；pytest 62/62；ruff All checks passed；pyright 0 errors。
 2026-09-26 10:02:24 +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 22f4d77abd feat(routes): 迁移管理员扫码/Cookie/操作记录端点 
- web/routers/admin.py：admin/qr/create、admin/qr/check、admin/cookie/status、
  admin/cookie/delete、admin/logs
- 管理员闸用本地实现，文案与「无 error_code」包体与 Flask _verify_admin_password
  逐字对齐（与 auth_system.admin_required 的 forbidden 字段不同）
- QRLoginManager await；文件类操作(save_cookie/logout/_get_cookie_info) 走 to_thread
- Cookie 变更后同步清 VIP 与全局 MUSIC_U 缓存

契约奇偶校验：36 项全 OK（新增 admin:logs、admin:cookie_status、非管理员 403）；
ruff All checks passed；pyright 0 errors；冒烟 10/10。
 2026-09-26 09:59:04 +08:00
snowy-yang b7616e9831 feat(routes): 迁移个人中心/公开播放/前端错误端点 + 修 QR 异步回归 
迁移（/api/v1/*，与 Flask 逐字段对齐）：
- user/qr/create、user/qr/check、user/status、user/logout、user/playlists、
  user/playlist、user/collect、user/comment
- api/playlist/play（密钥校验 + 逐曲直链解析：ThreadPoolExecutor(4) → asyncio.gather(4)）
- fe_error（前端错误上报，10/分/IP + 字段清洗）

修复我此前引入的异步回归（重要）：
- music_api.QRLoginManager 异步化后，main.py 4 处 Flask 同步路由仍当同步调用，
  返回协程 → Flask 侧扫码登录必坏。已改经 run_sync 桥接，实测两栈均返回 SVG。
- web/routers/user.py 同样改为 await。

契约奇偶校验：33 项（新增 user:status/logout/playlists401/playlist401/play:badkey）；
ruff All checks passed；pyright 0 errors；冒烟 10/10。
 2026-09-26 09:57:42 +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 18c77296c2 feat(routes): 迁移首页/静态资源 + /auth/me 认证状态 
- web/routers/index.py：GET / 首页，用 Jinja2 以 Flask 同口径渲染
  （keep_trailing_newline=False）——输出与 Flask render_template 逐字节一致
- web/app.py：挂载 /static 静态资源（site_auth.js 等，与 Flask 同目录）
- web/routers/auth_status.py：/api/v1/auth/me 认证状态
  · user/duration_text/announcement/smtp_configured/register_credits 逐字段对齐
- core/repo.py：补 get_announcement / get_smtp_config / smtp_configured 异步读

契约奇偶校验：28 项全 OK（新增 index 逐字节、auth:me）；
验证：pytest 51/51；ruff All checks passed；pyright 0 errors；
uvicorn 实跑 / 与 /static 与 /api/v1/* 均 200。
 2026-09-26 09:51:32 +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 f588d313f0 feat(routes): 迁移任务状态端点（topen/queue/batch_progress/task/*） 
- web/routers/tasks.py：topen、queue、batch_progress、task/cancel、
  task/heartbeat、task/list 迁至 /api/v1/*
- 读写 core.state 共享任务表/统计（与 Flask 同一批对象）——两栈迁移期看到同一份
  任务状态，这是单进程双框架成立的关键
- task/cancel 保持 POST-only（与 Flask 同口径，杜绝顶层导航 GET 触发取消）

契约奇偶校验：24 项全 OK（新增 queue/topen/task:list/heartbeat/progress404）；
验证：pytest 46/46；ruff All checks passed；pyright 0 errors；冒烟 10/10。
 2026-09-26 01:18:51 +08:00
snowy-yang f45a9ccd3a feat(routes): 迁移播客查询端点（parse/programs/search/hot） 
- web/routers/podcast.py：四个播客端点迁至 /api/v1/*，与 Flask 逐字段对齐
- podcast_api 仍为同步模块，用 asyncio.to_thread 包装：阻塞上游不占事件循环，
  行为与 Flask 一致
- 单集解析附音频直链（音质自动降级）+ 解析操作记共享 REQ_LOG

契约奇偶校验：19 项全 OK（新增 podcast hot/search/programs）；
play_count 加入易变字段（上游实时收听计数每次请求都变，非契约漂移）。

验证：pytest 46/46；ruff All checks passed；pyright 0 errors；冒烟 10/10。
 2026-09-26 01:16:53 +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 52ed8b54fb feat(server): 生产服务器切换 uvicorn（FastAPI + Flask 兜底） 
- web/main.py：uvicorn 入口，默认开启 Flask 兜底（未迁移路由回落遗留应用）；
  HOST/PORT/LOG_LEVEL 环境变量可配；proxy_headers 按 XFF 取真实 IP（仅信回环）；
  server_header=False 抹服务器指纹
- entrypoint.sh：默认 exec web/main.py；WEB_STACK=flask 可应急回退旧入口
- Dockerfile：安装 requirements-fastapi.txt（目标栈）+ requirements.txt（Flask 兜底）

验证（单进程双框架实跑）：/health、/（Flask 兜底）与 /api/v1/site/stats（FastAPI）
均 200；Server 头为 NeteaseUrl；ruff/pyright 干净。
 2026-09-26 00:35:02 +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 ce7ea66d6a refactor(async): music_api 异步化 + 全项目 lint 收敛 
music_api.py：
- 22 个方法改 async（HTTPClient.post_request*/NeteaseAPI.*/QRLoginManager.*），
  33 处 requests.* → await core.aiohttp_compat.*
- 16 个模块级同步包装改走 run_sync 桥（main.py 等 99 个同步调用点零改动）
- async 内 time.sleep → asyncio.sleep（修 7 处阻塞事件循环）

musica_downloader/qr_login：
- 单曲三请求 ThreadPoolExecutor → asyncio.gather（语义等价，失败处理保留）
- interactive_login 改 async，CLI 入口用 asyncio.run

真实缺陷修复（lint 发现）：
- podcast_api._to_int 未定义（2 处调用会 NameError）→ 补安全转换 helper
- main.py VALID_QUALITY_LEVELS 重复定义（覆盖 core.config 导入值）→ 移除
- 移除死代码变量（salt×2/device_id×3/file_path/zipped_files）

lint 收敛：524→0（ruff All checks passed）；pyright 0 errors。
pyproject 记录「有意保留」项（B904/RUF012/S305 上游协议等）及理由。

验证：冒烟 10/10；pytest 16/16；真实上游 get_toplist 异步直调与桥接均得 63 条。
 2026-09-26 00:32:45 +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
snowy-yang 41356e89c4 feat(web): FastAPI 脚手架（strangler 迁移起点） 
新增 web/ 包，与 Flask 应用并存、共享 core/：
- web/app.py     create_app 工厂；已迁移路由挂 /api/v1，可挂遗留 Flask 兜底
- web/main.py    uvicorn 入口（sys.path 补项目根）
- web/response.py 响应工具，与 Flask APIResponse 的 JSON 契约逐字段对齐
- web/routers/system.py 迁移样板：/api/v1/health、/api/v1/api/info
- requirements-fastapi.txt 迁移目标依赖（不影响当前生产 Flask 部署）

验证：
- 奇偶校验（.zcode/refactor/parity.py）Flask /health vs FastAPI /api/v1/health、
  /api/info vs /api/v1/api/info —— 状态码/顶层键/响应体全一致
- uvicorn 真实启动 200；Flask fallback 挂载下 /api/v1/* 走 FastAPI、/* 走 Flask 同为 200

当前仅样板端点；生产服务器切换与状态统一见后续迁移阶段。
 2026-09-26 00:17:56 +08:00
snowy-yang c2a8da3e43 refactor(core): 抽出框架无关核心层 core/，为 FastAPI 迁移铺路 
第一步模块拆分（纯搬运，零行为变化）：
- 新增 core/ 包：config(常量/配置) + state(运行时状态) + utils(纯函数) + security(音频签名)
- main.py 改为从 core 导入并以原下划线名再导出，250+ 既有调用点零改动

关键设计：
- 状态全部原地修改，import 即共享同一对象（21 项身份断言 + 10 项冒烟全绿）
- 音频签名密钥由启动时 _init_audio_secret(app.secret_key) 注入，
  解除 core.security 对 Flask app 的依赖，新老应用可互认 token

验证：py_compile 通过；冒烟 10/10 PASS；对象身份 22/22 PASS；
waitress 真实启动 /health 200 version=2.4.0。main.py 减 229 行。
 2026-09-26 00:16:04 +08:00
snowy-yang d209af847a chore: 基线快照 —— 纳入 git 版本控制（站点 v2.4.0 / Flask 单体） 
在框架迁移与模块拆分前保存当前可运行状态：
- 后端：main.py/auth_routes.py/auth_system.py/music_api.py/music_downloader.py/podcast_api.py/qr_login.py
- 前端：templates/index.html + static/site_auth.js
- 部署：Dockerfile/docker-compose.yml/entrypoint.sh/requirements.txt
敏感数据(data/、cookie.txt)与内部文档(交接文档/新会话引导)按 .gitignore 排除。
 2026-09-26 00:13:05 +08:00