dsh-ds-balance 2.1.3 → 2.3.0

package/lib/domain/account.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 账号钱包的领域形状与投影。
+ *
+ * 账号那条路（`ctx.deepseekAccount`）给的是**钱包列表**，不是官方余额端点的形状。
+ * 投影成 {@link RawBalanceResponse} 之后，下游（归一化 → 存储 → 视图 → 界面）一行都不用改 ——
+ * 这也是为什么这个函数放在领域层：它是纯的，且对着的是我们自己那条线上形状。
+ * @module dsh-ds-balance/domain/account
+ */
+import type { RawBalanceResponse } from './balance.js';
+/** 一条钱包。金额是官方给的十进制字符串，原样带着，不改精度。 */
+export interface AccountWallet {
+    readonly currency: string;
+    readonly balance: string;
+}
+/** 一次账号余额查询的结果：充值钱包与赠送钱包分开给。 */
+export interface AccountBalance {
+    readonly wallets: readonly AccountWallet[];
+    readonly bonusWallets: readonly AccountWallet[];
+}
+/**
+ * 把官方允许的科学计数法展开成十进制定点。
+ *
+ * 账号侧的钱包金额走 Platform 的 Web 客户端语法，允许 `1e+3` / `0E-16` / `.5` 这类写法；
+ * 本仓的 {@link parseMoney} **只认十进制定点**（这是刻意的：线上金额从来不带指数）。
+ * 所以先把形状补齐，再交给领域层 —— 缺了这一步，一个 `1e+3` 会让整次抓取报 ParseError。
+ * @param value - 官方给的金额字符串。
+ * @returns 定点字符串；形状认不出来时原样返回，让下游的 `parseMoney` 去报错。
+ */
+export declare function toPlainDecimal(value: string): string;
+/**
+ * 把账号钱包投影成官方余额端点的线上形状。
+ *
+ * 口径对齐官方账号页：**总余额 = 充值钱包 + 赠送钱包**，两个分项各自照给。
+ * 两条路都出现同一个币种时合并，只在一侧出现的币种也照出。
+ * @param balance - 账号服务给出的钱包。
+ * @returns `GET /user/balance` 的形状，可直接进 {@link normalize}。
+ * @throws {ParseError} 金额不是十进制定点（含展开后仍不合法的形状）。
+ */
+export declare function projectAccountBalance(balance: AccountBalance): RawBalanceResponse;
+//# sourceMappingURL=account.d.ts.map

package/lib/domain/account.js

@@ -0,0 +1,74 @@
+/**
+ * 账号钱包的领域形状与投影。
+ *
+ * 账号那条路（`ctx.deepseekAccount`）给的是**钱包列表**，不是官方余额端点的形状。
+ * 投影成 {@link RawBalanceResponse} 之后，下游（归一化 → 存储 → 视图 → 界面）一行都不用改 ——
+ * 这也是为什么这个函数放在领域层：它是纯的，且对着的是我们自己那条线上形状。
+ * @module dsh-ds-balance/domain/account
+ */
+import { formatMoney, parseMoney } from './money.js';
+/**
+ * 把官方允许的科学计数法展开成十进制定点。
+ *
+ * 账号侧的钱包金额走 Platform 的 Web 客户端语法，允许 `1e+3` / `0E-16` / `.5` 这类写法；
+ * 本仓的 {@link parseMoney} **只认十进制定点**（这是刻意的：线上金额从来不带指数）。
+ * 所以先把形状补齐，再交给领域层 —— 缺了这一步，一个 `1e+3` 会让整次抓取报 ParseError。
+ * @param value - 官方给的金额字符串。
+ * @returns 定点字符串；形状认不出来时原样返回，让下游的 `parseMoney` 去报错。
+ */
+export function toPlainDecimal(value) {
+    const text = value.trim();
+    const match = /^(-?)(\d*)(?:\.(\d*))?(?:[eE]([+-]?\d+))?$/.exec(text);
+    if (match === null)
+        return text;
+    const [, sign = '', whole = '', fraction = '', exponent] = match;
+    if (exponent === undefined) {
+        return `${sign}${whole === '' ? '0' : whole}${fraction === '' ? '' : `.${fraction}`}`;
+    }
+    const digits = `${whole}${fraction}`;
+    if (digits === '')
+        return text;
+    const pointAt = whole.length + Number(exponent);
+    if (pointAt <= 0)
+        return `${sign}0.${'0'.repeat(-pointAt)}${digits}`;
+    if (pointAt >= digits.length)
+        return `${sign}${digits}${'0'.repeat(pointAt - digits.length)}`;
+    return `${sign}${digits.slice(0, pointAt)}.${digits.slice(pointAt)}`;
+}
+/** 按币种把钱包折成最小单位；同币种出现多次时后者覆盖前者（官方不会给重复项）。 */
+function walletTotals(wallets) {
+    const totals = new Map();
+    for (const wallet of wallets) {
+        totals.set(wallet.currency, parseMoney(toPlainDecimal(wallet.balance)));
+    }
+    return totals;
+}
+/**
+ * 把账号钱包投影成官方余额端点的线上形状。
+ *
+ * 口径对齐官方账号页：**总余额 = 充值钱包 + 赠送钱包**，两个分项各自照给。
+ * 两条路都出现同一个币种时合并，只在一侧出现的币种也照出。
+ * @param balance - 账号服务给出的钱包。
+ * @returns `GET /user/balance` 的形状，可直接进 {@link normalize}。
+ * @throws {ParseError} 金额不是十进制定点（含展开后仍不合法的形状）。
+ */
+export function projectAccountBalance(balance) {
+    const toppedUp = walletTotals(balance.wallets);
+    const granted = walletTotals(balance.bonusWallets);
+    const currencies = [...new Set([...toppedUp.keys(), ...granted.keys()])];
+    return {
+        // 能读到钱包就说明账号可用；这与 `/user/balance` 的 `is_available` 同义。
+        is_available: true,
+        balance_infos: currencies.map((currency) => {
+            const topped = toppedUp.get(currency) ?? 0n;
+            const bonus = granted.get(currency) ?? 0n;
+            return {
+                currency,
+                total_balance: formatMoney(topped + bonus),
+                granted_balance: formatMoney(bonus),
+                topped_up_balance: formatMoney(topped),
+            };
+        }),
+    };
+}
+//# sourceMappingURL=account.js.map

