让 Kindle 常显一块 Token 看板：先有设计，越狱只是手段

"""数据源抽象：一个源 = 一次外部拉取，产出若干 metric 的结构化采样。

# [新: 2026-07-26] fetch 只此一条通道。曾经是 fetch()/notes()/resets()/data_at()
# 四个方法平行输出，且 notes 用的键约定(*_reset)和 fetch/resets(metric 名)还不
# 一样——于是需要 note_key/note_map/note_from 一整套胶水，而三份字典在调度层被
# update() 进全局状态、键只增不删，"过期的重置时刻该消失"这类语义根本落不了地
# (时间线会永远停在 100%)。收敛成"每个 metric 一条完整记录"后，调度层按源整体
# 替换，源不再产出的键自然消失；重置文案是展示逻辑，由快照层从 resets_at 现算。
"""

from abc import ABC, abstractmethod
from dataclasses import dataclass
from datetime import datetime
from typing import ClassVar


@dataclass(frozen=True)
class Sample:
    """一个 metric 的一次采样：数值 + (可选的)下次重置时刻。

    resets_at 跟着数值走，不单独开通道：额度百分比和它的重置时刻本来就是
    同一条记录的两个字段。已过重置时刻的采样，数值由源归零、resets_at 保留
    原值(过去时刻)——快照层据此写"已重置 · 待上报"并隐藏时间线。
    """

    value: float
    resets_at: datetime | None = None


@dataclass(frozen=True)
class Reading:
    """一轮 fetch 的完整结果。

    data_at: 这批数据本身的时刻；None = 就是"刚拉到的"，由调用方用当前时刻。
    上报型源必须填：它手里的数据可能是几小时前报上来的(尤其重启后回放的那份)，
    状态条要显示那个时刻，否则屏上写着刚更新过，其实是旧数据。
    """

    samples: dict[str, Sample]
    data_at: datetime | None = None

    def values(self) -> dict[str, float]:
        """{metric: 数值}，给 SampleStore 落盘与源状态指纹用。"""
        return {metric: sample.value for metric, sample in self.samples.items()}


class DataSource(ABC):
    """所有数据源的基类。

    调用方约束：
    - fetch() 由调度器每个采样周期调用一次，多个源之间用 gather 并发；
      单源抛异常只把该源标为 error/stale，绝不阻塞其他源。
    - fetch() 内部必须设超时(建议 <= 30s，小于采样周期)。
    - samples 的 metric 键全局唯一(跨源不得重名)，是 SampleStore 的主键之一。
    - 源只要活着，每周期都要把它持有的全部 metric 重新给一遍——
      store.latest(max_age) 靠这个约定识别"某维度不再被采集"。
    """

    key: ClassVar[str]  # 源标识，进 SourceStatus.key
    label: ClassVar[str]  # 展示名，进 SourceStatus.label

    @abstractmethod
    async def fetch(self) -> Reading:
        """拉取一次。数值是"累计值"而非增量——差分统一由 SampleStore
        用历史算，源本身保持无状态。
        """
        ...

"""额度维度声明表 —— 限额类数据的唯一配置源头。

# [新: 2026-07-26] 这张表以前散在两处：sources/push.py 的 metric_map/note_map
# (上报 key → 内部 metric 名) 和 snapshot.py 的 _RING_SPECS (顺序/标题/已用还是余额)。
# 加、删、换一个维度要同时改两个文件，漏一处的后果很隐蔽：上报侧删了、
# 展示侧没删 → 那个环会挂着 store 里几天前的历史值，永不更新也不报错。
# 合成一张表后：换顺序 = 挪一行，去掉一个维度 = 删一行，加维度 = 加一行。

⚠️ 列表顺序 = 环的 外圈 → 内圈。排序规则见 README 决策日志：
重置周期短(变化快)的放外圈——外圈周长大，同样的变化弧长最长、最醒目。

⚠️ 最多三环。半径是 `148 - i*44`(viewBox 坐标)，第四环只剩 16、几乎是个点；
灰度也只有三档 G_RING，第四环会 `i % 3` 撞回最外圈的黑色。
"""

from dataclasses import dataclass
from datetime import timedelta
from typing import Literal


