dsh-ds-balance 2.1.2 → 2.2.0

package/lib/services/balance-service.js

@@ -1,44 +1,38 @@
 /**
- * 余额缓存与状态机。
+ * 余额服务门面：**决定这一轮走哪条取数路**，然后把活交给那条路的账本。
  *
- * 职责：把「拿密钥 → 调上游 → 归一化 → 落快照」包成一次可合并的请求，并维护缓存状态。
- * **对外永不抛错**：一切失败都变成 `view.state` 与 `view.error`。
+ * 门面自己不持状态、不抓数据 —— 两份状态在 {@link SourceLedger} 里，一个来源一份。
+ * 选源规则是四层回落（会话路由 → 全局默认路由 → Key 优先 → 都没有），判据是纯函数
+ * [source-selector.ts](source-selector.ts)；两条路的读取策略在
+ * [source-readers.ts](source-readers.ts)。
  * @module dsh-ds-balance/services/balance-service
  */
-import { classify, describeError, parseRetryAfter, } from '../domain/errors.js';
-import { normalize } from '../domain/normalize.js';
-import { pickBalance } from '../domain/select.js';
-import { severityOf, thresholdsFor } from '../domain/severity.js';
-import { noopMetrics } from '../ports/metrics.js';
-import { endpointOf } from '../config.js';
-import { accountTag8, computeAccountTag } from './account-tag.js';
-/** 余额缓存与状态机。 */
+import { FALLBACK_ORDER, pickSource, routeOf } from './source-selector.js';
+/** 余额服务门面。 */
 export class BalanceService {
     options;
-    metrics;
-    snapshot = null;
-    state = 'empty';
-    error = null;
-    failures = 0;
-    retryAfterMs = null;
-    inflight = null;
-    /** 落盘失败只报一次，避免每轮刷新都刷屏。 */
-    persistWarned = false;
+    /** 当前活跃来源；由最近一次解析决定，调度与健康检查读它。 */
+    active = 'deepseek-http';
+    /**
+     * 来源判据是否已经定下来过。
+     *
+     * 宿主刚起来时两个可选服务（账号、默认模型）可能还没到，那一次解析只能按兜底走；
+     * 服务到齐后由装配处调 {@link invalidateSource} + `scheduler.reset()` 重新定一次。
+     * 一旦有请求解析过就以请求为准 —— 调度不拿全局默认去顶会话级的来源。
+     */
+    resolved = false;
+    /** 每条路只恢复一次（存储扫描不便宜，来回切来源不该重复扫）。 */
+    restores = new Map();
     constructor(options) {
         this.options = options;
-        this.metrics = options.metrics ?? noopMetrics;
     }
-    /** 当前状态切片，供调度与健康检查使用。 */
+    /** 当前活跃来源。诊断与测试用。 */
+    activeSource() {
+        return this.active;
+    }
+    /** 当前活跃账本的状态切片，供调度与健康检查使用。 */
     status() {
-        return {
-            state: this.state,
-            errorCode: this.error?.code ?? null,
-            consecutiveFailures: this.failures,
-            hasSnapshot: this.snapshot !== null,
-            serverRefreshSeconds: this.options.config.current().serverRefreshSeconds,
-            retryAfterMs: this.retryAfterMs,
-            lastSuccessAt: this.snapshot?.fetchedAt ?? null,
-        };
+        return this.ledger(this.active).status();
     }
     /**
      * 当前账本标识的前 8 位；还没有快照时是 `null`。
@@ -46,182 +40,139 @@ export class BalanceService {
      * **只回前 8 位**：完整 tag 是账本作用域标识，没有对外的理由。
      */
     accountTag8() {
-        const tag = this.snapshot?.accountTag;
-        return tag === undefined ? null : accountTag8(tag);
+        return this.ledger(this.active).accountTag8();
     }
-    /**
-     * 从存储恢复最近快照（挂载时调一次）。
-     *
-     * **按 `accountTag` 过滤**：凭据轮换后 tag 变了，旧快照视为不存在，不混用。
-     * 没有密钥可算 tag 时静默跳过。
-     */
+    /** 从存储恢复最近快照（挂载时调一次，恢复的是**当前活跃来源**那条账本）。 */
     async restore() {
-        try {
-            const apiKey = await this.options.keys.resolve();
-            const accountTag = computeAccountTag(this.options.salt, apiKey);
-            const stored = await this.options.store.loadLatestSnapshot(accountTag);
-            if (stored === null)
-                return;
-            this.snapshot = stored;
-            this.state = this.withinWindow() ? 'ok' : 'stale';
-            this.publishGauge();
-        }
-        catch (error) {
-            this.options.logger?.debug('ds-balance: no snapshot restored', {
-                error: describeError(error),
-            });
-        }
+        await this.restoreLedger(await this.resolve(undefined));
     }
     /**
      * 取当前视图。
      *
-     * 有在飞的请求就合并；不 force 且未过期就返回缓存；否则拉一次。
-     */
-    async getView(options = {}) {
-        if (this.inflight !== null)
-            return this.inflight;
-        if (options.force !== true && this.canServeCache())
-            return this.toView(options.currency);
-        const run = this.fetchOnce(options.currency).finally(() => {
-            this.inflight = null;
-        });
-        this.inflight = run;
-        return run;
-    }
-    /**
-     * 手动刷新。
+     * `providerHint` 一变（用户切了会话、切了模型）就重新解析来源 —— 这是「跟着会话走」的入口。
      *
-     * 冷却中不触发；已有请求在飞时合并并回报 `joined`。
+     * **本插件只记官方的那一个数字**，所以首选那条路拿不出数字时**退到另一条官方路**：
+     * 叉（空态 / 失败态）只在「官方两条路都拿不到数据」时才出现 —— 那才是「没接入官方」。
      */
-    async forceRefresh(reason) {
-        const cooldownMs = this.options.config.current().manualRefreshCooldownSeconds * 1000;
-        const since = this.options.clock.now() - (this.snapshot?.fetchedAt ?? 0);
-        if (this.state === 'ok' && since < cooldownMs) {
-            this.metrics.counter('force_rejected_total');
-            this.options.logger?.debug('ds-balance: manual refresh rejected by cooldown', { reason });
-            return { triggered: false, joined: false, cooldownMs: cooldownMs - since, state: this.state };
+    async getView(options = {}) {
+        const preferred = await this.resolve(options.providerHint);
+        const view = await this.viewOf(preferred, options);
+        // 展示出去的那条 = 刷新与标签认的那条（否则「数字是账号的、刷新去刷 Key」）。
+        if (view.state === 'ok') {
+            this.mark(preferred);
+            return view;
         }
-        if (this.inflight !== null) {
-            await this.inflight;
-            return { triggered: true, joined: true, cooldownMs: 0, state: this.state };
+        // 兜底顺序：固定顺序里排在前面的先试，跳过刚试过的那条。
+        for (const id of FALLBACK_ORDER) {
+            if (id === preferred)
+                continue;
+            const fallback = await this.viewOf(id, options);
+            // 有快照就赢过没快照（陈的官方数字也比一个叉有信息）；两边都没快照就继续找。
+            if (fallback.state === 'ok' || fallback.fetchedAt !== null) {
+                this.mark(id);
+                return fallback;
+            }
         }
-        await this.getView({ force: true });
-        return { triggered: true, joined: false, cooldownMs: 0, state: this.state };
+        this.mark(preferred);
+        return view;
     }
-    /** 快照是否还在 `serverRefreshSeconds` 窗口内。**只看时间，不看状态。** */
-    withinWindow() {
-        if (this.snapshot === null)
-            return false;
-        const window = this.options.config.current().serverRefreshSeconds * 1000;
-        return this.options.clock.now() - this.snapshot.fetchedAt < window;
+    /** 取一条路的视图（先确保它恢复过）。 */
+    async viewOf(id, options) {
+        await this.restoreLedger(id);
+        return this.ledger(id).getView({ force: options.force, currency: options.currency });
     }
     /**
-     * 能否直接拿缓存顶上。
+     * 定时刷新：刷**用户实际看到的那条**。
      *
-     * 与 {@link withinWindow} 分开：`restore` 要在状态还是 `empty` 时用纯时间判据，
-     * 而这里必须要求 `ok` —— 否则一次失败之后，窗口内的旧快照会让 `getView`
-     * 永远不再重试。
+     * 来源还没定过（宿主刚起来、可选服务未到齐）时先解析一次；定过之后就认 `active` ——
+     * 而 `active` 是**上一次真正把数字交出去的那条**（`getView` 兜底出去的也算），
+     * 所以兜底展示的账号数字才会被继续刷新，不会永远停在一张旧快照上。
      */
-    canServeCache() {
-        return this.state === 'ok' && this.withinWindow();
+    async refreshActive() {
+        let id = this.resolved ? this.active : await this.resolve(undefined);
+        // **服务晚到的自愈点**：宿主刚起来时判据可能还没齐（账号服务已注册、但它自己的凭据
+        // 还没读出来），那一轮会落在一条不可用的路上。下一轮发现仍旧不可用就再解析一次 ——
+        // 不必等界面来请求，也不必靠外部作废。
+        if (!(await this.ledger(id).available()))
+            id = await this.resolve(undefined);
+        this.mark(id);
+        await this.restoreLedger(id);
+        return this.ledger(id).getView({ force: true });
     }
-    /** 跑一次真实抓取。**所有异常都在这里被吸收。** */
-    async fetchOnce(currency) {
-        const startedAt = this.options.clock.now();
-        try {
-            const apiKey = await this.options.keys.resolve();
-            const config = this.options.config.current();
-            const raw = await this.options.client.fetchBalance({
-                baseUrl: endpointOf(config),
-                apiKey,
-                timeoutMs: this.options.config.timeoutMs(),
-            });
-            const snapshot = normalize(raw, computeAccountTag(this.options.salt, apiKey), this.options.clock.now());
-            // 落盘失败不算这次抓取失败：快照留在内存里，界面照常显示，
-            // 代价只是重启后不恢复。存储是可降级的一层。
-            await this.persist(snapshot);
-            this.snapshot = snapshot;
-            this.state = 'ok';
-            this.error = null;
-            this.failures = 0;
-            this.retryAfterMs = null;
-            this.metrics.counter('balance_fetch_total', { result: 'ok' });
-            this.metrics.histogram('balance_fetch_duration_ms', {}, this.options.clock.now() - startedAt);
-            this.publishGauge();
-            return this.toView(currency);
-        }
-        catch (error) {
-            this.applyFailure(error, startedAt);
-            return this.toView(currency);
-        }
+    /** 作废「来源已定」这件事，让下一次调度重新解析。 */
+    invalidateSource() {
+        this.resolved = false;
     }
     /**
-     * 把快照落盘。
+     * 手动刷新：**用户看哪条就刷哪条**（与 {@link getView} 同一条判定）。
      *
-     * **失败只记一次 warn，不往上抛**：存储层降级不该让整个余额功能不可用。
-     * @param snapshot - 刚归一化出来的快照。
+     * 首选那条一条数字都没有时，界面上实际是兜底那条在撑着 —— 那就刷兜底那条，
+     * 否则用户点了刷新、数字却永远不动。冷却仍由那条自己的账本管。
      */
-    async persist(snapshot) {
-        try {
-            await this.options.store.saveSnapshot(snapshot);
+    async forceRefresh(reason, providerHint) {
+        const preferred = await this.resolve(providerHint);
+        await this.restoreLedger(preferred);
+        const shown = this.ledger(preferred).status().hasSnapshot
+            ? preferred
+            : await this.firstWithSnapshot(preferred);
+        this.mark(shown);
+        await this.restoreLedger(shown);
+        return this.ledger(shown).forceRefresh(reason);
+    }
+    /** 找一条**有快照**的官方路；都没有就退回默认那条（那时才画叉）。 */
+    async firstWithSnapshot(preferred) {
+        for (const id of FALLBACK_ORDER) {
+            if (id === preferred)
+                continue;
+            await this.restoreLedger(id);
+            if (this.ledger(id).status().hasSnapshot)
+                return id;
         }
-        catch (error) {
-            if (this.persistWarned)
-                return;
-            this.persistWarned = true;
-            this.options.logger?.warn('ds-balance: snapshot not persisted, continuing in memory', {
-                error: describeError(error),
+        return preferred;
+    }
+    /** 记下「这条刚刚把数字交出去了」：展示、刷新、标签从此都认它。 */
+    mark(id) {
+        if (id !== this.active) {
+            this.options.logger?.debug('ds-balance: balance source switched', {
+                from: this.active,
+                to: id,
+            });
+            // 来源摆动（首选那条时好时坏）在界面上**刻意不给提示**（见决策记录
+            // `.agents/notes/2026-10-01-boundaries-left-as-is.md`），所以这里是唯一的观测出口：
+            // 没有这个计数器，「来源在摆」只能靠翻日志发现。
+            this.options.metrics?.counter('balance_source_switch_total', {
+                from: this.active,
+                to: id,
             });
         }
+        this.active = id;
+        this.resolved = true;
     }
-    /** 记录一次失败，并把状态推到 `stale` 或 `error`。 */
-    applyFailure(error, startedAt) {
-        const info = classify(error);
-        this.failures += 1;
-        this.error = info;
-        this.state = this.snapshot === null ? 'error' : 'stale';
-        this.retryAfterMs = retryAfterOf(error, this.options.clock.now());
-        // 只在首次失败打 warn，避免日志刷屏。
-        if (this.failures === 1) {
-            this.options.logger?.warn('ds-balance: balance fetch failed', { code: info.code });
-        }
-        this.metrics.counter('balance_fetch_total', { result: 'error' });
-        this.metrics.histogram('balance_fetch_duration_ms', {}, this.options.clock.now() - startedAt);
-        this.publishGauge();
+    /** 解析这一轮**首选**哪条路。 */
+    async resolve(hint) {
+        const routed = routeOf(hint ?? this.options.routeProvider());
+        // 问**每一条**账本自己「此刻可用吗」：新增来源时这里一行都不用改。
+        const availability = new Map();
+        await Promise.all([...this.options.ledgers].map(async ([id, ledger]) => {
+            availability.set(id, await ledger.available());
+        }));
+        return pickSource({ routed, available: (id) => availability.get(id) === true });
     }
-    /** 把缓存状态推成指标。 */
-    publishGauge() {
-        this.metrics.gauge('cache_state', { state: this.state }, 1);
+    /** 取账本；缺一条属于装配错误，直接抛（静默降级会让界面永远停在空态）。 */
+    ledger(id) {
+        const ledger = this.options.ledgers.get(id);
+        if (ledger === undefined)
+            throw new Error(`ds-balance: no ledger for source ${id}`);
+        return ledger;
     }
-    /** 把缓存折成对外视图。 */
-    toView(currency) {
-        const config = this.options.config.current();
-        const thresholds = this.options.config.thresholds();
-        const preference = currency ?? config.displayCurrency;
-        const selected = this.snapshot === null ? null : pickBalance(this.snapshot.balances, preference);
-        return {
-            state: this.state,
-            stale: this.state === 'stale',
-            fetchedAt: this.snapshot?.fetchedAt ?? null,
-            ageMs: this.snapshot === null
-                ? null
-                : Math.max(0, this.options.clock.now() - this.snapshot.fetchedAt),
-            isAvailable: this.snapshot?.isAvailable ?? null,
-            balances: this.snapshot?.balances ?? [],
-            selected: selected === null ? null : { currency: selected.currency, total: selected.total },
-            severity: severityOf(selected, this.snapshot?.isAvailable ?? false, thresholdsFor(selected?.currency ?? '', thresholds)),
-            thresholds,
-            error: this.state === 'ok' ? null : this.error,
-        };
+    /** 首次用到某条路时才恢复它的快照；并发调用合并成一次。 */
+    restoreLedger(id) {
+        let pending = this.restores.get(id);
+        if (pending === undefined) {
+            pending = this.ledger(id).restore();
+            this.restores.set(id, pending);
+        }
+        return pending;
     }
 }
-/** 从上游错误里抽 `Retry-After`；抽不到返回 `null`。 */
-function retryAfterOf(error, now) {
-    if (typeof error !== 'object' || error === null || !('headers' in error))
-        return null;
-    const headers = error.headers;
-    if (!(headers instanceof Headers))
-        return null;
-    return parseRetryAfter(headers, now) ?? null;
-}
 //# sourceMappingURL=balance-service.js.map

package/lib/services/balance-source.d.ts

@@ -0,0 +1,174 @@
+/**
+ * 一个取数来源的账本：快照、状态机、抓取与落盘。
+ *
+ * 职责：把「读一次 → 归一化 → 落快照」包成一次可合并的请求，并维护这一条路自己的缓存状态。
+ * **对外永不抛错**：一切失败都变成 `view.state` 与 `view.error`。
+ *
+ * 两条路（API Key / 账号登录）各持一份账本，互不影响 —— 谁的失败都不该拖累另一条。
+ * @module dsh-ds-balance/services/balance-source
+ */
+import type { BalanceSource, BalanceView, CacheState, Severity } from '../domain/balance.js';
+import { type ErrorCode } from '../domain/errors.js';
+import type { Clock } from '../ports/clock.js';
+import type { CoreStore } from '../ports/core-store.js';
+import type { Logger } from '../ports/logger.js';
+import { type Metrics } from '../ports/metrics.js';
+import type { ConfigService } from './config-service.js';
+/**
+ * 一条路的读取策略。
+ *
+ * 账本不认识凭据、不认识 HTTP —— 换来源就是换一个 reader。
+ * `available()` 与 `tag()` 都是**本地读**（凭据/身份来自内存），只有 `read()` 打上游。
+ */
+export interface SourceReader {
+    /** 这条路的凭据此刻可用吗。 */
+    available(): Promise<boolean>;
+    /** 这次快照的账本标识；凭据拿不到时抛错（由调用方吸收）。 */
+    tag(): Promise<string>;
+    /** 抓一次余额，连账本标识一起给。 */
+    read(): Promise<{
+        raw: unknown;
+        accountTag: string;
+    }>;
+}
+/** `forceRefresh` 的返回值，形状对齐契约 §8.4。 */
+export interface RefreshResult {
+    triggered: boolean;
+    joined: boolean;
+    cooldownMs: number;
+    state: CacheState;
+}
+/** 调度器需要的状态切片。 */
+export interface BalanceStatus {
+    state: CacheState;
+    errorCode: ErrorCode | null;
+    consecutiveFailures: number;
+    hasSnapshot: boolean;
+    serverRefreshSeconds: number;
+    /** 上游给的 `Retry-After`，优先于自算退避。 */
+    retryAfterMs: number | null;
+    /** 最近一次成功抓取的时刻；从未成功过是 `null`。健康检查要用。 */
+    lastSuccessAt: number | null;
+    /** 这一份状态属于哪条路。 */
+    source: BalanceSource;
+    /**
+     * 下面四项**只服务健康检查里的处境**（`GET /api/v1/healthz` 的 `situation`）：
+     * 不开浏览器也要能知道活跃账本此刻会画成什么。判定口径与 `toView` 完全同源。
+     */
+    /** 快照里的上游 `is_available`；没有快照时 `false`。 */
+    isAvailable: boolean;
+    /** 按当前显示币种偏好挑得出可展示的币种吗。 */
+    hasSelected: boolean;
+    /** 后端算好的严重度。 */
+    severity: Severity;
+}
+/** `getView` 的可选参数（账本层：来源已经定好了）。 */
+export interface LedgerViewOptions {
+    /** 跳过新鲜度判据强制拉一次。 */
+    force?: boolean;
+    /** 覆盖展示币种偏好；缺省读配置。 */
+    currency?: string;
+}
+/** 构造参数。 */
+export interface SourceLedgerOptions {
+    source: BalanceSource;
+    reader: SourceReader;
+    store: CoreStore;
+    config: ConfigService;
+    clock: Clock;
+    logger?: Logger | undefined;
+    metrics?: Metrics | undefined;
+}
+/** 一条路的账本。 */
+export declare class SourceLedger {
+    private readonly options;
+    private readonly metrics;
+    private snapshot;
+    private state;
+    private error;
+    private failures;
+    private retryAfterMs;
+    /** 上一次真的触发过手动刷新的时刻；`null` 表示本账本还没有过。 */
+    private lastManualRefreshAt;
+    private inflight;
+    /** 落盘失败只报一次，避免每轮刷新都刷屏。 */
+    private persistWarned;
+    constructor(options: SourceLedgerOptions);
+    /** 这条路的 id。 */
+    source(): BalanceSource;
+    /** 这条路的凭据此刻可用吗。 */
+    available(): Promise<boolean>;
+    /** 当前状态切片，供调度与健康检查使用。 */
+    status(): BalanceStatus;
+    /**
+     * 当前账本标识的前 8 位；还没有快照时是 `null`。
+     *
+     * **只回前 8 位**：完整 tag 是账本作用域标识，没有对外的理由。
+     */
+    accountTag8(): string | null;
+    /**
+     * 从存储恢复最近快照（这条账本第一次被用到时调一次）。
+     *
+     * **按 `accountTag` 过滤**：凭据轮换后 tag 变了，旧快照视为不存在，不混用。
+     * 没有凭据可算 tag 时静默跳过。
+     */
+    restore(): Promise<void>;
+    /**
+     * 取当前视图。
+     *
+     * 有在飞的请求就合并；不 force 且未过期就返回缓存；否则拉一次。
+     */
+    getView(options?: LedgerViewOptions): Promise<BalanceView>;
+    /**
+     * 手动刷新。
+     *
+     * 冷却中不触发；已有请求在飞时合并并回报 `joined`。
+     *
+     * **冷却的锚点是「上一次手动刷新」，不是「上一次抓取」**：调度与轮询也在抓，
+     * 拿 `snapshot.fetchedAt` 当锚点的话，一次自动刷新就会把用户刚按下的一下吞掉 ——
+     * 界面转了圈、倒计时也走了，上游却一次没打。
+     *
+     * 时刻取**决定触发那一刻**（不是抓完那一刻）：客户端从「拿到结果那一刻」起算，
+     * 两者相差一个往返 ⇒ 客户端更保守，按钮亮起时按下去一定真的会抓。
+     */
+    forceRefresh(reason: string): Promise<RefreshResult>;
+    /** 快照是否还在 `serverRefreshSeconds` 窗口内。**只看时间，不看状态。** */
+    private withinWindow;
+    /**
+     * 能否直接拿缓存顶上。
+     *
+     * 与 {@link withinWindow} 分开：`restore` 要在状态还是 `empty` 时用纯时间判据，
+     * 而这里必须要求 `ok` —— 否则一次失败之后，窗口内的旧快照会让 `getView`
+     * 永远不再重试。
+     */
+    private canServeCache;
+    /** 跑一次真实抓取。**所有异常都在这里被吸收。** */
+    private fetchOnce;
+    /**
+     * 把快照落盘。
+     *
+     * **失败只记一次 warn，不往上抛**：存储层降级不该让整个余额功能不可用。
+     * @param snapshot - 刚归一化出来的快照。
+     */
+    private persist;
+    /** 记录一次失败，并把状态推到 `stale` 或 `error`。 */
+    private applyFailure;
+    /** 记一次抓取耗时（带上来源标签，两条路各自可看）。 */
+    private observe;
+    /** 记一次抓取结果。 */
+    private count;
+    /** 把缓存状态推成指标。 */
+    private publishGauge;
+    /** 把缓存折成对外视图。 */
+    private toView;
+    /**
+     * 这一份视图的严重度。
+     *
+     * **只服务环的颜色与弧长**；「处境」是另一个维度，由 {@link situationOf} 判，
+     * 两者不再各自决定界面形态（历史上它们是两条互相打架的链）。
+     * @param selected - 选中币种的那条余额；没快照时是 `null`。
+     * @returns 严重度。
+     */
+    private severityOf;
+}
+//# sourceMappingURL=balance-source.d.ts.map