timarai-dashboard-mcp 1.0.3

package/docs/CAPABILITIES.md

@@ -0,0 +1,275 @@
+# 能力详解：能查什么、能出什么报表、给谁用
+
+> 本文把 README 里的「三层能力 / 覆盖度」翻译成人话：
+> **每个工具查的是什么数据、每张图回答什么问题、每套报表给谁看、什么时候用**。
+> 面向使用者与接入方，不涉及服务内部实现。
+
+---
+
+## 0. 一句话定位
+
+驾驶舱接口返回的是**一串 JSON**；本服务把它变成**Agent 能直接交付的成品**——
+一个数字（查数据）、一张图（出图）、一份能打印的报表（出报表）。
+
+没有本服务时，Agent 拿到 JSON 只能自己数数、拼 Markdown 表格、还容易看错口径；
+有了本服务，Agent 说一句「财务周报给我一份」，就拿到一份 A4 可打印、图表内联、
+顶部标注了数据是否已封板的 HTML。
+
+---
+
+## 1. 给谁用：角色 → 关心什么 → 用什么
+
+| 角色 | 典型问题 | 走哪条路 | 产出 |
+|------|----------|----------|------|
+| **老板 / CEO** | 「上个月生意怎么样」「哪个业务线在赚钱」「大户集中度有多高」 | `ceo-briefing` 报表，或 `dashboard_overview(cabin="ceo")` | CEO 经营简报（8 KPI + 9 图）/ 一屏数字 |
+| **运营负责人** | 「成功率掉了是谁的锅」「昨天异常为什么多」「哪个渠道在拖后腿」 | `ops-anomaly-triage` 报表，或 `dashboard_breakdown(subject="fail_reason")` | 运营异常归因报告 / 失败原因构成 |
+| **财务负责人** | 「钱进来多少出去多少」「结算跟上没有」「对账差多少、差在谁」 | `finance-weekly-review` 报表，或 `dashboard_overview(cabin="finance")` | 财务周度复盘（8 图）/ 资金总览 |
+| **中台 / 助理** | 「每天早上给我一份昨天的经营情况」 | `daily-briefing` 报表 | 每日经营日报（三舱 KPI + 4 条趋势） |
+| **需要全貌的会议** | 「把三个舱全给我过一遍」 | `cockpit-full` 报表 | 全量快照（32 张图，一页式） |
+
+**共性**：三类角色都不用记路由名、不用记字段名，直接说人话。
+Agent 负责把问题翻译成工具调用，本服务负责取数、口径、成图。
+
+---
+
+## 2. 第一层：查数据（9 个工具）
+
+### 2.1 工具一览
+
+| 工具 | 查什么 | 什么时候用 | 返回 |
+|------|--------|-----------|------|
+| `dashboard_filters` | 平台有哪些业务线 / 商户 / 渠道 / 币种 / 账户类型 | **筛选前先调它**，拿到合法取值再过滤 | 选项清单（商户默认前 10 条，`keyword` 可按名搜索） |
+| `dashboard_overview` | 某一舱的汇总 KPI（`cabin`: ceo / operation / finance） | 「现在整体怎么样」 | 8 个指标 + 环比 |
+| `dashboard_trend` | 按天走势（`subject`: gmv / order / success_rate / exception / fund / balance / settlement） | 「最近走势如何」 | 日粒度序列 |
+| `dashboard_breakdown` | 维度构成与占比（`subject`: business / business_analysis / channel / fail_reason / fund_distribution / balance_distribution / reconciliation） | 「是谁在拖后腿 / 钱都在哪」 | 分组清单 |
+| `dashboard_top_merchants` | 排行榜（`subject`: gmv / exception / balance / reconciliation）；`topN` 取前 1~50 条，`page`+`pageSize` 翻页（响应带 `total`） | 「最集中的几家是谁」「总共有多少家」 | 商户排行 |
+| `dashboard_platform_metrics` | 运营宽表 21 项（商户生命周期、VA/U 卡账户、渠道活跃与异常等） | 「商户增长 / 流失 / 渠道健康」 | `latest` 快照 + `points` 序列 |
+| `call_endpoint` | 逃生阀：任意已注册路由 | 语义工具没覆盖到的边角需求 | 原始响应 |
+| `render_chart` | 见 §3 | 要单张图 | `.svg` 落盘 |
+| `build_report` | 见 §4 | 要成套报表 | `.html` 落盘 |
+
+> `dashboard_overview` 只给**总量**；要「走势」用 `trend`、要「构成」用 `breakdown`、
+> 要「谁最多」用 `top_merchants`、要「商户增长/流失」用 `platform_metrics`。
+> 这是最容易选错的地方：**overview 回答不了「为什么」**。
+
+### 2.2 23 条路由全表
+
+全部只读。按舱 + 查询形态排列，`subject` 列是对应工具要传的参数。
+
+**公共**
+
+| 路由 | 作用 |
+|------|------|
+| `filters` | 取三舱可用筛选项（业务线 / 商户 / 渠道 / 币种 / 账户类型） |
+
+**CEO 舱（经营大盘）**
+
+| 路由 | 作用 | 对应 subject |
+|------|------|-------------|
+| `ceo/overview` | GMV、成功交易笔数、平台收入、毛利、活跃/新增商户、成功率、AUM | `overview: ceo` |
+| `ceo/trend` | 关键指标按日趋势（GMV / 收入 / 利润 / AUM 可切换） | `trend: gmv` |
+| `ceo/business-breakdown` | 各业务线的 GMV / 收入 / 利润 / 订单数与占比 | `breakdown: business` |
+| `ceo/top-merchants` | GMV TOP 商户排行 | `top: gmv` |
+
+**运营舱（交易运行）**
+
+| 路由 | 作用 | 对应 subject |
+|------|------|-------------|
+| `operation/overview` | 订单总数、成功/失败/异常/处理中/退款、成功率、平均处理耗时 | `overview: operation` |
+| `operation/order-trend` | 按日订单量 | `trend: order` |
+| `operation/success-rate-trend` | 按日成功率 | `trend: success_rate` |
+| `operation/exception-trend` | 按日异常订单量 | `trend: exception` |
+| `operation/business-analysis` | 各业务线订单量与成功率 | `breakdown: business_analysis` |
+| `operation/channel-analysis` | 各渠道订单量、成功率与渠道成本 | `breakdown: channel` |
+| `operation/fail-reason-breakdown` | 失败原因构成（按编码聚合笔数/金额/占比） | `breakdown: fail_reason` |
+| `operation/top-exception-merchants` | TOP 异常商户排行 | `top: exception` |
+| `operation/platform-metrics` | 21 项平台宽表指标 | `dashboard_platform_metrics` |
+
+**财务舱（资金闭环）**
+
+| 路由 | 作用 | 对应 subject |
+|------|------|-------------|
+| `finance/overview` | 总资产、流入/流出、待结算、待对账、对账异常、冻结、可用余额 | `overview: finance` |
+| `finance/fund-trend` | 按日资金流入 / 流出 | `trend: fund` |
+| `finance/balance-trend` | 按日账户余额与冻结 | `trend: balance` |
+| `finance/settlement-trend` | 按日结算金额与成功结算金额 | `trend: settlement` |
+| `finance/fund-distribution` | 各业务的流入 vs 流出 | `breakdown: fund_distribution` |
+| `finance/balance-distribution` | 各账户类型的余额与冻结 | `breakdown: balance_distribution` |
+| `finance/reconciliation-analysis` | 对账结果分布（已匹配 / 待处理 / 异常 / 人工） | `breakdown: reconciliation` |
+| `finance/top-merchant-balances` | TOP 商户余额排行 | `top: balance` |
+| `finance/top-reconciliation-merchants` | TOP 对账异常商户排行 | `top: reconciliation` |
+
+### 2.3 运营宽表的 21 项指标（分组）
+
+`operation/platform-metrics` 是运营舱唯一返回序列 + 快照的宽表，分七组：
+
+| 组 | 指标 | 用来回答 |
+|----|------|----------|
+| 商户生命周期 | 新增 / 首次成交激活 / 活跃 / 沉默 / 流失 / 不活跃 | 增长是「拉新」还是「唤醒」？存量在流失吗？ |
+| VA 账户 | VA 主账户、子账户 | VA 业务铺开了没有 |
+| U 卡 | U 卡账户与卡量 | 卡业务规模 |
+| 商户账户 | 商户账户数 | 开户转化 |
+| 卡 | 发卡与活跃 | 卡的实际使用 |
+| 结算 | 结算相关计数 | 结算是否跟上交易 |
+| 渠道 | 渠道活跃与异常 | 哪家渠道在出问题 |
+
+> 21 项的具体字段名以接口返回为准（`dashboard_platform_metrics` 会同时给出
+> `latest` 末日快照与 `points` 逐日序列）。预置图 `ops.merchant_growth` 已固化其中三条：
+> 新增 / 激活 / 活跃商户逐日走势。
+
+---
+
+## 3. 第二层：出图（39 张预置图，对应 `render_chart`）
+
+**为什么是「预置」而不是让 Agent 自由拼**：图形类型和字段一旦交给模型临时决定，
+就会出现「把成功率画成堆叠柱」这种错误，而且每次都要重新试探字段。
+这里把「图 → 路由 → 字段 → 单位」固化成 39 个 spec，Agent 只要点名要哪张图
+（`timarai://dashboard/charts` 可查全部 id）。
+
+### CEO 舱 · 17 张
+
+| id | 图 | 回答什么问题 |
+|----|----|-------------|
+| `ceo.kpi` | KPI 卡 ×8 | GMV、交易笔数、营业收入、毛利、活跃/新增商户、成功率、AUM（含环比） |
+| `ceo.gmv_trend` | 折线 | 每天做了多少 GMV（默认近 30 天） |
+| `ceo.revenue_trend` | 折线 | 每天收了多少手续费 |
+| `ceo.profit_trend` | 折线 | 每天赚多少毛利（**可能为负**） |
+| `ceo.aum_trend` | 折线 | 平台托管资产规模走势 |
+| `ceo.transaction_count_trend` | 折线 | 每天成功交易多少笔——配合 GMV 判断增长来自「单笔变大」还是「笔数变多」 |
+| `ceo.success_rate_trend` | 折线 | 每天整体成功率。**掉点通常先于 GMV 下滑出现**，是最早的告警信号 |
+| `ceo.active_merchant_trend` | 折线 | 每天多少商户在活跃，判断活跃度是扩张还是靠少数大户撑着 |
+| `ceo.new_merchant_trend` | 折线 | 每天新增多少商户，衡量获客节奏（非金额指标，不受币种影响） |
+| `ceo.business_gmv` | 柱状 | 哪条业务线 GMV 最大 |
+| `ceo.business_revenue` | 柱状 | 哪条业务线最赚钱（收入口径） |
+| `ceo.business_profit` | 柱状 | 哪条业务线毛利最高 / 在亏钱 |
+| `ceo.business_share` | 环形 | 业务线的 GMV 占比结构 |
+| `ceo.business_share_revenue` | 环形 | 同上，收入口径 |
+| `ceo.business_share_profit` | 环形 | 同上，利润口径（有负值时改用柱状） |
+| `ceo.business_share_orders` | 环形 | 同上，订单数口径 |
+| `ceo.top_merchants` | 横向条形 | GMV 前十商户是谁，头部集中度多高 |
+
+### 运营舱 · 11 张
+
+| id | 图 | 回答什么问题 |
+|----|----|-------------|
+| `ops.kpi` | KPI 卡 ×8 | 订单数、成功/失败/成功率/异常/处理中/退款、平均耗时（含环比） |
+| `ops.order_trend` | 折线 | 每天多少笔单（**只有笔数，不含金额**） |
+| `ops.success_rate_trend` | 折线 | 成功率有没有掉 |
+| `ops.exception_trend` | 折线 | 异常什么时候突然变多 |
+| `ops.business_orders` | 柱状 | 各业务线订单量对比 |
+| `ops.business_success_rate` | 柱状 | 哪条业务线成功率最低 |
+| `ops.channel_orders` | 柱状 | 各渠道跑了多少单 |
+| `ops.channel_success_rate` | 柱状 | 哪个渠道质量差（配合渠道成本看路由质量） |
+| `ops.fail_reason` | 环形 | 失败主要卡在哪个原因 |
+| `ops.top_exception_merchants` | 横向条形 | 异常是个别商户的问题还是普遍问题 |
+| `ops.merchant_growth` | 折线（3 线） | 新增 / 激活 / 活跃商户走势，看增长质量 |
+
+### 财务舱 · 11 张
+
+| id | 图 | 回答什么问题 |
+|----|----|-------------|
+| `fin.kpi` | KPI 卡 ×8 | 总资产、流入、流出、待结算、待对账、对账异常、冻结、可用余额 |
+| `fin.fund_trend` | 折线（双线） | 每天进多少、出多少，资金拐点在哪 |
+| `fin.balance_trend` | 折线（双线） | 余额走势；副线是**冻结资金**，不是流出 |
+| `fin.settlement_trend` | 折线（双线） | 结算金额 vs 成功结算金额，节奏与达成率 |
+| `fin.settlement_combo` | 组合（柱+线） | 同上，柱看规模、线看达成 |
+| `fin.fund_distribution` | 柱状（分组） | 各业务的**流入 vs 流出**（不是「资金规模」） |
+| `fin.balance_distribution` | 柱状（分组） | 各账户类型的余额与冻结 |
+| `fin.balance_share` | 环形 | 钱在各账户类型里怎么分布 |
+| `fin.reconciliation` | 环形 | 对账结果构成（已匹配 / 待处理 / 异常 / 人工） |
+| `fin.top_merchant_balances` | 横向条形 | 钱集中在哪几家（集中度风险） |
+| `fin.top_reconciliation_merchants` | 横向条形 | 对账异常金额集中在哪几家 |
+
+---
+
+## 4. 第三层：出报表（5 套模板，对应 `build_report`）
+
+图表顺序统一按 **总量 → 趋势 → 结构 → 集中度** 排列，这是经营分析通用的阅读路径。
+`narrative` 参数由 Agent 注入结论段落（**必须是字符串数组**）——
+工具负责数据与图形，模型负责说人话。
+
+| 模板 | 给谁 | 什么时候用 | 默认窗口 | 含几张图 |
+|------|------|-----------|---------|---------|
+| `ceo-briefing` | CEO / 老板 | 月度或周度经营简报 | 近 30 天 | 10（8 KPI 卡算 1） |
+| `finance-weekly-review` | 财务负责人 | 每周资金复盘 | 近 7 天 | 8 |
+| `ops-anomaly-triage` | 运营负责人 | 成功率/异常出问题时的归因 | 近 7 天 | 6 |
+| `daily-briefing` | 全员 / 中台 | 每天固定看一眼 | 昨天 | 7 |
+| `cockpit-full` | 管理层会议 | 三舱全量过一遍 | 近 7 天 | 32 |
+
+### `ceo-briefing` · CEO 经营简报
+CEO KPI 卡 → GMV / 收入 / 利润 / AUM 四条趋势 → 业务线 GMV / 收入 / 利润三张柱 →
+业务占比环 → GMV TOP10 商户。
+
+**看什么**：增长是否来自真实交易（GMV 与收入同步增长，而非补贴堆量）；
+哪条业务线贡献最大；头部商户集中度是否过高。
+
+### `finance-weekly-review` · 财务周度复盘
+财务 KPI 卡 → 资金流趋势 → 余额趋势 → 结算趋势 → 业务资金分布 →
+对账结果 → 余额 TOP10 → 对账异常 TOP10。
+
+**看什么**：净流入是否为正；待结算与待对账有没有堆积；异常集中在哪几家，谁该先跟进。
+
+### `ops-anomaly-triage` · 运营异常归因
+运营 KPI 卡 → 异常趋势 → 失败原因构成 → 渠道成功率 → 业务成功率 → 异常 TOP10 商户。
+
+**看什么**：按「先确认异常量、再看失败结构、再定位渠道与业务、最后落到具体商户」
+的顺序归因——是个别商户的问题，还是某个渠道/业务线的系统性问题。
+
+### `daily-briefing` · 每日经营日报
+三舱 KPI 卡 → GMV 趋势 → 订单趋势 → 成功率趋势 → 资金流趋势。
+
+**看什么**：只看总量和四条核心线，一分钟看完昨天的经营情况。
+
+### `cockpit-full` · 全量快照
+三舱 KPI + 全部主图，一页式，最接近需求文档里的驾驶舱页面形态（32 张）。
+适合周会、月会投屏，或作为「把三个舱全过一遍」的底稿。
+
+---
+
+## 5. 典型问题 → 调用链路
+
+| 你说 | Agent 会调 | 你拿到 |
+|------|-----------|--------|
+| 「上个月生意怎么样」 | `dashboard_overview(cabin="ceo", preset="last_month")` | 8 个指标 + 环比 |
+| 「GMV 最近走势」 | `dashboard_trend(subject="gmv", preset="last_30d")` | 按天序列 |
+| 「出一份 CEO 简报」 | `build_report(template="ceo-briefing")` | 可打印 HTML（Ctrl+P 出 PDF） |
+| 「成功率为什么掉了」 | `dashboard_breakdown(subject="fail_reason")` → `dashboard_breakdown(subject="channel")` → `dashboard_top_merchants(subject="exception")` | 失败原因 → 渠道 → 具体商户 |
+| 「钱都在哪几家」 | `dashboard_top_merchants(subject="balance", topN=20)` | 余额 TOP20 |
+| 「对账差多少」 | `dashboard_breakdown(subject="reconciliation")` → `dashboard_top_merchants(subject="reconciliation")` | 对账构成 + 异常商户 |
+| 「商户在流失吗」 | `dashboard_platform_metrics(preset="last_30d")` | 生命周期宽表（含沉默/流失） |
+| 「把运营异常归因做成报告」 | `build_report(template="ops-anomaly-triage")` | 归因报告 HTML |
+
+---
+
+## 6. 用之前要知道的七条口径纪律
+
+1. **未封板数据不能直接对外**：响应 `meta.isFinal=false` 时数字还会被修正，
+   报表顶部会强制挂红条提示。出正式财报前必须确认。
+   ——注意**查询窗口含今天时它必然是 `false`**（当日不封板），这是正常表现不是故障；
+   要终值就查纯历史窗口。
+2. **跨币种金额不可相加**：每个数值旁的 `currency` 说明它是什么钱——
+   只有显示具体币种码（如 `USDT`）才能合计；要算合计就用 `currencies` 指定单一币种重查。
+   2026-09-21 第九轮之后，**所有金额路由的每一行都带 `currency`**，不用再猜：
+   - `ceo/overview` 是唯一还会出现 `currency=MIXED` 的地方，它代表「**已拆分**」——
+     金额标量为 `null`、明细在 `amountsByCurrency`（数组），**不是数据缺失**；
+   - 其余路由会**按币种各占一行**：同一商户在 USD / USDT 下出现两行是正常拆行，
+     `rank` 在币种内重新编号；本 MCP 会在输出里显式说明，不要当成重复数据去重；
+   - `TransactionCount` 等计数指标：相加本来就是对的。
+   `share` 已是**全局占比**（各项之和为 1），可以直接排序比较。
+3. **币种清单已覆盖实际币种**：`dashboard_filters` 的清单现在是「字典配置 ∪ 日表去重」，
+   实测含 EUR；「按清单逐个币种查再相加」已能还原不筛选的合计。
+   这一结论由 e2e 的覆盖度探针持续盯住——清单若再缺币种，差额会被打在测试结果里。
+4. **GMV 是成功订单金额口径**，退款单独统计、不冲减 GMV；
+   它与 `transactionCount`（成功笔数）同口径但量纲不同，不可互推。
+5. **缺失 ≠ 零**：区间里没有统计产出的日期不会补 0，而是整日不出现，
+   同时列在 `meta.missingDates`。曲线断了一截要说「那几天无统计产出」，
+   **不要**说「跌到 0 了」——反过来，数据里出现的 0 才是真的零。
+6. **`successRate` 才是成功率**：历史上它被塞在 `share` 里，两者现已拆开，
+   `share` 回归「占比/构成比」的语义。
+7. **商户列表一次只给前 10 条**：要按商户过滤，先用 `dashboard_filters(keyword=...)`
+   搜出 ID——**前 10 条里没有，不代表该商户不存在**；
+   `dashboard_top_merchants` 同理，`total` 才是总家数。
+
+> 字段口径多处与直觉相反：例如 `operation/order-trend` 的 `value` 是**笔数**不是金额，
+> `finance/fund-distribution` 的 `value/secondaryValue` 是**流入/流出**不是资金规模。
+> 完整口径字典由 `timarai://dashboard/field-glossary` 资源提供，Agent 取数时可自查。

