"""代理质量分：延迟越低越高，被取用次数越多越低。

设计要点
--------
1. **延迟项**（0～100）：用平滑倒数把毫秒映射到质量，避免线性过于极端。
   ``latency_quality = 100 / (1 + latency_ms / latency_ref_ms)``
   在 ``latency_ref_ms`` 处约为 50 分；越快越接近 100。

2. **使用惩罚**：每次通过 API 随机取出代理视为一次「使用」，``use_count`` 递增；
   惩罚 ``min(max_use_penalty, use_count * use_penalty_per_pick)`` 从延迟项上扣除。

3. **未知延迟**：尚无 ``response_time_ms`` 时用 ``default_latency_ms`` 代替，避免给满分。

验证失败仍走 ``update_score`` 扣分；验证成功则用本函数**覆盖**分数（与当前延迟、使用次数一致）。
"""
from __future__ import annotations

from typing import Optional

from app.core.config import Settings


def compute_proxy_quality_score(
    latency_ms: Optional[float],
    use_count: int,
    settings: Settings,
) -> int:
    """根据延迟与累计使用次数计算 0～100 的整数分。"""
    ref = float(settings.score_latency_ref_ms)
    penalty_per = float(settings.score_use_penalty_per_pick)
    cap = float(settings.score_max_use_penalty)
    default_lat = float(settings.score_default_latency_ms)
    lo = int(settings.score_min)
    hi = int(settings.score_max)

    if ref <= 0:
        ref = 500.0
    if penalty_per < 0:
        penalty_per = 0.0
    if cap < 0:
        cap = 0.0
    if default_lat <= 0:
        default_lat = 1500.0

    ms = latency_ms
    if ms is None or ms <= 0:
        ms = default_lat

    latency_quality = 100.0 / (1.0 + float(ms) / ref)
    uses = max(0, int(use_count))
    usage_penalty = min(cap, uses * penalty_per)
    raw = latency_quality - usage_penalty
    score = int(round(raw))
    return max(lo, min(hi, score))