package/lib/domain/balance.d.ts

@@ -6,8 +6,18 @@
  */
 import type { ErrorInfo } from './errors.js';
 import type { Units } from './money.js';
+import type { Situation } from './situation.js';
 /** 币种代码，例如 `CNY` / `USD`。 */
 export type Currency = string;
+/**
+ * 余额来源：官方的两条取数路。
+ *
+ * - `deepseek-http`：官方余额端点 `GET /user/balance`，凭据是 API Key（解析链见 `KeyResolver`）。
+ * - `deepseek-account`：宿主账号服务的钱包查询，凭据是账号登录态。
+ *
+ * **取值是追加式的**：已落盘的记录里只有前者，所以它必须一直是合法值（域版本不抬）。
+ */
+export type BalanceSource = 'deepseek-http' | 'deepseek-account';
 /** 缓存状态。闭集。 */
 export type CacheState = 'empty' | 'ok' | 'stale' | 'error';
 /** 颜色严重度。闭集，前端只做机械映射。 */
@@ -32,10 +42,30 @@ export interface BalanceSnapshot {
     /** 全币种余额。 */
     balances: BalanceInfo[];
     /** 数据来源。 */
-    source: 'deepseek-http';
+    source: BalanceSource;
     /** 原始响应，审计用。 */
     raw: unknown;
 }