package/docs/CONTRACT.md

@@ -0,0 +1,170 @@
+# 契约规范
+
+接口侧与调用方**共同遵守**的约定，以及金额形态的统一路线。
+问题跟踪与逐轮复测记录不在本仓库（服务端待办不入库），见桌面
+《驾驶舱API前后端协作规范.md》。
+
+条款排序依据是**会不会让调用方输出错误结论**，不是实现难度。
+每条都配了可执行判据——没有判据的规范只是口号。
+
+---
+
+## 1. 值必须自描述
+
+任何金额数值必须能自证自己是什么钱，跨币种不得硬加总。
+
+- 金额字段旁必须有 `currency`：具体币种码（可相加）/ `MIXED`（多币种）/ `null`（非金额）
+- 多币种且未指定 `currencies` 时**按币种拆行**，不要按原值相加
+- `MIXED` 若保留，必须是"已拆分"语义（标量 `null` + 明细），不能是被相加过的数
+
+**违反后果**：USD 与 USDT 被当作同一单位累加，排行榜的**名次本身**就是错的。
+
+**判据**：`npm run e2e` 中「行级不得再出现 `MIXED`」「排行类不筛选 == 各币种分别查询之和」
+
+## 2. 禁止静默失败
+
+不支持 / 未实现的参数必须明确拒绝（4xx），**不得静默忽略**。
+
+**违反后果**：调用方以为筛选生效了，拿到的是全量。不报错、不报警，
+唯一症状是"数字看着有点大"——最贵的一类问题。
+
+**判据**：「非排行路由传 `pageSize` 必须 400」「`granularity=hour` 必须 400」
+
+## 3. 结果集边界可见
+
+- 分页必须返回 `total`
+- 区间内无统计产出的日期整日不出现 + 列在 `meta.missingDates`，有产出的列在 `coveredDates`
+- `meta.dataAsOf` 为 `null` 表示本区间无任何统计产出
+
+**违反后果**："缺失"被读成"跌到 0"，曲线断一截被当成断崖。
+
+**判据**：「翻页返回 `total`」「`missingDates` 标注正常」
+
+## 4. 缓存可观测
+
+命中缓存时 `meta.cached` / `meta.cacheAgeMs` 必须可见。
+
+**违反后果**：分不清"数据没变"和"拿到的是 30 秒前的副本"，
+也无法判断一次慢请求是冷路径还是真实退化。
+
+**判据**：「命中缓存时 `meta.cached` 可见」
+
+## 5. 错误真实且脱敏
+
+HTTP 状态码必须真实；错误文案不含内部细节（表名、SQL、堆栈、连接串）。
+
+- 4xx = 参数问题，用原参数重试必然再失败
+- 5xx = 服务端问题，可退避重试
+
+**违反后果**：状态码恒 200 会让调用方的 5xx 退避**从未生效**；脱敏不全等于暴露库结构。
+
+**判据**：`npm run live-check` 中「错 Secret 必须 401」「缺 Header 必须 400」
+
+## 6. 变更提前通报
+
+返回形态变更（字段新增 / 删除 / 改名 / 语义变化 / 值域变化）须在**部署前**同步一句。
+
+> ⚠️ **「某个字段开始有值了」和「某个字段没了」同等重要。**
+> 调用方常把"当前缺什么"写死成名单（本仓库就写死过「6 条路由没有 currency」）。
+> 接口侧补齐后，这类名单**不报错、只会开始说假话**——比漏报更伤，
+> 因为 Agent 会学着以后忽略警告。
+
+**违反后果**：2026-09-20 第六轮把金额趋势改成「日 × 币种」、`overview` 标量改 `null`，
+两边都没做错事，结果是下游折线锯齿、KPI 卡整排显示 0。
+
+**判据**：这条靠流程，无自动断言。§4 的发版门禁是兜底——
+**即使忘了通报，发布前跑一次也能在灰度环境发现。**
+
+---
+
+## 附：已确认的行为约定（不是 bug，改动须通报）
+
+接口侧于 2026-09-21 明确答复，双方记录在此，避免日后被当成缺陷反复提。
+
+| 行为 | 约定 | 说明 |
+|------|------|------|
+| `topN` | **按币种拆行之后**的全局截断。`topN=1` = 整表只留 1 行，**不是**「每币种各 1 条」 | 需要「每币种 TopN」须另开参数（如 `perCurrencyTopN`），当前没有。用 `topN` 前先决定要不要传 `currencies` |
+| `isStale` | 判定基准是 **`lastRefreshTime`**：`UtcNow - lastRefreshTime > 5min`，**不是 `dataAsOf`** | 与「统计产出滞后」是两种滞后，可同时为真也可只有一个为真。测试环境刷新任务不常驻，恒 `true` 是预期 |
+| `metricType` 空白容错 | 接受前后空格，`"gmv "` trim 后匹配 `GMV` | 这是**合法枚举的空白容错**，与「字段名写错严格 400」不冲突——两者都对，都不要改 |
+
+> **为什么这三条也要写成断言**：约定写在文档里不会自己报警。
+> 只有变成 `npm run e2e` 里的断言，「改了却没通报」才会在发版前显形——
+> 这正是 §6 那条「通报」规范的兜底形态。
+
+---
+
+## 金额形态的统一路线
+
+### 现状（v1）：拆行 + `currency`
+
+已铺到全部金额路由，与已上线的 trend / breakdown 一致。
+**形态一致比形态优雅重要**——这条取舍双方认同。
+
+```
+items: [
+  { merchantName: "summer7", currency: "USD",  value: 125585.52, rank: 1 },
+  { merchantName: "summer7", currency: "USDT", value: 125585.52, rank: 1 },
+]
+```
+
+已知代价：同一主体占多行。本仓库已在输出里显式说明"各占一行、不是重复数据"。
+
+### 目标（v2）：统一 `money` 信封
+
+接口侧原则同意、单独排期；本轮不做（避免再一次无通报的 breaking 改形）。
+
+```jsonc
+"gmv": {
+  "amount": null,          // 多币种且未指定时为 null —— 不猜测、不硬加
+  "currency": "MIXED",     // 或具体币种码
+  "amountsByCurrency": [   // 始终列出全部出现过的币种（含字典清单外的）
+    { "currency": "USD",  "amount": 1398096 },
+    { "currency": "USDT", "amount": 547155 }
+  ]
+}
+```
+
+1. 单币种 → `amount` 有值，`currency` 是币种码
+2. 多币种 → `amount` 为 `null`，`currency` 为 `MIXED`，明细在 `amountsByCurrency`
+3. `amountsByCurrency` **始终包含全部实际出现的币种**，不受字典配置限制
+
+这条能一次性解决排行类加总、分布类 `MIXED`，
+以及**以后新增的每一条金额路由**——这是它相对"按路由打补丁"的根本优势。
+
+### 迁移策略
+
+| 阶段 | 动作 |
+|------|------|
+| 现在 | v1 保持不变。存量不迁移——正确性已拿到，全线切是双边 breaking，收益不匹配风险 |
+| 新增 | 新增金额路由一律用 v2；规则 3 建议现在就对 v1 生效（成本最低、独立收益最大） |
+| 切换 | 若接口侧全线切：给切换窗口 + 提前通报，本仓库同步改解析并加双形态兼容 |
+
+完成判据：所有金额字段符合 `MoneyValue`，
+e2e 中「行级无 `MIXED`」改写为「**无裸数字金额**」。
+
+---
+
+## 发版门禁
+
+```bash
+cd E:\项目\TimarAI-Dashboard-MCP
+npm run e2e -- --base=https://<待发布环境>     # 81 项，约 3 分钟，全部只读
+npm run live-check -- --base=<环境>            # HTTP 鉴权契约 7 项
+```
+
+23 条路由全是只读，复用现有凭证即可；建议单独开一组门禁专用只读 key / secret。
+**不在群里或文档里贴明文。**
+
+---
+
+## 变更历史
+
+| 时间 | 内容 |
+|------|------|
+| 2026-09-21 15:00 | 接口侧修复「filters 清单含 EUR」「6 条金额路由按币种拆行」「分布类 `currency=USD`」「share 全量和 = 1」四项。本仓库同步假警报、拆行说明、字段字典 |
+| 2026-09-21 14:59 | 接口侧回复：协作建议 4 条采纳 3 条半（门禁 / 变更通报 / 字典兜底采纳，`money` 信封单独排期） |
+| 2026-09-21 13:20 | 发现 P0「filters 币种清单不含实际交易币种（EUR）」；本仓库修复多币种下环形 / 柱状图画错 |
+| 2026-09-20 | 第六轮：金额趋势改「日 × 币种」、`overview` 标量改 `null`。无通报，导致下游坏图 |
+
+8 轮累计 23 条问题：静默失败 6 · 值不自描述 9 · 缺元信息 5 · 真正的功能缺口 / 性能 3。
+**87% 不是"功能没做"，是"做了但没说清楚"。**