@dataclass(frozen=True)
class Dimension:
    """一个额度维度：从上报 key 一路到环上那一圈。"""

    report_key: str  # 上报方在 limits[].key 里写的名字，见 docs/report-api.md
    metric: str  # 内部 metric 名，SampleStore 的主键之一，全局唯一
    title: str  # 环图例上的展示名
    show: Literal["used", "remaining"] = "used"  # 图例大数字显示已用还是余额
    # 差分弧(斜纹那截)的口径。窗口越长，差分也该跟着放大：
    # "rolling" = 最近 settings.delta_window_min 分钟，适合 5 小时这种短窗口；
    # "today"   = 今天 00:00 起的增量，适合周限额——拿 15 分钟去切一个 7 天的
    #             额度看不出任何东西(这跟两条 tier-bar 的取舍是同一个道理)。
    delta_mode: Literal["rolling", "today"] = "rolling"
    # 自己的 resets_at 缺失时，借哪个维度的(填对方的 report_key)。
    # Fable 和周限额同时重置：正常情况 CC 的输出里两行各带一份重置时刻，
    # 各用各的；只有上报缺了 Fable 那行的 resets 段时才借用，不必要求
    # 上报方一定报两遍。重置文案与时间线都由快照层从 resets_at 现算。
    resets_from: str | None = None
    # 额度窗口时长，用来在环上画"时间走到哪儿了"那条线：窗口起点 = resets_at - window。
    # [新: 2026-07-26] 写死而不是让上报方报：这是产品常量(5 小时 / 7 天)，
    # 而且 CC 的用量输出里根本没有窗口长度这个信息，只有 session/week 这种名字。
    window: timedelta | None = None


_5H = timedelta(hours=5)
_WEEK = timedelta(days=7)

# 顺序即外圈→内圈
CLAUDE_DIMENSIONS: list[Dimension] = [
    Dimension("session_5h", "claude_session_pct", "时段限额 (5h)", window=_5H),
    Dimension("week_fable", "claude_fable_pct", "Fable 模型",
              resets_from="week", window=_WEEK, delta_mode="today"),
    Dimension("week", "claude_week_pct", "周限额", window=_WEEK, delta_mode="today"),
]

CODEX_DIMENSIONS: list[Dimension] = [
    Dimension("session_5h", "codex_session_pct", "时段限额 (5h)", window=_5H),
    # Codex 那边关心的是"还剩多少"，环本身仍画已用，只有图例大数字显示余额
    Dimension("week", "codex_week_pct", "周余额",
              show="remaining", window=_WEEK, delta_mode="today"),
]

# 看板内部源标识 → 该源的维度表
SOURCE_DIMENSIONS: dict[str, list[Dimension]] = {
    "claude_limits": CLAUDE_DIMENSIONS,
    "codex_limits": CODEX_DIMENSIONS,
}


def metric_map(dims: list[Dimension]) -> dict[str, str]:
    """上报 key → 内部 metric 名，给 PushSource 用。"""
    return {d.report_key: d.metric for d in dims}


def reset_metric_for(dim: Dimension, dims: list[Dimension]) -> str:
    """这个维度的重置时刻从哪个 metric 上读(可能借用别的维度的)。

    只在自己缺 resets_at 时才需要借用，借用的判断在快照层做——
    这里只负责"借谁"：resets_from 指向的维度被删了就退回自己。
    """
    if dim.resets_from is None:
        return dim.metric
    source = next((d for d in dims if d.report_key == dim.resets_from), None)
    return source.metric if source else dim.metric

"""Snapshot 契约模型 —— 前后端唯一契约源头。

骨架约定：这一层完整实现、不留骨架。由它生成 openapi.json，
Web 端(test/components.js)与 Kindle 渲染端(app/render/kindle.py)都对齐到这里。

⚠️ 字段名刻意与 test/mock.js 完全一致(value/delta/goals/delta_label/
rings/pct/note/show/layout...)——这不是随意起的名：前端组件直接按这些
字段取值，改名必须两端同步。
"""

from typing import Literal

from pydantic import BaseModel


class SourceStatus(BaseModel):
    """单个数据源的健康状态，渲染为看板底部的状态条。"""

    key: str
    label: str
    status: Literal["ok", "stale", "error"]
    updated_at: str  # "HH:MM"，展示用；stale 时前端会标"过期"


