dsh-plugin-show-me-data 0.1.0

package/docs/03-data-contracts.md

@@ -0,0 +1,291 @@
+# 03 · 数据契约与指标目录
+
+所有跨模块的类型都在这里定死。实现时**这些形状不得随意改动**；确需变更走 `11-decisions.md` 追加 ADR。
+
+---
+
+## 1. 基础类型
+
+### 1.1 `SourceRef`（溯源单元，强制出现在每个数值上）
+
+```js
+/** @typedef {Object} SourceRef
+ *  @property {string} adapterId    // 'fred'
+ *  @property {string} seriesRef    // 'PAYEMS' | '1.000012' | 'RPT_ECONOMY_CPI'
+ *  @property {string} url          // 人类可点开的原始地址（必须真实可达）
+ *  @property {string} label        // 'FRED' | '东方财富' | '美国财政部'
+ *  @property {string} [apiUrl]     // 机器可读的取数地址（便于复现）
+ */
+```
+
+### 1.2 `IndicatorDef`（指标定义 = 纯数据）
+
+```js
+/** @typedef {Object} IndicatorDef
+ *  @property {string} id                   // 'us.cpi.yoy'，全局唯一，点分命名
+ *  @property {'US'|'CN'|'GLOBAL'|'CUSTOM'} group
+ *  @property {{zh: string, en: string}} label
+ *  @property {string} unit                 // '%' | 'pp' | '点' | '万人' | '亿元' | '指数'
+ *  @property {'daily'|'weekly'|'monthly'|'quarterly'|'annual'} freq
+ *  @property {'SA'|'NSA'|'NA'} seasonal
+ *  @property {1|2|3|4|5} importance        // 5 = 最核心（首页默认展示）
+ *  @property {SourceBinding} source        // 取数绑定
+ *  @property {DisplaySpec} display         // 展示变换
+ *  @property {{zh: string, en?: string}} [notes]  // 供 AI 与 tooltip 使用的口径说明
+ *  @property {string[]} [tags]             // 'inflation','rates','labor','equity','bond'
+ */
+/** @typedef {Object} SourceBinding
+ *  @property {string} adapter              // 注册表里的 adapterId
+ *  @property {string} seriesRef            // 上游系列 ID / secid / reportName
+ *  @property {Object} [params]             // 例如 { klt: 101, fqt: 1 } 或 { column: 'NATIONAL_SAME' }
+ */
+/** @typedef {Object} DisplaySpec
+ *  @property {'raw'|'diff'|'pctChange'|'yoy'|'mom'|'annualize'|'ratio'} transform
+ *  @property {number} [window]             // 派生窗口（如 diff 的月数）
+ *  @property {number} [decimals]
+ *  @property {'up-is-good'|'down-is-good'|'neutral'} [polarity]  // 影响颜色与规则措辞
+ */
+```
+
+### 1.3 `RawSeries`（适配器唯一输出）
+
+```js
+/** @typedef {Object} RawSeries
+ *  @property {string} adapterId
+ *  @property {string} seriesRef
+ *  @property {{t: string, v: number}[]} points   // t = 'YYYY-MM-DD'；缺失点不得填 0，直接跳过
+ *  @property {Object} meta
+ *  @property {string} meta.name             // 上游给的名称（人类可读）
+ *  @property {string} [meta.unit]           // 上游若有则带上
+ *  @property {string} [meta.freq]
+ *  @property {string} fetchedAt             // ISO 时间（来自注入的 Clock）
+ *  @property {SourceRef} sourceRef
+ *  @property {Object} [raw]                 // 仅供调试与 fixture 对比，不参与业务
+ */
+```
+
+### 1.4 `SeriesView`（`app/series-view.js` 的输出）
+
+```js
+/** @typedef {Object} SeriesView
+ *  @property {string} indicatorId
+ *  @property {Range} range
+ *  @property {{t: string, v: number}[]} points        // 已排序、去重、按范围过滤
+ *  @property {SeriesStats} stats
+ *  @property {SourceRef} sourceRef
+ *  @property {'fresh'|'stale'|'error'|'missing'} status
+ *  @property {string} [lastSuccessAt]
+ *  @property {string} [errorKind]
+ */
+/** @typedef {Object} SeriesStats
+ *  @property {number} latest  @property {string} latestAt
+ *  @property {number} [prev]  @property {number} [changeAbs]  @property {number} [changePct]
+ *  @property {number} [yoy]   @property {number} [mom]
+ *  @property {number} mean  @property {number} min  @property {number} max
+ *  @property {number} stdDev  @property {number} [zScoreLatestChange]
+ *  @property {number} [slope]                        // 最小二乘斜率（每期）
+ *  @property {number} [percentile]                   // 最新值在区间内的分位（0–1）
+ *  @property {number} missingCount
+ */
+```
+
+### 1.5 `Metric`（卡片）与 `Noteworthy`（值得关注项）
+
+```js
+/** @typedef {Object} Metric
+ *  @property {string} indicatorId
+ *  @property {{zh: string, en: string}} label
+ *  @property {string} unit
+ *  @property {number} latest   @property {string} latestAt
+ *  @property {number} [changeAbs]  @property {number} [changePct]
+ *  @property {number[]} sparkline              // 归一化后的点（供 SVG 直接画）
+ *  @property {'fresh'|'stale'|'error'|'missing'} status
+ *  @property {SourceRef} sourceRef
+ *  @property {Hit[]} hits                      // 命中的规则（可为空）
+ *  @property {number} score                    // 0–100，排序用
+ */
+/** @typedef {Object} Hit
+ *  @property {string} ruleId
+ *  @property {number} score
+ *  @property {{zh: string, en?: string}} reason
+ *  @property {Object} evidence                 // 结构化证据：{ value, threshold, window, dates[] }
+ */
+```
+
+### 1.6 `Range`
+
+```js
+/** @typedef {Object} Range
+ *  @property {'1M'|'3M'|'6M'|'YTD'|'1Y'|'3Y'|'5Y'|'MAX'|'CUSTOM'} preset
+ *  @property {string} from   // 'YYYY-MM-DD'
+ *  @property {string} to     // 'YYYY-MM-DD'
+ */
+```
+
+`resolveRange(preset, today)` 是 `core/time/range.js` 的纯函数：给定 `today` 返回 `from`/`to`，
+**不读系统时间**（时间由注入的 `Clock` 提供），因此可以精确单测跨年、闰年、YTD 边界。
+
+### 1.7 错误与状态
+
+```js
+/** @typedef {Object} SourceError
+ *  @property {'network'|'http'|'parse'|'empty'|'unsupported'} kind
+ *  @property {string} adapterId
+ *  @property {string} seriesRef
+ *  @property {string} detail
+ *  @property {number} [httpStatus]
+ *  @property {boolean} retryable
+ */
+```
+
+状态语义（UI 与 AI 都依赖它）：
+
+| status | 含义 | UI |
+| --- | --- | --- |
+| `fresh` | 成功取数且在频率容差内 | 正常 |
+| `stale` | 取数失败但有历史快照，或最后观测日超容差 | 黄点 + 「最后成功 …」 |
+| `missing` | 上游成功但没有该范围的数据点 | 灰卡 + 说明 |
+| `error` | 取数失败且无快照 | 红卡 + 重试按钮 |
+
+---
+
+## 2. 归一化与派生规则（`core/stats`）
+
+这些规则会被逐条单测，实现时**先写测试再写实现**。
+
+1. **排序与去重**：按 `t` 升序；同一 `t` 出现多次时**保留最后一个**（上游修正值优先）。
+2. **缺失处理**：FRED 的 `"."`、空串、`"null"`、`"N/A"`、`"-"` 一律视为缺失 → 跳过，不填 0、不插值。
+3. **同比（yoy）**：与**去年同月**比较；月频按 `t` 减 12 个月，季频减 4 个季度；用「同月对齐」而非「往前数 N 个点」，
+   缺失时允许 ±1 个月的容差匹配，并在 `stats` 里记 `yoyAlignedDrift`。
+4. **环比（mom）**：与上一个已存在观测比较（不跳缺口），返回 `changeAbs` 与 `changePct`。
+5. **diff transform**（如非农）：`v[i] - v[i-1]`，用于水平值序列；窗口版为 `window` 期和差。
+6. **pctChange / yoy transform**：以百分比为单位输出（`3.4` 表示 3.4%），**不要输出 0.034**。
+7. **年化（annualize）**：仅对季频（×4）与月频（×12）的水平值允许，且必须在 `unit` 上标注 `(年化)`。
+8. **标准差 / z 分数**：样本标准差（n−1）；`zScoreLatestChange` 用「最近一次变化」对「同窗口历史变化」标准化；
+   **样本数 < 6 时该字段返回 `undefined`**（避免用 3 个点编出"2σ"）。
+9. **分位**：线性插值分位；样本 < 12 时返回 `undefined`。
+10. **斜率**：最小二乘对 `(i, v)` 拟合，单位「每期」；指数型序列（指数/点位）同时给出 `slopeRel = slope / mean`。
+11. **派生序列**（`core/stats/derive.js`）：`spread(a,b)` = 按日期**内连接**后相减；`ratio(a,b)` 同理；
+    内连接后剩余点数 < 3 时返回空并附 `reason: 'insufficient-overlap'`。
+12. **交易日近似**：不引入交易日历库。日频序列的「最近 N 个交易日」= 上游实际返回的最后 N 个观测，
+     **不要**用自然日推算交易日。
+
+---
+
+## 3. 种子指标目录（seriesRef 均为**实测可返回数据**）
+
+> 探测时间：本次会话。`fredgraph.csv` **无需 API key**，是本方案的取数主干。
+
+### 3.1 美国（FRED，`adapter: 'fred'`）
+
+| id | 名称 | seriesRef | 频率 | 单位 | display.transform |
+| --- | --- | --- | --- | --- | --- |
+| `us.cpi` | 美国 CPI 指数 | `CPIAUCSL` | monthly | 指数 | `raw`（同比见下） |
+| `us.cpi.yoy` | 美国 CPI 同比 | `CPIAUCSL` | monthly | % | `yoy` |
+| `us.core.cpi.yoy` | 美国核心 CPI 同比 | `CPILFESL` | monthly | % | `yoy` |
+| `us.pce.index` | 美国 PCE 物价指数 | `PCEPI` | monthly | 指数 | `raw` |
+| `us.pce.yoy` | 美国 PCE 同比 | `PCEPI` | monthly | % | `yoy` |
+| `us.unrate` | 美国失业率 | `UNRATE` | monthly | % | `raw` |
+| `us.payrolls.level` | 美国非农就业（水平） | `PAYEMS` | monthly | 万人 | `raw` |
+| `us.payrolls.change` | 美国非农就业（月增） | `PAYEMS` | monthly | 万人 | `diff` |
+| `us.fedfunds.monthly` | 联邦基金利率（月均） | `FEDFUNDS` | monthly | % | `raw` |
+| `us.fedfunds.daily` | 联邦基金利率（日度） | `DFF` | daily | % | `raw` |
+| `us.dgs10` | 美国 10Y 国债收益率 | `DGS10` | daily | % | `raw` |
+| `us.dgs2` | 美国 2Y 国债收益率 | `DGS2` | daily | % | `raw` |
+| `us.dgs3m` | 美国 3M 国债收益率 | `DGS3MO` | daily | % | `raw` |
+| `us.curve.10y2y` | 10Y−2Y 利差 | `T10Y2Y` | daily | pp | `raw` |
+| `us.breakeven10y` | 10Y 通胀预期 | `T10YIE` | daily | % | `raw` |
+| `us.gdp.real` | 美国实际 GDP | `GDPC1` | quarterly | 十亿美元 | `raw` |
+| `us.retail.sales` | 美国零售销售 | `RSAFS` | monthly | 百万美元 | `raw` |
+| `us.consumer.sentiment` | 密歇根消费者信心 | `UMCSENT` | monthly | 指数 | `raw` |
+| `us.mortgage30` | 30 年期房贷利率 | `MORTGAGE30US` | weekly | % | `raw` |
+| `us.dollar.index` | 美元指数（广义） | `DTWEXBGS` | daily | 指数 | `raw` |
+| `us.oil.wti` | WTI 原油 | `DCOILWTICO` | daily | 美元/桶 | `raw` |
+
+> `GDPC1` 返回的是**全历史**（1947 起），适配器必须支持 `cosd`（起始日）参数以避免拉全量。
+
+### 3.2 中国（东方财富，`adapter: 'eastmoney-macro'`）
+
+| id | 名称 | seriesRef（reportName） | 列（params.column） | 频率 | 单位 |
+| --- | --- | --- | --- | --- | --- |
+| `cn.cpi.yoy` | 中国 CPI 同比 | `RPT_ECONOMY_CPI` | `NATIONAL_SAME` | monthly | % |
+| `cn.cpi.mom` | 中国 CPI 环比 | `RPT_ECONOMY_CPI` | `NATIONAL_SEQUENTIAL` | monthly | % |
+| `cn.ppi.yoy` | 中国 PPI 同比 | `RPT_ECONOMY_PPI` | `BASE_SAME` | monthly | % |
+| `cn.pmi.mfg` | 中国制造业 PMI | `RPT_ECONOMY_PMI` | `MAKE_INDEX` | monthly | 指数（荣枯线 50） |
+| `cn.pmi.nonmfg` | 中国非制造业 PMI | `RPT_ECONOMY_PMI` | `NMAKE_INDEX` | monthly | 指数 |
+| `cn.gdp.yoy` | 中国 GDP 同比 | `RPT_ECONOMY_GDP` | `SUM_SAME` | quarterly | % |
+| `cn.gdp.level` | 中国 GDP 现价累计 | `RPT_ECONOMY_GDP` | `DOMESTICL_PRODUCT_BASE` | quarterly | 亿元 |
+| `cn.m2.yoy` | 中国 M2 同比 | `RPT_ECONOMY_CURRENCY_SUPPLY` | `BASIC_CURRENCY_SAME` | monthly | % |
+| `cn.m1.yoy` | 中国 M1 同比 | `RPT_ECONOMY_CURRENCY_SUPPLY` | `CURRENCY_SAME` | monthly | % |
+
+> ⚠️ **口径陷阱（实测确认，务必照抄）**：在 `RPT_ECONOMY_CURRENCY_SUPPLY` 里
+> `BASIC_CURRENCY`（≈355.5 万亿）才是 **M2**，`CURRENCY`（≈115.5 万亿）是 **M1**，
+> `FREE_CASH`（≈14.8 万亿）是 **M0**。列名与我们的直觉相反——**不要把 `CURRENCY_SAME` 当 M2 同比**
+> （实测两者分别为 7.7 与 4，用错会得出完全不同的结论）。目录里必须显式写 `params.column`，
+> 并有一条断言该值的量级测试（M2 同比历史上落在 0–20% 区间）。
+>
+> `MAKE_SAME` / `NMAKE_SAME` 是「较上月的**变化（百分点）**」而**不是同比**，不要当 yoy 用。
+
+**不存在的 reportName（实测返回 `code:9501 "报表配置不存在"`，不要用）**：
+`RPT_ECONOMY_LPR`、`RPT_ECONOMY_CALENDAR`、`RPT_ECONOMY_TRADE`、`RPT_ECONOMY_SHIBOR`、
+`RPT_ECONOMY_INTEREST_RATE`。
+→ 若确实需要 LPR / 财经日历 / 社融，**在 M4 用一个独立 spike 任务去找真实 reportName 或替代源**，
+找不到就把该指标标记为 `unsupported` 并在目录里注明，**不允许猜接口**。
+
+### 3.3 中国/香港/全球指数（东方财富行情，`adapter: 'eastmoney-quote'`）
+
+| id | 名称 | seriesRef（secid） | 频率 |
+| --- | --- | --- | --- |
+| `cn.idx.sse` | 上证指数 | `1.000001` | daily |
+| `cn.idx.szse` | 深证成指 | `0.399001` | daily |
+| `cn.idx.csi300` | 沪深 300 | `1.000300` | daily |
+| `cn.idx.chinext` | 创业板指 | `0.399006` | daily |
+| `cn.bond.govt.index` | 上证国债指数 | `1.000012` | daily |
+| `cn.bond.corp.index` | 上证企债指数 | `1.000013` | daily |
+| `hk.idx.hsi` | 恒生指数 | `100.HSI` | daily |
+| `us.idx.dji` | 道琼斯工业指数 | `100.DJIA` | daily |
+| `us.idx.spx` | 标普 500 | `100.SPX` | daily |
+| `us.idx.ndx` | 纳斯达克 100 | `100.NDX` | daily |
+| `jp.idx.n225` | 日经 225 | `100.N225` | daily |
+
+`params`: `{ klt: 101, fqt: 1, lmt: 800 }`（101=日线，1=前复权，lmt=取最近 N 根）。
+
+### 3.4 全球（World Bank / ECB / 美国财政部）
+
+| id | 名称 | adapter | seriesRef | 频率 |
+| --- | --- | --- | --- | --- |
+| `wb.gdp.us` | 美国 GDP（现价美元） | `worldbank` | `NY.GDP.MKTP.CD` + country `US` | annual |
+| `wb.gdp.cn` | 中国 GDP（现价美元） | `worldbank` | `NY.GDP.MKTP.CD` + country `CN` | annual |
+| `wb.inflation.cn` | 中国通胀（CPI 同比） | `worldbank` | `FP.CPI.TOTL.ZG` + country `CN` | annual |
+| `wb.unemployment.us` | 美国失业率（ILO 口径） | `worldbank` | `SL.UEM.TOTL.ZS` + country `US` | annual |
+| `ecb.exr.usd` | 欧元/美元 日汇率 | `ecb` | `EXR/D.USD.EUR.SP00.A` | daily |
+| `ust.avg.rate` | 美国国债平均利率 | `us-treasury` | `avg_interest_rates` | monthly |
+
+中国 CPI 的 FRED 镜像 `CHNCPIALLMINMEI` 也可用（OECD 口径，**指数非同比**，需 `yoy` 变换），
+作为 `cn.cpi.yoy` 的**交叉校验源**——两条独立来源同向才算可信，这是可选的加分项。
+
+### 3.5 派生指标（无 source，`display.transform` 或 `derive` 指令）
+
+| id | 名称 | 定义 |
+| --- | --- | --- |
+| `us.real10y` | 美国 10Y 实际利率 | `us.dgs10` − `us.breakeven10y` |
+| `us.curve.10y3m` | 10Y−3M 利差 | `us.dgs10` − `us.dgs3m` |
+| `us.payrolls.3m.avg` | 非农 3 月均值 | `diff` + `window: 3` 的移动平均 |
+| `cn.us.10y.spread` | 中美 10Y 利差 | 需要中国 10Y 收益率源（**待 M4 spike**，暂标 `unsupported`） |
+
+派生指标在目录里用 `derive: { op: 'spread'|'ratio'|'avg', operands: [...] }` 声明，
+由 `core/stats/derive.js` 解析；**派生指标同样要有单测**，尤其是重叠区间不足的情形。
+
+---
+
+## 4. 校验器（`core/types.js`）
+
+每个契约都配一个 `validateXxx(value)` 纯函数，返回 `{ ok, errors[] }`：
+
+- `validateIndicatorDef`：id 格式 `^[a-z0-9]+(\.[a-z0-9]+)+$`、`importance ∈ [1,5]`、
+  `display.transform` 在枚举内、有 `source.adapter/seriesRef`。
+- `validateRawSeries`：`points` 升序、`v` 为有限数、`t` 匹配 `^\d{4}-\d{2}-\d{2}$`、`sourceRef.url` 非空。
+- `validateMetric` / `validateSeriesView`：必填字段存在、`status` 在枚举内。
+
+**这些校验器在 CI 门禁里对「种子目录 + 每个适配器的 fixture 输出」全量跑一遍**
+（见 `08-test-plan.md`），所以新增指标或适配器若不合规会立刻红灯。

