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
1 parent 838d635bc5
commit 6288a98ecc
@@ -0,0 +1,116 @@
+# -*- coding: utf-8 -*-
+"""下载次数增减与格式化。
+
+（自 auth_system.py 拆出，行为与原实现一致。）
+"""
+
+import time
+
+from .db import (
+    _DB_LOCK,
+    _x,
+    get_conn,
+)
+from .users import (
+    get_user_by_id,
+    get_user_by_name,
+)
+
+# ============ 使用次数（按次计费：一首歌 = 1 次） ============
+
+
+def refund_credits(uid: int, count: int) -> int:
+    """退回下载次数（批量打包失败部分自动退费）。返回剩余次数（-1 表示不限）"""
+    user = get_user_by_id(uid)
+    if user and (user['duration_seconds'] or 0) == -1:
+        return -1  # 不限次数用户无需退费
+    count = max(0, int(count))
+    if count <= 0:
+        return (user['duration_seconds'] or 0) if user else 0
+    _x('UPDATE users SET duration_seconds = COALESCE(duration_seconds, 0) + ? WHERE id = ?',
+       (count, uid))
+    user = get_user_by_id(uid)
+    return (user['duration_seconds'] or 0) if user else 0
+
+
+def charge_credits(uid: int, count: int = 1) -> int:
+    """按次扣减使用次数（管理员与不限次数(-1)用户不扣减，返回 -1）。返回剩余次数
+
+    扣减在 _DB_LOCK 内"读取-判断-写入"一次完成，防止并发双击导致超扣/双花"""
+    user = get_user_by_id(uid)
+    if not user:
+        return 0
+    if user['role'] == 'admin' or (user['duration_seconds'] or 0) == -1:
+        _x('UPDATE users SET last_active = ? WHERE id = ?', (int(time.time()), uid))
+        return -1
+    count = max(1, int(count))
+    with _DB_LOCK:
+        conn = get_conn()
+        try:
+            row = conn.execute('SELECT duration_seconds FROM users WHERE id = ?', (uid,)).fetchone()
+            cur = int(row['duration_seconds'] or 0) if row else 0
+            if cur == -1:
+                conn.execute('UPDATE users SET last_active = ? WHERE id = ?', (int(time.time()), uid))
+                conn.commit()
+                return -1
+            newval = max(0, cur - count)
+            conn.execute('UPDATE users SET duration_seconds = ?, last_active = ? WHERE id = ?',
+                         (newval, int(time.time()), uid))
+            conn.commit()
+            return newval
+        finally:
+            conn.close()
+
+
+def reserve_credits(uid: int, count: int = 1):
+    """原子预扣下载次数（下载类接口在路由执行前调用，防止并发双击双花）。
+
+    足额：扣减并返回剩余次数；不限次数(-1)/管理员：不扣减返回 -1；
+    不足：返回 None（调用方应拒绝请求）"""
+    count = max(1, int(count))
+    with _DB_LOCK:
+        conn = get_conn()
+        try:
+            row = conn.execute('SELECT role, duration_seconds FROM users WHERE id = ?', (uid,)).fetchone()
+            if not row:
+                return None
+            if row['role'] == 'admin':
+                conn.execute('UPDATE users SET last_active = ? WHERE id = ?', (int(time.time()), uid))
+                conn.commit()
+                return -1
+            cur = int(row['duration_seconds'] or 0)
+            if cur == -1:
+                conn.execute('UPDATE users SET last_active = ? WHERE id = ?', (int(time.time()), uid))
+                conn.commit()
+                return -1
+            if cur < count:
+                return None
+            conn.execute('UPDATE users SET duration_seconds = ?, last_active = ? WHERE id = ?',
+                         (cur - count, int(time.time()), uid))
+            conn.commit()
+            return cur - count
+        finally:
+            conn.close()
+
+
+def add_credits(username: str, count: int) -> int:
+    """增加次数（卡密充值/试用领取），返回新剩余次数；不限次数(-1)用户保持不限
+
+    累加用 SQL 原生自增（原子），避免并发充值互相覆盖"""
+    user = get_user_by_name(username)
+    if not user:
+        return 0
+    if user['role'] == 'admin' or (user['duration_seconds'] or 0) == -1:
+        return -1
+    _x('UPDATE users SET duration_seconds = COALESCE(duration_seconds, 0) + ? WHERE id = ?',
+       (max(0, int(count)), user['id']))
+    user = get_user_by_name(username)
+    return (user['duration_seconds'] or 0) if user else 0
+
+
+def format_credits(count: int) -> str:
+    if count < 0:
+        return '不限次数'
+    if count <= 0:
+        return '已用完'
+    return f'{count} 次'