class TierBarMetric(BaseModel):
    """多档位进度条数据。value/delta/goals 单位是 token 个数(不是亿)。"""

    value: float
    delta: float  # 最近 delta_window 窗口内的增量，渲染为条末端的差分段
    goals: list[float]  # 递增档位；当前档 = 已达成个数，上限 = 下一个未达成档
    delta_label: str  # 如 "最近15分钟 +0.06亿"，由后端统一格式化


class Ring(BaseModel):
    """叠环中的一环。pct/delta 都是 0~100 的百分数。"""

    name: str
    pct: float  # 已用比例；环的填充始终画"已用"
    delta: float  # 差分弧(斜纹那截)的百分点，口径见 Dimension.delta_mode
    # 差分口径的说明文字，如 "最近15分钟 +3%" / "今日 +2%"。
    # 由后端统一格式化(同 TierBarMetric.delta_label)：口径按维度不同，
    # 让两个渲染端各自拼这句话就一定会拼错。
    delta_label: str = ""
    note: str  # 重置说明，如 "21:00 重置"
    # "remaining"：图例大数字显示剩余(如 Codex 周余额)；环本身仍表示已用
    show: Literal["used", "remaining"] = "used"
    # 这个额度窗口"时间走到哪儿了"(0~100)，渲染成环上一条细线：
    # 线在填充前面 = 用得比时间慢(有富余)，被填充盖过 = 超前消耗。
    # 缺 resets_at 或窗口时长时为 None(不画线)。
    # ⚠️ 它每分钟都在变，**不进推送去重的数据指纹**(见 snapshot.data_digest)，
    # 否则墨水屏会为了一条走动的线每分钟闪一次。
    time_pct: float | None = None


class RingsMetric(BaseModel):
    """叠环数据。约定：rings 按 外圈→内圈 排列，重置周期短(变化快)的放外圈
    ——外圈周长大，同样的变化弧长最长、最醒目(秒针在最外)。"""

    rings: list[Ring]


class TierBarItem(BaseModel):
    """tier-bars 合卡里的一条：引用 metrics 里的 key + 显示标题。"""

    metric: str
    title: str


class LayoutItem(BaseModel):
    """布局即配置：渲染端按 type 查组件注册表，语义与 test/components.js 一致。"""

    type: Literal["tier-bars", "rings", "sources"]
    metric: str | None = None  # rings 用：指向 metrics 的 key
    title: str | None = None
    items: list[TierBarItem] | None = None  # tier-bars 用


Metric = TierBarMetric | RingsMetric


class Snapshot(BaseModel):
    """GET /api/snapshot 的返回。两种渲染端只消费这一份，不各自拉数据源。"""

    generated_at: str  # "YYYY-MM-DD HH:MM"
    sources: list[SourceStatus]
    metrics: dict[str, Metric]
    layout: list[LayoutItem]


# ---------- 上报接口契约 [新: 2026-07-26] ----------
class LimitReport(BaseModel):
    """单个额度维度的一次上报。

    ⚠️ limits 刻意做成"列表 + key"而不是固定字段：Codex 报 2 个维度、
    Claude Code 报 3 个，以后加维度不用动接口，上报端也不需要知道
    看板内部的 metric 命名(映射表在 sources/push.py)。
    """

    key: str  # session_5h / week / week_fable ...
    available: bool = True  # False = 这个维度当前没数据(如时段还没开始用)
    used_percent: float | None = None  # 已用百分比 0~100；available=False 时为 None
    resets_at: str | None = None  # ISO 时刻，展示文案由后端格式化


class ReportEnvelope(BaseModel):
    """POST /api/report 的请求体。"""

    source: str  # claude_code / codex，决定映射到哪套 metric
    host: str  # 上报机标识，多台机器时用于分辨谁掉线了
    # 上报机自己的时钟，仅随 payload 原样留档、当前不参与任何逻辑。
    # 数据时刻一律用 Pi 收到的时刻(received_at)——否则某台机器时钟偏了
    # 就会永远压住其他机器
    reported_at: str | None = None
    limits: list[LimitReport]
    meta: dict = {}  # plan_type/credits 之类，原样留档，暂不渲染