package/docs/04-sources.md

@@ -0,0 +1,342 @@
+# 04 · 数据源适配器规格（含实测结果）
+
+**本文所有端点、状态码、耗时、响应形状均为本次会话实测**（Node 24 内置 `fetch`，UA `Mozilla/5.0`）。
+未实测的通路一律标注「未验证」，实现时不得当作事实。
+
+---
+
+## 0. 实测矩阵（2026-09 本次会话）
+
+| 数据源 | 端点 | HTTP | 耗时 | CORS | 结论 |
+| --- | --- | --- | --- | --- | --- |
+| **FRED CSV** | `https://fred.stlouisfed.org/graph/fredgraph.csv?id=<SERIES>&cosd=<YYYY-MM-DD>` | 200 | 0.3–3.0s | 不可用（`null` 或缺失） | ✅ **主干源，无需 API key**；**取数必须在宿主半** |
+| **东方财富 行情** | `https://push2his.eastmoney.com/api/qt/stock/kline/get?...` | 200 | 23–120ms | 回显 Origin | ✅ 股/债指数 |
+| **东方财富 宏观** | `https://datacenter-web.eastmoney.com/api/data/v1/get?reportName=...` | 200 | 90–225ms | `*` | ✅ 中国宏观 |
+| **美国财政部** | `https://api.fiscaldata.treasury.gov/services/api/fiscal_service/...` | 200 | ~2.5s | `*` | ✅ 国债/财政 |
+| **World Bank** | `https://api.worldbank.org/v2/country/<C>/indicator/<I>?format=json` | 200 | ~2.0s | `*` | ✅ 跨国年度 |
+| **ECB SDW** | `https://data-api.ecb.europa.eu/service/data/<FLOW>?format=csvdata` | 200 | ~1.8s | `*` | ✅ 欧元区 |
+| 腾讯行情 | `https://qt.gtimg.cn/q=sh000001,usDJI` | 200 | ~190ms | — | ⚠️ 可用但 **GBK 编码**，需解码；作为实时快照备选 |
+| BLS 公开 API | `https://api.bls.gov/publicAPI/v2/timeseries/data/...` | **403** | 1.5s | — | ❌ 不可用（改用 FRED 镜像） |
+| Yahoo Finance | `https://query1.finance.yahoo.com/v8/finance/chart/...` | **403** | 0.8s | — | ❌ 需要 crumb/cookie，不采用 |
+| Stooq CSV | `https://stooq.com/q/d/l/?s=...` | 200 但返回 JS 墙 | 1.2s | — | ❌ 反爬，不采用 |
+| 新浪行情 | `https://hq.sinajs.cn/list=...` | **403** | 4.5s | — | ❌ 需要特定 Referer，不采用 |
+
+> 上表由 `scripts/probe-sources.mjs` 复现（**现在已经可以跑**：`node scripts/probe-sources.mjs`）；
+> M10 的 `scripts/smoke.mjs` 会复用它做巡检。日后源变更时，更新本文档与脚本的探测清单。
+
+---
+
+## 1. `fred` — FRED CSV（主干源）
+
+**为什么用它**：覆盖美国几乎所有宏观与利率指标，**无需注册 key**，CSV 极简，稳定性好。
+（注：`api.stlouisfed.org` 的 JSON API **需要 API key**，本方案不用它。）
+
+### 请求
+
+```
+GET https://fred.stlouisfed.org/graph/fredgraph.csv?id=PAYEMS&cosd=2024-01-01
+```
+
+参数：
+
+| 参数 | 含义 | 建议 |
+| --- | --- | --- |
+| `id` | 系列 ID，**多个用逗号分隔可一次取多条** | 单指标一次；批量场景可合并 |
+| `cosd` | 起始日期 | **必须传**，否则 `GDPC1` 之类会返回全历史（实测 6.5KB / 1947 起） |
+| `coed` | 结束日期 | 可选，默认到今天 |
+
+### 响应（实测）
+
+```
+observation_date,PAYEMS
+2026-06-01,158892
+2026-07-01,158913
+2026-08-01,159075
+```
+
+- 首行是表头，第一列恒为 `observation_date`。
+- **缺失值写作 `.`**（例如节假日的美债收益率），必须跳过而不是当 0。
+
+### 解析规则
+
+```js
+// 伪代码，实现见 src/sources/fred.js
+const [header, ...rows] = text.trim().split('\n')
+const valueCol = header.split(',')[1]                 // 即 seriesRef
+const points = rows.map(r => r.split(','))
+  .filter(([, v]) => v && v !== '.' && v !== '')
+  .map(([t, v]) => ({ t, v: Number(v) }))
+  .filter(p => Number.isFinite(p.v))
+```
+
+### 溯源 URL
+
+```
+https://fred.stlouisfed.org/series/<SERIES>       // 人类可读页面（图表 + 元数据 + 发布说明）
+apiUrl: https://fred.stlouisfed.org/graph/fredgraph.csv?id=<SERIES>
+```
+
+### 陷阱
+
+1. **频率混合**：日频序列里周末/节假日可能完全没有行（`DGS10` 只含交易日），也可能有 `.`
+   （`DCOILWTICO` 偶有）。不要假设"每天一行"。
+2. **发布滞后**：最新观测日 ≠ 今天。`PAYEMS` 的 8 月值通常在 9 月初发布，`raw.meta` 里不要臆造发布日期。
+3. **数值精度**：`CHNCPIALLMINMEI` 返回 `115.004000000000005` 这类浮点噪声 → 输出前按 `display.decimals` 收敛。
+4. **不要**把 FRED 页面上的"同比 %"当成系列本身——很多系列只有指数，同比必须由我们算（`display.transform: 'yoy'`）。
+
+---
+
+## 2. `eastmoney-quote` — 东方财富行情（股/债指数）
+
+### 请求（实测）
+
+```
+GET https://push2his.eastmoney.com/api/qt/stock/kline/get
+      ?secid=1.000001
+      &fields1=f1,f2,f3
+      &fields2=f51,f52,f53,f54,f55,f56
+      &klt=101&fqt=1&end=20500101&lmt=800
+```
+
+| 参数 | 含义 |
+| --- | --- |
+| `secid` | `<market>.<code>`；`1.`=上交所，`0.`=深交所，`100.`=国际指数 |
+| `klt` | K 线周期：`101`=日，`102`=周，`103`=月 |
+| `fqt` | 复权：`1`=前复权 |
+| `lmt` | 取最近 N 根（避免拉全量） |
+| `end` | `20500101` 表示到最新 |
+
+### 响应（实测）
+
+```json
+{"rc":0,"data":{"code":"000001","market":1,"name":"上证指数",
+  "klines":["2026-09-09,3912.32,3888.11,3934.40,3852.03,579123145", ...]}}
+```
+
+`fields2` 的顺序即 CSV 列顺序，**标准字段号**：
+
+| 字段 | 含义 |
+| --- | --- |
+| `f51` | 日期 `YYYY-MM-DD` |
+| `f52` | 开 |
+| `f53` | **收（我们取这个作为 v）** |
+| `f54` | 高 |
+| `f55` | 低 |
+| `f56` | 成交量 |
+| `f57` | 成交额 |
+| `f58` | 振幅 |
+| `f59` | 涨跌幅 |
+| `f60` | 涨跌额 |
+| `f61` | 换手率 |
+
+### 溯源 URL
+
+```
+https://quote.eastmoney.com/zs000001.html      // 上证指数
+https://quote.eastmoney.com/center/gridlist.html#global_globalindex   // 国际指数
+apiUrl: 上面的 kline 请求
+```
+
+### 陷阱
+
+1. `rc !== 0` 或 `data === null` → 是**业务失败**（secid 错误），归类 `SourceError.kind='unsupported'`，
+   **不要**重试。
+2. 指数 `name` 字段是中文，用于 `meta.name`；`unit` 固定「点」。
+3. `secid` 前缀写错时不会报错，会返回**别的标的**——所以必须有"代码↔名称"断言测试
+   （例如 `1.000001` 必须解析出名称含「上证」），Fixture 里存住名称做回归。
+4. 单次 `lmt` 建议 ≤ 1000，过大响应变慢；`1Y` 范围用 260 根足够，`5Y` 用 1300 根 → 分页或直接 `lmt=1300`。
+
+---
+
+## 3. `eastmoney-macro` — 东方财富数据中心（中国宏观）
+
+### 请求（实测）
+
+```
+GET https://datacenter-web.eastmoney.com/api/data/v1/get
+      ?reportName=RPT_ECONOMY_CPI
+      &columns=ALL
+      &pageSize=60
+      &sortColumns=REPORT_DATE
+      &sortTypes=-1
+```
+
+### 响应（实测，节选）
+
+```json
+{"version":"…","result":{"pages":45,"data":[
+  {"REPORT_DATE":"2026-08-01 00:00:00","TIME":"2026年08月份","NATIONAL…":"…"}]},
+ "success":true}
+```
+
+**已确认存在**的 reportName：`RPT_ECONOMY_CPI`、`RPT_ECONOMY_PPI`、`RPT_ECONOMY_PMI`、
+`RPT_ECONOMY_GDP`、`RPT_ECONOMY_CURRENCY_SUPPLY`。
+
+**已确认不存在**（返回 `{"success":false,"code":9501,"message":"报表配置不存在,…"}`）：
+`RPT_ECONOMY_LPR`、`RPT_ECONOMY_CALENDAR`、`RPT_ECONOMY_TRADE`、`RPT_ECONOMY_SHIBOR`、
+`RPT_ECONOMY_INTEREST_RATE`。
+
+### 已知字段（实测可见）
+
+| 报表 | 字段 | 含义 |
+| --- | --- | --- |
+| CPI | `REPORT_DATE`, `TIME` | 报告期 与「2026年08月份」文本 |
+| CPI | `NATIONAL_SAME` | **同比** → `cn.cpi.yoy` 取这一列 |
+| CPI | `NATIONAL_SEQUENTIAL` | **环比** → `cn.cpi.mom` 取这一列 |
+| CPI | `NATIONAL_BASE` | 指数（定基） |
+| CPI | `NATIONAL_ACCUMULATE` | 累计同比 |
+| PPI | `BASE: 103.8` / `BASE_SAME: 3.8` / `BASE_ACCUMULATE: 102` | 指数 / **同比** / 累计 |
+| PMI | `MAKE_INDEX: 49.8` / `MAKE_SAME: 0.81` | 制造业 PMI / **较上月变化（pp，不是同比）** |
+| PMI | `NMAKE_INDEX: 49.0` / `NMAKE_SAME: -2.58` | 非制造业 PMI / 同上 |
+| GDP | `DOMESTICL_PRODUCT_BASE: 695704` | 现价累计总量（**亿元**；注意上游拼写 `DOMESTICL`） |
+| GDP | `SUM_SAME: 4.7` | **GDP 同比** → `cn.gdp.yoy` 取这一列 |
+| GDP | `FIRST/SECOND/THIRD_PRODUCT_BASE`、`FIRST/SECOND/THIRD_SAME` | 分产业总量与同比 |
+| 货币供应 | `BASIC_CURRENCY: 3555077.24` / `BASIC_CURRENCY_SAME: 7.7` | **这是 M2**（余额/同比） |
+| 货币供应 | `CURRENCY: 1154623` / `CURRENCY_SAME: 4` | **这是 M1** |
+| 货币供应 | `FREE_CASH: 148202.86` / `FREE_CASH_SAME: 11.6` | **这是 M0** |
+| 货币供应 | `*_SEQUENTIAL` | 环比（%） |
+
+> 全表由 `scripts/probe-sources.mjs` + 直接枚举 keys 实测得到（2026-09）。
+> ⚠️ **`BASIC_CURRENCY` = M2、`CURRENCY` = M1**，与直觉相反；而且 `MAKE_SAME`/`NMAKE_SAME`
+> 是"较上月变化（pp）"而**不是同比**。这两点必须有测试覆盖，否则会产出看似合理但完全错误的结论。
+
+### 适配器的额外职责
+
+`params.column` 指定取哪一列作为 `v`。因此**同一个 reportName 可以产出多个指标**
+（`cn.cpi.yoy` 与 `cn.cpi.mom` 共用 `RPT_ECONOMY_CPI`，只是列不同）。
+
+### 溯源 URL
+
+```
+https://data.eastmoney.com/cjsj/cpi.html      // CPI
+https://data.eastmoney.com/cjsj/ppi.html      // PPI
+https://data.eastmoney.com/cjsj/pmi.html      // PMI
+https://data.eastmoney.com/cjsj/gdp.html      // GDP
+apiUrl: 上面的 datacenter 请求
+```
+
+### 陷阱
+
+1. `REPORT_DATE` 是 `"2026-08-01 00:00:00"` 形式 → 归一化时**只取日期部分**。
+2. **数据是倒序**（`sortTypes=-1`）；适配器必须按时间升序输出，否则统计全错。
+3. 上游列名存在拼写问题（`DOMESTICL_PRODUCT_BASE`），**照抄不要"纠正"**。
+4. `success:false` 时 HTTP 仍是 200 → 必须检查 body。这是本适配器最容易漏的测试点。
+5. 该站点接口**非官方承诺**，字段可能变更 → 必须有 `parse` 层的**显式字段存在性断言**，
+   缺字段时抛 `SourceError.kind='parse'`，而不是静默产出 `undefined`。
+
+---
+
+## 4. `us-treasury` — 美国财政部 fiscaldata
+
+### 请求（实测）
+
+```
+GET https://api.fiscaldata.treasury.gov/services/api/fiscal_service/v2/accounting/od/avg_interest_rates
+      ?page[size]=100&sort=-record_date
+```
+
+### 响应（实测）
+
+```json
+{"data":[{"record_date":"2001-01-31","security_type_desc":"Marketable",
+          "security_desc":"Treasury Notes","avg_interest_rate_amt":"6.096", …}]}
+```
+
+### 陷阱
+
+1. 数值是**字符串**，且可能为空串 → 必须 `Number()` 后过滤 `NaN`。
+2. 数据集按 `security_desc` 分行（Notes / Bonds / Bills…）→ `params.filter` 支撑
+   `filter=security_desc:eq:Treasury Notes`；不写 filter 会混入多种证券类型。
+3. 分页是 `page[size]` / `page[number]`，`meta.total-pages` 可用。
+
+### 溯源 URL
+
+```
+https://fiscaldata.treasury.gov/datasets/average-interest-rates-treasury-securities/
+```
+
+---
+
+## 5. `worldbank` — 世界银行
+
+### 请求（实测）
+
+```
+GET https://api.worldbank.org/v2/country/US;CN/indicator/NY.GDP.MKTP.CD?format=json&per_page=100
+```
+
+### 响应（实测）
+
+```json
+[{"page":1,"pages":27,"per_page":100,"total":132,"lastupdated":"2026-07-13"},
+ [{"indicator":{"id":"NY.GDP.MKTP.CD","value":"GDP (current US$)"},
+   "country":{"id":"US","value":"United States"},
+   "date":"2025","value":30000000000000}, …]]
+```
+
+### 陷阱
+
+1. 顶层是**二元数组**：`[meta, rows]`；无数据时 `rows` 为 `null`（不是空数组）→ 必须处理。
+2. `date` 只有年份 → 归一化为 `<YYYY>-12-31`（年末），并在 `meta.freq='annual'` 标注；
+   不要虚构 `-01-01`，与"年度值"的口径不符。
+3. `value` 可能是 `null`（该国该年无数据）→ 跳过。
+4. **年度数据发布滞后 1–2 年**，卡片必须允许"最后观测日"远早于今天，不能一律判为 stale 报错
+   （规则：按 freq 计算陈旧阈值，annual 的阈值是 400 天）。
+
+---
+
+## 6. `ecb` — 欧洲央行 SDW
+
+### 请求（实测）
+
+```
+GET https://data-api.ecb.europa.eu/service/data/EXR/D.USD.EUR.SP00.A?format=csvdata&lastNObservations=30
+```
+
+### 响应（实测）
+
+CSV，首行是长表头：`KEY,FREQ,CURRENCY,CURRENCY_DENOM,EXR_TYPE,EXR_SUFFIX,TIME_PERIOD,OBS_VALUE,…`
+
+- 取 `TIME_PERIOD`（`YYYY-MM-DD`）与 `OBS_VALUE`（数值）。
+- `lastNObservations` 是必须用的参数，否则拉全历史。
+
+### 溯源 URL
+
+```
+https://data.ecb.europa.eu/data/datasets/EXR
+```
+
+---
+
+## 7. 适配器契约测试（所有适配器共用）
+
+`test/contract/source-adapter.test.js` 遍历 `src/sources/registry.js` 的注册表，对**每个**适配器断言：
+
+1. 导出齐全：`id`（小写 kebab）、`label`、`capabilities`、`fetchSeries`、`sourceRef`。
+2. `fetchSeries` 对同一 fixture **可重复调用且结果一致**（纯函数性）。
+3. 输出满足 `validateRawSeries`（升序、有限数、日期格式、`sourceRef.url` 可达格式）。
+4. 缺失值处理：fixture 里含 `.` / `null` / `""` 时，产出中**没有**这些点。
+5. 错误分类：
+   - fixture 为 HTML 错误页 → `kind='parse'` 或 `'http'`；
+   - fixture 为 `success:false` → `kind='unsupported'`（不重试）；
+   - fixture 为空 → `kind='empty'`。
+6. `sourceRef(seriesRef).url` 对目录里每个用到该适配器的指标都非空，且是 `https://`。
+7. **不泄漏上游私有字段**：返回值里除 `raw` 外不得出现上游原始键名。
+
+只要满足契约，新适配器**零改动**即可接入（见 `02` 文档 §5.2）。
+
+---
+
+## 8. 取数策略与降级
+
+| 策略 | 做法 | 必须的单测 |
+| --- | --- | --- |
+| 超时 | 每个请求 15s（`AbortController`），在用例层注入 `signal` | 超时 → `kind='network'`, `retryable=true` |
+| 重试 | 仅 `network`/`http(5xx)` 重试 1 次，退避 500ms；`parse`/`unsupported` 不重试 | 重试次数断言（用假 fetch 计数） |
+| 并发 | 同一 `key` 的 in-flight 请求合并 | 并发 5 次调用 → 上游只被调 1 次 |
+| 缓存 | TTL 按频率（日 15min / 月 6h / 季 24h） | 过期前不重取、过期后重取 |
+| 降级 | 失败返回上次快照 + `status='stale'` | 无快照 → `status='error'`；有快照 → `stale` 且数值等于快照 |
+| 批量 | `overview` 用 `Promise.allSettled`，单项失败不影响其他 | 5 项里 2 项失败 → 返回 5 项，其中 2 项带状态 |
+
+**免责声明**：面板与 AI 输出必须带一行固定文案——「数据来自公开源，仅供研究参考，不构成投资建议；
+口径以原始来源为准」。这句话是 UI 常量，不进 AI 提示词由模型自由发挥。