"""鉴权与限流（T-P1 落地；本文件先立签名）。"""
from __future__ import annotations

from typing import Any, Dict, Optional


def issue_key(ledger, student_id: int, rpm_cap: Optional[int] = None,
              day_cap_req: Optional[int] = None) -> Dict[str, Any]:
    """签发学生代理 key：明文只返回一次（T-P1 实现）。"""
    raise NotImplementedError("T-P1")


def authenticate(authorization: str, ledger, limits, now: float) -> Dict[str, Any]:
    """校验 Bearer key -> 学生上下文（T-P1 实现；带热路径缓存）。"""
    raise NotImplementedError("T-P1")


class RateLimiter:
    """令牌桶 rpm + per-key 并发信号量（T-P1 实现）。"""

    def allow(self, key_id: int, rpm_cap: int) -> bool:
        raise NotImplementedError("T-P1")