+/**
+ * 每个账本保留多少条快照。**历史保留深度，不是功能开关。**
+ *
+ * **为什么住在 domain**：写入路径（`SourceLedger.persist`）与启动清理
+ * （`DomainCoreStore.initialize`）都要读它，而 adapters 与 services 互相不能依赖 ——
+ * `domain/` 是两层共同的下游，是唯一能放这个常量的地方。
+ * （最初它住在 `balance-source.ts` 顶部，理由是「紧挨唯一调用点」；启动清理加入后
+ * 调用点变成两个，那条理由就不再成立。）
+ *
+ * - 当前**没有任何功能读第二条以后的记录**：唯一读点是 `loadLatestSnapshot` 取最新一条，
+ *   仓内没有 `listSnapshots`，也没有历史端点（`docs/ARCHITECTURE.md` 的阶段边界
+ *   明写不做图表）。所以这个数**不是**为功能服务的，不要因为「用不到」就调到 1。
+ * - 它真正的作用是**故障回退余量**：最新那条写失败、写坏、或落盘途中崩了时还能退到上一条，
+ *   覆盖连续两次失败就要 ≥ 3。
+ * - **刻意不进配置面**：配置字段用户看得见、改得动，而这个数没有用户可感知的语义 ——
+ *   改小它用户看不出界面变化，只会在某天丢快照时才后悔。给一个看不出区别的旋钮比不给更糟。
+ *
+ * 量级：一条快照约 0.9 KB，20 条约 18 KB —— 余量与存储成本之间没有取舍压力。
+ */
+export declare const SNAPSHOT_KEEP_N = 20;
 /** 一个币种的预警 / 告急阈值。 */
 export interface ThresholdPair {
     warn: Units;
@@ -43,6 +73,15 @@ export interface ThresholdPair {
 }
 /** 给前端的余额视图。 */
 export interface BalanceView {
+    /** 这一份数字是哪条取数路给的。界面据此标来源。 */
+    source: BalanceSource;
+    /**
+     * 处境：界面唯一的分支入口。
+     *
+     * 环、文案、来源标签都从它派生 —— 界面**不再**自己组合 `state` / `severity` / `error.code`。
+     * 判定只有一处（[situation.ts](situation.ts) 的 `situationOf`）。
+     */
+    situation: Situation;
     state: CacheState;
     stale: boolean;
     fetchedAt: number | null;

package/lib/domain/balance.js

@@ -4,5 +4,24 @@
  * 这里定义的是**契约形状**：金额一律 `bigint` 最小单位，序列化时才变字符串。
  * @module dsh-ds-balance/domain/balance
  */
-export {};
+/**
+ * 每个账本保留多少条快照。**历史保留深度，不是功能开关。**
+ *
+ * **为什么住在 domain**：写入路径（`SourceLedger.persist`）与启动清理
+ * （`DomainCoreStore.initialize`）都要读它，而 adapters 与 services 互相不能依赖 ——
+ * `domain/` 是两层共同的下游，是唯一能放这个常量的地方。
+ * （最初它住在 `balance-source.ts` 顶部，理由是「紧挨唯一调用点」；启动清理加入后
+ * 调用点变成两个，那条理由就不再成立。）
+ *
+ * - 当前**没有任何功能读第二条以后的记录**：唯一读点是 `loadLatestSnapshot` 取最新一条，
+ *   仓内没有 `listSnapshots`，也没有历史端点（`docs/ARCHITECTURE.md` 的阶段边界
+ *   明写不做图表）。所以这个数**不是**为功能服务的，不要因为「用不到」就调到 1。
+ * - 它真正的作用是**故障回退余量**：最新那条写失败、写坏、或落盘途中崩了时还能退到上一条，
+ *   覆盖连续两次失败就要 ≥ 3。
+ * - **刻意不进配置面**：配置字段用户看得见、改得动，而这个数没有用户可感知的语义 ——
+ *   改小它用户看不出界面变化，只会在某天丢快照时才后悔。给一个看不出区别的旋钮比不给更糟。
+ *
+ * 量级：一条快照约 0.9 KB，20 条约 18 KB —— 余量与存储成本之间没有取舍压力。
+ */
+export const SNAPSHOT_KEEP_N = 20;
 //# sourceMappingURL=balance.js.map

package/lib/domain/normalize.d.ts

@@ -5,7 +5,7 @@
  * **绝不静默归 0。**
  * @module dsh-ds-balance/domain/normalize
  */
-import type { BalanceSnapshot } from './balance.js';
+import type { BalanceSnapshot, BalanceSource } from './balance.js';
 /**
  * 生成单调递增、可按字典序排序的快照 id。
  * @param now - 当前时刻。
@@ -17,11 +17,12 @@ export declare function nextSnapshotId(now: number): string;
  * @param raw - 上游 JSON，未经信任。
  * @param accountTag - 账本作用域标识。
  * @param now - 抓取时刻。
+ * @param source - 这份数据是哪条取数路给的。
  * @returns 不可变快照。
  * @throws {ShapeError} 结构不符。
  * @throws {ParseError} 金额不是十进制定点。
  */
-export declare function normalize(raw: unknown, accountTag: string, now: number): BalanceSnapshot;
+export declare function normalize(raw: unknown, accountTag: string, now: number, source: BalanceSource): BalanceSnapshot;
 /** 从错误体里抽出的可读信息。 */
 export interface ParsedErrorBody {
     code?: string;

package/lib/domain/normalize.js

@@ -58,11 +58,12 @@ function parseAmount(value, field) {
  * @param raw - 上游 JSON，未经信任。
  * @param accountTag - 账本作用域标识。
  * @param now - 抓取时刻。
+ * @param source - 这份数据是哪条取数路给的。
  * @returns 不可变快照。
  * @throws {ShapeError} 结构不符。
  * @throws {ParseError} 金额不是十进制定点。
  */
-export function normalize(raw, accountTag, now) {
+export function normalize(raw, accountTag, now, source) {
     if (raw === null || typeof raw !== 'object')
         throw new ShapeError('response is not an object');
     const body = raw;
@@ -76,7 +77,7 @@ export function normalize(raw, accountTag, now) {
         fetchedAt: now,
         isAvailable: body.is_available,
         balances: body.balance_infos.map((entry, index) => toBalanceInfo(entry, index)),
-        source: 'deepseek-http',
+        source,
         raw,
     };
 }

package/lib/domain/severity.d.ts

@@ -24,8 +24,14 @@ export declare function thresholdsFor(currency: Currency, thresholds: Record<Cur
 /**
  * 判定严重度。
  *
- * 顺序即优先级：**不可用压过阈值**；没有任何选定币种时为 `unknown`。
- * @param selected - 选定的币种余额；为 `null` 时返回 `unknown`。
+ * **顺序即优先级，且顺序本身是有意的**：
+ * 1. **账户停用压过一切**（`!isAvailable`）—— 它是账户维度的事实，与有没有选中币种无关。
+ *    欠费/停用的账户上游可能给**空的** `balance_infos`，那也会有 `selected === null`；
+ *    若先判 `selected === null` 就会返回 `unknown`，界面把「账户停用」画成灰环，
+ *    与「账户本来就没有余额」同形 —— 这条顺序就是为它定的。
+ * 2. 没有任何选定币种（且账户可用）→ `unknown`：真的一无所有，没有信息可表。
+ * 3. 其余按阈值分档，边界取等号。
+ * @param selected - 选定的币种余额；为 `null` 时若账户不可用仍返回 `unavailable`。
  * @param isAvailable - 上游 `is_available`。
  * @param thresholds - 该币种的阈值。
  * @returns 闭集内的严重度。

package/lib/domain/severity.js

@@ -24,17 +24,24 @@ export function thresholdsFor(currency, thresholds) {
 /**
  * 判定严重度。
  *
- * 顺序即优先级：**不可用压过阈值**；没有任何选定币种时为 `unknown`。
- * @param selected - 选定的币种余额；为 `null` 时返回 `unknown`。
+ * **顺序即优先级，且顺序本身是有意的**：
+ * 1. **账户停用压过一切**（`!isAvailable`）—— 它是账户维度的事实，与有没有选中币种无关。
+ *    欠费/停用的账户上游可能给**空的** `balance_infos`，那也会有 `selected === null`；
+ *    若先判 `selected === null` 就会返回 `unknown`，界面把「账户停用」画成灰环，
+ *    与「账户本来就没有余额」同形 —— 这条顺序就是为它定的。
+ * 2. 没有任何选定币种（且账户可用）→ `unknown`：真的一无所有，没有信息可表。
+ * 3. 其余按阈值分档，边界取等号。
+ * @param selected - 选定的币种余额；为 `null` 时若账户不可用仍返回 `unavailable`。
  * @param isAvailable - 上游 `is_available`。
  * @param thresholds - 该币种的阈值。
  * @returns 闭集内的严重度。
  */
 export function severityOf(selected, isAvailable, thresholds) {
-    if (selected === null)
-        return 'unknown';
+    // 顺序不能换：见上面第 1 条（停用 + 空余额列表是一条真实路径）。
     if (!isAvailable)
         return 'unavailable';
+    if (selected === null)
+        return 'unknown';
     if (cmpMoney(selected.total, thresholds.critical) <= 0)
         return 'critical';
     if (cmpMoney(selected.total, thresholds.warn) <= 0)

package/lib/domain/situation.d.ts

@@ -0,0 +1,104 @@
+/**
+ * 处境：界面上每一种形态对应的「用户此刻的处境」。
+ *
+ * **为什么要有它**：之前环、文案、来源标签**各拼各的** —— 环只吃 `severity`，文案吃
+ * `state + error.code + isAvailable + selection`，标签吃 `state + source`。三套输入集不同、
+ * 优先级也不同，于是必然出现「环说 A、文案说 B」（例如旧快照 + `isAvailable: false` 时
+ * 环是叉、文案却是「数据已过期」），也必然出现「一个空环同时代表三种处境」。
+ *
+ * 现在只有这一处分支：`situationOf` 按**固定优先级**逐条判，第一个命中即返回。
+ * 环、文案、标签都从它的输出派生，不再各自读字段。
+ *
+ * **闭集，取值有意细**：内部枚举可以细（诊断、日志、指标都要它），
+ * 视觉可以粗（收起态只有 5 个族，见客户端 `client/situation.ts` 的形态表）。
+ * 两者不必一一对应 —— 但**每一处合并都必须是有意的、写在表里的**，不是默认掉进去的。
+ * @module dsh-ds-balance/domain/situation
+ */
+import type { Severity } from './balance.js';
+import type { ErrorCode } from './errors.js';
+/**
+ * 处境闭集。
+ *
+ * 前两个**只有客户端能产生**（宿主不可能知道「插件自己的端点通不通」与「首帧到了没有」），
+ * 其余九个由宿主判定。两个生产方、一张消费表。
+ */
+export type Situation = 
+/** 首帧：还没问到后端。客户端本地事实。 */
+'checking'
+/** 插件自己的端点不可达。客户端本地事实。 */
+ | 'offline'
+/** handler 自己抛错 —— 「我们坏了」，不是「上游坏了」。 */
+ | 'internal-error'
+/** 两条官方取数路都没有凭据 —— 需要用户去配置。 */
+ | 'no-credential'
+/** 接入过（或本该接入）却读不到：网络 / 上游 / 账号查询失败，且没有旧快照。 */
+ | 'fetch-failed'
+/** 读到了，但上游说这个账户不可用（停用 / 欠费）。 */
+ | 'account-unavailable'
+/** 有旧快照，但本次没读到。 */
+ | 'stale'
+/** 连上了、账户可用，但没有任何可展示的币种。 */
+ | 'empty-wallet'
+/** 有数字，正常。 */
+ | 'ok'
+/** 有数字，偏低。 */
+ | 'low'
+/** 有数字，告急。 */
+ | 'critical';
+/**
+ * {@link situationOf} 可能返回的处境。
+ *
+ * **注意不含 `internal-error` 与两个客户端值**：前者由 HTTP 层的兜底视图直接给
+ * （`handlers.ts` 的 `failureView` —— handler 自己抛错时根本走不到 `situationOf`），
+ * 后者只有客户端能产生。生产方是三分而不是两分，这张表把它写清楚。
+ */
+export declare const SITUATIONS_FROM_FACTS: readonly ["no-credential", "fetch-failed", "account-unavailable", "stale", "empty-wallet", "ok", "low", "critical"];
+/** 宿主能产生的处境 = 事实判出来的 + 兜底视图那一个。 */
+export declare const HOST_SITUATIONS: readonly ["internal-error", "no-credential", "fetch-failed", "account-unavailable", "stale", "empty-wallet", "ok", "low", "critical"];
+/** 客户端本地产生的处境（宿主不可能知道这两件事）。 */
+export declare const CLIENT_SITUATIONS: readonly ["checking", "offline"];
+/** 全部处境。 */
+export declare const SITUATIONS: readonly ["checking", "offline", "internal-error", "no-credential", "fetch-failed", "account-unavailable", "stale", "empty-wallet", "ok", "low", "critical"];
+/**
+ * 判定处境所需的事实。
+ *
+ * 刻意**只收事实、不收 `BalanceView`**：这样它可以脱离视图结构单测，
+ * 也让「哪些输入参与判定」在类型上就一目了然。
+ */
+export interface SituationFacts {
+    /** 有没有快照（旧快照也算有）。 */
+    hasSnapshot: boolean;
+    /** 本次抓取是否失败、但快照还在（`state === 'stale'`）。 */
+    stale: boolean;
+    /** 上游 `is_available`；没有快照时无意义。 */
+    isAvailable: boolean;
+    /** 有没有选中可展示的币种。 */
+    hasSelected: boolean;
+    /** 后端算好的严重度。 */
+    severity: Severity;
+    /** 本次失败的对外错误码；没失败时 `null`。 */
+    errorCode: ErrorCode | null;
+}
+/**
+ * 判定处境。**顺序即优先级**，第一个命中即返回。
+ *
+ * 三条刻意的优先级（都对旧写法做过修正）：
+ * 1. **没接入压过一切**：一条凭据都没有时，说「读不到余额」是误导 —— 用户没配过任何东西，
+ *    该说的是「尚未配置凭据」。判据是 `NO_KEY` **且没有快照**（有快照说明曾经读到过，
+ *    那就不是「没接入」，而是「这轮没读到」）。
+ * 2. **账户停用压过「数据过期」**：`isAvailable: false` 是上游明确给的事实，比「数字旧了」
+ *    更强的信号，且那种快照的余额通常是 0 —— 说「数据已过期」会把真问题藏起来。
+ * 3. **`stale` 的前提是「真的有一份旧数字」**（`hasSelected`）。快照在、但里面一个可展示的
+ *    币种都没有、这轮又没读到 —— 用户手里没有任何数字，说「数据已过期」是假话
+ *    （听着像「有旧数据可看」）。归 `fetch-failed`：读不到才是实话。
+ *
+ * **不变量（界面按它设计，测试钉着）**：
+ * - 返回 `stale` / `ok` / `low` / `critical` ⇒ **一定有可展示的币种**
+ *   （所以「有数字那一族」的颜色永远由真实阈值算出来，不会是 `unknown`）；
+ * - 返回 `account-unavailable` ⇒ `isAvailable` 一定是 `false`，颜色恒红。
+ *
+ * @param facts - 判定所需的六个事实。
+ * @returns 闭集内的处境。
+ */
+export declare function situationOf(facts: SituationFacts): Situation;
+//# sourceMappingURL=situation.d.ts.map

package/lib/domain/situation.js

@@ -0,0 +1,93 @@
+/**
+ * 处境：界面上每一种形态对应的「用户此刻的处境」。
+ *
+ * **为什么要有它**：之前环、文案、来源标签**各拼各的** —— 环只吃 `severity`，文案吃
+ * `state + error.code + isAvailable + selection`，标签吃 `state + source`。三套输入集不同、
+ * 优先级也不同，于是必然出现「环说 A、文案说 B」（例如旧快照 + `isAvailable: false` 时
+ * 环是叉、文案却是「数据已过期」），也必然出现「一个空环同时代表三种处境」。
+ *
+ * 现在只有这一处分支：`situationOf` 按**固定优先级**逐条判，第一个命中即返回。
+ * 环、文案、标签都从它的输出派生，不再各自读字段。
+ *
+ * **闭集，取值有意细**：内部枚举可以细（诊断、日志、指标都要它），
+ * 视觉可以粗（收起态只有 5 个族，见客户端 `client/situation.ts` 的形态表）。
+ * 两者不必一一对应 —— 但**每一处合并都必须是有意的、写在表里的**，不是默认掉进去的。
+ * @module dsh-ds-balance/domain/situation
+ */
+/**
+ * {@link situationOf} 可能返回的处境。
+ *
+ * **注意不含 `internal-error` 与两个客户端值**：前者由 HTTP 层的兜底视图直接给
+ * （`handlers.ts` 的 `failureView` —— handler 自己抛错时根本走不到 `situationOf`），
+ * 后者只有客户端能产生。生产方是三分而不是两分，这张表把它写清楚。
+ */
+export const SITUATIONS_FROM_FACTS = [
+    'no-credential',
+    'fetch-failed',
+    'account-unavailable',
+    'stale',
+    'empty-wallet',
+    'ok',
+    'low',
+    'critical',
+];
+/** 宿主能产生的处境 = 事实判出来的 + 兜底视图那一个。 */
+export const HOST_SITUATIONS = [
+    'internal-error',
+    ...SITUATIONS_FROM_FACTS,
+];
+/** 客户端本地产生的处境（宿主不可能知道这两件事）。 */
+export const CLIENT_SITUATIONS = ['checking', 'offline'];
+/** 全部处境。 */
+export const SITUATIONS = [
+    ...CLIENT_SITUATIONS,
+    ...HOST_SITUATIONS,
+];
+/**
+ * 判定处境。**顺序即优先级**，第一个命中即返回。
+ *
+ * 三条刻意的优先级（都对旧写法做过修正）：
+ * 1. **没接入压过一切**：一条凭据都没有时，说「读不到余额」是误导 —— 用户没配过任何东西，
+ *    该说的是「尚未配置凭据」。判据是 `NO_KEY` **且没有快照**（有快照说明曾经读到过，
+ *    那就不是「没接入」，而是「这轮没读到」）。
+ * 2. **账户停用压过「数据过期」**：`isAvailable: false` 是上游明确给的事实，比「数字旧了」
+ *    更强的信号，且那种快照的余额通常是 0 —— 说「数据已过期」会把真问题藏起来。
+ * 3. **`stale` 的前提是「真的有一份旧数字」**（`hasSelected`）。快照在、但里面一个可展示的
+ *    币种都没有、这轮又没读到 —— 用户手里没有任何数字，说「数据已过期」是假话
+ *    （听着像「有旧数据可看」）。归 `fetch-failed`：读不到才是实话。
+ *
+ * **不变量（界面按它设计，测试钉着）**：
+ * - 返回 `stale` / `ok` / `low` / `critical` ⇒ **一定有可展示的币种**
+ *   （所以「有数字那一族」的颜色永远由真实阈值算出来，不会是 `unknown`）；
+ * - 返回 `account-unavailable` ⇒ `isAvailable` 一定是 `false`，颜色恒红。
+ *
+ * @param facts - 判定所需的六个事实。
+ * @returns 闭集内的处境。
+ */
+export function situationOf(facts) {
+    // ①② 没有快照：分清「没接入」与「接入了但读不到」。
+    if (!facts.hasSnapshot) {
+        return facts.errorCode === 'NO_KEY' ? 'no-credential' : 'fetch-failed';
+    }
+    // ③ 账户维度的事实压过新鲜度：停用比「数字旧」更该说。
+    if (!facts.isAvailable)
+        return 'account-unavailable';
+    // ④ 没有可展示的币种：分清「这轮没读到」与「账户本来就没有」。
+    //    前者说「读不到」才是实话 —— 用户手里一个数字都没有，没有「旧数据」可谈；
+    //    这也是「有数字那一族」颜色不会是 unknown 的结构保证（见上面不变量）。
+    if (!facts.hasSelected)
+        return facts.stale ? 'fetch-failed' : 'empty-wallet';
+    // ⑤ 有旧快照、也有数字，但本轮没读到：数字照常显示，文案说它旧。
+    if (facts.stale)
+        return 'stale';
+    // ⑥ 有数字，按阈值分档。`unavailable` / `unknown` 在上面已经被接走，
+    //    真漏到这里说明判定链有洞 —— 归到最保守的「读不到」，不假装正常。
+    if (facts.severity === 'unavailable' || facts.severity === 'unknown')
+        return 'fetch-failed';
+    if (facts.severity === 'critical')
+        return 'critical';
+    if (facts.severity === 'warn')
+        return 'low';
+    return 'ok';
+}
+//# sourceMappingURL=situation.js.map

package/lib/http/handlers.d.ts

@@ -34,7 +34,7 @@ export interface HttpDeps {
 }
 /** `GET /api/v1/balance`。**状态码始终 200**，业务错误走 `state` + `error`。 */
 export declare function handleBalance(request: Request, deps: HttpDeps): Promise<Response>;
-/** `POST /api/v1/balance/refresh`。请求体 `{ reason }`，可省略。 */
+/** `POST /api/v1/balance/refresh`。请求体 `{ reason, provider }`，都可省略。 */
 export declare function handleRefresh(request: Request, deps: HttpDeps): Promise<Response>;
 /** `GET /api/v1/config`。**掩码是手动的** —— 本响应自己构造，不走 settings 读取。 */
 export declare function handleConfigGet(_request: Request, deps: HttpDeps): Promise<Response>;

package/lib/http/handlers.js

@@ -10,6 +10,7 @@
  * @module dsh-ds-balance/http/handlers
  */
 import { classify, describeError } from '../domain/errors.js';
+import { situationOf } from '../domain/situation.js';
 import { CONFIG_FIELDS, endpointOf, validateThresholds } from '../config.js';
 import { PLUGIN_VERSION, SCHEMA_VERSION } from '../version.js';
 import { newRequestId, toWireBalanceView, toWireError, } from './wire.js';
@@ -48,15 +49,21 @@ async function readJsonObject(request) {
 }
 /**
  * 空视图：任何 handler 在彻底失败时都回它，保证响应形状仍然合法。
+ *
+ * 处境固定 `internal-error`：走到这里说明**我们自己的代码抛了**（装配错误之类），
+ * 那是「我们坏了」而不是「上游坏了」—— 两者在界面上是不同的处境，不能混。
  * @param requestId - 本次请求的标识。
  * @param error - 触发失败的异常。
  * @param state - 要报告的状态；余额端点固定 `error`。
+ * @param source - 当时活跃的来源；取不到就按 Key 那条报（界面只拿它选来源标签）。
  * @returns 契约 §8.3 的响应体。
  */
-function failureView(requestId, error, state = 'error') {
+function failureView(requestId, error, state = 'error', source = 'deepseek-http') {
     return {
         requestId,
         schemaVersion: SCHEMA_VERSION,
+        source,
+        situation: 'internal-error',
         state,
         stale: false,
         fetchedAt: 0,
@@ -92,7 +99,11 @@ export async function handleBalance(request, deps) {
     const requestId = newRequestId();
     try {
         const currency = queryParam(request, 'currency');
-        const view = await deps.service.getView(currency === null || currency === '' ? {} : { currency });
+        const providerHint = queryParam(request, 'provider');
+        const view = await deps.service.getView({
+            ...(currency === null || currency === '' ? {} : { currency }),
+            providerHint,
+        });
         return json(toWireBalanceView(view, deps.service.accountTag8() ?? '', requestId));
     }
     catch (error) {
@@ -100,17 +111,19 @@ export async function handleBalance(request, deps) {
             requestId,
             error: describeError(error),
         });
-        return json(failureView(requestId, error));
+        return json(failureView(requestId, error, 'error', deps.service.activeSource()));
     }
 }
-/** `POST /api/v1/balance/refresh`。请求体 `{ reason }`，可省略。 */
+/** `POST /api/v1/balance/refresh`。请求体 `{ reason, provider }`，都可省略。 */
 export async function handleRefresh(request, deps) {
     const requestId = newRequestId();
     try {
         const body = await readJsonObject(request);
         const rawReason = body?.reason;
         const reason = typeof rawReason === 'string' && rawReason !== '' ? rawReason : 'manual';
-        const result = await deps.service.forceRefresh(reason);
+        const rawProvider = body?.provider;
+        const providerHint = typeof rawProvider === 'string' ? rawProvider : null;
+        const result = await deps.service.forceRefresh(reason, providerHint);
         return json({ requestId, schemaVersion: SCHEMA_VERSION, ...result, error: null });
     }
     catch (error) {
@@ -294,7 +307,18 @@ export async function handleHealthz(_request, deps) {
         requestId,
         schemaVersion: SCHEMA_VERSION,
         version: PLUGIN_VERSION,
+        // 当前活跃来源：两条路并存时，这是唯一能一眼看出「现在服务的是哪条」的地方。
+        source: status.source,
         state: status.state,
+        /** 活跃账本此刻会画成什么 —— 不开浏览器也能知道界面长什么样。 */
+        situation: situationOf({
+            hasSnapshot: status.hasSnapshot,
+            stale: status.state === 'stale',
+            isAvailable: status.isAvailable,
+            hasSelected: status.hasSelected,
+            severity: status.severity,
+            errorCode: status.errorCode,
+        }),
         lastSuccessAt: status.lastSuccessAt,
         consecutiveFailures: status.consecutiveFailures,
         scheduler: { running: deps.scheduler.isRunning(), nextRunAt: deps.scheduler.nextRunAt() },

package/lib/http/wire.d.ts

@@ -5,8 +5,9 @@
  * `bigint` 最小单位只活在进程内。本模块是纯函数，不碰 `ctx`、不发请求。
  * @module dsh-ds-balance/http/wire
  */
-import type { BalanceView, CacheState, Currency, Severity } from '../domain/balance.js';
+import type { BalanceSource, BalanceView, CacheState, Currency, Severity } from '../domain/balance.js';
 import type { ErrorCode, ErrorInfo } from '../domain/errors.js';
+import type { Situation } from '../domain/situation.js';
 /** 一个币种的余额，金额是八位小数字符串。 */
 export interface WireBalance {
     currency: Currency;
@@ -46,6 +47,15 @@ export interface WireCredentialInfo {
 export interface WireBalanceResponse {
     requestId: string;
     schemaVersion: number;
+    /** 这一份数字是哪条取数路给的；界面据此在标题里标来源。 */
+    source: BalanceSource;
+    /**
+     * 处境：界面**唯一**的分支入口。
+     *
+     * 环 / 文案 / 来源标签都由它派生。`state` 与 `severity` 仍留在契约里（旧客户端要活），
+     * 但新界面不再读它们做形态判断 —— 见 [domain/situation.ts](../domain/situation.ts)。
+     */
+    situation: Situation;
     state: CacheState;
     stale: boolean;
     fetchedAt: number;

package/lib/http/wire.js

@@ -44,6 +44,8 @@ export function toWireBalanceView(view, accountTag8, requestId) {
     return {
         requestId,
         schemaVersion: SCHEMA_VERSION,
+        source: view.source,
+        situation: view.situation,
         state: view.state,
         stale: view.stale,
         fetchedAt: view.fetchedAt ?? 0,